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"