READNEXT
Read next record during a browse of a file.
Conditions: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING, LOCKED, NOTAUTH, NOTFND, RECORDBUSY, SYSIDERR
- 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.
- 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
READNEXT can be used repeatedly to read records in sequential order from a 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 starting point 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 can be used both as an output and as an input parameter.
It is used as an output parameter when CICS, on completion of each READNEXT 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 READNEXT is to continue.
It may, except for BDAM, also be used as an input parameter. Modifying the RIDFLD before issuing the next READNEXT command causes that command to reposition the browse to the new identifier, from which it continues in the usual way. If the browse was started with the GENERIC option, the modified RIDFLD must be generic. If the browse was started with the GTEQ option, the next record returned is the first record in the data set with a key greater than or equal to the modified RIDFLD.
A READNEXT command following a READPREV, or a STARTBR or RESETBR that specified a 'last' key value, is treated as though the RIDFLD value has 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 READNEXT 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.
- You can specify UPDATE on a READNEXT 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 READNEXT, 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 READNEXT command to the next.
CICS supports only one TOKEN in a browse sequence, and the TOKEN value on each READNEXT invalidates the previous value.
Locks for UPDATE
- If you decide to DELETE or REWRITE the last record acquired by
a READNEXT 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.
Locks for read integrity
- 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 READNEXT with UPDATE or read integrity
- 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.
- 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.
- READNEXT requests for records that have retained locks are always rejected with a LOCKED response.
- READNEXT 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 READNEXT request waits until the update is complete (unless NOSUSPEND is also specified) as follows:
- For a READNEXT request against a non-recoverable file, the READ completes as soon as any VSAM request performing the update completes.
- For a READNEXT request against a recoverable file, the READ request completes when the updating task completes its next sync point or rollback.
- FILE(filename)
- specifies
the name of the file to be 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 to CICS. Otherwise, the resource 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 browse was started without the GENERIC option (that is a full key browse) and if the length specified is different from the length defined for the data set, the INVREQ condition occurs.
If the browse was started with the GENERIC option (that is, a generic key browse), and if the length specified is greater than the length specified for the data set, the INVREQ condition occurs.
If GTEQ and GENERIC were specified on the most recent STARTBR or RESETBR command, issuing READNEXT with KEYLENGTH(0) specified repositions the BROWSE at the start of the file. If EQUAL had been specified, the effect of READNEXT KEYLENGTH(0) would be unpredictable.
For a generic browse, CICS maintains a current key length for the browse. The current key length is initialized to be the value specified as KEYLENGTH on the STARTBR command.
You can modify the current key length by specifying KEYLENGTH on a READNEXT or RESETBR command. If the current key length is changed, this causes the browse to be repositioned. The browse is repositioned to the key whose initial characters match the value specified in the RIDFLD for the current key length.
The current key length is zero after a request that specifies KEYLENGTH(0).
IF KEYLENGTH is omitted on a READNEXT command, the current key length remains the same and the browse continues without repositioning.
If KEYLENGTH is specified on a READNEXT command and is equal to the current key length, this is treated as being no change and the browse is not repositioned. The one exception to this is when KEYLENGTH(0) is specified, which always causes the browse to be repositioned to the beginning of the file.
KEYLENGTH can be specified during a generic browse with a value equal to the full key length. This does not cause the current key length to change and the browse is not repositioned. The ability to specify the full key length during a generic browse is provided to allow requests that specify SYSID to be able to tell the function-shipping transformers how long the key is, so that the transformers can ship the key to the file-owning region.
A browse can be repositioned by modifying the RIDFLD data area. A generic browse is repositioned only if the modification to RIDFLD changes the part of RIDFLD corresponding to the current key length. A consequence of this is that the browse cannot be repositioned by modifying the RIDFLD data area if the current key length is zero.
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
- 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 READNEXT request waits until the update is complete (unless NOSUSPEND is also specified) as follows:
- For a recoverable file, the READNEXT request completes when the updating transaction completes its next sync point or rollback.
- For a non-recoverable file, the READNEXT completes as soon as the VSAM request performing the update completes.
After the READNEXT request has completed, the record remains locked to the task that issued the READNEXT. Other tasks may continue to read the record but no other task is allowed to update the record until the task that issued the READNEXT 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 VSAM data sets), or a block reference, physical key, and deblocking argument (for BDAM data
sets). 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 value can be greater than or equal to 1.
See Identifying BDAM records and Identifying VSAM records for more information about defining the record identification field.
Even if the browse is generic, this RIDFLD should always be large enough to accommodate the complete record identifier. This is because, on completion of the READNEXT command, the 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 READNEXT or READPREV command 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 of the data 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; they cannot be found in the resource definition.
- TOKEN(data-area) (RLS only)
- Returns,
as a fullword binary value, the request identifier for this READNEXT
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 READNEXT
command.
You must specify the returned TOKEN on a subsequent REWRITE or DELETE command to identify the record being rewritten or deleted. You can also specify the value returned by CICS on the TOKEN option 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, RESETBR, 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 READNEXT command unless the associated STARTBR or RESETBR command also specified XRBA.
KSDS data sets cannot be accessed by XRBA.
Conditions
- 15 DUPKEY
- RESP2
values (VSAM):
- 140
- A record is retrieved by way of an alternate index with the NONUNIQUEKEY
attribute, and another alternate index record with the same key follows.
It does not occur as a result of a READNEXT command that reads the
last of the records having the nonunique key.
In assembler language, if the SET option is being used, the register specified will not have 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 the 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.
- 16 INVREQ
- RESP2
values:
- 20
- The FILE definition does not allow updates.
- 25
- The KEYLENGTH option is specified for a generic browse (that is, one where GENERIC was specified on the STARTBR or the last RESETBR) and the value of KEYLENGTH was greater than the full key length.
- 26
- The KEYLENGTH option is specified for a nongeneric browse, and the specified length does not equal the length defined for the data set to which this file refers.
- 34
- The REQID, SYSID, or file name does not match that of any successful STARTBR command, or a SYNCPOINT was issued causing STARTBR, READNEXT/READPREVs position to be lost.
- 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 READNEXT.
- 42
- The KEYLENGTH option is specified for a generic browse (that is one where GENERIC was specified on the STARTBR or the last RESETBR) and the value of KEYLENGTH was less than zero.
- 52
- CONSISTENT is specified on a READ request to a non-RLS mode file, or to a data table that is specified with RLSACCESS(YES). CONSISTENT is not allowed if the file refers to a data table, even if the file definition specifies RLSACCESS(YES).
- 53
- REPEATABLE is specified on a READ request to a non-RLS mode file, or to a data table that is specified with RLSACCESS(YES). REPEATABLE is not allowed if the file refers to a data table, even if the file definition specifies RLSACCESS(YES).
- 54
- UPDATE is not allowed because the file is not a VSAM file that is accessed in RLS mode.
- 55
- NOSUSPEND is specified on a READ request to a non-RLS mode file, or to a data table that is specified with RLSACCESS(YES). NOSUSPEND is not allowed if the file refers to a data table, even if the file definition specifies RLSACCESS(YES).
- 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
- There is an I/O error during the READNEXT command. 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.
For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.
Further information is available in the EXEC interface block; for details, see EIB fields.
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 or a BDAM file with undefined-format 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.
- 94 LOADING
- RESP2
values:
- 104
- The read request specifies a record key for a record in a coupling facility data table that is
still being loaded, and the key is out of range of the records already loaded. Records can be
browsed in a coupling facility data table during loading only if the requested key is within the
range of those records already loaded.
The LOADING response can also be returned for a coupling facility data table that has failed during loading. For more information about what happens if the load for a coupling facility data table fails, see the description of the XDTLC global user exit in Data tables management exits XDTRD, XDTAD, and XDTLC.
If your application programs encounter the LOADING condition persistently or too frequently, check that this is not caused by conflicting file definitions that reference the same data set.
- 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 READNEXT request.
The LOCKED condition can also 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. This may occur if the READNEXT command immediately follows a STARTBR command that specified the key of the last record in the data set (a complete key of X'FF's).
- 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 READNEXT 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 READNEXT 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.