Summary of the cbl-gdb debugging commands

2020-08-31

When a COBOL program has been compiled using the cbl-gdb cobcd command, the resulting executable contains embedded instructions to load a set of debugging extensions, written in Python, when GDB is used to load the executable.

There are two commands implemented in the extension: print for displaying and changing variables, and cwatch for setting GDB watchpoints based on COBOL variable names.

The print command

    print/h              -- prints a list of the print commands
    print <var>          -- prints the variable
    print <var> = <newv> -- alters the value of <var> to <newv>
    print/d <var>        -- prints <var> in a verbose debugging format
    print *              -- prints all variables
    print ?              -- prints the variables referenced within
                         -- +/- RANGE lines of the current program line.
                         -- RANGE defaults to 6
    print/r N            -- changes the ? RANGE to +/- N lines
    print/r -1           -- makes "p ?" the same as "p *"
    print/r              -- prints the value of RANGE
    print/m <var>        -- prints <var> in GDB machine-interface format
    print/v0 <var>       -- prints <var> as <name : value> on one line
    print/v1 <var>       -- prints just the value
    print/v2 <var>       -- prints <var> as name and value on two lines
    print/v[0|1|2]       -- changes the session format to v0, v1, or v2
    print set repeat N   -- sets the <repeats N times> threshold
    print set repeat -1  -- turns    <repeats N times> counting off

The cwatch command

    cwatch <var>      -- sets a watchpoint on <var>
                      -- execution halts when the value of <var> changes

Environment variables

There are three environment variables that control how the Python extension loads:

    CPRINT_R=N       -- Changes default "p ?" to +/- N
    CPRINT_V=[0|1|2] -- Changes default /v formatting to v0, v1, or v2
    CPRINT=1         -- (See below)

The CPRINT=1 switch is of interest primarily to users who are developing and debugging the COBOL compiler, and debugging the C code that the COBOL compiler generates. As mentioned above, by default the Python implementation of the print command replaces the native GDB print command.

By setting the CPRINT=1 environment variable, the COBOL variable printing command is set to cprint, which means that the native print command is still available.

In this way, when trapping through the COBOL executable, cprint can be used to look at COBOL variables, and print can be used to look at C variables.

Basic print command semantics

When a debuggable COBOL program has been launched by GDB and execution has been stopped, the print command is used to access COBOL variables by name.

Because GDB allows trailing characters of commands to be omitted (as long as the resulting abbreviated command is unambiguous), p is the same as print.

Considerable flexibility is provided for finding variables within the context of the heirarchical description of COBOL variables.

Consider

    10 USER.
        20 NAME.
            30  FIRST PIC X(20).
            30  LAST  PIC X(20).

    10 AGENT.
        20 NAME.
            30  FIRST PIC X(20).
            30  LAST  PIC X(20).

the command print first will report two numbered lines:

1 : 30 FIRST/NAME/USER/program-id : "first name"
2 : 30 FIRST/NAME/AGENT/program-id : "first name"

Once this list has been shown to you, you can reference one of the results by number:

print 1 shows you

30 FIRST/NAME/USER/program-id : "first name"

You can also use COBOL-like references:

    print 1
    print first of user
    print first in user
    print first/user (deprecated)
    print first.user (deprecated)

Those all result in the same output:

30 FIRST/NAME/USER/program-id : "first name"

The print command is also used for altering variables. These commands:

    print 1 = newval
    print first of user = newval
    print first in user = newval
    print first/user = newval
    print first.user = newval

are all equivalent, They all result in

30 FIRST/NAME/USER/program-id : "newval"