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.

Format 1: READ statement for sequential retrieval

Read syntax diagramSkip visual syntax diagramREADfile-name-1NEXTRECORDINTOidentifier-1ATENDimperative-statement-1NOTATENDimperative-statement-2END-READ

Format 2: READ statement for random retrieval

Read syntax diagramSkip visual syntax diagramREADfile-name-1RECORDINTOidentifier-1KEYISdata-name-1INVALIDKEYimperative-statement-3NOT INVALIDKEYimperative-statement-4END-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.

    Start of changeidentifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.End of change

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.