Reads the previous record during a browse.

Sintaxe:

Notes:

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:

READPREV repeatedly reads records in reverse 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 series of READNEXT and READPREV commands in any sequence.
A browse must be initiated with the STARTBR command, to identify the start 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 in the file.
This data area can be used both as an output and as an input argument.

It is used as an output argument when CICS, on completion of each READPREV 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 READPREV 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 READPREV commands.
This has the effect of repositioning the browse to the new identifier, from which it continues in the usual way.
The modified record identifier must always be a full key, RBA, or RRN.

If you include a READPREV command immediately following a STARTBR command, your STARTBR command must specify the key of a record that exists on the file; otherwise, the NOTFND condition occurs for the READPREV command.

A READPREV command that follows a READNEXT command reads the same record as that which is read by the READNEXT command.

Intervening insertion or deletion activities on the underlying file might cause other records to be read.

If you issue a READPREV command in a context in which 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 READPREV or READNEXT command.

Opções:

FILE(name)
• Specifies the name of the CICS file that being 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 is 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).
• If a specified KEYLENGTH value differs from the length that is defined for the underlying file, the INVREQ condition occurs.

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 READPREV 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.
• 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 READPREV 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 READPREV 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 exists.
• Ação pré-definida: Terminates the task abnormally.

ENDFILE
• Occurs if an end-of-file condition is detected during a 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 READPREV command:
  • A READPREV command is issued for a file for which no previous STARTBR command has been successfully issued.
  • The KEYLENGTH option is specified, and the specified length differs from the length that is defined for the underlying file.
  • 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 READPREV 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 browse.
• An I/O error is any unusual event that is not covered by a CICS on Open Systems or CICS for Windows 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 provided, is unsuccessful.
• One place where this might occur is where the READPREV command immediately follows a STARTBR command that specifies the key of a record that does not exist on the file.
• 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 READPREV 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
• READNEXT
• 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