Missing files and duplicate keys

A batch job runs at night with nobody watching, so every file error has to become a message in a log and a status the scheduler reads. This lesson takes the two file errors a new program meets first, a file that is not there and a key that is already there, and ends with the paragraph that turns a status into a sentence.

A file that is not there

OPEN INPUT of a file the run folder does not hold fails with status 35. The program does not stop: it has to look at the status, say what is missing, and set RETURN-CODE so the shell knows the job failed.

IDENTIFICATION DIVISION. PROGRAM-ID. MISS. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT IN-F ASSIGN TO "missing.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-STATUS. DATA DIVISION. FILE SECTION. FD IN-F. 01 IN-REC PIC X(10). WORKING-STORAGE SECTION. 01 WS-STATUS PIC XX. PROCEDURE DIVISION. OPEN INPUT IN-F. DISPLAY "open " WS-STATUS. IF WS-STATUS NOT = "00" DISPLAY "input file missing.dat is not there" DISPLAY "put it in the run folder and start the job again" MOVE 12 TO RETURN-CODE END-IF. READ IN-F AT END DISPLAY "at end" END-READ. DISPLAY "read " WS-STATUS. CLOSE IN-F. DISPLAY "close " WS-STATUS. DISPLAY "return " RETURN-CODE. STOP RUN.

cobc -x -free -Wall -o miss miss.cob
./miss

open 35
input file missing.dat is not there
put it in the run folder and start the job again
read 47
close 42
return +000000012

The message names the file and the action, which is what a log line has to do at three in the morning. The run ends with exit status 12: that is the shell reading the special register RETURN-CODE, so the job scheduler knows this step failed without parsing a log.

What the next verbs do

Three more statuses came out of the same run, and each one is a lesson in reading the status field rather than assuming it. The READ printed nothing and left 47: the file is not open, so the verb is not allowed in this mode. The CLOSE printed nothing and left 42, a close of a file that was never opened.

Neither of them is fatal, and that is the trap: a program that ignores the status of the open runs on, reads nothing, produces a report of zero lines and exits with 0. The scheduler marks the job green. The IF after the open is the whole difference between a report and an empty report.

A duplicate key

The second error a new program meets is a write of a record whose key is already in an indexed file. The write is refused with status 22 and the file keeps its old record:

IDENTIFICATION DIVISION. PROGRAM-ID. DUP. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT CUS-F ASSIGN TO "dup.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). 05 CUS-NAME PIC X(8). WORKING-STORAGE SECTION. 01 WS-STATUS PIC XX. PROCEDURE DIVISION. OPEN OUTPUT CUS-F. MOVE "A10" TO CUS-ID. MOVE "Ada" TO CUS-NAME. WRITE CUS-REC. DISPLAY "write 1 " WS-STATUS. MOVE "Ada L" TO CUS-NAME. WRITE CUS-REC. DISPLAY "write 2 " WS-STATUS. IF WS-STATUS = "22" DISPLAY "customer " CUS-ID " is already in the file" DISPLAY "nothing was changed; use the update job to change a name" MOVE 8 TO RETURN-CODE END-IF. CLOSE CUS-F. DISPLAY "return " RETURN-CODE. STOP RUN.

cobc -x -free -Wall -o dup dup.cob
./dup

write 1 00
write 2 22
customer A10 is already in the file
nothing was changed; use the update job to change a name
return +000000008

The name in the record area was overwritten by the failed write, and the record in the file still says Ada. This run ends with exit status 8, which the program set itself. That is the reason the message says nothing was changed: a program that reported success here would be wrong about the file and about the name.

Check before you write

A loader that must add a file of customers without stopping at the first duplicate reads first and writes only when the read found nothing. The index answers the question in one call, and the count of skipped records is the report of the job:

IDENTIFICATION DIVISION. PROGRAM-ID. GUARD. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT CUS-F ASSIGN TO "guard.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. 01 WS-WRITTEN PIC 9(2) VALUE 0. 01 WS-SKIPPED PIC 9(2) VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT CUS-F. CLOSE CUS-F. OPEN I-O CUS-F. MOVE "A10" TO CUS-ID. PERFORM ADD-ONE. MOVE "A10" TO CUS-ID. PERFORM ADD-ONE. MOVE "B20" TO CUS-ID. PERFORM ADD-ONE. CLOSE CUS-F. DISPLAY "written " WS-WRITTEN " skipped " WS-SKIPPED. STOP RUN. ADD-ONE. READ CUS-F INVALID KEY WRITE CUS-REC ADD 1 TO WS-WRITTEN NOT INVALID KEY ADD 1 TO WS-SKIPPED END-READ.

cobc -x -free -Wall -o guard guard.cob
./guard

written 02 skipped 01

Two records were added and one was skipped, and no status was printed because none of the three was an error. The shape is the one the update lesson used for its counters: one paragraph does the work, one counter says how it went, and the job writes both into its log.

A status table with messages

The paragraph that turns a status into a sentence belongs in one place, so that the same code always reads the same way. Every code it knows was produced by a verb of this program:

