DEBUG SET — VMS FORTRAN_5.2
The meaning of the command depends on the keyword specified. For
example, SET BREAK establishes breakpoints, SET MODULE loads the
symbol table for a module, and so on. See the help under each
keyword.
Format:
SET keyword [/qualifier] parameter
Additional information available:
ABORT_KEYATSIGNBREAKDEFINEDISPLAYEDITOR
EVENT_FACILITYIMAGEKEYLANGUAGELOGMARGINS
MAX_SOURCE_FILESMODEMODULEOUTPUTPROCESSPROMPT
RADIXSCOPESEARCHSOURCESTEPTASKTERMINAL
TRACETYPEWATCHWINDOW
Parameters
keyword
Keyword can be ABORT_KEY, ATSIGN, BREAK, DEFINE, DISPLAY, EDITOR,
EVENT_FACILITY, IMAGE, KEY, LANGUAGE, LOG, MARGINS,
MAX_SOURCE_FILES, MODE, MODULE, OUTPUT, PROCESS, PROMPT, RADIX,
SCOPE, SEARCH, SOURCE, STEP, TASK, TERMINAL, TRACE, TYPE, WATCH,
or WINDOW.
qualifiers
Depends on the keyword specified.
parameters
Depends on the keyword specified.
ABORT_KEY
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 may be necessary if your program has a CTRL/C AST service
routine enabled.
Note that many CTRL-key sequences have VMS predefined functions,
and the SET ABORT_KEY command enables you to override such
definitions (see the VMS DCL Concepts Manual). Some of the
CTRL-key characters not used by the VMS 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. Always use
either CTRL/C or an equivalent CTRL-key sequence established with
the SET ABORT_KEY command.
Format:
SET ABORT_KEY = CTRL_character
Additional information available:
Example
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> GO
...
<CTRL/C>
%DEBUG-W-ABORTED, command aborted by user request
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>
%DEBUG-W-ABORTED, command aborted by user request
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 sequence of commands shows the following:
1. Use of the (default) CTRL/C sequence to perform the abort
function.
2. Use of the SET ABORT_KEY command to reassign the abort
function to the CTRL/P sequence.
Parameter
character
Specifies the key you press while holding down the CTRL key. You
can specify any alphabetic character.
ATSIGN
Establishes the default file specification for processing
debugger command procedures. This is useful if you wish (for
example) to change the file type of your debugger command
procedures from .COM to .DBG. Or if you have several debugger
command procedures, you can place them in one directory and
specify this directory as the default file specification.
Format:
SET ATSIGN file-spec
Example:
DBG> SET ATSIGN MYDISK:[MYDIR.DEBUG].DBG
DBG> @MYFILE
The file MYDISK:[MYDIR.DEBUG]MYFILE.DBG is executed as a command
procedure.
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 [/qualifiers]
[address-expression[,...]]
[ WHEN (conditional-expression)]
[ DO (command[;...])]
When a breakpoint is triggered, the debugger takes the following
action:
1. Suspends program execution at the breakpoint location.
2. If /AFTER was specified when the breakpoint was set, 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 one was
specified when the breakpoint was set. 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 breakpoint location by
issuing a "break ..." message, unless /SILENT was specified.
5. Displays the line of source code where execution is
suspended, unless /NOSOURCE or /SILENT was specified when the
breakpoint was set, or SET STEP NOSOURCE was entered
previously.
6. Executes the commands in a DO clause, if one was specified
when the breakpoint was set. 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. The only exception is
with the /EVENT qualifier, which requires that you specify an
event name keyword and permits you also to specify an address
expression for certain event names.
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.
Breakpoints may be user defined or predefined. User defined
breakpoints are those that you 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 invoke 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 may have both a
user defined and a predefined breakpoint. Canceling the user
defined breakpoint does not affect the predefined breakpoint, and
conversely.
Additional information available:
/ACTIVATING/AFTER:n/BRANCH/CALL/EVENT/EXCEPTION
/INSTRUCTION/INSTRUCTION/INTO/JSB/LINE
/MODIFY/NOJSB/NOSHARE/NOSILENT/NOSOURCE/NOSYSTEM
/OVER/RETURN/SHARE/SILENT/SOURCE/SYSTEM/TEMPORARY
/TERMINATING
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 (EXAMINE D; STEP; EXAMINE Y; GO)
This command causes the debugger to break at location LOOP1. At
the breakpoint, the following commands are issued, in the order
given: EXAMINE D, STEP, EXAMINE Y, and 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 command EXAMINE Y is
issued.
5 DBG> SET BREAK/TEMPORARY 1440
DBG> SHOW BREAK
breakpoint at 1440 [temporary]
DBG>
This command sets a temporary breakpoint at location 1440. After
that breakpoint is triggered, it disappears.
6 DBG> SET BREAK/LINE
This command causes the debugger to break on the start 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
start of every source line encountered during execution. The
second command tests for the condition at each instruction.
8 DBG> SET BREAK/INSTRUCTION=ADDL3
This command causes the debugger to break whenever the
instruction ADDL3 is about to be executed.
9 DBG> SET BREAK/LINE/INTO/NOSHARE/NOSYSTEM
This command causes the debugger to break on the start of every
source line, including lines in called routines (/INTO) but not
in shareable image routines (/NOSHARE) or system routines
(/NOSYSTEM).
10 DBG> SET BREAK/RETURN ROUT4
This command causes the debugger to break whenever the RET
instruction of routine ROUT4 is about to be executed.
11 DBG> SET BREAK/RETURN %LINE 14
This command causes the debugger to break whenever the RET
instruction of the routine that includes line 14 is about to be
executed. This form of the command is useful if execution is
currently suspended within a routine and you want to set a
breakpoint on that routine's RET instruction.
12 DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS)
This command causes the debugger to break whenever an exception
is signaled. At the breakpoint, the commands SET MODULE/CALLS
and SHOW CALLS are issued.
13 DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3
This command sets two breakpoints, which are associated with the
Ada tasks RESERVE and task 3, respectively. Each breakpoint is
triggered whenever its associated task makes a transition to the
RUN state.
14 DBG_1> SET BREAK/ACTIVATING
This command causes the debugger to break whenever a process of a
multiprocess program is brought under debugger control.
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 may
include a path name to specify the entity uniquely. More
generally, an address expression may also be a virtual memory
address or a register and may be composed of numbers (offsets)
and symbols, as well as one or more operators, operands, or
delimiters.
Do not specify the asterisk asterisk wildcard character (*). Do
not specify an address expression with /ACTIVATING, /BRANCH,
/CALL, /EXCEPTION, /INSTRUCTION[=(opcode-list)], /INTO, /[NO]JSB,
/LINE, /OVER, /[NO]SHARE, /[NO]SYSTEM, or /TERMINATING. The
/MODIFY and /RETURN qualifiers are used with specific kinds of
address expressions.
If you specify a virtual 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 may 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. CALLS and CALLG routines start with
an entry mask.
command
Specifies a debugger command that is to be executed as part of
the DO clause when break action is taken.
conditional-expression
Specifies a conditional expression in the currently set language
that is to be evaluated when execution reaches the breakpoint.
If the expression is TRUE, break action occurs, and the debugger
reports that a break has occurred. If the expression is FALSE,
break action does not occur. In this case, a report is not
issued, the commands specified by the DO clause are not executed,
and program execution is continued.
Qualifiers
The qualifiers can be grouped as follows.
The /LINE qualifier sets a breakpoint on each line of source
code.
The following qualifiers set breakpoints on classes of
instructions. Note that use of these qualifiers and of the /LINE
qualifier causes the debugger to trace every instruction of your
program as it executes and thus significantly slows down
execution: /BRANCH, /CALL, /INSTRUCTION,
/INSTRUCTION=(opcode-list), /RETURN.
The following qualifiers set breakpoints on classes of events:
/ACTIVATING, /EVENT=event-name, /EXCEPTION, /TERMINATING.
The following qualifiers affect what happens at a routine call:
/INTO, /[NO]JSB, /OVER, /[NO]SHARE, /[NO]SYSTEM.
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.
The /MODIFY qualifier is used to monitor changes at program
locations (typically changes in the values of variables).
/ACTIVATING
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
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.
Do not specify an address expression with /ACTIVATING. See also
/TERMINATING.
/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 command SET BREAK/AFTER:1 has the same effect as the
SET BREAK command.
/BRANCH
Causes the debugger to break on every branch instruction
encountered during execution (including BEQL, BGTR, BLEQ, BGEQ,
BLSS, BGTRU, BLEQU, BVC, BVS, BGEQU, BLSSU, BRB, BRW, JMP, BBS,
BBC, BBSS, BBCS, BBSC, BBCC, BBSSI, BBCCI, BLBS, BLBC, ACBB,
ACBW, ACBL, ACBF, ACBD, ACBG, ACBH, AOBLEQ, AOBLSS, SOBGEQ,
SOBGTR, CASEB, CASEW, CASEL). Do not specify an address
expression with /BRANCH. See also /INTO, /OVER.
/CALL
Causes the debugger to break on every call instruction (including
the CALLS, CALLG, BSBW, BSBB, JSB, RSB, and RET instructions)
encountered during execution. Do not specify an address
expression with /CALL. See also /INTO, /OVER.
/EVENT=event-name
Note: This qualifier applies only to Ada and SCAN. See the VAX
Ada and VAX SCAN documentation for complete information.
Causes the debugger to break on the specified event (if that
event is defined and detected by the run- time system). If you
specify an address expression with /EVENT, causes the debugger to
break whenever the specified event occurs for that address
expression. Event names depend on the run-time facility. You
can display the event names associated with the current run-time
facility by entering the SHOW EVENT_FACILITY command. Note that
you cannot specify an address expression with certain event
names.
/EXCEPTION
Causes the debugger to break whenever an exception is signaled.
The break action occurs before any user- written exception
handlers are invoked. Do not specify an address expression with
/EXCEPTION.
As a result of a SET BREAK/EXCEPTION command, whenever your
program generates an exception condition, the debugger suspends
program execution, reports the exception condition, 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 resignalled, thus allowing any
user-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 user-declared
exception handler.
o If you enter a STEP command, the debugger steps into any
user-declared exception handler. If there is no
user-declared handler for that exception, the debugger
resignals the exception.
o If you enter a CALL command, the routine specified is
executed. If a routine is called with the CALL command
directly after an exception breakpoint has been triggered, no
breakpoints, tracepoints, or watchpoints set within that
routine are triggered. However, they are triggered if the
CALL command is given at another time.
/INSTRUCTION
Causes the debugger to break on every instruction executed. Do
not specify an address expression with /INSTRUCTION. See also
/INTO, /OVER.
/INSTRUCTION=(opcode-list)
Causes the debugger to break on every instruction whose opcode is
in the list. Do not specify an address expression with
/INSTRUCTION. See also /INTO, /OVER.
/INTO
Applies only to breakpoints set with /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE; that is, when an address
expression is not explicitly specified. When used with those
qualifiers, causes the debugger to break at the specified points
within called routines (as well as within the routine where
execution is currently suspended). /INTO is the default behavior
and is the opposite of /OVER.
When using /INTO, you can further qualify the break action with
the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB
Qualifies /INTO. Use /JSB only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE. /JSB permits the
debugger to break within routines that are called by the JSB or
CALL instruction. /JSB is the default for all languages except
DIBOL. Do not specify an address expression with /[NO]JSB.
/LINE
Causes the debugger to break at the start of each new line. Do
not specify an address expression with /LINE. See also /INTO,
/OVER.
/MODIFY
Causes a break at 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 may 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.
/NOJSB
Qualifies /INTO. Use /NOJSB only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/NOJSB specifies that breakpoints not be set within routines
called by JSB instructions. /NOJSB is the default for DIBOL
programs. In DIBOL, user- written routines are called by the
CALL instruction and DIBOL run-time library routines are called
by the JSB instruction. Do not specify an address expression
with /NOJSB.
/NOSHARE
Qualifies /INTO. Use /NOSHARE only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/NOSHARE specifies that breakpoints not be set within shareable
images. Do not specify an address expression with /[NO]SHARE.
/NOSILENT
Specifies that the "break . . . " message is displayed at the
breakpoint. This is the default.
/NOSOURCE
Specifies that the source line for the current location is not
displayed at the breakpoint. See also SET STEP [NO]SOURCE.
/NOSYSTEM
Qualifies /INTO. Use /NOSYSTEM only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/NOSYSTEM specifies that breakpoints not be set within system
routines (P1 space). Do not specify an address expression with
/SYSTEM.
/OVER
Applies only to breakpoints set with /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE; that is, when an address
expression is not explicitly specified. When used with those
qualifiers, causes the debugger to break at the specified points
only within the routine where execution is currently suspended
(not within called routines). /OVER is the opposite of /INTO
(the default behavior).
/RETURN
Causes the debugger to break on the RET (return) instruction of
the routine associated with the specified address expression
(which may be a routine name, line number, and so on). This
qualifier can only be applied to routines called with a CALLS or
CALLG instruction; it cannot be used with JSB routines. Breaking
on the RET instruction enables you to inspect the local
environment (for example, obtain the values of local variables)
before the RET instruction deletes the routine's call frame from
the call stack.
For this qualifier, the address-expression parameter is an
instruction address within a CALLS or CALLG routine. It may
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 command
if the same address expresion is specified.
/SHARE
Qualifies /INTO. Use /SHARE only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/SHARE (default) permits the debugger to break within shareable
image routines as well as other routines. Do not specify an
address expression with /[NO]SHARE.
/SILENT
Specifies that the "break . . . " message and the source line
for the current location are not displayed at the breakpoint.
/SILENT overrides /SOURCE. See also SET STEP [NO]SOURCE.
/SOURCE
Specifies that the source line for the current location is
displayed at the breakpoint. This is the default. /SILENT
overrides /SOURCE. See also SET STEP [NO]SOURCE.
/SYSTEM
Qualifies /INTO. Use /SYSTEM only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/SYSTEM (default) permits the debugger to break within system
routines (P1 space) as well as other routines. Do not specify an
address expression with /SYSTEM.
/TEMPORARY
Causes the breakpoint to disappear after it is triggered (the
breakpoint does not remain permanently set).
/TERMINATING
Causes the debugger to break when a process performs an image
exit. Note that the debugger always gains control and displays
its prompt when the last image of a single-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. Do not specify an address expression
with /TERMINATING. See also /ACTIVATING.
DEFINE
Specifies how to interpret DEFINE commands. The DEFINE command
can bind a symbol to either an address, a command string, a group
of process names, or a value.
Example:
DBG> SET DEFINE COMMAND
DBG> DEFINE B = "SET BREAK"
DBG> DEFINE M = "SET MODULE"
Additional information available:
ADDRESSCOMMANDPROCESS_GROUPVALUE
Parameters
ADDRESS
Treat subsequent DEFINE commands as DEFINE/ADDRESS.
COMMAND
Treat subsequent DEFINE commands as DEFINE/COMMAND.
PROCESS_GROUP
Treat subsequent DEFINE commands as DEFINE/PROCESS_GROUP
VALUE
Treat subsequent DEFINE commands as DEFINE/VALUE.
ADDRESS
Treat subsequent DEFINE commands as DEFINE/ADDRESS.
COMMAND
Treat subsequent DEFINE commands as DEFINE/COMMAND.
PROCESS_GROUP
Treat subsequent DEFINE commands as DEFINE/PROCESS_GROUP
VALUE
Treat subsequent DEFINE commands as DEFINE/VALUE.
DISPLAY
Creates a screen display to be shown on the terminal screen. A
screen display is a set of text lines that can be viewed through
a window on the terminal screen. The SET DISPLAY command defines
such a display, sets its maximum size in text lines, defines its
screen position, and establishes its display kind. Once set, the
display may be selected to have certain attributes such as output
or scrolling by the SELECT command.
Format:
SET DISPLAY [/qualifier...] [disp-name [AT wspec] [dkind]
[, disp-name [AT wspec] [dkind]...]]
Additional information available:
Examples
1 DBG> SET DISPLAY DISP2 AT RS45
DBG> SELECT/OUTPUT DISP2
In this example, the SET DISPLAY command creates a new display
named DISP2 essentially at the right bottom half of the screen,
above the PROMPT display, which is located at S6. This is an
output display by default. The SELECT/OUTPUT command then
selects DISP2 as the current output display.
2 DBG> SET WINDOW TOP AT (1,8,45,30)
DBG> SET DISPLAY NEWINST AT TOP INSTRUCTION
DBG> SELECT/INST NEWINST
In this example, the SET WINDOW command creates a window named
TOP starting at line 1 and column 45, and extending down for 8
lines and to the right for 30 columns. The SET DISPLAY command
creates an instruction display named NEWINST to be displayed
through TOP. The SELECT/INST command selects NEWINST as the
current instruction display.
3 DBG> SET DISPLAY CALLS AT Q3 DO (SHOW CALLS)
This command creates a DO display named CALLS at window Q3. Each
time the debugger gains control from the program, the SHOW CALLS
command is executed and the output is displayed in display CALLS,
replacing any previous contents.
4 DBG> SET DISPLAY/MARK EXAM AT Q2 DO (EXAM A,B,C)
This command creates a DO display named EXAM at window Q2. The
display shows the current values of variables A, B, and C
whenever the debugger prompts for input. Any changed values are
highlighted.
5 DBG_2> SET DISPLAY/PROCESS OUT_/SUFFIX AT S45 OUTPUT
This command creates an output display at window S45. The
/PROCESS qualifier, by default, makes the display specific to the
visible process (process 2, in this example). The /SUFFIX
qualifier appends a process-identifying suffix, that denotes the
visible process, to the display name OUT_. By default, the
/SUFFIX qualifier appends the same process identifier suffix that
appears on the prompt. Therefore, the full display name is
OUT_2.
Parameters
disp-name
The name of the new display being defined. If a screen display
by the same name already exists, the previous display must be
cancelled before the new one can be established.
wspec
The name of the screen window at which this display is to be
positioned. This may also be a window specification of the form
(start-line, line-count, start-column, column-count). If wspec
is omitted, the display is positioned at window H1 or H2.
dkind
The display kind. This can be OUTPUT for an output display,
SOURCE for a source display, SOURCE(debug-cmd-list) for an
automatically updated source display, DO(debug-cmd-list) for an
automatically updated output display, INSTRUCTION for an
instruction display, INSTRUCTION(debug-cmd-list) for an
automatically updated instruction display, or REGISTER for an
automatically updated register display. If omitted, dkind
defaults to OUTPUT.
Qualifiers
Additional information available:
/DYNAMIC/HIDE/MARK_CHANGE/NODYNAMIC/NOPROCESS
/POP/PROCESS/PUSH/REMOVE/SIZE:n/SUFFIX
/DYNAMIC
Specifies that the display is to automatically adjust its window
dimensions proportionally when you change the screen height or
width with a SET TERMINAL command. This is the default behavior
for all displays.
/HIDE
Hides the specified display under any other displays that occupy
the same region on the terminal screen. This has the same effect
as the /PUSH qualifier.
/MARK_CHANGE
Specifies that any changed lines of a DO(debug-cmd-list) display
are marked each time the display is automatically updated. The
marking is done by highlighting each line of the display which
has a different textual content this time compared to the last
time the display was updated. This qualifier is useful when you
want changed variables in an automatically updated display to be
highlighted on change. This qualifier is not applicable to other
kinds of displays.
/NODYNAMIC
Specifies that the display is not to automatically adjust its
window dimensions when you change the screen height or width with
a SET TERMINAL command.
/NOPROCESS
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
Causes the specified display to always be associated with the
visible process, which may change during program execution. This
is the default behavior.
/POP
Pops the specified display to the front of all other displays
that occupy the same region on the terminal screen. This is the
default action of the SET DISPLAY command.
/PROCESS[=(process-spec)]
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
Causes the specified display to be process specific -- that is,
the specified display is associated only with a particular
process. The contents of a process-specific display are
generated and modified in the context of that process. You can
make any display process specific, except for the PROMPT display.
/PROCESS=(process-spec) causes the specified display to be
associated with the specified process. You must include the
parentheses. Use any of the following process-spec forms:
[%PROCESS_NAME] process-name The VMS process name, if that
name contains no spaces or
lowercase characters[1].
[%PROCESS_NAME] "process-name" The VMS process name, if that
name contains spaces or lowercase
characters. You can also use
apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The VMS process identification
number (PID, a hexadecimal number).
%PROCESS_NUMBER process-number The number assigned to a process
(or %PROC process-number) when it comes under debugger control.
Process numbers appear in a
SHOW PROCESS display.
process-group-name A symbol defined with the
DEFINE/PROCESS_GROUP command to
represent a group of processes.
%NEXT_PROCESS The next process in the debugger's
circular process list after the
visible process.
%PREVIOUS_PROCESS The previous process in the
debugger's circular process list
before the visible process.
%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.
_______________________________________________________
[1]The process name can include the asterisk wildcard
character (*)
/PROCESS causes the specified display to be associated with the
process that was the visible process when the DISPLAY/PROCESS
command was executed. If you do not specify /PROCESS, the
current process- specific behavior (if any) of the specified
display remains unchanged. See also /SUFFIX.
/PUSH
Pushes the specified display under any other displays that occupy
the same region on the terminal screen. This has the same effect
as the /HIDE qualifier.
/REMOVE
Marks the specified display as being removed. A removed display
does not appear on the screen unless explicitly requested with a
later DISPLAY command. Although a removed display is not visible
on the screen, the display and its contents are preserved.
/SIZE:n
Sets the maximum size of the display in text lines to be n lines.
If more than n lines are written to the display, the oldest lines
are lost as new lines are added. If this qualifier is omitted,
the default size is 64 lines.
For source displays, n gives the number of source lines to buffer
at any one time. This is not normally significant since a source
display can always be scrolled over the entire source file.
/SUFFIX[=process-identifier-type]
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS). Use
this qualifier only directly after a display name.
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process. This qualifier is used
primarily in command procedures when specifying display
definitions or key definitions that are bound to display
definitions. Use any of the following process-identifier-type
keywords:
PROCESS_NAME The display-name suffix is the VMS process name.
PROCESS_NUMBER The display-name suffix is the process number
(as shown in a SHOW PROCESS display).
PROCESS_PID The display-name suffix is the VMS process
identification number (PID).
If you specify /SUFFIX without a process-identifier- type
keyword, the process identifier type used for the display-name
suffix is, by default, the same as that used for the prompt
suffix (see SET PROMPT/SUFFIX).
See also /[NO]PROCESS.
EDITOR
Establishes the editor that is invoked by the EDIT command.
Format:
SET EDITOR [{/CALLABLE_EDT |
/CALLABLE_EMACS |
/CALLABLE_LSEDIT |
/CALLABLE_TPU}]
[/[NO]START_POSITION]
[command_line]
The qualifiers /CALLABLE_EDT, /CALLABLE_EMACS, /CALLABLE_LSEDIT,
and /CALLABLE_TPU cause the EDIT command to invoke the callable
versions of the editor chosen. If none of these are specified,
then the command_line is required, and it is SPAWNed to DCL when
the EDIT command is used.
For /CALLABLE_LSEDIT and /CALLABLE_TPU, the command_line
specified is passed to the callable editor as the command line to
use. If no command_line is specified, the default is "LSEDIT" or
"TPU", respectively. The command_line parameter is currently
ignored for /CALLABLE_EDT and /CALLABLE_EMACS since those
routines do not allow for a command line.
The /START_POSITION qualifier on the SET EDITOR command defines
whether the /START_POSITION qualifier is appended to the command
line before invoking the specific editor. Currently only LSEDIT
(both SPAWNed and /CALLABLE_LSEDIT) support this qualifier.
The default is SPAWNed LSEDIT, with the /START_POSITION
qualifier. If the default were set by the SET EDITOR command, it
would be:
DBG> SET EDITOR/START_POSITION LSEDIT
Example:
DBG> SET EDITOR '@MAIL$EDIT ""'
DBG> SET EDITOR/CALLABLE_EDT
DBG> SET EDITOR/CALLABLE_TPU
DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION
DBG> SET EDITOR/CALLABLE_LSEDIT/START_POSITION
The first command causes EDIT to spawn the command line
'@MAIL$EDIT ""', which invokes the same editor used in MAIL.
The second command causes EDIT to invoke CALLABLE_EDT. No
command line is allowed with CALLABLE_EDT.
The third command causes EDIT to invoke CALLABLE_TPU with the
default command line of "TPU".
The fourth command causes EDIT to invoke CALLABLE_TPU with the
command line "TPU/SECTION=MYSECINI.TPU$SECTION".
The last command causes EDIT to invoke CALLABLE_LSEDIT with the
default command line of "LSEDIT". Also, the /START_POSITION
qualifier is appended to the command line, so that the editing
session starts on the source line that the debugger is currently
pointing to.
EVENT_FACILITY
Selects a particular run time facility for the debugger to use
for the SET BREAK/EVENT and SET TRACE/EVENT commands.
This allows the specified facility (the run time library of a
language or other run time system) to define and detect certain
types of events in the execution of your program which would
otherwise be very difficult (or impossible) for you to set a
breakpoint on. These events are treated as ordinary debugger
"eventpoints". That is, you can set a break or trace on them
(using WHEN or DO clauses if desired), display them with the SHOW
BREAK or SHOW TRACE commands, and remove them with the CANCEL
BREAK or CANCEL TRACE commands. (See also "SHOW
EVENT_FACILITY").
Format:
SET EVENT_FACILITY facility_name
Example:
SET EVENT_FACILITY ADA
Causes the debugger to use the Ada RTL as the event facility for
succeeding "/EVENT" commands. The Ada language includes
multitasking. The "EVENT_FACILITY" mechanism allows you to set
breakpoints on events such as task switching which you could not
do otherwise.
IMAGE
"SET IMAGE imagename" loads the symbol table for the specified
shareable image, and sets your debugging context to that
shareable image. Use the SHOW IMAGE command to find out what the
shareable images in your program are.
Format:
SET IMAGE [/ALL] [image-name [,...]]
For example, if you want to set a breakpoint in routine SUBR in
module SUBR in shareable image SHARE1, then you could enter the
commands:
DBG> SET IMAGE SHARE1
DBG> SET MODU SUBR
DBG> SET BREAK SUBR
The specified image should have been linked /DEBUG or /TRACE. If
the image was linked /NOTRACE then no symbol table is available
for that image and you cannot SET IMAGE to it.
KEY
This command changes the current key definition state. Note that
keys are defined by using the DEFINE/KEY command.
Example: To make DEFINE/KEY redefine the GOLD keys by default,
do:
DBG> SET KEY/STATE=GOLD
Format:
SET KEY [/qualifiers[,...]]
Command Qualifiers Defaults
/[NO]LOG /LOG /[NO]STATE=state-name
current state
Additional information available:
Qualifiers
Additional information available:
/LOG
Print an informational message indicating whether or not the key
state has been set.
/NOLOG
Do not print the informational message associated with the
command.
/NOSTATE
Do not change the current state
/STATE
Set the state to state-name.
Format:
SET KEY/STATE=state-name
LANGUAGE
Establishes the current language. This affects what expressions
are allowed in commands that accept language expressions
(EXAMINE, EVALUATE, DEPOSIT, and so on). This also affects the
default radix setting.
At debugger start-up, the debugger sets the current language to
the language in which the module containing the transfer address
was written. You can (and should) change this language by the
SET LANGUAGE command if you begin debugging a module written in a
different source language.
Format:
SET LANGUAGE language-name
Example:
DBG> SET LANGUAGE ADA
Additional information available:
Parameters
language-name
Specifies the name of the language. Valid languages include the
following: ADA, BASIC, BLISS, C, COBOL, DIBOL, FORTRAN, MACRO,
PASCAL, PLI, RPG, SCAN, and UNKNOWN. (UNKNOWN gives a kind of
"generic" language support and is intended to be used by any
language not in the above list).
Type "HELP Languages" for information on specific support.
LOG
Specifies the name of the log file to which the debugger writes
when the output parameter is set to LOG. Note that SET LOG only
specifies the name of the file; you need to do SET OUTPUT LOG to
actually enable logging. The default log file name is DEBUG.LOG.
Format:
SET LOG file-spec
Example:
DBG> SET LOG MARCH24.DBG
DBG> SET OUTPUT LOG
Additional information available:
Parameters
file-spec
The log file's file specification.
MARGINS
Specifies the leftmost source-line character position at which to
begin display of a line of source code (the left margin) and/or
the rightmost source-line character position at which to end
display of a line of source code.
The SET MARGINS command affects only the display of lines of
source code, that is, the display resulting from commands such as
TYPE and EXAMINE/SOURCE. The SET MARGINS command does not affect
the display resulting from commands (such as EXAMINE, EVALUATE,
SHOW MODE, and so on) that do not display source code.
Format:
rm
SET MARGINS lm:rm
lm:
:rm
Example:
DBG> SET MARGINS 10:70
Additional information available:
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).
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 specified to the left of the
colon and the right margin to the number specified to the right
of the colon.
If you specify a single number followed by a colon, the debugger
sets the left margin to the number specified and leaves the right
margin unchanged.
If you specify a colon followed by a single number, the debugger
sets the right margin to the number specified and leaves the left
margin unchanged.
MAX_SOURCE_FILES
Specifies the maximum number of source files that the debugger
may keep open at any one time. The default value is 5.
The value of MAX_SOURCE_FILES does not limit the number of source
files that the debugger can open, it limits the number that may
be kept open at any one time. Thus, if the debugger reaches this
limit, it must close a file in order to open another one.
Setting MAX_SOURCE_FILES to a very small number can make the
debugger's use of source files inefficient. Setting
MAX_SOURCE_FILES to a large number runs the risk of exceeding
your "open file quota". It is usually best to leave
MAX_SOURCE_FILES at the default value of 5.
Format:
SET MAX_SOURCE_FILES n
Additional information available:
Parameters
n - Specifies the maximum number of source files that the debugger
may keep open at any one time.
MODE
Establishes one or more "modes". The two most important "modes"
are:
(1) Screen mode or noscreen mode, which affects whether you want
to view debugger output line-by-line, or in a screen-oriented
fashion.
(2) Keypad mode or nokeypad mode, which affects whether the
numeric keypad is used to enter debugger commands, or whether it
is used to enter numbers.
In addition, there are a large number of other "modes" that
affect the debugger's behavior; these are described in detail in
the subtopics.
Format:
SET MODE mode-keyword [,mode-keyword]
Additional information available:
DYNAMICG_FLOATINTERRUPTKEYPADLINENODYNAMIC
NOG_FLOATNOINTERRUPTNOKEYPADNOLINENOOPERANDS
NOSCREENNOSCROLLNOSEPARATENOSYMBOLICOPERANDS
SCREENSCROLLSEPARATESYMBOLIC
Parameters
mode-keyword
May be one of the following:
o DYNAMIC -- Enables dynamic module setting (see description
under DYNAMIC) (default).
o NODYNAMIC -- Disables dynamic module setting (see description
under DYNAMIC).
o G_FLOAT -- Specifies that debugger pick up D exponent constant
as G_float.
o NOG_FLOAT -- Specifies that debugger pick up D exponent
constant as D_float. (default).
o INTERRUPT -- Enables interrupt mode for debugging multiprocess
programs (see description under INTERRUPT) (default).
o NOINTERRUPT -- Disables interrupt mode for debugging
multiprocess programs (see description under NOINTERRUPT).
o KEYPAD -- Turn on keypad mode.
o NOKEYPAD -- Turn off keypad mode. (default).
o LINE -- Specifies that the debugger display code locations in
terms of line numbers (%LINE), if possible. (default).
o NOLINE -- Specifies that the debugger symbolize code locations
to "routine + offset" instead of line number.
o OPERANDS -- Enables display of operands when examining VAX
instructions.
o NOOPERANDS -- Disables display of operands when examining VAX
instructions.
o SCREEN -- Turns on screen mode.
o NOSCREEN -- Turns off screen mode. (default).
o SCROLL -- Specifies that output be scrolled through the output
display as it is generated (default).
o NOSCROLL -- Specifies that the output display be updated only
once per command, instead of scrolling the output line-by-line
as it is generated.
o SEPARATE -- Runs debugger I/O in a separate VAXstation window.
(only available on a VAXstation).
o NOSEPARATE -- Runs debugger I/O in the window where the
debugger initially started. (only available on a VAXstation).
(default).
o SYMBOLIC -- Specifies that the debugger display the locations
denoted by address-expressions symbolically, if possible.
(default).
o NOSYMBOLIC -- Specifies that the debugger turn off
symbolization of addresses.
DYNAMIC
Enables dynamic module setting. Dynamic module setting means
that whenever you are at the DBG prompt, if your PC is in a
module that is not set, then the debugger sets the module
automatically. For example, if you step into a function in a
module that is not set, the debugger sets the module and issues
an informational that it has done so.
The debugger does not cancel modules for you, so as you step
through your program there may be an increasing number of modules
set.
Example:
DBG> SET MODE DYNAMIC
DBG> STEP/INTO
stepped to routine SUBR
%DEBUG-I-DYNMODSET, setting module SUBR
G_FLOAT
Specifies that all double-precision constants entered in
expressions should be interpreted as G_Floating. This only
affects the interpretation of constants such as "1.1D0" that are
entered in expressions; variables in your program are still
interpreted according to their declared type.
INTERRUPT
(Applies to a multiprocess debugging configuration -- that is,
when DBG$PROCESS has the value MULTIPROCESS). Specifies that,
when program execution is suspended in any process, the debugger
interrupts execution in any other processes that were executing
images and prompts for input. SET MODE INTERRUPT is the default.
KEYPAD
Activates keypad mode. See "Help Keypad" for more information.
LINE
Specifies that the debugger display code locations in terms of
line numbers (%LINE), if possible. (default).
Example:
DBG> SET MODE LINE; STEP
stepped to %LINE 20
DBG> SET MODE NOLINE; STEP
stepped to SUBR + 36
NODYNAMIC
Turns off dynamic module setting. One might occasionally want to
turn off this feature if performance is a problem. See
description under "DYNAMIC" for more info.
NOG_FLOAT
Specifies that all double-precision constants entered in
expressions should be interpreted as D_Floating. This only
affects the interpretation of constants such as "1.1D0" that are
entered in expressions; variables in your program are still
interpreted according to their declared type. (default).
NOINTERRUPT
(Applies to a multiprocess debugging configuration -- that is,
when DBG$PROCESS has the value MULTIPROCESS). Specifies that,
when program execution is suspended in any process, the debugger
take the following action:
1. If execution was suspended because of an unhandled exception,
the debugger interrupts execution in any other processes that
were executing images and prompts for input.
2. If execution was suspended because of a breakpoint or
watchpoint or the completion of a STEP command, the debugger
lets execution proceed in any other processes that were
executing images and does not display the prompt unless
execution is eventually suspended in all these processes. As
long as execution continues in any process, the debugger does
not prompt for input. In such cases, use CTRL/C to interrupt
all processes and display the prompt.
NOKEYPAD
Disables keypad mode. This may be necessary if you would rather
use the keypad to enter numbers, instead of debugger commands.
NOLINE
Specifies that the debugger symbolize code locations to "routine
+ offset" instead of line number.
Example:
DBG> SET MODE LINE; STEP
stepped to %LINE 20
DBG> SET MODE NOLINE; STEP
stepped to SUBR + 36
NOOPERANDS
Specifies that the operands of VAX instructions are not to be
evaluated when you enter the command EXAMINE/INSTRUCTION.
Example:
DBG> SET MODE OPERANDS=BRIEF
DBG> EXAMINE .0\%PC
X\X$START+0C: MOVL B^04(R4),R7
B^04(R4) X\X$START\K (address 00001058) contains 00000016
R7 R7 contains 00000000
DBG> SET MODE NOOPERANDS
DBG> EXAMINE .0\%PC
X\X$START+0C: MOVL B^04(R4),R7
NOSCREEN
Disables screen mode. (default)
NOSCROLL
Specifies that the output display be updated only once per
command, instead of scrolling the output line-by-line as it is
generated. This reduces the amount of screen updating that takes
place, which might be an advantage on slow terminals.
NOSEPARATE
This command applies only to VAXstations.
Specifies that debugger input and output go to the window in
which the debugger was invoked. This is the default behavior.
NOSYMBOLIC
Specifies that the debugger not attempt to symbolize addresses.
The only advantage of this is performance: suppressing
symbolization may speed up command processing slightly by
reducing the amount of work the debugger has to do. Note that
SET MODE NOSYM does NOT cause the debugger to turn all names into
numbers - it just requests that the debugger make no attempt to
turn numbers into names.
Example:
DBG> EVAL/ADDR X
7FFFFEC0
DBG> EXAMINE %HEX 7FFFFEC0
SUBR\X: 3
DBG> SET MODE NOSYM
DBG> EXAMINE %HEX 7FFFFEC0
7FFFFEC0: 3
OPERANDS
Specifies that, when you enter an EXAMINE command to examine an
instruction, the display include the address and contents of each
instruction operand. The entity being examined must be of type
"instruction".
You can control the amount of information displayed, by
specifying either OPERANDS=BRIEF or OPERANDS=FULL. These
qualifiers can be used on either the SET MODE OPERANDS or
EXAMINE/OPERANDS commands. The default is OPERANDS=BRIEF.
Example:
DBG> SET MODE OPERANDS=BRIEF
DBG> EXAMINE .0\%PC
X\X$START+0C: MOVL B^04(R4),R7
B^04(R4) X\X$START\K (address 00001058) contains 00000016
R7 R7 contains 00000000
DBG> SET MODE OPERANDS=FULL
DBG> EXAMINE .0\%PC
X\X$START+0C: MOVL B^04(R4),R7
B^04(R4) R4 contains X\X$START\M (address 00001054),
B^04(00001054) evaluates to X\X$START\K
(address 00001058), which contains 00000016
R7 R7 contains 00000000
SCREEN
Enables screen mode. See Screen_features for more information.
SCROLL
Specifies that, in screen mode, output be scrolled through the
output display as it is generated. (default).
SEPARATE
This command applies only to VAXstations.
Creates a separate debugger window for debugger input and output.
The effect is as if you had defined DBG$INPUT and DBG$OUTPUT to
point to the newly created window. For example:
DBG> SET MODE SEPARATE
(... new window ...)
DBG>
SYMBOLIC
Specifies that the debugger attempt to symbolize addresses that
appear in its output. This is the default behavior (since a
symbolic representation is usually preferred). For example:
DBG> EVAL/ADDR X
7FFFFEC0
DBG> EXAMINE %HEX 7FFFFEC0
SUBR\X: 3
DBG> SET MODE NOSYM
DBG> EXAMINE %HEX 7FFFFEC0
7FFFFEC0: 3
MODULE
Sets the specified module(s). "Modules" are a subdivision of
your program. The exact definition depends on the language, for
example, in FORTRAN every subroutine is a module, whereas in ADA
every compilation unit is a module. Setting a module means that
the symbols in that module become available to the debugger.
Format:
SET MODULE [/qualifier] [module-name [,module-name] ... ]
Example:
DBG> EX X ! X is declared in SUBR
%DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table
DBG> SET MODU SUBR
DBG> EX X ! Now you can examine X
SUBR\X: 5
Additional information available:
Parameters
module-name
Specifies the name of the module to be set.
Qualifiers
Additional information available:
/ALL
Specifies that all of the modules in your program be set.
(However, your "shareable image" modules is not set by a SET
MODULE/ALL - you have to explicitly set each one.)
/CALLS
Sets all the modules that currently have routines on the call
stack. These are the modules that are listed when you enter a
SHOW CALLS command. You would use the /CALLS qualifier to set
modules that might not have been dynamically set by the debugger.
/NORELATED
(Applies to ADA only).
This qualifier tells the debugger to set only the module or
modules specified in this command, but not the "with"ed packages
and subunit parents that would normally be set along with the
specified module. This can degrade the debugger's ability to
look up symbols to some extent, for example, names that are
visible in ADA because of a "with" clause are not visible in the
debugging session if the "with"ed package is not set.
/RELATED
(Applies to ADA only).
This qualifier is the default. "Related module setting" means
that when you set an ADA module, all "with"ed package specs are
also set for you, and if the module is a subunit, its parent is
set for you. This enables the debugger to achieve the same name
visibility rules as the ADA language.
OUTPUT
Specifies whether or not to send output to the terminal, and
whether or not to send output to a log file.
Format:
SET OUTPUT option [,option...]
Example:
DBG> SET OUTPUT LOG ! Enable logging
DBG> SET OUTPUT NOTERM ! Turn off terminal output
! After the above two commands, output is only going
! to the log file, not to the terminal
DBG> SET OUT NOTERM,NOLOG
%DEBUG-I-OUTPUTLOST, output being lost
! After the above, output is going to neither the terminal
! or the log file, so you get an informational that output
! is being lost. This is obviously a useless output mode.
DBG> SET OUT TERM,NOLOG ! Back to the default
Additional information available:
LOGNOLOGNOSCREEN_LOGNOTERMINALNOVERIFY
SCREEN_LOGTERMINALVERIFY
Parameters
option
May be one of the following output parameters:
LOG NOLOG NOTERMINAL NOVERIFY
TERMINAL VERIFY SCREEN_LOG NOSCREEN_LOG
LOG
Specifies that both debugger output and user input be recorded in
a log file. If you specify the name of the log file by the SET
LOG command, the debugger writes to that file; otherwise, the
debugger writes to a file with the default file specification
DEBUG.LOG.
NOLOG
Specifies that debugger output and user input not be recorded in
a log file. This is the default.
NOSCREEN_LOG
Specifies that screen images should not be logged to the log
file, even when logging is otherwise enabled. This is the
default.
NOTERMINAL
Specifies that debugger output, except for diagnostic messages,
not be displayed at the terminal.
NOVERIFY
Specifies that the debugger's echoing of commands in command
procedures and in DO Command Sequences not be included as
debugger output. This is the default.
SCREEN_LOG
Specifies that screen images should be written to the log file
whenever screen mode is set and logging is enabled by the LOG
option. This parameter can cause log file to get very large, and
should be used with caution.
TERMINAL
Specifies that debugger output be displayed at the terminal.
This is the default.
VERIFY
Specifies that the debugger's echoing of commands in command
procedures and in DO Command sequences be included as debugger
output.
PROCESS
Note: This command applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
The SET PROCESS command establishes the visible process, modifies
characteristics of one or more processes, or enables/disables
dynamic process setting.
Format:
SET PROCESS [/qualifier] [process-spec[, . . . ]]
By default, commands are executed in the context of the visible
process. The visible process is the process that is your current
debugging context. Symbol lookups and the setting of
breakpoints, tracepoints, and watchpoints are done in the context
of the visible process.
The DO command enables you to execute commands in the context of
specific processes or of all processes. The DO command is
equivalent to entering a SET PROCESS/VISIBLE command for each
process specified (or for all processes, if no process is
specified with the DO command) and then entering the specified
commands.
Dynamic process setting is enabled by default and is controlled
with the /[NO]DYNAMIC qualifier. When dynamic process setting is
enabled (SET PROCESS/DYNAMIC), whenever the debugger suspends
program execution and displays its prompt, the process in which
execution is suspended becomes the visible process automatically.
Additional information available:
Examples
1 DBG_1> SET PROCESS/HOLD/ALL
DBG_1> SHOW PROCESS/ALL
Number Name Hold State Current PC
* 1 TEST_X YES step PROG\%LINE 50
2 TEST_Y YES break PROG\%LINE 71
The command SET PROCESS/HOLD/ALL places all processes on hold.
This is confirmed in the SHOW PROCESS/ALL display.
2 DBG_1> SET PROCESS/NOHOLD %VISIBLE_PROCESS
DBG_1> SHOW PROCESS/ALL
Number Name Hold State Current PC
* 1 TEST_X step PROG\%LINE 50
2 TEST_Y YES break PROG\%LINE 71
The command SET PROCESS/NOHOLD %VISIBLE_PROCESS releases the
visible process from hold. This is confirmed in the SHOW
PROCESS/ALL display.
3 DBG_1> SET PROCESS TEST_Y
DBG_2> SHOW PROCESS
Number Name Hold State Current PC
* 2 TEST_Y YES break PROG\%LINE 71
The command SET PROCESS TEST_Y makes process TEST_Y the visible
process. The command SHOW PROCESS displays information about the
visible process, by default.
4 DBG_1> SET PROCESS/HOLD/ALL
DBG_1> DO (EXAMINE X; STEP)
For %PROCESS_NUMBER 1
MAIN_PROG\X: 78
For %PROCESS_NUMBER 2
TEST\X: 29
stepped to MAIN_PROG\%LINE 26 in %PROCESS_NUMBER 1
26: K = K + 1
DBG_1>
The command SET PROCESS/HOLD/ALL puts all processes on HOLD. The
DO command broadcasts the commands EXAMINE X and STEP to all
processes (processes 1 and 2 in this case). The STEP is executed
in the visible process, process 1, because a HOLD condition in
the visible process is ignored. Because process 2 is on HOLD,
execution is inhibited in that process.
Parameters
process-spec
Specifies a process. Use any of the following forms:
[%PROCESS_NAME] process-name The VMS process name, if that
name contains no spaces or
lowercase characters[1].
[%PROCESS_NAME] "process-name" The VMS process name, if that
name contains spaces or lowercase
characters. You can also use
apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The VMS process identification
number (PID, a hexadecimal number).
%PROCESS_NUMBER process-number The number assigned to a process
(or %PROC process-number) when it comes under debugger control.
Process numbers appear in a
SHOW PROCESS display.
process-group-name A symbol defined with the
DEFINE/PROCESS_GROUP command to
represent a group of processes.
%NEXT_PROCESS The next process in the debugger's
circular process list after the
visible process.
%PREVIOUS_PROCESS The previous process in the
debugger's circular process list
before the visible process.
%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.
_______________________________________________________
[1]The process name can include the asterisk wildcard
character (*)
You can also use the asterisk wildcard character (*) to specify
all processes.
Qualifiers
Additional information available:
/ALL/DYNAMIC/HOLD/NODYNAMIC/NOHOLD/VISIBLE
/ALL
Applies the SET PROCESS command to all processes. Do not specify
a process with this qualifier. Do not specify /[NO]DYNAMIC, or
/VISIBLE with /ALL.
/DYNAMIC
Enables dynamic process setting (default). When dynamic process
setting is enabled, whenever the debugger suspends execution and
displays its prompt, the process in which execution is suspended
becomes the visible process automatically. Do not specify a
process with /DYNAMIC. Do not specify /ALL, /[NO]HOLD, or
/VISIBLE with /DYNAMIC.
/HOLD
Puts a specified process on hold. This prevents images in that
process from executing when you enter a GO, STEP, or CALL
command, unless the process is the visible process. A HOLD
condition in the visible process is ignored. The behavior
described also applies when you use the DO command to broadcast a
GO, STEP, or CALL command to specific processes.
If no process is specified, /HOLD places the visible process on
HOLD. See the descriptions of the GO, STEP, CALL, EXIT, and QUIT
commands for the effects of these commands on held processes. Do
not specify /[NO]DYNAMIC with /HOLD.
/NODYNAMIC
Disables dynamic process setting. When dynamic process setting
is disabled, the visible process remains unchanged until you
specify another process with the SET PROCESS/VISIBLE command. Do
not specify a process with /NODYNAMIC. Do not specify /ALL,
/[NO]HOLD, or /VISIBLE with /NODYNAMIC.
/NOHOLD
Unholds a specified process. This permits images in that process
to execute when you enter a GO, STEP, or CALL command, regardless
of which process is the visible process. The behavior described
also applies when you use the DO command to broadcast a GO, STEP,
or CALL command to specific processes.
If no process is specified, /NOHOLD unholds the visible process.
See the descriptions of the GO, STEP, CALL, EXIT, and QUIT
commands for the effects of these commands on unheld processes.
Do not specify /[NO]DYNAMIC with /NOHOLD.
/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, tracepoints, and
watchpoints are done in the context of that process. You must
specify one, and only one, process. If you do not specify
/VISIBLE, it is assumed by default. Do not specify /ALL, or
/[NO]DYNAMIC with /VISIBLE.
PROMPT
Changes the debugger prompt string from DBG> to a string of your
choice. In addition, the /[NO]SUFFIX and /[NO]POP qualifiers
control convenience features for debugging multiprocess programs
or using the debugger at a VAXstation, respectively.
Format:
SET PROMPT [/qualifier] [prompt-parameter]
Additional information available:
Examples
1 DBG> SET PROMPT "$ "
$ SET PROMPT "d b g : "
d b g : SET PROMPT "DBG> "
DBG>
The successive SET PROMPT commands change the debugger prompt
from "DBG>" to "$", to "d b g :", then back to "DBG>".
2 DBG_1> SET PROMPT/NOSUFFIX "dbg> "
dbg> SET PROMPT/SUFFIX
DBG_1> SET PROMPT/SUFFIX=PROCESS_NUMBER "xyz_"
xyz_1> SET PROMPT/SUFFIX=PROCESS_NAME
SMITH> SET PROMPT/SUFFIX=PROCESS_NAME "John "
John SMITH> SET PROMPT/SUFFIX=PROCESS_PID
20800E4D>
The successive SET PROMPT commands show the effect of the
/[NO]SUFFIX qualifier and the prompt-parameter string for
multiprocess programs.
Parameters
prompt-parameter
Specifies the string which is to become the new prompt. 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> for a non-
multiprocess debugging configuration (when the logical name
DBG$PROCESS is undefined or has the value DEFAULT).
By default, for a multiprocess debugging configuration (when
DBG$PROCESS has the value MULTIPROCESS), the prompt string
consists of a process-independent prefix (specified by
prompt-parameter) and a process-specific suffix (specified by the
/[NO]SUFFIX qualifier). The suffix changes automatically as the
visible process changes.
Qualifiers
Additional information available:
/SUFFIX[=process-identifier-type]
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
/SUFFIX enables "dynamic prompt setting". As a result, the
prompt string includes a process-specific suffix that
automatically identifies the visible process. This is the
default behavior.
When you invoke the debugger with the RUN command to debug a
multiprocess program, the prompt string is DBG_1> by default.
This indicates that dynamic prompt setting is enabled and that
the visible process is process 1 (the first process connected to
the debugger). You can control the process-specific
prompt-string suffix by specifying one of the following
process-identifier-type keywords with the /SUFFIX qualifier:
PROCESS_NAME The prompt-string suffix is the VMS process name.
PROCESS_NUMBER The prompt-string suffix is the process number
(as shown in a SHOW PROCESS display). This is the
default.
PROCESS_PID The prompt-string suffix is the VMS process
identification number (PID).
The following table illustrates the possible kinds of prompt
strings for a multiprocess debugging configuration. Note that
the entire prompt string depends on the prompt-parameter command
parameter (which controls the process-independent prefix), and on
the values of /[NO]SUFFIX and the process- identifier-type
keyword (which control the process-specific suffix):
Prompt-
parameter Qualifier and Keyword Resulting
(prefix): (suffix): Prompt_String:
none none unchanged
none /NOSUFFIX DBG>
none /SUFFIX DBG_process-number> [1]
none /SUFFIX=PROCESS_NAME process-name>
none /SUFFIX=PROCESS_NUMBER process-number>
none /SUFFIX=PROCESS_PID pid>
XYZ_ /NOSUFFIX XYZ_>
XYZ_ /SUFFIX XYZ_process-number>
XYZ_ /SUFFIX=PROCESS_NAME XYZ_process-name>
XYZ_ /SUFFIX=PROCESS_NUMBER XYZ_process-number>
XYZ_ /SUFFIX=PROCESS_PID XYZ_pid>
_______________________________________________________
[1]The default prompt for a multiprocess debugging configuration
is DBG_process-number>, which is equivalent to entering the
following command:
DBG> SET PROMPT/SUFFIX=PROCESS_NUMBER "DBG_"
/NOPOP
Note: This qualifier applies only to VAXstations.
Causes the debugger window to not pop over other windows, nor to
attach to the keyboard automatically, when the debugger prompts
for input. This is the default behavior. If you do not specify
/NOPOP, the prompt behavior is set to /NOPOP.
/NOSUFFIX
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
/NOSUFFIX disables dynamic prompt setting. As a result, the
prompt string does not include a process-specific suffix and does
not change when another process becomes the visible process.
/POP
Note: This qualifier applies only to VAXstations.
Causes the debugger window to pop over other windows and become
attached to the keyboard when the debugger prompts for input. If
you do not specify /POP, the prompt behavior is set to /NOPOP.
RADIX
SET RADIX is the new syntax (in place of SET MODE) for specifying
the radix (decimal, hex, octal, binary) of numbers. Input and
output radices can be specified separately.
Format:
SET RADIX[/qualifier...] radix
Example:
DBG> SET RADIX DECIMAL
DBG> EVAL 5 + 5
10
DBG> SET RADIX HEX
DBG> EVAL 5 + 5
0A
Additional information available:
BINARYDECIMALDEFAULTHEXADECIMALOCTAL
Parameters
radix
May be one of the following:
o BINARY -- Sets the radix to binary.
o DECIMAL -- Sets the radix to decimal.
o DEFAULT -- Sets the radix back to the language default.
o HEXADECIMAL -- Sets the radix to hexadecimal.
o OCTAL -- Sets the radix to octal.
BINARY
Sets the radix to binary.
DECIMAL
Sets the radix to decimal.
DEFAULT
Sets the radix back to the default for the current language.
HEXADECIMAL
Sets the radix to hexadecimal.
OCTAL
Sets the radix to octal.
Qualifiers
Additional information available:
/INPUT
Set only the input radix.
Example:
DBG> SET RADIX/INPUT DECIMAL; SET RADIX/OUTPUT HEX
DBG> EVAL 31
1F
/OUTPUT
Set only the output radix.
DBG> SET RADIX/INPUT DECIMAL; SET RADIX/OUTPUT HEX
DBG> EVAL 31
1F
/OVERRIDE
Set the "override" radix.
"Override" radix is like output radix except that it also causes
all data to be displayed as integer (that is, the type is
overriden).
SCOPE
SET SCOPE is used to control how the debugger looks up names. If
you find yourself repeatedly using the same pathname on examines,
then SET SCOPE provides a way of abbreviating those examine
commands. Also see the help on "Pathnames" and "Scopes".
Example: instead of saying:
DBG> EXAM ROUT1\ROUT2\X
DBG> EXAM ROUT1\ROUT2\Y
you can say:
DBG> SET SCOPE ROUT1\ROUT2
DBG> EXAM X
DBG> EXAM Y
Format:
SET SCOPE location [,location,...]
Additional information available:
ParametersQualifierDefaultExamplesNotes
Parameters
location
Can either be a "pathname", a "numeric scope" or the "global
scope". These are further explained below:
o Pathname -- One or more program location labels, separated by
the backslash character (\), that identifies a program
location. The pathname elements may be module, routine, and
block names, as well as line numbers and numeric labels. A
common pathname format is the following:
MODULE\ROUTINE\BLOCK. A pathname may be complete or
incomplete, so long as it identifies a unique program
location. Also see the help on "Pathnames".
o 0,1,2,...-- The set of decimal integers represent called
routines, where 0 represents the currently active program
unit, 1 represents the routine that called the currently
active program unit, and so on.
o \ -- Represents the global scope. That is, "EXAMINE \X"
displays the global symbol X, if one exists.
Qualifier
Additional information available:
/MODULE
This qualifier is only needed in the case where you have a module
and a routine with the same name. Normally, you want to set
scope to the routine, so that is the default. If you want to set
scope to the module, then SET SCOPE/MODULE is used.
Default
The default scope is the search list 0,1,2,3,...,N, where N is
the current number of levels in your call stack. The default
scope therefore changes as your program executes.
The meaning of this default scope is that a symbol lookup such as
"EXAMINE X" first looks for X in the routine that is currently
executing. If no X is visible there, then the debugger looks in
the caller of that routine. Next it looks in the caller of that
routine, and so on up the stack.
Examples
DBG> SET SCOPE ROUTINE_NAME\NESTED_ROUTINE
! Now if you EXAMINE something the debugger first looks
! for it in NESTED_ROUTINE
DBG> CANCEL SCOPE
! This sets you back to the default scope of 0,1,2,3,...,N,
! where N is the number of active call frames.
! This means symbol lookups are done relative to your current PC.
! This search list tells the debugger to perform symbol
! lookups first relative to the current routine, then relative to
! the caller of the current routine, and so on up the stack.
DBG> SET SCOPE 1
! Now symbol lookups are done one level up the call stack.
! For example, now if you do EXAM R5, you are seeing the value
! of register 5 in the caller of the current routine.
Notes
SET SCOPE may have the side effect of setting a module. For
example, if FOO is the name of one of your modules, SET SCOPE FOO
sets the module FOO if it is not already set. However, if what
you want to do is to make the symbols in FOO available to the
debugger, you should use SET MODULE, not SET SCOPE. The scope is
best left at its default value of "0,1,2,...", so that it changes
dynamically as your program executes.
SEARCH
Establishes current SEARCH parameters to be used by the debugger
whenever a SEARCH command qualifier is not specified in a SEARCH
command.
SEARCH parameters determine whether the debugger searches for all
occurrences (ALL) of the string or only the next occurrence
(NEXT) of the string, and whether the debugger 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 cannot be part of an identifier in the current language
(IDENTIFIER).
You can specify more than one SEARCH parameter in a single SET
SEARCH command by separating each parameter with a comma.
Format:
SET SEARCH option [,option...]
Additional information available:
Parameters
option
Specifies the current SEARCH parameters.
o ALL -- specifies that the debugger search for all occurrences
of the string in the specified range and display every line
containing an occurrence of the string.
o NEXT -- specifies that the debugger search for the first
occurrence of the string in the specified range and display
the line containing this occurrence. This is the default.
o IDENTIFIER -- specifies that the debugger search for an
occurrence of the string in the specified range but display
the string only if it is bounded on either side by af
character that cannot be part of an identifier in the current
language.
o STRING -- specifies that the debugger search for and display
the string as specified, and not interpret the context
surrounding an occurrence of the string, as it does in the
case of IDENTIFIER. This is the default.
ALL
Specifies that the debugger search for all occurrences of the
string in the specified range and display every line containing
an occurrence of the string.
IDENTIFIER
Specifies that the debugger search for an occurrence of the
string in the specified range but display the string only if it
is bounded on either side by af character that cannot be part of
an identifier in the current language.
NEXT
Specifies that the debugger search for the first occurrence of
the string in the specified range and display the line containing
this occurrence. This is the default.
STRING
Specifies that the debugger search for and display the string as
specified, and not interpret the context surrounding an
occurrence of the string, as it does in the case of IDENTIFIER.
This is the default.
Examples
DBG> SET SEARCH ALL,IDENT
DBG> SEARCH FOO X ! Find all occurences of X in module FOO
module FOO
21: X = 3
33: Y = X+1
SOURCE
Directs the debugger in the location of source file(s) by
overriding selected field(s) in the full file specification of
the original (at compile time) source file(s).
Typically you would specify a directory, or a search list of
directories. For example:
DBG> SET SOURCE [],SRC$
The above says to first look for the source file in the current
working directory, then look for it in the directory with the
logical name SRC$. If several versions of the file exist in the
specified directory then the debugger attempts to choose the
right one by matching the date and time of the file with the
information it has in the symbol table.
Format:
SET SOURCE[/MODULE=modname][/EDIT] dirname[,dirname...]
Additional information available:
Parameters
dirname
Specifies one or more file-specification fields to insert in
place of the corresponding field(s) in the full file
specification of the original (at compile time) source file(s).
Dirname may consist of one, several, or all of the following
fields in the full file specification, which has the following
format:
node::device:[directory]file-name.file-type;version-number
Typically, the reason for using SET SOURCE is that the file has
been copied to another directory, and in this case you would just
specify the [directory] portion of the full file spec.
Qualifiers
Additional information available:
/MODULE=modname
Specifies that the indicated directory search list is to be used
in locating source files only for the specified module.
/EDIT
Specifies that the indicated directory search list is to be used
only for the EDIT command.
STEP
The SET STEP command establishes default qualifiers (/LINE,
/INTO, and so on) for subsequent STEP commands.
Format:
SET STEP step-default[,...]
The parameters that you specify in the SET STEP command have the
same names as the STEP command qualifiers.
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.
If you invoke screen mode with the keypad-key sequence PF1-PF3,
the command SET STEP NOSOURCE is entered in addition to the
command SET MODE SCREEN. 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.
Additional information available:
BRANCHCALLEXCEPTIONINSTRUCTIONINTO
JSBLINENOJSBNOSHARENOSILENTNOSOURCENOSYSTEM
OVERRETURNSHARESILENTSOURCESYSTEM
Parameters
Step-default
The following parameters affect where the STEP command suspends
execution after a step:
SET STEP BRANCH
SET STEP CALL
SET STEP EXCEPTION
SET STEP INSTRUCTION
SET STEP INSTRUCTION=(opcode-list)
SET STEP LINE
SET STEP RETURN
The following parameters affect what output is seen when a STEP
command is executed:
SET STEP [NO]SILENT
SET STEP [NO]SOURCE
The following parameters affect what happens at a routine call:
SET STEP INTO
SET STEP [NO]JSB
SET STEP OVER
SET STEP [NO]SHARE
SET STEP [NO]SYSTEM
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 condition).
INSTRUCTION
Subsequent STEP commands are treated as STEP/INSTRUCTION (step to
the next instruction). You can also specify one or more
instructions (INSTRUCTION=(opcode- list)). The debugger then
steps to the next instruction that is in the specified list.
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 means of 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).
JSB
If INTO is in effect, subsequent STEP commands are treated as
STEP/INTO/JSB (step into routines called by a JSB instruction as
well as those called by a CALL instruction). This is the default
for all languages except DIBOL.
LINE
Subsequent STEP commands are treated as STEP/LINE (step to the
next line). This is the default for all languages.
NOJSB
If INTO is in effect, subsequent STEP commands are treated as
STEP/INTO/NOJSB (step over routines called by a JSB instruction,
but step into routines called by a CALL instruction). This is
the default for DIBOL.
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).
NOSILENT
Subsequent STEP commands are treated as STEP/NOSILENT (after a
step, display the "stepped to . . . " message). This is the
default.
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).
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).
OVER
Subsequent STEP commands are treated as STEP/OVER (step over all
called routines) rather than STEP/INTO (step into called
routines). SET STEP OVER is the default.
RETURN
Subsequent STEP commands are treated as STEP/RETURN (step to the
RET instruction of the routine that is currently executing --
that is, up to the point just prior to transferring control back
to the calling routine).
SHARE
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). This is the default.
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).
SOURCE
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).
This is the default.
SYSTEM
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). This is the
default.
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 to not
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.
TASK
(Only valid for ADA multitasking programs).
Modifies certain characteristics of tasks in your program. Using
this command, you can change a task's priority, put a task on
hold, switch to a different active task, make a task visible to
the debugger, cause a task to abort, or change the time all tasks
are given to execute.
For those commands which operate on individual tasks, the tasks
to modify can be specified by taskname parameters and/or by "task
selection qualifiers". If neither of these means are used, the
task defaults to the "visible task", %VISIBLE_TASK. (See SET
TASK/VISIBLE and SET TASK/ACTIVE).
Format:
SET TASK [/qualifier...] [taskname [,taskname...] ]
Additional information available:
ParametersSelection QualifiersAttribute QualifiersExamples
Parameters
taskname
A taskname parameter may be a pathname which designates a task
declared in your program, for example, MY_MAIN\PROG\MONITOR.
A taskname parameter may also be a task ID or pseudo taskname. A
task ID is a unique number that is associated with a task at the
time the task is created. The debugger syntax for specifying a
task ID is "%TASK n", where "n" is a positive decimal integer.
You can see what task IDs are assigned to currently existing
tasks by typing SHOW TASK/ALL.
A pseudo taskname is one of the built-in symbols %ACTIVE_TASK,
%CALLER_TASK, %NEXT_TASK, or %VISIBLE_TASK. Type "HELP Lexicals"
for more information on these.
The default taskname parameter is %VISIBLE_TASK.
Selection Qualifiers
There is only one task selection qualifier, the /ALL qualifier.
It cannot be used in combination with taskname parameters.
Additional information available:
/ALL
Selects all tasks that currently exist in your program to be
modified as specified by the other qualifiers given. Taskname
parameters are not permitted.
Attribute Qualifiers
These qualifiers determine what task attributes are to be
modified. If no task attribute qualifer is given, the qualifier
/VISIBLE is assumed by default.
Additional information available:
/ABORT/ACTIVE/HOLD/PRIORITY/RESTORE/TIME_SLICE
/VISIBLE
/ABORT
Forces an ABORT of the selected tasks.
/ACTIVE
Causes the task given by the taskname parameter to become the
"active task" (see Lexicals %ACTIVE_TASK). The active task is
that task which executes instructions when the debugger is left
(as when you type GO, STEP, or CALL). It is marked with a '*' in
the SHOW TASK display.
The SET TASK/ACTIVE command allows you to force a "task switch"
to the named task without leaving the debugger.
In addition to making the named task become the active task, this
command also makes it become the visible task, which is the
default task assumed by other debugging commands.
This qualifier requires exactly one taskname parameter and the
named task must be in either the READY or the RUN state.
/HOLD
/HOLD
/NOHOLD
Controls whether or not the selected task(s) is allowed to make
the transition into the RUN state (that is become the active
task).
Placing a task on HOLD restricts the state transitions the task
can make once the program is subsequently allowed to execute. A
task that is already in the RUNNING state (the active task) and
is then placed on HOLD can continue to execute as long as it
remains in the RUNNING state. If the task leaves the RUNNING
state while on HOLD, or is placed on HOLD while in another state,
it cannot enter the RUNNING state until the HOLD is removed or
until it is made active with the SET TASK/ACTIVE command.
/PRIORITY = n
Causes the selected task(s) to have its priority changed to n,
where n is a decimal integer from 0 to 15 inclusive. (VAX Ada
specifies subtype PRIORITY to be INTEGER range 0..15).
/RESTORE
Causes the selected task(s) to have its natural priority
restored.
This allows you to undo the effect of SET TASK/PRIORITY, without
the need to remember the task's natural priority. The task's
natural priority is the value given by the pragma PRIORITY in the
task specification.
/TIME_SLICE = t
Change the current setting of the value of the Ada pragma
TIME_SLICE to t, where t is given as a fixed point decimal number
of seconds.
This is the time used by the Ada multitasking system for
round-robin scheduling. (See the command SET TASK/TIME_SLICE).
The task list and task selection qualifiers must be omitted.
/VISIBLE
Causes the task given by the taskname parameter to become the
"visible task" (see Lexicals %VISIBLE_TASK).
The visible task is the default task assumed by debugging
commands when you do not (or cannot) specify a task. For
example, the debugger command EXAMINE %R0 displays register 0 of
the visible task.
The task whose execution entered the debugger is called the
active task. Each time the debugger is entered, the visible task
and the active task are one and the same. Using this qualifier,
you can make the visible task be a task other than the active
task.
This qualifier requires exactly one taskname parameter.
Examples
SET TASK/PRI=3 X,Y
Set the priority of tasks X and Y to 3.
SET TASK/RESTORE X
Restore the priority of task X.
SET TASK/ALL/HOLD
Put all tasks on hold.
SET TASK/ALL/NOHOLD
Remove hold status from all tasks that are currently held.
SET TASK/VISIBLE X
Make task X be the default visible task.
SET TASK/ACTIVE %TASK 3
Switch from the currently active task to task 3 and remain in the
debugger.
TERMINAL
The debugger obtains the size of your terminal when you begin
your debugging session, and uses this size information (width and
height) when formatting output. You may change your terminal
size during a debugging session with the SET TERMINAL command.
This command adjusts all the predefined windows for the new
screen size. (For example, H1 changes size to remain at the top
half of the new screen.)
This command also adjusts screen displays. Those displays that
are marked as DYNAMIC (See HELP [SET] DISPLAY/DYNAMIC) are
adjusted just like all the windows. Those displays that are
marked NODYNAMIC are not be affected.
Additional information available:
Examples
DBG> SET TERM/WIDTH:132
! Or on a VAXstation...
DBG> SET TERM/PAGE=55/WIDTH=155
Qualifiers
Additional information available:
/PAGE
Sets the terminal page size (that is, the number of lines on the
screen).
Format:
SET TERMINAL/PAGE:n
This qualifier specifies that the terminal is now n rows long.
"n" may have any value between 18 and 100. This qualifier is
most commonly used on a VAXstation.
/WIDTH
Sets the terminal screen width.
Format:
SET TERMINAL/WIDTH:n
This qualifier specifies that the terminal is now n columns wide.
Typically n is either 80 or 132 on VT100 type terminals, but may
have any value between 20 and 255. (these sizes are most
commonly used on a VAXstation.)
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[/qualifiers]
[address-expression[,...]]
[ WHEN (conditional-expression)]
[ DO (command[;...]]
When a tracepoint is triggered, the debugger takes the following
action:
1. Suspends program execution at the tracepoint location.
2. If /AFTER was specified when the tracepoint was set, 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 one was
specified when the tracepoint was set. 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 /SILENT was specified.
5. Displays the line of source code corresponding to the
tracepoint, unless /NOSOURCE or /SILENT was specified when
the breakpoint was set, or SET STEP NOSOURCE was entered
previously.
6. Executes the commands in a DO clause, if one was specified
when the tracepoint was set.
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. The only exception is
with the /EVENT qualifier, which requires that you specify an
event name keyword and permits you also to specify an address
expression for certain event names.
If you set a tracepoint at a location currently used as a
breakpoint, the breakpoint is canceled in favor of the
tracepoint, and vice versa.
Tracepoints may be user defined or predefined. User defined
tracepoints are those that you 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 invoke 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 may have both a
user defined and a predefined tracepoint. Canceling the user
defined tracepoint does not affect the predefined tracepoint, and
conversely.
Additional information available:
/ACTIVATING/AFTER:n/BRANCH/CALL/EVENT/EXCEPTION
/INSTRUCTION/INSTRUCTION/INTO/JSB/LINE
/MODIFY/NOJSB/NOSHARE/NOSILENT/NOSOURCE/NOSYSTEM
/OVER/RETURN/SHARE/SILENT/SOURCE/SYSTEM/TEMPORARY
/TERMINATING
Examples
1 DBG> SET TRACE SUB3
This command causes the debugger to trace the start 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 start 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 (EX Y)
This command causes the debugger to trace line 14 of module TEST5
when X is not equal to 2. At the tracepoint, the command EXAMINE
Y is issued. The /NOSOURCE qualifier suppresses the display of
source code at the tracepoint.
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.
6 DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
This SET TRACE command causes the debugger to trace the start of
routine SUB2 during execution. At the tracepoint, the DO clause
sets a watchpoint on variable K. The /SILENT qualifier on the
SET TRACE command 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 SET TRACE command causes the debugger to trace the RET
instruction of routine ROUT4 (that is, just before execution
returns to the calling routine). At the tracepoint, the DO
clause issues the command EXAMINE X. 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 when an Ada task makes
a transition to the TERMINATED state.
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 may
include a path name to specify the entity uniquely. More
generally, an address expression may also be a virtual memory
address or a register and may be composed of numbers (offsets)
and symbols, as well as one or more operators, operands, or
delimiters.
Do not specify the asterisk wildcard character (*). Do not
specify an address expression with /ACTIVATING, /BRANCH, /CALL,
/EXCEPTION, /INSTRUCTION[=(opcode- list)], /INTO, /[NO]JSB,
/LINE, /OVER, /[NO]SHARE, /[NO]SYSTEM, or /TERMINATING. The
/MODIFY and /RETURN qualifiers are used with specific kinds of
address expressions.
If you specify a virtual 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 may 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. CALLS and CALLG routines start with
an entry mask.
command
Specifies a debugger command that is to be executed as part of
the DO clause when trace action is taken.
conditional-expression
Specifies a conditional expression in the currently set language
that is to be evaluated whenever execution reaches the
tracepoint. If the expression is TRUE, trace action occurs, and
the debugger reports that a tracepoint has been reached. If the
expression is FALSE, trace action does not occur. In this case,
a report is not issued, the commands specified by the DO clause
are not executed, and program execution is continued.
Qualifiers
The qualifiers can be grouped as follows.
The /LINE qualifier sets a tracepoint on each line of source
code.
The following qualifiers set tracepoints on classes of
instructions. Note that use of these qualifiers and of the /LINE
qualifier causes the debugger to trace every instruction of your
program as it executes and thus significantly slows down
execution: /BRANCH, /CALL, /INSTRUCTION,
/INSTRUCTION=(opcode-list), /RETURN.
The following qualifiers set tracepoints on classes of events:
/ACTIVATING, /EVENT=event-name, /EXCEPTION, /TERMINATING.
The following qualifiers affect what happens at a routine call:
/INTO, /[NO]JSB, /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.
The /MODIFY qualifier is used to monitor changes at program
locations (typically changes in the values of variables).
/ACTIVATING
Note: This qualifier applies to a multiprocess debugging
configuration (when DBG$PROCESS has the value MULTIPROCESS).
Causes the debugger to trace when a new process comes under
debugger control. This is the default behavior. Do not specify
an address expression with /ACTIVATING. See also /TERMINATING.
/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 command SET TRACE/AFTER:1 has the same effect as the
SET TRACE command.
/BRANCH
Causes the debugger to trace every branch instruction encountered
during program execution (including BEQL, BGTR, BLEQ, BGEQ, BLSS,
BGTRU, BLEQU, BVC, BVS, BGEQU, BLSSU, BRB, BRW, JMP, BBS, BBC,
BBSS, BBCS, BBSC, BBCC, BBSSI, BBCCI, BLBS, BLBC, ACBB, ACBW,
ACBL, ACBF, ACBD, ACBG, ACBH, AOBLEQ, AOBLSS, SOBGEQ, SOBGTR,
CASEB, CASEW, CASEL). Do not specify an address expression with
/BRANCH. See also /INTO, /OVER.
/CALL
Causes the debugger to trace every call instruction encountered
during program execution (including the CALLS, CALLG, BSBW, BSBB,
JSB, RSB, and RET instructions). Do not specify an address
expression with /CALL. See also /INTO, /OVER.
/EVENT=event-name
Note: This qualifier applies only to Ada and SCAN. See the VAX
Ada and VAX SCAN documentation for complete information.
Causes the debugger to trace the specified event (if that event
is defined and detected by the run-time system). If you specify
an address expression with /EVENT, causes the debugger to trace
whenever the specified event occurs for that address expression.
Event names depend on the run-time facility. You can display the
event names associated with the current run-time facility by
entering the SHOW EVENT_FACILITY command. Note that you cannot
specify an address expression with certain event names.
/EXCEPTION
Causes the debugger to trace every exception that is signaled.
The trace action occurs before any user- written exception
handlers are invoked. Do not specify an address expression with
/EXCEPTION.
As a result of a SET TRACE/EXCEPTION command, whenever your
program generates an exception condition, the debugger reports
the exception condition and resignals the exception, thus
allowing any user-declared exception handler to execute.
/INSTRUCTION
Causes the debugger to trace every instruction executed. Do not
specify an address expression with /INSTRUCTION. See also /INTO,
/OVER.
/INSTRUCTION=(opcode-list)
Causes the debugger to trace every instruction whose opcode is in
the list. Do not specify an address expression with
/INSTRUCTION. See also /INTO, /OVER.
/INTO
Applies only to tracepoints set with /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE; that is, when an address
expression is not explicitly specified. When used with those
qualifiers, causes the debugger to trace the specified points
within called routines (as well as within the routine where
execution is currently suspended). /INTO is the default behavior
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.
/JSB
Qualifies /INTO. Use /JSB only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE. /JSB permits the
debugger to set tracepoints within routines that are called by
the JSB or CALL instruction. /JSB is the default for all
languages except DIBOL. Do not specify an address expression
with /[NO]JSB.
/LINE
Causes the debugger to trace the start of each new line. Do not
specify an address expression with /LINE. See also /INTO, /OVER.
/MODIFY
Causes the debugger to report a tracepoint whenever an
instruction writes to and modifies the value of a location
indicated by a specified address expression. The address
expression is typically a variable name.
The command SET TRACE/MODIFY X is equivalent to the command SET
WATCH X DO(GO). SET TRACE/MODIFY operates under the same
restrictions as SET WATCH.
If you specify an absolute address for the address expression,
the debugger may 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.
/NOJSB
Qualifies /INTO. Use /NOJSB only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/NOJSB specifies that tracepoints not be set within routines
called by JSB instructions. /NOJSB is the default for DIBOL
programs. In DIBOL, user- written routines are called by the
CALL instruction and DIBOL run-time library routines are called
by the JSB instruction. Do not specify an address expression
with /NOJSB.
/NOSHARE
Qualifies /INTO. Use /NOSHARE only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/NOSHARE specifies that tracepoints not be set within shareable
images. Do not specify an address expression with /[NO]SHARE.
/NOSILENT
Specifies that the "trace . . . " message is displayed at the
tracepoint. This is the default.
/NOSOURCE
Specifies that the source line for the current location is not
displayed at the tracepoint. See also SET STEP [NO]SOURCE.
/NOSYSTEM
Qualifies /INTO. Use /NOSYSTEM only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/NOSYSTEM specifies that tracepoints not be set within system
routines (P1 space). Do not specify an address expression with
/SYSTEM.
/OVER
Applies only to tracepoints set with /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE; that is, when an address
expression is not explicitly specified. When used with those
qualifiers, causes the debugger to trace the specified points
only within the routine where execution is currently suspended
(not within called routines). /OVER is the opposite of /INTO
(the default behavior).
/RETURN
Causes the debugger to trace the RET (return) instruction of the
routine associated with the specified address expression (which
may be a routine name, line number, and so on). This qualifier
can only be applied to routines called with a CALLS or CALLG
instruction; it cannot be used with JSB routines. Tracing the
RET instruction enables you to inspect the local environment (for
example, obtain the values of local variables) before the RET
instruction deletes the routine's call frame from the call stack.
Causes the debugger to trace the RETURN (RET) instruction of the
specified routine. This qualifier can only be applied to
routines called with a CALLS or CALLG instruction; it cannot be
used with JSB routines.
For this qualifier, the address-expression parameter is an
instruction address within a CALLS or CALLG routine. It may
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 command
if the same address expresion is specified.
/SHARE
Qualifies /INTO. Use /SHARE only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/SHARE (default) permits the debugger to set tracepoints within
shareable image routines as well as other routines. Do not
specify an address expression with /[NO]SHARE.
/SILENT
Specifies that the "trace . . . " message and the source line
for the current location are not displayed at the tracepoint.
/SILENT overrides /SOURCE.
/SOURCE
Specifies that the source line for the current location is
displayed at the tracepoint. This is the default. See also SET
STEP [NO]SOURCE.
/SYSTEM
Qualifies /INTO. Use /SYSTEM only with /INTO and one of the
following qualifiers: /BRANCH, /CALL,
/INSTRUCTION[=(opcode-list)], or /LINE.
/SYSTEM (default) permits the debugger to set tracepoints within
system routines (P1 space) as well as other routines. Do not
specify an address expression with /SYSTEM.
/TEMPORARY
Causes the tracepoint to disappear after it is triggered (the
tracepoint does not remain permanently set).
/TERMINATING
Causes the debugger to trace when a process performs an image
exit. This is the default behavior. Note that the debugger
always gains control and displays its prompt when the last image
of a single-process or multiprocess program exits. Do not
specify an address expression with /TERMINATING. See also
/ACTIVATING.
TYPE
Establishes the default type to be associated with untyped
program locations and, when the /OVERRIDE qualifier is specified,
the type to be associated with both untyped program locations and
program locations that have compiler-generated types.
Format:
SET TYPE [/qualifier] type-keyword
Additional information available:
ASCICASCIDASCIWASCIZBYTED_FLOATDATE_TIME
FLOATG_FLOATH_FLOATINSTRUCTIONLONGOCTAWORD
QUADWORDWORD
ParametersASCII:nPACKED:nTYPE=(t)QualifiersExamples
Parameters
type-keyword
May be one of the following debugger types:
o BYTE -- Type byte integer (length 1 byte).
o WORD -- Type word integer (length 2 bytes).
o LONGWORD -- Type longword integer (length 4 bytes).
o QUADWORD -- Type quadword integer (length 8 bytes).
o OCTAWORD -- Type octaword integer (length 16 bytes).
o PACKED:n -- Type packed decimal (length n nibbles).
o ASCII:n -- Type ASCII character (length n bytes). Each
character occupies one byte of memory. If you do not specify
a value for n, the debugger assumes a default length of 4
bytes. The value n is interpreted in decimal radix.
o ASCIC -- Counted ascii string (byte count).
o ASCIW -- Counted ascii string (word count).
o ASCIZ -- Zero-terminated ascii string.
o DATE_TIME -- Type date-time (internal VMS representation).
o INSTRUCTION -- Type instruction whose length is variable,
depending on the number of instruction operands and the kind
of addressing modes used.
o FLOAT -- F_floating type (length 4 bytes). Values of type
F_floating may range from .29*10**-38 to 1.7*10**38 with
approximately 7 decimal digits of precision.
o D_FLOAT -- D_floating type (length 8 bytes). Values of type
D_floating may range from .29*10**-38 to 1.7*10**38 with
approximately 16 decimal digits of precision.
o G_FLOAT -- G_floating type (length 8 bytes). Values of type
G_floating may range from .56*10**-308 to .9*10**308 with
approximately 15 decimal digits of precision.
o H_FLOAT -- H_floating type (length 16 bytes). Values of type
H_floating may range from .84*10**-4932 to .59*10**4932 with
approximately 33 decimal digits of precision.
o TYPE=(t) -- Same type as "t", where "t" is a variable in your
program.
ASCIC
Sets the default type to counted ASCII.
ASCID
Sets the default type to ASCID.
ASCII:n
Sets the default type to ASCII strings of length n.
ASCIW
Sets the default type to word-counted ASCII.
ASCIZ
Sets the default type to zero-terminated ASCII.
BYTE
Sets the default type to byte-integer.
D_FLOAT
Sets the default type to D_Floating.
DATE_TIME
Sets the default type to be VMS internal date/time
representation.
FLOAT
Sets the default type to single-precision floating.
G_FLOAT
Sets the default type to G_Floating.
H_FLOAT
Sets the default type to H_Floating.
INSTRUCTION
Sets the default type to instruction.
LONG
Sets the default type to LONG.
OCTAWORD
Sets the default type to OCTAWORD.
PACKED:n
Sets the default type to PACKED with length n.
QUADWORD
Sets the default type to QUADWORD.
TYPE=(t)
Sets the default type to be the same type as "t", where "t" is a
variable in your program.
WORD
Sets the default type to WORD.
Qualifiers
Additional information available:
/OVERRIDE
Indicates that the specified type be associated with untyped
program locations and with those locations that have
compiler-generated types.
Examples
DBG> SET TYPE ASCII
! Now untyped locations get displayed as ASCII strings.
DBG> EXAM 1000 ! Location 1000 has no compiler-generated type.
1000: "...."
DBG> SHOW SYM/TYPE X
data FOO\X
type: floating point (F_FLOAT, size 4 bytes)
DBG> EXAMINE X
FOO\X: 1.2 ! X does have a type (float), so it is
displayed
! according to that type.
DBG> SET TYPE/OVERR ASCII
DBG> EXAMINE X
FOO\X: "...." ! Now X is displayed as ASCII because of the
! /OVERRIDE qualifier on the SET TYPE.
WATCH
Establishes a watchpoint at the location denoted by an address
expression.
Format:
SET WATCH [/qualifiers]
address-expression [,...]
[ WHEN (conditional-expression)]
[ DO (command[;...])]
Whenever an instruction causes the modification of a watched
location, the debugger takes the following action:
1. Suspends program execution after that instruction has
completed execution.
2. If /AFTER was specified when the watchpoint was set, 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 one was
specified when the watchpoint was set. 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,
unless /SILENT was specified.
5. Reports the old (unmodified) value at the watched location.
6. Reports the new (modified) value at the watched location.
7. Displays the line of source code where execution is
suspended, unless /NOSOURCE or /SILENT was specified when the
watchpoint was set, or SET STEP NOSOURCE was entered
previously.
8. Executes the commands in a DO clause, if one was specified
when the watchpoint was set. 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 watched location. If you
specify an absolute memory address that the debugger cannot
associate with a compiler-generated type, the debugger watches 4
bytes of virtual 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 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.
Additional information available:
ExamplesGlobal Section WatchpointsParametersQualifiersStatic Nonstatic Watchpoints
/AFTER:n/INTO/NOSILENT/NOSOURCE/NOSTATIC/OVER
/SILENT/SOURCE/STATIC/TEMPORARY
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 is triggered whenever any array
element changes. In this case the third element changed.
3 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 on
the SET TRACE command suppresses the "trace at . . . " message
and the display of source code at the tracepoint.
4 DBG_1> SET WATCH ARR(1)
DBG_1> SHOW WATCH
watchpoint of PPL3\ARR(1)
DBG_1> GO
%DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has been
remapped to a global section
predefined trace on activation at routine PPL3
in %PROCESS_NUMBER 2
predefined trace on activation at routine PPL3
in %PROCESS_NUMBER 3
watch of PPL3\ARR(1) at PPL3\%LINE 93 in %PROCESS_NUMBER 2
93: ARR(1) = INDEX
old value: 0
new value: 1
break at PPL3\%LINE 94 in %PROCESS_NUMBER 2
94: ARR(I) = I
DBG_2> DO (SHOW WATCH)
For %PROCESS_NUMBER 1
watchpoint of PPL3\ARR(1) [global-section watchpoint]
For %PROCESS_NUMBER 2
watchpoint of PPL3\ARR(1) [global-section watchpoint]
For %PROCESS_NUMBER 3
watchpoint of PPL3\ARR(1) [global-section watchpoint]
DBG_2>
In this example of a global section watchpoint, the SET WATCH
command sets a watchpoint on element 1 of array ARR. Because ARR
has not yet been mapped to a global section, the SHOW WATCH
command identifies the watchpoint as a conventional static
watchpoint.
After the GO command resumes execution, ARR is remapped to a
global section. The watchpoint is automatically treated as a
global section watchpoint.
Processes 2 and 3 come under debugger control, then the
watchpoint is triggered in process 2, interrupting execution. At
this point, the SHOW WATCH command confirms that the watchpoint
is visible from each process.
Global Section Watchpoints
You can set watchpoints on variables or arbitrary program
locations in global sections. A global section is a region of
virtual 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.
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 may include a path
name to specify the variable uniquely. More generally, an
address expression may also be a virtual memory address or a
register and may be composed of numbers (offsets) and symbols, as
well as one or more operators, operands, or delimiters.
Do not specify the asterisk wildcard character (*).
command
Specifies a debugger command that is to be executed as part of
the DO clause when watch action is taken.
conditional-expression
Specifies a conditional expression in the currently set language
that is to be evaluated whenever execution reaches the
watchpoint. If the expression is TRUE, watch action occurs, and
the debugger reports that a watchpoint has been triggered. If
the expression is FALSE, watch action does not occur. In this
case, a report is not issued, the commands specified by the DO
clause are not executed, and program execution is continued.
Qualifiers
The qualifiers can be grouped as follows.
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 qualifiers are used to override the debugger's
determination of whether a variable is static or nonstatic:
/[NO]STATIC.
Static 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 virtual 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 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 the PC value is within the scope of the
defining routine (including any routine called by the definining
routine). The watchpoint is cancelled when execution returns
from the defining routine.
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 through 3FFFFFFF, hexadecimal); a nonstatic
variable is in P1 space (40000000 through 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 the PC value is not within the scope of the
defining routine. The /[NO]STATIC qualifiers enable you to
override the default behavior. For example, if you have
allocated nonstack storage in P1 space, use the /STATIC qualifier
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 stack in P0 space, use the /NOSTATIC qualifier
when setting a watchpoint on a variable that is allocated on that
stack. This enables the debugger to treat the watchpoint as a
nonstatic watchpoint.
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 down execution, the debugger
issues a message when you set a nonstatic watchpoint. The /INTO
and /OVER qualifiers enable you to choose whether to also trace
instructions within any routine that is called by the defining
routine or to execute the called routine at normal speed.
/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
command SET WATCH/AFTER:1 has the same effect as the SET WATCH
command.
/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). SET WATCH/INTO 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.
/NOSILENT
Specifies that the "watch . . . " message is displayed at the
watchpoint. This the default.
/NOSOURCE
Specifies that the source line for the current location is not
displayed at the watchpoint. See also SET STEP [NO]SOURCE.
/NOSTATIC
Enables you to override the debugger's default determination of
whether a specified variable (location) is static or nonstatic.
/NOSTATIC specifies that the debugger should treat the variable
as a nonstatic variable, even though it may be allocated in P0
space. /NOSTATIC causes the debugger to monitor the location by
tracing every instruction. Exercise caution when using this
qualifier.
/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. SET WATCH/OVER 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. SET WATCH/OVER is the default behavior when
you set watchpoints on nonstatic variables.
/SILENT
Specifies that the "watch . . . " message and the source line
for the current location are not displayed at the watchpoint.
/SILENT overrides /SOURCE.
/SOURCE
Specifies that the source line for the current location is
displayed at the watchpoint. This is the default. /SILENT
overrides /SOURCE. See also SET STEP [NO]SOURCE.
/STATIC
Enables you to override the debugger's default determination of
whether a specified variable (location) is static or nonstatic.
/STATIC specifies that the debugger should treat the variable as
a static variable, even though it may 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. Exercise caution when using this qualifier.
/TEMPORARY
Causes the watchpoint to disappear after it is triggered (the
watchpoint does not remain permanently set).
WINDOW
Establishes a screen window definition. A screen window is a
region on the terminal screen at which a screen display may be
displayed. A screen window definition associates a window name
with a screen region specified in terms of a beginning line,
height (line count), beginning column, width (characters per
line). The last two values are optional and, if not specified,
default to column 1 and the current terminal screen width
respectively. Once defined, the name of a screen window can be
used in DISPLAY and SET DISPLAY commands to position screen
displays on the screen.
Format:
SET WINDOW wname AT (start-line, line_count
[, start-column, column-count])
Additional information available:
Parameters
wname
The name of the window being defined.
start-line
The starting line number of the window. This is the line at
which the window header line is displayed. The top line of the
screen is line 1.
line-count
The number of lines of text in the window, not counting the
header line. Line-count must be at least 1. Start-line plus
line-count may not exceed the current screen height.
start-column
The starting column number of the window. This is the column at
which the first character in the window is displayed. Note, the
left hand border may occupy the column just to the left of the
starting column number. The left most column on the screen is
column 1.
column-count
The number of characters per line in the window. Column-count
must be at least 1 and less than the current terminal screen
width. Start-column plus column-count may not exceed the current
screen width.
Examples
! Make a window named ONELINE at the top of the
! screen that spans the entire width of the screen.
!
DBG> SET WINDOW ONELINE AT (1,1)
! Make a window named MIDDLE for the central
! region of the screen.
!
DBG> SET WINDOW MIDDLE AT (9,4,30,20)