Debugging and Troubleshooting

The Circulation LOANCHK program counts loans per copy slot. A book has three copies, so WS-SLOT has three entries, but the loop runs while the index is not greater than 4: a classic off-by-one.

Compiled with cobc -x -Wall LOANCHK.cob, with no warnings, the program runs to the end and prints a wrong answer without any complaint, which is the dangerous outcome:

The fourth slot is the first three bytes after the table, which here is WS-IDX and the start of WS-TOTAL; 10 was added to storage that belongs to other items, and the printed total is no longer meaningful. The page uses this program for every tool below.

Source: GnuCOBOL 3.2 manual: debug switches; Enterprise COBOL for z/OS 6.5 Programming Guide: Checking for valid ranges

Source: GnuCOBOL 3.2 manual: debug switches; GnuCOBOL 3.2 manual: compiler options

Recompiling the sample with -debug stops it at the first bad subscript and says where:

The program ends with exit status 1. The message gives the source line, the item, the bad value, the legal maximum and a call-stack style listing of paragraphs. Compiling with -g -fec=bound produced the same first line and the same exit status, with a shorter call listing (no ENTRY line).

A second common defect is invalid numeric data. The program BADNUM redefines three characters as a packed-decimal field and adds it to a total, which is what happens when a record with text in a numeric column is read:

Compiled with cobc -x -Wall BADNUM.cob, no warnings, the unchecked program prints garbage and truncates the second result silently:

Compiled with -debug it stops before the first DISPLAY:

The message shows the bytes found (41 42 43 are ABC in ASCII; on z/OS they would be EBCDIC C1 C2 C3). The COMPUTE that truncated 150 to 50 is not an error in either case because no ON SIZE ERROR phrase was coded and the standard says the result is then undefined; -fec=size did not report it in this run, so the dependable cure is to code the phrase, as Arithmetic and COMPUTE shows. On Enterprise COBOL the equivalent checks are the compiler options SSRANGE and NUMCHECK (see the performance page for their cost).

Source: GnuCOBOL 3.2 manual: exception names; Programming Guide: Checking for incompatible data

Trace code is generated at compile time but printed only when the environment variable COB_SET_TRACE is set to Y (or COB_TRACE_FILE names a file). With -ftrace the output is the program, entry and paragraph:

(That output is from the COV program of the coverage section; LOANCHK has a single paragraph and prints the same shape.) With -ftraceall every statement is shown with its line, which for the first iterations of the sample is:

Setting COB_TRACE_FILE=trace.log sends the trace to a file instead of the screen, which keeps a long batch run readable. A trace answers "which path did it take" and is the first thing to try when the data is correct but the result is not; for a wrong value, the next section is faster.

Source: GnuCOBOL 3.2 manual: debug switches and trace

A line with D in column 7 is a debugging line: it is compiled only when the program says WITH DEBUGGING MODE on SOURCE-COMPUTER (or the compiler is given -fdebugging-line), and is a comment otherwise. That allows DISPLAY statements that cost nothing in production to stay in the source.

Compiled with cobc -x -Wall DBGLINE.cob, no warnings, it prints:

Without WITH DEBUGGING MODE only the last line is printed; adding -fdebugging-line brings the first two back. With -std=ibm the same program prints fine=00420 and FINE 00420, because the IBM dialect does not insert the decimal point when displaying an item with an implied decimal point. On Enterprise COBOL the WITH DEBUGGING MODE clause works the same way, and the DEBUGGING declarative in the Language Reference is a separate, older facility that runs a section before each paragraph.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: DEBUGGING declarative; GnuCOBOL 3.2 manual: debug switches

Coverage answers "which statements did my test data run". The COV program is a corrected LOANCHK that adds a branch the test data never takes:

Compiled with cobc -x -Wall --coverage COV.cob, no warnings, run once (it prints TOTAL 0030), and then processed with gcov -o . COV, the program produces a COV.cob.gcov file whose lines are the COBOL source with counts:

##### marks the line that never ran, and gcov reported 91.67 percent of the 12 COBOL lines executed. gcov also prints messages about the generated C file when it is not at hand ("Cannot open source file"), which can be ignored when only the .cob.gcov file is used. The counts are per line of the generated C that maps to the source line, so a line with several statements shows one number.

Source: GnuCOBOL 3.2 manual: compiler options (--coverage)

A program compiled with -g can be stepped in GDB, and the manual and release notes of 3.2 describe improved support for stepping through the COBOL source rather than the generated C. A typical session sets a breakpoint on a source line (break LOANCHK.cob:14), runs, prints COBOL items through the generated C fields and uses bt for the stack. GDB was not available in the container used for this page, so no session is shown, and the exact printing of COBOL data items is left to the manual.

A program that fails on z/OS ends with a system completion code (an abend such as S0C7; S means system) or a user completion code (U4038; U means the program or Language Environment asked for it). Language Environment may convert a program interrupt into its own condition first; the completion code on the job log then comes with a message CEE3207S or CEE3250C style line from LE, and the message identifies the failing condition and program. The common ones for COBOL programs are these (z/OS; not run here).

The meaning of each code is documented in the z/OS messages and codes volumes and in the Language Environment debugging guide; the S0Cn rows follow the long-standing IBM definitions, while the "first thing to look at" column is practical advice, not a quotation.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: Requesting dumps; Programming Guide: Checking for valid ranges; IBM z/OS 3.2 documentation

When a condition is not handled, Language Environment writes a CEEDUMP to the CEEDUMP DD (or SYSOUT) if the run-time option TERMTHDACT asks for a dump (TRACE, DUMP or UADUMP). Its parts, in the order they appear, are these, and reading them in this order finds the failing statement:

To go from the offset to the COBOL statement, compile with OFFSET or LIST (and MAP) and look the offset up in the compiler listing: the listing shows each COBOL statement with its generated instructions and the offset where they start. With the TEST option the debugger tool can do the same step automatically. The tools that format dumps from a job (IBM Fault Analyzer, Broadcom Abend-AID and similar) are separate products; they are named here only so that a reader recognises the names at work.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: Requesting dumps; Programming Guide: TEST

The TEST compiler option adds debugging information to the load module: the data names, the statement table and (optionally) the hooks that let a debugger stop before each statement or only at paragraph starts. It makes the module larger and slower, so it is used on test builds only. The debug tool that reads it (IBM z/OS Debugger, or the VS Code debug extensions described on the tooling page) lets the programmer set breakpoints on a COBOL line, step, inspect and change data items by name and see the call stack. Enterprise COBOL 6 uses separate debug information (the SEPARATE suboption, kept in a file next to the listing) so the production module need not carry it; the suboptions and their default are in the TEST option page.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: TEST; Programming Guide: Debugging an AMODE 64 program