READ Statement

The READ statement retrieves records from files.

Format 1

A Format 1 READ is a Sequential READ, which retrieves the NEXT or PREVIOUS record, as determined by the current file pointer.

       READ file-1   {NEXT    } RECORD INTO data-1 
                     {PREVIOUS} 
                     [{IGNORING LOCK    }] 
                      {WITH LOCK        } 
                      {WITH NO LOCK     } 
                      {WITH IGNORE LOCK } 
                      {WITH WAIT        }
                      {WITH KEPT LOCK   } 
                     [ AT END statement-1 ] 
                     [ NOT AT END statement-2 ] 
                     [ END-READ ]

Syntax:

file-n is a file described in the File Section with an FD.
data-n is a data item.
key-name-n is a data element that has been named as a key for an indexed file.
statement-n is an imperative statement.

General Rules:

file-1 must be OPEN Input or I-O before the READ statement is executed.
The Format 1 READ statement applies to files declared with ACCESS MODE IS SEQUENTIAL or ACCESS MODE IS DYNAMIC.
A successful READ statement retrieves a record from an indexed, relative, or sequential file, and stores the record in the data area described in the File Description (FD) in the File Section of the program.
The NEXT and PREVIOUS phrases indicate in which direction the READ is to move the file pointer in the sequential READ operation.
The file pointer is initially placed at the beginning of the file after a successful OPEN statement.
In files described with ORGANIZATION IS SEQUENTIAL, a READ NEXT statement after an OPEN statement retrieves the first record in the file.
In files described with ORGANIZATION IS SEQUENTIAL, the READ NEXT and READ PREVIOUS statements retrieve the next/previous physical record in the file after/before the current position of the file pointer.
In files described with ORGANIZATION IS RELATIVE, the READ NEXT statement retrieves the next physical record in the file after the position marked by the RELATIVE KEY, and increments the relative-key data field. The READ PREVIOUS statement retrieves the previous physical record in the file after the position marked by the RELATIVE KEY and decrements the relative-key data field.
In files described with ORGANIZATION IS INDEXED, the READ NEXT and READ PREVIOUS statements retrieve the next/previous physical record in the file after/before the current position of the file pointer.
The file pointer may be placed anywhere in the file with the START statement. For details, see the START statement section.
The INTO phrase causes a MOVE to data-1 after the data has been retrieved in the record area of the File Description (FD).
The IGNORING LOCK phrase ignores locks held by other programs.
IGNORING LOCK and WITH IGNORE LOCK are synonyms.
The WITH LOCK phrase causes the record to be locked. A locked record cannot be READ WITH LOCK or updated by another program.
WITH LOCK and WITH KEPT LOCK are synonyms.
The WITH NO LOCK phrase allows access to the record by other programs.
The WITH IGNORE LOCK phrase ignores locks held by other programs.
The WITH WAIT phrase causes the READ statement to wait for a lock held on record to be released.
The AT END condition is triggered when the end of the file is reached in a sequence of READ NEXT statements, or when the beginning of the file is reached in a sequence of READ PREVIOUS statements.
If the AT END condition is triggered, and the AT END phrase is included in the READ statement, the FILE STATUS variable is set to “10”, the statement-list within the scope of the AT END phrase is executed, and control is then passed to the next statement after the READ.
The NOT AT END condition is triggered when the sequential READ is successful. When the NOT AT END phrase is included in the READ statement, and the READ is successful, the statement-list within the scope of the NOT AT END phrase is executed, and control is then passed to the next statement after the READ.

Format 2

A Format 2 READ is a KEY’ed READ, which READ's on the relative key of a relative file, or one of the record keys of an indexed file.

       READ file-1   RECORD INTO data-1 
                     [{IGNORING LOCK    }] 
                      {WITH LOCK        } 
                      {WITH NO LOCK     } 
                      {WITH IGNORE LOCK } 
                      {WITH WAIT        } 
                      {WITH KEPT LOCK   } 
                      [ KEY IS { data-2 } ] 
                               { key-name-1 } ] 
                      [ INVALID KEY statement-3 ] 
                      [ NOT INVALID KEY statement-4 ] 
                      [ END-READ ]

Syntax:

file-n is a file described in the File Section with an FD.
data-n is a data item.
key-name-n is a data element that has been named as a key for an indexed file.
statement-n is an imperative statement.

General Rules:

