COBOL File I/O

COBOL file I/O is how your program reads from and writes to files (datasets on the mainframe or files elsewhere). You declare the file in the ENVIRONMENT and DATA divisions, open it in a mode that matches what you will do (read, write, or update), then use READ, WRITE, REWRITE, or DELETE as appropriate, and close the file when done. Every operation can set a file status code so your program can handle success, end-of-file, and errors. This page covers the basic flow: SELECT and FD, OPEN modes, READ and WRITE, REWRITE and DELETE, CLOSE, and file status.

Explain Like I'm Five: What Is File I/O?

File I/O is reading from and writing to a file. The file is like a list of records (lines) on disk. Before you can read or write, you "open" the file and say what you will do: only read, only write new stuff, or read and change. Then you read one record at a time (or write new ones). When you read, you might reach the end of the list—that is "end of file." When you are done, you "close" the file. The system also gives you a short code after each action (success, end of file, or error) so your program can decide what to do next.

Declaring the File: SELECT and FD

In the ENVIRONMENT DIVISION, FILE-CONTROL section, you use SELECT to associate a logical file name with an external file (ASSIGN) and optionally a file status data item. The file status item (e.g. PIC X(2)) is set after each I/O operation so you can check the result. In the DATA DIVISION, FILE SECTION, you define the file with an FD (file description) and the record layout(s) that describe each record. The record area is where the current record is read into or where you build a record before WRITE. Only one record format is "current" at a time for a given file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT CUST-FILE ASSIGN TO CUSTDS
               ORGANIZATION IS SEQUENTIAL
               FILE STATUS IS WS-FILE-STATUS.
 
       DATA DIVISION.
       FILE SECTION.
       FD  CUST-FILE.
       01  CUST-RECORD.
           05 CUST-ID    PIC 9(6).
           05 CUST-NAME  PIC X(30).
           05 CUST-AMT   PIC S9(7)V99.
 
       WORKING-STORAGE SECTION.
       01  WS-FILE-STATUS PIC X(2).

OPEN: Establishing Access

OPEN connects your program to the file and sets the mode. You must OPEN before any READ, WRITE, REWRITE, or DELETE. The mode determines what operations are allowed. OPEN INPUT is for reading only: you can only READ. OPEN OUTPUT creates a new file (or replaces an existing one) and allows only WRITE. OPEN I-O opens an existing file for both reading and updating: you can READ, then REWRITE the same record or DELETE it (for indexed files). OPEN EXTEND opens an existing file so you can only WRITE new records at the end (append). If you open a required file that does not exist (e.g. INPUT or I-O), you get a status such as 35 (file not found). If you open OUTPUT and the file exists, it is deleted and recreated empty.

1
2
3
4
5
6
7
8
9
       OPEN INPUT  CUST-FILE
       *> or: OPEN OUTPUT OUT-FILE
       *> or: OPEN I-O    MASTER-FILE
       *> or: OPEN EXTEND LOG-FILE
 
       IF WS-FILE-STATUS NOT = '00' AND WS-FILE-STATUS NOT = '05'
           DISPLAY 'OPEN failed ' WS-FILE-STATUS
           STOP RUN
       END-IF

READ: Retrieving Records

READ gets the next record (sequential) or a record by key (indexed/relative). For sequential files, READ advances through the file; each READ returns the next record. You use AT END (or check file status 10) to detect when there are no more records. For indexed or relative files, you can READ with a key to get a specific record, or READ NEXT to get the next in key order after a successful START or READ. After a successful READ, the record is in the FD record area. Always check file status (or AT END / INVALID KEY) before using the record; if status is not 00, the record area may be undefined.

1
2
3
4
5
6
7
8
9
10
11
12
       *> Sequential read loop
       PERFORM UNTIL WS-FILE-STATUS = '10'
           READ CUST-FILE
               AT END SET WS-EOF TO TRUE
               NOT AT END
                   PERFORM PROCESS-RECORD
           END-READ
           IF WS-FILE-STATUS NOT = '00' AND WS-FILE-STATUS NOT = '10'
               DISPLAY 'READ error ' WS-FILE-STATUS
               EXIT PERFORM
           END-IF
       END-PERFORM

