CICS FILE READPREV

CICS File Readnext CICS File ENDBR


Advertisements


Read previous record during a file browse

REDPREV is applicable for VSAM and data tables only.


Syntax:

EXEC CICS 
     READPREV FILE(filename) INTO(data-area)
              SET(ptr-ref)
              RIDFLD(data-area)
              UPDATE TOKEN(data-area) 
              KEYLENGTH(data-value)
              REQID(data-value)
              SYSID(system-name)  
              LENGTH(data-area)
              RBA/RRN NOSUSPEND            
END-EXEC. 

READPREV command is safe when

  • Defined as remote and the function shipped over an IPIC connection to a remote CICS region.
  • Defined as either local VSAM.

READPREV can be used repeatedly to read records in reverse sequential order.

The VSAM file can be on a local or a remote system.

A browse can have sequence of READNEXT and READPREV commands in any order.

The data area in RIDFLD is used both as an output and as an input parameter.

CICS holds the RIDFLD identifier to mark the point from where the subsequent READPREV is to continue.

RIDFLD may also be used as an input parameter.

Modifying RIDFLD before issuing the next READPREV command causes the reposition of the browse based on the new identifier.

The modified record identifier must always be a full key, RBA, or RRN.

If READPREV command issued immediately following a STARTBR command, your STARTBR command RIDFLD must specify the key of a record that exists on the data set; otherwise the NOTFND condition will occur.

Issuing UPDATE on a READPREV command acquires an exclusive lock.

The remains until:

  • If the file is recoverable, the lock is released at completion of the next syncpoint or rollback.
  • If the file is non-recoverable, the lock will be released by the time ENDBR has completed.
  • Lock will be releases if the program either issues another READNEXT or READPREV command, or ends the browse.

FILE (filename)

Specifies the name of the file.

If SYSID is specified, the file is from the remote region.

If the SYSID not specified, the resource definition is used to find out whether the data set is on a local or a remote system.


UNCOMMITTED

The record is read without read integrity.

No attempt is made to serialize this read request with any concurrent update activity for the same record.


UPDATE

Specifies that the record is to be obtained for updating.

For VSAM and data tables deletion.

If this option is omitted, a read-only operation is assumed.

UPDATE promises read integrity.

If another task has issued a READ REPEATABLE request against the same record, READ UPDATE request is made to wait until that task reaches SYNCPOINT (unless issued NOSUSPEND).


TOKEN (data-area)

Specifies the unique identifier for this READ request.

The data area length is a full word binary value.

TOKEN is an optional field.


INTO (data-area)

Specifies the data area that needs to be written with the record after the READ successful.

The INTO is specified, the LENGTH is not mandatory.

But the INTO data area should be capable of placing the default record length.


RIDFLD (data-area)

Specifies the record identification field.

Contains the key value used to identify the record to delete.

Contents can be a key value, RBA, RRN.

For RRN, the format of the field is full word binary.

For RBA, the RIDFLD can be greater than or equal to zero.

For RRN, the RIDFLD can be greater than or equal to 1.

RIDFLD is mandatory if GENERIC option specified.


SET (ptr-ref)

specifies the pointer reference that is to contain the address of the retrieved record.

The pointer reference is valid until the next READ command for the same file or until completion of a corresponding REWRITE, DELETE, or UNLOCK, or a SYNCPOINT.

If DATALOCATION (ANY) is associated with the application program, the address of the data can be above or below the 16 MB line.

If DATALOCATION (BELOW) is associated with the application program, the address of the data is below the 16 MB line.


KEYLENGTH (data-value)

Specifies the length of the key specified in the RIDFLD option.

The length field definition is of length half word binary.

KEYLENGTH is not applicable for RBA or RRN specified.

KEYLENGTH option is mandatory if GENERIC is specified.

If the length value specified is different from the length defined for the data set without GENERIC, the INVREQ condition occurs.

If the KEYLENGTH is not less than the length specified in the VSAM definition with GENERIC option, The INVREQ condition occurs.

If zero value specified for KEYLENGTH, the results are unpredictable.

If KEYLENGTH (0) is used with the reading the first record in the data set and the GTEQ option must also be specified.

If EQUAL is specified either explicitly or by default with KEYLENGTH (0), the results of the READ are unpredictable.


REQID(data-value)

specifies as a half word binary value.

REQID is a unique request identifier for a single browse.

REQID used to control multiple browse operations on a file.

If this option is not specified, a default value of zero is assumed by the system.


SYSID (system-name)

Specifies the name of the remote system/local system.

