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

  1. Change the table to ten entries and the subscript to eleven. Which line does the checked run name?
  2. Give FIXEDSUB a second table and read TAB-TWO(1) from a program that has no TAB-TWO. Read the compile error in full.
  3. Turn on one check only with -fec=EC-BOUND-SUBSCRIPT and time the loop again. Does it cost less than -debug?
  4. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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