Debug and runtime checks
A COBOL program compiled without options trusts its own code. A subscript of six into a table of five reads the two bytes behind the table and carries on, and the wrong value travels through the rest of the run. -debug adds the checks that stop it at the statement that did it, with the line and the name of the field.
What -debug turns on
-d and --debug are the same option, and cobc --help says exactly what it expands to:
-d, --debug enable all run-time error checking,
equal to -fstack-check -fec=EC-ALL
Both halves matter. -fec=EC-ALL turns on the exception checks: every subscript, every reference modification, every packed field, every CALL. -fstack-check keeps a stack of the PERFORMs in progress, which is what produces the Last statement of block after a failure. The list of exception names is long:
cobc --list-exceptions | head -12
Exception Name
EC-ALL
EC-ARGUMENT
EC-ARGUMENT-FUNCTION (f)
EC-ARGUMENT-IMP
EC-BOUND
EC-BOUND-FUNC-RET-VALUE
EC-BOUND-IMP
EC-BOUND-ODO (f)
EC-BOUND-OVERFLOW (f)
EC-BOUND-PTR (f)
The command prints 178 lines here, and the (f) marks a check that the compiler can also be asked to turn into a call to a handler of your own. EC-BOUND-SUBSCRIPT and EC-BOUND-ODO are the two this lesson uses.
A subscript out of range
The program fills a table of five entries, then reads item six on purpose. The subscript is a field, not a constant, so nothing at compile time can see the value:
IDENTIFICATION DIVISION.
PROGRAM-ID. BOUNDS.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TAB-AREA.
05 TAB-ITEM PIC 9(2) OCCURS 5 TIMES.
01 WS-I PIC 9(2).
PROCEDURE DIVISION.
PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 5
MOVE WS-I TO TAB-ITEM(WS-I)
END-PERFORM.
MOVE 6 TO WS-I.
DISPLAY "reading item " WS-I.
DISPLAY "[" TAB-ITEM(WS-I) "]".
STOP RUN.
The checked build stops at the second DISPLAY and says which field, which value and how many entries the table has:
cobc -x -free -Wall -debug -o bounds bounds.cob
./bounds
echo $?
reading item 06
libcob: bounds.cob:16: error: subscript of 'TAB-ITEM' out of bounds: 6
note: maximum subscript for 'TAB-ITEM': 5
Last statement of "BOUNDS" was DISPLAY at line 16 of bounds.cob
ENTRY BOUNDS at bounds.cob:11
Started by ./bounds
1
Three parts of that message are worth reading twice. First, the name in the message is the elementary item, not the table: the table is TAB-AREA and the limit that was broken belongs to TAB-ITEM. Second, the entry line points at the paragraph or section the run entered, which is the whole PROCEDURE DIVISION here, so it repeats the first line of the program. Third, the run ends with status 1, which is what a batch step reads as a failed step.
The same source without -debug is a different program in every way that matters: it reads two bytes past the table, prints them and returns success.
cobc -x -free -Wall -o bounds-plain bounds.cob
./bounds-plain
echo $?
reading item 06
[ ]
0
The two spaces are the two bytes behind the table, which no rule of the language says anything about. They happened to be spaces in this build on this machine; a different compiler, a different table and a different number of variables can make that line a number, a crash or a value that looks plausible and is wrong. That is the kind of bug a checked build turns into a message with a line number.
The one the compiler catches
A constant subscript needs no runtime check at all: the compiler knows the table size and the number and refuses the source.
IDENTIFICATION DIVISION.
PROGRAM-ID. FIXEDSUB.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 TAB-AREA.
05 TAB-ITEM PIC 9(2) OCCURS 5 TIMES.
PROCEDURE DIVISION.
DISPLAY "item six " TAB-ITEM(6).
STOP RUN.
cobc -x -free -Wall -debug -o fixedsub fixed.cob
fixed.cob:10: error: subscript of 'TAB-ITEM' out of bounds: 6
8 |
9 | PROCEDURE DIVISION.
10 > DISPLAY "item six " TAB-ITEM(6).
11 | STOP RUN.
12 | <EOF>
The arrow marks the offending line, so the reader does not have to count from the top of the listing. This is a compile error and not a warning: -debug changes nothing about it, and the same message appears without the option.
A CALL that finds nothing
The check that matters most in a job of several programs is the one on CALL. A program can be built and linked with a call to a name that does not exist at run time, and the failure arrives only when the statement runs:
IDENTIFICATION DIVISION.
PROGRAM-ID. CALLMISS.
PROCEDURE DIVISION.
DISPLAY "before".
CALL "NOSUCH".
DISPLAY "after".
STOP RUN.
cobc -x -free -Wall -debug -o callmiss callmiss.cob
./callmiss
echo $?
before
libcob: callmiss.cob:6: error: module 'NOSUCH' not found
Last statement of "CALLMISS" was CALL at line 6 of callmiss.cob
ENTRY CALLMISS at callmiss.cob:5
Started by ./callmiss
1
This one is not a debug-only check: the runtime has to resolve the name of any CALL it is given, and a name it cannot find fails the run with or without the option. The next lesson runs modules on purpose with cobcrun, and there the folder the module lives in decides the same question.
What the checks cost
The checks are not free. A loop of twenty million additions, built twice from the same source and timed ten times each on this machine:
IDENTIFICATION DIVISION.
PROGRAM-ID. LOOPC.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-I PIC 9(9) COMP-5.
01 WS-T PIC 9(18) COMP-5.
PROCEDURE DIVISION.
PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 20000000
ADD WS-I TO WS-T
END-PERFORM.
DISPLAY WS-T.
STOP RUN.
cobc -x -free -Wall -o loop loop.cob
cobc -x -free -Wall -debug -o loop-debug loop.cob
hyperfine --warmup 2 --runs 10 ./loop ./loop-debug
Benchmark 1: ./loop
Time (mean ± σ): 246.7 ms ± 4.6 ms [User: 244.0 ms, System: 2.5 ms]
Range (min … max): 243.8 ms … 259.2 ms 10 runs
Benchmark 2: ./loop-debug
Time (mean ± σ): 299.1 ms ± 10.7 ms [User: 296.1 ms, System: 2.5 ms]
Range (min … max): 292.1 ms … 328.0 ms 10 runs
Summary
./loop ran
1.21 ± 0.05 times faster than ./loop-debug
About a fifth more time on a loop of arithmetic, which is the cheapest kind of work the checks have; a loop that touches tables and files pays more, because every subscript and every buffer length is then checked too. The number to remember is not this one but the shape of it: a checked build is slow enough to matter in a timed run and fast enough to use in a test run.
So the two builds have two jobs. -debug is the one the tests run, and a run that fails there is a bug in the program. The plain build is the one the batch runs, fast and quiet. Both come from one source, which is the reason a Makefile has two targets and not two copies of the program.
Exercises
- Change the table to ten entries and the subscript to eleven. Which line does the checked run name?
- Give FIXEDSUB a second table and read TAB-TWO(1) from a program that has no TAB-TWO. Read the compile error in full.
- Turn on one check only with -fec=EC-BOUND-SUBSCRIPT and time the loop again. Does it cost less than -debug?
- Make the unchecked BOUNDS read item 500 and run it. What does it print, and what is the exit status?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does cobc -debug turn on?
Answer
All runtime error checks and PERFORM stack checking
cobc --help says -d, --debug is equal to -fstack-check -fec=EC-ALL.
-
A subscript of 6 into a table of 5 is a constant. When does the compiler report it?
Answer
At compile time, with the line and an arrow under it
FIXEDSUB fails to build with subscript of TAB-ITEM out of bounds: 6 before any run.
-
What status does the checked run of BOUNDS return?
Answer
1
The runtime error ends the run with status 1, which the page shows as the last line.
-
Why does the unchecked build of BOUNDS print two spaces?
Answer
It read two bytes behind the table, and no rule says what they hold
The table has five entries; the sixth read lands behind it.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 T. 05 T-ITEM PIC 9(2) OCCURS 4 TIMES. 01 I PIC 9(2). PROCEDURE DIVISION. PERFORM VARYING I FROM 1 BY 1 UNTIL I IS GREATER THAN 4 MOVE I TO T-ITEM(I) END-PERFORM. DISPLAY T-ITEM(4). STOP RUN.Answer
04
The loop fills the table with one to four; the fourth item holds 4.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(3) VALUE 7. 01 B PIC 9(3) VALUE 2. 01 C PIC 9(3). PROCEDURE DIVISION. COMPUTE C = A / B DISPLAY C. STOP RUN.Answer
003
A and B are integers and C has no decimal places, so 3.5 is truncated to 3.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 N PIC 9(2) VALUE 0. PROCEDURE DIVISION. PERFORM UNTIL N IS GREATER THAN 2 ADD 1 TO N END-PERFORM. DISPLAY N. STOP RUN.Answer
03
The loop stops when N passes 2, so the last value is 3.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W PIC X(8) VALUE "ABCDEFGH". PROCEDURE DIVISION. DISPLAY W(3:2). STOP RUN.Answer
CD
Reference modification counts from 1, so position 3 is C and two characters are CD.
-
Why build the same source twice, once with -debug and once without?
Answer
The checked build finds bugs in tests and the plain build runs fast in batch
The timing run shows the checked build about a fifth slower on plain arithmetic.
-
What is the point of the PERFORM stack in a checked run?
Answer
It names the statement and the paragraph chain that were running when the check failed
The Last statement of block and the ENTRY line come from that stack.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and timed with hyperfine on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev