READNEXT
Summary
READNEXT used to read records in sequential order from the current reading position of the file on a local or a remote system. A series of sequential read commands is known as a browse of the file.
A browse consists of a sequence of READNEXT and READPREV commands in any order. A browse must be initiated with the STARTBR command and terminated with the ENDBR command.
Modifying the RIDFLD before issuing the next READNEXT command causes repositioning the browse to the new identifier. 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 with a key greater than or equal to the modified RIDFLD. Specifying UPDATE on a READNEXT command acquires an exclusive lock. The duration of these exclusive locks depends on the next commands execution in application program -
- If DELETE or REWRITE command executed, the lock remains active until below
- 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.
- If either issues another READNEXT or READPREV command or ends the browse, then the lock get released.
Syntax -
Parameters -
FILE(file-name) -
Specifies the name of the file to be browsed. If SYSID is specified, the data set is on a remote system irrespective of the name is defined to CICS.
If SYSID is not specified, the data set assumed to be on the local system. 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 where the record retrieved is to be written from the data set.
KEYLENGTH(data-value) -
data-value is a halfword binary value. Specifies the key length. The value specified in KEYLENGTH is same as the value specified in the RIDFLD option except when RBA or RRN is specified.
KEYLENGTH is not valid when RBA or RRN is specified. KEYLENGTH must be specified if GENERIC is specified or key is specified. If the length specified is different from the length defined for the data set and the operation is not generic, the INVREQ condition occurs.
If the browse was started with the GENERIC option 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 STARTBR or RESETBR command, issuing READNEXT with KEYLENGTH(0) repositions the BROWSE at the start of the file. If EQUAL is specified with READNEXT KEYLENGTH(0), the results of the READ are unpredictable. If only KEYLENGTH(0) is specified which always causes the browse to be repositioned to the beginning of the file.
CICS maintains a current key length for the generic browse. The current key length is initialized to the value specified as KEYLENGTH on the STARTBR command. Current key length can be modified by specifying KEYLENGTH on a READNEXT or RESETBR command.
Changing the current key length causes the browse to be repositioned. A browse can be repositioned by modifying the RIDFLD data area. For remote files, specify the KEYLENGTH in the FILE definition. If KEYLENGTH is not defined and is not specified in the application program and the key is longer than 4 characters, the default value is 4.
LENGTH(data-value) -
data-value is a halfword binary value. Specifies the data area (record) length to where the record is to be put. The LENGTH parameter contains the actual length of the record on completion of the READNEXT command. This option is mandatory if SYSID is specified.
If the file is on a remote system, the LENGTH parameter should be set in the file resource definition. If the file is on a local system, the LENGTH option must be specified for variable-length records, but is optional for fixed-length records. However, it is advisable to specify the length of fixed-length records.
If the LENGTH option is specified and the data area longer than the record being accessed while reading fixed-length records, the LENGERR condition is raised. 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 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. If the SET option specified, do not need to specify the LENGTH option.
NOSUSPEND (RLS only) -
The request does not wait if the record is locked by VSAM with an active lock.
RBA -
This option is for VSAM KSDS or ESDS base data sets only. Specifies the RIDFLD option field contains a relative byte address. This option must be specified when the STARTBR or RESETBR command issued the RBA option. Its not mandatory when the STARTBR or RESETBR command did not specify with RBA.
REQID(data-value) -
data-value is a halfword binary value. Specifies 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 or a relative byte address, or relative record number (for VSAM data sets), or a block reference, a physical key, and a deblocking argument (for BDAM data sets).
The field is full word binary for a relative byte address or a relative record number. If RBA is specified, the RIDFLD can be greater than or equal to zero.
If RRN is specified, the RIDFLD can be greater than or equal to 1 even when the GTEQ option is specified. RIDFLD should specify if the GENERIC option specified. If the browse is generic, the RIDFLD should always be large enough to accommodate the complete record identifier.
RRN -
This option is valid for VSAM RRDS. Specifies the RIDFLD option contains a relative record number.
SET(ptr-ref) -
Specifies the pointer reference to contain the address of the retrieved record. 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.
SYSID(system-name) -
Specifies the system name to which the request is directed. If SYSID specified and omit RBA and RRN, LENGTH and KEYLENGTH must be specified.
TOKEN(data-area) (RLS only) -
Returns the request identifier for this READNEXT UPDATE request. This is an output value returned by file control, for use in associating a subsequent REWRITE or DELETE (or UNLOCK) request with the record returned on READNEXT command.
The returned TOKEN must be specified on a subsequent REWRITE or DELETE command to identify the record being rewritten or deleted. The returned TOKEN must be specified on a subsequent UNLOCK command to identify the token that is being invalidated.
CICS supports only one active TOKEN at a time for a given REQID. 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.
UNCOMMITTED -
The record is read without read integrity. No attempt is made to serialize read request with any concurrent update activity for the same record.
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 UPDATE specified, TOKEN must be specified.
XRBA -
Specifies the RIDFLD option field contains an extended relative byte address. This option should be used when browsing records in an ESDS extended addressing data set.
XRBA on a READNEXT command cannot specify unless the associated STARTBR or RESETBR command also specified XRBA. KSDS data sets cannot be accessed by XRBA.
Error Conditions -
Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.
| Error Condition | RESP2, Description & Solution | System Action |
|---|---|---|
| 15 DUPKEY | 140 - A record is accessed by way of an alternate index with the NONUNIQUEKEY attribute and another alternate index record with the same key follows. Solution -Verify the record key and use READ with UPDATE to delete specific record or use generic key to delete both if the second record is not important. | Task abnormally terminated |
| 12 FILENOTFOUND | 1 - A file name in the FILE option is not defined to CICS. Solution -Contact support team to define the FILE in CICS region. | Task abnormally terminated |
| 20 ENDFILE | 90 - An end-of-file condition is detected during the browse. Solution -File end reached during the browse and should be handled programmatically. Modify the program to handle the error to continue the flow. | Task abnormally terminated |
| 21 ILLOGIC | 110 - VSAM error occurs that is not in one of the other CICS response categories. Solution -This might be due to the non-sequence of file operations. Debug the program to correct the logic. | Task abnormally terminated |
| 16 INVREQ | 20 - The FILE definition does not allow updates. Solution -Change the resource definitions if the deletion is valid or do not perform delete if the file definitions are correct. 25 - The KEYLENGTH, GENERIC was specified on the STARTBR or the last RESETBR and the value of KEYLENGTH was greater than the full key length. Solution -When a KEYLENGTH and GENERIC options specified, it is a generic key and the length value should be less than the length of the full key. Change the program to modify the length value. 26 - The KEYLENGTH option is specified for a nongeneric browse and the specified length does not equal the length defined for the data set. Solution -If only KEYLENGTH option specified, the length value should match the dataset full key. Change the program to modify the length value. 34 - The REQID, SYSID or file name does not match with any successful STARTBR command. Solution -A SYNCPOINT was issued causing STARTBR, READNEXT/READPREVs position to be lost. 37 - The type of record identification used to access a data set during the browse has been changed. Solution -The record identification used for browse should be same until the browse completion. Modify the programming logic to resolve the issue. 42 - The KEYLENGTH, GENERIC was specified on the STARTBR or the last RESETBR and the value of KEYLENGTH was less than zero. Solution -When a KEYLENGTH and GENERIC options specified, it is a generic key and the length value should be less than the length of the full key and should be greater than zero. Change the program to modify the length value. 54 - UPDATE is not allowed because the file is not a VSAM file that is accessed in RLS mode. Solution -UPDATE option is allowed on VSAM file. Modify the program to remove UPDATE as the file is not VSAM. 55 - NOSUSPEND is specified on a READ request to a non-RLS mode file. Solution -NOSUSPEND option is valid for only VSAM files accessed in RLS mode. Modify the program to remove NOSUSPEND option for files which are not accessing in RLS mode. | Task abnormally terminated |
| 17 IOERR | 120 - There is an I/O error during the READNEXT operation. Solution -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. | Task abnormally terminated |
| 54 ISCINVREQ | 70 - The remote system indicates a failure that does not correspond to a known condition. Solution -Contact remote system support team to resolve the issue. | Task abnormally terminated |
| 100 LOCKED | 106 - An attempt is being made to read a record either specifying the UPDATE keyword or specifying CONSISTENT or REPEATABLE, but the record is locked by a retained lock. Solution -The record might get locked for some other reason. Wait for some time and try again. | abend the task with code AEX8. |
| 70 NOTAUTH | 101 - A resource security check has failed on FILE (filename). Solution -Contact system administrator team to check whether the appropriate access added for the user or group. It will resolve the problem. | Task abnormally terminated |
| 22 LENGERR | 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. Solution -Either LENGTH option or SET option should be specified for the files in the above case. Modify the program to specify either LENGTH or SET option. 11 - The length of the record read with the INTO option exceeds the value specified in the LENGTH option. Solution -The length option specified with LENGTH option should equal to the record read length. If you are not aware of the length, specify it as a MAXLENGTH. 13 - An incorrect length is specified for a file with fixed-length records. Solution -Modify the program to specify the file fixed length as a length value to resolve the issue. | Task abnormally terminated |
| 101 RECORDBUSY | 107 - The NOSUSPEND keyword is specified and the record is locked by an active lock. Solution -This might occur very rarely. Wait for some time and try again.If this occurring on regular basis, modify the application program to remove NOSUSPEND. | Abend the task with code AEX9 |
| 53 SYSIDERR | 130 - The SYSID name specified is neither the local region nor a remote system or the link to the remote system is closed. Solution -The specified SYSID name is not related to any system. Correct it.If the link to the remote system is closed, that might be due to the remote system is not up and running. Contact remote system support team. | Task abnormally terminated |
| 13 NOTFND | 80 - An attempt to retrieve a record based on the search argument provided is unsuccessful. Solution -This might occur due to the record already gets deleted or the record doesn’t exist. Handle the error programmatically. 81 - XRBA was specified and the value of RIDFLD was greater than 4 GB but the data set is not an extended addressing ESDS. Solution -XBRA option only used for extended ESDS. If the dataset is not extended ESDS, do not use XBRA. Modify program to remove the XBRA. | Task abnormally terminated |