DECLARATIVES and USE
Every file verb in this course has been followed by an IF on the status. There is a second way to catch the same failures, older than the status field: a DECLARATIVES section at the top of the procedure division, with a USE clause that says which file it watches and a paragraph the runtime calls when that file fails.
DECLARATIVES and USE
The section stands between PROCEDURE DIVISION. and the first paragraph of the program, and it ends with END DECLARATIVES. A file that is not there makes its handler run on every verb that fails on it:
IDENTIFICATION DIVISION.
PROGRAM-ID. D1.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT IN-F ASSIGN TO "absent.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-ST.
DATA DIVISION.
FILE SECTION.
FD IN-F.
01 IN-REC PIC X(10).
WORKING-STORAGE SECTION.
01 WS-ST PIC XX.
PROCEDURE DIVISION.
DECLARATIVES.
IN-ERROR SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON IN-F.
IN-HANDLER.
DISPLAY "handler: error on IN-F, status " WS-ST.
END DECLARATIVES.
MAIN-PARA.
OPEN INPUT IN-F.
DISPLAY "open " WS-ST.
CLOSE IN-F.
STOP RUN.
cobc -x -free -Wall -o d1 d1.cob
./d1
handler: error on IN-F, status 35
open 35
handler: error on IN-F, status 42
Three lines for two verbs. The handler ran before the DISPLAY of the status, because the runtime calls it as part of the failed statement, and it ran again for the CLOSE of a file that never opened. The program still printed both statuses and still ended with STOP RUN: a declarative reports and returns, it does not stop the run.
A handler for a duplicate key
The same clause catches an indexed file error in the middle of a loop, and the program continues with the statement after the one that failed:
IDENTIFICATION DIVISION.
PROGRAM-ID. D2.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CUS-F ASSIGN TO "cus106.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).
05 CUS-NAME PIC X(8).
WORKING-STORAGE SECTION.
01 WS-ST PIC XX.
01 WS-ERRORS PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
DECLARATIVES.
CUS-ERROR SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON CUS-F.
CUS-HANDLER.
ADD 1 TO WS-ERRORS.
DISPLAY "handler: " WS-ST " on record " CUS-ID.
END DECLARATIVES.
MAIN-PARA.
OPEN OUTPUT CUS-F.
MOVE "A10" TO CUS-ID.
MOVE "Ada" TO CUS-NAME.
WRITE CUS-REC.
DISPLAY "write 1 " WS-ST.
MOVE "Bob" TO CUS-NAME.
WRITE CUS-REC.
DISPLAY "write 2 " WS-ST.
DISPLAY "after the failed write the name is " CUS-NAME.
CLOSE CUS-F.
DISPLAY "errors " WS-ERRORS.
STOP RUN.
cobc -x -free -Wall -o d2 d2.cob
./d2
write 1 00
handler: 22 on record A10
write 2 22
after the failed write the name is Bob
errors 01
The handler counted the failure and named the record, and the program went on: the second write was refused with 22, the name field still held the value the program had moved into it, and the summary line reported one error. That is a workable design for a loader that skips duplicates, and it is the one that predates the status field in most shops.
A run with no error
A declarative is not a call the program makes; the runtime calls it. A clean run shows the handler never entered:
IDENTIFICATION DIVISION.
PROGRAM-ID. D3.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT IN-F ASSIGN TO "present.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-ST.
DATA DIVISION.
FILE SECTION.
FD IN-F.
01 IN-REC PIC X(10).
WORKING-STORAGE SECTION.
01 WS-ST PIC XX.
01 WS-CALLS PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
DECLARATIVES.
IN-ERROR SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON IN-F.
IN-HANDLER.
ADD 1 TO WS-CALLS.
DISPLAY "handler: status " WS-ST.
END DECLARATIVES.
MAIN-PARA.
OPEN OUTPUT IN-F.
MOVE "first" TO IN-REC.
WRITE IN-REC.
CLOSE IN-F.
OPEN INPUT IN-F.
DISPLAY "open " WS-ST.
READ IN-F
AT END DISPLAY "at end"
NOT AT END DISPLAY "read [" FUNCTION TRIM(IN-REC) "]"
END-READ.
CLOSE IN-F.
DISPLAY "handler calls " WS-CALLS.
STOP RUN.
cobc -x -free -Wall -o d3 d3.cob
./d3
open 00
read [first]
handler calls 00
Zero calls. A program that has both the declarative and the IF on the status therefore has two readers of the same failure, which is a design choice: the declarative logs, the status field decides what happens next. The lesson on file errors uses the status field alone, and it is the shorter of the two.
What the USE clause does not do is as important. It cannot catch a duplicate key before the write, it cannot stop the run, and it does not know which paragraph failed: the handler sees the status and the record, and that is all.
Exercises
- Add a second USE section for a second file to the first program and see which handler runs for which file.
- Make the handler of the duplicate program set RETURN-CODE and read the exit status of the run.
- Delete the IF on the status from a program of the file-errors lesson and add a declarative instead. Which version reports more?
- Put a GO TO into a handler and say what the program does after it.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Where does the DECLARATIVES section stand?
Answer
At the top of the PROCEDURE DIVISION, before the first paragraph, closed by END DECLARATIVES
The programs of the page put it between PROCEDURE DIVISION and MAIN-PARA.
-
When does the handler of USE AFTER STANDARD ERROR run?
Answer
When a file verb on that file fails
It ran for the failed open and the failed close of the missing file.
-
What does the program do after the handler finishes?
Answer
It continues with the statement after the one that failed
The program printed its status lines and its summary after both failures.
-
How did the clean run show that the handler was not called?
Answer
A counter in working storage stayed at zero
The last line of the run was handler calls 00.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-ST PIC XX VALUE "35". 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. IF W-ST NOT = "00" ADD 1 TO W-N END-IF. DISPLAY W-N " " W-ST. STOP RUN.Answer
1 35
The status is not zero, so the counter counts the failure.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9(2) VALUE 0. PROCEDURE DIVISION. PERFORM 3 TIMES ADD 1 TO W-C END-PERFORM. DISPLAY W-C. STOP RUN.Answer
03
Three passes of the loop count three.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 120. 01 W-B PIC 9(3) VALUE 0. PROCEDURE DIVISION. IF W-A IS GREATER THAN 100 MOVE 4 TO W-B ELSE MOVE 0 TO W-B END-IF. DISPLAY W-B. STOP RUN.Answer
004
The amount is above the limit, so the error code is set.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-S PIC XX VALUE "22". 01 W-T PIC X(12) VALUE SPACES. PROCEDURE DIVISION. EVALUATE W-S WHEN "00" MOVE "ok" TO W-T WHEN "22" MOVE "duplicate" TO W-T WHEN OTHER MOVE "other" TO W-T END-EVALUATE. DISPLAY "[" FUNCTION TRIM(W-T) "]". STOP RUN.Answer
[duplicate]
The status 22 has its own branch in the handler.
-
Which failure can a USE clause not prevent?
Answer
A duplicate key before the write, because it runs only after the verb failed
The handler of the page saw the 22 of the write that was already refused.
-
Why does a shop sometimes keep both the declarative and the status check?
Answer
The declarative logs the failure and the status field decides what happens next
The handler of the first program ran for both verbs while the program still read each status.
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