READPREV

Read previous record during a file browse; VSAM and data tables only.

READPREV

Conditions: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOCKED, NOTAUTH, NOTFND, RECORDBUSY, SYSIDERR

This command is threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over an IPIC connection to a remote CICS® region.
Defined as either local VSAM or RLS.

This command is not threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over a non-IPIC connection.
Defined as a shared data table, coupling facility data table, or BDAM file.

Description

READPREV can be used repeatedly to read records in reverse sequential order from a VSAM file on a local or a remote system.

Such a series of sequential read commands is known as a browse of the file. A browse can also consist of a sequence of READNEXT and READPREV commands in any order. A browse must be initiated with the STARTBR command, to identify the start of the browse, and terminated with the ENDBR command.

You must provide, in the RIDFLD option, a data area that is sufficiently large to contain a complete identifier (full key, RBA, or RRN) of records in the file. This data area is used both as an output and as an input parameter.

It is used as an output parameter when CICS, on completion of each READPREV command, places the complete identifier of the record just retrieved into the RIDFLD data area. CICS then holds this identifier to mark the point from which the subsequent READPREV is to continue.

It may also be used as an input parameter. Modifying the RIDFLD before issuing the next READPREV command causes that command to reposition the browse to the new identifier, from which it continues in the usual way. The modified record identifier must always be a full key, RBA, or RRN. A generic key may not be specified, nor may a browse that was started with the GENERIC option include a READPREV command.

If you include a READPREV command 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.

A READPREV command following a READNEXT, or a STARTBR or RESETBR that did not specify a 'last' key value, is treated as though the RIDFLD value had been modified and results in a reposition (as above).

Reading files accessed in RLS mode

For files accessed in RLS mode, you can include the UPDATE keyword on the READPREV request to update some records during the browse. If you specify UPDATE you must also specify TOKEN. You can then update the record by issuing a DELETE or REWRITE command that specifies the TOKEN returned on the browse function.

Note: TOKEN without the UPDATE keyword implies UPDATE.

Use of the UPDATE option is subject to the following rules:

You can specify UPDATE on a READPREV command only if the file is accessed in RLS mode. If you specify UPDATE for a file accessed in non-RLS mode, CICS returns INVREQ.
You can specify UPDATE on READPREV, but not on the STARTBR or RESETBR commands.
You can intermix UPDATE and non-update requests within the same browse.
CICS does not preserve the UPDATE option for you from one READPREV command to the next.
CICS supports only one TOKEN in a browse sequence, and the TOKEN value on each READPREV invalidates the previous value.

Locks for UPDATE

Specifying UPDATE on a READPREV command acquires an exclusive lock. The duration of these exclusive locks within a browse depends on the action your application program takes:

If you decide to DELETE or REWRITE the last record acquired by a READPREV UPDATE in a browse, using the associated token, the lock remains active as follows:
- If the file is recoverable, the lock is released at completion of the next sync point or rollback.
- If the file is non-recoverable, the lock will be released by the time ENDBR has completed, but might be released earlier.
If you decide not to update the last record read, CICS frees the exclusive lock when your program either issues another READNEXT or READPREV command, or ends the browse.

Important: The UNLOCK command does not free an exclusive lock held by VSAM against a record acquired by READPREV UPDATE. An UNLOCK in a browse invalidates the TOKEN returned by the last request.

Locks for read integrity

Specifying one of the read integrity options acquires a shared lock on each READPREV. The duration of these shared locks with a browse depends on the type of read integrity you specify:

If you specify CONSISTENT read integrity, the shared lock is held only for the duration of each read request—that is, until the record is returned to your program.
If you specify REPEATABLE read integrity, the shared lock is held for the duration of the unit of work in which the browse is performed. In this case, your program could acquire a large number of shared locks, which will prevent the granting of exclusive locks for update functions. You should use REPEATABLE read integrity in a browse with caution.

Function shipping READPREV with UPDATE or read integrity

If a READPREV command that specifies UPDATE or one of the read integrity options is function-shipped to a member of the CICS family of products that does not support UPDATE or the read integrity options, the request fails:

If an ISC link is used, the request receives an ATNI abend.
If an MRO link is used, the request receives an AXF8 abend.
AXF8 is an abend code, received by the sending side of a function-shipped request. It indicates that an attempt has been made to send a request that specifies UPDATE on an MRO link to a CICS region that does not support update or read integrity options.

Read integrity

When a file is accessed in RLS mode, non-update read requests can specify read integrity options: UNCOMMITTED, CONSISTENT, or REPEATABLE.

If you do not specify any of these keywords, CICS uses the value specified on the READINTEG parameter of the FILE resource definition, for which the default is UNCOMMITTED.

If you want to use the level of read integrity specified in the READINTEG keyword of the FILE definition, and then you need to change from using a local file to a remote file, or if you change the location of a remote file, ensure that:

The remote file-owning region is at the CICS Transaction Server for OS/390®, Version 1 Release 1 (or later) level.
The FILE definition in the remote system specifies:
- RLS mode
- The correct read integrity values for your application.

Retained and active locks

RECORDBUSY refers to active locks and LOCKED refers to retained locks.

These locks affect READPREV requests which acquire locks; that is, update requests and requests with read integrity. These are the kinds of READPREV requests which are referred to in the following bullets. Other READPREV requests are unaffected by the presence of retained or active locks.

READPREV requests for records that have retained locks are always rejected with a LOCKED response.
READPREV requests for records that have active locks wait for the lock to be released, except when the NOSUSPEND keyword is specified, in which case CICS returns the RECORDBUSY response.

Options

CONSISTENT (RLS only)

The record is read with a level of read integrity provided by a VSAM shared lock that lasts for the duration of the request.

If the record is being modified by another task, which therefore holds an exclusive lock, the READPREV request waits until the update is complete (unless NOSUSPEND is also specified) as follows:

For a READPREV request against a non-recoverable file, the READPREV completes as soon as any VSAM request performing the update completes.
For a READPREV request against a recoverable file, the READPREV request completes when the updating task completes its next syncpoint or rollback.

FILE(filename)

specifies the name of the file being browsed.

If SYSID is specified, the data set to which this file refers is assumed to be on a remote system irrespective of whether the name is defined in the file resource definition. Otherwise, the file definition is used to find out whether the data set is on a local or a remote system.

INTO(data-area)

specifies the data area into which the record retrieved from the data set is to be written.

KEYLENGTH(data-value)

specifies the length (halfword binary) of the key that has been specified in the RIDFLD option, except when RBA or RRN is specified, in which case KEYLENGTH is not valid. If the length specified is different from the length defined for the data set, the INVREQ condition occurs.

For remote files, the KEYLENGTH can be specified in the FILE definition. If KEYLENGTH is not defined there, and is not specified in the application program, and the key is longer than 4 characters, the default value is 4.

LENGTH(data-area)

specifies the length, as a halfword binary value, of the data area where the record is to be put. On completion of the READNEXT command, the LENGTH parameter contains the actual length of the record.

This option must be specified if SYSID is specified.

If the file is on a remote system, the LENGTH parameter need not be set here 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, using the INTO option, but not for fixed-length records. It is, however, advisable to specify the length for fixed-length records because:

It causes a check to be made that the record being read is not too long for the available data area.
When browsing fixed-length records into an area longer than the record being accessed, the LENGERR condition is raised for COBOL, C, PL/I, and assembler-language applications if the LENGTH option is specified. If the LENGTH option is not explicitly specified, then the LENGERR condition is returned if the length can be inferred from the data area. If the length specified exceeds the file record length, CICS uses the longer length for the move. If the target area in the application program is not large enough, storage is overlaid beyond the target area.

If you specify the SET option, you need not also specify the LENGTH option.

When browsing into a target data area longer than the record being read, the contents of the target data area, from the end of the retrieved record to the end of the target data area, are unpredictable.

If you 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. In this case, the LENGTH data area is set to the length of the record before truncation.

Note that a file control command issued against a variable-length record in a file defined on the local CICS system fails with a LENGERR condition if a length is not specified. However, if the same command is issued against a file defined on a remote system, the command does not fail.

NOSUSPEND (RLS only)

The request does not wait if the record is locked by VSAM with an active lock, including records locked as the result of a DEADLOCK.

Note: Requests that specify NOSUSPEND wait for at least 1 second before CICS returns the RECORDBUSY response.

RBA

(VSAM KSDS or ESDS base data sets, or CICS-maintained data tables only, but not paths) specifies that the record identification field specified in the RIDFLD option contains a relative byte address.

This option must be specified when the STARTBR or RESETBR command specified the RBA option. It must not be specified when the STARTBR or RESETBR command did not specify RBA.

You cannot use RBA for:

User-maintained data tables
Coupling facility data tables
Any KSDS file opened in RLS access mode
KSDS files that use extended addressing.

Also, you are recommended not to use RBA for ESDS files that hold more than 4GB. (Use XRBA instead.)

REPEATABLE (RLS only)

The record is read with a level of read integrity provided by a VSAM shared lock that lasts for the duration of the unit of work in which the read request is issued.

If the record is being modified by another task, which therefore holds an exclusive lock, the READPREV request waits until the update is complete (unless NOSUSPEND is also specified) as follows:

For a recoverable file, the READPREV request completes when the updating transaction completes its next sync point or rollback.
For a non-recoverable file, the READPREV completes as soon as the VSAM request performing the update completes.

After the READPREV request has completed, the record remains locked to the task that issued the READPREV. Other tasks can continue to read the record, but no other task is allowed to update the record until the task that issued the READPREV performs its next sync point or rollback.

REQID(data-value)

specifies as a halfword binary value a unique request identifier for a browse, used to control multiple browse operations on a file. If this option is not specified, a default value of zero is assumed.

RIDFLD(data-area)

specifies the record identification field. The contents can be a key, a relative byte address, or relative record number. For a relative byte address or a relative record number, the format of this field must be fullword binary. For a relative byte address, the RIDFLD value can be greater than or equal to zero. For a relative record number, the RIDFLD value can be greater than or equal to 1.

On completion of the READPREV command, this field is updated by CICS with the complete identification of the record retrieved.

RRN

(VSAM RRDS) specifies that the record identification field specified in the RIDFLD option contains a relative record number.

SET(ptr-ref)

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

In assembler language, if the DUPKEY condition occurs, the register specified will not have been set, but can be loaded from DFHEITP1.

The pointer reference is valid until the next READPREV or READNEXT command that specifies SET for the same browse (REQID) for the same file. The pointer is no longer valid after an ENDBR or SYNCPOINT command. If you want to retain the data within the field addressed by the pointer, you must move it to your own area.

If DATALOCATION(ANY) is associated with the application program, the address returned in the SET pointer can be above or below the 16 MB line.

If DATALOCATION(BELOW) is associated with the application program, the address returned in the SET pointer is below the 16 MB line.

If TASKDATAKEY(USER) is specified for the running task, the data returned is in user-key storage; otherwise it is in CICS-key storage.

SYSID(systemname)

specifies the name of the system to which the request is directed.

If you specify SYSID, and omit both RBA and RRN, you must also specify LENGTH and KEYLENGTH.

TOKEN(data-area) (RLS only)

Returns, as a fullword binary value, a unique identifier for this READPREV UPDATE request. This is an output value returned by file control to the requesting task, for use in associating a subsequent REWRITE or DELETE (or UNLOCK) request with the record returned on this READPREV command.

Your application program must specify the returned TOKEN on a subsequent REWRITE or DELETE command to identify the record being rewritten or deleted. Your application program can also specify the returned TOKEN on a subsequent UNLOCK command to identify the token that is being invalidated.

You must specify TOKEN if you specify UPDATE (but UPDATE is assumed if you specify TOKEN without UPDATE).

CICS supports only one active TOKEN at a time for a given REQID. Thus, a TOKEN value remains valid only until the following READNEXT, READPREV, or ENDBR command for this browse, or until a REWRITE, DELETE, or UNLOCK command (whichever is first).

TOKEN can be function shipped. However, if a request specifying TOKEN is function shipped to a member of the CICS family of products that does not recognize this keyword, the request fails.

UNCOMMITTED

The record is read without read integrity. The current data, as known to VSAM, is returned. No attempt is made to serialize this read request with any concurrent update activity for the same record. The record may be being updated by another transaction, therefore the value of the record may change later if that update is subsequently backed out.

UPDATE (RLS only)

Specifies that the record is to be obtained for updating or deletion. If this option and TOKEN are both omitted, read only is assumed.

If you specify UPDATE, you must also specify TOKEN.

UPDATE is only valid for files defined to the local region

XRBA

specifies that the record identification field specified in the RIDFLD option contains an extended relative byte address. This option should be used when browsing records in an ESDS extended addressing data set.

You cannot specify XRBA on a READPREV command unless the associated STARTBR or RESETBR command also specified XRBA.

KSDS data sets cannot be accessed by XRBA.

Conditions

15 DUPKEY

RESP2 values:

140: A record is retrieved by way of an alternate index with the NONUNIQUEKEY attribute, and another alternate index record with the same key exists.
In assembler language, if the SET option is being used, the specified register has not been set, but can be loaded from DFHEITP1.

Default action: terminate the task abnormally.

20 ENDFILE

RESP2 values:

90: An end-of-file condition is detected during a browse.

Default action: terminate the task abnormally.

12 FILENOTFOUND

