Enterprise COBOL for z/OS, V4.2, Language Reference

READ statement

For sequential access, the READ statement makes the next logical record from a file available to the object program. For random access, the READ statement makes a specified record from a direct-access file available to the object program.

When the READ statement is executed, the associated file must be open in INPUT or I-O mode.

Read syntax diagramSkip visual syntax diagram
Format 1: READ statement for sequential retrieval

>>-READ--file-name-1--+------+--+--------+---------------------->
                      '-NEXT-'  '-RECORD-'   

>--+--------------------+--------------------------------------->
   '-INTO--identifier-1-'   

>--+-------------------------------------+---------------------->
   '-+----+--END--imperative-statement-1-'   
     '-AT-'                                  

>--+------------------------------------------+--+----------+--><
   '-NOT--+----+--END--imperative-statement-2-'  '-END-READ-'   
          '-AT-'                                                

Read syntax diagramSkip visual syntax diagram
Format 2: READ statement for random retrieval

>>-READ--file-name-1--+--------+--+--------------------+-------->
                      '-RECORD-'  '-INTO--identifier-1-'   

>--+--------------------------+--------------------------------->
   '-KEY--+----+--data-name-1-'   
          '-IS-'                  

>--+------------------------------------------+----------------->
   '-INVALID--+-----+--imperative-statement-3-'   
              '-KEY-'                             

>--+----------------------------------------------+------------->
   '-NOT INVALID--+-----+--imperative-statement-4-'   
                  '-KEY-'                             

>--+----------+------------------------------------------------><
   '-END-READ-'   

file-name-1
Must be defined in a data division FD entry.
NEXT RECORD
Reads the next record in the logical sequence of records. NEXT is optional when the access mode is sequential, and has no effect on READ statement execution.

You must specify the NEXT RECORD phrase to retrieve records sequentially from files in dynamic access mode.

INTO identifier-1
identifier-1 is the receiving field.

identifier-1 must be a valid receiving field for the selected sending record description entry in accordance with the rules of the MOVE statement.

The record areas associated with file-name-1 and identifier-1 must not be the same storage area.

When there is only one record description associated with file-name-1 or all the records and the data item referenced by identifier-1 describe an elementary alphanumeric item or an alphanumeric group item, the result of the execution of a READ statement with the INTO phrase is equivalent to the application of the following rules in the order specified:

  • The execution of the same READ statement without the INTO phrase.
  • The current record is moved from the record area to the area specified by identifier-1 according to the rules for the MOVE statement without the CORRESPONDING phrase. The size of the current record is determined by rules specified for the RECORD clause. If the file description entry contains a RECORD IS VARYING clause, the implied move is a group move. The implied MOVE statement does not occur if the execution of the READ statement was unsuccessful. Any subscripting or reference modification associated with identifier-1 is evaluated after the record has been read and immediately before it is moved to the data item. The record is available in both the record area and the data item referenced by identifier-1.

    If identifier-1 is a date field, then the implied MOVE statement is performed according to the behavior described under Moves involving date fields.

When there are multiple record descriptions associated with file-name-1 and they do not all describe an alphanumeric group item or elementary alphanumeric item, the following rules apply:

  1. If the file referenced by file-name-1 is described as containing variable-length records, or as a QSAM file with RECORDING MODE 'S' or 'U', a group move will take place.
  2. If the file referenced by file-name-1 is described as containing fixed-length records, a move will take place according to the rules for a MOVE statement using, as a sending field description, the record that specifies the largest number of character positions. If more than one such record exists, the sending field record selected will be the one among those records that appears first under the description of file-name-1.

KEY IS phrase

The KEY IS phrase can be specified only for indexed files. data-name-1 must identify a record key associated with file-name-1. data-name-1 can be qualified; it cannot be subscripted.

AT END phrases

For sequential access, both the AT END phrase and an applicable EXCEPTION/ERROR procedure can be omitted.

For information about at-end condition processing, see AT END condition.

INVALID KEY phrases

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure can be omitted.

For information about INVALID KEY phrase processing, see Invalid key condition.

END-READ phrase

This explicit scope terminator serves to delimit the scope of the READ statement. END-READ permits a conditional READ statement to be nested in another conditional statement. END-READ can also be used with an imperative READ statement. For more information, see Delimited scope statements.

Multiple record processing

If more than one record description entry is associated with file-name-1, those records automatically share the same storage area; that is, they are implicitly redefined. After a READ statement is executed, only those data items within the range of the current record are replaced; data items stored beyond that range are undefined. The following figure illustrates this concept. If the range of the current record exceeds the record description entries for file-name-1, the record is truncated on the right to the maximum size. In either of these cases, the READ statement is successful and the I-O status is set to 04 indicating a record length conflict has occurred.

This figure shows 2 record areas of different sizes in an FD. When a shorter record is read, the content of the remaining record area is undefined.

Sequential access mode

Format 1 must be used for all files in sequential access mode.

Execution of a format-1 READ statement retrieves the next logical record from the file. The next record accessed is determined by the file organization.

Sequential files

The NEXT RECORD is the next record in a logical sequence of records. The NEXT phrase need not be specified; it has no effect on READ statement execution.

If SELECT OPTIONAL is specified in the file-control entry for this file, and the file is unavailable during this execution of the object program, execution of the first READ statement causes an at-end condition; however, since no file is available, the system-defined end-of-file processing is not performed.

AT END condition

