READ Statement

The READ statement makes records available to the program from the program's data files.

Format 1

READ file-name  [NEXT    ] RECORD 
                [PREVIOUS]
                [BACKWARD]

          [ WITH [NO  ] LOCK ]
                 [KEPT]

          [ INTO dest ]

          [ ALLOWING UPDATERS ]

          [ AT END statement-1 ]

          [ NOT AT END statement-2 ]

          [ END-READ ]

Format 2

READ file-name RECORD 

     [ WITH [NO  ] LOCK ]
            [KEPT]

     [ INTO dest ]

     [ ALLOWING UPDATERS ]

     [ KEY IS key-name ]

     [ INVALID KEY statement-1 ]

     [ NOT INVALID KEY statement-2 ]
     
     [ END-READ ]

Syntax Rules

  1. file-name is the name of a file described in the Data Division. It may not be a sort file.
  2. dest is a data item.
  3. key-name is the name of a data item specified as a record key for file-name.
  4. statement-1 and statement-2 are imperative statements.
  5. Format 1 must be used for sequential access files.
  6. The KEY phrase can be used only for indexed files.
  7. dest may not occupy any of the storage area used by the record area of file-name.
  8. BACKWARD and PREVIOUS are equivalent.
  9. The NEXT or PREVIOUS phrase must be specified for a Format 1 READ for dynamic access mode files.
  10. The PREVIOUS phrase may not be specified for a sequential organization file.
  11. The word KEPT is treated as commentary.
  12. The LOCK, INTO and ALLOWING phrases may appear in any order.

