Reads the next record during a browse.

Sintaxe

Notas:

1. DATASET is also accepted, but FILE is preferred.
2. When SYSID is specified, the LENGTH option can be omitted if SET is also specified, but not if INTO is also specified.
3. KEYLENGTH is required with SYSID for a KSDS browse.
4. DSIDERR is equivalent to FILENOTFOUND.

Descrição:

READNEXT repeatedly reads records in sequence from a file that is 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 sequence.
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 large enough to contain a complete identifier (full key, RBA, or RRN) of records that are in the file.
This data area can be used both as an output and input argument.

It is used as an output argument when CICS, on completion of each READNEXT command, places the complete identifier of the record that is just retrieved into the RIDFLD data area.
CICS then remembers this identifier to mark the point from which the subsequent READNEXT is to continue.

It can also be used as an input argument to allow you to modify the RIDFLD data area contents before you issue subsequent READNEXT commands.
This has the effect of repositioning the browse to the new identifier, from which it continues in the usual way.
If the browse was started with the GTEQ option, that attribute also applies to the modified RIDFLD option.

A READNEXT command that follows a READPREV command attempts to read the same record as that which is read by the READPREV command.
Intervening insertion or deletion activities on the underlying file might cause other records to be read.

If you issue a READNEXT command in a context where an ILLOGIC or IOERROR condition does not terminate a task, and such a condition occurs, the browse is terminated.
You will need to reestablish the position of the browse by issuing a STARTBR command before you issue another READNEXT or READPREV command.

Opções:

FILE(name)
• Specifies the name of the CICS file that is to be browsed.
• The name must be alphanumeric, up to eight characters long, and the file must be currently BROWSABLE (see INQUIRE FILE).
• If a remote SYSID is specified, the underlying file is assumed to reside on a remote system irrespective of whether the name exists in the local File Definitions (FD).
• Otherwise, the FD 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 that was retrieved from the file is to be written.
• The contents of the data area are unpredictable if a condition other than LENGERR occurs.
• See INTO and SET for more information about using this option.

KEYLENGTH(data-value)
• Specifies, as a 16-bit binary value, the length of the key that is supplied in the RIDFLD option.
• If KEYLENGTH is omitted, and SYSID is also omitted, CICS obtains the length of the key if the file is local, or gets it from the KeyLen attribute in the FD if the file is remote.
  If SYSID is present, KEYLENGTH must be specified; the length cannot be taken from the FD. See KEYLENGTH and RIDFLD for more information about using this option.
• KEYLENGTH should not be present if the record identification field that is supplied in the RIDFLD option contains either a relative byte address (use the RBA option) or a relative record number (use the RRN option).

LENGTH(data-area)
• Specifies, as a 16-bit binary value, the length of the data area into which 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.
• The LENGTH option must be specified if the SYSID and INTO options are both present.
• It must also be specified with the INTO option on commands that involve variable-length records.
• It need not be specified for fixed-length records, but its inclusion is recommended because:
  • It causes a check to be made that the record that is being read is not too long for the available data area.
  • If fixed-length records are being browsed into an area that is longer than the record that is being accessed, and the LENGTH option is not specified, the LENGERR condition occurs (for COBOL and PL/I applications).
• If the target data area is longer than the record that is 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 that is 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.
• See LENGTH for more information about using this option.

RBA
• Specifies that the record identification field that is supplied in the RIDFLD option contains a relative byte address.
• You must specify this option when browsing an ESDS.
• The RBA option should not be present if the record identification field that is supplied in the RIDFLD option contains either a key (use the KEYLENGTH option) or a relative record number (use the RRN option).

REQID(data-value)
• Specifies, as a 16-bit binary value, a unique request identifier for the browse; it is used to control multiple browse operations on a file.
• The value should be the same as that which is given to the corresponding STARTBR command.
• 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 32-bit binary; and either the RBA or the RRN option must be specified as appropriate.
• A relative byte address can be greater than, or equal to, zero; a relative record number can be greater than, or equal to 1.
• The RIDFLD data area 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 that is retrieved.
• See KEYLENGTH and RIDFLD for more information about using this option.

RRN
• Specifies that the record identification field that is supplied in the RIDFLD option contains a relative record number.
• You must specify this option when browsing an RRDS.
• The RRN option should not be present if the record identification field that is supplied in the RIDFLD option contains either a key (use the KEYLENGTH option) or a relative byte address (use the RBA option).

SET(ptr-ref)
• Specifies a pointer reference that is to be set to the address of the retrieved record.
• See INTO and SET for more information about using this option.

• The pointer reference is valid until the next READNEXT or READPREV command that specifies SET for the same file and the same REQID.
• The pointer is no longer valid after an ENDBR or SYNCPOINT command.
• If you want to retain the data within the field that is addressed by the pointer, you should move it to your own area.