If the file position indicator indicates that no next logical record exists, or that an optional input file is not available, the following occurs in the order specified:

  1. A value derived from the setting of the file position indicator is placed into the I-O status associated with file-name-1 to indicate the at-end condition.
  2. If the AT END phrase is specified in the statement causing the condition, control is transferred to imperative-statement-1 in the AT END phrase. Any USE AFTER STANDARD EXCEPTION procedure associated with file-name-1 is not executed.
  3. If the AT END phrase is not specified and an applicable USE AFTER STANDARD EXCEPTION procedure exists, the procedure is executed. Return from that procedure is to the next executable statement following the end of the READ statement.

    Both the AT END phrase and an applicable EXCEPTION/ERROR procedure can be omitted.

    When the at-end condition occurs, execution of the READ statement is unsuccessful. The contents of the associated record area are undefined and the file position indicator is set to indicate that no valid next record has been established.

    For QSAM files, attempts to access or move data into the record area after an unsuccessful read can result in a protection exception.

If an at-end condition does not occur during the execution of a READ statement, the AT END phrase is ignored, if specified, and the following actions occur:

  1. The file position indicator is set and the I-O status associated with file-name-1 is updated.
  2. If an exception condition that is not an at-end condition exists, control is transferred to the end of the READ statement after the execution of any USE AFTER STANDARD EXCEPTION procedure applicable to file-name-1.

    If no USE AFTER STANDARD EXCEPTION procedure is specified, control is transferred to the end of the READ statement or to imperative-statement-2, if specified.

  3. If no exception condition exists, the record is made available in the record area and any implicit move resulting from the presence of an INTO phrase is executed. Control is transferred to the end of the READ statement or to imperative-statement-2, if specified. In the latter case, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement which causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the READ statement.

After the unsuccessful execution of a READ statement, the contents of the associated record area are undefined and the file position indicator is set to indicate that no valid next record has been established. Attempts to access or move data into the record area after an unsuccessful read can result in a protection exception.

Multivolume QSAM files

If end-of-volume is recognized during execution of a READ statement, and logical end-of-file has not been reached, the following actions are taken:

  • The standard ending volume label procedure is executed.
  • A volume switch occurs.
  • The standard beginning volume label procedure is executed.
  • The first data record of the next volume is made available.

Indexed or relative files

The NEXT RECORD is the next logical record in the key sequence.

For indexed files, the key sequence is the sequence of ascending values of the current key of reference. For relative files, the key sequence is the sequence of ascending values of relative record numbers for records that exist in the file.

Before the READ statement is executed, the file position indicator must have been set by a successful OPEN, START, or READ statement. When the READ statement is executed, the record indicated by the file position indicator is made available if it is still accessible through the path indicated by the file position indicator.

If the record is no longer accessible (because it has been deleted, for example), the file position indicator is updated to point to the next existing record in the file, and that record is made available.

For files in sequential access mode, the NEXT phrase need not be specified.

For files in dynamic access mode, the NEXT phrase must be specified for sequential record retrieval.

AT END condition

This condition exists when the file position indicator indicates that no next logical record exists or that an optional input file is not available. The same procedure occurs as for sequential files (see AT END condition).

If neither an at-end nor an invalid key condition occurs during the execution of a READ statement, the AT END or the INVALID KEY phrase is ignored, if specified. The same actions occur as when the at-end condition does not occur with sequential files (see AT END condition).

Sequentially accessed indexed files

When an ALTERNATE RECORD KEY with DUPLICATES is the key of reference, file records with duplicate key values are made available in the order in which they were placed in the file.

Sequentially accessed relative files

If the RELATIVE KEY clause is specified for this file, READ statement execution updates the RELATIVE KEY data item to indicate the relative record number of the record being made available.

Random access mode

Format 2 must be specified for indexed and relative files in random access mode, and also for files in the dynamic access mode when record retrieval is random.

Execution of the READ statement depends on the file organization, as explained in the following sections.

Indexed files

Execution of a format-2 READ statement causes the value of the key of reference to be compared with the value of the corresponding key data item in the file records, until the first record having an equal value is found. The file position indicator is positioned to this record, which is then made available. If no record can be so identified, an INVALID KEY condition exists, and READ statement execution is unsuccessful. (See Invalid key condition for details of the invalid key condition.)

If the KEY phrase is not specified, the prime RECORD KEY becomes the key of reference for this request. When dynamic access is specified, the prime RECORD KEY is also used as the key of reference for subsequent executions of sequential READ statements, until a different key of reference is established.

When the KEY phrase is specified, data-name-1 becomes the key of reference for this request. When dynamic access is specified, this key of reference is used for subsequent executions of sequential READ statements, until a different key of reference is established.

Relative files

Execution of a format-2 READ statement sets the file position indicator pointer to the record whose relative record number is contained in the RELATIVE KEY data item, and makes that record available.

If the file does not contain such a record, the INVALID KEY condition exists, and READ statement execution is unsuccessful. (See Invalid key condition for details of the invalid key condition).

The KEY phrase must not be specified for relative files.

Dynamic access mode

For files with indexed or relative organization, dynamic access mode can be specified in the file-control entry. In dynamic access mode, either sequential or random record retrieval can be used, depending on the format used.

Format 1 with the NEXT phrase must be specified for sequential retrieval. All other rules for sequential access apply.

READ statement notes:

  • If the FILE-STATUS clause is specified in the file-control entry, the associated file status key is updated when the READ statement is executed.
  • After unsuccessful READ statement execution, the contents of the associated record area and the value of the file position indicator are undefined. Attempts to access or move data into the record area after an unsuccessful read can result in a protection exception.


Rate this page

[ Index | Table of contents ]