/SYSTEM (default)

/NOSYSTEM

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.

/TEMPORARY

Causes the breakpoint to disappear after it is triggered (the
breakpoint does not remain permanently set).

/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.

/UNALIGNED_DATA

(Alpha only) Causes the 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).

/VECTOR_INSTRUCTION

(VAX only) Causes the debugger to break on every vector instruction
encountered during program execution. See also the /INTO and /OVER
qualifiers.

Description

When a breakpoint is triggered, the debugger takes the following
actions:

Suspends program execution at the breakpoint location.

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.

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.

Reports that execution has reached the breakpoint location by
issuing a "break..." message, unless you specified /SILENT.

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.

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.

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:

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 systems, 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.

Examples

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 (EXAMINE D; STEP; EXAMINE 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.

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/INSTRUCTION=ADDL3

(VAX only) This command causes the debugger to break whenever the
instruction ADDL3 is about to be executed.

#9

DBG> SET BREAK/LINE/INTO/NOSHARE/NOSYSTEM

This command causes the debugger to break on the beginning of every
source line, including lines in called routines (/INTO) but not in
shareable image routines (/NOSHARE) or system routines (/NOSYSTEM).

#10

DBG> SET BREAK/RETURN ROUT4

This command causes the debugger to break whenever the return
instruction of routine ROUT4 is about to be executed.

#11

DBG> SET BREAK/RETURN %LINE 14

This command causes the debugger to break whenever the return
instruction of the routine that includes line 14 is about to be
executed. This form of the command is useful if execution is currently
suspended within a routine and you want to set a breakpoint on that
routine's return instruction.

#12

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.

#13

DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3

This command sets two breakpoints, which are associated with task
RESERVE and task 3 (task ID = 3), respectively. Each breakpoint is
triggered whenever its associated task makes a transition to the RUN
state.

#14

all> SET BREAK/ACTIVATING

This command causes the debugger to break whenever a process of a
multiprocess program is brought under debugger control.

Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_GROUP, or
/VALUE) for the DEFINE command.

Format

SET DEFINE define-default

Parameters

define-default

Specifies the default to be established for the DEFINE command. Valid
keywords (which correspond to DEFINE command qualifiers) are as follows:

ADDRESS

Subsequent DEFINE commands are treated as DEFINE/ADDRESS. This is the
default.

COMMAND

Subsequent DEFINE commands are treated as DEFINE/COMMAND.

PROCESS_SET

Subsequent DEFINE commands are treated as DEFINE/PROCESS_SET.

VALUE

Subsequent DEFINE commands are treated as DEFINE/VALUE.

Description

The SET DEFINE command establishes a default qualifier for subsequent
DEFINE commands. The parameters that you specify in the SET DEFINE
command have the same names as the qualifiers for the DEFINE command.
The qualifiers determine whether the DEFINE command binds a symbol to
an address, a command string, a list of processes, or a value.

You can override the current DEFINE default for the duration of a
single DEFINE command by specifying another qualifier. Use the SHOW
DEFINE command to identify the current DEFINE defaults.

Related commands:

DEFINE
DEFINE/PROCESS_SET
DELETE
SHOW DEFINE
SHOW SYMBOL/DEFINED

Example

DBG> SET DEFINE VALUE

The SET DEFINE VALUE command specifies that subsequent DEFINE commands
are treated as DEFINE/VALUE.

Format

SET EDITOR [command-line]

Parameters

command-line

Specifies a command line to start a particular editor on your system
when you use the EDIT command.

You need not specify a command line if you use /CALLABLE_EDT,
/CALLABLE_LSEDIT, or /CALLABLE_TPU. If you do not use one of these
qualifiers, the editor specified in the SET EDITOR command line is
spawned to a subprocess when you enter the EDIT command.

You can specify a command line with /CALLABLE_LSEDIT or /CALLABLE_TPU
but not with /CALLABLE_EDT.

Qualifiers

/CALLABLE_EDT

Specifies that the callable version of the EDT editor is started when
you use the EDIT command. Do not specify a command line with this
qualifier (a command line of "EDT" is used).

/CALLABLE_LSEDIT

(VAX only) Specifies that the callable version of the DEC
Language-Sensitive Editor (LSEDIT) is started when you use the EDIT
command. If you also specify a command line, it is passed to callable
LSEDIT. If you do not specify a command line, the default command line
is LSEDIT.

/CALLABLE_TPU

Specifies that the callable version of the DEC Text Processing Utility
(DECTPU) is started when you use the EDIT command. If you also specify
a command line, it is passed to callable DECTPU. If you do not specify
a command line, the default command line is TPU.

/START_POSITION

/NOSTART_POSITION (default)

Controls whether the /START_POSITION qualifier is appended to the
specified or default command line when you enter the EDIT command.
Currently, only DECTPU and the DEC Language-Sensitive Editor (specified
as TPU or /CALLABLE_TPU, and LSEDIT or /CALLABLE_LSEDIT, respectively)
support this qualifier.

The /START_POSITION qualifier affects the initial position of the
editor's cursor. By default (/NOSTART_POSITION), the editor's cursor is
placed at the beginning of source line 1, regardless of which line is
centered in the debugger's source display or whether you specify a line
number in the EDIT command. If you specify /START_POSITION, the cursor
is placed either on the line whose number you specify in the EDIT
command, or (if you do not specify a line number) on the line that is
centered in the current source display.

Description

The SET EDITOR command enables you to specify any editor that is
installed on your system. In general, the command line specified as
parameter to the SET EDITOR command is spawned and executed in a
subprocess.

On VAX processors, if you use EDT, LSEDIT, or DECTPU, you can start
these editors in a more efficient way. You can specify /CALLABLE_EDT,
/CALLABLE_LSEDIT, or /CALLABLE_TPU, which causes the callable versions
of EDT, LSEDIT, and DECTPU, respectively, to be invoked by the EDIT
command. In the case of LSEDIT and DECTPU, you can also specify a
command line that is executed by the callable editor.

On Alpha processors, you can use /CALLABLE_EDT or /CALLABLE_TPU, but not
/CALLABLE_LSEDIT.

Related commands:

EDIT
(SET,SHOW,CANCEL) SOURCE
SHOW DEFINE

Examples

#1

DBG> SET EDITOR '@MAIL$EDIT ""'

This command causes the EDIT command to spawn the command line
'@MAIL$EDIT ""', which starts the same editor as you use in MAIL.

#2

DBG> SET EDITOR/CALLABLE_TPU

This command causes the EDIT command to start callable DECTPU with the
default command line of TPU.

#3

DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION

This command causes the EDIT command to start callable DECTPU with the
command line TPU/SECTION=MYSECINI.TPU$SECTION.

#4

DBG> SET EDITOR/CALLABLE_EDT/START_POSITION

This command causes the EDIT command to start callable EDT with the
default command line of EDT. Also the /START_POSITION qualifier is
appended to the command line, so that the editing session starts on the
source line that is centered in the debugger's current source display.

Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX Threads services.

Format

SET EVENT_FACILITY facility-name

Parameters

facility-name

Specifies an event facility. Valid facility-name
keywords are as follows:

ADA

If the event facility is set to ADA, the (SET,CANCEL) BREAK and
(SET,CANCEL) TRACE commands recognize Ada-specific events as well as
generic, low-level task events. (Ada events consist of task and
exception events.)

You can set the event facility to ADA only if the main program is
written in Ada or if the program calls an Ada routine.

THREADS

If the event facility is set to THREADS, the (SET,CANCEL) BREAK and
(SET,CANCEL) TRACE commands recognize POSIX Threads-specific as well
as generic, low-level task events. All POSIX Threads events are task
(thread) events.

You can set the event facility to THREADS only if the shareable
image CMA$RTL is currently part of the program's process (if that image
is listed in a SHOW IMAGE display).

SCAN

(VAX only) If the event facility is set to SCAN, the (SET,CANCEL) BREAK
and (SET,CANCEL) TRACE commands recognize SCAN (pattern-matching)
events.

You can set the event facility to SCAN only if the main program is
written in SCAN or if the program calls a SCAN routine.

Description

The current event facility (ADA, THREADS, or SCAN) defines the
eventpoints that you can set with the SET BREAK/EVENT and SET
TRACE/EVENT commands.

When started with a program that is linked with an event facility, the
debugger automatically sets the facility in a manner appropriate for
the type of program. For example, if the main program is written in Ada
or SCAN, the event facility is set to ADA or SCAN, respectively.

The SET EVENT_FACILITY command enables you to change the event facility
and thereby change your debugging context. This is useful if you have a
multilanguage program and want to debug a routine that is associated
with an event facility but that facility is not currently set.

On VAX processors, you cannot use both Ada and POSIX Threads tasking
services in the same program. This implies that you can change the
event facility only from ADA to SCAN or from POSIX Threads to SCAN, or
conversely.

Use the SHOW EVENT_FACILITY command to identify the event names
associated with the current event facility. These are the keywords that
you can specify with the (SET,CANCEL) BREAK/EVENT and (SET,CANCEL)
TRACE/EVENT commands.

Related commands:

(SET,CANCEL) BREAK/EVENT
(SET,CANCEL) TRACE/EVENT
SHOW BREAK
SHOW EVENT_FACILITY
SHOW IMAGE
SHOW TASK
SHOW TRACE

Example

DBG> SET EVENT_FACILITY THREADS

This command establishes THREADS (POSIX Threads) as the current event
facility.

Loads symbol information for one or more shareable images and
establishes the current image.

Format

SET IMAGE [image-name[,...]]

Parameters

image-name

Specifies a shareable image to be set. Do not use the asterisk (*)
wildcard character. Instead, use the /ALL qualifier. Do not specify an
image name with /ALL.

Qualifiers

/ALL

Specifies that all shareable images are set.

Description

The SET IMAGE command builds data structures for one or more specified
images but does not set any modules within the images specified.

The current image is the current debugging context: you have access to
symbols in the current image. If you specify only one image with the
SET IMAGE command, that image becomes the current image. If you specify
a list of images, the last one in the list becomes the current image.
If you specify /ALL, the current image is unchanged.

Before an image can be set with the SET IMAGE command, it must have
been linked with the /DEBUG or /TRACEBACK qualifier on the DCL command
LINK. If an image was linked /NOTRACEBACK, no symbol information is
available for that image and you cannot specify it with the SET IMAGE
command.

Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands
are available only when the image in whose context they were created is
the current image. When you use the SET IMAGE command to establish a
new current image, these definitions are temporarily unavailable.
However, definitions created with the DEFINE/COMMAND and DEFINE/KEY
commands are available for all images.

Related commands:

SET MODE [NO]DYNAMIC
(SET,SHOW,CANCEL) MODULE
(SHOW,CANCEL) IMAGE

Example

DBG> SET IMAGE SHARE1
DBG> SET MODULE SUBR
DBG> SET BREAK SUBR

This sequence of commands shows how to set a breakpoint on routine SUBR
in module SUBR of shareable image SHARE1. The SET IMAGE command sets
the debugging context to SHARE1. The SET MODULE command loads the
symbol records of module SUBR into the run-time symbol table (RST). The
SET BREAK command sets a breakpoint on routine SUBR.