READNEXT - IBM Mainframe

This command is used to read the next record in a sequence. A series of sequential READNEXT commands on a file is known as a browse function. (READPREV command can also be used as part of the browse function) The command is used repeatedly to read the records in sequential order from a file on either a local or remote system. The browse function must be started with the 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 READNEXT 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 READPREV command. The syntax of the READNEXT command is given below

An example of the command is given below:

The explanation of the various options of the command is given 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. It is required when the GENERIC option is used, and also may be used whenever a key is specified. If KEYLENGTH (0) is used with the intent of starting the browse at the beginning of the file, then the GTEQ option is also required. If EQUAL is specified either explicitly or by default with KEYLENGTH (0), the results of the READ will be unpredictable. An INVREQ condition occurs with either of the following conditions (a) the length specified is different from the length defined for the data set and the operation is not generic or (b) GENERIC is specified and the KEYLENGTH is not less than that specified in the VSAM definition.
  • When performing a generic browse, CICS maintains the key length for the browse. (Key length is initialized to the value specified in the KEYLENGTH on the STARTBR command) The current key length can be modified by resetting the value on the next READNEXT or RESETBR command. Changing the value will cause the browse to reposition to the record where the key whose initial characters match he value specified in the RIDFLD for the current key length. KEYLENGTH (0) will always cause the browse operation to reposition back to the beginning of the file. When using the SYSID option on a generic browse, the full key length may be specified in order to be able to tell the function shipping transformers the key length, so that the CICS transformers can ship the key to the file-owning region. The following changes with the KEYLENGTH option will NOT cause the browse function to reposition on the next browse command executed.
  • KEYLENGTH option is omitted on a READNEXT command with the key length remaining unchanged
  • KEYLENGTH value specified on a READNEXT command is equal to the current key length
  • A generic browse command using the KEYLENGTH option with a value equal t6 the full key length
  • Another method for repositioning the browse is by modifying the RIDFLD option data area. For generic browse repositioning to work (by modifying the RIDLFD option data area) the current key length must also change in size. A consequence of this ability is that the repositioning will not work when the key length on the generic browse is zero.
  • 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:
    1. An automatic check is made on the record being retrieved to check the record length against the available data area.
    2. 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 than the record will produce unpredictable results with any data from the end of the retrieved record to the end of the target data area.
    3. 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.
    4. 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 (VSAM only) - 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) - Haifword 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 (dataarea) - 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.
    4. A block reference
    5. A physical key
    6. A deblocking argument (for BDAM data sets)

Results can be unpredictable for any of the following:

    1. If the variable specified by RIDFLD is shorter than the K.EYLENGTH specified in the command
    2. If KEYLENGTH is not specified, then the key length of the file being read must not be shorter than the RIDFLD variable specified in the command
    3. For GENERIC browse functions, this field must be large enough to contain a complete record identifier, because on completion of the READNEXT command, the field is updated by CICS with the complete identification of the record retrieved.
    4. RRN (VSAM only) - 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 is valid until the next READNEXT or READPREV command specifying SET for the same file. The pointer reference is invalid once the ENDBR or SYNCPOINT command is executed. 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 DFHEITP1. 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 copies new location is returned. When storage protection is active, and TASKDATAKEY(USER) is specified, the returned data is in user-key DSA.
  • SYSID (system name) - Character field (4 bytes) specifying the name for the APPC connection where the request will be directed to. If this option is used, and both RBA and RRN are omitted, then KEYLENGTH must be specified because it cannot be found in the FCT entry.

The handle conditions are:

  • DUPKEY (VSAM only) - This is 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. It will not occur when the READNEXT command that reads the last of the records has a non-unique key. 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 condition 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.
  • ILLOGIC (VSAM only) - ILLOGIC condition is 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. KEYLENGTH and GENERIC options are used and the length used with the KEYLENGTH option is greater than or equal to the length of a full key
    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. Exclusive control is not released by a REWRITE, UNLOCK, or DELETE command after a READ UPDATE command prior to another READ UPDATE command is issued
    4. READNEXT command is executed without a successful STARTBR command being executed.
    5. The record type (e.g., key or relative byte address) used in accessing the data has been changed from one browse command to the next. KEYLENGTH and GENERIC options are used and the length used with the KEYLENGTH option is less than or equal to zero.

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 CICS 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. When the command is missing the LENGTH or SET options on a file with variable length records or a BDAM file with undefined format records
    2. 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. 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 - Set when an unsuccessful attempt is made to retrieve a record based on the search argument provided. This might occur if the READNEXT command immediately follows a STARTBR command that specified the key of the last record in the data set (a complete key of X'FF's). 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.

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

IBM Mainframe Topics