READ - IBM Mainframe

This is the command, which reads a record into a record area defined in the Working storage. If the read is successful then the contents of the record will be available in the working storage. The syntax of the READ command is given below:

The options of the READ command are:

  • EQUAL (VSAM oVily) - Search will only be satisfied when a record containing the same key (complete or generic) as the one specified in the RIDFLD (Record Identification Field) option.
  • FILE (filename) - Contains the name of the 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 exists on the local system.
  • GENERIC (VSAM only) - The search, key contains a generic key with the length value being specified in the KEYLENGTH option. The search condition is satisfied when a record is found that contains the same starting characters from the generic key used. This option should only be used on a KSDS VSAM file or a path over either a KSDS or an ESDS.
  • GTEQ (VSAM only) - When searching for a record with the same key (complete or generic) specified in the RIDFLD option, if the search is unsuccessful, then the next record having a greater key is retrieved. This option should only be used on a KSDS VSAM file or a path over either a KSDS or an ESDS.
  • INTO (data_area) - Identifies the data area where the record being retrieved from the data set will be written.
  • KEYLENGTH (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 reading the first record in 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 1NVREQ condition occurs with either of the following conditions:
    1. The length specified is different from the length defined for the data set and the operation is not generic
    2. GENERIC is specified and the KEYLENGTH is not less than that specified in the VSAM definition
  • 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. This option must also be specified with the INTO option on READ 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/1, 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.
  • INTO (dataarea) - 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 (VSAM only) - Option when used will identify the record identification field of the R1DFLD 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.
  • RRN (VSAM only) - Option indicates that the R1DFLD 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, or until completion of a corresponding REWRITE, DELETE, or UNLOCK command, or a SYNCPOINT in the case of READ UPDATE SET. 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.
    1. When coding in assembler language, if the DUPKEY condition occurs, the specified register has not been set, but can be loaded from DFHEITP1. When SET is not used, the LENGTH option must either be specified explicitly or must be capable of being defaulted from the INTO option using the length attribute reference in assembler language, or STG and CSTG in PL/I. LENGTH must be specified explicitly in OS/VS COBOL or C/370. The pointer reference address can be above or below the 16MB line when DATALOCATION (ANY) is associated in RDO with the application program.
    2. 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.fhe 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.
  • UPDATE - Option is used to indicate that the record will be obtained for updating or deletion (VSAM only). The record is obtained as read only when this option is omitted. When this option is specified the record is moved into the working storage with intention of updating or deleting the record. The fields to be updated will have new data moved into the working storage of the record to be changed before the record is rewritten with the REWRITE command. A record READ FOR UPDATE should be read as close to the UPDATE command as possible in order to prevent file lockout of other tasks. If it is determined that the record will not be rewritten, issue an UNLOCK command as soon as possible so that the exclusive control on the record is released. Given below is an example of the READ command:

The handle conditions for the READ command are:

  • DISABLED - This can occur if the READ command was initially defined as disabled and has not
  • since been enabled or if an EXEC CICS SET FILE or a CEMT SET FILE command has disabled it.
  • The default action is the abnormal termination of the task.
  • DUPKEY (VSAM only) - This condition 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. 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.
  • FILENOTFOUND - This is 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) - ILLOGIC is set when a VSAM error occurs that is not defined by one or the other CICS response categories. Default action is the abnormal termination of the task.
  • INVREQ - Occurs for any of the following reasons:
    1. READ is not permitted per the FCT entry definition or READ with UPDATE option is not permitted per the FCT entry definition.
    2. 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
    3. 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
    4. 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
    5. A BDAM key conversion occurred
    6. KEYLENGTH and GENERIC options are used and the length used with the KEYLENGTH option is less than or equal to zero.
  • The default action of INVREQ is the abnormal termination of the task. IOERR - IOERR 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 - This is 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.
  • LENCERR - Occurs for any of the following reasons:
    1. When the LENGTH and SET options are omitted on the command for a file with variable length records or for a BDAM file with variable length or undefined format records
    2. When a record length read with the INTO option used exceeds the LENGTH option value specified. The record will be truncated, and the LENGTH option value for the data area is set to the actual length of the record
    3. When the length Is specified incorrectly for a file with 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 task termination.
  • NOTFND - When an unsuccessful attempt is made to retrieve a record based on the search argument provided. The default action is abnormal task termination.
  • NOTOPEN - This is set for a/iy one of the following conditions that may occur:
    1. The requested file is in a CLOSED and UNENABLED state. This condition occurs after a CLOSE request has been received against an OPEN ENABLED file and the file is no longer in use. The CLOSED UNENABLED state can also be set by specifying the initial state of the FILSTAT parameter (TYPE=FILE) of the FCT, or by defining the RDO options for the file definition as STATUS=UNENABLED and OPENTIME=FIRSTREF.
    2. The requested file is in use by other transactions with an OPEN status but a CLOSE request against the file has been received. This error does not occur when the request is made to a file that has a status of either CLOSED ENABLED or CLOSED DISABLED. The CLOSED ENABLED condition when encountered from this command will cause the file to open as part of executing the request. When the CLOSED DISABLED condition is encountered the DISABLED condition is set as a result of executing this command.
  • The default action is abnormal task termination.
  • 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 abnormal task termination.


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

IBM Mainframe Topics