WRITE and REWRITE

WRITE adds a new record. For sequential files, the record is written at the current position (next after the last write or at the start for OUTPUT). For indexed files, the record is inserted by key. Use WRITE for files opened OUTPUT or EXTEND. REWRITE replaces the last record that was read (or the record at the current key for indexed). You must have successfully read the record before REWRITE. Use REWRITE for files opened I-O when you have modified the record in the record area and want to write it back. For indexed files, DELETE removes the last record read (or the record at the current key). After REWRITE or DELETE, the record is no longer "current" until you read again.

1
2
3
4
5
6
7
8
9
10
11
12
13
       MOVE new-data TO CUST-RECORD
       WRITE CUST-RECORD
       IF WS-FILE-STATUS NOT = '00'
           DISPLAY 'WRITE error ' WS-FILE-STATUS
       END-IF
 
       *> Update: after READ, change and REWRITE
       READ CUST-FILE ...
       *> modify CUST-RECORD
       REWRITE CUST-RECORD
       IF WS-FILE-STATUS NOT = '00'
           DISPLAY 'REWRITE error ' WS-FILE-STATUS
       END-IF

CLOSE

CLOSE releases the file. You should CLOSE every file you opened before the program ends. After CLOSE, no further I/O is allowed on that file until you OPEN it again. If you do not CLOSE, the system may close it at program termination, but explicit CLOSE is good practice and ensures buffers are flushed. Check file status after CLOSE; 00 means success.

File Status Codes

The two-byte file status is set after every OPEN, READ, WRITE, REWRITE, DELETE, START, and CLOSE. The first byte is a category: 0 = success, 1 = AT END, 2 = invalid key, 3 = permanent error, 4 = logic error, 9 = implementer. The second byte gives detail. Common codes: 00 success, 10 end of file, 21 sequence error, 23 record not found, 30 permanent error, 35 file not found at OPEN. Always check file status after each operation and branch accordingly; do not assume success.

Sequential vs Indexed Files

Sequential files are read and written in physical order. You OPEN, then READ in a loop until AT END, or WRITE records one after another. Indexed files (and relative files) have keys: you can READ by key, START at a key, READ NEXT, REWRITE, and DELETE. The SELECT and FD must specify ORGANIZATION IS INDEXED (or RELATIVE) and the key(s). Invalid key conditions (duplicate key, record not found) set status 2x. For more detail, see the sequential-file-operations and file-organization tutorials.

Step-by-Step: Reading a Sequential File

1. Define the file in FILE-CONTROL with SELECT, ASSIGN, and FILE STATUS. Define the FD and record in the FILE SECTION.
2. OPEN INPUT the file. Check file status; if not 00 (or 05 for optional file), handle the error.
3. In a loop: READ the file. If status 10, exit the loop (end of file). If status 00, process the record. If another status, handle the error.
4. After the loop, CLOSE the file. Check status after CLOSE.

Step-by-Step: Writing and Updating with I-O

1. OPEN I-O the file (it must already exist). Check file status.
2. To update: READ the record (by key for indexed, or sequentially). If status 00, modify the record in the record area, then REWRITE. Check status after REWRITE.
3. To add: move data to the record area and WRITE (for EXTEND you would OPEN EXTEND and only WRITE).
4. CLOSE the file when done.

Best Practices

• Always specify FILE STATUS and check it after every file operation. Do not assume 00.
• Use the correct OPEN mode: INPUT for read-only, I-O for update, OUTPUT for new file, EXTEND for append.
• Only REWRITE or DELETE after a successful READ (or after START for indexed). Do not REWRITE without reading first.
• CLOSE all opened files before program end. Handle errors so you still CLOSE on error paths.

Test Your Knowledge