ON EXCEPTION and the status table

A verb can fail in three ways, and COBOL gives each a phrase: the file verbs have INVALID KEY, the string verbs have ON OVERFLOW, and CALL has ON EXCEPTION. All three sit inside the statement that can fail, which is the difference between them and the IF on the status field.

CALL ... ON EXCEPTION

ON EXCEPTION of a call catches what the CALL itself failed to do: a name no program answers to. The program below sets a flag in the exception branch and prints it after the call:

IDENTIFICATION DIVISION. PROGRAM-ID. E2. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-NAME PIC X(8) VALUE "NOPROG". 01 WS-FLAG PIC X VALUE "N". PROCEDURE DIVISION. CALL WS-NAME ON EXCEPTION MOVE "Y" TO WS-FLAG DISPLAY "exception branch" NOT ON EXCEPTION DISPLAY "normal branch" END-CALL. DISPLAY "flag " WS-FLAG. STOP RUN.

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

exception branch
normal branch
flag Y

Two branches of one statement ran, and the flag of the exception branch was set. In a conforming compiler only the first of the two would print; in this one the NOT ON EXCEPTION clause is executed as well, so it cannot be trusted to mean "the call worked". The same program with a call to a subprogram that exists printed only inside the callee and flag N.

The pattern that survives both behaviours is the one the program already uses: set a result field in the exception branch, test the field after END-CALL, and keep the normal work outside the statement. It is also the pattern of the status parameter of the call lessons, and it costs one field.

INVALID KEY and NOT INVALID KEY

The file verbs that address a record by a key are READ, WRITE, REWRITE, DELETE and START. Each takes INVALID KEY for a key that is wrong and NOT INVALID KEY for a key that is not:

IDENTIFICATION DIVISION. PROGRAM-ID. K1. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT CUS-F ASSIGN TO "k1.idx" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS CUS-ID FILE STATUS IS WS-ST. DATA DIVISION. FILE SECTION. FD CUS-F. 01 CUS-REC. 05 CUS-ID PIC X(3). WORKING-STORAGE SECTION. 01 WS-ST PIC XX. PROCEDURE DIVISION. OPEN OUTPUT CUS-F. CLOSE CUS-F. OPEN I-O CUS-F. MOVE "A10" TO CUS-ID. WRITE CUS-REC INVALID KEY DISPLAY "write A10 refused, status " WS-ST NOT INVALID KEY DISPLAY "write A10 ok" END-WRITE. WRITE CUS-REC INVALID KEY DISPLAY "write A10 again refused, status " WS-ST NOT INVALID KEY DISPLAY "write A10 again ok" END-WRITE. MOVE "Z99" TO CUS-ID. READ CUS-F INVALID KEY DISPLAY "read Z99 refused, status " WS-ST NOT INVALID KEY DISPLAY "read Z99 ok" END-READ. MOVE "A10" TO CUS-ID. READ CUS-F INVALID KEY DISPLAY "read A10 refused, status " WS-ST NOT INVALID KEY DISPLAY "read A10 ok" END-READ. CLOSE CUS-F. STOP RUN.

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

write A10 ok
write A10 again refused, status 22
read Z99 refused, status 23
read A10 ok

Four verbs, two failures, and each failure in the branch that names it: 22 for the second write of a key, 23 for a read of one that is not there. The file was opened I-O because a READ on a file opened OUTPUT fails with 47 and no key phrase applies; that is the trap the exercise at the end of the page asks about.

ON OVERFLOW of STRING and UNSTRING

STRING overflows when the receiving field is full before the sources are used up, and UNSTRING when the receiving list is full before the delimited text is:

IDENTIFICATION DIVISION. PROGRAM-ID. O1. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-SRC PIC X(20) VALUE "ABCDEFGHIJKLMNOPQRST". 01 WS-DST PIC X(5). PROCEDURE DIVISION. STRING WS-SRC DELIMITED BY SIZE INTO WS-DST ON OVERFLOW DISPLAY "string overflow, the field is full" NOT ON OVERFLOW DISPLAY "string fit" END-STRING. DISPLAY "dst [" FUNCTION TRIM(WS-DST) "]". STOP RUN.

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

string overflow, the field is full
dst [ABCDE]

One branch, as it should be: the field took five characters and the rest of the source was dropped. A program that must keep the whole line uses WITH POINTER and checks the pointer against the length of the receiving field, which is the STRING lesson.

