COB_SET_TRACE and -ftrace

A trace answers the question a stack backtrace cannot: what did the program do before it got here. It costs one build option and one environment variable, it needs no debugger, and it works on a batch job that nobody is watching, which is where the interesting failures happen.

Two switches, not one

The trace code has to be in the executable and the trace has to be asked for at run time. -ftrace puts the code in; COB_SET_TRACE=1 turns it on. Either one without the other prints nothing, and the program here shows all four combinations.

IDENTIFICATION DIVISION. PROGRAM-ID. TRACED. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-N PIC 9(2) VALUE 3. PROCEDURE DIVISION. MAIN-PARA. DISPLAY "start". PERFORM WORK-PARA DISPLAY "done". STOP RUN. WORK-PARA. DISPLAY "working " WS-N.

cobc -x -free -Wall -o trace-plain trace.cob
COB_SET_TRACE=1 ./trace-plain

start
working 03
done

The variable is set and the trace is absent, because the executable holds no trace code. The other half of the pair:

cobc -x -free -Wall -ftrace -o trace trace.cob
./trace

start
working 03
done

The code is in the executable and the trace is still absent, because nobody asked for it. That is the useful default: one build with -ftrace can run a thousand times quietly and once with the variable set when a job misbehaves.

A trace of paragraphs

Both switches together print a line for the program entry and a line for every paragraph the run enters:

COB_SET_TRACE=1 ./trace

Source: 'trace.cob'
Program-Id:  TRACED
Program-Id:  TRACED               Entry: TRACED                          Line:      9
Program-Id:  TRACED           Paragraph: MAIN-PARA                       Line:      9
Program-Id:  TRACED           Paragraph: WORK-PARA                       Line:     15
start
working 03
done

WORK-PARA appears once, at the PERFORM that called it. MAIN-PARA appears once too, and its line is nine: the header is the first line the run executes. There is no line for the end of a paragraph, and no count of the times it ran, so a trace of a loop is a trace of its paragraphs repeated. That is the first thing to look at when a trace of a batch job is longer than expected.

Every statement with -ftraceall

-ftraceall goes one level down and prints every statement the run executes, with the verb and the line:

cobc -x -free -Wall -ftraceall -o traceall trace.cob
COB_SET_TRACE=1 ./traceall

Source: 'trace.cob'
Program-Id:  TRACED
Program-Id:  TRACED               Entry: TRACED                          Line:      9
Program-Id:  TRACED           Paragraph: MAIN-PARA                       Line:      9
Program-Id:  TRACED                      DISPLAY                          Line:     10
Program-Id:  TRACED                      PERFORM                          Line:     11
Program-Id:  TRACED           Paragraph: WORK-PARA                       Line:     15
Program-Id:  TRACED                      DISPLAY                          Line:     16
Program-Id:  TRACED                      DISPLAY                          Line:     12
start
working 03
done
Program-Id:  TRACED                      STOP RUN                        Line:     13

The trace reads like the source with the paragraph removed. Line 10 is the first DISPLAY, line 11 the PERFORM, then the paragraph header of the callee at 15, its DISPLAY at 16, back to the caller at 12, and the STOP RUN at 13. The last line is below the program output for the buffering reason the next section shows. The line numbers are the whole value of this mode: a loop shows which iteration reached which statement, and a missing line says which branch the run did not take.

Standard error, not standard output

The trace goes to standard error and the DISPLAY lines go to standard output, so a job can keep its report clean while a trace is on:

COB_SET_TRACE=1 ./trace 2>/dev/null

start
working 03
done

The other way round leaves only the trace. This also explains the order of the two blocks in a captured run: standard output is a pipe, which is block buffered, so its three lines are written when the program ends, after the trace lines that standard error wrote without buffering.

Reading a trace

Four things are worth knowing before the first long trace. The first is that the trace names the unit of work and not the statement in a paragraph trace, so a paragraph that runs once per record appears once per record and nothing tells the records apart; a statement trace shows the loop, not the record. The second is that the line numbers are the lines of the source the executable was built from: an edited source with an old executable points at the wrong lines, which is why the trace prints Source: first.

The third is cost. The paragraph trace prints one line per PERFORM, the statement trace one per statement, and a job of a million records writes millions of lines to a file at whatever speed the disk has. A trace is turned on for a run, not left on. The fourth is that a trace is not a replacement for a checked build: it says where the program went, and -debug from the previous lesson says what the program did that the language does not allow. Both together, with the trace to standard error and the program output to a report file, is what a batch failure usually needs.

Exercises

  1. Add a paragraph that is never performed. Does it appear in the paragraph trace? In the statement trace?
  2. Put the DISPLAY of WORK-PARA inside PERFORM 3 TIMES and count the trace lines.
  3. Run COB_SET_TRACE=1 ./traceall 2>trace.log and read the file with wc -l. How many lines for a program of nine statements?
  4. Delete a blank line above WORK-PARA and run the old executable with the new source. Which line does the trace name for that paragraph, and which line holds it now?

Questions

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

  1. Which two things does a paragraph trace need?

    Answer

    -ftrace at build time and COB_SET_TRACE=1 at run time

    Neither half alone printed a trace on this page.

  2. Where does the trace go?

    Answer

    Standard error

    COB_SET_TRACE=1 ./trace 2>/dev/null left only the DISPLAY lines.

  3. What does -ftraceall add to -ftrace?

    Answer

    A line for every statement the run executes

    The traceall output names DISPLAY, PERFORM and STOP RUN with their lines.

  4. Why do the three DISPLAY lines come after the trace in a captured run?

    Answer

    Standard output was a block-buffered pipe and standard error was not buffered

    The trace went to standard error at once; standard output was flushed at the end.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 N PIC 9(2) VALUE 0. PROCEDURE DIVISION. PERFORM ADD-ONE 3 TIMES DISPLAY N. STOP RUN. ADD-ONE. ADD 1 TO N.

    Answer

    03

    Three PERFORMs of the paragraph add one each time.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W PIC X(5) VALUE "abcde". PROCEDURE DIVISION. DISPLAY FUNCTION REVERSE(W). STOP RUN.

    Answer

    edcba

    REVERSE returns the five characters in the other order.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 T. 05 T-X 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 DISPLAY T-X(I) MOVE 1 TO T-X(I) END-PERFORM. STOP RUN.

    Answer

    00 / 00 / 00 / 00

    Each entry is displayed before it is set, so all four lines are zero.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(3) VALUE 250. 01 B PIC 9(3) VALUE 250. 01 C PIC 9(3). PROCEDURE DIVISION. ADD A B GIVING C DISPLAY C. STOP RUN.

    Answer

    500

    250 plus 250 fits in three digits.

  9. What does the trace line for a paragraph tell you?

    Answer

    The program, the paragraph it entered and the source line of the header

    The lines name Program-Id, Paragraph and Line only.

  10. Why is a statement trace not left on in production?

    Answer

    One line per statement writes millions of lines on a large job

    A trace is turned on for a run, not left on.

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