RESP2 values:

1: A file name referred to in the FILE option is not defined to CICS.

Default action: terminate the task abnormally.

21 ILLOGIC

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

RESP2 values (VSAM):

110: A VSAM error occurs that is not in one of the other CICS response categories.
See EIBRCODE in the EXEC interface block; for details, see EIB fields.

Default action: terminate the task abnormally.

16 INVREQ

RESP2 values:

20: The FILE definition does not allow updates.
24: A READPREV command is issued for a file for which the previous STARTBR or RESETBR command has the GENERIC option.
26: The KEYLENGTH option is specified and the specified length does not equal the length defined for the data set for this file refers to.
37: The type of record identification (for example, key or relative byte address) used to access a data set during the browse has been changed. You cannot specify one type of addressing on STARTBR and another on READPREV.
39: A READPREV is issued for a BDAM file.
41: The REQID, SYSID, or file name does not match that of any successful STARTBR command.
52: CONSISTENT is not allowed because the file is not a VSAM file that is accessed in RLS mode.
53: REPEATABLE is not allowed because the file is not a VSAM file that is accessed in RLS mode.
54: UPDATE is not allowed because the file is not a VSAM file that is accessed in RLS mode.
55: NOSUSPEND is not allowed because the file is not a VSAM file that is accessed in RLS mode.
57: An attempt to update the file has failed because the associated VSAM data set has an AVAILABILITY state of RREPL, which disallows update operations except those from replication programs.

Default action: terminate the task abnormally.

17 IOERR

RESP2 values:

120

An I/O error occurred during the browse. An I/O error is any unusual event that is not covered by a CICS condition.

For VSAM files, IOERR usually indicates a hardware error. Further information is available in the EXEC interface block; for details, see EIB fields.

For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.

Default action: terminate the task abnormally.

54 ISCINVREQ

RESP2 values:

70: The remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

10: Neither the LENGTH nor the SET option is specified for a file with variable-length records.
11: The length of the record read with the INTO option specified exceeds the value specified in the LENGTH option; the record is truncated, and the data area supplied in the LENGTH option is set to the actual length of the record.
13: An incorrect length is specified for a file with fixed-length records.

Default action: terminate the task abnormally.

100 LOCKED

RESP2 values:

106

The read request specifies the UPDATE keyword, or one of the read integrity keywords CONSISTENT or REPEATABLE, or the file resource definition specifies read integrity, but VSAM holds a retained lock against the record (see Retained and active locks).

The key of the locked record is not returned to your application program. If you handle this condition and control is returned to your program, the browse can continue and retrieve the record following the locked record by issuing another READPREV request.

The LOCKED condition also can occur for a request to a recoverable CFDT that uses the locking model, if the record that is being read is locked by a retained lock. See Coupling facility data table retained locks for information about investigating retained locks on records in a coupling facility data table.

Default action: abend the task with code AEX8.

70 NOTAUTH

RESP2 values:

101: A resource security check has failed on FILE(filename).

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

80: An attempt to retrieve a record based on the search argument provided is unsuccessful. One place where this may occur is where the READPREV command immediately follows a STARTBR or RESETBR command that specified GTEQ and the key of a record that does not exist on the data set.
81: XRBA was specified, and the value of RIDFLD was greater than 4 GB, but the data set is not an extended addressing ESDS.

Default action: terminate the task abnormally.

101 RECORDBUSY

RESP2 values:

107: NOSUSPEND is specified on the request but VSAM holds an active lock against the record, which would cause the request to wait (see Retained and active locks).
The key of the locked record is not returned to your application program. If you handle this condition and control is returned to your program, the browse can continue and retrieve the record following the locked record by issuing another READPREV request.

Default action: abend the task with code AEX9.

53 SYSIDERR

RESP2 values:

130: The SYSID option specifies a name that is neither the local system nor a remote system that is defined by a CONNECTION or IPCONN definition. SYSIDERR also occurs when the link to the remote system is known but unavailable. In the case of an IPCONN, SYSIDERR occurs if the link is known but either the local or remote systems do not support file control commands that are function shipped using IP interconnectivity.
131: For a coupling facility data table, the connection to the coupling facility data table server has failed. This could be because the server itself has failed, or the server is available, but CICS has failed to connect to it.
132: The READPREV is issued against a coupling facility data table that no longer exists, probably because of a coupling facility failure, in which case the coupling facility data table server also fails. See Setting up and running a coupling facility data table server for information about restarting a coupling facility data table server and reloading a table.

Default action: terminate the task abnormally.