IDENTIFICATION DIVISION. PROGRAM-ID. O2. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-LINE PIC X(30) VALUE "AA,BB,CC,DD,EE". 01 WS-T1 PIC X(4). 01 WS-T2 PIC X(4). PROCEDURE DIVISION. UNSTRING WS-LINE DELIMITED BY "," INTO WS-T1 WS-T2 ON OVERFLOW DISPLAY "unstring overflow" NOT ON OVERFLOW DISPLAY "unstring finished" END-UNSTRING. DISPLAY "one [" FUNCTION TRIM(WS-T1) "]". DISPLAY "two [" FUNCTION TRIM(WS-T2) "]". STOP RUN.

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

unstring overflow
one [AA]
two [BB]

Two fields were filled and the three remaining pieces of the line were dropped. The status of the verb is not a file status and nothing but this phrase reports it, which makes the phrase the only way a program learns that its record had more fields than it was ready for.

The statuses this page produced

Four of the codes of the page came from verbs that ran here, and the other two come from the sections above:

CodeProduced byPhrase that catches it
00the successful write and readNOT INVALID KEY
22the second write of one keyINVALID KEY
23a read of a key that is not thereINVALID KEY
47a read on a file opened OUTPUTnone: the status field only
35an open of a file that is not therenone: the status field only
42a close of a file that is not opennone: the status field only

The last three rows are the lesson: a key phrase catches a key failure and nothing else, so a program that checks only INVALID KEY misses every mishap of the open and close of its files. The status field sees all six, and the status lesson is its table.

Exercises

  1. Change the first program to call a name that exists and then to call a name that does not. Which lines differ?
  2. Open the indexed file of the second program OUTPUT and read a record. Which status comes back, and which branch runs?
  3. Give the STRING of the third program a receiving field of forty characters and read the branch that runs this time.
  4. Add a third receiving field to the UNSTRING and say which branch runs.

Questions

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

  1. What does CALL ... ON EXCEPTION catch?

    Answer

    A call that could not be made, such as a program name nothing answers to

    The page called a name that does not exist and the exception branch ran.

  2. Which phrase catches a duplicate key on a WRITE?

    Answer

    INVALID KEY

    The second write printed its INVALID KEY branch with status 22.

  3. Which failure has no phrase and only the status field?

    Answer

    A READ on a file opened OUTPUT, which returns 47

    The first version of the page showed status 47 and no branch running.

  4. What does ON OVERFLOW of UNSTRING report?

    Answer

    That the receiving fields were full before the text was

    Two fields were filled and the rest of the line was dropped.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-SRC PIC X(6) VALUE "ABCDEF". 01 W-DST PIC X(3). PROCEDURE DIVISION. STRING W-SRC DELIMITED BY SIZE INTO W-DST ON OVERFLOW DISPLAY "full" NOT ON OVERFLOW DISPLAY "fit" END-STRING. DISPLAY "[" W-DST "]". STOP RUN.

    Answer

    full then [ABC]

    Three characters fit and the rest of the source overflowed.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-S PIC XX VALUE "23". 01 W-M PIC X(10) VALUE SPACES. PROCEDURE DIVISION. IF W-S = "23" MOVE "not found" TO W-M END-IF. DISPLAY "[" FUNCTION TRIM(W-M) "]". STOP RUN.

    Answer

    [not found]

    The status 23 is the one a missing record leaves.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-L PIC X(12) VALUE "AA;BB;CC". 01 W-A PIC X(3). 01 W-B PIC X(3). PROCEDURE DIVISION. UNSTRING W-L DELIMITED BY ";" INTO W-A W-B ON OVERFLOW DISPLAY "overflow" END-UNSTRING. DISPLAY W-A " " W-B. STOP RUN.

    Answer

    overflow then AA BB

    Two fields are full and the third piece is dropped, which is the overflow.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9 VALUE 0. PROCEDURE DIVISION. MOVE 3 TO W-C. SUBTRACT 1 FROM W-C. DISPLAY W-C. STOP RUN.

    Answer

    2

    One is subtracted from three in the same field.

  9. Why does the second program open the file with I-O?

    Answer

    A READ needs a file opened for input, and I-O allows reads and writes

    The read on an OUTPUT file returned 47 in the first version.

  10. What is the difference between a key phrase and the status field?

    Answer

    The phrase catches one kind of failure of one verb, the field records every verb

    The table of the page lists three failures that no phrase catches.

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