EXEC CICS READ
INTO(RECORD)
LENGTH(RLENGTH)
FILE(’MASTER’)
RIDFLD(ACCTNO)
KEYLENGTH(4)
GENERIC
GTEQ
READNEXT
Read the next record during a browse.
(1)
READNEXT FILE (
name
) INTO
SET (
(
data-area ptr-ref
)
)
LENGTH (
data-area
)
RIDFLD (
data-area
)
KEYLENGTH
RBA
RRN
(
data-value
)
REQID (
data-value
)
(2)
SYSID (
name
)
Notes:
1
2
DATASET is also accepted, but FILE is the preferred term (see “DATASET option” on page 311).
Only supported when function shipping.
Conditions:
DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR,
NOTAUTH, NOTFND, SYSIDERR
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.
The first READNEXT command reads the record at the position specified in the
STARTBR command. On completion of the READNEXT command, CICS places the complete identifier of the record just retrieved into the RIDFLD data area. When the next READNEXT command is issued, CICS reads the record following the position identified by the contents of the RIDFLD field and updates the RIDFLD field with the identifier of the record just read.
Chapter 32. Application programming commands - reference
395
You may modify the RIDFLD data area contents before issuing subsequent
READNEXT commands. This has the effect of starting a new browse, which means the record identified by the RIDFLD field is read on the next READNEXT command, rather than the next record, in the same way as if a STARTBR command had been issued. CICS updates the RIDFLD contents with the complete identifier of the record just read, and the next READNEXT command causes the next record to be read, as before.
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 file with a key greater than or equal to the modified RIDFLD.
A READNEXT command following a READPREV command has the same effect as issuing a STARTBR command or repositioning the browse. The record identified by the RIDFLD field is read; that is CICS reads the same record as that read by the
READPREV command, not the next record.
See Chapter 10, “File control,” on page 115 for further information.
Options
FILE(
name
)
specifies the name of the file to be browsed. The name must be alphanumeric, up to 8 characters long, and must have been defined in the file control table
(FCT) unless the SYSID option specifies a remote system.
If a nonlocal SYSID is specified, the underlying file is assumed to be on a remote system irrespective of whether the name is defined in the local FCT.
Otherwise, the FCT entry is used to determine whether the underlying file is on a local or a remote system.
INTO(
data-area
)
specifies the data area into which the record retrieved from the file is to be written.
KEYLENGTH(
data-value
)
specifies as a halfword binary value the length of the key supplied in the
RIDFLD option.
If the browse was started without the GENERIC option (that is, a full key browse) and a specified KEYLENGTH value differs from the length defined for the underlying file, the INVREQ condition occurs.
In a generic browse, if KEYLENGTH is omitted or the KEYLENGTH value is unchanged, the browse continues using the last specified key length.
KEYLENGTH(0) may be used in a generic browse with the object of reading the first record in the file, provided that GTEQ was specified on the STARTBR or RESETBR command.
LENGTH(
data-area
)
specifies as a halfword binary value the length of the data area where the retrieved record is to be placed. On completion of the retrieval operation, the
LENGTH argument (which must be a data area) contains the actual length of the retrieved record.
This option must be specified with SYSID. It must also be specified with the
INTO option on commands involving variable-length records. It need not be specified for fixed-length records, but its inclusion is recommended because:
396
CICS for iSeries Application Programming Guide V5
v
It causes a check to be made that the record being read is not too long for the available data area. v
When browsing fixed-length records into an area longer than the record being accessed, the LENGERR condition occurs 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.
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 specify the largest record that 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 argument is set to the length of the record before truncation.
If you specify the SET option, the LENGTH option need not be specified but, if it is, the argument must be a data area.
RBA
specifies that the record identification field specified in the RIDFLD option contains a relative byte address. The RIDFLD value can be from 0 upward.
This option must be specified when browsing an ESDS directly.
REQID(
data-value
)
specifies as a halfword binary value a unique request identifier for the browse; it is 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 a relative record number. For a relative byte address or a relative record number, the format of this field must be fullword binary.
Even if the browse is generic, this field 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
specifies that the record identification field specified in the RIDFLD option contains a relative record number. Use this option only when browsing an
RRDS. The RIDFLD value can be from 1 upward.
SET(
ptr-ref
)
specifies a pointer reference to be set to the address of the retrieved record.
The pointer reference is valid until the next READNEXT or READPREV command specifying SET 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 should move it to your own area.
SYSID(
name
)
specifies the name of the system to which the request is directed. The name can be up to 4 characters long.
If you specify SYSID, and omit both RBA and RRN, you must also specify
LENGTH and KEYLENGTH; they cannot be found in the FCT.
Chapter 32. Application programming commands - reference
397
Exception Conditions
Note:
RESP2 values are not set for files that are on remote systems.
DUPKEY
RESP2 values:
140
A record is retrieved from a VSAM emulated file that allows duplicate keys, and another 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.
Default action: Terminate the task abnormally.
ENDFILE
RESP2 values:
90
An end-of-file condition is detected during the browse.
Default action: Terminate the task abnormally.
FILENOTFOUND
RESP2 values:
1
The name specified in the FILE option cannot be found in the FCT.
Default action: Terminate the task abnormally.
ILLOGIC
RESP2 values:
110
There is an error that does not fall within one of the other CICS response categories. (Further information is available in the EIBRCODE
field; refer to Appendix A, “EXEC interface block,” on page 529 for
details.)
Default action: Terminate the task abnormally.
INVREQ
RESP2 values:
25
The KEYLENGTH option is specified for a generic browse (that is, one where GENERIC was specified on the STARTBR command or the last
RESETBR command) and the value of KEYLENGTH was greater than or equal to the full key length.
26
34
The KEYLENGTH option is specified for a non-generic browse, and the specified length differs from the length defined for the underlying file.
The READNEXT command is issued for a file that has had no previous
STARTBR command successfully issued.
37
42
The type of record identification (for example, key or relative byte address) used to access a file during the browse is changed by the
READNEXT command.
The KEYLENGTH option is specified for a generic browse (that is, one where GENERIC was specified on the STARTBR command or the last
RESETBR command) and the value of KEYLENGTH was less than zero.
Default action: Terminate the task abnormally.
398
CICS for iSeries Application Programming Guide V5
IOERR
RESP2 values:
120
There is an I/O error during the READNEXT. An I/O error is any unusual event that is not covered by a CICS exception condition.
(Further information is available in the EIBRCODE field; refer to
Appendix A, “EXEC interface block,” on page 529 for details.)
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
13
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.
An incorrect length is specified for a file with fixed-length records.
Default action: Terminate the task abnormally.
NOTAUTH
RESP2 values:
101
A resource security check has failed on FILE(
name
).
Default action: Terminate the task abnormally.
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 file (a complete key of X'FF' bytes).
Default action: Terminate the task abnormally.
SYSIDERR
RESP2 values:
130
The SYSID option specifies either a name that is not defined in the terminal control system table (TCS), or a system to which the link is closed.
Default action: Terminate the task abnormally.
Chapter 32. Application programming commands - reference
399