General Rules

  1. The file referenced by a READ statement must be open in the INPUT or I-O mode when the statement executes.
  2. For sequential access mode files, if neither NEXT nor PREVIOUS is used, NEXT is implied.
  3. A successful READ statement causes the file's record area to be filled with the record retrieved from the file.
  4. If the record read is smaller than the record area, the excess characters are left unmodified unless the file has automatic trailing space removal specified. In this case, the record is padded with spaces.
  5. The READ statement updates the value of the associated FILE STATUS variable.
  6. A successful Format 1 READ statement retrieves a record from the file according to the following rules:
    1. The last OPEN, READ, or START verb used for the file determines which record is retrieved. Other file operations do not affect which record is retrieved.
    2. If an OPEN verb was the last verb to affect the file position, then the first record is retrieved if the NEXT phrase is used (or implied). If the PREVIOUS phrase is used, an end-of-file condition occurs.
    3. If the last verb to affect the file position was a successful START statement, then the record selected by that START statement is returned, regardless of whether the NEXT or PREVIOUS phrase was used.
    4. If the last verb to affect the file position was a successful READ statement, then the following or the preceding record is retrieved, depending on the NEXT or PREVIOUS phrase used.
    5. For sequential and relative files, the record ordering is based on the physical ordering of the records in the file (relative files are physically ordered by ascending record numbers).
    6. For indexed files, the record ordering is based on the logical ordering of the current Key of Reference. The Key of Reference is set by the last successful OPEN, READ, or START statement executed for the file.
  7. When a Format 1 READ statement executes, the preceding rule may indicate that no next logical record exists. When this happens, the following occurs:
    1. The at-end condition is set and the appropriate FILE STATUS is set.
    2. If the AT END phrase is specified, statement-1 executes. Control does not proceed to a USE AFTER EXCEPTION statement.
    3. If no AT END phrase is specified, but an appropriate USE AFTER EXCEPTION procedure exists, that procedure is executed with an implied return to the end of the READ statement.
    4. If neither case (b) nor (c) applies, then an error message is printed and the program halts.
  8. If the at-end condition does not occur, and no other exception causes the USE AFTER EXCEPTION procedure to execute, the NOT AT END phrase (if any) is used and statement-2 is executed.
  9. For a relative file, a Format 1 READ updates the contents of the file's RELATIVE KEY data item to reflect the record number of the returned record.
  10. When the program is sequentially accessing records from an indexed file that contains records with duplicated alternate key values, those records are returned in the same order in which they were created. These duplicate values can be created by WRITE or REWRITE statements. (These records may be reordered in the process of rebuilding the file on another key.)

    For sites using the RMS file system, please note that when a set of records having duplicate keys is encountered, RMS returns only the first record in the set.

  11. A Format 2 READ statement provides you with the ability to read records in random order by specifying appropriate key values. A Format 2 READ statement on a relative file retrieves the record whose record number is specified by the file's RELATIVE KEY data item.
  12. For indexed files, a Format 2 READ statement retrieves the record that contains the same key value as the corresponding data item in the file's record area. The key used is the one named in the KEY phrase of the READ statement. If no KEY phrase is used, the file's primary key is implied. The key used becomes the file's current Key of Reference for future Format 1 READ statements. For key values that are duplicated, the record that corresponds to the first of the sequence of duplicated values (as described in General Rule 10 above) is returned.
  13. After successfully retrieving a record, a Format 2 READ statement sets the file's File Position Indicator to the next logical record according to General Rule 6.
  14. If a Format 2 READ cannot find a record with the appropriate key value, the invalid-key condition exists. When this happens the following occurs:
    1. If the INVALID KEY phrase is specified, statement-1 executes. Control does not proceed to a USE AFTER EXCEPTION statement.
    2. If no INVALID KEY phrase is specified, but an appropriate USE AFTER EXCEPTION procedure exists, that procedure is executed with an implied return to the end of the READ statement.
    3. If neither case (a) nor (b) applies, then an error message is printed and the program halts.
  15. If the NOT INVALID KEY phrase is used and the invalid-key condition does not exist, and no other condition causes a USE AFTER EXCEPTION procedure to execute, statement-2 is executed.
  16. If an applicable USE AFTER EXCEPTION procedure exists, it executes whenever a condition occurs that results in a non-zero file status. However, it does not execute if the condition is invalid-key and an INVALID KEY phrase is used, or if the condition is at-end and an AT END phrase is used.
  17. If a READ statement is unsuccessful, the current file position and the current Key of Reference are both set to be undefined. See General Rules 22 and 23 for exceptions.
  18. The INTO phrase causes the contents of the file's record area to be moved to dest according to the rules of the MOVE statement. This move occurs after the record is retrieved, but only if the statement is successful.
  19. The WITH NO LOCK and ALLOWING UPDATERS phrases are equivalent. They both cause the record to be read without record locking. In the default mode, any successful READ on a file open in the I-O mode causes the retrieved record to be locked. A locked record may not be read (with lock) or updated by another program. Once locked, a record remains locked until any other I/O statement in the program that locked it is executed for the file. (An exception to this is files that hold multiple record locks--see File-Control Paragraph for details.) Once another I/O statement is executed for the file, the currently locked record becomes unlocked, even if the I/O is unsuccessful.
  20. The WITH NO LOCK and ALLOWING UPDATERS phrases are implied for a file open in the INPUT mode, and thus have no effect.
  21. For files with manual record locking mode the WITH NO LOCK phrase is implied. For such a file to place a record lock, it must specify WITH LOCK on the READ statement. See File-Control Paragraph for more information.
  22. Normally, a read that fails due to a record lock will return the appropriate FILE STATUS. In RM/COBOL compatibility mode, however, if the file has no applicable USE AFTER EXCEPTION procedure available, the program will wait until the record becomes unlocked. It will then read the record and proceed normally. Note that this can result in deadlock. This feature is provided for RM/COBOL compatibility. Because of the danger in using it, it is not recommended.
  23. The current Key of Reference and current file position are not modified by a record locked condition. This allows a program to wait an appropriate amount of time for the record to become unlocked and then try executing the same READ statement without having to re-establish the current file position. Because of the nature of RMS, this rule is not followed for a program running under the VMS operating system. In this case, the File Position Indicator is undefined.
  24. If the end of a file is reached by a READ NEXT statement, a subsequent READ PREVIOUS statement will return the last record in the file. Similarly, if the beginning of a file is reached by a READ PREVIOUS statement, a READ NEXT statement will retrieve the first record of the file.
  25. If the NEXT SENTENCE option is used, control passes to the next executable sentence. Note that the ANSI standard states that NEXT SENTENCE is an archaic feature and its use should be avoided.
  26. The IBM DOS/VS COBOL -Cv compatibility mode supports Reversed File Reads.
Parent topic: Procedure Division Statements