READ CUSTOMER-FILE AT END ... END-READ retrieves the next logical record or runs the end-of-file branch. The file must already be open for INPUT or I-O, and the program must not use the record area after an unsuccessful read.
What the COBOL READ statement requires
The file name in a READ names an FD, not a record layout. Its SELECT entry defines the organization and access mode, while the FD defines the record area. Before the first read, issue OPEN INPUT when the program only reads the file or OPEN I-O when it can also update records.
The COBOL file operations guide covers the wider OPEN, READ, WRITE, REWRITE, and CLOSE lifecycle. This page concentrates on READ syntax and the branches a program must handle.
READ syntax by access pattern
| Access pattern | Typical form | Condition to handle |
|---|---|---|
| Sequential file | READ file [INTO target] AT END ... END-READ | AT END or status 10 |
| Indexed file, random access | READ file [INTO target] KEY IS key-name INVALID KEY ... END-READ | INVALID KEY, commonly status 23 when a record is not found |
| Indexed file, dynamic access | READ file NEXT RECORD [INTO target] AT END ... END-READ | AT END after positioning for sequential retrieval |
| Relative file, random access | Set the relative key, then READ file ... INVALID KEY ... END-READ | INVALID KEY; the READ does not use a KEY IS phrase |
NEXT is optional for a sequential file because sequential retrieval is already implied. It is required when a file opened with dynamic access is to retrieve the next record rather than perform a random read.
Sequential READ with an EOF loop
A safe loop initializes its own EOF switch, lets AT END set that switch, and processes the record only under NOT AT END.
When no next record exists, COBOL sets the file status before it runs the AT END statements. IBM also documents the record area as undefined after an unsuccessful READ. Keeping record processing inside NOT AT END prevents stale or unpredictable data from entering the next calculation.
For a longer example that reads and writes sequential records, see COBOL sequential file organization.
How READ INTO works
The INTO phrase adds an implicit move after a successful read. COBOL first makes the current record available in the file's record area and then moves it to the receiving item. If the read fails, that move does not occur.
READ INTO and process the working-storage copy. Mixing the two without a reason makes record changes harder to follow.Random READ for an indexed file
Random access to an indexed file compares the key of reference with the indexed key. Move the requested value to that key before issuing the read. If no matching record exists, COBOL runs the INVALID KEY branch and sets FILE STATUS.
An indexed file can define alternate record keys, so the selected key must match a key named for that file. The COBOL indexed-file guide covers primary keys, alternate keys, and duplicate-key rules.
Dynamic access: START and READ NEXT
Dynamic access allows random and sequential operations in the same run. A common pattern uses START to establish a position and then READ NEXT RECORD to walk forward in key sequence.
The sequence after START follows the key of reference. If an alternate key established the position, subsequent sequential reads use that key order until another operation changes the reference. See the COBOL START statement for its comparison conditions and positioning rules.
Random READ for a relative file
A relative file uses the data item named by the RELATIVE KEY clause. Set that relative record number before a random read. Unlike an indexed random read, the relative-file READ does not specify a KEY IS phrase.
The COBOL relative organization guide explains relative keys and record-number access in more detail.
FILE STATUS values to check after READ
A FILE STATUS data item is updated after every input/output operation. Declaratives and runtime settings can affect handling, but these common two-character values are a useful starting point.
| Status | Meaning in a READ path | Typical response |
|---|---|---|
00 | Successful completion | Process the record. |
04 | Successful read with a record-length condition under applicable rules | Check the FD, LRECL, record format, and compiler/runtime setting. |
10 | No next logical record; end of file | End the sequential loop. |
23 | Record not found or no record at the requested key | Handle the missing indexed or relative record. |
47 | READ attempted when the file is not open for INPUT or I-O | Correct the OPEN mode and control flow. |
Use the COBOL file status code reference when the status is not one of these common READ outcomes.
Which OPEN modes permit READ?
| OPEN mode | Can READ? | Purpose |
|---|---|---|
INPUT | Yes | Read existing records without updating them. |
I-O | Yes | Read existing records and permit supported update operations. |
OUTPUT | No | Create or replace output content. |
EXTEND | No | Add records at the end of a supported sequential file. |
Common READ mistakes
- Processing after AT END: the record area is undefined after an unsuccessful read.
- Omitting NEXT under dynamic access: a sequential retrieval from a dynamically accessed file needs
NEXT RECORD. - Using KEY IS for a relative file: set the declared relative-key item instead.
- Ignoring FILE STATUS:
INVALID KEYandAT ENDhandle branches, while the status supplies the diagnostic value. - Reading after OPEN OUTPUT: READ is allowed only after OPEN INPUT or OPEN I-O.
- Assuming READ INTO bypasses the FD area: a successful read still makes the current record available in the file's record area before the implicit move.
Official IBM references
- Enterprise COBOL READ statement
- READ in sequential access mode
- READ in random access mode
- FILE STATUS clause
- IBM READ statement notes
Frequently asked questions
What does the COBOL READ statement do?
READ retrieves one logical record from an open file. Sequential access gets the next record; random access gets the record identified by a key or relative record number.
What is the difference between READ and READ NEXT?
READ gets the next record automatically in sequential access mode. In dynamic access mode, READ with NEXT RECORD requests sequential retrieval from the current file position.
When should a COBOL program use AT END?
Use AT END for a sequential read when no next logical record exists. Do not process the record area after that unsuccessful read.
What does READ INTO do in COBOL?
READ INTO retrieves a record and then performs an implicit MOVE to the receiving data item. The move occurs only when the READ succeeds.
No comments:
Post a Comment