Establishes a breakpoint at the location denoted by an address
expression, at instructions of a particular class, or at the
occurrence of specified events.
Format
SET BREAK [address-expression[, . . . ]]
[WHEN(conditional-expression)]
[DO(command[; . . . ])]
1 – Parameters
address-expression
Specifies an address expression (a program location) at which
a breakpoint is to be set. With high-level languages, this
is typically a line number, a routine name, or a label, and
can include a path name to specify the entity uniquely. More
generally, an address expression can also be a memory address or
a register and can be composed of numbers (offsets) and symbols,
as well as one or more operators, operands, or delimiters. For
information about the operators that you can use in address
expressions, see the Address_Expressions help topic.
Do not specify the asterisk (*) wildcard character. Do not
specify an address expression with any of the following
qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/HANDLER
/INSTRUCTION
/INTO
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/SYSEMULATE (Alpha only)
/TERMINATING
/UNALIGNED_DATA (Alpha and Integrity servers only)
The /MODIFY and /RETURN qualifiers are used with specific kinds
of address expressions.
If you specify a memory address or an address expression whose
value is not a symbolic location, check (with the EXAMINE
command) that an instruction actually begins at the byte of
memory so indicated. If an instruction does not begin at this
byte, a run-time error can occur when an instruction including
that byte is executed. When you set a breakpoint by specifying
an address expression whose value is not a symbolic location, the
debugger does not verify that the location specified marks the
beginning of an instruction.
conditional-expression
Specifies a conditional expression in the currently set
language that is to be evaluated whenever execution reaches the
breakpoint. (The debugger checks the syntax of the expressions in
the WHEN clause when execution reaches the breakpoint, not when
the breakpoint is set.) If the expression is true, the debugger
reports that a breakpoint has been triggered. If an action (DO
clause) is associated with the breakpoint, it will occur at this
time. If the expression is false, a report is not issued, the
commands specified by the DO clause (if one was specified) are
not executed, and program execution is continued.
command
Specifies a debugger command to be executed as part of the DO
clause when break action is taken. The debugger checks the syntax
of the commands in a DO clause when it executes the DO clause,
not when the breakpoint is set.
2 – Qualifiers
2.1 /ACTIVATING
Causes the debugger to break when a new process comes under
debugger control. The debugger prompt is displayed when the first
process comes under debugger control. This enables you to enter
debugger commands before the program has started execution. See
also the /TERMINATING qualifier.
2.2 /AFTER
/AFTER:n
Specifies that break action not be taken until the nth time the
designated breakpoint is encountered (n is a decimal integer).
Thereafter, the breakpoint occurs every time it is encountered
provided that conditions in the WHEN clause (if specified) are
true. The SET BREAK/AFTER:1 command has the same effect as SET
BREAK.
2.3 /BRANCH
Causes the debugger to break on every branch instruction
encountered during program execution. See also the /INTO and
/OVER qualifiers.
2.4 /CALL
Causes the debugger to break on every call instruction
encountered during program execution, including the RET
instruction. See also the /INTO and /OVER qualifiers.
2.5 /EVENT
/EVENT=event-name
Causes the debugger to break on the specified event (if that
event is defined and detected by the current event facility).
If you specify an address expression with /EVENT, causes the
debugger to break whenever the specified event occurs for that
address expression. You cannot specify an address expression with
certain event names.
Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX threads services. Use the SHOW EVENT_
FACILITY command to identify the current event facility and the
associated event names.
2.6 /EXCEPTION
Causes the debugger to break whenever an exception is signaled.
The break action occurs before any application-declared exception
handlers are invoked.
As a result of a SET BREAK/EXCEPTION command, whenever your
program generates an exception, the debugger suspends program
execution, reports the exception, and displays its prompt. When
you resume execution from an exception breakpoint, the behavior
is as follows:
o If you enter a GO command without an address-expression
parameter, the exception is resignaled, thus allowing any
application-declared exception handler to execute.
o If you enter a GO command with an address-expression
parameter, program execution continues at the specified
location, thus inhibiting the execution of any application-
declared exception handler.
On Alpha, you must explicitly set a breakpoint in the
exception handler before entering a STEP or a GO command to
get the debugger to suspend execution within the handler.
o If you enter a CALL command, the routine specified is
executed.
On Alpha processors, an exception might not be delivered (to
the program or debugger) immediately after the execution of the
instruction that caused the exception. Therefore, the debugger
might suspend execution on an instruction beyond the one that
actually caused the exception.
2.7 /HANDLER
Causes the debugger to scan the call stack and attempt to set a
breakpoint on every established frame-based handler whenever the
program being debugged has an exception. The debugger does not
discriminate between standard RTL handlers and user-established
handlers.
On Alpha and Integrity servers, most RTLs establish a jacket
RTL handler on a frame where the user program has defined a
handler. The RTL jacket performs setup, argument manipulation,
and dispatch to the user written handlers. When processing the
exception, the debugger can only set the breakpoint on the RTL
jacket handler, because that is the address on the call stack. If
the debugger suspends program execution in a jacket RTL handler,
you can usually reach the user-defined handler by finding the
dispatch point(s) via some number of STEP/CALLs followed by a
STEP/INTO.
See the OpenVMS Calling Standard for more information on frame-
based handlers.
If the jacket RTL handler is part of an installed shared image
such as ALPHA LIBOTS, the debugger cannot set a breakpoint on it
(no private user mode write access). In this case, activate ALL
RTLs as private images via logical names. For example:
$DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;
Note that the trailing semicolon (;) is required. Note also that
all (or none) of your shared installed RTLs should be activated
privately. Use SHOW IMAGE/FULL data to realize the list of images
with system space code sections and then define logicals for all
of them and rerun your debug session.
2.8 /INSTRUCTION
/INSTRUCTION
/INSTRUCTION[=(opcode[, . . . ])]
When you do not specify an opcode, causes the debugger to break
on every instruction encountered during program execution.
See also the /INTO and /OVER qualifiers.
2.9 /INTO
(Default) Applies only to breakpoints set with the following
qualifiers (that is, when an address expression is not explicitly
specified):
/BRANCH
/CALL
/INSTRUCTION
/LINE
When used with those qualifiers, /INTO causes the debugger to
break at the specified points within called routines (as well as
within the routine in which execution is currently suspended).
The /INTO qualifier is the default and is the opposite of /OVER.
When using /INTO, you can further qualify the break action with
/[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM.
2.10 /LINE
Causes the debugger to break on the beginning of each source
line encountered during program execution. See also the /INTO and
/OVER qualifiers.
2.11 /MODIFY
Causes the debugger to break on every instruction that writes to
and modifies the value of the location indicated by the address
expression. The address expression is typically a variable name.
The SET BREAK/MODIFY command acts exactly like a SET WATCH
command and operates under the same restrictions.
If you specify an absolute address for the address expression,
the debugger might not be able to associate the address with
a particular data object. In this case, the debugger uses a
default length of 4 bytes. You can change this length, however,
by setting the type to either WORD (SET TYPE WORD, which changes
the default length to 2 bytes) or BYTE (SET TYPE BYTE, which
changes the default length to 1 byte). SET TYPE LONGWORD restores
the default length of 4 bytes.
2.12 /OVER
Applies only to breakpoints set with the following qualifiers
(that is, when an address expression is not explicitly
specified):
/BRANCH
/CALL
/INSTRUCTION
/LINE
When used with those qualifiers, /OVER causes the debugger to
break at the specified points only within the routine in which
execution is currently suspended (not within called routines).
The /OVER qualifier is the opposite of /INTO (which is the
default).
2.13 /RETURN
Causes the debugger to break on the return instruction of the
routine associated with the specified address expression (which
can be a routine name, line number, and so on). Breaking on the
return instruction enables you to inspect the local environment
(for example, obtain the values of local variables) while
the routine is still active. Note that the view of a local
environment may differ depending on your architecture. On Alpha
processors, this qualifier can be applied to any routine.
The address-expression parameter is an instruction address within
a routine. It can simply be a routine name, in which case it
specifies the routine start address. However, you can also
specify another location in a routine, so you can see only those
returns that are taken after a certain code path is followed.
A SET BREAK/RETURN command cancels a previous SET BREAK if you
specify the same address expression.
2.14 /SHARE
/SHARE (default)
/NOSHARE
Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/LINE
The /SHARE qualifier permits the debugger to break within
shareable image routines as well as other routines. The /NOSHARE
qualifier specifies that breakpoints not be set within shareable
images.
2.15 /SILENT
/SILENT
/NOSILENT (default)
Controls whether the "break . . . " message and the source line
for the current location are displayed at the breakpoint. The
/NOSILENT qualifier specifies that the message is displayed. The
/SILENT qualifier specifies that the message and the source line
are not displayed. The /SILENT qualifier overrides /SOURCE. See
also the SET STEP [NO]SOURCE command.
2.16 /SOURCE
/SOURCE (default)
/NOSOURCE
Controls whether the source line for the current location is
displayed at the breakpoint. The /SOURCE qualifier specifies that
the source line is displayed. The /NOSOURCE qualifier specifies
that no source line is displayed. The /SILENT qualifier overrides
/SOURCE. See also the SET STEP [NO]SOURCE command.
2.17 /SYSEMULATE
/SYSEMULATE[=mask]
(Alpha only) Stops program execution and returns control to the
debugger after the operating system emulates an instruction.
The optional argument mask is an unsigned quadword with bits
set to specify which emulated instruction groups shall cause
breakpoints. The only emulated instruction group currently
defined consists of the BYTE and WORD instructions. Select this
instruction group by setting bit 0 of mask to 1.
If mask is not specified or if mask = FFFFFFFFFFFFFFFF, the
debugger stops program execution when the operating system
emulates any instruction.
2.18 /SYSTEM
/SYSTEM (default)
/NOSYSTEM
Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/LINE
The /SYSTEM qualifier permits the debugger to break within system
routines (P1 space) as well as other routines. The /NOSYSTEM
qualifier specifies that breakpoints not be set within system
routines.
2.19 /TEMPORARY
Causes the breakpoint to disappear after it is triggered (the
breakpoint does not remain permanently set).
2.20 /TERMINATING
Causes the debugger to break when a process does an image exit.
The debugger gains control and displays its prompt when the
last image of a one-process or multiprocess program exits. A
process is terminated when the image has executed the $EXIT
system service and all of its exit handlers have executed. See
also the /ACTIVATING qualifier.
2.21 /UNALIGNED_DATA
(Alpha and Integrity servers only) Causesthe debugger to break
directly after any instruction that accesses unaligned data (for
example, after a load word instruction that accesses data that is
not on a word boundary).
3 – Description
When a breakpoint is triggered, the debugger takes the following
actions:
1. Suspends program execution at the breakpoint location.
2. If you specified /AFTER when you set the breakpoint, checks
the AFTER count. If the specified number of counts has not
been reached, execution resumes and the debugger does not do
the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the breakpoint. If the value of the
expression is false, execution resumes and the debugger does
not do the remaining steps.
4. Reports that execution has reached the breakpoint location by
issuing a "break . . . " message, unless you specified /SILENT.
5. Displays the line of source code at which execution is
suspended, unless you specified /NOSOURCE or /SILENT when
you set the breakpoint or unless you previously entered SET
STEP NOSOURCE.
6. Executes the commands in a DO clause, if you specified one
when you set the breakpoint. If the DO clause contains a GO
command, execution continues and the debugger does not perform
the next step.
7. Issues the prompt.
You set a breakpoint at a particular location in your program
by specifying an address expression with the SET BREAK command.
You set a breakpoint on consecutive source lines, classes of
instructions, or events by specifying a qualifier with the SET
BREAK command. Generally, you must specify either an address
expression or a qualifier, but not both. Exceptions are /EVENT
and /RETURN.
The /LINE qualifier sets a breakpoint on each line of source
code.
The following qualifiers set breakpoints on classes of
instructions. Using these qualifiers with /LINE causes the
debugger to trace every instruction of your program as it
executes and thus significantly slows down execution:
/BRANCH
/CALL
/INSTRUCTION
/RETURN
The following qualifiers affect what happens at a routine call:
/INTO
/OVER
/[NO]SHARE
/[NO]SYSTEM
4 – Description, Continued...
The following qualifiers affect what output is displayed when a
breakpoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of
breakpoints:
/AFTER:n
/TEMPORARY
Use the /MODIFY qualifier to monitor changes at program locations
(typically changes in the values of variables).
If you set a breakpoint at a location currently used as
a tracepoint, the tracepoint is canceled in favor of the
breakpoint, and vice versa.
On OpenVMS Alpha and Integrity servers, the SET BREAK/UNALIGNED_
DATA command calls the $START_ALIGN_FAULT_REPORT system service
routine. Do not issue this command if the program you are
debugging includes a call to the same $START_ALIGN_FAULT_REPORT
routine. If you issue the command before the program call, the
program call fails. If the program call occurs before you issue
the command, unaligned breaks are not set.
Breakpoints can be user defined or predefined. User-defined
breakpoints are set explicitly with the SET BREAK command.
Predefined breakpoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are established
automatically when you start the debugger. Use the SHOW BREAK
command to identify all breakpoints that are currently set. Any
predefined breakpoints are identified as such.
User-defined and predefined breakpoints are set and canceled
independently. For example, a location or event can have both
a user-defined and a predefined breakpoint. Canceling the user-
defined breakpoint does not affect the predefined breakpoint, and
conversely.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) BREAK
CANCEL ALL
GO
(SET,SHOW) EVENT_FACILITY
SET STEP [NO]SOURCE
SET TRACE
SET WATCH
STEP
5 – Examples
1.DBG> SET BREAK SWAP\%LINE 12
This command causes the debugger to break on line 12 of module
SWAP.
2.DBG> SET BREAK/AFTER:3 SUB2
This command causes the debugger to break on the third and
subsequent times that SUB2 (a routine) is executed.
3.DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAM D; STEP; EXAM Y; GO)
This command causes the debugger to break at location LOOP1. At
the breakpoint, the following commands are issued, in the order
given: (1) EXAMINE D, (2) STEP, (3) EXAMINE Y, and (4) GO.
The /NOSOURCE qualifier suppresses the display of source code
at the breakpoint.
4.DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y)
This command causes the debugger to break on routine ROUT3 when
X is greater than 4. At the breakpoint, the EXAMINE Y command
is issued. The syntax of the conditional expression in the WHEN
clause is language-dependent.
5.DBG> SET BREAK/TEMPORARY 1440
DBG> SHOW BREAK
breakpoint at 1440 [temporary]
DBG>
This command sets a temporary breakpoint at memory address
1440. After that breakpoint is triggered, it disappears.
6.DBG> SET BREAK/LINE
This command causes the debugger to break on the beginning of
every source line encountered during program execution.
7.DBG> SET BREAK/LINE WHEN (X .NE. 0)
DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 0)
These two commands cause the debugger to break when X is not
equal to 0. The first command tests for the condition at the
beginning of every source line encountered during execution.
The second command tests for the condition at each instruction.
The syntax of the conditional expression in the WHEN clause is
language-dependent.
8.DBG> SET BREAK/RETURN ROUT4
This command causes the debugger to break whenever the return
instruction of routine ROUT4 is about to be executed.
9.DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS)
This command causes the debugger to break whenever an exception
is signaled. At the breakpoint, the SET MODULE/CALLS and SHOW
CALLS commands are issued.
10all> SET BREAK/ACTIVATING
This command causes the debugger to break whenever a process of
a multiprocess program is brought under debugger control.