DEBUG SET — VMS 5.1-B
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:
ATSIGNBREAKDEFINEDISPLAYEDITOREVENT_FACILITY
IMAGEKEYLANGUAGELOGMARGINMAX_SOURCE_FILES
MODEMODULEOUTPUTPROMPTRADIXSCOPESEARCH
SOURCESTEPTASKTERMINALTRACETYPEWATCH
WINDOW
Parameters
keyword
Keyword can be ATSIGN, BREAK, DEFINE, DISPLAY, EDITOR,
EVENT_FACILITY, EXCEPTION BREAK, LANGUAGE, LOG, MARGIN,
MAX_SOURCE_FILES, MODE, MODULE, OUTPUT, RADIX, SCOPE, SEARCH,
SOURCE, STEP, TASK, TERMINAL, TRACE, TYPE, WATCH or WINDOW.
qualifiers
Depends on the keyword specified.
parameters
Depends on the keyword specified.
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 will be executed as a
command procedure.
BREAK
Establishes a breakpoint. The breakpoint may be at a specified
address (for example, SET BREAK %LINE 15), or it may be at a
certain class of instructions (for example, SET BREAK/CALL to
break on all calls and returns).
When a breakpoint is activated, the debugger suspends program
execution, reports the breakpoint, and prompts for your commands.
An optional WHEN clause specifies a condition to be tested each
time the breakpoint is reached. If the condition is not met, the
breakpoint is not taken.
An optional DO clause specifies debugger commands to be executed
each time the breakpoint is taken.
Format:
SET BREAK [/qualifiers]
[address-expression[,address-expression...]]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
Additional information available:
/AFTER:n/BRANCH/CALL/EVENT/EXCEPTION/INSTRUCTION
/INSTRUCTION/LINE/MODIFY/NOSILENT/NOSOURCE
/RETURN/SILENT/SOURCE/TEMPORARY
Parameters
address-expression
Specifies the location(s) at which the breakpoint is to be set.
If more than one address-expression is given, multiple
breakpoints are set.
conditional-expression
A language expression which is evaluated when the breakpoint is
about to be activated. The breakpoint is then activated if and
only if the expression evaluates to TRUE.
debug-cmd-list
Any debugger command that you want the debugger to execute when
the breakpoint is taken.
Example:
DBG> SET BREAK SUBR -
WHEN (X .EQ. 4) DO (EX X;EX Y)
Qualifiers
The qualifiers can be grouped as follows:
These give a condition to break on and thus take the place
of an address expression:
/BRANCH /CALL /EVENT /EXCEPTION
/INSTRUCTION /INSTRUCTION=(opcode-list) /LINE
These control how much information to display at the breakpoint:
/[NO]SILENT /[NO]SOURCE
Other qualifiers:
/AFTER:n /MODIFY /RETURN /TEMPORARY
See the individual subtopics for details.
/AFTER:n
Specifies that break action not be taken until the nth time it is
hit.
Example:
DBG> SET BREAK/AFTER:5 %LINE 5
/BRANCH
Causes you to break at every branch instruction. An address
expression is not allowed -- that is, SET BREAK/BRANCH is
sufficient. After specifying SET BREAK/BRANCH, every GO command
acts like a STEP/BRANCH.
Example: Break when X is no longer equal to zero, where the
condition is tested at each branch instruction:
DBG> SET BREAK/BRANCH WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/CALL
Causes you to break at every call or return instruction. An
address expression is not allowed -- that is, SET BREAK/CALL is
sufficient. After specifying SET BREAK/CALL, every GO command
acts like a STEP/CALL.
Example: Break when X is no longer equal to zero, where the
condition is tested at each call or return instruction:
DBG> SET BREAK/CALL WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/EVENT
Causes you to break on an event which is defined by and detected
by the run time system of a language or other run time facility.
Format:
SET BREAK/EVENT=keyword [/qualifiers]
[expression[, expression...]]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
keyword
The keyword determines the type of event to break on. The events
and the event names (that is, the allowed keywords) are defined
by the run time facility. To select a particular run time
facility use the command SET EVENT_FACILITY. To see which run
time facility has been selected and what the allowed keywords
are, use the command SHOW EVENT_FACILITY.
expression
The allowed parameters are determined by the particular event and
event facility. Generally, they may be either address
expressions or language expressions. Parameters may be optional,
in which case omitting them implies a "wildcard" as a parameter.
Some types of events may not allow parameters at all.
qualifiers
The only qualifiers that are allowed with the /EVENT qualifier
are /AFTER, /SILENT, /SOURCE, and /TEMPORARY.
WHEN and DO clauses
These behave the same as for other types of breakpoints.
Examples
The VMS Ada multitasking system defines a set of events dealing
with task state transitions. Accordingly the allowed parameters
are task names. When debugging an Ada program, you might use the
following commands:
SET BREAK/EVENT=RUN ALPHA, %TASK 3
Trigger a breakpoint when either task ALPHA, or the task whose ID
is 3 goes into the run state.
SET BREAK/EVENT=TERMINATED DO (SHOW TASK/ALL)
Trigger a breakpoint when any task terminates and execute the
debugger command to display all the tasks in the program.
/EXCEPTION
Causes the debugger to treat an exception condition generated by
your program as a breakpoint (for example if your program takes
an ACCVIO, or signals an exception). If you enter a GO command
from an exception breakpoint, the VMS condition handling facility
looks for exception handlers in your program. Thus, an exception
breakpoint is a stopping point after the exception occurs but
before your program's handlers are invoked.
Do not specify an address expression with SET BREAK/EXCEPTION.
Example:
DBG> SET BREAK/EXCEPTION DO (SHOW CALLS; GO)
/INSTRUCTION
Causes you to break at every machine instruction. An address
expression is not allowed -- that is, SET BREAK/INSTRUCTION is
sufficient. After specifying SET BREAK/INSTRUCTION, then every
GO command acts like a STEP/INSTRUCTION.
Example: Break when X is no longer equal to zero, where the
condition is tested at each machine instruction:
DBG> SET BREAK/INST WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/INSTRUCTION=(opcode-list)
Causes you to break at each instruction which is in the given
opcode list. For example:
DBG> SET BREAK/INSTR=(ADDL3)
The above causes a break to occur each time an ADDL3 instruction
is about to be executed. Note that this is one of the forms of
SET BREAK that requires the debugger to trace every instruction
your program executes, and thus this form of SET BREAK will
significantly slow down your program's execution.
/LINE
Causes you to break at every line. An address expression is not
allowed -- that is, SET BREAK/LINE is sufficient. After
specifying SET BREAK/LINE, then every GO command acts like a
STEP/LINE.
Example: Break when X is no longer equal to zero, where the
condition is tested at each line:
DBG> SET BREAK/LINE WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/MODIFY
"SET BREAK/MODIFY address-expression" specifies that you want to
be notified when the value at the given address changes. This is
synonymous with "SET WATCH address-expression".
Example:
DBG> SET BREAK/MODIFY X DO (SHOW CALLS)
/NOSILENT
Opposite of /SILENT. This specifies that you do want to see the
"break at ..." message when the breakpoint is activated. Since
this is the default, the qualifier is a no-op and is just
included for completeness.
/NOSOURCE
Specifies that you do not want to see source display when the
breakpoint is activated. This qualifier is included for
completeness (that is, there is a STEP/NOSOURCE and a SET STEP
NOSOURCE so there should be a SET BREAK/NOSOURCE ...).
/RETURN
A "return" breakpoint is activated at the return of the specified
routine. For example, SET BREAK/RETURN SUBR will cause you to
break at the return from the routine SUBR, rather than at the
start of the routine. This is done by setting an "invisible"
breakpoint at SUBR and then essentially doing a STEP/RETURN from
that invisible breakpoint, so that the break actually occurs at
the return from the routine.
Example:
DBG> SET BREAK/RETURN %LINE 15; GO
break on return from routine SUBR\%LINE 115 ...
The break occurs before the execution of the RET instruction, so
that all the stack locals are still available. Return breaks are
thus useful for observing the values of variables at the end of a
routine.
/SILENT
Specifies that you do not want to see either the "break at..."
message or the source display when the breakpoint is activated.
Silent breaks or silent traces are usually specified with a DO
clause (that is, you want to take some action at a given point,
but are not particularly interested in the "break at ..."
message).
Example:
DBG> SET BREAK/SILENT SUBR DO (SHOW CALLS; GO)
/SOURCE
Specifies that you want to see source display when the breakpoint
is activated. This is normally the default (unless you have said
SET STEP NOSOURCE).
/TEMPORARY
Specifies that the breakpoint stay around for only one activation
-- that is, the breakpoint will automatically be canceled after
it is triggered.
Example:
DBG> SET BREAK/TEMPORARY %LINE 15 ! This is the same as:
DBG> SET BREAK %LINE 15 DO (CANCEL BREAK %LINE 15)
DEFINE
Specifies how to interpret DEFINE commands. The DEFINE command
can bind a symbol to either an address, a command string, or a
value.
Example:
DBG> SET DEFINE COMMAND
DBG> DEFINE B = "SET BREAK"
DBG> DEFINE M = "SET MODULE"
Additional information available:
Parameters
ADDRESS Treat subsequent DEFINE commands as DEFINE/ADDRESS.
COMMAND Treat subsequent DEFINE commands as DEFINE/COMMAND.
VALUE Treat subsequent DEFINE commands as DEFINE/VALUE.
ADDRESS
Treat subsequent DEFINE commands as DEFINE/ADDRESS.
COMMAND
Treat subsequent DEFINE commands as DEFINE/COMMAND.
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]...]]
Example:
DBG> SET DISPLAY/MARK EXAM AT Q2 DO (EXAM A,B,C)
Additional information available:
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/POP
/PUSH/REMOVE/SIZE:n
/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.
/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.
/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.
EDITOR
Establishes the editor which will be 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 will 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 this will be
SPAWNed to DCL when the EDIT command is used.
For /CALLABLE_LSEDIT and /CALLABLE_TPU, the command_line
specified will be 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 will be 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 will cause EDIT to spawn the command line
'@MAIL$EDIT ""', which will invoke the same editor used in MAIL.
The second command will cause EDIT to invoke CALLABLE_EDT. No
command line is allowed with CALLABLE_EDT.
The third command will cause EDIT to invoke CALLABLE_TPU with the
default command line of "TPU".
The fourth command will cause EDIT to invoke CALLABLE_TPU with
the command line "TPU/SECTION=MYSECINI.TPU$SECTION".
The last command will cause EDIT to invoke CALLABLE_LSEDIT with
the default command line of "LSEDIT". Also, the /START_POSITION
qualifier will be appended to the command line, so that the
editing session will start on the source line that the debugger
is currently pointing to.
EVENT_FACILITY
Format: SET EVENT_FACILITY facility_name
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").
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.
MARGIN
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 MARGIN 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 MARGIN 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 MARGIN lm:rm
lm:
:rm
Example:
DBG> SET MARGIN 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_FLOATKEYPADLINEMOVIENODYNAMIC
NOMOVIENOG_FLOATNOKEYPADNOLINENOOPERANDS
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 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 MOVIE -- "Movie mode" causes the screen display to be updated
more frequently (see description under MOVIE).
o NOMOVIE -- Cancels "movie mode" (see description under MOVIE).
(default).
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 will set the module for
you. For example, if you step into a function in a module that
is not set, the debugger will set the module and issue 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.
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
MOVIE
"Movie mode" causes the screen display to be updated on every
command, instead of only at the "DBG>" prompt. It is called
"movie mode" because you can watch your program run with "SET
MODE SCREEN,MOVIE; WHILE 1 DO (STEP)"
Movie mode is mainly useful for setting up demos that give
sequences of debugger commands from command files:
DBG> SET MODE SCREEN,MOVIE
DBG> @DEMO.DBG
In the default (nomovie) mode, the screen would not be updated
until the next DBG> prompt, after the entire demo command file
completes. Movie mode causes more frequent updating, and hence
the screen is updated after every command in DEMO.DBG, which is
what you would want.
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.
NOMOVIE
Cancels "movie mode" (see description under MOVIE). (default).
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).
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 will not be 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 will not be 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.
PROMPT
Allows you to change the debugger prompt from "DBG> " to a string
of your choice. The parameter to SET PROMPT is the string which
will become the new prompt. If the string contains blanks,
semicolons, or lower-case characters then it must be enclosed in
quotes, for example,
DBG>SET PROMPT "d b g > "
d b g > SET PROMPT DBG>
DBG>
On VAXstations, also allows you to control whether the debugger
window automatically pops over other windows and is attached to
the keyboard when the debugger prompts for input. See the /POP
and /NOPOP qualifiers.
Format:
SET PROMPT [/qualifier] string
Additional information available:
Parameters
string
May be any string, optionally enclosed in single or double
quotes. If you do not specify a prompt string, the prompt string
is unchanged. Examples:
DBG> SET PROMPT "$ "
$ SET PROMPT XXX:
XXX:SET PROMPT 'DBG>'
DBG>EXIT
Qualifiers
Additional information available:
/NOPOP
This qualifier applies only to VAXstations.
Causes the debugger window to not pop over other windows, nor to
attach to the keyboard, when the debugger prompts for input.
This is the default behavior.
If you do not specify /POP or /NOPOP, the prompt behavior is set
to /NOPOP, the default.
/POP
This qualifier applies only to VAXstations.
Causes the debugger window to automatically pop over other
windows and attach to the keyboard whenever the debugger prompts
for input.
If you do not specify /POP or /NOPOP, the prompt behavior is set
to /NOPOP, the default.
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" will
show you 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.
What this default scope means is that a symbol lookup such as
"EXAMINE X" will first look for X in the routine that is
currently executing. If no X is visible there, then the debugger
will look in the caller of that routine. Next it will look 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
will set 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 will attempt 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
Establishes current step conditions to be used by the debugger
whenever a step command qualifier is not specified in a STEP
command.
Format:
SET STEP parameter [,parameter...]
Additional information available:
BRANCHCALLEXCEPTIONINSTRUCTIONINTO
JSBLINENOJSBNOSHARENOSILENTNOSOURCENOSYSTEM
OVERRETURNSHARESILENTSOURCESYSTEM
ParametersINSTRUCTION=(opcode-list)Examples
Parameters
The possible parameters are list below:
The following affect where you step to:
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 affect what output is seen on a STEP:
SET STEP [NO]SILENT
SET STEP [NO]SOURCE
The following affect what happens at a routine call:
SET STEP INTO
SET STEP OVER
SET STEP [NO]JSB
SET STEP [NO]SHARE
SET STEP [NO]SYSTEM
See the subtopics for further description.
BRANCH
Specifies that each step take you to the next branch instruction.
CALL
Specifies that each step take you to the next call instruction.
EXCEPTION
Specifies that each step take you to the next exception.
INSTRUCTION
Specifies that each step take you to the next machine
instruction.
INSTRUCTION=(opcode-list)
Specifies that the step operation should take you to the next
instruction that is a member of the set (opcode-list).
INTO
Specifies that when you step from a location containing a call to
a subroutine, you step into the called subroutine. You can
control the types of routines that you step into by also
specifying one or more of the following parameters: [NO]JSB,
[NO]SHARE, and [NO]SYSTEM.
JSB
Specifies that, if INTO is in effect, when you step from a
location containing a JSB or CALL instruction, you step into the
called routine. This is the default for all languages except
DIBOL.
LINE
Specifies that each step take you to the next source line of your
program.
NOJSB
Specifies that, if INTO is in effect, when you step from a
location containing a JSB or CALL instruction, you step over a
routine called with the JSB instruction, but into a routine
called with the CALL instruction. This is the default for DIBOL.
NOSHARE
Specifies that, if INTO is in effect, when you step from a
location containing a call to a routine in a shareable image, you
step over the routine.
NOSILENT
Specifies that you do want to see the "stepped to" message. That
is, this undoes the effect of a previous SET STEP SILENT.
NOSOURCE
Specifies that line(s) of source code not be displayed when STEP
commands are executed.
NOSYSTEM
Specifies that, if INTO is in effect, when you step from a
location containing a call to a routine in system space (P1
space), you step over the routine.
OVER
Specifies that when you step from a location containing a call to
a subroutine, you step over the called subroutine.
RETURN
Specifies that each step take you to the next level of return.
(That is, "STEP/RETURN n" will take you up n levels of your call
stack).
SHARE
Specifies that, if INTO is in effect, when you step from a
location containing a call to a routine in a shareable image, you
step into the routine. This is the default.
SILENT
Specifies that the "stepped to ..." message and all other output
be suppressed on step operations.
SOURCE
Specifies that line(s) of source code be displayed when STEP
commands are executed.
SYSTEM
Specifies that, if INTO is in effect, when you step from a
location containing a call to a routine in system space (P1
space), you step into the routine. This is the default.
Examples
DBG> SET MODE SCREEN; SET STEP SILENT
! The above puts you in screen mode and also turns off
! all "stepped to ..." output. Some people prefer to set
! step to "silent" when in screen mode since the step output
! is redundant in screen mode.
DBG> SET STEP NOSIL, NOSOURCE, INST
! The above turns "stepped to ..." output back on, turns off
! source output (since in screen mode the source output
! is redundant), and also specifies that you want to step
! by machine instruction and see the assembly language
! instructions as you step.
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 will execute 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 will adjust all the predefined windows for the new
screen size. (For example, H1 will change size to remain at the
top half of the new screen.)
This command will also adjust screen displays. Those displays
that are marked as DYNAMIC (See HELP [SET] DISPLAY/DYNAMIC) will
be adjusted just like all the windows. Those displays that are
marked NODYNAMIC will 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. The tracepoint may be at a specified
address (for example, SET TRACE %LINE 15), or it may be at a
certain class of instructions (for example, SET TRACE/CALL to
trace all calls and returns).
When a tracepoint is activated, the debugger reports the
tracepoint, executes any DO clauses, and then continues
execution.
An optional WHEN clause specifies a condition to be tested each
time the tracepoint is reached. If the condition is not met, the
tracepoint is not taken.
An optional DO clause specifies debugger commands to be executed
each time the tracepoint is taken.
Format:
SET TRACE[/qualifiers]
[address-expression[,address-expression...]]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
Additional information available:
/AFTER:n/BRANCH/CALL/EVENT/EXCEPTION/INSTRUCTION
/INSTRUCTION/LINE/MODIFY/NOSILENT/NOSOURCE
/RETURN/SILENT/SOURCE/TEMPORARY
Parameters
address-expression
Specifies the location(s) at which the tracepoint is to be set.
If more than one address-expression is given, multiple
tracepoints are set.
conditional-expression
A language expression which is evaluated when the tracepoint is
about to be activated. The tracepoint is then activated if and
only if the expression evaluates to TRUE.
debug-cmd-list
Any debugger command that you want the debugger to execute when
the tracepoint is taken.
Example:
DBG> SET TRACE SUBR -
WHEN (X .EQ. 4) DO (EX X;EX Y)
Qualifiers
The qualifiers can be grouped as follows:
These give a condition to trace on and thus take the place
of an address expression:
/BRANCH /CALL /EVENT /EXCEPTION
/INSTRUCTION /INSTRUCTION=(opcode-list) /LINE
These control how much information to display at the tracepoint:
/[NO]SILENT /[NO]SOURCE
Other qualifiers:
/AFTER:n /MODIFY /RETURN /TEMPORARY
See the individual subtopics for details.
/AFTER:n
Specifies that trace action not be taken until the nth time it is
hit.
Example:
DBG> SET TRACE/AFTER:5 %LINE 5
/BRANCH
Causes you to trace at every branch instruction. An address
expression is not allowed -- that is, SET TRACE/BRANCH is
sufficient. After specifying SET TRACE/BRANCH, every GO command
acts like a STEP/BRANCH.
Example: trace when X is no longer equal to zero, where the
condition is tested at each branch instruction:
DBG> SET TRACE/BRANCH WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/CALL
Causes you to trace at every call or return instruction. An
address expression is not allowed -- that is, SET TRACE/CALL is
sufficient. After specifying SET TRACE/CALL, every GO command
acts like a STEP/CALL.
Example: trace when X is no longer equal to zero, where the
condition is tested at each call or return instruction:
DBG> SET TRACE/CALL WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/EVENT
Causes you to trace on an event which is defined by and detected
by the run time system of a language or other run time facility.
Format:
SET TRACE/EVENT=keyword [/qualifiers]
[expression[, expression...]]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
keyword
The keyword determines the type of event to trace on. The events
and the event names (that is the allowed keywords) are defined by
the run time facility. To select a particular run time facility
use the command SET EVENT_FACILITY. To see which run time
facility has been selected and what the allowed keywords are, use
the command SHOW EVENT_FACILITY.
expression
The allowed parameters are determined by the particular event and
event facility. Generally, they may be either address
expressions or language expressions. Parameters may be optional,
in which case omitting them implies a "wildcard" as a parameter.
Some types of events may not allow parameters at all.
qualifiers
The only qualifiers that are allowed with the /EVENT qualifier
are /AFTER, /SILENT, /SOURCE, and /TEMPORARY.
WHEN and DO clauses
These behave the same as for other types of tracepoints.
Examples
The VMS Ada multitasking system defines a set of events dealing
with task state transitions. Accordingly the allowed parameters
are task names. When debugging an Ada program, you might use the
following commands:
SET TRACE/EVENT=RUN ALPHA, %TASK 3
Trigger a tracepoint when either task ALPHA, or the task whose ID
is 3 goes into the run state.
SET TRACE/EVENT=TERMINATED DO (SHOW TASK/ALL)
Trigger a tracepoint when any task terminates and execute the
debugger command to display all the tasks in the program.
/EXCEPTION
Sets an exception tracepoint. This tracepoint will be taken
anytime an exception is generated from your program, for example,
if your program takes an ACCVIO, or if your program signals an
exception. If you say "GO" from an exception trace, then VMS
will look for exception handlers in your program. In other
words, an exception trace is a stopping point after the exception
occurs but before your program's handlers are invoked.
An address expression is not allowed -- that is, SET
TRACE/EXCEPTION is sufficient.
Example:
DBG> SET TRACE/EXCEPTION DO (SHOW CALLS; GO)
/INSTRUCTION
Causes you to trace at every machine instruction. An address
expression is not allowed -- that is, SET TRACE/INSTRUCTION is
sufficient. After specifying SET TRACE/INSTRUCTION, then every
GO command acts like a STEP/INSTRUCTION.
Example: trace when X is no longer equal to zero, where the
condition is tested at each machine instruction:
DBG> SET TRACE/INST WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/INSTRUCTION=(opcode-list)
Causes you to trace at each instruction which is in the given
opcode list. For example:
DBG> SET TRACE/INSTR=(ADDL3)
The above causes a trace to occur each time an ADDL3 instruction
is about to be executed. Note that this is one of the forms of
SET TRACE that requires the debugger to trace every instruction
your program executes, and thus this form of SET TRACE will
significantly slow down your program's execution.
/LINE
Causes you to trace at every line. An address expression is not
allowed -- that is, SET TRACE/LINE is sufficient. After
specifying SET TRACE/LINE, then every GO command acts like a
STEP/LINE.
Example: trace when X is no longer equal to zero, where the
condition is tested at each line:
DBG> SET TRACE/LINE WHEN (X .NE. 0)
Note that the above command will cause the debugger to trace
every instruction of your program as it executes and thus
significantly slow down execution.
/MODIFY
"SET TRACE/MODIFY address-expression" specifies that you want to
be notified when the value at the given address changes. This is
synonymous with "SET WATCH address-expression".
Example:
DBG> SET TRACE/MODIFY X DO (SHOW CALLS)
/NOSILENT
Opposite of /SILENT. This specifies that you do want to see the
"trace at ..." message when the tracepoint is activated. Since
this is the default, the qualifier is a no-op and is just
included for completeness.
/NOSOURCE
Specifies that you do not want to see source display when the
tracepoint is activated. This qualifier is included for
completeness (that is, there is a STEP/NOSOURCE and a SET STEP
NOSOURCE so there should be a SET TRACE/NOSOURCE ...).
/RETURN
A "return" tracepoint is activated at the return of the specified
routine. For example, SET TRACE/RETURN SUBR will cause you to
trace at the return from the routine SUBR, rather than at the
start of the routine. This is done by setting an "invisible"
tracepoint at SUBR and then essentially doing a STEP/RETURN from
that invisible tracepoint, so that the trace actually occurs at
the return from the routine.
Example:
DBG> SET TRACE/RETURN %LINE 15; GO
trace on return from routine SUBR\%LINE 115 ...
The trace occurs before the execution of the RET instruction, so
that all the stack locals are still available. Return traces are
thus useful for observing the values of variables at the end of a
routine.
/SILENT
Specifies that you do not want to see either the "trace at..."
message or the source display when the tracepoint is activated.
Silent traces or silent traces are usually specified with a DO
clause (that is, you want to take some action at a given point,
but are not particularly interested in the "trace at ..."
message).
Example:
DBG> SET TRACE/SILENT SUBR DO (SHOW CALLS; GO)
/SOURCE
Specifies that you want to see source display when the tracepoint
is activated. This is normally the default (unless you have said
SET STEP NOSOURCE).
/TEMPORARY
Specifies that the tracepoint stay around for only one activation
-- that is, the tracepoint will automatically be canceled after
it is triggered.
Example:
DBG> SET TRACE/TEMPORARY %LINE 15 ! This is the same as:
DBG> SET TRACE %LINE 15 DO (CANCEL TRACE %LINE 15)
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 specified by the
address-expression.
Whenever an instruction causes the modification of a watched
location, DEBUG will break, report the old and the new values of
the watched location, and prompt for commands.
Format:
SET WATCH [/qualifiers]
address-expression [,address-expression...]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
Additional information available:
ParametersQualifiersAggregateExample
/AFTER:n/INTO/NOSILENT/NOSOURCE/NOSTATIC/OVER
/SILENT/SOURCE/STATIC/TEMPORARY
Parameters
address-expression
Specifies the location at which the watchpoint is to be
established. This is usually the name of a variable in your
program.
conditional-expression
A language expression which is evaluated when the watchpoint is
triggered. If the expression does not evaluate to TRUE the
watchpoint is not activated.
debug-cmd-list
One or more debugger commands (separated by semicolons)
specifying action you want to take when the watchpoint is
triggered.
Qualifiers
The qualifiers can be grouped as follows:
These control how much information to display at the watchpoint:
/[NO]SILENT /[NO]SOURCE
These tell the debugger whether it is a static watchpoint:
/STATIC /[NO]STATIC
For non-static watchpoints, these control whether the
debugger traces into or over called routines:
/INTO /OVER
Other qualifiers:
/AFTER:n /TEMPORARY
See the individual subtopics for details.
/AFTER:n
Specifies that the watchpoint is not to be triggered until the
Nth time that the address gets modified.
/INTO
For non-static watchpoints, which involve tracing every
instruction, the debugger needs to make a decision at a CALL or
JSB instruction whether it should trace over the called routine
or into the called routine. The default is to trace over the
routine -- that is, to let the routine run at full speed and
resume instruction tracing when it returns. This is faster, but
means that if the routine modifies the watched variable, you are
not informed until the return of the routine.
By specifying /INTO, you override that default and tell the
debugger to trace through all calls.
/NOSILENT
Opposite of /SILENT. Specifies that you do want to see all the
output. Since this is the default, the qualifier is actually a
no-op.
/NOSOURCE
Specifies that you do not want to see source display when the
watchpoint is triggered.
/NOSTATIC
Specifies that the watched location is not a static location.
For example, it may be on the stack. Normally, the debugger can
determine this itself (by checking whether the address is in P1
space). However, if you are allocating your own stack in P0
space, then you may need to explicitly inform the debugger when
you set a watchpoint on a non-static variable.
/OVER
For non-static watchpoints, which involve tracing every
instruction, the debugger needs to make a decision at a CALL or
JSB instruction whether it should trace over the called routine
or into the called routine. The default is to trace over the
routine -- that is, to let the routine run at full speed and
resume instruction tracing when it returns. This is faster, but
means that if the routine modifies the watched variable, you are
not informed until the return of the routine.
/SILENT
Suppresses "watch of ..." messages and other output.
/SOURCE
Specifies that you do want to see source display when the
watchpoint is triggered.
/STATIC
Specifies that the watched location is statically allocated.
Normally, the debugger can determine this itself (by checking
whether the address is in P1 space). However, if you are
allocating non-stack storage in P1 space, then you may need to
explicitly inform the debugger when you set a watchpoint in this
storage that this is a static location. Then the debugger can
use the faster write-protection method of watching the location
instead of tracing every instruction.
/TEMPORARY
Specifies that the watchpoint disappear after the first time it
is triggered.
Aggregate
Watchpoints can now be set on aggregates -- that is, entire
arrays or records). For example, if A is an array and R is a
record, then the following are allowed:
DBG> SET WATCH A
The above watchpoint will trigger if any element of the array A
changes.
DBG> SET WATCH R
The above watchpoint will trigger if any element of the record R
changes.
Example
DBG> SET WATCH X
DBG> GO
watchpoint of FOO\X at %LINE 15
15: X = X + 1
FOO\X
old value: 0
new value: 1
break at FOO\%LINE 16
16: Y = Y + 1
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
will 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 will be 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 will be 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)