System-name declaration length is 1-4 characters.

If SYSID specified, RBA and RRN can be omitted.


LENGTH (data-area-length)

Specifies the length of data area after the record retrieved successfully.

Data-area-length in declaration is a half word binary value.

Once the READ command completed, the LENGTH parameter contains the actual length of the record.

LENGTH must be specified if SYSID is specified.

If the file is on a remote system, the LENGTH parameter need not be set in application program but must be set in the file resource definition.

If the file is on a local system, the LENGTH parameter must be set for variable-length records.

If SET option is specified, it’s not needed to specify the LENGTH option.

If specify the INTO option, the LENGTH argument must be a data area that specifies the largest record the program accepts.

If the retrieved record is longer than the value specified in the LENGTH option, the record is truncated to the specified value and the LENGERR condition occurs.


RBA

Specifies RIDFLD contains a relative byte address.

For VSAM KSDS base data sets.

This option used only when deleting records using RBA instead of keys to identify the records.


RRN

Option is for VSAM RRDS only

Specifies that the RIDFLD contains a relative record number.

This option can be used only with files referencing relative record data sets.


EQUAL

Specifies that the search is satisfied only for the record which has the same key which is provided in RIDFLD.

The data provided in RIDFLD may be a full key or partial key.


GTEQ

GTEQ is valid for VSAM KSDS.

Specifies CICS to retrieve the next available record if the equal key record not found which is specified in RIDFLD.

If match not found, READ will retrieve next record which is greater than to key.


NOSUSPEND (RLS only)

Specifies that the request is not to wait if VSAM is holding by another task.

NOSUSPEND wait for at least 1 second before CICS returns the RECORDBUSY response.


Frequent ERROR Conditions:


12 FILENOTFOUND

RESP2 values:
1

A file name used in the FILE option is not defined to CICS.

Task will be terminated abnormally.


13 NOTFND

RESP2 values:
80

An attempt to retrieve a record based on the search argument provided is unsuccessful.

Task will be terminated abnormally.


15 DUPKEY

RESP2 values (VSAM):
140

A record is retrieved of an alternate index with the NONUNIQUEKEY and another alternate index record with the same key follows.

Task will be terminated abnormally.


16 INVREQ

RESP2 values:
20

READ is not allowed according to the resource definition.

A READ command with the UPDATE option is issued to a file where update operations are not allowed.

25

Error occurs, if the KEYLENGTH is not less than the length specified in the VSAM definition with GENERIC option

26

Error occurs, if the length value specified is different from the length defined for the data set without GENERIC.

42

The KEYLENGTH and GENERIC options are specified and the length specified in the KEYLENGTH option is less than zero.

44

The command does not conform to the format of READ for a user-maintained or coupling facility data table; for example, if RBA is specified.

Task will be terminated abnormally.


16 INVREQ

RESP2 values:
20

The FILE does not allow updates because of updates.

25

The value of KEYLENGTH was greater than the full key length.

26

The specified KEYLENGTH does not equal the length defined for the data set to which this file refers.

34

The REQID/SYSID/file name does not match that of any successful STARTBR command.

42

The value of KEYLENGTH was less than zero.

54

UPDATE is not allowed because the file is not a VSAM file that is accessed in RLS mode.

Task will be terminated abnormally.


17 IOERR

RESP2 values:
120

There is an I/O error during the READPREV command.

For VSAM files, IOERR usually indicates a hardware error.

Task will be terminated abnormally.


20 ENDFILE

RESP2 values:
90

An end-of-file condition is detected during the browse.

Task will be terminated abnormally.


21 ILLOGIC

The browse that is currently in progress is terminated when this condition is raised.

Task will be terminated abnormally.


22 LENGERR

RESP2 values:
11

The length of the record read with the INTO option specified exceeds the value specified in the LENGTH option.

13

An incorrect length is specified for a file with fixed-length records.

Task will be terminated abnormally.


53 SYSIDERR

RESP2 values:
130

The SYSID option name that is neither the local system nor a remote system.

Task will be terminated abnormally.


70 NOTAUTH

RESP2 values:
101

A resource have no authority and has failed on FILE(filename).

Task will be terminated abnormally


100 LOCKED

RESP2 values:
106

An attempt is being made to read a record specifying the UPDATE keyword, but the record is locked by a retained lock.

The LOCKED condition can also occur for a READ UPDATE request to a recoverable CFDT that uses the locking model, if the record being read is locked by a retained lock.

Task will be terminated abnormally with code AEX8.


CICS File Readnext CICS File ENDBR

Advertisements