4.4.3 Suspending Program Execution
The SET BREAK command lets you select breakpoints ,
which are locations at which the program will stop running.
When you reach a breakpoint, you can enter commands to
check the call stack, examine the current values of variables,
and so on.
A typical use of the SET BREAK command is shown in the
following example:
DBG> SET BREAK COUNTER
DBG> GO
.
.
.
break at TEST\COUNTER
34: SUB COUNTER(LONG X,Y)
DBG>
In this example, the SET BREAK command sets a breakpoint
on the subprogram COUNTER; the GO command starts ex-
ecution. When the subprogram COUNTER is encountered,
execution is suspended, the debugger announces that the
breakpoint at COUNTER has been reached (break at . . . ),
displays the source line (34) where execution is suspended,
and prompts you for another command. At this breakpoint,
you can step through the subprogram COUNTER, using
the STEP command, and use the EXAMINE command (see
Section 4.5.1) to check on the current values of X and Y.
When using the SET BREAK command, you can specify pro-
gram locations using various kinds of address expressions (for
example, line numbers, routine names, instructions, virtual
memory addresses). With high-level languages, you typi-
cally use routine names, labels, or line numbers, possibly with
directory specifications to ensure uniqueness.
Routine names and labels should be specified as they appear
in the source code. Line numbers may be derived from ei-
ther a source code display or a listing file. When specifying
a line number, use the prefix %LINE. (Otherwise, the de-
bugger will interpret the line number as a memory location.)
For example, the next command sets a breakpoint at line 41
of the currently executing module; the debugger will suspend
execution when the PC is at the start of line 41:
DBG> SET BREAK %LINE 41
Note that you can set breakpoints only on lines that resulted
in machine code instructions. The debugger warns you if you
try to do otherwise (for example, on a comment line). If you
want to pick a line number in a module other than the one
currently executing, you need to specify the module's name
in a directory specification. For example:
DBG> SET BREAK SCREEN_IO\%LINE 58
You do not always have to specify a particular program lo-
cation, such as line 58 or COUNTER, to set a breakpoint.
You can set breakpoints on events, such as exceptions. You
can use the SET BREAK command with a qualifier, but
no parameter, to break on every line, or on every CALL
instruction, and so on. For example:
DBG> SET BREAK/LINE
DBG> SET BREAK/CALL
You can conditionalize a breakpoint (with a WHEN clause)
or specify that a list of commands be executed at the break-
point (with a DO clause on the debugger command). For
example, the next command sets a breakpoint on the la-
bel LOOP3. The DO (EXAMINE TEMP) clause causes the
value of the variable TEMP to be displayed whenever the
breakpoint is triggered.
DBG> SET BREAK LOOP3 DO (EXAMINE TEMP)
DBG> GO
.
.
.
break at COUNTER\LOOP3
37: LOOP3: FOR I = 1 TO 10
COUNTER\TEMP: 284.19
DBG>
To display the currently active breakpoints, enter the SHOW
BREAK command:
DBG> SHOW BREAK
breakpoint at SCREEN_IO\%LINE 58
breakpoint at COUNTER\LOOP3
do (EXAMINE TEMP)
.
.
.
DBG>
To cancel a breakpoint, enter the CANCEL BREAK com-
mand, specifying the program location exactly as you did
when setting the breakpoint. The CANCEL BREAK/ALL
command cancels all breakpoints.