IDENTIFICATION DIVISION. PROGRAM-ID. MSG. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT IN-F ASSIGN TO "absent.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-STATUS. SELECT CUS-F ASSIGN TO "msg.idx" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS CUS-ID FILE STATUS IS WS-STATUS. DATA DIVISION. FILE SECTION. FD IN-F. 01 IN-REC PIC X(10). FD CUS-F. 01 CUS-REC. 05 CUS-ID PIC X(3). WORKING-STORAGE SECTION. 01 WS-STATUS PIC XX. 01 WS-TEXT PIC X(34). PROCEDURE DIVISION. OPEN INPUT IN-F. PERFORM REPORT-STATUS. DISPLAY "open input " WS-STATUS " " FUNCTION TRIM(WS-TEXT). READ IN-F AT END CONTINUE END-READ. PERFORM REPORT-STATUS. DISPLAY "read " WS-STATUS " " FUNCTION TRIM(WS-TEXT). CLOSE IN-F. PERFORM REPORT-STATUS. DISPLAY "close " WS-STATUS " " FUNCTION TRIM(WS-TEXT). OPEN OUTPUT CUS-F. MOVE "A10" TO CUS-ID. WRITE CUS-REC. PERFORM REPORT-STATUS. DISPLAY "write " WS-STATUS " " FUNCTION TRIM(WS-TEXT). WRITE CUS-REC. PERFORM REPORT-STATUS. DISPLAY "write again " WS-STATUS " " FUNCTION TRIM(WS-TEXT). CLOSE CUS-F. STOP RUN. REPORT-STATUS. EVALUATE WS-STATUS WHEN "00" MOVE "ok" TO WS-TEXT WHEN "10" MOVE "end of file" TO WS-TEXT WHEN "22" MOVE "duplicate key, the record exists" TO WS-TEXT WHEN "23" MOVE "record not found" TO WS-TEXT WHEN "35" MOVE "the file is not there" TO WS-TEXT WHEN "42" MOVE "close of a file that is not open" TO WS-TEXT WHEN "47" MOVE "verb not allowed in this open mode" TO WS-TEXT WHEN OTHER MOVE "unknown status" TO WS-TEXT END-EVALUATE.

cobc -x -free -Wall -o msg msg.cob
./msg

open input 35 the file is not there
read 47 verb not allowed in this open mode
close 42 close of a file that is not open
write 00 ok
write again 22 duplicate key, the record exists

FUNCTION TRIM removes the spaces of the PIC X(34) field, so the log line ends at the last real character. The WHEN OTHER branch matters as much as the rest: a new code in a later compiler must appear as an unknown status in the log, not as a blank line.

Exercises

  1. Run miss a second time. Which status does the OPEN INPUT return now, and why?
  2. Change the MOVE 12 TO RETURN-CODE in miss to 4 and read the exit status of the run.
  3. Add the code 10 to the table of msg and produce it with a read of an empty file.
  4. Give guard a third status branch for 21 and say when a write can return it.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which status does OPEN INPUT return for a file that is not in the run folder?

    Answer

    35

    The program printed open 35 and then a message naming the file.

  2. Which status does a READ of a file that failed to open return?

    Answer

    47

    The verb is not allowed in the current open mode, and the run printed read 47.

  3. What does RETURN-CODE do at the end of a run?

    Answer

    It becomes the exit status the shell and the scheduler read

    The run of miss set it to 12 and the shell saw 12.

  4. Which status does a WRITE of a record whose key already exists return?

    Answer

    22

    The second write of the duplicate program printed 22 and the file kept the first record.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-S PIC XX VALUE "35". 01 W-T PIC X(20) VALUE "missing file ". PROCEDURE DIVISION. IF W-S = "35" DISPLAY W-S " " FUNCTION TRIM(W-T) ELSE DISPLAY "ok" END-IF. STOP RUN.

    Answer

    35 missing file

    The status is 35 and TRIM removes the spaces the field holds.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT F-I ASSIGN TO "q6d.idx" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS K-F FILE STATUS IS W-S. DATA DIVISION. FILE SECTION. FD F-I. 01 R-I. 05 K-F PIC X(2). WORKING-STORAGE SECTION. 01 W-S PIC XX. 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT F-I. MOVE "AA" TO K-F. WRITE R-I. WRITE R-I. IF W-S = "22" ADD 1 TO W-N END-IF. MOVE "BB" TO K-F. WRITE R-I. IF W-S = "00" ADD 1 TO W-N END-IF. DISPLAY W-N. CLOSE F-I. STOP RUN.

    Answer

    2

    The duplicate returned 22 and counted, and the write of BB returned 00 and counted.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-S PIC XX. 01 W-T PIC X(20). PROCEDURE DIVISION. MOVE "42" TO W-S. PERFORM REPORT-STATUS. DISPLAY W-S " " FUNCTION TRIM(W-T). STOP RUN. REPORT-STATUS. EVALUATE W-S WHEN "00" MOVE "ok" TO W-T WHEN "42" MOVE "not open" TO W-T WHEN OTHER MOVE "unknown" TO W-T END-EVALUATE.

    Answer

    42 not open

    The EVALUATE finds the branch for 42 before it reaches WHEN OTHER.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-S PIC XX VALUE "31". 01 W-T PIC X(10). PROCEDURE DIVISION. EVALUATE W-S WHEN "00" MOVE "ok" TO W-T WHEN "22" MOVE "duplicate" TO W-T END-EVALUATE. DISPLAY "[" FUNCTION TRIM(W-T) "]". STOP RUN.

    Answer

    []

    No branch matches 31 and there is no WHEN OTHER, so the field keeps its spaces.

  9. A job opens its input, ignores the status, reads nothing and exits with 0. What does the scheduler see?

    Answer

    A successful step with an empty report

    That is the trap of the second section: no message, no error, and a green job.

  10. Why does the loader read a record before it writes one?

    Answer

    A read of an absent key returns INVALID KEY, which is the proof that the key is free

    The guarded program wrote two records and skipped the one the read found.

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