READPREV - IBM Mainframe

This command is used to read the previous record in a sequence. A series Of sequential READPREV commands on a file is known as a browse function. (READNEXT command can also be used as part of the browse function) The command is used repeatedly to read the records in reverse sequential order from a file on either a local or remote system.

The browse function must be started with me STARTBR command (which identifies the starting point in the file) and terminate with the ENDBR command. The RIDFLD option must be a data area that is large enough to hold a complete identifier (full key, RBA, or RRN) of records in the file. The command is valid for VSAM and CICS maintained data tables only. This data area can be used both as an output and as an input parameter. When used as an output parameter, after each READPREV command, CICS places the complete identifier of the record just retrieved into the RIDFLD data area, and retains the value to mark the point in the file for the next command in order to continue reading the file.

When it is used as an input parameter, CICS will allow the application program to modify the RIDFLD data area prior to executing the next read command. The effect of this allows for repositioning of the browse to a new starting point where the browse will continue in the usual way. If the GENERIC option is used then the RIDFLD value must also be generic. When the browse operation is started with the GTEQ option, then the next record returned will be the record with a key greater than or equal to the RIDFLD value.

This command is also used in browsing a CICS maintained data table. Access is to the source VSAM KSDS data set. A READPREV command followed by a READNEXT command will retrieve the same record as the one retrieved by the first READNEXT command. 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 data set; otherwise the NOTFND condition occurs for the READPREV command.

The syntax of the READPREV command is given below:

An example of the command is given below:

The various options of the READPREV command are explained below:

  • FILE (filename) - Contains the name of the user maintained file to be accessed. The FCT entry for the filename will determine where the location (local or remote) of the data set resides. However, when the SYSID option is used,. the location of the filename is assumed to exist on a remote system regardless of what the entry has defined in the FCT if one exist on the local system
  • INTO (data_area) - Identifies the data area where the record being retrieved from the file will be written.
  • KEYLENCTH (data_value) - Halfword binary length (PIC S9(4) COMP) returning the length of the key specified in the RIDFLD option. This option is invalid when RBA or RRN options specified. An INVREQ condition occurs when the key length specified is different from the key length of the file.
  • LENGTH (data_area) - Halfword binary field (PIC S9(4) COMP) containing the length of the data area where the record is to be stored. Upon command completion the LENGTH parameter will contain the actual length of the record. The option is required when using the SYSID option.

This option must also be specified with the INTO option on commands involving variable length records. This option is not needed for fixed length records, but its inclusion is recommended because:

An automatic check is made on the record being retrieved to check the record length against the available data area

LENGERR condition is triggered when reading fixed length records into the data area longer than the record being accessed, for VS COBOL II, PL/I, and assembler-language applications when the LENGTH option is not used. When the specified length exceeds the file record length then CICS will use the longer length for the move. When the target data area is not large enough in the application program then storage is overlaid beyond the target area.

Retrieving a record into a target data area that is larger that the record will produce unpredictable results with any data from the end of the retrieved record to the end of the target data area. When using the INTO option, the LENGTH option must be a data area that specifies the largest record the program accepts. When the retrieved record exceeds the LENGTH option value specified, the record is truncated to the specified LENGTH option value, the LENGERR condition occurs, and the LENGTH data area is set to the length of the record prior to truncation. When using the SET option, the LENGTH option is not required, but if it is used, then the argument must be a data area.

  • RBA - Option when used will identify the record identification field of the RIDFLD option as a relative byte address. This option is only used for reading records directly from an ESDS file, or when reading from a KSDS file and using relative byte addresses instead of keys to identify the records. This option is required for browsing an ESDS or KSDS file in which the STARTBR command specified the RBA option.
  • REQID (data_value) - Halfword binary field (PIC S9(4) COMP) containing the value of the unique request identifier for a browse, used in controlling multiple browse operations on a data set. The default for this option when used is zero.
  • RIDFLD (data_area) - Specifies the record identification field. The contents can be one of the following:
    1. A key
    2. A relative byte address, with a format that is a fullword binary integer (pic s9(8) comp) value that can be greater than or equal to zero
    3. A relative record number (for VSAM data sets), with a format that is a fullword binary integer (PIC S9(8) COMP) value that can be greater than or equal to one.

On completion of the READPREV command, the field is updated by CICS with the complete identification of the record retrieved.

  • RRN - Option indicates that the RIDFLD contains a relative record number in the record identification field. This option is required for a relative record data set.
  • SET(ptr_ref) - This option when used indicates that CICS will supply a buffer where the record is read, and sets the pointer reference to the address that is to contain the retrieved record. The pointer reference once set is only valid until the next READ command is issued for the same file. To retain the data in this buffered area, it should be moved to another area created by the application program before the pointer reference is changed. When coding in assembler language, if the DUPKEY condition occurs, the specified register has not been set, but can be loaded from DFHE1TP1. The pointer reference address can be above or below the 16MB line when DATALOCATION (ANY) is associated in RDO with the application program.

When the pointer reference address resides above the 16MB line, and the DATALOCATION (BELOW) is associated in RDO with the application program, then the data is copied below the 16MB line, and the address of this copy's new location is returned. When storage protection is active, and TASKDATAKEY (USER) is specified, the returned data is in user-key DSA.

  • SYSID (systemname) - Character field (4 bytes) specifying the name for the APPC connection where the request will be directed to. If this option is used and omit both RBA and RRN, then LENGTH and KEYBENGTH must be specified because these values cannot be found in the FCT entry.

Handle conditions are:

  • DUPKEY (VSAM only) - Set when a record is retrieved through an alternate index with the NONUNIQUEKEY attribute, and another alternate index record with the same key value is retrieved next. When coding in assembler language, if this condition occurs, the specified register has not been set, but can be loaded from DFHEITP1. The default action is the abnormal termination of the task.
  • ENDFILE - This is set when the end of file condition is detected during the browse operation. The default action is the abnormal termination of the task.
  • FILENOTFOUND - Set when a file name specified in the FILE option of the command cannot be located in the FCT. The default action is the abnormal termination of the task.
  • ILLOCIC (VSAM only) - Set when a VSAM error occurs that is not defined by one of the other CICS response categories. The default action is the abnormal termination of the task.
  • INVREQ - Occurs for any of the following reasons:
    1. READPREV command is executed without a successful STARTBR command being executed with the GENERIC option specified.
    2. KEYLENGTH option is used without the GENERIC option and the specified length is not equal to the length defined for the data set to which this file refers
    3. The record type (eg., key or relative byte address) used in accessing the data has been changed from one browse command to the next.
    4. READPREV command issued against a BDAM file.
    5. READPREV command is executed without a successful STARTBR command being executed.

The default action is the abnormal termination of the task.

  • IOERR - This is set when an I/O error occurs during the READ. An I/O error can be any unusual event not covered by an existing ClCS condition. For VSAM files, IOERR normally indicates a hardware error. The default action is the abnormal termination of the task.
  • ISCINVREQ - Set when the remote system indicates a failure that is not covered by an existing CICS condition. The default action is the abnormal termination of the task.
  • LENGERR - Occurs for any of the following reasons:
    1. Set when the command is missing the LENGTH or SET options on a file with variable length records
    2. Set when the retrieved record exceeds the LENGTH option value specified, the record is truncated to the specified LENGTH option value, and the LENGTH data area is set to the length of the record prior to truncation.
    3. Set when an incorrect length is specified for a file containing fixed length records.

The default action is the abnormal termination of the task.

  • NOTAUTH - Resource security check failure has occurred on FILE (filename). The default action is the abnormal termination of the task.
  • NOTFND - This is set when an unsuccessful attempt is made to retrieve a record based on the search argument provided. The default action is the abnormal termination of the task.
  • SYSIDERR - The SYSID specified cannot be found in the intersystem table, (defined in CICS by defining a CONNECTION), or if the link to the remote system is unavailable or closed. The default action is the abnormal termination of the task.

Browse Inefficiencies

Browse operations are inefficient because many records have to be read from a file. Limit browse by providing the ability to reset its starting key. Files, which are browsed frequently, should have a larger file-blocking factor in order to minimize the number of required file accesses. A browse against a file with a small blocking factor will be less efficient because of the greater number of accesses required.

Special Techniques for Sequential Read

There are some special techniques for sequential read, which are very useful in the actual programming. Some of them are Skip sequential read and changing browse direction.

In Skip sequential read, records will be skipped while continuing the browse operation established by the prior STARTBR command. For the READNEXT command, the new key for skipping must be in the forward direction form the current record. That is, while doing a READNEXT, a backward skipping is not possible. Similarly while doing a READPREV a forward skipping is not possible. Here what is actually done is instead of moving the length value into the LENGTH filed for the READNEXT/READPREV commands the key of the record to read, after skipping the necessary records, is moved into the RIDFLD. So the READNEXT/READPREV command will read the record with the specified key skipping the records in between.

In direction switching, the READNEXT and READPREV commands are used. That is after a series of READNEXT commands, if you want to change the direction of browse, then issue a READPREV command. But the first READPREV command will again fetch the previously fetched record.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM Mainframe Topics