INITIAL, EXTERNAL and CANCEL
A subprogram is a program, and a program owns its working storage. Whether that storage survives a call is a property of the subprogram, chosen in its PROGRAM-ID, and it is the difference between a function and an object with a memory.
Working storage between calls
A plain subprogram initialises its working storage once, at the first call, and keeps it for the rest of the run. Calling it three times shows the same counter going up; a second subprogram declared IS INITIAL starts from its VALUE on every call:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
PROCEDURE DIVISION.
CALL "COUNT-IT".
CALL "COUNT-IT".
CALL "COUNT-IT".
CALL "RESET-IT".
CALL "RESET-IT".
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. COUNT-IT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CALLS PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
ADD 1 TO WS-CALLS.
DISPLAY "count-it call " WS-CALLS.
GOBACK.
END PROGRAM COUNT-IT.
IDENTIFICATION DIVISION.
PROGRAM-ID. RESET-IT IS INITIAL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CALLS PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
ADD 1 TO WS-CALLS.
DISPLAY "reset-it call " WS-CALLS.
GOBACK.
END PROGRAM RESET-IT.
cobc -x -free -Wall -o state state.cob
./state
count-it call 01
count-it call 02
count-it call 03
reset-it call 01
reset-it call 01
The counter of the first subprogram reached 03, the second printed 01 twice. Nothing in the caller changed: the whole difference is the two words IS INITIAL in the PROGRAM-ID of the callee.
IS INITIAL
IS INITIAL makes the subprogram start the way it started the first time: every working-storage item goes back to its VALUE clause, or to spaces and zeros, on each call. That is usually what a helper that computes something wants, and it is never what a subprogram that keeps a total wants.
Two more facts belong with the clause. It applies to working storage and not to LOCAL-STORAGE, which is reset on every call anyway and is the finer tool for one recursive program. And it does not undo the effect of an EXTERNAL item, because that item is not storage of this program at all.
EXTERNAL data
A field declared IS EXTERNAL is one storage area for the whole run, declared under the same name in every program that uses it. The classic use is a run date or a run counter that every module reads:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-TOTAL PIC 9(5) IS EXTERNAL.
PROCEDURE DIVISION.
MOVE 100 TO WS-TOTAL.
CALL "ADD-EXT".
CALL "ADD-EXT".
DISPLAY "main total " WS-TOTAL.
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. ADD-EXT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-TOTAL PIC 9(5) IS EXTERNAL.
PROCEDURE DIVISION.
ADD 50 TO WS-TOTAL.
DISPLAY "callee total " WS-TOTAL.
GOBACK.
END PROGRAM ADD-EXT.
cobc -x -free -Wall -o ext ext.cob
./ext
callee total 00150
callee total 00200
main total 00200
Both programs declare the same five-digit field and both see one area. The description must match: two programs that declare the name with different PIC clauses get one area described two ways, which is the mismatch of the previous lesson with a longer life.
External data is convenient and easy to abuse. A run date is read-only in practice and belongs here; a balance that three modules update is the start of a program whose behaviour depends on the call order, which is exactly what the status parameter of the previous lesson avoids.
CANCEL
CANCEL drops a subprogram: its storage and its state go away, and the next call starts it as if for the first time. A third run of the counting subprogram shows the reset in the middle of a run:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINP.
PROCEDURE DIVISION.
CALL "COUNT-IT".
CALL "COUNT-IT".
CANCEL "COUNT-IT".
CALL "COUNT-IT".
STOP RUN.
END PROGRAM MAINP.
IDENTIFICATION DIVISION.
PROGRAM-ID. COUNT-IT.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CALLS PIC 9(2) VALUE 0.
PROCEDURE DIVISION.
ADD 1 TO WS-CALLS.
DISPLAY "call " WS-CALLS.
GOBACK.
END PROGRAM COUNT-IT.
cobc -x -free -Wall -o cancel cancel.cob
./cancel
call 01
call 02
call 01
The third call printed 01 again. In a program of this size the clause looks like a curiosity; in a run of a thousand transactions it is how a program gets a clean start for each one without ending the process, which matters when the alternative is a fresh start of a large executable.
Exercises
- Give COUNT-IT of the first program IS INITIAL and run it. Which lines change?
- Declare WS-TOTAL of the external program with PIC 9(7) in the callee only. What does the run print?
- Put CANCEL "COUNT-IT" before the very first call. Does the program still run?
- Move the counter of STATE to LOCAL-STORAGE and run it. Which numbers come out?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
When is the working storage of a plain subprogram initialised?
Answer
Once, at the first call, and it keeps its values afterwards
The counter of COUNT-IT reached 03 over three calls.
-
What does IS INITIAL do to a subprogram?
Answer
It resets its working storage on every call
RESET-IT printed 01 on both calls.
-
What is an item declared IS EXTERNAL?
Answer
One storage area for the whole run, declared under the same name in each program
The total of the caller and the callee was the same five-digit area.
-
What does CANCEL do?
Answer
It drops the subprogram and its state, so the next call starts fresh
The call after the CANCEL printed 01 again.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. CALL "Q5SUB". CALL "Q5SUB". STOP RUN. END PROGRAM Q5. IDENTIFICATION DIVISION. PROGRAM-ID. Q5SUB. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9 VALUE 0. PROCEDURE DIVISION. ADD 1 TO W-C. DISPLAY W-C. GOBACK. END PROGRAM Q5SUB.Answer
1 then 2
The working storage of the subprogram survives the first call, so the second adds to 2.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) IS EXTERNAL. PROCEDURE DIVISION. MOVE 10 TO W-A. CALL "Q6SUB". DISPLAY W-A. STOP RUN. END PROGRAM Q6. IDENTIFICATION DIVISION. PROGRAM-ID. Q6SUB. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) IS EXTERNAL. PROCEDURE DIVISION. ADD 5 TO W-A. GOBACK. END PROGRAM Q6SUB.Answer
015
The external item is one area, so the callee added five to the ten of the caller.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9 VALUE 0. PROCEDURE DIVISION. CALL "Q7SUB". CANCEL "Q7SUB". CALL "Q7SUB". STOP RUN. END PROGRAM Q7. IDENTIFICATION DIVISION. PROGRAM-ID. Q7SUB. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-C PIC 9 VALUE 0. PROCEDURE DIVISION. ADD 1 TO W-C. DISPLAY W-C. GOBACK. END PROGRAM Q7SUB.Answer
1 then 1
The CANCEL dropped the state, so the second call started from one again.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 7. PROCEDURE DIVISION. CALL "Q8SUB" USING W-A. DISPLAY W-A. STOP RUN. END PROGRAM Q8. IDENTIFICATION DIVISION. PROGRAM-ID. Q8SUB. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC 9(3). PROCEDURE DIVISION USING L-A. ADD 3 TO L-A. GOBACK. END PROGRAM Q8SUB.Answer
010
The linkage item is the caller field, so the addition is visible after the return.
-
Why is a shared EXTERNAL balance a risk?
Answer
The behaviour of the run depends on the order of the calls
One area updated by several modules makes the result a function of the call order.
-
Which storage is reset on every call without any extra clause?
Answer
LOCAL-STORAGE
LOCAL-STORAGE is the storage of one call, which is why recursive subprograms use it.
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