SYSID(name)
• Specifies on which CICS region the READNEXT is to run.
• The SYSID name has one through four characters.
• For a full description of the SYSID option, refer to SYSID.
• If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the FD entry for the file that is requested in the FILE option.
• If the SYSID option requests a remote SYSID:
  • KEYLENGTH must be specified for a KSDS browse because the length of the key cannot be determined from the FD entry.
  • LENGTH is required if SET is not specified.

Condições:

DISABLED
• Occurs if a file is disabled. A file might be disabled because:
  • It was initially defined as disabled and has not since been enabled.
  • It has been disabled by an EXEC CICS SET FILE command or by the CEMT transaction.
• This condition cannot occur after a successful STARTBR command that specified the same REQID, unless an ENDBR has since been issued for that REQID.
• Ação pré-definida: Terminates the task abnormally.

DUPKEY
• Occurs if a record is retrieved by way of an alternative index that supports non-unique keys, and another alternative index record that has the same key follows.
• It does not occur as a result of a READNEXT command that reads the last of the records that has the non-unique key.
• Ação pré-definida: Terminates the task abnormally.

ENDFILE
• Occurs if an end-of-file condition is detected during the browse.
• Ação pré-definida: Terminates the task abnormally.

FILENOTFOUND
• Occurs if the name that is specified in the FILE option cannot be found in the FD.
• Ação pré-definida: Terminates the task abnormally.

ILLOGIC
• Occurs if an error occurs that does not fall within one of the other CICS response categories.
• Further information is available in the EIBRCODE field; see Appendix A, EXEC interface block (EIB) fields for details.)
• Ação pré-definida: Terminates the task abnormally.

INVREQ
• Occurs for the following conditions, depending on the options that are specified on the READNEXT command:
  • The READNEXT command is issued for a file that has had no previous STARTBR command successfully issued.
  • The type of record identification (for example, key or relative byte address) that is used to access a file during the browse is changed by the READNEXT command.
  • An invalid combination of RIDFLD, RBA, and RRN is specified for the file type.
• Ação pré-definida: Terminates the task abnormally.

IOERR
• Occurs if an I/O error occurs during the READNEXT.
• An I/O error is any unusual event that is not covered by a CICS condition.
• Further information is available in the EIBRCODE field; see Appendix A, EXEC interface block (EIB) fields for details.
• See Processing the IOERR condition for information about handling the IOERR condition.
• Ação pré-definida: Terminates the task abnormally.

ISCINVREQ
• Occurs if the remote system indicates a failure that does not correspond to a known condition.
• Ação pré-definida: Terminates the task abnormally.

LENGERR
• Occurs for the following conditions:
  • The length of the record that is read with the INTO option specified exceeds the value that is specified in the LENGTH option; the record is truncated, and the data area that is supplied in the LENGTH option is set to the actual length of the record.
  • An incorrect length is specified for a file that has fixed-length records.
• Ação pré-definida: Terminates the task abnormally.

NOTAUTH
• Occurs for the following conditions:
  • A resource security check is unsuccessful on FILE(name).
  • SYSID was specified by a transaction that is defined with the RSLCheck attribute set to either internal or external.
• Ação pré-definida: Terminates the task abnormally.

NOTFND
• Occurs if an attempt to retrieve a record, based on the search argument that is provided, is unsuccessful.
• Ação pré-definida: Terminates the task abnormally.

NOTOPEN
• Occurs for the following conditions:
  • The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED state is reached after a CLOSE request has been received against an OPEN ENABLED file, and the file is no longer in use.
  • The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.
  • Current activity is allowed to complete, but no new activity is allowed to start.
• This condition does not occur if the request is made to either a CLOSED, ENABLED file or a CLOSED, DISABLED file.
• In the first case, the file is opened as part of executing the request. In the second case, the DISABLED condition occurs.
• This condition cannot occur after a successful STARTBR command that specified the same REQID, unless an ENDBR has since been issued for that REQID.
• Ação pré-definida: Terminates the task abnormally.

SYSIDERR
• Occurs if a problem with the communications configuration prevents the READNEXT from proceeding.
• For example:
  • The connection that is named in the SYSID option is not the name of a Communications Definition (CD) entry.
  • The SYSID option references a CD entry that is incorrectly configured.
  • The SYSID option references a CD entry that is marked as out of service.
• It can also occur if the connection to the remote system is closed.
• This could be because the remote system is not available.
• Ação pré-definida: Terminates the task abnormally.

Informações relacionadas:

• Processing the IOERR condition
• ENDBR
• INQUIRE FILE
• READ
• READPREV
• STARTBR
• UNLOCK
• Appendix A, EXEC interface block (EIB) fields
• TXSeries for Multiplatforms Application Programming Guide
• TXSeries for Multiplatforms Administration Reference
• TXSeries for Multiplatforms Intercommunication Guide