file-1 must be OPEN Input or I-O before the READ statement is executed.
The Format 2 READ statement applies to files declared with ACCESS MODE IS RANDOM or ACCESS MODE IS DYNAMIC.
The INTO phrase causes a MOVE to data-1 after the data has been retrieved in the record area of the File Description (FD).
The KEY clause is optional.
If the KEY clause is not present, then:
- In relative files, the value of the relative key field is used as the key.
- In indexed files, the current value of the primary key stored in the record in the File Section is used as the key.
The KEY clause, when used, references keys as follows:
- In relative files, the value of the data field referenced is used as the relative key.
- In indexed files, the data field referenced must identify either the primary key or one of the alternate record keys.
A successful READ statement retrieves a record from an indexed, or relative file, and stores the record in the data area described in the File Description (FD) in the File Section of the program.
When a READ statement is made using an alternate key that allows duplicates, the first record that matches the given key is retrieved.
The INTO phrase causes a MOVE to data-1 after the data has been retrieved in the record area of the File Description (FD).
The WITH LOCK phrase causes the record to be locked. A locked record cannot be READ WITH LOCK or updated by another program.
WITH LOCK and WITH KEPT LOCK are synonyms.
The IGNORING LOCK phrase ignores locks held by other programs.
IGNORING LOCK and WITH IGNORE LOCK are synonyms.
The WITH NO LOCK phrase allows access to the record by other programs.
The WITH WAIT phrase causes the READ statement to wait for a lock held on record to be released.
The INVALID KEY condition is triggered in a READ on a relative file when a RELATIVE KEY data field does not contain a positive integer value.
The INVALID KEY condition is triggered in a READ on an indexed file when the RECORD KEY is not found.
When the INVALID KEY condition is triggered, and the INVALID KEY clause is included in the READ statement, the FILE STATUS variable is set to “23”, the statement-list within the scope of the INVALID KEY phrase is executed, and control is then passed to the next statement after the READ.
The NOT INVALID KEY condition is triggered when the READ is successful. When the NOT INVALID KEY phrase is included in the READ statement, and the READ is successful, the statement-list within the scope of the NOT INVALID KEY phrase is executed, and control is then passed to the next statement after the READ.
The READ statement updates the FILE STATUS variable.
If a READ statement is unsuccessful, the file pointer is undefined.

Code Sample:

       ... 
                     SELECT SEQ-FILE-1 ASSIGNTO"SEQ-FILE-1" 
                     ORGANIZATION IS SEQUENTIAL 
                     ACCESS IS SEQUENTIAL 
                     FILE STATUS IS SEQ-FILE-1-STAT. 
       ... 
              FD SEQ-FILE-1. 
              01 SEQ-FILE-1-RECORD PIC X(10). 
       ... 
              77 SEQ-FILE-1-STATPIC XX. 
              01 WS-SEQ-FILEPIC X(10). 
       ... 
                     READ SEQ-FILE-1 NEXT RECORD. 
                     READ SEQ-FILE-1 NEXT RECORD INTO WS-SEQ-FILE. 
                     READ SEQ-FILE-1 NEXT RECORD IGNORING LOCK. 
                     READ SEQ-FILE-1 NEXT RECORD WITH LOCK.
                     READ SEQ-FILE-1 NEXT RECORD WITH NO LOCK. 
                     READ SEQ-FILE-1 NEXT RECORD WITH IGNORE LOCK. 
                     READ SEQ-FILE-1 NEXT RECORD WITH WAIT. 
                     READ SEQ-FILE-1 NEXT RECORD WITH KEPT LOCK. 
                     READ SEQ-FILE-1 NEXT RECORD 
                            AT END MOVE "10" TO SEQ-FILE-1-STAT 
                            NOT AT END 
                                   CONTINUE 
                     END-READ. 

                     SELECT IDX-FILE-1 ASSIGN TO "IDX-FILE-1" 
                     ORGANIZATION IS INDEXED 
                     ACCESS IS DYNAMIC 
                     RECORD KEY IS IDX-KEY 
                     FILE STATUS IS IDX-FILE-1-STAT. 

              FD IDX-FILE-1. 
              01 IDX-FILE-1-RECORD. 
                     03 IDX-KEY PIC X(10). 

              77 IDX-FILE-1-STAT PIC XX. 
              01 WS-IDX-FILE PIC X(10). 

      ... 
                     READ IDX-FILE-1 NEXT RECORD. 
                     READ IDX-FILE-1 NEXT RECORD INTO WS-IDX-FILE. 
                     READ IDX-FILE-1 PREVIOUS RECORD. 
                     READ IDX-FILE-1 IGNORING LOCK. 
                     READ IDX-FILE-1 WITH LOCK. 
                     READ IDX-FILE-1 WITH NOLOCK. 
                     READ IDX-FILE-1 WITH IGNORE LOCK. 
                     READ IDX-FILE-1 WITH WAIT. 
                     READ IDX-FILE-1 WITH KEPT LOCK. 
                     READ IDX-FILE-1 
                            INVALID KEY MOVE "23" TO IDX-FILE-1-STAT 
                            NOT INVALID KEY 
                                   CONTINUE 
                     END-READ.