Read next record during a browse of a file.
READNEXT >>-READNEXT--FILE(filename)--+-INTO(data-area)-+----------------> '-SET(ptr-ref)----' >--+--------------------------+--RIDFLD(data-area)--------------> +-UNCOMMITTED--------------+ +-CONSISTENT---------------+ +-REPEATABLE---------------+ '-UPDATE--TOKEN(data-area)-' >--+-----------------------+--+-------------------+-------------> '-KEYLENGTH(data-value)-' '-REQID(data-value)-' >--+--------------------------------------+--+------+-----------> +-SYSID(systemname)--LENGTH(data-area)-+ +-RBA--+ '-LENGTH(data-area)--------------------' +-RRN--+ '-XRBA-' >--+-----------+----------------------------------------------->< '-NOSUSPEND-'
Conditions: DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING, LOCKED, NOTAUTH, NOTFND, RECORDBUSY, SYSIDERR
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).
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.
CICS supports only one TOKEN in a browse sequence, and the TOKEN value on each READNEXT invalidates the previous value.
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.
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.
RECORDBUSY refers to active locks, and LOCKED refers to retained locks.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
If you specify UPDATE, you must also specify TOKEN.
UPDATE is only valid for files defined to the local region
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.
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.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
See EIBRCODE in the EXEC interface block; for details, see EIB fields.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
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.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
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 .
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.
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 tables retained locks for information about investigating retained locks on records in a coupling facility data table.
Default action: abend the task with code AEX8.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
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.
Default action: terminate the task abnormally.