FILE STATUS
Every file statement leaves a two-character code in the field named by FILE STATUS. The code is the only report a program gets: no exception is thrown, no message is printed, and the next statement runs whatever the last one did. This lesson collects the codes this compiler really returned on this machine.
The codes of a read
One file, opened and closed several times, with the status printed after every verb:
IDENTIFICATION DIVISION.
PROGRAM-ID. CODES.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT DAT-F ASSIGN TO "status.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-STATUS.
DATA DIVISION.
FILE SECTION.
FD DAT-F.
01 DAT-REC PIC X(6).
WORKING-STORAGE SECTION.
01 WS-STATUS PIC XX.
PROCEDURE DIVISION.
OPEN INPUT DAT-F.
DISPLAY "open input, missing " WS-STATUS.
OPEN OUTPUT DAT-F.
DISPLAY "open output " WS-STATUS.
MOVE "AAAA" TO DAT-REC.
WRITE DAT-REC.
CLOSE DAT-F.
DISPLAY "close " WS-STATUS.
OPEN INPUT DAT-F.
DISPLAY "open input " WS-STATUS.
READ DAT-F
AT END CONTINUE
NOT AT END CONTINUE
END-READ.
DISPLAY "read " WS-STATUS.
READ DAT-F
AT END CONTINUE
NOT AT END CONTINUE
END-READ.
DISPLAY "read at end " WS-STATUS.
READ DAT-F
AT END CONTINUE
NOT AT END CONTINUE
END-READ.
DISPLAY "read after end " WS-STATUS.
WRITE DAT-REC.
DISPLAY "write on input " WS-STATUS.
CLOSE DAT-F.
DISPLAY "close " WS-STATUS.
READ DAT-F
AT END CONTINUE
NOT AT END CONTINUE
END-READ.
DISPLAY "read after close " WS-STATUS.
CLOSE DAT-F.
DISPLAY "close again " WS-STATUS.
STOP RUN.
cobc -x -free -Wall -o codes codes.cob
./codes
open input, missing 35
open output 00
close 00
open input 00
read 00
read at end 10
read after end 46
write on input 48
close 00
read after close 47
close again 42
A verb in the wrong mode
48 came from the write to a file opened for input, 47 from the read after the close, and 42 from the second close. All three are "not now": the verb is legal in the language and not in the state the file is in. A program that prints the status after the verb has a line to read; a program that does not has a report that silently lost a record.
46 is the read after the end of the file: the file is still open for input and the read is not allowed because the previous one reached the end. It is the reason a loop exits on 10 and never asks for another record.
A file that is not there
35 is the first line of the run: an OPEN INPUT of a file that does not exist. The open failed, the file stayed closed, and the program went on to create the same file with OPEN OUTPUT, which returned 00. A program that treats 35 as "empty input" reads nonsense; a program that tests the status before the first read does not.
Duplicate keys and missing records
Two more codes need an indexed file, and the next lesson is about that organisation. Here the point is only the code: a write of a key that is already in the file, and a read of a key that is not:
IDENTIFICATION DIVISION.
PROGRAM-ID. ICODES.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CUS-F ASSIGN TO "cus.idx"
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS CUS-ID
FILE STATUS IS WS-STATUS.
DATA DIVISION.
FILE SECTION.
FD CUS-F.
01 CUS-REC.
05 CUS-ID PIC X(3).
WORKING-STORAGE SECTION.
01 WS-STATUS PIC XX.
PROCEDURE DIVISION.
OPEN OUTPUT CUS-F.
DISPLAY "open output " WS-STATUS.
MOVE "A10" TO CUS-ID.
WRITE CUS-REC.
DISPLAY "write A10 " WS-STATUS.
MOVE "A10" TO CUS-ID.
WRITE CUS-REC.
DISPLAY "write A10 again " WS-STATUS.
CLOSE CUS-F.
OPEN INPUT CUS-F.
DISPLAY "open input " WS-STATUS.
MOVE "B20" TO CUS-ID.
READ CUS-F
INVALID KEY DISPLAY "read B20 invalid key " WS-STATUS
NOT INVALID KEY DISPLAY "read B20 ok"
END-READ.
MOVE "A10" TO CUS-ID.
READ CUS-F
INVALID KEY DISPLAY "read A10 invalid key"
NOT INVALID KEY DISPLAY "read A10 ok " WS-STATUS
END-READ.
CLOSE CUS-F.
STOP RUN.
cobc -x -free -Wall -o icodes icodes.cob
./icodes
open output 00
write A10 00
write A10 again 22
open input 00
read B20 invalid key 23
read A10 ok 00
The table
Every code below was printed by one of the two runs on this page:
| Code | Meaning | Where it came from |
|---|---|---|
| 00 | success | every open, the read, the close |
| 10 | end of file | the read after the only record |
| 22 | duplicate key | the second write of A10 |
| 23 | record not found | the read of B20 |
| 35 | file not found | the input open before the file existed |
| 42 | close of a file that is not open | the second close |
| 46 | read after the end of the file | the read after the end |
| 47 | read of a file that is not open for input | the read after the close |
| 48 | write to a file that is not open for output | the write on the input file |
A program that checks the status after every verb and treats anything except 00 and 10 as an error is a program whose failures are visible. The codes are the same on every platform for the first digit, and a program that prints the two characters rather than a message of its own is a program a support engineer can read.
The next lesson uses the indexed file for what it is good at: reading a record by its key, rewriting it and deleting it, with the same status check after every statement.
Exercises
- Add a REWRITE to the input file of the first program and print the status. Which code comes back?
- Open the indexed file with OPEN I-O and read B20 again. Is the code the same as with OPEN INPUT?
- Print the status after a START with a key below the first record. Which code comes back?
- Write a paragraph that takes a status and prints a sentence for 00, 10 and everything else, and use it after every verb of the first program.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Where does a program read the result of a file operation?
Answer
In the field named by FILE STATUS, after every verb
The two characters in WS-STATUS are the only report the language gives.
-
Which code is the end of the file?
Answer
10
The read after the last record left 10 in the status and took the AT END branch.
-
Which code is a duplicate key on a write?
Answer
22
The second write of A10 to the indexed file printed 22.
-
Which code is a record the key does not find?
Answer
23
The read of B20 took the INVALID KEY branch and left 23.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT F-A ASSIGN TO "q5.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS W-S. DATA DIVISION. FILE SECTION. FD F-A. 01 R-A PIC X(2). WORKING-STORAGE SECTION. 01 W-S PIC XX. PROCEDURE DIVISION. OPEN INPUT F-A. DISPLAY W-S. STOP RUN.Answer
35
The file does not exist in the run, so the open fails with the not-found code.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT F-A ASSIGN TO "q6.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS W-S. DATA DIVISION. FILE SECTION. FD F-A. 01 R-A PIC X(2). WORKING-STORAGE SECTION. 01 W-S PIC XX. PROCEDURE DIVISION. OPEN OUTPUT F-A. MOVE "AA" TO R-A. WRITE R-A. CLOSE F-A. OPEN INPUT F-A. READ F-A AT END CONTINUE NOT AT END CONTINUE END-READ. READ F-A AT END CONTINUE NOT AT END CONTINUE END-READ. DISPLAY W-S. CLOSE F-A. STOP RUN.Answer
10
The second read reaches the end of a one-record file and leaves the end code.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 S-F PIC XX VALUE "46". PROCEDURE DIVISION. IF S-F = "10" OR S-F = "00" DISPLAY "fine" ELSE DISPLAY "check " S-F END-IF. STOP RUN.Answer
check 46
The read-after-end code is neither success nor end of file, so the program reports it.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 A-F PIC X(2) VALUE "00". PROCEDURE DIVISION. IF A-F = "00" DISPLAY "ok" ELSE DISPLAY "failed" END-IF. STOP RUN.Answer
ok
The comparison with the success code is true.
-
A program ignores the status after WRITE. A record is lost. What does the run show?
Answer
Nothing: the write failed quietly and the next statement ran
A failed write leaves 48 or another code in the status and does not stop the program.
-
Why print the two characters instead of a message of your own?
Answer
The code is what the manual and a support engineer know, and a wrapper can add the sentence
The raw code is stable across platforms and versions, and the message can be looked up.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev