1 – ABORT_KEY
Assigns the debugger's abort function to another Ctrl-key
sequence. By default, Ctrl/C does the abort function.
NOTE
This command is not available in the VSI DECwindows Motif for
OpenVMS user interface to the debugger.
Format
SET ABORT_KEY = CTRL_character
1.1 – Parameters
character
Specifies the key you press while holding down the Ctrl key. You
can specify any alphabetic character.
1.2 – Description
By default, the Ctrl/C sequence, when entered within a debugging
session, aborts the execution of a debugger command and
interrupts program execution. The SET ABORT_KEY command enables
you to assign the abort function to another Ctrl-key sequence.
This might be necessary if your program has a Ctrl/C AST service
routine enabled.
Many Ctrl-key sequences have predefined functions, and the SET
ABORT_KEY command enables you to override such definitions (see
the OpenVMS User's Manual). Some of the Ctrl-key characters not
used by the operating system are G, K, N, and P.
The SHOW ABORT_KEY command identifies the Ctrl-key sequence
currently in effect for the abort function.
Do not use Ctrl/Y from within a debugging session. Instead, use
either Ctrl/C or an equivalent Ctrl-key sequence established with
the SET ABORT_KEY command.
Related commands:
Ctrl/C
Ctrl/Y
SHOW ABORT_KEY
1.3 – Example
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> GO
. . .
<Ctrl/C>
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
<Ctrl/C>
%DEBUG-W-ABORTED, command aborted by user request
DBG> SET ABORT_KEY = CTRL_P
DBG> GO
. . .
<Ctrl/P>
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
<Ctrl/P>
%DEBUG-W-ABORTED, command aborted by user request
DBG>
This example shows the following:
o Use of Ctrl/C for the abort function (default).
o Use of the SET ABORT_KEY command to reassign the abort
function to Ctrl/P.
2 – ATSIGN
Establishes the default file specification that the debugger uses
when searching for command procedures.
Format
SET ATSIGN file-spec
2.1 – Parameters
file-spec
Specifies any part of a file specification (for example, a
directory name or a file type) that the debugger is to use
by default when searching for a command procedure. If you do
not supply a full file specification, the debugger assumes
SYS$DISK:[]DEBUG.COM as the default file specification for any
missing field.
You can specify a logical name that translates to a search list.
In this case, the debugger processes the file specifications
in the order they appear in the search list until the command
procedure is found.
2.2 – Description
When you invoke a debugger command procedure with the execute
procedure (@) command, the debugger assumes, by default, that the
command procedure file specification is SYS$DISK:[]DEBUG.COM. The
SET ATSIGN command enables you to override this default.
Related commands:
@ (Execute Procedure)
SHOW ATSIGN
2.3 – Example
DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> @TEST
In this example, when you use the @TEST command, the debugger
looks for the file TEST.DBG in USER:[JONES.DEBUG].
3 – BREAK
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[; . . . ])]
3.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.
3.2 – Qualifiers
3.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.
3.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.
3.2.3 /BRANCH
Causes the debugger to break on every branch instruction
encountered during program execution. See also the /INTO and
/OVER qualifiers.
3.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.
3.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.
3.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.
3.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.
3.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.
3.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.
3.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.
3.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.
3.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).
3.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.
3.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.
3.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.
3.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.
3.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.
3.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.
3.2.19 /TEMPORARY
Causes the breakpoint to disappear after it is triggered (the
breakpoint does not remain permanently set).
3.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.
3.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.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
3.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
3.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.
4 – DEFINE
Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_
GROUP, or /VALUE) for the DEFINE command.
Format
SET DEFINE define-default
4.1 – 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.
4.2 – 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
4.3 – Example
DBG> SET DEFINE VALUE
The SET DEFINE VALUE command specifies that subsequent DEFINE
commands are treated as DEFINE/VALUE.
5 – EDITOR
Establishes the editor that is started by the EDIT command.
Format
SET EDITOR [command-line]
5.1 – 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.
5.2 – Qualifiers
5.2.1 /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).
5.2.2 /CALLABLE_TPU
Specifies that the callable version of the VSI Text Processing
Utility (TPU) is started when you use the EDIT command. If you
also specify a command line, it is passed to callable TPU. If
you do not specify a command line, the default command line is
TPU.
5.2.3 /START_POSITION
/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 TPU and the VSI 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.
5.3 – 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 Alpha and Integrity servers, if you use EDT, LSEDIT, or
TPU, you can start these editors in a more efficient way.
You can specify /CALLABLE_EDT or /CALLABLE_TPU which causes the
callable versions of EDT and TPU respectively, to be invoked
by the EDIT command. In the case of TPU, 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
5.4 – 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 TPU
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 TPU
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.
6 – EVENT_FACILITY
Establishes the current event facility.
Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX threads services.
Format
SET EVENT_FACILITY facility-name
6.1 – 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).
6.2 – 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.
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
6.3 – Example
DBG> SET EVENT_FACILITY THREADS
This command establishes THREADS (POSIX threads) as the current
event facility.
7 – IMAGE
Loads symbol information for one or more shareable images and
establishes the current image.
Format
SET IMAGE [image-name[, . . . ]]
7.1 – 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.
7.2 – Qualifiers
7.2.1 /ALL
Specifies that all shareable images are set.
7.3 – 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
7.4 – 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.
8 – KEY
Establishes the current key state.
NOTE
This command is not available in the VSI DECwindows Motif for
OpenVMS user interface to the debugger.
Format
SET KEY
8.1 – Qualifiers
8.1.1 /LOG
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the key
state has been set. The /LOG qualifier displays the message. The
/NOLOG qualifier suppresses the message.
8.1.2 /STATE
/STATE[=state-name]
/NOSTATE (default)
Specifies a key state to be established as the current state.
You can specify a predefined key state, such as GOLD, or
a user-defined state. A state name can be any appropriate
alphanumeric string. The /NOSTATE qualifier leaves the current
state unchanged.
8.2 – Description
Keypad mode must be enabled (SET MODE KEYPAD) before you can use
this command. Keypad mode is enabled by default.
By default, the current key state is the DEFAULT state. When
you define function keys, you can use the DEFINE/KEY /IF_STATE
command to assign a specific state name to the key definition.
If that state is not set when you press the key, the definition
is not processed. The SET KEY/STATE command enables you to change
the current state to the appropriate state.
You can also change the current state by pressing a key
that causes a state change (a key that was defined with
DEFINE/KEY/LOCK_STATE/SET_STATE).
Related commands:
DELETE/KEY
DEFINE/KEY
SHOW KEY
8.3 – Example
DBG> SET KEY/STATE=PROG3
This command changes the key state to the PROG3 state. You
can now use the key definitions that are associated with this
state.
9 – LANGUAGE
Establishes the current language.
Format
SET LANGUAGE language-name
9.1 – Parameters
language-name
Specifies a language.
On Integrity servers, you can specify one of the following
keywords:
AMACRO BASIC BLISS C
C++ COBOL Fortran PASCAL
UNKNOWN
On Alpha systems, you can specify one of the following keywords:
ADA AMACRO BASIC BLISS
C C++ COBOL FORTRAN
MACRO MACRO64 PASCAL UNKNOWN
MACRO-32 must be compiled with the AMACRO compiler.
9.2 – Description
When you start the debugger, the current language is set to that
in which the module containing the main program is written. This
is usually the module containing the image transfer address. To
debug a module written in a different source language from that
of the main program, you can change the language with the SET
LANGUAGE command.
The current language setting determines how the debugger parses
and interprets the names, operators, and expressions you specify
in debugger commands, including things like the typing of
variables, array and record syntax, the default radix for the
entry and display of integer data, case sensitivity, and so on.
The language setting also determines how the debugger formats and
displays data associated with your program.
The default radix for both data entry and display is decimal for
most languages. The exceptions are BLISS and MACRO, which have a
default radix of hexadecimal.
The default type for program locations that do not have a
compiler-generated type is longword integer. This is appropriate
for debugging 32-bit applications.
It is advisable to change the default type to quadword for
debugging applications that use the 64-bit address space (on
OpenVMS Integrity server systems, the default type is quadword).
Use the SET TYPE QUADWORD command.
Use the SET LANGUAGE UNKNOWN command when debugging a program
written in an unsupported language. To maximize the usability
of the debugger with unsupported languages, SET LANGUAGE UNKNOWN
causes the debugger to accept a large set of data formats and
operators, including some that might be specific to only a few
supported languages.
Note that SET LANGUAGE UNKNOWN can be an easy, quick workaround
for language-related problems because it uses the "loosest" set
of rules.
For information about debugger support for language-specific
operators and constructs, see the Language_Support help topic.
Related commands:
EVALUATE
EXAMINE
DEPOSIT
SET MODE
SET RADIX
SET TYPE
SHOW LANGUAGE
9.3 – Examples
1.DBG> SET LANGUAGE COBOL
This command establishes COBOL as the current language.
2.DBG> SET LANGUAGE PASCAL
This command establishes Pascal as the current language.
9.4 /DYNAMIC
Toggles the state of automatic language setting.
Format
SET LANGUAGE/DYNAMIC
9.4.1 – Description
When you start the debugger, the current language is set to that
in which the module containing the main program is written. This
is usually the module containing the image transfer address. By
default, when the scope of the program being executed changes to
a module written in a different language, the debugger changes
the current language to that of the module.
You can prevent the debugger from automatically changing the
current language with the SET LANGUAGE/NODYNAMIC command.
Related commands:
SET LANGUAGE
SHOW LANGUAGE
9.4.2 – Examples
1.DBG> SET LANGUAGE/NODYNAMIC
This command prevents the debugger from changing the current
language until you enter a SET LANGUAGE or SET LANGUAGE/DYNAMIC
command.
10 – LOG
Specifies a log file to which the debugger writes after a SET
OUTPUT LOG command has been entered.
Format
SET LOG file-spec
10.1 – Parameters
file-spec
Denotes the file specification of the log file. If you do
not supply a full file specification, the debugger assumes
SYS$DISK:[]DEBUG.LOG as the default file specification for any
missing field.
If you specify a version number and that version of the file
already exists, the debugger writes to the file specified,
appending the log of the debugging session onto the end of that
file.
10.2 – Description
The SET LOG command determines only the name of a log file; it
does not cause the debugger to create or write to the specified
file. The SET OUTPUT LOG command accomplishes that.
If you entered a SET OUTPUT LOG command but no SET LOG command,
the debugger writes to the file SYS$DISK:[]DEBUG.LOG by default.
If the debugger is writing to a log file and you specify another
log file with the SET LOG command, the debugger closes the former
file and begins writing to the file specified in the SET LOG
command.
Related commands:
SET OUTPUT LOG
SET OUTPUT SCREEN_LOG
SHOW LOG
10.3 – Examples
1.DBG> SET LOG CALC
DBG> SET OUTPUT LOG
In this example, the SET LOG command specifies the debugger
log file to be SYS$DISK:[]CALC.LOG. The SET OUTPUT LOG command
causes user input and debugger output to be logged to that
file.
2.DBG> SET LOG [CODEPROJ]FEB29.TMP
DBG> SET OUTPUT LOG
In this example, the SET LOG command specifies the debugger
log file to be [CODEPROJ]FEB29.TMP. The SET OUTPUT LOG command
causes user input and debugger output to be logged to that
file.
11 – MARGINS
Specifies the leftmost and rightmost source-line character
position at which to begin and end display of a source line.
NOTE
This command is not available in the VSI DECwindows Motif for
OpenVMS user interface to the debugger.
Format
SET MARGINS rm
lm:rm
lm:
:rm
11.1 – Parameters
lm
The source-line character position at which to begin display of
the line of source code (the left margin).
rm
The source-line character position at which to end display of the
line of source code (the right margin).
11.2 – Description
The SET MARGINS command affects only the display of source lines.
It does not affect the display of other debugger output, as from
an EXAMINE command.
The SET MARGINS command is useful for controlling the display
of source code when, for example, the code is deeply indented
or long lines wrap at the right margin. In such cases, you can
set the left margin to eliminate indented space in the source
display, and you can decrease the right margin setting (from its
default value of 255) to truncate lines and prevent them from
wrapping.
The SET MARGINS command is useful mostly in line (noscreen) mode.
In line mode, the SET MARGINS command affects the display of
source lines resulting from a TYPE, EXAMINE/SOURCE, SEARCH, or
STEP command, or when a breakpoint, tracepoint, or watchpoint is
triggered.
In screen mode, the SET MARGINS command has no effect on
the display of source lines in a source display, such as the
predefined display SRC. Therefore it does not affect the output
of a TYPE or EXAMINE/SOURCE command, since that output is
directed at a source display. The SET MARGINS command affects
only the display of any source code that might appear in an
output or DO display (for example, after a STEP command has
been executed). However, such source-code display is normally
suppressed if you enable screen mode by pressing PF1-PF3, because
that sequence issues the SET STEP NOSOURCE command as well as SET
MODE SCREEN to eliminate redundant source display.
By default, the debugger displays a source line starting at
character position 1 of the source line. This is actually
character position 9 on your terminal screen. The first eight
character positions on the screen are reserved for the line
number and cannot be manipulated by the SET MARGINS command.
If you specify a single number, the debugger sets the left margin
to 1 and the right margin to the number specified.
If you specify two numbers, separated with a colon, the debugger
sets the left margin to the number on the left of the colon and
the right margin to the number on the right.
If you specify a single number followed by a colon, the debugger
sets the left margin to that number and leaves the right margin
unchanged.
If you specify a colon followed by a single number, the debugger
sets the right margin to that number and leaves the left margin
unchanged.
Related commands:
SET STEP [NO]SOURCE
SHOW MARGINS
11.3 – Examples
1.DBG> SHOW MARGINS
left margin: 1 , right margin: 255
DBG> TYPE 14
module FORARRAY
14: DIMENSION IARRAY(4:5,5), VECTOR(10), I3D(3,3,4)
DBG>
This example displays the default margin settings for a line of
source code (1 and 255).
2.DBG> SET MARGINS 39
DBG> SHOW MARGINS
left margin: 1 , right margin: 39
DBG> TYPE 14
module FORARRAY
14: DIMENSION IARRAY(4:5,5), VECTOR
DBG>
This example shows how the display of a line of source code
changes when you change the right margin setting from 255 to
39.
3.DBG> SET MARGINS 10:45
DBG> SHOW MARGINS
left margin: 10 , right margin: 45
DBG> TYPE 14
module FORARRAY
14: IMENSION IARRAY(4:5,5), VECTOR(10),
DBG>
This example shows the display of the same line of source code
after both margins are changed.
4.DBG> SET MARGINS :100
DBG> SHOW MARGINS
left margin: 10 , right margin: 100
DBG>
This example shows how to change the right margin setting while
retaining the previous left margin setting.
5.DBG> SET MARGINS 5:
DBG> SHOW MARGINS
left margin: 5 , right margin: 100
DBG>
This example shows how to change the left margin setting while
retaining the previous right margin setting.
12 – MODE
Enables or disables a debugger mode.
Format
SET MODE mode[, . . . ]
12.1 – Parameters
DYNAMIC
(Default) Enables dynamic mode. When dynamic mode is enabled,
the debugger sets modules and images automatically during program
execution so that you typically do not have to enter the SET
MODULE or SET IMAGE command. Specifically, whenever the debugger
interrupts execution (whenever the debugger prompt is displayed),
the debugger automatically sets the module and image that contain
the routine in which execution is currently suspended. If the
module or image is already set, dynamic mode has no effect
on that module or image. The debugger issues an informational
message when its sets a module or image automatically.
NODYNAMIC
Disables dynamic mode. Because additional memory is allocated
when a module or image is set, you might want to disable dynamic
mode if performance becomes a problem (you can also free up
memory by canceling modules and images with the CANCEL MODULE
and CANCEL IMAGE commands). When dynamic mode is disabled, you
must set modules and images explicitly with the SET MODULE and
SET IMAGE commands.
G_FLOAT
Specifies that the debugger interpret double-precision floating-
point constants entered in expressions as G_FLOAT (does not
affect the interpretation of variables declared in your program).
NOG_FLOAT
(Default) Specifies that the debugger interpret double-precision
floating-point constants entered in expressions as D_FLOAT (does
not affect the interpretation of variables declared in your
program).
INTERRUPT
Useful when debugging a multiprocess program. Specifies that,
when program execution is suspended in any process, the debugger
interrupts execution in all other processes that were executing
images and prompts for input.
NOINTERRUPT
(Default) Useful when debugging a multiprocess program. Specifies
that, when program execution is suspended in any process, the
debugger take no action with regard to other process.
KEYPAD
NOTE
This parameter is not available in the VSI DECwindows Motif
for OpenVMS user interface to the debugger.
(Default) Enables keypad mode. When keypad mode is enabled,
you can use the keys on the numeric keypad to perform certain
predefined functions. Several debugger commands, especially
useful in screen mode, are bound to the keypad keys. (See the
Keypad_Definitions_CI help topic; also, use the SHOW KEY command
to determine the current key definitions.) You can also redefine
the key functions with the DEFINE/KEY command.
NOKEYPAD
NOTE
This parameter is not available in the VSI DECwindows Motif
for OpenVMS user interface to the debugger.
Disables keypad mode. When keypad mode is disabled, the keys on
the numeric keypad do not have predefined functions, nor can you
assign debugger functions to those keys with DEFINE/KEY commands.
LINE
(Default) Specifies that the debugger display program locations
in terms of line numbers, if possible.
NOLINE
Specifies that the debugger display program locations as routine-
name + byte-offset rather than in terms of line numbers.
OPERANDS[=keyword]
Specifies that the EXAMINE command, when used to examine
an instruction, display the address and contents of the
instruction's operands in addition to the instruction and
its operands. The level of information displayed about any
nonregister operands depends on whether you use the keyword BRIEF
or FULL. The default is OPERANDS=BRIEF.
NOOPERANDS
(Default) Specifies that the EXAMINE command, when used to
examine an instruction, display only the instruction and its
operands.
SCREEN
NOTE
This parameter is not available in the VSI DECwindows Motif
for OpenVMS user interface to the debugger.
Enables screen mode. When screen mode is enabled, you can divide
the terminal screen into rectangular regions, so different data
can be displayed in different regions. Screen mode enables you to
view more information more conveniently than the default, line-
oriented, noscreen mode. You can use the predefined displays, or
you can define your own.
NOSCREEN
NOTE
This parameter is not available in the VSI DECwindows Motif
for OpenVMS user interface to the debugger.
(Default) Disables screen mode.
SCROLL
NOTE
This parameter is not available in the VSI DECwindows Motif
for OpenVMS user interface to the debugger.
Enables scroll mode. When scroll mode is enabled, a screen-mode
output or DO display is updated by scrolling the output line by
line, as it is generated. SET MODE SCROLL is the default.
NOSCROLL
NOTE
This parameter is not available in the VSI DECwindows Motif
for OpenVMS user interface to the debugger.
Disables scroll mode. When scroll mode is disabled, a screen-mode
output or DO display is updated only once per command, instead
of line by line as it is generated. Disabling scroll mode reduces
the amount of screen updating that takes place and can be useful
with slow terminals.
SEPARATE
(Applies only to workstations running VWS.) Specifies that a
separate window be created for debugger input and output. This
feature is useful when debugging screen-oriented programs,
because it moves all debugger displays out of the window that
contains the program's input and output. The separate window is
created with a height of 24 lines and a width of 80 columns wide,
emulating a VT-series terminal screen.
NOSEPARATE
(Applies only to workstations running VWS. Default.) Specifies
that no separate window be created for debugger input and output.
SYMBOLIC
(Default) Enables symbolic mode. When symbolic mode is
enabled, the debugger displays the locations denoted by address
expressions symbolically (if possible) and displays instruction
operands symbolically (if possible). EXAMINE/NOSYMBOLIC can be
used to override SET MODE SYMBOLIC for the duration of an EXAMINE
command.
NOSYMBOLIC
Disables symbolic mode. When symbolic mode is disabled, the
debugger does not attempt to symbolize numeric addresses (it
does not cause the debugger to convert numbers to names). This is
useful if you are interested in identifying numeric addresses
rather than their symbolic names (if symbolic names exist
for those addresses). When symbolic mode is disabled, command
processing might speed up somewhat, because the debugger does not
need to convert numbers to names. EXAMINE/SYMBOLIC can be used
to override SET MODE NOSYMBOLIC for the duration of an EXAMINE
command.
WAIT
(Default) Enables wait mode. In wait mode the debugger waits
until all processes under its control have stopped before
prompting for a new command.
NOWAIT
Disable wait mode. In nowait mode, the debugger immediately
prompts for new commands even if some or all processes are still
running.
12.2 – Description
For details about the SET MODE command, see the parameter
descriptions. The default values of these modes are the same
for all languages.
Related commands:
EVALUATE
EXAMINE
DEFINE/KEY
DEPOSIT
DISPLAY
(SET,SHOW,CANCEL) IMAGE
(SET,SHOW,CANCEL) MODULE
SET PROMPT
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
(SHOW,CANCEL) MODE
SYMBOLIZE
12.3 – Example
DBG> SET MODE SCREEN
This command puts the debugger in screen mode.
13 – MODULE
Loads the symbol records of a module in the current image into
the run-time symbol table (RST) of that image.
NOTES
The current image is either the main image (by default) or
the image established as the current image by a previous SET
IMAGE command.
By default, the debugger automatically loads symbols in a
module as needed. As such, this behavior makes the use of an
explicit SET MODULE command optional. For more information,
see SET MODE DYNAMIC.
Format
SET MODULE [module-name[, . . . ]]
13.1 – Parameters
module-name
Specifies a module of the current image whose symbol records
are loaded into the RST. Do not use the asterisk (*) wildcard
character. Instead, use the /ALL qualifier. Do not specify a
module name with /ALL or /CALLS.
13.2 – Qualifiers
13.2.1 /ALL
Specifies that the symbol records of all modules in the current
image be loaded into the RST.
13.2.2 /CALLS
Sets all the modules that currently have routines on the call
stack. If a module is already set, /CALLS has no effect on that
module.
13.2.3 /RELATED
/RELATED (default)
/NORELATED
(Applies to Ada programs.) Controls whether the debugger loads
into the RST the symbol records of a module that is related to a
specified module through a with-clause or subunit relationship.
Once loaded, you can reference names declared in related modules
within debugger commands exactly as you reference them within the
Ada source code.
13.3 – Description
The SET MODULE command loads the symbol records of a module in
the current image into the run-time symbol table (RST) of that
image. Symbol records must be present in the RST if the debugger
is to recognize and properly interpret the symbols declared in
your program. The process by which the symbol records of a module
are loaded into the RST is called setting a module. This command
also supports user-provided mixed-case and lowercase module names
on Integrity and Alpha servers.
At debugger startup, the debugger sets the module containing
the transfer address (the main program). By default, dynamic
mode is enabled (SET MODE DYNAMIC). Therefore, the debugger sets
modules (and images) automatically as the program executes so
that you can reference symbols as you need them. Specifically,
whenever execution is suspended, the debugger sets the module
and image containing the routine in which execution is suspended.
In the case of Ada programs, as a module is set dynamically, its
related modules are also set automatically, by default, to make
the appropriate symbols accessible (visible).
Dynamic mode makes accessible most of the symbols you might need
to reference. If you need to reference a symbol in a module that
is not already set, proceed as follows:
o If the module is in the current image, use the SET MODULE
command to set the module where the symbol is defined or
reference the symbol with a fully-qualified path name. For
example:
DBG>SET BREAK X\Y
o If the module is in another image, use the SET IMAGE command
to make that image the current image, then use the SET MODULE
command to set the module where the symbol is defined.
If dynamic mode is disabled (SET MODE NODYNAMIC), only the module
containing the transfer address is set automatically. You must
set any other modules explicitly.
If you use the SET IMAGE command to establish a new current
image, all modules previously set remain set. However, only the
symbols in the set modules of the current image are accessible.
Symbols in the set modules of other images are temporarily
inaccessible.
When dynamic mode is enabled, memory is allocated automatically
to accommodate the increasing size of the RST. If dynamic mode
is disabled, the debugger automatically allocates more memory as
needed when you set a module or an image.
If a parameter in a SET SCOPE command designates a program
location in a module that is not already set, the SET SCOPE
command sets that module.
For information specific to Ada programs, type Help
Language_Support Ada.
Related commands:
(SET,SHOW,CANCEL) IMAGE
SET MODE [NO]DYNAMIC
(SHOW) MODULE
13.4 – Examples
1.DBG> SET MODULE SUB1
This command sets module SUB1 (loads the symbol records of
module SUB1 into the RST).
2.DBG> SET IMAGE SHARE3
DBG> SET MODULE MATH
DBG> SET BREAK %LINE 31
In this example, the SET IMAGE command makes shareable image
SHARE3 the current image. The SET MODULE command sets module
MATH in image SHARE3. The SET BREAK command sets a breakpoint
on line 31 of module MATH.
3.DBG> SHOW MODULE/SHARE
module name symbols language size
FOO yes MACRO 432
MAIN no FORTRAN 280
. . .
SHARE$DEBUG no Image 0
SHARE$LIBRTL no Image 0
SHARE$MTHRTL no Image 0
SHARE$SHARE1 no Image 0
SHARE$SHARE2 no Image 0
total modules: 17. bytes allocated: 162280.
DBG> SET MODULE SHARE$SHARE2
DBG> SHOW SYMBOL * IN SHARE$SHARE2
In this example, the SHOW MODULE/SHARE command identifies all
modules in the current image and all shareable images (the
names of the shareable images are prefixed with SHARE$).
The SET MODULE SHARE$SHARE2 command sets the shareable image
module SHARE$SHARE2. The SHOW SYMBOL command identifies any
universal symbols defined in the shareable image SHARE2. For
more information, see the SHOW MODULE/SHARE command.
4.DBG> SET BREAK X/Y:
In this example, the debugger automatically loads the module
information when you specify the module name in the command.
Debugger ensures that the module information for module X is
loaded, and then locates the information for the routine named
Y.
14 – OUTPUT
Enables or disables a debugger output option.
Format
SET OUTPUT output-option[, . . . ]
14.1 – Parameters
output-option
Specifies an output option to be enabled or disabled. Valid
keywords are as follows:
LOG Specifies that debugger input and output be recorded
in a log file. If you specify the log file by
the SET LOG command, the debugger writes to that
file; otherwise, by default the debugger writes to
SYS$DISK[]:DEBUG.LOG.
NOLOG (Default) Specifies that debugger input and output
not be recorded in a log file.
SCREEN_LOG Specifies that, while in screen mode, the screen
contents be recorded in a log file as the screen is
updated. To log the screen contents, you must also
specify SET OUTPUT LOG. See the description of the
LOG option regarding specifying the log file.
NOSCREEN_ (Default) Specifies that the screen contents, while
LOG in screen mode, not be recorded in a log file.
TERMINAL
NOTE
This parameter is not available in the VSI
DECwindows Motif for OpenVMS user interface
to the debugger.
(Default) Specifies that debugger output be
displayed at the terminal.
NOTERMINAL
NOTE
This parameter is not available in the VSI
DECwindows Motif for OpenVMS user interface
to the debugger.
Specifies that debugger output, except diagnostic
messages, not be displayed at the terminal.
VERIFY Specifies that the debugger echo, on the current
output device, each input command string that it is
executing from a command procedure or DO clause. The
current output device is by default SYS$OUTPUT (your
terminal) but can be redefined with the logical name
DBG$OUTPUT.
NOVERIFY (Default) Specifies that the debugger not display
each input command string that it is executing from
a command procedure or DO clause.
14.2 – Description
Debugger output options control the way in which debugger
responses to commands are displayed and recorded. For details
about the SET OUTPUT command, see the parameter descriptions.
Related commands:
@ (Execute Procedure)
(SET,SHOW) ATSIGN
(SET,SHOW) LOG
SET MODE SCREEN
SHOW OUTPUT
14.3 – Example
DBG> SET OUTPUT VERIFY,LOG,NOTERMINAL
This command specifies that the debugger take the following
actions:
o Output each command string that it is executing from a
command procedure or DO clause (VERIFY)
o Record debugger output and user input in a log file (LOG)
o Not display output at the terminal, except diagnostic
messages (NOTERMINAL)
15 – PROCESS
Establishes the visible process or enables/disables dynamic
process setting.
Used only when debugging multiprocess programs (kept debugger
only).
Format
SET PROCESS [process-spec[, . . . ]]
15.1 – Parameters
process-spec
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name " spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
You can also use the asterisk (*) wildcard character to specify
process set all.
Do not specify a process with the /[NO]DYNAMIC qualifier.
15.2 – Qualifiers
15.2.1 /DYNAMIC
/DYNAMIC (default)
/NODYNAMIC
Controls whether dynamic process setting is enabled or disabled.
When dynamic process setting is enabled (/DYNAMIC), whenever the
debugger suspends execution and displays its prompt, the process
in which execution is suspended automatically becomes the visible
process. When dynamic process setting is disabled (/NODYNAMIC),
the visible process remains unchanged until you specify another
process with the SET PROCESS/VISIBLE command.
15.2.2 /VISIBLE
Makes the specified process the visible process. This switches
your debugging context to the specified process, so that symbol
lookups and the setting of breakpoints, and so on, are done
in the context of that process. When using /VISIBLE, you must
specify one process.
15.3 – Description
The SET PROCESS command establishes the visible process, defines
the current process set, or defines the visible process.
By default, commands are executed in the context of the visible
process (the process that is your current debugging context).
Symbol lookups, the setting of breakpoints, and so on, are done
in the context of the visible process.
Dynamic process setting is enabled by default and is controlled
with /[NO]DYNAMIC. When dynamic process setting is enabled,
whenever the debugger suspends program execution and displays
its prompt, the process in which execution is suspended becomes
the visible process automatically.
Related commands:
CALL
EXIT
GO
QUIT
SHOW PROCESS
STEP
15.4 – Example
all> SET PROCESS TEST_Y
all> SHOW PROCESS
Number Name State Current PC
* 2 TEST_Y break PROG\%LINE 71
all>
The SET PROCESS TEST_Y command makes process TEST_Y the visible
process. The SHOW PROCESS command displays information about
the visible process by default.
16 – PROMPT
Changes the debugger prompt string to your personal preference.
Format
SET PROMPT [prompt-parameter]
16.1 – Parameters
prompt-parameter
Specifies the new prompt string. If the string contains spaces,
semicolons (;), or lowercase characters, you must enclose it in
quotation marks (") or apostrophes ('). If you do not specify a
string, the current prompt string remains unchanged.
By default, the prompt string is DBG> when debugging a single
process program.
By default, when debuggging a multiprocess program, the prompt
string is the name of the current process set followed by a right
angle bracket (>). You should not use the SET PROMPT command when
debugging multiprocess programs.
16.2 – Qualifiers
16.2.1 /POP
/POP
/NOPOP (default)
(Applies only to workstations running VWS.) The /POP qualifier
causes the debugger window to pop over other windows and become
attached to the keyboard when the debugger prompts for input. The
/NOPOP qualifier disables this behavior (the debugger window is
not popped over other windows and is not attached to the keyboard
automatically when the debugger prompts for input).
16.3 – Description
The SET PROMPT command enables you to tailor the debugger prompt
string to your individual preference.
If you are debugging a multiprocess program, you should not use
the SET PROMPT command.
If you are using the debugger at a workstation, /[NO]POP enables
you to control whether the debugger window is popped over other
windows whenever the debugger prompts for input.
Related commands:
(SET,SHOW) PROCESS
16.4 – Examples
1.DBG> SET PROMPT "$ "
$ SET PROMPT "d b g : "
d b g : SET PROMPT "DBG> "
DBG>
In this example, the successive SET PROMPT commands change the
debugger prompt from "DBG>" to "$", to "d b g :", then back to
"DBG>".
17 – RADIX
Establishes the radix for the entry and display of integer data.
When used with /OVERRIDE, it causes all data to be displayed as
integer data of the specified radix.
Format
SET RADIX radix
17.1 – Parameters
radix
Specifies the radix to be established. Valid keywords are as
follows:
BINARY Sets the radix to binary.
DECIMAL Sets the radix to decimal. This is the default for
all languages except BLISS, MACRO-32, and MACRO-64
(Alpha and Integrity servers only).
DEFAULT Sets the radix to the language default.
OCTAL Sets the radix to octal.
HEXADECIMAL Sets the default radix to hexadecimal. This is the
default for BLISS, MACRO-32, and MACRO-64 (Alpha and
Integrity servers only).
17.2 – Qualifiers
17.2.1 /INPUT
Sets only the input radix (the radix for entering integer data)
to the specified radix.
17.2.2 /OUTPUT
Sets only the output radix (the radix for displaying integer
data) to the specified radix.
17.2.3 /OVERRIDE
Causes all data to be displayed as integer data of the specified
radix.
17.3 – Description
The current radix setting influences how the debugger interprets
and displays integer data in the following contexts:
o Integer data that you specify in address expressions or
language expressions.
o Integer data that is displayed by the EXAMINE and EVALUATE
commands.
The default radix for both data entry and display is decimal for
most languages. The exceptions are BLISS and MACRO, which have a
default radix of hexadecimal.
The SET RADIX command enables you to specify a new radix
for data entry or display (the input radix and output radix,
respectively).
If you do not specify a qualifier, the SET RADIX command
changes both the input and output radix. If you specify /INPUT
or /OUTPUT, the command changes the input or output radix,
respectively.
Using SET RADIX/OVERRIDE changes only the output radix but causes
all data (not just data that has an integer type) to be displayed
as integer data of the specified radix.
Except when used with /OVERRIDE, the SET RADIX command does not
affect the interpretation or display of noninteger values (such
as real or enumeration type values).
The EVALUATE, EXAMINE, and DEPOSIT commands have radix
qualifiers (/BINARY, /HEXADECIMAL, and so on) which enable you to
override, for the duration of that command, any radix previously
established with SET RADIX or SET RADIX/OVERRIDE.
You can also use the built-in symbols %BIN, %DEC, %HEX, and %OCT
in address expressions and language expressions to specify that
an integer literal should be interpreted in binary, decimal,
hexadecimal, or octal radix.
Related commands:
DEPOSIT
EVALUATE
EXAMINE
(SET,SHOW,CANCEL) MODE
(SHOW,CANCEL) RADIX
17.4 – Examples
1.DBG> SET RADIX HEX
This command sets the radix to hexadecimal. This means that,
by default, integer data is interpreted and displayed in
hexadecimal radix.
2.DBG> SET RADIX/INPUT OCT
This command sets the radix for input to octal. This means
that, by default, integer data that is entered is interpreted
in octal radix.
3.DBG> SET RADIX/OUTPUT BIN
This command sets the radix for output to binary. This means
that, by default, integer data is displayed in binary radix.
4.DBG> SET RADIX/OVERRIDE DECIMAL
This command sets the override radix to decimal. This means
that, by default, all data (not just data that has an integer
type) is displayed as decimal integer data.
18 – SCOPE
Establishes how the debugger looks up symbols (variable names,
routine names, line numbers, and so on) when a path-name prefix
is not specified.
Format
SET SCOPE location[, . . . ]
18.1 – Parameters
location
Denotes a program region (scope) to be used for the
interpretation of symbols that you specify without a path-name
prefix. A location can be any of the following, unless you
specify /CURRENT or /MODULE.
path-name Specifies the scope denoted by the path-name
prefix prefix. A path-name prefix consists of the
names of one or more nesting program elements
(module, routine, block, and so on), with each
name separated by a backslash character (\).
When a path-name prefix consists of more than
one name, list a nesting element to the left of
the backslash and a nested element to the right of
the backslash. A common path-name prefix format is
module\routine\block\.
If you specify only a module name and that name is
the same as the name of a routine, use /MODULE;
otherwise, the debugger assumes that you are
specifying the routine.
n Specifies the scope denoted by the routine which
is n levels down the call stack (n is a decimal
integer). A scope specified by an integer changes
dynamically as the program executes. The value 0
denotes the routine that is currently executing,
the value 1 denotes the caller of that routine,
and so on down the call stack. The default scope
search list is 0,1,2, . . . ,n, where n is the
number of calls in the call stack.
\ Specifies the global scope-that is, the set of
(backslash) all program locations in which a global symbol is
known. The definition of a global symbol and the
way it is declared depends on the language.
When you specify more than one location parameter, you establish
a scope search list. If the debugger cannot interpret the symbol
using the first parameter, it uses the next parameter, and
continues using parameters in order of their specification until
it successfully interprets the symbol or until it exhausts the
parameters specified.
18.2 – Qualifiers
18.2.1 /CURRENT
Establishes a scope search list that is like the default search
list (0,1,2, . . . ,n), numeric scope specified as the command
parameter. Scope 0 is the PC scope, and n is the number of calls
in the call stack.
When using SET SCOPE/CURRENT, note the following conventions and
behavior:
o The default scope search list must be in effect when the
command is entered. To restore the default scope search list,
enter the CANCEL SCOPE command.
o The command parameter specified must be one (and only one)
decimal integer from 0 to n.
o In screen mode, the command updates the predefined source,
instruction, and register displays SRC, INST, and REG,
respectively, to show the routine on the call stack in which
symbol searches are to start.
o The default scope search list is restored when program
execution is resumed.
18.2.2 /MODULE
Indicates that the name specified as the command parameter is a
module name and not a routine name. You need to use /MODULE only
if you specify a module name as the command parameter and that
module name is the same as the name of a routine.
18.3 – Description
By default, the debugger looks up a symbol specified without a
path-name prefix according to the scope search list 0,1,2, . . .
,n, where n is the number of calls in the call stack. This
scope search list is based on the current PC value and changes
dynamically as the program executes. The default scope search
list specifies that a symbol lookup such as EXAMINE X first looks
for X in the routine that is currently executing (scope 0, also
known as the PC scope); if no X is visible there, the debugger
looks in the caller of that routine (scope 1), and so on down the
call stack; if X is not found in scope n, the debugger searches
the rest of the run-time symbol table (RST)-that is, all set
modules and the global symbol table (GST), if necessary.
In most cases, this default scope search list enables you
to resolve ambiguities in a predictable, natural way that is
consistent with language rules. But if you cannot access a symbol
that is defined multiple times, use either of the following
techniques:
o Specify the symbol with a path-name prefix. The path-name
prefix consists of any nesting program units (for example,
module\routine\block) that are necessary to specify the symbol
uniquely. For example:
DBG> EXAMINE MOD4\ROUT3\X
DBG> TYPE MOD4\27
o Establish a new default scope (or a scope search list) for
symbol lookup by using the SET SCOPE command. You can then
specify the symbol without using a path-name prefix. For
example:
DBG> SET SCOPE MOD4\ROUT3
DBG> EXAMINE X
DBG> TYPE 27
18.4 – Description, Continued...
The SET SCOPE command is useful in those cases where otherwise
you would need to use a path name repeatedly to specify symbols.
SET SCOPE changes the debugger's language setting to the language
of the specified scope.
To restore the default scope search list, use the CANCEL SCOPE
command.
When the default scope search list is in effect, you can use the
SET SCOPE/CURRENT command to specify that symbol searches start
at a numeric scope other than scope 0, relative to the call stack
(for example, scope 2).
When you use the SET SCOPE command, the debugger searches only
the program locations you specify explicitly, unless you specify
/CURRENT. Also, the scope or scope search list established with a
SET SCOPE command remains in effect until you restore the default
scope search list or enter another SET SCOPE command. However, if
you specify /CURRENT, the default scope search list is restored
whenever program execution is resumed.
The SET SCOPE command updates a screen-mode source or instruction
display only if you specify /CURRENT.
If a name you specify in a SET SCOPE command is the name of
both a module and a routine, the debugger sets the scope to the
routine. In such cases, use the SET SCOPE/MODULE command if you
want to set the scope to the module.
If you specify a module name in a SET SCOPE command, the debugger
sets that module if it is not already set. However, if you want
only to set a module, use the SET MODULE command rather than the
SET SCOPE command, to avoid the possibility of disturbing the
current scope search list.
For information specific to Ada programs, type Help Language_
Support Ada.
Related commands:
CANCEL ALL
SEARCH
SET MODULE
(SHOW,CANCEL) SCOPE
SHOW SYMBOL
SYMBOLIZE
TYPE
18.5 – Examples
1.DBG> EXAMINE Y
%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique
DBG> SHOW SYMBOL Y
data CHECK_IN\Y
data INVENTORY\COUNT\Y
DBG> SET SCOPE INVENTORY\COUNT
DBG> EXAMINE Y
INVENTORY\COUNT\Y: 347.15
DBG>
In this example, the first EXAMINE Y command indicates that
symbol Y is defined multiple times and cannot be resolved from
the current scope search list. The SHOW SYMBOL command displays
the different declarations of symbol Y. The SET SCOPE command
directs the debugger to look for symbols without path-name
prefixes in routine COUNT of module INVENTORY. The subsequent
EXAMINE command can now interpret Y unambiguously.
19 – SEARCH
Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or
/STRING) for the SEARCH command.
Format
SET SEARCH search-default[, . . . ]
19.1 – Parameters
search-default
Specifies a default to be established for the SEARCH command.
Valid keywords (which correspond to SEARCH command qualifiers)
are as follows:
ALL Subsequent SEARCH commands are treated as SEARCH/ALL,
rather than SEARCH/NEXT.
IDENTIFIER Subsequent SEARCH commands are treated as
SEARCH/IDENTIFIER, rather than SEARCH/STRING.
NEXT (Default) Subsequent SEARCH commands are treated as
SEARCH/NEXT, rather than SEARCH/ALL.
STRING (Default) Subsequent SEARCH commands are treated as
SEARCH/STRING, rather than SEARCH/IDENTIFIER.
19.2 – Description
The SET SEARCH command establishes default qualifiers for
subsequent SEARCH commands. The parameters that you specify with
SET SEARCH have the same names as the qualifiers for the SEARCH
command. The qualifiers determine whether the SEARCH command:
(1) searches for all occurrences of a string (ALL) or only the
next occurrence (NEXT); and (2) displays any occurrence of the
string (STRING) or only those occurrences in which the string is
not bounded on either side by a character that can be part of an
identifier in the current language (IDENTIFIER).
You can override the current SEARCH default for the duration of
a single SEARCH command by specifying other qualifiers. Use the
SHOW SEARCH command to identify the current SEARCH defaults.
Related commands:
SEARCH
(SET,SHOW) LANGUAGE
SHOW SEARCH
19.3 – Example
DBG> SHOW SEARCH
search settings: search for next occurrence, as a string
DBG> SET SEARCH IDENTIFIER
DBG> SHOW SEARCH
search settings: search for next occurrence, as an identifier
DBG> SET SEARCH ALL
DBG> SHOW SEARCH
search settings: search for all occurrences, as an identifier
DBG>
In this example, the SET SEARCH IDENTIFIER command directs
the debugger to search for an occurrence of the string in
the specified range but display the string only if it is not
bounded on either side by a character that can be part of an
identifier in the current language.
The SET SEARCH ALL command directs the debugger to search for
(and display) all occurrences of the string in the specified
range.
20 – SOURCE
Specifies a directory search list, a directory search method, or
both a list and a method for source files.
Format
SET SOURCE directory-spec[, . . . ]
20.1 – Parameters
directory-spec
Specifies any part of an OpenVMS file specification (typically
a device/directory) that the debugger is to use by default
when searching for a source file. For any part of a full file
specification that you do not supply, the debugger uses the file
specification stored in the module's symbol record (that is, the
file specification that the source file had at compile time).
If you specify more than one directory in a single SET SOURCE
command, you create a source directory search list (you can
also specify a search list logical name that is defined at your
process level). In this case, the debugger locates the source
file by searching the first directory specified, then the second,
and so on, until it either locates the source file or exhausts
the list of directories.
20.2 – Qualifiers
20.2.1 /DISPLAY
Specifies the directory search list used when the debugger
displays source code. The default display search directory is
the compilation directory.
20.2.2 /EDIT
Specifies the directory search list used during execution of the
debugger's EDIT command. The default edit search directory is the
compilation directory.
20.2.3 /EXACT
/EXACT (default)
Specifies the directory search method used. In this case, the
debugger searches for the exact version of the source file, as
indicated in the debugger symbol table.
20.2.4 /LATEST
Specifies the directory search method used. In this case, the
debugger searches for the latest version of the source file, that
is, the highest-numbered version in your directory.
20.2.5 /MODULE
/MODULE=module-name
Specifies the directory search list used only for the designated
module. You can append one or more of the qualifiers listed above
to the SET SOURCE/MODULE command.
20.2.6 /ORIGINAL
(Applies to STDL programs only. Requires installation of the
Correlation Facility (a separate layered product) and invocation
of the kept debugger.) Specifies that the debugger display the
original STDL source file, rather than the intermediate files
produced during STDL compilation.
20.3 – Description
By default, the debugger expects a source file to be in the same
directory it was in at compile time. If a source file has been
moved to a different directory since compile time, use the SET
SOURCE command to specify a directory search list and search
method to locate the file.
Specifying the Directory Search List
A complete ODS-2 OpenVMS file specification has the following
format:
node::device:[directory]file-name.file-type;version-number
This format reflects the DECnet node name functionality used in
DECnet Phase IV that shipped with the OpenVMS operating system.
For more information, see the DECnet for OpenVMS Networking
Manual.
On OpenVMS systems running Version 6.1 or later and DECnet-
Plus for OpenVMS, a complete file specification can include
expanded node designations, called full names. Full names are
hierarchically structured DECnet-Plus for OpenVMS node names that
can be stored in a DECdns naming service. Full names can be a
maximum of 255 bytes long, in the following format:
namespace:.directory ... .directory.node-name
In this syntax statement, namespace identifies the global naming
service, directory ... .directory defines the hierarchical
directory path within the naming service, and node-name is the
specific object defining the DECnet node.
For information on full names and suggestions for setting up a
system of names, see the VSI OpenVMS System Manager's Manual. For
information on DECnet-Plus for OpenVMS, see the DECnet-Plus for
OpenVMS Introduction and User's Guide.
If the full file specification of a source file exceeds 255
characters, the debugger cannot locate the file. You can work
around this problem by first defining a logical name "X" (at DCL
level) to expand to your long file specification, and then using
the SET SOURCE X command.
A SET SOURCE command with neither the /DISPLAY nor the /EDIT
qualifier changes both the display and edit search directories.
When compiling a program with the /DEBUG qualifier, if you use
a rooted-directory logical name to specify the location of the
source file, make sure that it is a concealed rooted-directory
logical name. If it is not concealed and you move the source file
to another directory after compilation, you cannot then use the
debugger SET SOURCE command to specify the new location of the
source file.
To create a concealed rooted-directory logical name, use the DCL
command DEFINE with the /TRANSLATION_ATTR=CONCEALED qualifier.
20.4 – Description, Continued...
Specifying the Directory Search Method
When you issue a SET SOURCE command, be aware that one of the
two qualifiers -/LATEST or /EXACT-will always be active. These
qualifiers affect the debugger search method. The /LATEST
qualifier directs the debugger to search for the version last
created (the highest-numbered version in your directory). The
/EXACT qualifier directs the debugger to search for the version
last compiled (the version recorded in the debugger symbol table
created at compile time). For example, a SET SOURCE/LATEST
command might search for SORT.FOR;3 while a SET SOURCE/EXACT
command might search for SORT.FOR;1.
If the debugger locates this version using the directory search
list, it checks that the creation or revision date and time,
file size, record format, and file organization are the same as
the original compile-time source file. If these characteristics
match, the debugger concludes that the original source file has
been located in its new directory.
If the debugger cannot locate this version using the directory
search list, it identifies the file that has the closest revision
date and time (if such a file exists in that directory) and
issues a NOTORIGSRC message ("original version of source file
not found") when first displaying the source code.
Specifying the /EDIT Qualifier
The /EDIT qualifier is needed when the files used for the display
of source code are different from the files to be edited by
using the EDIT command. This is the case with Ada programs. For
Ada programs, the (SET, SHOW, CANCEL) SOURCE commands affect
the search of files used for source display (the "copied"
source files in Ada program libraries); the (SET,SHOW,CANCEL)
SOURCE/EDIT commands affect the search of the source files you
edit when using the EDIT command. If you use /MODULE with /EDIT,
the effect of /EDIT is further qualified by /MODULE.
For information specific to Ada programs, see the
Language_Support Ada help topic.
Specifying the /ORIGINAL Qualifier
Before you can use the /ORIGINAL qualifier in a SET SOURCE
command, the Correlation Facility (a separate layered product)
must be installed on your system. Refer to Correlation Facility
documentation for information on creating a correlation library
before debugging.
Then, invoke the kept debugger and issue the SET SOURCE/ORIGINAL
command as follows:
$ DEBUG/KEEP
DBG> SET SOURCE/ORIGINAL
DBG> RUN filename.EXE
After issuing these commands, you can debug STDL source code in
the same way you debug any other supported language program.
Related commands:
(SHOW,CANCEL) SOURCE
20.5 – Examples
1.DBG> SHOW SOURCE
no directory search list in effect
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
In this example, the SET SOURCE command specifies that the
debugger should search directories [PROJA], [PROJB], and
[PETER.PROJC], in that order, for the latest version of source
files.
2.DBG> SET SOURCE /EXACT
DBG> SHOW SOURCE
no directory search list in effect,
match the exact source file
DBG> SET SOURCE [JONES]
DBG> SHOW SOURCE
source directory list for all modules,
match the exact source file version:
[JONES]
DBG> CANCEL SOURCE /EXACT
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[JONES]
In this example, the SET SOURCE/EXACT command establishes a
search method (exact version) that remains in effect for the
SET SOURCE [JONES] command. The CANCEL SOURCE/EXACT command not
only cancels SET SOURCE/EXACT command, but also affects the SET
SOURCE [JONES] command.
21 – STEP
Establishes default qualifiers (/LINE, /INTO, and so on) for the
STEP command.
Format
SET STEP step-default[, . . . ]
21.1 – Parameters
BRANCH
Subsequent STEP commands are treated as STEP/BRANCH (step to the
next branch instruction).
CALL
Subsequent STEP commands are treated as STEP/CALL (step to the
next call instruction).
EXCEPTION
Subsequent STEP commands are treated as STEP/EXCEPTION (step to
the next exception).
INSTRUCTION
Subsequent STEP commands are treated as STEP/INSTRUCTION (step to
the next instruction).
On VAX processors, you can also specify one or more instructions
(opcode[, . . . ]). The debugger then steps to the next
instruction in the specified list.
On VAX processors, if you specify a vector instruction, do not
include an instruction qualifier (/UNALIGNED_DATA, /MODIFY, /0,
or /1)) with the instruction mnemonic.
INTO
Subsequent STEP commands are treated as STEP/INTO (step into
called routines) rather than STEP/OVER (step over called
routines). When INTO is in effect, you can qualify the types
of routines to step into by using the [NO]JSB, [NO]SHARE,
and [NO]SYSTEM parameters, or by using the STEP/[NO]JSB,
STEP/[NO]SHARE, and STEP/[NO]SYSTEM command/qualifier
combinations (the latter three take effect only for the immediate
STEP command).
LINE
(Default) Subsequent STEP commands are treated as STEP/LINE (step
to the next line).
OVER
(Default) Subsequent STEP commands are treated as STEP/OVER (step
over all called routines) rather than STEP/INTO (step into called
routines).
RETURN
Subsequent STEP commands are treated as STEP/RETURN (step to the
return instruction of the routine that is currently executing-
that is, up to the point just prior to transferring control back
to the calling routine).
SEMANTIC_EVENT
(Alpha only) Subsequent STEP commands are treated as
STEP/SEMANTIC_EVENT (step to the next semantic event).
SHARE
(Default) If INTO is in effect, subsequent STEP commands
are treated as STEP/INTO/SHARE (step into called routines in
shareable images as well as into other called routines).
NOSHARE
If INTO is in effect, subsequent STEP commands are treated as
STEP/INTO/NOSHARE (step over called routines in shareable images,
but step into other routines).
SILENT
Subsequent STEP commands are treated as STEP/SILENT (after a
step, do not display the "stepped to . . . " message or the source
line for the current location).
NOSILENT
(Default) Subsequent STEP commands are treated as STEP/NOSILENT
(after a step, display the "stepped to . . . " message).
SOURCE
(Default) Subsequent STEP commands are treated as STEP/SOURCE
(after a step, display the source line for the current location).
Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands
are treated as SET BREAK/SOURCE, SET TRACE/SOURCE, and SET
WATCH/SOURCE, respectively (at a breakpoint, tracepoint, or
watchpoint, display the source line for the current location).
NOSOURCE
Subsequent STEP commands are treated as STEP/NOSOURCE (after a
step, do not display the source line for the current location).
Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands
are treated as SET BREAK/NOSOURCE, SET TRACE/NOSOURCE, and
SET WATCH/NOSOURCE, respectively (at a breakpoint, tracepoint,
or watchpoint, do not display the source line for the current
location).
SYSTEM
(Default) If INTO is in effect, subsequent STEP commands are
treated as STEP/INTO/SYSTEM (step into called routines in system
space (P1 space) as well as into other called routines).
NOSYSTEM
If INTO is in effect, subsequent STEP commands are treated as
STEP/INTO/NOSYSTEM (step over called routines in system space,
but step into other routines).
21.2 – Description
The SET STEP command establishes default qualifiers for
subsequent STEP commands. The parameters that you specify in
the SET STEP command have the same names as the qualifiers for
the STEP command. The following parameters affect where the STEP
command suspends execution after a step:
BRANCH
CALL
EXCEPTION
INSTRUCTION
LINE
RETURN
SEMANTIC_EVENT (Alpha only)
The following parameters affect what output is seen when a STEP
command is executed:
[NO]SILENT
[NO]SOURCE
The following parameters affect what happens at a routine call:
INTO
OVER
[NO]SHARE
[NO]SYSTEM
You can override the current STEP defaults for the duration of a
single STEP command by specifying other qualifiers. Use the SHOW
STEP command to identify the current STEP defaults.
Enabling screen mode by pressing PF1-PF3 enters the SET STEP
NOSOURCE command as well as the SET MODE SCREEN command.
Therefore, any display of source code in output and DO displays
that would result from a STEP command or from a breakpoint,
tracepoint, or watchpoint being triggered is suppressed, to
eliminate redundancy with the source display.
Related commands:
SHOW STEP
STEP
21.3 – Examples
1.DBG> SET STEP INSTRUCTION,NOSOURCE
This command causes the debugger to execute the program to the
next instruction when a STEP command is entered, and not to
display lines of source code with each STEP command.
2.DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE
This command causes the debugger to execute the program to
the next line when a STEP command is entered, and to step into
called routines in user space only. The debugger steps over
routines in system space and in shareable images.
22 – TASK
Changes characteristics of one or more tasks of a tasking program
(also called a multithread program).
NOTE
SET TASK and SET THREAD are synonymous commands. They
perform identically.
Format
SET TASK [task-spec[, . . . ]]
22.1 – Parameters
task-spec
Specifies a task value. Use any of the following forms:
o When the event facility is THREADS:
- A task (thread) ID number as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW
TASK display.
o When the event facility is ADA:
- A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
- A task ID (for example, %TASK 2), as indicated in a SHOW
TASK display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or
EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_ The task previous to the visible task in the
TASK debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are
the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard character. Instead, use the
/ALL qualifier. Do not specify a task with /ALL or /TIME_SLICE.
If you do not specify a task or /ALL with /ABORT, /[NO]HOLD,
/PRIORITY, or /RESTORE, the visible task is selected.
22.2 – Qualifiers
22.2.1 /ABORT
Marks the specified tasks for termination. Termination occurs
at the next allowable point after a specified task resumes
execution.
For HP Ada tasks, the effect is identical to executing an Ada
abort statement for the tasks specified and causes these tasks
to be marked as abnormal. Any dependent tasks are also marked for
termination.
For POSIX threads threads, use the following command:
PTHREAD tset -c thread-number
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
22.2.2 /ACTIVE
Makes the specified task the active task, which is the task that
runs when a STEP, GO, CALL, or EXIT command executes. This causes
a task switch to the new active task and makes that task the
visible task. The specified task must be in either the RUNNING or
READY state. When using /ACTIVE, you must specify one task.
For POSIX threads programs or HP Ada on Alpha programs, use
one of the following alternatives:
o For query-type actions, use the SET TASK/VISIBLE command.
o To gain control of execution, use a strategic placement of
breakpoints.
o Use the PTHREAD tset -a thread-number command.
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
22.2.3 /ALL
Applies the SET TASK command to all tasks.
22.2.4 /HOLD
/HOLD
/NOHOLD (default)
When the event facility is THREADS, use the
PTHREAD tset -h thread-number or the PTHREAD tset -n thread-num
command.
Controls whether a specified task is put on hold. The /HOLD
qualifier puts a specified task on hold.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED
to the READY state.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED
to the READY state.
A task already in the RUNNING state (the active task) can
continue to execute as long as it remains in the RUNNING state,
even though it is put on hold. If the task leaves the RUNNING
state for any reason (including expiration of a time slice, if
time slicing is enabled), it will not return to the RUNNING state
until released from the hold condition.
You can override the hold condition and force a task into the
RUNNING state with the SET TASK/ACTIVE command even if the task
is on hold.
The /NOHOLD qualifier releases a specified task from hold.
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
22.2.5 /PRIORITY
/PRIORITY=n
When the event facility is THREADS, use the PTHREAD
tset -s thread-number command.
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example, while
executing an Ada rendezvous or
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example, while
executing an Ada rendezvous or POSIX threads synchronization
event. This qualifier does not affect a task's scheduling policy.
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
22.2.6 /VISIBLE
Makes the specified task the visible task, which is the task
whose call stack and register set are the current context for
looking up symbols, register values, routine calls, breakpoints,
and so on. Commands such as EXAMINE are directed at the visible
task. The /VISIBLE qualifier does not affect the active task.
When using /VISIBLE, you must specify one task.
22.3 – Description
The SET TASK command enables you to establish the visible task
and the active task, control the execution of tasks, and cause
task state transitions, directly or indirectly.
To determine the current state of a task, use the SHOW TASK
command. The possible states are RUNNING, READY, SUSPENDED, and
TERMINATED.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
SET BREAK/EVENT
SET TRACE/EVENT
(SET, SHOW) EVENT_FACILITY
SHOW TASK|THREAD
22.4 – Examples
1.DBG> SET TASK/ACTIVE %TASK 3
(Event facility = ADA) This command makes task 3 (task ID = 3)
the active task.
2.DBG> PTHREAD tset -a 3
(Event facility = THREADS) This command makes task 3 (task ID =
3) the active task.
3.DBG> SET TASK %NEXT_TASK
This command makes the next task in the debugger's task list
the visible task. (The /VISIBLE qualifier is a default for the
SET TASK command.)
4.DBG> SET TASK/HOLD/ALL
DBG> SET TASK/ACTIVE %TASK 1
DBG> GO
. . .
DBG> SET TASK/ACTIVE %TASK 3
DBG> STEP
. . .
In this example, the SET TASK/HOLD/ALL command freezes
the state of all tasks except the active task. Then, SET
TASK/ACTIVE is used selectively (along with the GO and STEP
commands) to observe the behavior of one or more specified
tasks in isolation.
23 – TERMINAL
Sets the terminal-screen height or width that the debugger uses
when it formats screen and other output.
NOTE
This command is not available in the VSI DECwindows Motif for
OpenVMS user interface to the debugger.
Format
SET TERMINAL
23.1 – Qualifiers
23.1.1 /PAGE
/PAGE:n
Specifies that the terminal screen height should be set to n
lines. You can use any value from 18 to 100.
23.1.2 /WIDTH
/WIDTH:n
Specifies that the terminal screen width should be set to n
columns. You can use any value from 20 to 255. For a VT100-,
VT200-, or VT300 series terminal, n is typically either 80 or
132.
23.1.3 /WRAP
Tells the debugger to wrap output text in predefined display
OUT at the column specified by the /WIDTH qualifier. If you do
not specify /WIDTH in the current command, /WRAP defaults to the
%WIDTH setting.
23.2 – Description
The SET TERMINAL command enables you to define the portion of
the screen that the debugger has available for formatting screen
output.
This command is useful with VT100-, VT200-, or VT300-series
terminals, where you can set the screen width to typically 80 or
132 columns. It is also useful with workstations, where you can
modify the size of the terminal-emulator window that the debugger
uses.
You must specify at least one qualifier. You can specify all. The
/PAGE and /WIDTH qualifiers each require a value.
When you enter the SET TERMINAL command, all display window
definitions are automatically adjusted to reflect the new screen
dimensions. For example, RH1 changes dimensions proportionally to
remain in the top right half of the screen.
Similarly, all "dynamic" display windows are automatically
adjusted to maintain their relative proportions. Note that
all display windows are dynamic unless referenced with the
DISPLAY/NODYNAMIC command. In that case, the display window
retains its current dimensions after subsequent SET TERMINAL
commands. However, you can use the DISPLAY command to reconfigure
the display window (you can also use keypad-key combinations,
such as BLUE-MINUS, to enter predefined DISPLAY commands).
Related commands:
DISPLAY/[NO]DYNAMIC
EXPAND
(SET,SHOW,CANCEL) WINDOW
SHOW TERMINAL
23.3 – Example
DBG> SET TERMINAL/WIDTH:132
This command specifies that the terminal screen width be set to
132 columns.
24 – THREAD
Changes characteristics of one or more tasks of a tasking program
(also called a multithread program).
NOTE
SET TASK and SET THREAD are synonymous commands. They
perform identically.
Format
SET TASK [task-spec[, . . . ]]
24.1 – Parameters
task-spec
Specifies a task value. Use any of the following forms:
o When the event facility is THREADS:
- A task (thread) ID number as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW
TASK display.
o When the event facility is ADA:
- A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
- A task ID (for example, %TASK 2), as indicated in a SHOW
TASK display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or
EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_ The task previous to the visible task in the
TASK debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are
the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard character. Instead, use the
/ALL qualifier. Do not specify a task with /ALL or /TIME_SLICE.
If you do not specify a task or /ALL with /ABORT, /[NO]HOLD,
/PRIORITY, or /RESTORE, the visible task is selected.
24.2 – Qualifiers
24.2.1 /ABORT
Marks the specified tasks for termination. Termination occurs
at the next allowable point after a specified task resumes
execution.
For HP Ada tasks, the effect is identical to executing an Ada
abort statement for the tasks specified and causes these tasks
to be marked as abnormal. Any dependent tasks are also marked for
termination.
For POSIX threads threads, use the following command:
PTHREAD tset -c thread-number
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
24.2.2 /ACTIVE
Makes the specified task the active task, which is the task that
runs when a STEP, GO, CALL, or EXIT command executes. This causes
a task switch to the new active task and makes that task the
visible task. The specified task must be in either the RUNNING or
READY state. When using /ACTIVE, you must specify one task.
For POSIX threads programs or HP Ada on Alpha programs, use
one of the following alternatives:
o For query-type actions, use the SET TASK/VISIBLE command.
o To gain control of execution, use a strategic placement of
breakpoints.
o Use the PTHREAD tset -a thread-number command.
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
24.2.3 /ALL
Applies the SET TASK command to all tasks.
24.2.4 /HOLD
/HOLD
/NOHOLD (default)
When the event facility is THREADS, use the
PTHREAD tset -h thread-number or the PTHREAD tset -n thread-num
command.
Controls whether a specified task is put on hold. The /HOLD
qualifier puts a specified task on hold.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED
to the READY state.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED
to the READY state.
A task already in the RUNNING state (the active task) can
continue to execute as long as it remains in the RUNNING state,
even though it is put on hold. If the task leaves the RUNNING
state for any reason (including expiration of a time slice, if
time slicing is enabled), it will not return to the RUNNING state
until released from the hold condition.
You can override the hold condition and force a task into the
RUNNING state with the SET TASK/ACTIVE command even if the task
is on hold.
The /NOHOLD qualifier releases a specified task from hold.
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
24.2.5 /PRIORITY
/PRIORITY=n
When the event facility is THREADS, use the PTHREAD
tset -s thread-number command.
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example, while
executing an Ada rendezvous or
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example, while
executing an Ada rendezvous or POSIX threads synchronization
event. This qualifier does not affect a task's scheduling policy.
You can get help on POSIX threads debugger commands by typing
PTHREAD HELP.
See the Guide to the POSIX Threads Library for more information
about using the POSIX threads debugger.
24.2.6 /VISIBLE
Makes the specified task the visible task, which is the task
whose call stack and register set are the current context for
looking up symbols, register values, routine calls, breakpoints,
and so on. Commands such as EXAMINE are directed at the visible
task. The /VISIBLE qualifier does not affect the active task.
When using /VISIBLE, you must specify one task.
24.3 – Description
The SET TASK command enables you to establish the visible task
and the active task, control the execution of tasks, and cause
task state transitions, directly or indirectly.
To determine the current state of a task, use the SHOW TASK
command. The possible states are RUNNING, READY, SUSPENDED, and
TERMINATED.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
SET BREAK/EVENT
SET TRACE/EVENT
(SET, SHOW) EVENT_FACILITY
SHOW TASK|THREAD
24.4 – Examples
1.DBG> SET TASK/ACTIVE %TASK 3
(Event facility = ADA) This command makes task 3 (task ID = 3)
the active task.
2.DBG> PTHREAD tset -a 3
(Event facility = THREADS) This command makes task 3 (task ID =
3) the active task.
3.DBG> SET TASK %NEXT_TASK
This command makes the next task in the debugger's task list
the visible task. (The /VISIBLE qualifier is a default for the
SET TASK command.)
4.DBG> SET TASK/HOLD/ALL
DBG> SET TASK/ACTIVE %TASK 1
DBG> GO
. . .
DBG> SET TASK/ACTIVE %TASK 3
DBG> STEP
. . .
In this example, the SET TASK/HOLD/ALL command freezes
the state of all tasks except the active task. Then, SET
TASK/ACTIVE is used selectively (along with the GO and STEP
commands) to observe the behavior of one or more specified
tasks in isolation.
25 – TRACE
Establishes a tracepoint at the location denoted by an address
expression, at instructions of a particular class, or at the
occurrence of specified events.
Format
SET TRACE [address-expression[, . . . ]]
[WHEN(conditional-expression)]
[DO(command[; . . . ])]
25.1 – Parameters
address-expression
Specifies an address expression (a program location) at which
a tracepoint 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, type Help Address_Expressions.
Do not specify the asterisk (*) wildcard character. Do not
specify an address expression with the following qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INTO
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/TERMINATING
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 tracepoint 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
tracepoint. (The debugger checks the syntax of the expressions in
the WHEN clause when execution reaches the tracepoint, not when
the tracepoint is set.) If the expression is true, the debugger
reports that a tracepoint has been triggered. If an action (DO
clause) is associated with the tracepoint, 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 trace action is taken. The debugger checks the syntax
of the commands in a DO clause when it executes the DO clause,
not when the tracepoint is set.
25.2 – Qualifiers
25.2.1 /ACTIVATING
Causes the debugger to trace when a new process comes under
debugger control. See also the /TERMINATING qualifier.
25.2.2 /AFTER
/AFTER:n
Specifies that trace action not be taken until the nth time the
designated tracepoint is encountered (n is a decimal integer).
Thereafter, the tracepoint occurs every time it is encountered
provided that conditions in the WHEN clause (if specified) are
true. The SET TRACE/AFTER:1 command has the same effect as SET
TRACE.
25.2.3 /BRANCH
Causes the debugger to trace every branch instruction encountered
during program execution. See also the /INTO and /OVER
qualifiers.
25.2.4 /CALL
Causes the debugger to trace every call instruction encountered
during program execution, including the return instruction. See
also the /INTO and /OVER qualifiers.
25.2.5 /EVENT
/EVENT=event-name
Causes the debugger to trace 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 trace 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. To identify the
current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
25.2.6 /EXCEPTION
Causes the debugger to trace every exception that is signaled.
The trace action occurs before any application-declared exception
handlers are invoked.
As a result of a SET TRACE/EXCEPTION command, whenever your
program generates an exception, the debugger reports the
exception and resignals the exception, thus allowing any
application-declared exception handler to execute.
25.2.7 /INSTRUCTION
When you do not specify an opcode, causes the debugger to trace
every instruction encountered during program execution.
See also the /INTO and /OVER qualifiers.
25.2.8 /INTO
(Default) Applies only to tracepoints 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
trace 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 trace action with
the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.
25.2.9 /LINE
Causes the debugger to trace the beginning of each source line
encountered during program execution. See also the /INTO and
/OVER qualifiers.
25.2.10 /MODIFY
Causes the debugger to trace when an instruction writes to and
changes the value of a location indicated by a specified address
expression. The address expression is typically a variable name.
The SET TRACE/MODIFY X command is equivalent to SET WATCH X
DO(GO). The SET TRACE/MODIFY command operates under the same
restrictions as SET WATCH.
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). The SET TYPE LONGWORD
command restores the default length of 4 bytes.
25.2.11 /OVER
Applies only to tracepoints 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
trace 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).
25.2.12 /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 TRACE/RETURN command cancels a previous SET TRACE if you
specify the same address expression.
25.2.13 /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 set tracepoints
within shareable image routines as well as other routines. The
/NOSHARE qualifier specifies that tracepoints not be set within
shareable images.
25.2.14 /SILENT
/SILENT
/NOSILENT (default)
Controls whether the "trace . . . " message and the source line
for the current location are displayed at the tracepoint. The
/NOSILENT qualifier specifies that the message is displayed. The
/SILENT qualifier specifies that the message and source line are
not displayed. The /SILENT qualifier overrides /SOURCE.
25.2.15 /SOURCE
/SOURCE
/NOSOURCE (default)
Controls whether the source line for the current location is
displayed at the tracepoint. The /SOURCE qualifier specifies that
the source line is displayed. The /NOSOURCE qualifier specifies
that the source line is not displayed. The /SILENT qualifier
overrides /SOURCE. See also the SET STEP [NO]SOURCE command.
25.2.16 /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 set tracepoints
within system routines (P1 space) as well as other routines. The
/NOSYSTEM qualifier specifies that tracepoints not be set within
system routines.
25.2.17 /TEMPORARY
Causes the tracepoint to disappear after it is triggered (the
tracepoint does not remain permanently set).
25.2.18 /TERMINATING
(Default) Causes the debugger to trace 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. See also the /ACTIVATING qualifier.
25.3 – Description
When a tracepoint is triggered, the debugger takes the following
actions:
1. Suspends program execution at the tracepoint location.
2. If you specified /AFTER when you set the tracepoint, checks
the AFTER count. If the specified number of counts has not
been reached, execution is resumed and the debugger does not
perform the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the tracepoint. If the value of the
expression is false, execution is resumed and the debugger
does not perform the remaining steps.
4. Reports that execution has reached the tracepoint location by
issuing a "trace . . . " message, unless you specified /SILENT.
5. Displays the line of source code corresponding to the
tracepoint, unless you specified /NOSOURCE or /SILENT when
you set the tracepoint or entered a previous SET STEP NOSOURCE
command.
6. Executes the commands in a DO clause, if you specified one
when you set the tracepoint.
7. Resumes execution.
You set a tracepoint at a particular location in your program
by specifying an address expression with the SET TRACE command.
You set a tracepoint on consecutive source lines, classes of
instructions, or events by specifying a qualifier with the SET
TRACE 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 tracepoint on each line of source
code.
The following qualifiers set tracepoints on classes of
instructions. Using these qualifiers and /LINE causes the
debugger to trace every instruction of your program as it
executes and thus significantly slows down execution.
/BRANCH
/CALL
/INSTRUCTION
/RETURN
/SYSEMULATE (Alpha only)
The following qualifiers set tracepoints on classes of events:
/ACTIVATING
/EVENT=event-name
/EXCEPTION
/TERMINATING
25.4 – Description (Continued...)
The following qualifiers affect what happens at a routine call:
/INTO
/OVER
/[NO]SHARE
/[NO]SYSTEM
The following qualifiers affect what output is displayed when a
tracepoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of
tracepoints:
/AFTER:n
/TEMPORARY
Use the /MODIFY qualifier to monitor changes at program locations
(typically changes in the values of variables).
If you set a tracepoint at a location currently used as
a breakpoint, the breakpoint is canceled in favor of the
tracepoint, and conversely.
Tracepoints can be user defined or predefined. User-defined
tracepoints are set explicitly with the SET TRACE command.
Predefined tracepoints, 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 TRACE
command to identify all tracepoints that are currently set. Any
predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled
independently. For example, a location or event can have both
a user-defined and a predefined tracepoint. Canceling the user-
defined tracepoint does not affect the predefined tracepoint, and
conversely.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) TRACE
CANCEL ALL
GO
SET BREAK
(SET,SHOW) EVENT_FACILITY
SET STEP [NO]SOURCE
SET WATCH
25.5 – Examples
1.DBG> SET TRACE SUB3
This command causes the debugger to trace the beginning of
routine SUB3 when that routine is executed.
2.DBG> SET TRACE/BRANCH/CALL
This command causes the debugger to trace every BRANCH
instruction and every CALL instruction encountered during
program execution.
3.DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM
This command causes the debugger to trace the beginning of
every source line, including lines in called routines (/INTO)
but not in shareable image routines (/NOSHARE) or system
routines (/NOSYSTEM).
4.DBG> SET TRACE/NOSOURCE TEST5\%LINE 14 WHEN (X .NE. 2) DO (EXAMINE Y)
This command causes the debugger to trace line 14 of module
TEST5 when X is not equal to 2. At the tracepoint, the EXAMINE
Y command is issued. The /NOSOURCE qualifier suppresses the
display of source code at the tracepoint. The syntax of
the conditional expression in the WHEN clause is language-
dependent.
5.DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0)
This command causes the debugger to trace when X is not equal
to 0. The condition is tested at each instruction encountered
during execution. The syntax of the conditional expression in
the WHEN clause is language-dependent.
6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
This command causes the debugger to trace the beginning of
routine SUB2 during execution. At the tracepoint, the DO
clause sets a watchpoint on variable K. The /SILENT qualifier
suppresses the "trace . . . " message and the display of source
code at the tracepoint. This example shows a convenient way
of setting a watchpoint on a nonstatic (stack or register)
variable. A nonstatic variable is defined only when its
defining routine (SUB2, in this case) is active (on the call
stack).
7.DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X)
This command causes the debugger to trace the return
instruction of routine ROUT4 (that is, just before execution
returns to the calling routine). At the tracepoint, the DO
clause issues the EXAMINE X command. This example shows a
convenient way of obtaining the value of a nonstatic variable
just before execution leaves that variable's defining routine.
8.DBG> SET TRACE/EVENT=TERMINATED
This command causes the debugger to trace the point at which
any task makes a transition to the TERMINATED state.
26 – TYPE
Establishes the default type to be associated with program
locations that do not have a symbolic name (and, therefore, do
not have an associated compiler-generated type). When used with
/OVERRIDE, it establishes the default type to be associated with
all locations, overriding any compiler-generated types.
Format
SET TYPE type-keyword
26.1 – Parameters
ASCIC
Sets the default type to counted ASCII string with a 1-byte count
field that precedes the string and gives its length. AC is also
accepted as a keyword.
ASCID
Sets the default type to ASCII string descriptor. The CLASS and
DTYPE fields of the descriptor are not checked, but the LENGTH
and POINTER fields provide the character length and address
of the ASCII string. The string is then displayed. AD is also
accepted as a keyword.
ASCII:n
Sets the default type to ASCII character string (length n bytes).
The length indicates both the number of bytes of memory to be
examined and the number of ASCII characters to be displayed. If
you do not specify a value for n, the debugger uses the default
value of 4 bytes. The value n is interpreted in decimal radix.
ASCIW
Sets the default type to counted ASCII string with a 2-byte count
field that precedes the string and gives its length. This data
type occurs in PASCAL and PL/I. AW is also accepted as a keyword.
ASCIZ
Sets the default type to zero-terminated ASCII string. The ending
zero byte indicates the end of the string. AZ is also accepted as
a keyword.
BYTE
Sets the default type to byte integer (length 1 byte).
D_FLOAT
Sets the default type to D_floating (length 8 bytes).
DATE_TIME
Sets the default type to date and time. This is a quadword
integer (length 8 bytes) containing the internal representation
of date and time. Values are displayed in the format dd-mmm-yyyy
hh:mm:ss.cc. Specify an absolute date and time as follows:
[dd-mmm-yyyy[:]] [hh:mm:ss.cc]
EXTENDED_FLOAT
(Alpha only) Sets the default type to IEEE X_floating (length 16
bytes).
G_FLOAT
Sets the default type to G_floating (length 8 bytes).
INSTRUCTION
Sets the default type to instruction (variable length, depending
on the number of instruction operands and the kind of addressing
modes used).
LONG_FLOAT
(Alpha only) Sets the default type to IEEE S_Floating type
(single precision, length 4 bytes).
LONG_LONG_FLOAT
(Alpha only) Sets the default type to IEEE T_Floating type
(double precision, length 8 bytes).
LONGWORD
Sets the default type to longword integer (length 4 bytes). This
is the default type for program locations that do not have a
symbolic name (do not have a compiler-generated type).
OCTAWORD
Sets the default type to octaword integer (length 16 bytes).
PACKED:n
Sets the default type to packed decimal. The value of n is the
number of decimal digits. Each digit occupies one nibble (4
bits).
QUADWORD
Sets the default type to quadword integer (length 8 bytes).
TYPE=expression
Sets the default type to the type denoted by expression (the name
of a variable or data type declared in the program). This enables
you to specify an application-declared type.
S_FLOAT
(Alpha only) Sets the default type to IEEE S_Floating type
(single precision, length 4 bytes).
T_FLOAT
On Alpha systems, sets the default type to IEEE T_Floating type
(double precision, length 8 bytes).
X_FLOAT
On Alpha systems, sets the default type to IEEE X_floating type
(length 16 bytes).
WORD
Sets the default type to word integer (length 2 bytes).
26.2 – Qualifiers
26.2.1 /OVERRIDE
Associates the type specified with all program locations, whether
or not they have a symbolic name (whether or not they have an
associated compiler-generated type).
26.3 – Description
When you use EXAMINE, DEPOSIT, or EVALUATE commands, the default
types associated with address expressions affect how the debugger
interprets and displays program entities.
The debugger recognizes the compiler-generated types associated
with symbolic address expressions (symbolic names declared in
your program), and it interprets and displays the contents of
these locations accordingly. For program locations that do not
have a symbolic name and, therefore, no associated compiler-
generated type, the default type in all languages is longword
integer, which is appropriate for debugging 32-bit applications.
The default data type for untyped storage locations has been
changed from longword (32 bits) to quadword (64 bits).
On Alpha systems, when debugging applications that use the 64-bit
address space, you should use the SET TYPE QUADWORD command.
The SET TYPE command enables you to change the default type
associated with locations that do not have a symbolic name.
The SET TYPE/OVERRIDE command enables you to set a default type
for all program locations, both those that do and do not have a
symbolic name.
The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII,
/BYTE, /G_FLOAT, and so on) which enable you to override, for the
duration of a single command, the type previously associated with
any program location.
Related commands:
CANCEL TYPE/OVERRIDE
DEPOSIT
EXAMINE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW,CANCEL) MODE
SHOW TYPE
26.4 – Examples
1.DBG> SET TYPE ASCII:8
This command establishes an 8-byte ASCII character string as
the default type associated with untyped program locations.
2.DBG> SET TYPE/OVERRIDE LONGWORD
This command establishes longword integer as the default type
associated with both untyped program locations and program
locations that have compiler-generated types.
3.DBG> SET TYPE D_FLOAT
This command establishes D_Floating as the default type
associated with untyped program locations.
4.DBG> SET TYPE TYPE=(S_ARRAY)
This command establishes the type of the variable S_ARRAY as
the default type associated with untyped program locations.
27 – WATCH
Establishes a watchpoint at the location denoted by an address
expression.
Format
SET WATCH address-expression[, . . . ]
[WHEN(conditional-expression)]
[DO(command[; . . . ])]
27.1 – Parameters
address-expression
Specifies an address expression (a program location) at which
a watchpoint is to be set. With high-level languages, this is
typically the name of a program variable and can include a path
name to uniquely specify the variable. 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 online help topic.
Do not specify the asterisk (*) wildcard character.
conditional-expression
Specifies a conditional expression in the currently set language;
the expression is to be evaluated whenever execution reaches the
watchpoint. (The debugger checks the syntax of the expressions in
the WHEN clause when execution reaches the watchpoint, not when
the watchpoint is set.) If the expression is true, the debugger
reports that a watchpoint has been triggered. If an action (DO
clause) is associated with the watchpoint, 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 watch action is taken. The debugger checks the syntax
of the commands in a DO clause when it executes the DO clause,
not when the watchpoint is set.
27.2 – Qualifiers
27.2.1 /AFTER
/AFTER:n
Specifies that watch action not be taken until the nth time the
designated watchpoint is encountered (n is a decimal integer).
Thereafter, the watchpoint occurs every time it is encountered
provided that conditions in the WHEN clause are true. The SET
WATCH/AFTER:1 command has the same effect as SET WATCH.
27.2.2 /INTO
Specifies that the debugger is to monitor a nonstatic variable
by tracing instructions not only within the defining routine, but
also within a routine that is called from the defining routine
(and any other such nested calls). The SET WATCH/INTO command
enables you to monitor nonstatic variables within called routines
more precisely than SET WATCH/OVER; but the speed of execution
within called routines is faster with SET WATCH/OVER.
27.2.3 /OVER
Specifies that the debugger is to monitor a nonstatic variable
by tracing instructions only within the defining routine, not
within a routine that is called by the defining routine. As a
result, the debugger executes a called routine at normal speed
and resumes tracing instructions only when execution returns
to the defining routine. The SET WATCH/OVER command provides
faster execution than SET WATCH/INTO; but if a called routine
modifies the watched variable, execution is interrupted only upon
returning to the defining routine. When you set watchpoints on
nonstatic variables, SET WATCH/OVER is the default.
27.2.4 /SILENT
/SILENT
/NOSILENT (default)
Controls whether the "watch . . . " message and the source line
for the current location are displayed at the watchpoint. The
/NOSILENT qualifier specifies that the message is displayed. The
/SILENT qualifier specifies that the message and source line are
not displayed. The /SILENT qualifier overrides /SOURCE.
27.2.5 /SOURCE
/SOURCE (default)
/NOSOURCE
Controls whether the source line for the current location is
displayed at the watchpoint. The /SOURCE qualifier specifies that
the source line is displayed. The /NOSOURCE qualifier specifies
that the source line is not displayed. The /SILENT qualifier
overrides /SOURCE. See also the SET STEP [NO]SOURCE command.
27.2.6 /STATIC
/STATIC
/NOSTATIC
Enables you to override the debugger's default determination of
whether a specified variable (watchpoint location) is static or
nonstatic. The /STATIC qualifier specifies that the debugger
should treat the variable as a static variable, even though
it might be allocated in P1 space. This causes the debugger
to monitor the location by using the faster write-protection
method rather than by tracing every instruction. The /NOSTATIC
qualifier specifies that the debugger should treat the variable
as a nonstatic variable, even though it might be allocated in P0
space, and causes the debugger to monitor the location by tracing
every instruction. Be careful when using these qualifiers.
27.2.7 /TEMPORARY
Causes the watchpoint to disappear after it is triggered (the
watchpoint does not remain permanently set).
27.3 – Description
When an instruction causes the modification of a watchpoint
location, the debugger takes the following actions:
1. Suspends program execution after that instruction has
completed execution.
2. If you specified /AFTER when you set the watchpoint, checks
the AFTER count. If the specified number of counts has not
been reached, execution continues and the debugger does not
perform the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the watchpoint. If the value of the
expression is false, execution continues and the debugger
does not perform the remaining steps.
4. Reports that execution has reached the watchpoint location
("watch of . . . ") unless you specified /SILENT.
5. Reports the old (unmodified) value at the watchpoint location.
6. Reports the new (modified) value at the watchpoint location.
7. Displays the line of source code at which execution is
suspended, unless you specified /NOSOURCE or /SILENT when
you set the watchpoint or entered a previous SET STEP NOSOURCE
command.
8. Executes the commands in a DO clause, if you specified one
when you set the watchpoint. If the DO clause contains a GO
command, execution continues and the debugger does not perform
the next step.
9. Issues the prompt.
For high-level language programs, the address expressions you
specify with the SET WATCH command are typically variable names.
If you specify an absolute memory address that is associated
with a compiler-generated type, the debugger symbolizes the
address and uses the length in bytes associated with that type
to determine the length in bytes of the watchpoint location. If
you specify an absolute memory address that the debugger cannot
associate with a compiler-generated type, the debugger watches 4
bytes of memory (by default), beginning at the byte identified by
the address expression. 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.
You can set a watchpoint on a range, for example,
SET WATCH 30000:300018
The debugger establishes a series of longword watches that cover
the range.
You can set watchpoints on aggregates (that is, entire arrays
or records). A watchpoint set on an array or record triggers
if any element of the array or record changes. Thus, you do not
need to set watchpoints on individual array elements or record
components. Note, however, that you cannot set an aggregate
watchpoint on a variant record.
You can also set a watchpoint on a record component, on an
individual array element, or on an array slice (a range of array
elements). A watchpoint set on an array slice triggers if any
element within that slice changes. When setting the watchpoint,
follow the syntax of the current language.
27.4 – Description, Continued...
The following qualifiers affect what output is seen when a
watchpoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of
watchpoints:
/AFTER:n
/TEMPORARY
The following qualifiers apply only to nonstatic variables:
/INTO
/OVER
The following qualifier overrides the debugger's determination of
whether a variable is static or nonstatic:
/[NO]STATIC
NOTE
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) WATCH
MONITOR
SET BREAK
SET STEP [NO]SOURCE
SET TRACE
27.5 – Static and Nonstatic Watchpoints
Static and Nonstatic Watchpoints
The technique for setting a watchpoint depends on whether the
variable is static or nonstatic.
A static variable is associated with the same memory address
throughout execution of the program. You can always set a
watchpoint on a static variable throughout execution.
A nonstatic variable is allocated on the call stack or in a
register and has a value only when its defining routine is active
(on the call stack). Therefore, you can set a watchpoint on a
nonstatic variable only when execution is currently suspended
within the scope of the defining routine (including any routine
called by the defining routine). The watchpoint is canceled when
execution returns from the defining routine. With a nonstatic
variable, the debugger traces every instruction to detect any
changes in the value of a watched variable or location.
Another distinction between static and nonstatic watchpoints
is speed of execution. To watch a static variable, the debugger
write-protects the page containing the variable. If your program
attempts to write to that page, an access violation occurs and
the debugger handles the exception, determining whether the
watched variable was modified. Except when writing to that page,
the program executes at normal speed.
To watch a nonstatic variable, the debugger traces every
instruction in the variable's defining routine and checks the
value of the variable after each instruction has been executed.
Since this significantly slows execution, the debugger issues a
message when you set a nonstatic watchpoint.
As explained in the next paragraphs, /[NO]STATIC, /INTO, and
/OVER enable you to exercise some control over speed of execution
and other factors when watching variables.
The debugger determines whether a variable is static or nonstatic
by checking how it is allocated. Typically, a static variable is
in P0 space (0 to 3FFFFFFF, hexadecimal); a nonstatic variable is
in P1 space (40000000 to 7FFFFFFF) or in a register. The debugger
issues a warning if you try to set a watchpoint on a variable
that is allocated in P1 space or in a register when execution is
not currently suspended within the scope of the defining routine.
The /[NO]STATIC qualifiers enable you to override this default
behavior. For example, if you have allocated nonstack storage
in P1 space, use /STATIC when setting a watchpoint on a variable
that is allocated in that storage area. This enables the debugger
to use the faster write-protection method of watching the
location instead of tracing every instruction. Conversely, if,
for example, you have allocated your own call stack in P0 space,
use /NOSTATIC when setting a watchpoint on a variable that is
allocated on that call stack. This enables the debugger to treat
the watchpoint as a nonstatic watchpoint.
You can also control the execution speed for nonstatic
watchpoints in called routines by using /INTO and /OVER.
On Alpha processors, both static and nonstatic watchpoints are
available. With static watchpoints, the debugger write-protects
the page of memory in which the watched variable is stored.
Static watchpoints, therefore, would interfere with the system
service itself if not for the debugger's use of system service
interception (SSI).
If a static watchpoint is in effect then, through system service
interception, the debugger deactivates the static watchpoint,
asynchronous traps (ASTs), and thread switching, just before the
system service call. The debugger reactivates them just after
the system service call completes, putting the watchpoint, AST
enabling, and thread switching back to their original state
and, finally, checking for any watchpoint hits. This behavior
is designed to allow the system service to run as it normally
would (that is, without write-protected pages) and to prevent
the AST code or a different thread from potentially changing the
watchpointed location while the watchpoint is deactivated. Be
aware of this behavior if, for example, your application tests to
see if ASTs are enabled.
An active static watchpoint can cause a system service to fail,
likely with an ACCVIO status, if the system service is not
supported by the system service interception (SSI) vehicle (
SYS$SSISHR on OpenVMS Alpha systems). Any system service that is
not in SYS$PUBLIC_VECTORS is unsupported by SSI, including User
Written System Services (UWSS) and any loadable system services,
such as $MOUNT.
When a static watchpoint is active, the debugger write-protects
the page containing the variable to be watched. A system service
call not supported by SSI can fail if it tries to write to that
page of user memory.
To avoid this failure, do either of the following:
o Deactivate the static watchpoint before the service call.
When the call completes, check the watchpoint manually and
reactivate it.
o Use nonstatic watchpoints. Note that nonstatic watchpoints can
slow execution.
If a watched location changes during a system service routine,
you will be notified, as usual, that the watchpoint occurred.
Note that, on rare occasions, stack may show one or more debugger
frames on top of the frame or frames for your program. To work
around this problem, enter one or more STEP/RETURN commands to
get back to your program.
System service interception is on by default, but on Alpha
processors only, you can disable interception prior to a
debugging session by issuing the following command:
$ DEFINE SSI$AUTO_ACTIVATE OFF
To reenable system service interception, issue one of the
following commands:
$ DEFINE SSI$AUTO_ACTIVATE ON
$ DEASSIGN SSI$AUTO_ACTIVATE
27.6 – Global Section Watchpoints
On Alpha processors, you can set watchpoints on variables or
arbitrary program locations in global sections. A global section
is a region of memory that is shared among all processes of a
multiprocess program. A watchpoint that is set on a location in
a global section (a global section watchpoint) triggers when any
process modifies the contents of that location.
You set a global section watchpoint just as you would set a
watchpoint on a static variable. However, because of the way the
debugger monitors global section watchpoints, note the following
point. When setting watchpoints on arrays or records, performance
is improved if you specify individual elements rather than the
entire structure with the SET WATCH command.
If you set a watchpoint on a location that is not yet mapped to
a global section, the watchpoint is treated as a conventional
static watchpoint. When the location is subsequently mapped
to a global section, the watchpoint is automatically treated
as a global section watchpoint and an informational message is
issued. The watchpoint is then visible from each process of the
multiprocess program.
Examples
1.DBG> SET WATCH MAXCOUNT
This command establishes a watchpoint on the variable MAXCOUNT.
2.DBG> SET WATCH ARR
DBG> GO
. . .
watch of SUBR\ARR at SUBR\%LINE 12+8
old value:
(1): 7
(2): 12
(3): 3
new value:
(1): 7
(2): 12
(3): 28
break at SUBR\%LINE 14
DBG>
In this example, the SET WATCH command sets a watchpoint on
the three-element integer array, ARR. Execution is then resumed
with the GO command. The watchpoint triggers whenever any array
element changes. In this case, the third element changed.
3.DBG> SET WATCH ARR(3)
This command sets a watchpoint on element 3 of array ARR (Fortran
array syntax). The watchpoint triggers whenever element 3
changes.
4.DBG> SET WATCH P_ARR[3:5]
This command sets a watchpoint on the array slice consisting
of elements 3 to 5 of array P_ARR (Pascal array syntax). The
watchpoint triggers whenever any of these elements change.
5.DBG> SET WATCH P_ARR[3]:P_ARR[5]
This command sets a separate watchpoint on each of elements 3 to
5 of array P_ARR (Pascal array syntax). Each watchpoint triggers
whenever its target element changes.
6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
In this example, variable K is a nonstatic variable and is
defined only when its defining routine, SUB2, is active (on
the call stack). The SET TRACE command sets a tracepoint on
SUB2. When the tracepoint is triggered during execution, the
DO clause sets a watchpoint on K. The watchpoint is then canceled
when execution returns from routine SUB2. The /SILENT qualifier
suppresses the "trace . . . " message and the display of source
code at the tracepoint.
7.DBG> g
%DEBUG-I-ASYNCSSWAT, possible asynchronous system service and static
watchpoint collision break at LARGE_UNION\main\%LINE 24192+60
DBG> sho call
module name routine name line rel PC abs PC
*LARGE_UNION main 24192 00000000000003A0 00000000000303A0
*LARGE_UNION __main 24155 0000000000000110 0000000000030110
FFFFFFFF80B90630 FFFFFFFF80B90630
DBG> ex/sour %line 24192
module LARGE_UNION
24192: sstatus = sys$getsyi (EFN$C_ENF, &sysid, 0, &syi_ile, &myiosb, 0, 0);
In this example, an asynchronous write by SYS$QIO to its IOSB
output parameter fails if that IOSB is being watched directly
or even if it simply lives on the same page as an active static
watchpoint.
Debugger notices this problem and warns the user about potential
collisions between static watchpoints and asynchronous system
services.
28 – WINDOW
Creates a screen window definition. This command is not available
in the VSI DECwindows Motif for OpenVMS user interface to the
debugger.
Format
SET WINDOW window-name
AT (start-line,line-count
[,start-column,column-count])
28.1 – Parameters
window-name
Specifies the name of the window you are defining. If a window
definition with that name already exists, it is canceled in favor
of the new definition.
start-line
Specifies the starting line number of the window. This line
displays the window title, or header line. The top line of the
screen is line 1.
line-count
Specifies the number of text lines in the window, not counting
the header line. The value must be at least 1. The sum of start-
line and line-count must not exceed the current screen height.
start-column
Specifies the starting column number of the window. This is the
column at which the first character of the window is displayed.
The leftmost column of the screen is column 1.
column-count
Specifies the number of characters per line in the window. The
value must be at least 1. The sum of start-column and column-
count must not exceed the current screen width.
28.2 – Description
A screen window is a rectangular region on the terminal screen
through which you can view a display. The SET WINDOW command
establishes a window definition by associating a window name
with a screen region. You specify the screen region in terms of a
starting line and height (line count) and, optionally, a starting
column and width (column count). If you do not specify the
starting column and column count, the starting column defaults
to column 1 and the column count defaults to the current screen
width.
You can specify a window region in terms of expressions that use
the built-in symbols %PAGE and %WIDTH.
You can use the names of any windows you have defined with the
SET WINDOW command in a DISPLAY command to position displays on
the screen.
Window definitions are dynamic-that is, window dimensions expand
and contract proportionally when a SET TERMINAL command changes
the screen width or height.
Related commands:
DISPLAY
(SHOW,CANCEL) DISPLAY
(SET,SHOW) TERMINAL
(SHOW,CANCEL) WINDOW
28.3 – Examples
1.DBG> SET WINDOW ONELINE AT (1,1)
This command defines a window named ONELINE at the top of the
screen. The window is one line deep and, by default, spans the
width of the screen.
2.DBG> SET WINDOW MIDDLE AT (9,4,30,20)
This command defines a window named MIDDLE at the middle of the
screen. The window is 4 lines deep starting at line 9, and 20
columns wide starting at column 30.
3.DBG> SET WINDOW FLEX AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
This command defines a window named FLEX that occupies a region
around the middle of the screen and is defined in terms of the
current screen height (%PAGE) and width (%WIDTH).