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

READPREV
>>-READPREV--FILE(filename)--+-INTO(data-area)-+---------------->
'-SET(ptr-ref)----'
>--+--------------------------+--RIDFLD(data-area)-------------->
+-UNCOMMITTED--------------+
+-CONSISTENT---------------+
+-REPEATABLE---------------+
'-UPDATE--TOKEN(data-area)-'
>--+-------------------+---------------------------------------->
'-REQID(data-value)-'
>--+--------------------------------------+--+-----+------------>
+-SYSID(systemname)--LENGTH(data-area)-+ +-RBA-+
'-LENGTH(data-area)--------------------' '-RRN-'
>--+-----------+-----------------------------------------------><
'-NOSUSPEND-'
Conditions: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, LENGERR, LOCKED, NOTAUTH, NOTFND, RECORDBUSY, SYSIDERR
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 may 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.
Note: You cannot specify an RBA for VSAM data sets greater
than 4GB (that is, defined with the extended format / extended addressability
attribute). The only VSAM data sets greater than 4GB supported by CICS® are KSDS,
and then only if they are accessed by key. CICS does not support ESDS or RRDS
data sets defined with the extended attribute.
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 specifying 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:
Locks for UPDATE
Specifying UPDATE on a READPREV
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 syncpoint 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.
UNLOCK note
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 specifying 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:
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 don't 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 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 not specified. 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.
- 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. You must specify this option after
any STARTBR or RESETBR command that specified the RBA option.
You cannot
use RBA for:
- User-maintained data tables
- Coupling facility data tables
- Any KSDS files opened in RLS access mode
- KSDS or ESDS files that hold more than 4GB
- 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 syncpoint 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 syncpoint 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 can be greater than or equal to zero. For a relative
record number, the RIDFLD 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 specifying
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 16MB line.
If
DATALOCATION(BELOW) is associated with the application program, the address
returned in the SET pointer is below the 16MB 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.
Conditions
- 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.
- ENDFILE
- RESP2
values:
- 90
- An end-of-file condition is detected during a browse.
Default action: terminate the task abnormally.
- FILENOTFOUND
- RESP2
values:
- 1
- A file name referred to in the FILE option cannot be found in the FCT.
Default action: terminate the task abnormally.
- ILLOGIC
- RESP2
values (VSAM):
- 110
- A VSAM error occurs that does not fall within one of the other CICS response
categories.
(See EIBRCODE in the EXEC interface block, EXEC interface block.)
Default action: terminate the task abnormally.
- 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 is changed.
- 39
- A READPREV is issued for a BDAM file.
- 41
- The REQID, if any, 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.
Default action: terminate the task abnormally.
- 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 normally
indicates a hardware error. (Further information is available in the EXEC
interface block, EXEC interface block.)
For
a coupling facility data table, an IOERR indicates a bad response returned
from a coupling facility access.
Default action: terminate the task abnormally.
- ISCINVREQ
- RESP2
values:
- 70
- The remote system indicates a failure that does not correspond to a known
condition.
Default action: terminate the task abnormally.
- 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.
- 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 can also occur for a request to a recoverable CFDT that uses
the locking model, if the record being read is locked by a retained lock.
See the CICS Recovery
and Restart Guide for information about investigating retained
locks on records in a coupling facility data table.
Default action: abend the task with code AEX8.
- NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on FILE(filename).
Default action: terminate the task abnormally.
- 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.
Default action: terminate the task abnormally.
- 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.
- SYSIDERR
- RESP2
values:
- 130
- The SYSID option specifies a name that has not been defined to CICS as
a remote system (defined by defining a CONNECTION). SYSIDERR also occurs when
the link to the remote system is closed.
- 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 the CICS System Definition Guide for
information about restarting a coupling facility data table server and reloading
a table.
Default action: terminate the task abnormally.