DEBUG DEBUG — VMS 5.5
For more detailed help, choose one of the additional topics
listed below:
Additional information available:
SS$_DEBUGATTACHCALLCANCELCONNECTDECLARE
DEFINEDELETEDEPOSITDISABLEDISPLAYDOEDIT
ENABLEEVALUATEEXAMINEEXITEXITLOOPEXPANDEXTRACT
FORGOHELPIFMOVEQUITREPEAT
SAVESCROLLSEARCHSELECTSETSHOWSPAWN
STEPSYMBOLIZESYNCHRONIZETYPEWHILE
New FeaturesRelease NotesAddress ExpressionsBuilt in Symbols
DECwindows InterfaceDebugging ConfigurationsKeypad DefinitionsLanguage Support
Logical NamesMessagesMultiprocessPath NamesScreen ModeSystem Management
@file specCtrl CCtrl WCtrl YCtrl Z
New Features
Additional information available:
V5.5
The following new features and commands are provided in version
5.5 of the debugger. These are documented in detail elsewhere
in the help topics.
The debugger provides enhanced support for tasking programs.
Tasking programs (also called multithread programs) have
multiple threads of execution within a VMS process.
Ada programs have built-in tasking services, and debugger
support for VAX Ada tasking programs has been available since
VMS Version 4.2 (since VAX Ada Version 1.0).
Starting with Version 5.5, debugger tasking support has been
extended to include any program that uses DECthreads or POSIX
1003.4a services. These services are provided for languages
that do not have built-in tasking services.
Debugger tasking support enables you to perform functions such
as the following:
- Display task information
- Modify task characteristics to control task execution,
priority, state transitions, and so on
- Monitor task-specific events and state transitions
There are no new commands or qualifiers. However, the following
commands, which are task-related, have been enhanced to provide
the new support:
- SET TASK and SHOW TASK
- SET EVENT_FACILITY (you can now specify THREADS as a command
parameter, as well as ADA and SCAN)
- SHOW EVENT_FACILITY
- SET BREAK/EVENT and SET TRACE/EVENT (THREADS events are now
defined as well as ADA and SCAN events)
V5.4
The following is a list of the new features and commands in
version 5.4 of the debugger. These are documented in detail
elsewhere in the help topics.
o You can debug vectorized programs --- that is, programs that
use VAX vector instructions. See help on Vector_Features,
which also lists the new debugger commands and qualifiers for
this release.
o When using the EXAMINE command, you can specify composite
address expressions of a complex form, such as might be
appropriate for a vectorized program. (This feature is not
restricted to vectorized programs.) See help on
Composite_Examine.
For more information about this release, see help on
Release_Notes V5.4.
Additional information available:
Vector FeaturesComposite Examine
Vector Features
The Version 5.4 debugger has a new set of features that let you
debug vectorized programs (programs that use VAX vector
instructions). You can now do the following:
o Display information about the use and availability of the
vector processor on your system
o Control and monitor the execution of vector instructions with
breakpoints, watchpoints, and so on
o Specify built-in symbols for the vector registers (%V0 to
%V15) and the vector control registers (%VCR, %VLR, and %VMR)
o Examine and deposit into the vector registers and the vector
control registers
o Display vector instructions using a screen-mode instruction
display
o Examine and deposit vector instructions and their operands
o Do masked operations on vector registers and vector
instructions to display only certain register elements or
override the masking associated with a vector instruction
o When using the EXAMINE command, specify composite address
expressions of a complex form that might be appropriate for a
vectorized program
o Display the decoded results of vector floating-point
exceptions
o Control synchronization between the scalar and vector
processors
o Save and restore the current vector state when using the CALL
command to execute a routine that might affect the vector
state
The following is a list of the new and enhanced commands and
qualifiers for the debugger's command interface:
o CALL/[NO]SAVE_VECTOR_STATE
o CANCEL BREAK/VECTOR_INSTRUCTION
o CANCEL TRACE/VECTOR-INSTRUCTION
o EXAMINE/FMASK, /TMASK, and /OPERANDS
o SET BREAK/VECTOR_INSTRUCTION and /INSTRUCTION[=(opcode[,...])]
o SET STEP VECTOR_INSTRUCTION and INSTRUCTION[=(opcode[,...])]
o SET TRACE/VECTOR_INSTRUCTION and /INSTRUCTION[=(opcode[,...])]
o SET VECTOR_MODE [NO]SYNCHRONIZED
o SHOW PROCESS
o SHOW VECTOR_MODE
o STEP/VECTOR_INSTRUCTION and /INSTRUCTION[=(opcode[,...])]
o SYNCHRONIZE VECTOR_MODE
Composite Examine
When using the EXAMINE command, you can specify various forms of
composite address expressions --- expressions that include byte
offsets from a given address. For example, if X is an integer
variable, the following EXAMINE command displays the value
currently stored at the memory location 6 bytes beyond the
address of X:
DBG> EXAMINE X + 6
MOD3\X+6: 274903
You can now specify composite address expressions of a complex
form, such as might be appropriate for a vectorized program.
(This feature is not restricted to vectorized programs.) For
example:
DBG> EXAMINE ARRX(1) + .%V9(0:VLR-1)
DBG> EXAMINE ARRZ(1) + .%V1(0:3) + .%V3(0:2)
V5.2
The following is a list of the new features and commands in
version 5.2 of the debugger. These are documented in detail
elsewhere in the help topics.
o The debugger is now available in a DECwindows
(direct-manipulation) interface for workstations. You can
use the debugger's command interface from the DECwindows
interface by opening a command window (box). For information
about the DECwindows interface, see the V5.2 VMS Debugger
Manual.
o You can now use the debugger in two configurations, default
or multiprocess, depending on the definition of the
DBG$PROCESS logical name. Use the default configuration to
debug programs that run in one process (see help on
Default_Configuration). Use the multiprocess configuration
to debug programs that run normally in more than one process
(see help on Multiprocess_Configuration).
The Compatibility topic explains the use of commands and
other features in the default and multiprocess
configurations.
o You can now selectively display and cancel user-defined and
predefined breakpoints and tracepoints (see help on
Breakpoints).
o The DISPLAY command now lets you create a new display, as
well as modify an existing display (see help on DISPLAY).
o The SET SCOPE command has a new /CURRENT qualifier (see help
on SET SCOPE).
For more information, see help on:
Release_Notes V5.2
Multiprocess
Debugging_Configurations
Additional information available:
BreakpointsCompatibilityDefault ConfigurationMultiprocess Configuration
Breakpoints
The SHOW BREAK and SHOW TRACE commands now have /PREDEFINED and
/USER qualifiers. By default, SHOW BREAK and SHOW TRACE display
both user-defined and predefined breakpoints and tracepoints.
/USER displays only the user-defined breakpoints or tracepoints.
/PREDEFINED displays only the predefined breakpoints or
tracepoints.
The CANCEL BREAK, CANCEL TRACE, and CANCEL ALL commands now have
/PREDEFINED and /USER qualifiers. By default, these commands
cancel only any user-defined breakpoints and tracepoints.
/PREDEFINED cancels only predefined breakpoints and tracepoints.
The combination of /USER/PREDEFINED cancels both user-defined
and predefined breakpoints and tracepoints.
For more information, see help on the commands.
Compatibility
All commands, qualifiers, and built-in symbols that are provided
for multiprocess debugging are also supported in the default
debugging configuration and have analogous behaviors (where
applicable). For example:
o The EXIT command without a parameter specified ends a
debugging session in both configurations.
o A DO command without the /PROCESS qualifier executes the
specified commands in all processes.
o In the default configuration, the visible process is the
process that runs the entire prgram. It is identified as
process 1 in a SHOW PROCESS display.
o Built-in symbols such as %PROCESS_NUMBER and %VISIBLE_PROCESS
are interpreted correctly in the default configuration.
This compatibility is especially useful in that command
procedures for multiprocess debugging can also be used for
debugging programs that run in only one process.
Default Configuration
The default debugging configuration, like the V5.0 or earlier
debugger, is used to debug programs that run in only one
process. The default configuration is enabled when the
DBG$PROCESS logical name is either undefined or defined as
DEFAULT. Differences between the default configuration and the
V5.0 or earlier debugger are described in the subtopics.
Additional information available:
Ctrl C and Ctrl YTwo Process Debugger
Ctrl C and Ctrl Y
To interrupt program execution or the execution of a debugger
command from within a debugging session, you must now use Ctrl/C
instead of Ctrl/Y. Using Ctrl/C aborts these operations without
exiting the debugger (the debugger prompt is displayed after a
Ctrl/C).
If your program already has a Ctrl/C AST routine enabled, use
the SET ABORT_KEY command to reassign the abort function to
another control key sequence. The SHOW ABORT_KEY identifies the
control key currently assigned the abort function.
As with previous versions of the debugger, you can press Ctrl/Y
to interrupt a program running without debugger control. This
returns you to the DCL level. The DEBUG command then invokes
the debugger. Do not use Ctrl/Y for other purposes when using
the debugger.
For more information, see help on CTRL_C, CTRL_Y, and SET
ABORT_KEY.
Two Process Debugger
In VMS V5.0 or earlier versions, the debugger and the program
being debugged ran in the same process. Starting with this
version, the debugger consists of two parts (main and kernel
debuggers). In the default debugging configuration, the program
being debugged runs in one process along with the kernel
debugger. The main debugger runs in a subprocess.
The new default configuration provides the following advantages
over previous versions of the debugger. The main debugger,
which contains most of the debugger code, and the program run
entirely in separate processes, with very little interference.
Another advantage is the ability to abort commands or program
execution without leaving a debugging session (see help on
CTRL_C).
For more information, see help on Debugging_Configurations.
Multiprocess Configuration
The multiprocess debugging configuration, which is new with this
version of the debugger, lets you debug programs whose images
run in several processes. The multiprocess configuration is
enabled when the DBG$PROCESS logical name is defined as
MULTIPROCESS.
The multiprocess configuration lets you do the following:
o Display detailed information about processes and the images
running in those processes (SHOW PROCESS).
o Set the debugging context to a particular process (which then
becomes the visible process). This lets you set breakpoints,
examine variables, display the call stack, and so on in the
context of that process (SET PROCESS/[VISIBLE]).
o Execute commands in the context of selected processes, which
may be other than the visible process (DO).
o Keep selected processes from executing when you start the
execution of the other processes (SET PROCESS/[NO]HOLD).
o Control whether execution is interrupted in other processes
when it is suspended in some process (SET MODE NOINTERRUPT).
o Terminate selected processes (EXIT, QUIT).
o Bring a spawned process waiting to connect to the debugger
under debugger control. Interrupt an image that is running
without debugger control in some process and bring that
process under debugger control (CONNECT).
o Set and cancel breakpoints and tracepoints to trigger
automatically when processes come under debugger control (SET
(BREAK,TRACE) /ACTIVATING, CANCEL (BREAK,TRACE) /ACTIVATING.)
o Set and cancel breakpoints and tracepoints to trigger
automatically when processes perform an image exit (SET
(BREAK,TRACE) /TERMINATING, CANCEL (BREAK,TRACE)
/TERMINATING).
o Enable and disable convenience features to help you identify
the process that is the current debugging context (the
visible process) and its associated input/output:
* Dynamic process setting (SET PROCESS/DYNAMIC). This
feature is enabled by default.
* Dynamic prompt setting (SET PROMPT/SUFFIX). This feature
is enabled by default.
o Create process-specific screen-mode displays
(DISPLAY/PROCESS/SUFFIX). Several key definitions are now
associated with process-specific displays. For information
about new and changed key definitions, see help on
Release_Notes V5.2 Keypad.
o Set watchpoints in global sections --- that is, in regions of
memory shared among all processes of a multiprocess program.
Such watchpoints are triggered whenever any process changes
the value at the watched location.
The following are the new and changes commands and qualifiers
specific to multiprocess debugging:
CONNECT
DEFINE/PROCESS_GROUP
DISPLAY
/[NO]PROCESS=
/SUFFIX=
DO
EXIT
QUIT
(SET,CANCEL) BREAK
/ACTIVATING
/TERMINATING
(SET,CANCEL) TRACE
/ACTIVATING
/TERMINATING
SET MODE [NO]INTERRUPT
(SET,SHOW) PROCESS
SET PROMPT
/[NO]SUFFIX=keyword
V5.0
The following is a list of the new features and commands in
version 5.0 of the debugger. These are documented in detail
elsewhere in the help topics.
o Dynamically reformatting register display
o EXAMINE/OPERANDS (and SET MODE [NO]OPERANDS)
o MACRO support enhancements
o New predefined windows for screen mode
o SET MODULE/CALLS
o SET PROMPT/[NO]POP
o SET MODE [NO]SEPARATE
o SPAWN/INPUT and /OUTPUT
For more information, see the subtopics.
Additional information available:
Dynamic Register DisplayEXAMINE OPERANDS QualifierMACRO Support
Screen Mode WindowsSET MODULE CALLS QualifierSPAWN Qualifiers
Dynamic Register Display
By default, register displays, such as the predefined display
REG, are now dynamic. This means that the window dimensions
adjust proportionally when you change the screen height or width
with a SET TERMINAL command.
Also, a register display now reformats the displayed
information, in the best way possible, to the window in which it
has been displayed. The default window for REG remains RH1.
However, if you were to display REG in window Q3, for example,
the information would reformat automatically to fit into the new
window.
For more information, see help on Screen_Mode Register_Display.
EXAMINE OPERANDS Qualifier
To aid in debugging MACRO code, the /OPERANDS qualifier has been
added to the EXAMINE command. If you use EXAMINE/OPERANDS, the
debugger displays the addresses and contents of each of the
instruction operands. For example:
DBG> EXAMINE/OPER .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
For more information, see help on the following commands:
o EXAMINE/OPERANDS
o SET MODE OPERANDS
o SET MODE NOOPERANDS
MACRO Support
The following enhancements have been made to MACRO support, to
match the support available with other languages.
o The debugger now displays MACRO source lines, whether you are
debugging in line mode or screen mode.
o When the language is set to MACRO, the default behavior of
the STEP command is now STEP/LINE (instead of STEP
/INSTRUCTION, the previous behavior).
o When the language is set to MACRO, the debugger interprets an
address expression used in a language expression as the
current value stored at that address (not the address denoted
by the address expression, the previous behavior). This
change affects how language expressions are evaluated by the
EVALUATE, DEPOSIT, IF, FOR, REPEAT, and WHILE commands, and
by WHEN clauses as used with the SET BREAK, SET TRACE, and
SET WATCH commands. For example, the DEPOSIT X = Y + 2
command evaluates the sum of 2 and the current value of Y and
deposits the resulting value into X.
For more information, see help on MACRO Expressions.
Screen Mode Windows
The predefined windows now include eighths of the screen height,
in addition to halves, thirds, quarters, and sixths, plus the
right and left halves. The letter E denotes an eighth. For
example, E2 denotes the top second eighth of the screen, and
RE67 denotes the right sixth and seventh eighths of the screen.
SET MODULE CALLS Qualifier
The SET MODULE/CALLS command sets all modules that currently
have routines on the call stack. These are the modules listed
when you enter a SHOW CALLS command. Use the /CALLS qualifier
to set modules that might not have been dynamically set by the
debugger.
SET_MODE_SEPARATE
The SET MODE [NO]SEPARATE command applies only to VAXstations.
Before V5.0, if you invoked the debugger on a VAXstation, a
separate window was created for debugger input and output.
Starting with V5.0 you have control over this behavior. The SET
MODE SEPARATE command creates a separate 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. The SET
MODE NOSEPARATE command disables this behavior, so that debugger
input and output are displayed in the window where you invoked
the debugger.
For more information, see help on the SET MODE [NO]SEPARATE and
SET PROMPT/[NO]POP commands.
SET_PROMPT
The SET PROMPT command has a new qualifier /[NO]POP, which
applies only to VAXstations.
Before V5.0, if you were running the debugger in an emulated
terminal window on a VAXstation, the window popped over other
windows and attached to the keyboard whenever the debugger
prompted for input.
Starting with V5.0 you have control over this behavior. The SET
PROMPT/POP command enables this behavior. The SET PROMPT/NOPOP
command (which is the default) disables this behavior, so that
the debugger window does not automatically pop over other
windows and does not attach to the keyboard when the debugger
prompts for input.
If you use the SET PROMPT command without specifying a new
prompt string, the current prompt string is unchanged. If you
enter the command without the /[NO]POP qualifier, the prompt
behavior is set to /NOPOP, which is the default.
For more information, see help on the SET PROMPT/POP and SET
MODE [NO]SEPARATE commands.
SPAWN Qualifiers
Two new qualifiers have been added to the SPAWN command:
/INPUT Specifies an input file containing one or more DCL
commands to be executed by the spawned subprocess.
/OUTPUT Writes the output from the SPAWN operation to a
specified file.
V4.6
The following is a list of the new features and commands in
version 4.6 of the debugger. These are documented in detail
elsewhere in the help topics.
o Ada predefined breakpoints
o Call from exception break
o Nonstatic watchpoints
o Step from exception break
For more information, see the subtopics.
Additional information available:
Ada Predefined BreakpointsCall Exception BreakNonstatic Watchpoints
Step Exception Break
Ada Predefined Breakpoints
If any portion of your program is written in the Ada programming
language, then two breakpoints are automatically set on debugger
startup. These breakpoints are on Ada Events
Dependents_Exception and Exceptions_Terminated. Whenever you
enter the SHOW BREAK command, these breakpoints are displayed.
Call Exception Break
Prior to version 4.6, the debugger did not let you call from an
exception break. The CALL command is now allowed in this
situation. For example:
Earlier versions of DEBUG
-------------------------
DBG> SET BREAK/EXC
DBG> GO
%SYSTEM-F-ACCVIO, access violation...
break on exception preceding BLIHANDLER\SUBR\%LINE 38
38: a = ..a;
DBG> CALL PRIME(7)
%DEBUG-W-STEFROEXC, call from exception break is not allowed
Version 4.6 of DEBUG
--------------------
DBG> SET BREAK/EXC
DBG> GO
%SYSTEM-F-ACCVIO, access violation...
break on exception preceding BLIHANDLER\SUBR\%LINE 38
38: a = ..a;
DBG> CALL PRIME(7)
value returned is 00000001
There are some restrictions associated with issuing a CALL from
an exception breakpoint: Breakpoints, tracepoints, and
watchpoints are not triggered within the called routine.
(Normally, you could set a breakpoint within a routine, call it
with the CALL command, and break within the routine). But since
most people use CALL to call their own dumping or debugging
routines, they do not want to set breakpoints in the dumping
routine, and this restriction does not matter.
Nonstatic Watchpoints
Starting with version 4.6, it is possible to set watchpoints on
variables which are on the stack or allocated to registers. To
implement these watchpoints the debugger must trace every
instruction. (Watchpoints of static variables are implemented
by write-protecting the page and catching the access violation).
Therefore, watches of stack or register variables are slower
than watches of static variables.
When you set a watchpoint, the debugger determines whether the
watched location is a stack location or register, and if so,
issues an informational that you are setting a stack or register
watchpoint. The information is also displayed by the SHOW WATCH
command:
DBG> SET WATCH I
%DEBUG-I-WPTTRACE, non-static watchpoint, tracing every instruction
DBG> SHOW WATCH
watchpoint of EIGHTQUEENS\TRYCOL\I [tracing every instruction]
The watchpoint then operates like any other watchpoint. For
example:
DBG> GO
watch of EIGHTQUEENS\TRYCOL\I at EIGHTQUEENS\TRYCOL\%LINE 46
46: i := i + 1 ;
old value: 0
new value: 1
Since you are watching a variable local to a routine, the
watchpoint is automatically canceled when you return from the
routine:
DBG> STEP/RETURN
stepped on return from routine EIGHTQUEENS\TRYCOL
59: end ; (* trycol *)
DBG> STEP
stepped to EIGHTQUEENS\%LINE 69
69: writeln ;
%DEBUG-I-WATCHVAR, watched variable TRYCOL\I has gone out of scope
%DEBUG-I-WATCHCAN, watchpoint now canceled
For a recursive routine, it is possible to have separate
watchpoints for the same variable at different levels of
recursion. For example, in the above example, if TRYCOL was
recursive, you could have watchpoints of TRYCOL 0\I, TRYCOL 1\I,
and so on.
For more information see help on SET WATCH /[NO]STATIC, /INTO,
and /OVER.
Step Exception Break
Prior to version 4.6, the debugger would not let you step from
an exception break. Now, the STEP command is allowed in this
situation, and the effect is that you step to the start of
whatever exception handler gets control. If you have not
declared any exception handlers, the exception is just
resignalled, and you end up back at the debugger prompt (that
is, the STEP has no effect). For example:
Earlier versions of DEBUG
-------------------------
DBG> SET BREAK/EXC
DBG> GO
%SYSTEM-F-ACCVIO, access violation...
break on exception preceding BLIHANDLER\SUBR\%LINE 38
38: a = ..a;
DBG> STEP
%DEBUG-W-STEFROEXC, step from exception break is not allowed
Version 4.6 of DEBUG
--------------------
DBG> SET BREAK/EXC
DBG> GO
%SYSTEM-F-ACCVIO, access violation...
break on exception preceding BLIHANDLER\SUBR\%LINE 38
38: a = ..a;
DBG> EX .FP ! Check for a handler
7FF00D68: 00000400
DBG> EX .. ! See what the handler is
BLIHANDLER\HANDLER1: entry mask ^M<R2,R3>
DBG> STEP ! STEP to the handler
stepped to routine BLIHANDLER\HANDLER1
V4.4
The following is a list of the new features and commands in
version 4.4 of the debugger. These are documented in detail
elsewhere in the help topics.
o DIBOL language support. See help on Language DIBOL.
o DISPLAY/[NO]POP and DISPLAY/[NO]PUSH.
o EXAMINE/TYPE.
o New screen windows. See help on Screen_Mode Windows.
o Scan language support. See help on Language SCAN.
o Scope default of 0,1,2,..n. See help on SET SCOPE Default.
o SELECT/INPUT, /ERROR and /PROGRAM.
o SET and SHOW ATSIGN.
o SET and SHOW EDITOR.
o Shareable Image support. See help on Shareable_Image.
o SHOW STACK
o SS$_DEBUG signal parameters. See help on SS$_DEBUG.
o STEP/[NO]JSB and /[NO]SHARE.
There are also various new screen features, as discussed in the
following subtopics.
Additional information available:
Display AttributesExtracting DisplaysKey DefinitionsMoving Displays
PROMPT DisplayResizing DisplaysVertically Divided Windows
Shareable ImagesWindow Definitions
Display Attributes
In addition to the attributes INSTRUCTION, OUTPUT, SCROLL, and
SOURCE, the debugger now provides the following attributes,
which are also selected with the SELECT command:
Attribute Usage or Effect
----------------------------------------------------------
ERROR Displays debugger diagnostic messages.
INPUT Echoes your debugger input.
PROGRAM Displays program output. Currently, only the
new predefined PROMPT display can have the
PROGRAM attribute.
PROMPT Where the debugger prompts for input. Currently,
only the new predefined PROMPT display can have
the PROMPT attribute.
For example, the following command causes your input, debugger
output, and debugger diagnostic messages to be logged in the OUT
display in the proper sequence:
DBG> SELECT/INPUT/ERROR OUT
For information on assigning display attributes, see help on
Screen_Mode Display_Attributes.
Extracting Displays
You can now save screen displays into a file, or create a file
with all the debugger commands necessary to re-create the
current screen state at a later time. See help on the EXTRACT
command.
Key Definitions
The default definitions of the KP7 and MINUS keys have been
changed to accommodate changes in predefined display and window
definitions. The new definitions are as follows:
Key Definition
-----------------------------------------------
KP7 DISPLAY SRC AT LH1, INST AT RH1,
OUT AT S45, PROMPT AT S6
GOLD-KP7 DISPLAY INST AT LH1, REG AT RH1,
OUT AT S45, PROMPT AT S6
BLUE-KP7 Not defined
MINUS DISPLAY %NEXTDISP AT S12345
GOLD-MINUS Not defined
BLUE-MINUS (Default.) DISPLAY SRC AT H1,
OUT AT S45, PROMPT AT S6
For more information, see help on Window_Definitions.
Moving Displays
You can use the MOVE command to a display across the screen
vertically or horizontally or both.
PROMPT Display
There is a new predefined display PROMPT where the debugger
prompts for input, forces program output, and (by default)
prints debugger diagnostic messages. By default, PROMPT takes
up the bottom sixth of the screen (the predefined window S6).
On VT200 or VT100 series terminals, S6 includes lines 21 through
24.
The PROMPT display is of the new display kind PROGRAM. The
PROMPT display is the only display of that kind (no other
PROGRAM displays can be created). PROMPT has several
restrictions compared with other displays. To avoid possible
confusion when manipulating that display:
o PROMPT can never be hidden by another display. It is always
on top of the display pasteboard.
o PROMPT can be moved anywhere on the screen, expanded to fill
the full screen height, and shrunk down to two lines. But
PROMPT must always occupy the full width of the screen and,
therefore, cannot be moved, expanded, or shrunk horizontally.
See help on Screen_Mode Display_Attributes for information on
assigning display attributes to various displays, including the
PROMPT display.
Resizing Displays
To expand and contract displays, use the EXPAND command.
Vertically Divided Windows
Previously, display windows had to occupy the full width of the
screen (columns 1--80). Now, windows can be defined to occupy
any rectangular region of the screen. Windows occupying the
left or right half of the screen (columns 1--40 and 42--80,
respectively) are predefined. With these predefined displays,
column 41 is reserved as a border.
To see the effect, invoke the debugger, use the SET MODE SCREEN
command, and then press KP7. That key definition has been
changed to show the SRC display in the top left half of the
screen (LH1), the INST display in the top right half (RH1), the
OUT display under these two, and the new PROMPT display under
OUT.
Shareable Images
With version 4.4 of the debugger, you can debug shareable images
in the same way as you debug your main image --- that is, full
symbol table information is now available for shareable images.
To build a shareable image with symbol table, compile your
modules with the /DEBUG qualifier and then link the image with
the /SHARE and /DEBUG qualifiers. For example:
$ LINK/SHARE/DEBUG FOO
Then, once you have run your main program with the debugger, you
can load the symbol table information for the shareable image
FOO using the command:
DBG> SET IMAGE FOO
For more information, see help on the SET IMAGE, CANCEL IMAGE,
and SHOW IMAGE commands.
Window Definitions
Previously, the bottom sixth of the screen (lines 21--24 on a
VT200 or VT100 series terminal) could not be used for defining
display windows. That area was reserved for the debugger
prompt, debugger diagnostic messages, and program output. Also,
windows had to occupy the full width of the screen.
Now, windows can be defined to occupy any rectangular region of
the screen. The DISPLAY and SET WINDOW commands now accept
horizontal (column) as well as vertical (line) coordinates. The
following is the general form of a window specification for the
SET WINDOW command:
SET WINDOW window-name AT (start-line,line-count
[,start-column,column-count])
For more information, see help on the DISPLAY and SET WINDOW
commands.
Old and new default windows have been defined to cover the
greater usable screen height and to account for vertically
defined windows. For example, on VT200 or VT100 series
terminals, FS (full screen) now covers lines 1--24, H1 lines
1--12, H2 lines 13--24, and so on. A new symbol prefix, S,
denotes a multiple of one sixth of the screen. For example, S56
is the bottom two sixths of the screen. And for each of the
full-width predefined windows (for example, FS, H2, T12, Q3,
S45, and so on) there is also a left-half and a right-half
predefined window. These window names have the prefix L and R,
respectively. Examples of predefined windows follow:
Window Location
name (start-line,line-count,start-column,column-count)
----------------------------------------------------------
FS (1, 23, 1, 80)
LFS (1, 23, 1, 40)
RH1 (1, 11, 42, 39)
LH2 (13, 11, 1, 40)
LT12 (1 , 15, 1, 40)
Q234 (7, 17, 1, 80)
RS56 (17, 7, 42, 39)
V4.2
The following is a list of the new features and commands in
version 4.2 of the debugger. These are documented in detail
elsewhere in the help topics.
o Ada language support. See help on Language Ada.
o Aggregate watchpoints. See help on SET WATCH aggregate.
o Dynamic module setting. See help on SET MODE DYNAMIC.
o Enable and Disable AST. See help on ENABLE and DISABLE.
o Exception built-in symbols. See help on Built_in_Symbols %EXC.
o Exit handlers. See help on SHOW EXIT_HANDLERS.
o Instruction display. See help on Screen Instruction-display.
o Large terminal support. See help on SET TERMINAL.
o Noline mode. See help on SET MODE NOLINE.
o Parameters for SHOW MODULE. See help on SHOW MODULE Parameters.
o Scroll mode. See help on SET MODE SCROLL.
o Setting the debugger prompt. See help on SET PROMPT.
o %SOURCE_SCOPE. See help on Screen Source_Display.
Release Notes
Additional information available:
V5.5
The additional topics describe any problems or restrictions with
this release of the debugger and provide any other relevant
information.
New features are listed separately under HELP New_Features V5.5.
Additional information available:
Corrected Problems or RestrictionsNew Problems or RestrictionsPrevious Problems or Restrictions
Single Process Debugging Configuration
Corrected Problems or Restrictions
The following problems or restrictions in previous versions of
the debugger have been corrected:
o In VMS Version 5.3, the RUN/DETACHED command entered after
the LINK/DEBUG command did not work correctly. If you linked
a program using the command LINK/DEBUG and then executed the
program in a detached process (using the command
RUN/DETACHED), the debugger went into an infinite loop. This
problem has been corrected.
o In VMS Version 5.4:
* The following source-line correlation problem affected the
debugging of MACRO programs that invoke the $FAO or $FAO_S
system service macro or an application-defined macro that
contained any of the following directives:
.IRP .IRP .REPT .REPEAT
This problem caused the debug symbol table information
about source lines and line numbers to be unreliable. The
screen-mode source display (SRC) was not updated correctly
when the debugger suspended execution. This problem has
been corrected.
* The creation and sorting of the Static Address Table (SAT)
was slow. The creation and sorting has been improved, and
startup time for very large programs is now faster.
* In large Ada programs, the commands SET MODULE/ALL or SET
MODULE followed by SET BREAK caused ROPERAND faults. This
problem has been corrected; the SET MODULE and SET BREAK
commands now work correctly with large Ada programs.
* Pressing Ctrl/C did not abort the display of large amounts
of watchpoint information. This problem has been
corrected; pressing Ctrl/C now aborts the display of large
amounts of watchpoint information.
* Support for Ada descriptors was inadequate. This problem
has been corrected; Ada extended descriptors are now fully
supported.
* In C expressions, the NOT <PARENDCHAR>(^) operator did not
have the correct precedence and, as a result, the EVALUATE
command did not evaluate expressions correctly. This
problem has been corrected; the EVALUATE command now
evaluates C expressions containing the NOT operator
correctly.
* At debugger startup with very large programs,
%DEBUG-I-INVDMTPTR and %DEBUG-I-MISMODEND errors sometimes
occurred, and the program could not be debugged. This was
a problem in both the linker and the debugger. The
problem has been corrected; these startup errors no longer
occur.
New Problems or Restrictions
The following subtopics describe problems or restrictions with
this version of the debugger.
Additional information available:
DEPOSIT TYPE Command with C Programs
DEPOSIT TYPE Command with C Programs
When debugging a C program, you cannot use the DEPOSIT/TYPE
command if the type specified is a mixed or lower case name.
For example, suppose the program has a function:
xyzzy_type foo ()
{
xyzzy_type z;
z = get_z ();
return (z);
}
If you try to enter the following command, the debugger issues a
message that it cannot find the type "xyzzy_type":
DBG> DEPOSIT/TYPE=(xyzzy_type) z = "whatever"
Previous Problems or Restrictions
The additional topics describes problems or restrictions that
originated in previous versions of the debugger and have not yet
been corrected.
The version in which the problem or restriction was first
noticed is identified.
Additional information available:
$WAKE Call Followed by $HIBER Call V53Examining LABEL[n] for Code Location V54
SET IMAGE Command Limitation V53Using Concealed Rooted-Directory Logical Names for Source V54
Using Debugger Commands in DCL Command Procedures v52Using the Abort Key or Stop Button After a SPAWN Command V52
Using the Debugger on a VAXstation Running VWS V50Vector Support Restrictions and Problems V54
Watchpoints in Installed Writable Shareable Images 53
$WAKE Call Followed by $HIBER Call V53
If a program running under the debugger issues a $WAKE call
followed by a $HIBER call, the debugger hibernates.
Examining LABEL[n] for Code Location V54
A command in the form EXAMINE LABEL[n] or EXAMINE LABEL(n),
where LABEL is a label for a code location and n is an integer,
causes an access violation error. In this case, the debugger
does not handle the error. Note that this problem does not
occur when the label marks the start of data storage, as in a
MACRO program.
SET IMAGE Command Limitation V53
For some large programs with many program sections (usually
caused by many FORTRAN routines with many COMMON blocks) the
debugger may receive an internal error during the processing of
a SET IMAGE command. In such cases, the image cannot be
debugged.
Using Concealed Rooted-Directory Logical Names for Source V54
When compiling a program with the /DEBUG qualifier, if you use a
rooted-directory logical name to specify the location of the
source file, make sure that it is a concealed rooted-directory
logical name. To create a concealed rooted-directory logical
name, use the syntax illustrated in the following command line:
DEFINE/TRANSLATION_ATTRIB=CONCEALED ROOTDIR DISK3$:[USER.DIR1.]
If the rooted-directory logical name is not concealed and you
move the source file to another directory after compilation, you
cannot then use the debugger SET SOURCE command to specify the
new location of the source file.
Using Debugger Commands in DCL Command Procedures v52
Before Version 5.2, you could use a DCL command procedure to
invoke the debugger and issue debugger commands contained in
that command procedure. For example:
$ ! Procedure to run PROG2 under debugger
$ ! control and issue debugger commands
$ !
$ RUN PROG2
SET BREAK %LINE 17
GO
EXIT
$ SHOW SYSTEM
$ LOGOUT
Beginning with Version 5.2, you can no longer put debugger
commands directly into a command procedure. Instead, you must
create a temporary file containing the debugger commands and
define the DBG$INPUT logical name as that file. For example:
$ CREATE DEBUG_COMMANDS.TMP
SET BREAK %LINE 17
GO
EXIT
$ DEFINE/USER DBG$INPUT DEBUG_COMMANDS.TMP
$ RUN PROG2
$ DELETE DEBUG_COMMANDS.TMP;0
$ SHOW SYSTEM
$ LOGOUT
Another way to work around this problem is to set up a
single-process debugging configuration, by using the following
DCL command:
$ DEFINE DBG$PROCESS NONE
Using the Abort Key or Stop Button After a SPAWN Command V52
If you use the SPAWN command either from the DCL level or from
within a debugging session, the debugger abort key or Stop
button is disabled after you log out or return from the spawned
subprocess.
In the debugger command interface, the abort key is Ctrl/C by
default. In the DECwindows interface, the abort button is the
Stop button in the main window.
The only way to re-enable the abort key or Stop button is to log
out and log back in.
Using the Debugger on a VAXstation Running VWS V50
There is a problem with the handling of Ctrl/Y when the debugger
is running in its own window and SET MODE SEPARATE is in effect.
Ctrl/Y is ignored when the keyboard is attached to the debugger
window. To make Ctrl/Y take effect, attach the keyboard to the
window from which you invoked the debugger (by pointing at that
window with the mouse), then press Ctrl/Y.
Vector Support Restrictions and Problems V54
The following are problems and restrictions with the debugger's
support for vectorized programs:
o When the programming language is BLISS, COBOL, or RPG, to
deposit into %VMR you must specify a type qualifier. For
example:
DBG> DEPOSIT/QUADWORD %VMR = %HEX 0FFFFFFFF
o When the programming language is PL/I, COBOL, or DIBOL, the
EXAMINE %VMR command displays %VMR as an array of bits
instead of as a hexadecimal quadword. To get the default
behavior for other programming languages, use the
EXAMINE/HEX/QUADWORD %VMR command.
o When the vector mode is synchronized (if SET VECTOR_MODE
SYNCHRONIZED is in effect), the debugger suspends execution
twice at any breakpoints that were set on vector
instructions. To resume execution from such breakpoints, you
must enter the GO or STEP command twice.
Watchpoints in Installed Writable Shareable Images 53
The technique for setting watchpoints in installed writable
shareable images is as follows:
o When using the command interface, enter the command SET
WATCH /NOSTATIC.
o When using the DECwindows interface, proceed as follows:
1. Choose Watch... from the Control menu.
2. Choose `Set nonstatic watchpoint' from the Set/Cancel
(upper) option menu. Note that, if you choose `Set
watchpoint', the debugger might display the following
message:
"Internal debugger error in DBGEVENT\DBG$FIND_EVENT_ID -
no matching event ID"
Single Process Debugging Configuration
Before VMS Version 5.2, the debugger and the program being
debugged ran in the same process. This debugging configuration
is referred to as the single-process configuration. Beginning
with VMS Version 5.2, the debugger consists of the following two
parts that run in separate processes:
o DEBUG.EXE, a relatively small kernel debugger image
o DEBUGSHR.EXE, a larger main image
When you invoke the debugger, if a separate process cannot be
created to run the main debugger image, the debugger issues one
or more messages and automatically uses the single-process
configuration (where the debugger shares a single process with
the user program). For example, if quotas are not sufficient to
create a subprocess for the main debugger, the messages are as
follows:
%DEBUG-E-CANTCREATEMAIN, could not create the VAX DEBUG subprocess
-SYSTEM-F-EXQUOTA, exceeded quota
%DEBUG-I-SHRPRC, VAX DEBUG will share user process
In the single-process configuration, you can use the debugger to
debug a program that normally runs in only one process.
However, you cannot use the following additional debugger
features available beginning with VMS Version 5.2:
o You cannot use the multiprocess debugging configuration.
o You cannot use the debugger's DECwindows interface.
o You do not have the benefit of reduced interference between
the debugger and the program being debugged.
In the single-process configuration, press Ctrl/Y to abort a
debugger command or program execution from within a debugging
session. This returns you to the DCL level. The DEBUG command
then invokes the debugger, which then displays its prompt. You
cannot use the SET ABORT_KEY command to reassign the abort
function to another control key.
The single-process configuration avoids the following
restrictions of the default and multiprocess configurations:
o Restriction on using debugger commands in DCL command
procedures
o Restriction on using the abort key (by default, Ctrl/C) after
a SPAWN command.
For more information about these restrictions, see the
additional topics.
If you wish to use the single-process debugging configuration
because it avoids these restrictions, you can do so by making
the following logical name assignment before invoking the
debugger:
$ DEFINE DBG$PROCESS NONE
NOTE: To avoid the restrictions of the default configuration
use the single-process configuration (enabled when the
definition of DBG$PROCESS is NONE) only when necessary.
The single-process configuration is unsupported and may
not be available in future releases of the debugger. If
you have any problems using the default or multiprocess
configurations (other than those mentioned in these
release notes), please submit a Software Problem Report
(SPR).
Additional information available:
Using Debugger Commands in DCL Command ProceduresUsing the Abort Key or Stop Button After a SPAWN Command
Using Debugger Commands in DCL Command Procedures
Before Version 5.2, you could use a DCL command procedure to
invoke the debugger and issue debugger commands contained in
that command procedure. For example:
$ ! Procedure to run PROG2 under debugger
$ ! control and issue debugger commands
$ !
$ RUN PROG2
SET BREAK %LINE 17
GO
EXIT
$ SHOW SYSTEM
$ LOGOUT
Beginning with Version 5.2, you cannot put debugger commands
directly into a command procedure. Instead, you must create a
temporary file containing the debugger commands and assign the
DBG$INPUT logical name to point to that file. For example:
$ CREATE DEBUG_COMMANDS.TMP
SET BREAK %LINE 17
GO
EXIT
$ DEFINE/USER DBG$INPUT DEBUG_COMMANDS.TMP
$ RUN PROG2
$ DELETE DEBUG_COMMANDS.TMP;0
$ SHOW SYSTEM
$ LOGOUT
Another way to work around this problem is to set up a
single-process debugging configuration, by using the following
DCL command:
$ DEFINE DBG$PROCESS NONE
Using the Abort Key or Stop Button After a SPAWN Command
If you use the SPAWN command either from the DCL level or from
within a debugging session, the debugger abort key or Stop
button is disabled after you log out or return from the spawned
subprocess.
By default, in the debugger command interface, the abort key is
Ctrl/C. In the DECwindows interface, the abort button is the
Stop button in the main window.
The only way to re-enable the abort key or Stop button is to log
out and in again.
V5.4
The additional topics describe any problems or restrictions with
this release of the debugger and provide any other relevant
information.
New features are listed separately under HELP New_Features V5.4.
There are no incompatibilities with previous versions of the
debugger.
These release notes do not include any information that might be
specific to the debugger's DECwindows interface. For more
information, see the VMS Version 5.4 Release Notes Manual.
Additional information available:
Corrected Problems or RestrictionsNew Problems or RestrictionsPrevious Problems or Restrictions
Single Process Debugging ConfigurationObsolete Commands
Corrected Problems or Restrictions
The following problems or restrictions in previous versions of
the debugger have been corrected.
In VMS Version 5.0:
o If you defined a symbol with the DEFINE/COMMAND command, you
could not then specify that symbol as the first or only
element of a command string in another DEFINE/COMMAND
command. This problem has been corrected; there are no
longer any restrictions on using a previously defined symbol
in another DEFINE/COMMAND command.
o If you used the STEP command to execute a line of code that
caused certain exceptions, the debugger executed the program
(stepped) into an application-declared exception handler, if
one was available, and suspended execution within the
handler. This problem has been corrected; the debugger now
allows uninterrupted execution of the exception handler.
o In a COBOL program, depositing a value into a variable of
type SIGNED LEADING SEPARATE modified adjacent memory
locations. This problem has been fixed; depositing no longer
affects adjacent locations.
In VMS Version 5.2:
o You could not invoke the debugger with a program that was
linked with more than 25 images, including any Run-Time
Library images. This problem has been corrected; there are
no longer any restrictions on the number of images that can
be linked with your program.
o To get good debugger startup performance with large images
(more than 5000 blocks), you had to adjust your working set
quota (WSQUOTA) to 3000 or more. This problem has been
corrected; you no longer have to adjust your working set
quota to achieve good startup performance with large images.
In VMS Version 5.3:
o With a GO command, if you specified an address expression
after the program terminated, any breakpoints, tracepoints,
or watchpoints that you set previously were ignored. This
problem has been corrected; any previously set breakpoints,
tracepoints, or watchpoints are no longer ignored.
o The low/high bound expressions in Pascal subrange expressions
were restricted to being constants. This problem has been
corrected; the subrange expressions no longer have such a
restriction.
o The Parameters subtopic in the online help caused some
confusion. To elimate any confusion, the Parameters subtopic
has been deleted from the HELP MESSAGES topic.
o There were restrictions on specifying a search list for
SYS$LIBRARY. This problem has been corrected; any such
restrictions have now been removed.
o The technique for setting watchpoints in installed writable
shareable images was not included in the debugger
documentation. The VMS Version 5.4 edition of the VMS
Debugger Manual outlines the technique for setting
watchpoints.
New Problems or Restrictions
The following subtopics describe problems or restrictions with
this version of the debugger.
Additional information available:
Vector Support Restrictions and ProblemsMACRO Source Correlation Problem
Vector Support Restrictions and Problems
The following are problems and restrictions with the debugger's
support for vectorized programs:
o When the programming language is BLISS, COBOL, or RPG, to
deposit into %VMR you must specify a type qualifier. For
example:
DBG> DEPOSIT/QUADWORD %VMR = %HEX 0FFFFFFFF
o When the programming language is PL/I, COBOL, or DIBOL, the
EXAMINE %VMR command displays %VMR as an array of bits
instead of as a hexadecimal quadword. To get the default
behavior for other programming languages, use the
EXAMINE/HEX/QUADWORD %VMR command.
o When the vector mode is synchronized (if SET VECTOR_MODE
SYNCHRONIZED is in effect), the debugger suspends execution
twice at any breakpoints that were set on vector
instructions. To resume execution from such breakpoints, you
must enter the GO or STEP command twice.
MACRO Source Correlation Problem
There is a source-line correlation problem with MACRO programs
that invoke either the $FAO or $FAO_S system service macro, or
an application-defined macro that contains any of the following
directives:
.IRP .IRP .REPT .REPEAT
In such cases, the symbol table information about source lines
and line numbers might be unreliable. The problem occurs as
soon as the macro is invoked and persists as long as execution
is within the module in which the macro is invoked.
When the problem occurs, the pointer in a screen-mode source
display is typically 1 or 2 lines off the line where execution
is actually suspended.
To determine the exact point where execution is suspended, use
the screen-mode instruction display INST. The arrow in display
INST correctly points to the instruction where execution is
suspended. Pressing KP7 puts displays SRC and INST side by side
so that you can quickly compare the MACRO source code and the
decoded instruction stream. Note that the line number
information in display INST might be unreliable (as in SRC).
The problem shows up also when the debugger issues a "stepped
to...", "break at...", or "trace at..." message, which might
indicate the wrong source line.
Specifying a line number in a command may also give incorrect
results. For example, do not specify SET BREAK %LINE 34. When
setting breakpoints or tracepoints, specify a routine name, a
label, or a memory address instead of a line number.
Previous Problems or Restrictions
The additional topics describes problems or restrictions that
originated in previous versions of the debugger and have not yet
been corrected.
The version in which the problem or restriction was first
noticed is identified.
Additional information available:
$WAKE Call Followed by $HIBER Call V53Debugging SMG Programs Using the Debugger’s Command Interface V50
RUN DETACHED Command Entered After LINK DEBUG Command V53SET IMAGE Command Limitation V53
Using Debugger Commands in DCL Command Procedures v52Using the Abort Key or Stop Button After a SPAWN Command V52
Using the Debugger on a VAXstation Running VWS V50
$WAKE Call Followed by $HIBER Call V53
If a program running under the debugger issues a $WAKE call
followed by a $HIBER call, the debugger hibernates.
Debugging SMG Programs Using the Debugger's Command Interface V50
The debugger uses the VMS Screen Management Facility (SMG) to
implement screen mode. If your program also calls SMG routines
and you debug it with the debugger running on the same terminal,
there is likely to be interference between your program and the
debugger.
To avoid this problem, debug the program using two terminals or
a VAXstation. This technique is described in the VMS Debugger
Manual.
RUN DETACHED Command Entered After LINK DEBUG Command V53
If you link a program with the LINK/DEBUG command and then
execute the program in a detached process (with the RUN/DETACHED
command), the debugger goes into an infinite loop. To
circumvent this problem, use the following syntax for the
RUN/DETACHED command:
$ RUN/DETACHED/OUTPUT=device:/INPUT=device:
SET IMAGE Command Limitation V53
For some large programs with many program sections (usually
caused by many FORTRAN routines with many COMMON blocks) the
debugger may receive an internal error during the processing of
a SET IMAGE command. In such cases, the image cannot be
debugged.
Using Debugger Commands in DCL Command Procedures v52
Before Version 5.2, you could use a DCL command procedure to
invoke the debugger and issue debugger commands contained in
that command procedure. For example:
$ ! Procedure to run PROG2 under debugger
$ ! control and issue debugger commands
$ !
$ RUN PROG2
SET BREAK %LINE 17
GO
EXIT
$ SHOW SYSTEM
$ LOGOUT
Beginning with Version 5.2, you can no longer put debugger
commands directly into a command procedure. Instead, you must
create a temporary file containing the debugger commands and
define the DBG$INPUT logical name as that file. For example:
$ CREATE DEBUG_COMMANDS.TMP
SET BREAK %LINE 17
GO
EXIT
$ DEFINE/USER DBG$INPUT DEBUG_COMMANDS.TMP
$ RUN PROG2
$ DELETE DEBUG_COMMANDS.TMP;0
$ SHOW SYSTEM
$ LOGOUT
Another way to work around this problem is to set up a
single-process debugging configuration, by using the following
DCL command:
$ DEFINE DBG$PROCESS NONE
Using the Abort Key or Stop Button After a SPAWN Command V52
If you use the SPAWN command either from the DCL level or from
within a debugging session, the debugger abort key or Stop
button is disabled after you log out or return from the spawned
subprocess.
In the debugger command interface, the abort key is Ctrl/C by
default. In the DECwindows interface, the abort button is the
Stop button in the main window.
The only way to re-enable the abort key or Stop button is to log
out and log back in.
Using the Debugger on a VAXstation Running VWS V50
There is a problem with the handling of Ctrl/Y when the debugger
is running in its own window and SET MODE SEPARATE is in effect.
Ctrl/Y is ignored when the keyboard is attached to the debugger
window. To make Ctrl/Y take effect, attach the keyboard to the
window from which you invoked the debugger (by pointing at that
window with the mouse), then press Ctrl/Y.
Single Process Debugging Configuration
Before VMS Version 5.2, the debugger and the program being
debugged ran in the same process. This debugging configuration
is referred to as the single-process configuration. Beginning
with VMS Version 5.2, the debugger consists of the following two
parts that run in separate processes:
o DEBUG.EXE, a relatively small kernel debugger image
o DEBUGSHR.EXE, a larger main image
When you invoke the debugger, if a separate process cannot be
created to run the main debugger image, the debugger issues one
or more messages and automatically uses the single-process
configuration (where the debugger shares a single process with
the user program). For example, if quotas are not sufficient to
create a subprocess for the main debugger, the messages are as
follows:
%DEBUG-E-CANTCREATEMAIN, could not create the VAX DEBUG subprocess
-SYSTEM-F-EXQUOTA, exceeded quota
%DEBUG-I-SHRPRC, VAX DEBUG will share user process
In the single-process configuration, you can use the debugger to
debug a program that normally runs in only one process.
However, you cannot use the following additional debugger
features available beginning with VMS Version 5.2:
o You cannot use the multiprocess debugging configuration.
o You cannot use the debugger's DECwindows interface.
o You do not have the benefit of reduced interference between
the debugger and the program being debugged.
In the single-process configuration, press Ctrl/Y to abort a
debugger command or program execution from within a debugging
session. This returns you to the DCL level. The DEBUG command
then invokes the debugger, which then displays its prompt. You
cannot use the SET ABORT_KEY command to reassign the abort
function to another control key.
The single-process configuration avoids the following
restrictions of the default and multiprocess configurations:
o Restriction on using debugger commands in DCL command
procedures
o Restriction on using the abort key (by default, Ctrl/C) after
a SPAWN command.
For more information about these restrictions, see the
additional topics.
If you wish to use the single-process debugging configuration
because it avoids these restrictions, you can do so by making
the following logical name assignment before invoking the
debugger:
$ DEFINE DBG$PROCESS NONE
NOTE: To avoid the restrictions of the default configuration
use the single-process configuration (enabled when the
definition of DBG$PROCESS is NONE) only when necessary.
The single-process configuration is unsupported and may
not be available in future releases of the debugger. If
you have any problems using the default or multiprocess
configurations (other than those mentioned in these
release notes), please submit a Software Problem Report
(SPR).
Additional information available:
Using Debugger Commands in DCL Command ProceduresUsing the Abort Key or Stop Button After a SPAWN Command
Using Debugger Commands in DCL Command Procedures
Before Version 5.2, you could use a DCL command procedure to
invoke the debugger and issue debugger commands contained in
that command procedure. For example:
$ ! Procedure to run PROG2 under debugger
$ ! control and issue debugger commands
$ !
$ RUN PROG2
SET BREAK %LINE 17
GO
EXIT
$ SHOW SYSTEM
$ LOGOUT
Beginning with Version 5.2, you cannot put debugger commands
directly into a command procedure. Instead, you must create a
temporary file containing the debugger commands and assign the
DBG$INPUT logical name to point to that file. For example:
$ CREATE DEBUG_COMMANDS.TMP
SET BREAK %LINE 17
GO
EXIT
$ DEFINE/USER DBG$INPUT DEBUG_COMMANDS.TMP
$ RUN PROG2
$ DELETE DEBUG_COMMANDS.TMP;0
$ SHOW SYSTEM
$ LOGOUT
Another way to work around this problem is to set up a
single-process debugging configuration, by using the following
DCL command:
$ DEFINE DBG$PROCESS NONE
Using the Abort Key or Stop Button After a SPAWN Command
If you use the SPAWN command either from the DCL level or from
within a debugging session, the debugger abort key or Stop
button is disabled after you log out or return from the spawned
subprocess.
By default, in the debugger command interface, the abort key is
Ctrl/C. In the DECwindows interface, the abort button is the
Stop button in the main window.
The only way to re-enable the abort key or Stop button is to log
out and in again.
Obsolete Commands
The following debugger commands and qualifiers are obsolete and
are no longer documented:
ALLOCATE
The debugger now allocates and deallocates memory
automatically. This command now has no effect.
CANCEL EXCEPTION BREAK
Same as the newer CANCEL BREAK/EXCEPTION command, which
better conforms to the general command format for canceling
breakpoints.
SET DISPLAY
The DISPLAY command now lets you create a new display, as
well as modifying an existing display.
SET EXCEPTION BREAK
Same as the newer SET BREAK/EXCEPTION command, which better
conforms to the general command format for setting
breakpoints.
SET MODULE/ALLOCATE
The debugger now allocates and deallocates memory
automatically. /ALLOCATE now has no effect.
UNDEFINE
Same as the newer DELETE command, which conforms to the
analogous DELETE command in DCL.
UNDEFINE/KEY
Same as the newer DELETE/KEY command, which conforms to the
DELETE/KEY command in DCL.
V5.2
For a summary description of all new features for this release
of the debugger, see help on New_Features V5.2. The release
notes describe the following topics:
o Changes from single-process to two-process (default) and
multiprocess debugging configurations (see help on
Two_Process_Debugger)
o Using the single-process debugging configuration (used in
previous VMS versions) in certain cases (see help on
Single_Process_Debugger)
o Changes in the use of Ctrl/Y and Ctrl/C (see help on
Ctrl_C_and_Ctrl_Y)
o Changes to the debugger keypad key definitions (see help on
Keypad)
o Restrictions on using the abort key (Ctrl/C, by default)
after a SPAWN command (see help on Abort_After_Spawn)
o Restrictions on using debugger commands in DCL command
procedures (see help on DCL_Command_Procedures)
o System management considerations for using the debugger (see
help on System_Management)
These release notes do not include any information that may be
specific to the debugger's DECwindows interface. For more
information, see the VMS Version 5.2 Release Notes.
Additional information available:
Two Process DebuggerSingle Process DebuggerCtrl C and Ctrl YKeypad
Abort After SpawnDCL Command ProceduresSystem Management
Two Process Debugger
Before VMS Version 5.2, you could use the debugger only with
one-process programs. The debugger and the program being
debugged ran in the same process. This debugging configuration
is referred to as the single-process configuration in these
release notes.
Starting with VMS Version 5.2, you can use the debugger with
multiprocess programs (programs that run in more than one
process). To accommodate this and other new capabilities, such
as the DECwindows interface, the debugger now consists of two
parts that run in separate processes: a relatively small kernel
debugger image (DEBUG.EXE) and a larger main debugger image
(DEBUGSHR.EXE) which contains most of the debugger code.
This separation reduces potential interference between the
debugger and the program being debugged. The separation also
makes it possible to have two debugging configurations-default
and multiprocess:
o When you use the debugger with a one-process program, the
kernel debugger runs in one process along with the program
and the main debugger runs in a subprocess. This two-process
debugging configuration is the default configuration. It
results when the DBG$PROCESS logical name is either undefined
or is defined as DEFAULT.
o When you use the debugger with a multiprocess program, a
kernel debugger runs in each process of the program, and the
main debugger runs in a subprocess. The multiprocess
configuration, which results when the DBG$PROCESS logical
name is defined as MULTIPROCESS, enables one main debugger to
communicate with several kernel debuggers in the same VMS job
tree.
For more information, see help on Debugging_Configurations.
Single Process Debugger
When you invoke the VMS Version 5.2 debugger, if a separate
process cannot be created to run the main debugger image, the
debugger issues one or more messages and automatically uses the
single-process configuration (the V5.0 and earlier
configuration, where the debugger shares a single process with
the user program). For example, if quotas are not sufficient to
create a subprocess for the main debugger, the messages are as
follows:
%DEBUG-E-CANTCREATEMAIN, could not create the VAX DEBUG subprocess
-SYSTEM-F-EXQUOTA, exceeded quota
%DEBUG-I-SHRPRC, VAX DEBUG will share user process
In the single-process configuration, you can use the debugger to
debug a program that normally runs in only one process.
However, you cannot use the additional debugger features
available with VMS Version 5.2:
o You cannot use the multiprocess debugging configuration.
o You cannot use the debugger's DECwindows interface.
o You do not have the benefit of reduced interference between
the debugger and the program being debugged.
In the single-process configuration, press Ctrl/Y to abort a
debugger command or program execution from within a debugging
session. Ctrl/Y returns you to DCL level. The DEBUG command at
the DCL level invokes the debugger, which then displays its
prompt. You cannot use the SET ABORT_KEY command to reassign
the abort function to another control key.
The single-process configuration avoids the V5.2 restrictions in
using the abort key after a SPAWN command and use of debugger
commands in DCL command procedures (see help on Release_Notes
V5.2 Abort_After_Spawn and DCL_Command_Procedures).
If you want to use the single-process debugging configuration
because it avoids these restrictions, define the DBG$PROCESS
logical name as follows before invoking the debugger:
$ DEFINE DBG$PROCESS NONE
NOTE: Use the single-process configuration (enabled when
DBG$PROCESS is defined as NONE) only when necessary to
avoid the restrictions of the default configuration. The
single-process configuration is unsupported and may not
be available in future releases of the debugger. Please
submit an SPR if you encounter any problems using the
default or multiprocess configurations (other than those
mentioned in these release notes).
Ctrl C and Ctrl Y
In previous versions of the debugger, you could use Ctrl/Y as
follows:
o From within a debugging session, to interrupt program
execution or to abort a debugger command.
o From the DCL level, to interrupt a program executing freely.
(You can then invoke the debugger by using the DEBUG
command).
You should now use Ctrl/Y only at the DCL level.
You should now use Ctrl/C rather than Ctrl/Y to abort a debugger
command or interrupt program execution from within a debugging
session.
Ctrl/C aborts these operations without exiting the debugging
session (the debugger prompt is displayed after you enter
Ctrl/C).
If your program already has a Ctrl/C AST routine enabled, use
the new SET ABORT_KEY command to reassign the abort function to
another control key. The SHOW ABORT_KEY diplays the control key
that is currently assigned the abort function.
If you use Ctrl/Y from within a debugging session, the effect
(as in previous versions of the debugger) is to interrupt the
debugging session and return control to DCL level. The effect
is the same as using Ctrl/Y with any program or utility running
on VMS.
For more information, see help on CTRL_C, CTRL_Y, and the SET
ABORT_KEY command.
Keypad
The following previously unused keypad key combinations now let
you display process-specific source and instruction displays:
GOLD-KP9 BLUE-KP9 BLUE-KP7 BLUE-KP3 BLUE-KP1
For symmetry, the command string previously assigned to BLUE-KP3
(SELECT/SOURCE %NEXT_SOURCE) has been moved to GOLD-COMMA (which
was previously unused).
The following table summarizes the new and changed functions.
For summary information arranged in keypad layout, use the HELP
KEYPAD command. For complete information about the command
bindings, use the SHOW KEY command.
Use the key definitions that manipulate process-specific
displays only with multiprocess programs.
State Key Command Invoked or Function
----------------------------------------------------------------
GOLD COMMA SELECT/SOURCE %NEXT_SOURCE Selects the next
source display in the display list as the current
source display. (This function was previously
assigned to BLUE-KP3.)
GOLD KP9 SET PROCESS/VISIBLE %NEXT_PROCESS Makes the next
process in the process list the visible process.
BLUE KP9 Displays two predefined process-spespecific source
displays, SRC_n. These are located at Q1 and Q2,
respectively, for the visible process and next
process on the process list.
BLUE KP7 Displays two sets of predefined process-specific
source and instruction displays, SRC_n and INST_n.
These comprise source and instruction displays for
the visible process at Q1 and RQ1, respectively,
and source and instruction displays for the next
process on the process list at Q2 and RQ2,
respectively.
BLUE KP3 Displays three predefined process-specific source
displays, SRC_n. These are located at S1, S2,
and S3, respectively, for the previous, current
(visible), and next process on the process list.
BLUE KP1 Displays three sets of predefined process-specific
source and instruction displays, SRC_n and INST_n.
These comprise source and instruction displays for
the visible process at S2 and RS2, respectively;
source and instruction displays for the previous
process on the process list at S1 and RS1, respec-
tively; and source and instruction displays for
the next process on the process list at S3 and
RS3, respectively.
Abort After Spawn
If you use the SPAWN command either from DCL level or from
within a debugging session, the debugger's abort key (by
default, Ctrl/C) is disabled after you log out or return from
the spawned subprocess.
The only way to re-enable the abort key or button is to log out
and log in again.
DCL Command Procedures
With previous versions of the debugger, you could use a DCL
command procedure to invoke the debugger and issue debugger
commands contained in that command procedure. For example:
$ ! Procedure to run PROG2 under debugger
$ ! control and issue debugger commands
$ !
$ RUN PROG2
SET BREAK %LINE 17
GO
EXIT
$ SHOW SYSTEM
$ LOGOUT
Starting with this version of the debugger, you can no longer
put debugger commands directly into a command procedure.
Instead, you must create a temporary file containing the
debugger commands and assign the DBG$INPUT logical name to point
to that file. For example:
$ CREATE DEBUG_COMMANDS.TMP
SET BREAK %LINE 17
GO
EXIT
$ DEFINE/USER DBG$INPUT DEBUG_COMMANDS.TMP
$ RUN PROG2
$ DELETE DEBUG_COMMANDS.TMP;0
$ SHOW SYSTEM
$ LOGOUT
Another workaround is to set up a single-process debugging
configuration. See help on Release_Notes V5.2 Single_Process.
System Management
In previous versions, the debugger and the program being
debugged ran in the same process.
Starting with this version, the debugger consists of two parts
(main and kernel), to accommodate the debugging of multiprocess
programs.
Note the following changes affecting system management:
o For a program that runs in one process, a debugging session
now requires two processes instead of one.
o For a mutiprocess program, a debugging session requires as
many processes as are used by the program, plus an additional
process for the main debugger.
Under these conditions, multiple users who are simultaneously
debugging programs can place an additional load on a system.
The subtopics describe the resources used by the debugger so
that you can tune your system for this activity.
Note that the discussion covers only the resources used by the
debugger. In the case of multiprocess programs, you might also
have to tune your system to support the programs themselves.
Additional information available:
User Quotas
Each user needs a PRCLM quota sufficient to create an additional
subprocess for the debugger, beyond the number of processes
needed by the program.
BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may
need to be increased to account for the debugger subprocess as
follows:
o Each user's ENQLM quota should be increased by at least the
number of processes being debugged.
o Each user's PGFLQUOTA may need to be increased. If a user
has an insufficient PGFLQUOTA, the debugger might fail to
activate or cause "virtual memory exceeded" errors during
execution.
o Each user's BYTLM and FILLM quotas may need to be increased.
The debugger requires BYTLM and FILLM quotas sufficient to
open each image file being debugged, the corresponding source
files, and the debugger input, output, and log files. Use
the SET MAX_SOURCE_FILES command to limit the number of
source files kept open by the debugger at any one time.
System Resources
The kernel and main debugger communicate through global
sections. The main debugger communicates with up to 8 kernel
debuggers through a 65-page global section. Therefore, the
SYSGEN global-page and global-section parameters (GBLPAGES and
GBLSECTIONS, respectively) may need to be increased. For
example, if 10 users are using the debugger simultaneously, 10
global sections using a total of 650 global pages are required
by the debugger.
V5.0
The subtopics that follow list any known bugs that could not be
fixed in time for the version 5.06 release. Also noted are any
incompatible changes that have been made for Version 4.6 of the
debugger that you should be aware of and any problems indicated
in previous release notes that have been corrected for Version
5.0.
For more information, see help on New_Features.
Additional information available:
Corrected ProblemsDynamic Register DisplayMACRO SupportObsolete Commands
Screen Mode Line WrappingVAXstation DEBUG Separate Window Control
Corrected Problems
Problems with the SET IMAGE and SET SCOPE commands that were
noted in the V4.6 release notes have been corrected (see help on
Release_Notes V4.6).
Before Version 5.0, when you specified a list of images with the
SET IMAGE command, only the last image specified was set. Now,
all specified images are set. As before, the current image is
the last image in the list (the last image set).
Previously, before issuing a SET SCOPE command, you had to be
sure that the module containing the path-name elements specified
in the SET SCOPE command was set. Now, if that module is not
already set, the SET SCOPE command automatically sets it for
you.
Dynamic Register Display
Register displays, such as the predefined display REG, are now
dynamic by default. This means that the window dimensions
adjust proportionally when you change the screen height or width
with a SET TERMINAL command.
Also, a register display now reformats the displayed
information, in the best way possible, to the window in which it
has been displayed. The default window for REG remains RH1.
However, if you were to display REG in window Q3, for example,
the information would reformat automatically to fit into the new
window.
For more information, see help on Screen_Mode Register_Display.
MACRO Support
Several enhancements have been made to MACRO support for Version
5.0, to match the support available with other languages (for
more information, see help on New_Features). Some of these
enhancements result in different behavior from previous versions
of the debugger.
When the language is set to MACRO, the default behavior of the
STEP command is now STEP/LINE (not STEP/INSTRUCTION, the
previous behavior). This change was made possible because
source line display is now available for MACRO programs.
When the language is set to MACRO, the debugger interprets an
address expression used in a language expression as the current
value stored at that address (not the address denoted by the
address expression, the previous behavior). This change affects
how language expressions are evaluated by the EVALUATE, DEPOSIT,
IF, FOR, REPEAT, and WHILE commands, and by WHEN clauses as used
with the SET BREAK, SET TRACE, and SET WATCH commands. For
example, the DEPOSIT X = Y + 2 command evaluates the sum of 2
and the current value of Y and deposits the resulting value into
X. Previously, that command evaluated the sum of 2 and the
address of Y and deposited the resulting value into X.
As before, you can get the address of an address expression by
using the EVALUATE/ADDRESS command.
Obsolete Commands
The following commands and qualifiers are obsolete starting with
VMS Version 5.0 and are no longer documented, for the reasons
stated. For compatibility with previous versions, these
commands and qualifiers will be supported indefinitely except as
indicated.
ALLOCATE
The debugger now allocates and deallocates memory
automatically. This command now has no effect.
CANCEL EXCEPTION BREAK
Same as the newer CANCEL BREAK/EXCEPTION command, which
better conforms to the general command format for canceling
breakpoints.
SET EXCEPTION BREAK
Same as the newer SET BREAK/EXCEPTION command, which better
conforms to the general command format for setting
breakpoints.
SET MODULE/ALLOCATE
The debugger now allocates and deallocates memory
automatically. /ALLOCATE now has no effect.
UNDEFINE
Same as the newer DELETE command, which conforms to the
analogous DCL command DELETE.
UNDEFINE/KEY
Same as the newer DELETE/KEY command, which conforms to the
DELETE/KEY command in DCL.
Screen Mode Line Wrapping
The change described affects how very long lines of debugger
output are presented in the OUTPUT display or in a DO display
--- for example, when you enter an EXAMINE command to examine
long ASCII strings.
Before Version 5.0, the debugger wrapped text in the OUTPUT
display or in a DO display if the text was longer than the width
of the terminal, regardless of the width of the display window.
The debugger now wraps text in these displays only if it exceeds
255 characters. If there is any text beyond the right edge of
the display window, a diamond-shaped character (or a question
mark for terminals that do not support the diamond character)
appears at the right edge. This indication is analogous to the
behavior of a text editor.
To see the hidden text, use the SCROLL/RIGHT command (or press
KP6 repeatedly, as needed).
VAXstation DEBUG Separate Window Control
(Applies only to VAXstations.) The default behavior of the
debugger on VAXstations has changed. With the addition of the
SET MODE [NO]SEPARATE command, a separate window for debugger
input and output is no longer created by default when you invoke
the debugger. You can now control the creation of the separate
window. For more information, see help on New_Features V5.0
SET_MODE_SEPARATE.
With the addition of the /[NO]POP qualifier to the SET PROMPT
command, the debugger window no longer pops and attaches to the
keyboard by default when the debugger prompts for input. You
can now control this behavior. See help on New_Features V5.0
SET_PROMPT.
If you use the SET PROMPT command without specifying a new
prompt string, the prompt string is unchanged. If you use SET
PROMPT without the /[NO]POP qualifier, the prompt behavior is
set to /NOPOP, which is the default.
The default behavior in V4.4, 4.5, and 4.6 was to pop the window
and attach it to the keyboard.
To get the previous behavior, put the following commands in your
DBG$INIT file:
SET MODE SEPARATE
SET PROMPT/POP
V4.6
The subtopics that follow list any known bugs that could not be
fixed in time for the version 4.6 release. Also noted are any
incompatible changes that have been made for Version 4.6 of the
debugger that you should be aware of. New features are listed
separately under HELP New_Features.
Additional information available:
SET IMAGE CommandSET SCOPE CommandVAXstation Support
SET IMAGE Command
With the SET IMAGE command, if you specify a list of images,
only the last image in the list is set. For example:
DBG> SET IMAGE A,B,C
In this example, only image C is set. You can set images A, B,
and C by issuing separate SET IMAGE commands for each image.
SET SCOPE Command
Before entering a SET SCOPE command, be sure that the module
that contains the elements named in the path name has already
been set by a SET MODULE command or dynamically by the debugger.
Use the SHOW MODULE command to determine whether a module is set
--- that is, whether its symbols have been loaded into the
run-time symbol table.
VAXstation Support
Previously, if the debugger detected that it was running on a
VAXstation, it would create a separate emulated terminal window
for its own input and output. This meant that terminal I/O
performed by the program was logically and physically separated
from the debugger's I/O, particularly helpful when debugging
screen-mode applications.
To remove a potential problem on the VAXstation, the method the
debugger uses to control the separate window has been changed.
Previously, the debugger controlled the separate window with
UIS$xxx calls. The debugger now uses the new OSC sequences to
communicate control functions to the terminal emulator.
With this update, the debugger's behavior is slightly different.
It still creates a separate window, but only if both of the
following two conditions are met:
o You must be running the SDC release of VWS V3.0 (or higher).
o You must have the following system logical name defined:
$ DEFINE/SYSTEM/EXEC UIS$VT_ENABLE_OSC_STRINGS TRUE
V4.4
The subtopics that follow list any known bugs that could not be
fixed in time for the version 4.4 release. Also noted are any
incompatible changes that have been made for Version 4.4 of the
debugger that you should be aware of. New features are listed
separately under HELP New_Features.
Additional information available:
Key DefinitionsRegister DisplayScreen ManagementShareable Images
VAXstationsWindow Definitions
Key Definitions
The default definitions of the KP7 and MINUS keys have been
changed to accommodate changes in predefined display and window
definitions. The new definitions are as follows:
Key Definition
-----------------------------------------------
KP7 DISPLAY SRC AT LH1, INST AT RH1,
OUT AT S45, PROMPT AT S6
GOLD-KP7 DISPLAY INST AT LH1, REG AT RH1,
OUT AT S45, PROMPT AT S6
BLUE-KP7 Not defined
MINUS DISPLAY %NEXTDISP AT S12345
GOLD-MINUS Not defined
BLUE-MINUS (Default.) DISPLAY SRC AT H1,
OUT AT S45, PROMPT AT S6
For more information on the new window definitions, see help on
New_Features V4.4 Window_Definitions.
Register Display
The screen-mode register display (REG) has been reformatted to
take advantage of the new window capabilities. REG is now a
square display that fits in one of the quarters of the screen
(for example, the top lefthand window LH1 or the top righthand
window RH1). If your debugger initialization file had a command
like ---
DBG> DISPLAY REG AT Q3
then you may want to change it to something like ---
DBG> DISPLAY REG AT RH1
to accommodate the re-shaped register display.
Screen Management
In version 4.4 the debugger uses the SMG screen package to
implement its screen mode. If your program also calls SMG
routines, and you debug it with the debugger running on the same
terminal, then there probably will be interference between your
program and the debugger.
The recommended solution is to debug the program using two
terminals. For a description of how to do this, see Chapter 8
of the VMS Debugger Manual.
Shareable Images
Support for debugging shareable images is new in version 4.4 of
the debugger and is described under New_Features. There is one
restriction you should be aware of when debugging shareable
images. The shareable image must have been linked with the
/DEBUG qualifier in order for shareable image debugging to work.
If the image was not linked with the /DEBUG qualifier, the
debugger may let you use SET IMAGE for that image but it may
show you incorrect results.
In summary:
$ LINK/SHARE/DEBUG X ! Can SET IMAGE, everything OK
$ LINK/SHARE X ! Can SET IMAGE, get incorrect results
$ LINK/SHARE/NOTRACE X ! Cannot SET IMAGE
VAXstations
In version 4.4, the debugger comes up in its own window when you
run it on the VAXstation.
There is a problem with Ctrl/Y handling when the debugger is
running in its own VAXstation window. The Ctrl/Y is ignored
when the keyboard is attached to the debugger window. To make
the Ctrl/Y take effect you must attach the keyboard to the
original window (by pointing at it with the mouse), and then
press Ctrl/Y.
This problem will be fixed in a future release.
Window Definitions
If you use predefined windows such as H2 in your initialization
file or in your own command or key definitions then you should
be aware of the following changes.
Changes to display window definitions and the addition of a
PROMPT predefined display have caused some incompatibilities
with earlier versions of the debugger.
Previously, the bottom sixth of the screen (lines 21--24) on a
VT100 or VT200 series terminal) could not be used for defining
display windows. That area was reserved for the debugger
prompt, debugger input, debugger diagnostic messages, and
program output. Now, display windows can occupy any part of the
screen, and a new predefined PROMPT display shows the debugger
prompt, debugger input, and program output.
The boundaries of the default windows have been redefined to
cover the greater usable screen height. For example, on a VT100
or VT200 series terminal, FS (full screen) now covers lines
1--24, H1 lines 1--12, H2 lines 13--24, and so on. A new symbol
prefix, S, denotes a multiple of one sixth of the screen. For
example, S56 is the bottom two sixths of the screen. (There are
other new predefined windows that occupy only the left or right
halves of the screen. See help on New_Features V4.4
Vertically_Divided_Windows.)
The PROMPT display occupies S6 by default, but can be moved
elsewhere, like any display. To avoid confusion, the PROMPT
display is always on top of the display pasteboard and therefore
hides the part of any display that overlaps the PROMPT window.
By default, the OUT display is now at S45 (not, as previously,
at H2), so it is not hidden by the PROMPT display. And the
keypad keys that manipulate display windows have been redefined
so that no display is positioned behind S6 (see help on
Release_Notes V4.4 Key_Definitions). If your debugger
initialization file contains DISPLAY commands to locate displays
near the bottom of the screen (for example, at H2, T3, or Q34)
you may want to modify these window definitions so the displays
are not hidden.
For more information, see help on New_Features V4.4
Window_Definitions.
V4.2
The following is a list of any incompatible changes that have
been made for version 4.2 of the debugger.
For more information, see help on New_Features.
Additional information available:
Register WindowsMACRO DefaultsBASIC Defaults
Register Windows
In version 4.0 of the debugger, the register display occupied 5
lines of the screen. Special windows were invented to
accomodate a display of this size, and these were named R1, R2,
R3, R12, and R23.
For version 4.2 of the debugger, the register display has been
reduced to just 4 lines. This was done by making more efficient
use of space and also by removing the translation of R0 as an
error message. (To get the translation of R0, use the EXAMINE
/CONDITION R0 command).
Now that the register display occupies 4 lines, it fits in the
standard windows Q1, Q2, Q3, and Q4 (one quarter of the screen).
So the special purpose windows R1, R2, and R3 have been dropped.
If you refer to them in any command files, you should change
your command file to use one of the Q (quarter) displays
instead. For example:
Old DBG$INIT file New DBG$INIT file
------------------ ------------------
DISPLAY REG AT R1 DISPLAY REG AT Q1
DISPLAY OUT AT R23 DISPLAY OUT AT Q234
MACRO Defaults
In version 4.0, the screen default for MACRO was to display the
registers on the top of the screen, and the output display in
the rest of the screen. Because of the addition of the
instruction display in version 4.2, this default was changed to
be the assembly language instructions (INST display) in H1 and
the output display in H2. This make the MACRO default closer to
the rest of the languages. If you want to display the registers
for MACRO, you now need to specify that in a DISPLAY command.
For example, the following puts the registers in the top quarter
and the assembly instructions in the second quarter:
DBG> DISPLAY REG AT Q1
DBG> DISPLAY INST AT Q2
BASIC Defaults
In version 4.0, the screen-mode defaults for language BASIC were
the same as for language MACRO. This was because, at that time,
the BASIC compiler was not generating the symbol table records
needed to do source display.
With version 2.4 of BASIC, source display is available for that
language. So the screen-mode default for BASIC has been changed
to be the source display in the top half of the screen, and the
output display in the bottom half of the screen (the same as for
the other high-level languages).
Address Expressions
The term "address expression" is used in many debugger help
topics. An address expression specifies a location in your
program. Commands for which you specify address expressions
are:
DEPOSIT (at the left of the equal sign)
EXAMINE
EVALUATE/ADDRESS
SET BREAK
SET TRACE
SET WATCH
In general, you can specify addresses using the syntax of the
currently set language:
DBG> EXAMINE A(1) ! FORTRAN
DBG> SET WATCH A[1] ! Pascal
DBG> EXAMINE C OF R ! COBOL
You can specify addresses numerically, and you can also use the
built-in symbols %LINE and %LABEL for referring to code
locations:
DBG> EXAMINE 512
DBG> SET BREAK %LINE 10
You can use the following operators to specify addresses that
you might not be able to specify by name:
+ - * / Arithmetic operators
@ or . Indirection
<p,s> Select bit field
For example, the following command examines the instruction 3
bytes after line 10:
DBG> EXAMINE %LINE 10 + 3
The following command examines the location pointed to by P:
DBG> EXAMINE @P
The following examples show the difference between address
expressions and language expressions:
DBG> EVALUATE/ADDR X
512
DBG> EXAMINE X
X: 0
DBG> EVALUATE X+1 ! Language expression: adds 0 + 1
1
DBG> EXAMINE X+1 ! Address expression: 1 byte beyond X
513: 0
Built in Symbols
The debugger built-in symbols provide options for specifying
program entities and values in debugger commands.
The Overview topic lists the built-in symbols according to
functional groupings.
Additional information available:
%AP%FP%SP%PC%PSL%VCR%VLR
%VMR%NAME%PARCNT%BIN%DEC%HEX%OCT
%CURLOC%NEXTLOC%PREVLOC%CURVAL%LABEL%LINE%PAGE
%WIDTH%DECWINDOWS%ADDR%DESCR%REF%VAL
%CURDISP%CURSCROLL%NEXTDISP%NEXTINST
%NEXTOUTPUT%NEXTSCROLL%NEXTSOURCE%SOURCE_SCOPE
%INST_SCOPE%CURRENT_SCOPE_ENTRY%NEXT_SCOPE_ENTRY
%PREVIOUS_SCOPE_ENTRY%PROCESS_NAME%PROCESS_PID
%PROCESS_NUMBER%NEXT_PROCESS%PREVIOUS_PROCESS%VISIBLE_PROCESS
%ADAEXC_NAME%EXC_FACILITY%EXC_NAME%EXC_NUM
%EXC_SEVERITY%ACTIVE_TASK%CALLER_TASK%NEXT_TASK
%TASK%VISIBLE_TASK
Overview
The debugger built-in symbols are grouped functionally as
follows:
Built-in Symbol Usage
---------------------------------------------------------------
%R0 to %R11, %AP (R12), To specify VAX general registers.
%FP (R13), %SP (R14),
%PC (R15), %PSL
%V0 to %V15, %VCR, To specify VAX vector registers and
%VLR, %VMR vector control registers.
%NAME To construct identifiers.
%PARCNT In command procedures, to count
parameters passed.
%BIN, %DEC, %HEX, To specify radix (binary, decimal,
%OCT (hexadecimal, or octal).
%CURLOC, %NEXTLOC, To specify consecutive program
%PREVLOC, %CURVAL locations and the current value
of an entity.
%LABEL and %LINE To specify numeric labels and
line numbers.
%PAGE and %WIDTH To specify the screen height and
width.
%DECWINDOWS In debugger command procedures or
initialization files, to determine
whether the DECwindows interface
or command interface was invoked.
%ADDR, %DESCR, %REF, To specify the argument passing
%VAL mechanism for the CALL command.
%CURDISP, %CURSCROLL, To specify screen-mode displays.
%NEXTDISP, %NEXTINST,
%NEXTOUTPUT, %NEXTSCROLL,
%NEXTSOURCE
%SOURCE_SCOPE To specify the scope, relative to the
call stack, for which source code is
displayed in screen mode.
%INST_SCOPE To specify the scope, relative to the
call stack, for which decoded instruc-
tions are displayed in screen mode.
%CURRENT_SCOPE_ENTRY, To specify the call frame for source
%NEXT_SCOPE_ENTRY, display, instruction display, and
%PREVIOUS_SCOPE_ENTRY symbol lookup.
%ADAEXC_NAME, To provide information about the
%EXC_FACILITY, current exception.
%EXC_NAME, %EXC_NUM,
%EXC_SEVERITY
%NEXT_PROCESSS, To specify processes in multiprocess
%PREVIOUS_PROCESS, programs.
%PROCESS_NAME
%PROCESS_PID,
%PROCESS_NUMBER,
%VISIBLE_PROCESS
%ACTIVE_TASK, To specify tasks in tasking programs.
%CALLER_TASK,
%NEXT_TASK, %TASK,
%VISIBLE_TASK
%Rn
Specifies the VAX general purpose registers R0 through R11.
Example:
DBG> DEPOSIT %R1 = 23
%AP
Specifies the VAX argument pointer register (R12).
%FP
Specifies the VAX frame pointer register (R13).
%SP
Specifies the VAX stack pointer register (R14).
%PC
Specifies the VAX program counter register (R15) which contains
the address of the next instruction to execute.
Examples:
1. DBG> EXAMINE %PC
MOD3\%PC: 1554
Displays the value contained in the PC (the address of the
next instruction to execute).
2. DBG> EXAMINE .%PC
MOD3\%LINE 12: MOVL B^12(R11),R1
Displays the value at the address in the PC (the next
instruction to execute).
%PSL
Specifies the VAX processor status longword.
%Vn
Specifies the VAX vector registers V0 through V15.
%VCR
Specifies the VAX vector count register (VCR) which contains the
length of the offset vector generated by the IOTA instruction.
%VLR
Specifies the VAX vector length register (VLR) which limits the
highest element of a vector register processed by a vector
instruction.
%VMR
Specifies the VAX vector mask register (VMR) which contains a
mask (bit pattern) that a vector instruction uses to operate on
only certain elements of a vector register operand.
%NAME
Constructs identifiers that are not ordinarily legal in the
current language.
Format:
%NAME id-char-string
%NAME 'any-char-string'
Examples:
1. DBG> EXAMINE %NAME 12
Examines a variable named 12.
2. DBG> EXAMINE %NAME 'P.AAA'
Examines a generated label P.AAA
%PARCNT
Specifies the number of actual parameters to the current command
procedure. For example, suppose the command file ABC is invoked
with the @ABC 111,222,333 command. Inside ABC, %PARCNT then has
the value 3 because there are three parameters on this
particular call to ABC. %PARCNT is used in command procedures
that can take a variable number of actual parameters. %PARCNT
can only be used inside command files; it is not defined when
commands are entered from the terminal.
Example:
EVAL %PARCNT
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVAL X)
%BIN
Interprets the numeric literal (or all numeric literals in the
parenthesized expression) in binary radix.
Examples:
DBG> EVALUATE/DEC %BIN 10
2
DBG> EVALUATE/DEC %BIN (10 + 10)
4
%DEC
Interprets the numeric literal (or all numeric literals in the
parenthesized expression) in decimal radix.
Examples:
DBG> EVALUATE/HEX %DEC 10
0A
DBG> EVALUATE/HEX %DEC (10 + 10)
14
%HEX
Interprets the numeric literal (or all numeric literals in the
parenthesized expression) in hexadecimal radix.
Examples:
DBG> EVALUATE/DEC %HEX 10
16
DBG> EVALUATE/DEC %HEX (10 + 10)
32
%OCT
Interprets the numeric literal (or all numeric literals in the
parenthesized expression) in octal radix.
Examples:
DBG> EVALUATE/DEC %OCT 10
8
DBG> EVALUATE/DEC %OCT (10 + 10)
16
%CURLOC
Specifies the current logical entity --- that is, the program
location last referenced by an EXAMINE, DEPOSIT, or EVALUATE
/ADDRESS command. You can also use the period (.) for this
purpose.
Examples:
DBG> EXAMINE RADIUS
CIRCLE\RADIUS: 0.0000000E+00
DBG> DEPOSIT %CURLOC = 1 ! Set RADIUS to 1
DBG> DEPOSIT . = 2 ! Set RADIUS to 2
%NEXTLOC
Specifies the logical successor of the current entity --- that
is, the program location that logically follows the location
last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS
command. The EXAMINE command without a parameter is the same as
EXAMINE %NEXTLOC.
Examples:
DBG> EXAMINE PRIMES(4)
SIEVE\PRIMES(4): 7
DBG> EXAMINE %NEXTLOC
SIEVE\PRIMES(5): 11
DBG> EXAMINE ! Same as EXAMINE %NEXTLOC
SIEVE\PRIMES(6): 13
%PREVLOC
Specifies the logical predecessor of the current entity --- that
is, the program location that logically precedes the location
last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS
command. You can also use the circumflex (^) for this purpose.
Examples:
DBG> EXAMINE PRIMES(6)
SIEVE\PRIMES(6): 13
DBG> EXAMINE %PREVLOC
SIEVE\PRIMES(5): 11
DBG> EXAMINE ^
SIEVE\PRIMES(4): 7
%CURVAL
Specifies the value that was last displayed by an EVALUATE or
EXAMINE command or that was deposited by a DEPOSIT command. You
can also use the backslash (\) for this purpose. These two
symbols are not affected by an EVALUATE/ADDRESS command.
Examples:
DBG> EXAMINE RADIUS
CIRCLE\RADIUS: 0.0000000E+00
DBG> EVALUATE %CURVAL
0.0000000E+00
%LABEL
Specifies a numbered label in your program. This is intended
for languages like FORTRAN whcih have numeric program labels.
You can qualify the label with a path name specifying the
containing module.
Example:
DBG> SET BREAK MODULENAME\%LABEL 10
The old syntax of %LABEL MODULENAME\10 is no longer accepted.
%LINE
Specifies a line number in your program. You can qualify the
line number with a path name specifying the containing module.
Example:
DBG> SET BREAK MODULENAME\%LINE 10
The old syntax of %LINE MODULENAME\10 is no longer accepted.
%PAGE
Specifies the current height of the screen in lines.
For example, the following command defines a screen-mode window
named MIDDLE that occupies a region around the middle of the
screen:
DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
%WIDTH
Specifies the current width of the screen in columns.
For example, the following command defines a screen-mode window
named MIDDLE that occupies a region around the middle of the
screen:
DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
%DECWINDOWS
Determines whether the DECwindows interface or command interface
was invoked. With the DECwindows interface, the value of
%DECWINDOWS is 1 (TRUE). With the command interface, the value
of %DECWINDOWS is 0 (FALSE).
Example:
DBG> EVALUATE %DECWINDOWS
0
The following example shows how to use %DECWINDOWS in a debugger
initialization file to position the debugger source window, SRC,
at debugger startup:
IF %DECWINDOWS THEN
! DECwindows (workstation) syntax:
(DISPLAY SRC AT (100,300,100,700))
ELSE
! Screen-mode (terminal) syntax:
(DISPLAY SRC AT (AT H1))
%ADDR
(Default.) Used with the CALL command to pass the argument by
address.
%DESCR
Used with the CALL command to pass the argument by descriptor.
%REF
(Default.) Used with the CALL command to pass the argument by
reference.
%VAL
(Default.) Used with the CALL command to pass the argument by
value.
%CURDISP
Specifies the current display (screen mode). This is the
display most recently referenced with a DISPLAY command --- the
least occluded display.
Example:
DBG> SELECT/SCROLL %CURDISP
%CURSCROLL
Specifies the current (screen-mode) scrolling display. This is
the default display for the SCROLL, MOVE, and EXPAND commands,
as well as for the associated keys (KP2, KP4, KP6, and KP8).
Example:
DBG> EXPAND/DOWN:5 %CURSCROLL
%NEXTDISP
Specifies the next display after the current display in the
screen-mode display list. The next display is the display that
follows the topmost display. Because the display list is
circular, this is the display at the bottom of the pasteboard
--- the most occluded display.
Example:
DBG> DISPLAY/POP %NEXTDISP
%NEXTINST
Specifies the next instruction display after the current
instruction display in the screen-mode display list. The
current instruction display is the display that receives the
output from EXAMINE/INSTRUCTION commands.
Example:
DBG> DISPLAY/REMOVE %NEXTINST
%NEXTOUTPUT
Specifies the next output display after the current output
display in the screen-mode display list. An output display
receives debugger output that is not already directed to another
display.
Example:
DBG> EXTRACT %NEXTOUTPUT OUT4.TXT
%NEXTSCROLL
Specifies the next display after the current scrolling display
in the screen-mode display list.
Example:
DBG> SELECT/SCROLL %NEXTSCROLL
%NEXTSOURCE
Specifies the next source display after the current source
display in the screen-mode display list. The current source
display is the display which receives the output from TYPE and
EXAMINE/SOURCE commands.
Example:
DBG> SELECT/SOURCE %NEXTSOURCE
%SOURCE_SCOPE
Specifies the scope, relative to the call stack, for which
source code is displayed in a screen-mode source display. If
source code is not available for display in that scope, the
debugger displays source code for the next level down the call
stack for which it is available.
%SOURCE_SCOPE is used in the definition of the predefined
screen-mode source display SRC:
DBG> DISPLAY SRC AT H1 SOURCE (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC)
%INST_SCOPE
Specifies the scope, relative to the call stack, for which
decoded VAX instructions are displayed in a screen-mode
instruction display.
%INST_SCOPE is used in the definition of the predefined
screen-mode instruction display INST:
DBG> DISPLAY INST AT H1 INSTRUCTION (EXAMINE/INST .%INST_SCOPE\%PC)
%CURRENT_SCOPE_ENTRY
Specifies the call frame that the debugger is currently using as
reference when displaying source code or decoded VAX
instructions, or when searching for symbols. By default, this
is call frame 0.
%CURRENT_SCOPE_ENTRY returns an integer value that denotes a
call frame on the call stack. Call frame 0 denotes the routine
at the top of the call stack, where execution is suspended; call
frame 1 denotes the calling routine; and so on.
%NEXT_SCOPE_ENTRY
Specifies the next frame down the call stack from the call frame
denoted by %CURRENT_SCOPE_ENTRY.
%NEXT_SCOPE_ENTRY returns an integer value that denotes a call
frame on the call stack. Call frame 0 denotes the routine at
the top of the call stack, where execution is suspended; call
frame 1 denotes the calling routine; and so on.
%PREVIOUS_SCOPE_ENTRY
Specifies the next frame up the call stack from the call frame
denoted by %CURRENT_SCOPE_ENTRY.
%PREVIOUS_SCOPE_ENTRY returns an integer value that denotes a
call frame on the call stack. Call frame 0 denotes the routine
at the top of the call stack, where execution is suspended; call
frame 1 denotes the calling routine; and so on.
%PROCESS_NAME
When specifying a VMS process name in a debugger command string,
you can optionally precede the name with the %PROCESS_NAME
symbol.
Example:
DBG_2> EXIT %PROCESS_NAME JONES_4
%PROCESS_NAME applies only to a multiprocess debugging
configuration (when the DBG$PROCESS logical name is defined as
MULTIPROCESS). For more information, see help on Multiprocess
Specifying_Processes.
%PROCESS_PID
When specifying a VMS process identification number (PID) in a
debugger command string, you must precede the PID with the
%PROCESS_PID symbol. For example:
DBG_2> CONNECT %PROCESS_PID 258001B6
%PROCESS_PID applies only to a multiprocess debugging
configuration (when the DBG$PROCESS logical name is defined as
MULTIPROCESS). For more information, see help on Multiprocess
Specifying_Processes.
%PROCESS_NUMBER
When specifying a debugger-assigned process number in a debugger
command string, you must precede the number with the
%PROCESS_NUMBER symbol (or the abbreviation %PROC).
Example:
DBG_2> SHOW PROCESS %PROC 3
%PROCESS_NUMBER applies only to a multiprocess debugging
configuration (when the DBG$PROCESS logical name is defined as
MULTIPROCESS). For more information, see help on Multiprocess
Specifying_Processes.
%NEXT_PROCESS
Specifies the next process in the debugger's process list after
the visible process.
Example:
DBG_3> SET PROCESS/HOLD %NEXT_PROCESS
%NEXT_PROCESS applies only to a multiprocess debugging
configuration (when the DBG$PROCESS logical name is defined as
MULTIPROCESS). For more information, see help on Multiprocess
Specifying_Processes.
%PREVIOUS_PROCESS
Specifies the previous process in the debugger's process list
before the visible process.
Example:
DBG_3> SHOW PROCESS/FULL %PREVIOUS_PROCESS
%PREVIOUS_PROCESS applies only to a multiprocess debugging
configuration DBG$PROCESS logical name is defined as
MULTIPROCESS). For more information, see help on Multiprocess
Specifying_Processes.
%VISIBLE_PROCESS
Specifies the visible process. This is the process whose stack,
register set, and images are the current context for looking up
symbols, register values, routine calls, breakpoints, and so on.
Example:
DBG_2> DO/PROCESS=(%VISIBLE_PROCESS,%NEXT_PROCESS) (EXAMINE X)
%VISIBLE_PROCESS applies only to a multiprocess debugging
configuration (when the DBG$PROCESS logical name is defiened as
value MULTIPROCESS). For more information, see help on
Multiprocess Specifying_Processes.
%ADAEXC_NAME
A special form of %EXC_NAME for Ada programs. In Ada, an
exception can be raised with syntax such as raise XXX;. In this
case, the exception name in the VMS sense is just EXCEPTION,
which is what %EXC_NAME returns. %ADAEXC_NAME returns the Ada
exception name (XXX).
Example:
DBG> SET BREAK/EXCEPTION WHEN (%ADAEXC_NAME = "XXX")
%EXC_FACILITY
Returns the facility of the current exception. This provides a
way of qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_FACILITY
"SYSTEM"
DBG> SET BREAK/EXC WHEN (%EXC_FAC = "SYSTEM")
%EXC_NAME
Returns the name of the current exception. This provides a way
of qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_NAME
"FLTDIV_F"
DBG> SET BREAK/EXC WHEN (%EXC_NAME = "FLTDIV_F")
%EXC_NUM
Returns the current exception number. This provides a way of
qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_NUM
12
DBG> EVALUATE/COND %EXC_NUM
%SYSTEM-F-ACCVIO, access violation at PC !XL, virtual address !XL
DBG> SET BREAK/EXC WHEN (%EXC_NUM = 12)
%EXC_SEVERITY
Returns the severity code of the current exception. This
provides a way of qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_SEVERITY
"F"
DBG> SET BREAK/EXC WHEN (%EXC_SEV = "F")
%ACTIVE_TASK
(Applies only to tasking programs.) Returns the currently
active task --- the one running when the debugger last took
control. See help on the SET TASK/ACTIVE command.
Example:
DBG> EVALUATE %ACTIVE_TASK
%TASK 2
%CALLER_TASK
(Applies only to Ada tasking programs.) Returns the task that
is the entry caller of the active task during a task rendezvous.
If the active task (%ACTIVE_TASK) is not currently executing an
accept statement (that is, a rendezvous is not in progress),
%CALLER_TASK returns %TASK 0.
For example, the following command sets a breakpoint within an
accept statement. The breakpoint is triggered only when %TASK 3
is the task making the entry call of the rendezvous.
DBG> TYPE 51:53
module SAMPLE
51: accept RENDEZVOUS do
52: PUT_LINE("Beginning the rendezvous");
53: end RENDEZVOUS;
DBG> SET BREAK %LINE 52 WHEN (%CALLER_TASK = %TASK 3)
%NEXT_TASK
(Applies only to tasking programs.) Returns the next task after
the currently visible task (%VISIBLE_TASK). "Next" in this
context is just an internal ordering that cycles through all
tasks. This is useful for command procedures.
Example:
DBG> WHILE %NEXT NEQ %ACTIVE DO -
(SET TASK %NEXT; SHOW CALLS)
%TASK
(Applies only to tasking programs.) Specifies a task by its
task ID. This is the debugger syntax for referring to a task by
its task ID. The task ID is a unique number associated with a
task at the time the task is created. You can get the task
number by using the SHOW TASK/ALL command or by examining task
objects.
Example:
DBG> EXAMINE T1
T1: %TASK 2
DBG> SET TASK %TASK 2
%VISIBLE_TASK
(Applies only to tasking programs.) Returns the task that the
debugger is using to do symbol lookups. It is the default task
assumed by debugging commands when you do not (or cannot)
specify a task. For example, the EXAMINE %R0 command displays
register 0 of the visible task.
The visible task is normally the same as the active task
(%ACTIVE_TASK) but can be changed with the SET TASK command.
Example:
DBG> SET TASK %TASK 2
DBG> EVALUATE %VISIBLE
%TASK 2
DECwindows Interface
The VMS debugger has two user interfaces:
o A command interface for terminals and workstations
o A DECwindows interface for workstations
This help library covers the command interface.
Context-sensitive online help about the DECwindows interface is
available when you use that interface.
Type HELP Logical_Names DBG$DECW$DISPLAY for more information.
For complete information, see the DECwindows-interface
documentation in the VMS Debugger Manual.
Debugging Configurations
You can use the debugger in two configurations --- default or
multiprocess. Use the default configuration to debug a program
that normally runs (without the debugger) in only one process.
Use the multiprocess configuration to debug a program that
normally runs in more than one process. The configuration
depends only on the definition of the DBG$PROCESS logical name,
as indicated in the following table:
DBG$PROCESS Configuration
---------------------------------------
Undefined or DEFAULT Default
MULTIPROCESS Multiprocess
Note that a multiprocess configuration results from DBG$PROCESS
having the value MULTIPROCESS and does not depend on whether a
program runs in more than one process. The value of DBG$PROCESS
determines whether or not images running in different processes
can connect to the same debugging session.
For more information, see help on Multiprocess.
Additional information available:
Examples
1. $ DEFINE/JOB DBG$PROCESS MULTIPROCESS
$ RUN PROG1
...
DBG_1>
In this example, the DEFINE/JOB command specifies the
multiprocess configuration. This is indicated by the
process-specific prompt suffix (_1), which is displayed
initially when the debugger is invoked with the RUN command.
The prompt suffix indicates that execution is suspended in
process 1, the first process brought under debugger control.
Process 1 is currently the visible process --- the context for
executing process-specific commands like STEP, EXAMINE, and so
on.
2. $ DEFINE DBG$PROCESS DEFAULT
$ RUN PROG1
...
DBG>
In this example, the DEFINE command specifies the default
configuration. This indicated by the DBG> prompt, which is
displayed when the debugger is invoked with the RUN command.
Process Relationships
The debugger consists of two parts:
1. A relatively small kernel debugger image (DEBUG.EXE) which
runs in the same process as the image being debugged
2. A larger main debugger image (DEBUGSHR.EXE) which contains
most of the debugger code and runs in a subprocess.
In the default (non-multiprocess) configuration, the program
being debugged (which may consist of several images) runs in one
process along with the kernel debugger. The main debugger runs
in a subprocess.
In the multiprocess configuration, the program being debugged
(which may consist of several images) runs in several processes.
Each process running an image under debugger control is also
running a local copy of the kernel debugger. One main debugger
runs in a separate subprocess and communicates with the other
processes through their kernel debuggers.
Regardless of the configuration, the presence of a main debugger
running in some process sets up a unique debugging session.
The current definition of DBG$PROCESS determines whether or not
debuggable images running in different processes can connect to
the same main debugger.
Additional information available:
Default ConfigurationMultiprocess Configuration
Default Configuration
The default configuration is achieved when DBG$PROCESS is either
undefined or is defined as DEFAULT:
$ DEFINE DBG$PROCESS DEFAULT
Under these conditions, when you invoke the debugger, the
program runs in its original process along with the kernel
debugger, but a new subprocess is created to run the main
debugger (see Figure 1).
When you use the default configuration, a new main debugger
(and, therefore, a new debugging session) begins every time you
invoke the debugger.
Figure 1: Default Debugging Configuration
+----------+
| program |
| being |
| debugged |
|----------|
| kernel |
| debugger |
+----------+
|
+----------+
| main |
| debugger |
+----------+
Multiprocess Configuration
The multiprocess configuration lets you interact with several
processes from one debugging session. This configuration is
enabled if the definition of DBG$PROCESS is MULTIPROCESS:
$ DEFINE/JOB DBG$PROCESS MULTIPROCESS
When defining DBG$PROCESS, use a job logical definition to
ensure that the definition applies to all processes in that job
tree. An image can be connected to an existing multiprocess
debugging session only if the process running the image is in
the same job tree as the main debugger of that debugging
session.
In the multiprocess configuration, the main debugger runs in one
process. Each process associated with the multiprocess program
runs a kernel debugger along with one or more images of the
program. The main debugger communicates with each kernel
debugger. Although all processes of a multiprocess
configuration must be in the same job tree, they do not have to
be related in a particular process/subprocess hierachy.
Moreover, the program images running in separate processes do
not have to communicate with each other.
Two possible multiprocess configurations are illustrated in
Figures 1 and 2. Figure 1 shows the typical multiprocess
configuration. The program runs in one master parent process
and several subprocesses. The debugger is invoked from the
master process, and then the program creates subprocesses during
execution (a subprocess may also become the parent of another
level of subprocesses).
Figure 1: Multiprocess Configuration, Single Master Process
+--------+
| master |
/|--------|\
/ |kernel | \
+--------+ |debugger| +--------+
|child1 | +--------+ |child2 |
/|--------| | |--------|
/ |kernel | | |kernel |
+--------+ |debugger| | |debugger|
|child3 | +--------+ | +--------+
|--------| | | /
|kernel | | | /
|debugger| | | /
+--------+ | | /
\ | | /
+------------------+
| main |
| debugger |
+------------------+
In Figure 2, the multiprocess program runs in several peer
processes. There is no master process. This configuration
would result if you invoked the debugger by running one
debuggable image and then used the SPAWN/NOWAIT command
repeatedly to spawn other processes and run a debuggable image
in each spawned process.
Figure 2: Multiprocess Configuration, Peer Processes
+--------+ +--------+ +--------+ +--------+
| proc1 |--| proc2 |--| proc3 |--| proc4 |
|--------| |--------| |--------| |--------|
|kernel | |kernel | |kernel | |kernel |
|debugger| |debugger| |debugger| |debugger|
+--------+ +--------+ +--------+ +--------+
\ | | /
+-----------------------+
| main |
| debugger |
+-----------------------+
Keypad Definitions
On Digital VT-series terminals and MicroVAX workstations, you
can use the numeric keypad to enter debugger commands if SET
MODE KEYPAD is in effect. Keypad mode is enabled by default,
but can be disabled by the SET MODE NOKEYPAD command. In keypad
mode, keypad keys are bound to commonly used debugger commands
such as STEP, GO and EXAMINE.
Most keys are bound to screen-mode commands to help you
manipulate the predefined screen displays efficiently. Some
keys are terminated --- the corresponding command executes
immediately. Others are not terminated; you can enter
additional parameters to the command before terminating it with
a carriage return or the ENTER key. Also, some keys echo on the
terminal while others do not, depending on the key.
You can define your own keypad definitions with the DEFINE/KEY
command.
Additional information available:
DEFAULTGOLDBLUEMOVEEXPANDCONTRACTMOVE_GOLD
EXPAND_GOLDCONTRACT_GOLDMOVE_BLUEEXPAND_BLUE
CONTRACT_BLUE
DEFAULT
Keypad definitions when you +--------+--------+--------+--------+
do not use a color key. | | Help | Set | |
| GOLD | Keypad | Mode | BLUE |
For more keypad help, see | |Default | Screen | |
the following topics: +--------+--------+--------+--------+
| Src LH1| | | Disp |
KEYPAD BLUE |Inst RH1| Scroll | Disp | next |
KEYPAD GOLD | Out S45| Up | next | S12345 |
KEYPAD STATE_KEYS +--------+--------+--------+--------+
| | Exam | | |
Ctrl/W does Display/Refresh | Scroll | Source | Scroll | Go |
to refresh the screen in | Left | .0\%PC | Right | |
screen mode. +--------+--------+--------+--------+
| | | Select | |
| Exam | Scroll | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
GOLD
Keypad definitions when you +--------+--------+--------+--------+
press the GOLD key first. | | Help |Set Mode| |
| GOLD | Keypad | No | BLUE |
Reset cancels the GOLD key. | | Gold | Screen | |
+--------+--------+--------+--------+
For more keypad help, see |Inst LH1| | Set | |
the following topics: | Reg RH1| Scroll | Process| |
| Out S45| Top | next | |
KEYPAD BLUE +--------+--------+--------+--------+
KEYPAD DEFAULT | Scroll | | Scroll | Select |
KEYPAD STATE_KEYS | Left | Show | Right | Source |
| 255 | Calls | 255 | next |
Ctrl/W does Display/Refresh +--------+--------+--------+--------+
to refresh the screen in | Exam | | Select | |
screen mode. | prev | Scroll | Output | E |
| | Bottom | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
BLUE
Keypad definitions when you +--------+--------+--------+--------+
press the BLUE key first. | | Help | | |
| GOLD | Keypad | Disp | BLUE |
"..." means that you must enter | | Blue | Gener | |
more input after pressing key. +--------+--------+--------+--------+
|2 SRC Qn| Scroll | 2 SRC | Disp |
Reset cancels the BLUE key. | 2 INST | Up | at | Src H1 |
| at RQn | ... | Q1,Q2 | Out S45|
For more keypad help, see +--------+--------+--------+--------+
the following topics: | Scroll | Show | Scroll | Select |
| Left | Calls | Right | Inst |
KEYPAD DEFAULT | ... | 3 | ... | next |
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS |3 SRC Sn| Scroll | 3 SRC | |
| 3 INST | Down | at | E |
Ctrl/W does Display/Refresh | at RSn | ... |S1,S2,S3| N |
to refresh the screen in +--------+--------+--------+ T |
screen mode. | | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
MOVE
Keypad definitions in the MOVE +--------+--------+--------+--------+
MOVE state when you do not use | | Help | Set | |
a color key. | GOLD | Keypad | Mode | BLUE |
| | Move | Screen | |
For more keypad help, see +--------+--------+--------+--------+
the following topics: | Src LH1| | | Disp |
|Inst RH1| Move | Disp | next |
KEYPAD BLUE | Out S45| Up | next | S12345 |
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | | Exam | | |
| Move | Source | Move | Go |
Ctrl/W does Display/Refresh | Left | .0\%PC | Right | |
to refresh the screen in +--------+--------+--------+--------+
screen mode. | | | Select | |
| Exam | Move | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
EXPAND
Keypad definitions in the +--------+--------+--------+--------+
EXPAND state when you do not | | Help | Set | |
use a color key. | GOLD | Keypad | Mode | BLUE |
| | Expand | Screen | |
For more keypad help, see +--------+--------+--------+--------+
the following topics: | Src LH1| | | Disp |
|Inst RH1| Expand | Disp | next |
KEYPAD BLUE | Out S45| Up | next | S12345 |
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | | Exam | | |
| Expand | Source | Expand | Go |
Ctrl/W does Display/Refresh | Left | .0\%PC | Right | |
to refresh the screen in +--------+--------+--------+--------+
screen mode. | | | Select | |
| Exam | Expand | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
CONTRACT
Keypad definitions in the +--------+--------+--------+--------+
CONTRACT state when you do not | | Help | Set | |
use a color key. | GOLD | Keypad | Mode | BLUE |
| |Contract| Screen | |
For more keypad help, see +--------+--------+--------+--------+
the following topics: | Src LH1| Expand | | Disp |
|Inst RH1| Up= | Disp | next |
KEYPAD BLUE | Out S45| -1 | next | S12345 |
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | Expand | Exam | Expand | |
| Left= | Source | Right= | Go |
Ctrl/W does Display/Refresh | -1 | .0\%PC | -1 | |
to refresh the screen in +--------+--------+--------+--------+
screen mode. | | Expand | Select | |
| Exam | Down= | Scroll | E |
| | -1 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
MOVE_GOLD
Keypad definitions in the +--------+--------+--------+--------+
MOVE state when you press | | Help |Set Mode| |
the GOLD key first. | GOLD | Keypad | No | BLUE |
| |MoveGold| Screen | |
Reset cancels the GOLD key. +--------+--------+--------+--------+
|Inst LH1| Move | Set | |
For more keypad help, see | Reg RH1| Up= | Process| |
the following topics: | Out S45| 999 | next | |
+--------+--------+--------+--------+
KEYPAD BLUE | Move | | Move | Select |
KEYPAD DEFAULT | Left= | Show | Right= | Source |
KEYPAD STATE_KEYS | 999 | Calls | 999 | next |
+--------+--------+--------+--------+
Ctrl/W does Display/Refresh | Exam | Move | Select | |
to refresh the screen in | prev | Down= | Output | E |
screen mode. | | 999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
EXPAND_GOLD
Keypad definitions in the +--------+--------+--------+--------+
EXPAND state when you press | | Help |Set Mode| |
the GOLD key first. | GOLD | Keypad | No | BLUE |
| |ExpaGold| Screen | |
Reset cancels the GOLD key. +--------+--------+--------+--------+
|Inst LH1| Expand | Set | |
For more keypad help, see | Reg RH1| Up= | Process| |
the following topics: | Out S45| 999 | next | |
+--------+--------+--------+--------+
KEYPAD BLUE | Expand | | Expand | Select |
KEYPAD DEFAULT | Left= | Show | Right= | Source |
KEYPAD STATE_KEYS | 999 | Calls | 999 | next |
+--------+--------+--------+--------+
Ctrl/W does Display/Refresh | Exam | Expand | Select | |
to refresh the screen in | prev | Down= | Output | E |
screen mode. | | 999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
CONTRACT_GOLD
Keypad definitions in the +--------+--------+--------+--------+
CONTRACT state when you press | | Help |Set Mode| |
the GOLD key first. | GOLD | Keypad | No | BLUE |
| |CntrGold| Screen | |
Reset cancels the GOLD key. +--------+--------+--------+--------+
|Inst LH1| Expand | Set | |
For more keypad help, see | Reg RH1| Up= | Process| |
the following topics: | Out S45| -999 | next | |
+--------+--------+--------+--------+
KEYPAD BLUE | Expand | | Expand | Select |
KEYPAD DEFAULT | Left= | Show | Right= | Source |
KEYPAD STATE_KEYS | -999 | Calls | -999 | next |
+--------+--------+--------+--------+
Ctrl/W does Display/Refresh | Exam | Expand | Select | |
to refresh the screen in | prev | Down= | Output | E |
screen mode. | | -999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
MOVE_BLUE
Keypad definitions in the +--------+--------+--------+--------+
MOVE state when you press | | Help | | |
the BLUE key first. | GOLD | Keypad | Disp | BLUE |
| |MoveBlue| Gener | |
Reset cancels the BLUE key. +--------+--------+--------+--------+
|2 SRC Qn| | 2 SRC | Disp |
For more keypad help, see | 2 INST | Move | at | Src H1 |
the following topics: | at RQn | Up=5 | Q1,Q2 | Out S45|
+--------+--------+--------+--------+
KEYPAD DEFAULT | | Show | | Select |
KEYPAD GOLD | Move | Calls | Move | Inst |
KEYPAD STATE_KEYS | Left=10| 3 |Right=10| next |
+--------+--------+--------+--------+
Ctrl/W does Display/Refresh |3 SRC Sn| | 3 SRC | |
to refresh the screen in | 3 INST | Move | at | E |
screen mode. | at RSn | Down=5 |S1,S2,S3| N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
EXPAND_BLUE
Keypad definitions in the +--------+--------+--------+--------+
EXPAND state when you press | | Help | | |
the BLUE key first. | GOLD | Keypad | Disp | BLUE |
| |ExpaBlue| Gener | |
Reset cancels the BLUE key. +--------+--------+--------+--------+
|2 SRC Qn| | 2 SRC | Disp |
For more keypad help, see | 2 INST | Expand | at | Src H1 |
the following topics: | at RQn | Up=5 | Q1,Q2 | Out S45|
+--------+--------+--------+--------+
KEYPAD DEFAULT | | Show | | Select |
KEYPAD GOLD | Expand | Calls | Expand | Inst |
KEYPAD STATE_KEYS | Left=10| 3 |Right=10| next |
+--------+--------+--------+--------+
Ctrl/W does Display/Refresh |3 SRC Sn| | 3 SRC | |
to refresh the screen in | 3 INST | Expand | at | E |
screen mode. | at RSn | Down=5 |S1,S2,S3| N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
CONTRACT_BLUE
Keypad definitions in the +--------+--------+--------+--------+
CONTRACT state when you press | | Help | | |
the BLUE key first. | GOLD | Keypad | Disp | BLUE |
| |CntrBlue| Gener | |
Reset cancels the BLUE key. +--------+--------+--------+--------+
|2 SRC Qn| Expand | 2 SRC | Disp |
For more keypad help, see | 2 INST | Up= | at | Src H1 |
the following topics: | at RQn | -5 | Q1,Q2 | Out S45|
+--------+--------+--------+--------+
KEYPAD DEFAULT | Expand | Show | Expand | Select |
KEYPAD GOLD | Left= | Calls | Right= | Inst |
KEYPAD STATE_KEYS | -10 | 3 | -10 | next |
+--------+--------+--------+--------+
Ctrl/W does Display/Refresh |3 SRC Sn| Expand | 3 SRC | |
to refresh the screen in | 3 INST | Down= | at | E |
screen mode. | at RSn | -5 |S1,S2,S3| N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
State Keys
You can use the four scrolling keys (KP8, KP2, KP4, and KP6) to
expand, contract, and move displays. Just as they can do a
SCROLL/UP, /DOWN, /LEFT, or /RIGHT, they can now do a MOVE/UP,
and so on. The GOLD key can be used to cause the operation to
advance more than one line or column. The commands apply to the
current scrolling display. You can use the KP3 key to select
the current scrolling display from the display circular list.
Four keys on the LK201 keyboard facilitate this. They put the
numeric keypad in one of the following four states:
DEFAULT MOVE EXPAND CONTRACT
The state changes the definition of the keys KP8, KP2, KP4, and
KP6. The meaning of all other keys remains unchanged.
For example, in the MOVE state (F18), pressing KP2 causes the
default scrolling display to move down by one character
position. Pressing GOLD-KP2 moves the display down by a larger
increment. The keypad remains in the MOVE state until another
state, such as the DEFAULT state (F17), is selected. This
restores the definition of the SCROLL operation.
If you do not have an LK201 keyboard with the F17--F20 keys on
it, you can get the same effect by typing the corresponding
commands:
Commands Keys
----------------------------------------------------------------
F17 F18 F19 F20
SET KEY/STATE=DEFAULT or +--------+--------+--------+--------+
SET KEY/STATE=MOVE | | | | |
SET KEY/STATE=EXPAND | DEFAULT| MOVE | EXPAND |CONTRACT|
SET KEY/STATE=CONTRACT | | | | |
+--------+--------+--------+--------+
Summary
Summary of debugger key +--------+--------+--------+--------+
definitions. | | | | |
| GOLD | Help | Screen | BLUE |
For more keypad help, see | | | Mode | |
the following topics: +--------+--------+--------+--------+
| Select | | | Disp |
KEYPAD BLUE | Screen | Up | Disp | next |
KEYPAD DEFAULT | Layout | | next | at FS |
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | | | | |
| Left | Where | Right | Go |
Ctrl/W does Display/Refresh | | am I? | | |
to refresh the screen in +--------+--------+--------+--------+
screen mode. | | | | |
| Exam | Down | Select | E |
| | | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
Language Support
You can use the debugger with the following VAX languages:
Ada BASIC BLISS C COBOL DIBOL
FORTRAN MACRO-32 Pascal PL/I RPG II SCAN
The debugger recognizes the syntax, data typing, and scoping
rules of a given language.
The debugger also recognizes the operators and expression syntax
of a given language. Therefore, you can compute the value of a
source-language expression using the syntax of the currently set
language.
The additional topics provide the following information for each
language:
o Supported operators in language expressions
o Supported constructs in language expressions and address
expressions
o Supported data types
o Any other language-specific features (for example, event
keywords in the case of Ada and SCAN)
o Restrictions in debugger support, if any
For more information about language-specific debugger support,
see the documentation for the particular language.
If your program is written in more than one language, you can
use the SET LANGUAGE command to change the debugging context
from one language to another during a debugging session.
When debugging a program written in an unsupported language, you
can set the language to UNKNOWN. To maximize the usability of
the debugger with unsupported languages, this setting causes the
debugger to accept a large set of data formats and operators,
including some that might be specific to only a few supported
languages. For information about the operators and constructs
that are recognized when the language is set to UNKNOWN, see
help on Language_Support UNKNOWN.
Additional information available:
BASICBLISSCCCOBOLDIBOLFORTRANMACRO
PLIRPGSCANUNKNOWN
Ada
The debugger completely supports the Ada language. It knows
about Ada names, operators, and data types when evaluating
expressions in an EXAMINE or EVALUATE command. It knows about
Ada packages, with clauses, and use clauses, and follows Ada
scoping rules when looking up symbols. There are a large number
of special-purpose commands to support debugging of Ada tasking
programs and Ada exception events.
Additional information available:
Data TypesEventsExceptionsTaskingOperatorsNamesPredefined Symbols
OverloadingPackagesSubunitsTick OperatorsRestrictions
Data Types
Supported Ada data types:
Integer Float
Fixed Enumeration
Arrays Records
Pointers Tasks
Events
The debugger lers you set breakpoints and tracepoints (known
generically as eventpoints) on certain types of events occurring
during the execution of your program which are defined and
detected by the Ada RTL. These events would otherwise be very
difficult (or impossible) for you to set a breakpoint on.
They fall into two broad categories: exception events and task
events. Exception events let you break or trace on any
exception that is about to be handled by an Ada exception
handler. They are applicable to any Ada program. Task events
deal specifically with tasking programs. They let you break or
trace on task scheduling, termination, and other state
transitions.
Additional information available:
CommandsEvent ParametersExamples
Commands
To tell debugger to use the Ada RTL as the event detection
facility for succeeding commands, use the SET EVENT_FACILITY ADA
command.
To see what the run time event facility is and what the defined
events are, use the SHOW EVENT_FACILITY command.
To set an eventpoint for the Ada RTL to detect, use the SET
BREAK/EVENT=keyword or SET TRACE/EVENT=keyword command.
To display the eventpoints you have set, use the SHOW BREAK or
SHOW TRACE command.
To remove the eventpoints use the CANCEL BREAK/EVENT=keyword or
CANCEL TRACE/EVENT=keyword command.
Event Parameters
Generally, the SET BREAK/EVENT and SET TRACE/EVENT commands can
take parameters which can be either address expressions or
language expressions. For Ada, the allowed parameters are task
names. Parameters are optional; omitting them implies a
wildcard as a parameter.
Examples
1. The following command initializes the debugger for Ada events:
DBG> SET EVENT_FACILITY ADA
2. The following command displays the defined event names:
DBG> SHOW EVENT_FACILITY
event facility is ADA
ADA event names and definitions:
...
3. The following command sets a breakpoint that is triggered
whenever any exception is handled by an Ada exception handler:
DBG> SET BREAK/EVENT=HANDLED
DBG> GO
...
break on ADA event HANDLED in %TASK 1
task %TASK 1 is about to handle an exception
the ADA exception handler is at: SCREEN_IO.%LINE 36
%ADA, Exception was copied at a "raise" or "accept".
Error PC=0000F60B
-ADA, Exception BAD_INPUT
-ADA, Exception raised prior to PC=00000670
4. In the following example, you set two tracepoints that are
triggered when either task GAMMA or %TASK 1 makes a transition
to the RUN state. When the event is triggered, the debugger
displays information about all tasks in the program.
DBG> SET TRACE/EVENT=RUN GAMMA, %TASK 1 DO (SHOW TASK/ALL)
DBG> GO
trace on ADA event RUN in %TASK 1
task %TASK 1 is about to run
task id pri hold state substate task object
* %TASK 1 7 RUN 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
%TASK 4 7 READY SAMPLE.GAMMA
%TASK 5 7 READY SAMPLE.DELTA
trace on ADA event RUN in %TASK 4
task %TASK 4 is about to run
task id pri hold state substate task object
%TASK 1 7 SUSP Dependents 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
* %TASK 4 7 RUN SAMPLE.GAMMA
%TASK 5 7 READY SAMPLE.DELTA
5. The following command sets a breakpoint that is triggered
whenever any task enters the TERMINATED state. When the event
is triggered, displays information about all tasks in the
program.
DBG> SET BREAK/EVENT=TERMINATED DO (SHOW TASK/ALL)
DBG> GO
break on ADA event TERMINATED in %TASK 5
task %TASK 5 is terminating normally.
task id pri hold state substate task object
%TASK 1 7 READY 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
%TASK 4 7 READY SAMPLE.GAMMA
* %TASK 5 7 RUN Terminated SAMPLE.DELTA
DBG> GO
break on ADA event TERMINATED in %TASK 4
task %TASK 4 is terminating normally.
task id pri hold state substate task object
%TASK 1 7 READY 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
* %TASK 4 7 RUN Terminated SAMPLE.GAMMA
%TASK 5 7 TERM Terminated SAMPLE.DELTA
Exceptions
The debugger has built-in symbols that provide information about
the current exception.
For information about Ada-specific exceptions, see help on
Language_Support Ada Events.
For non-Ada-specific exceptions, see help on Built_in_Symbols
%EXC
Tasking
The debugger has several commands to help you debug Ada tasking
programs:
SHOW TASK Observe the state of the tasking system.
SET TASK Alter the state of the tasking system.
SET BREAK/EVENT Set breakpoints or tracepoints on task
SET TRACE/EVENT events of interest to you.
For more information, see help on these commands. Also, see
help on the support for task events described under Language Ada
Events.
Operators
Supported Ada operators in expressions:
Kind Symbol Function
----------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix MOD Modulus
Infix REM Remainder
Infix ** Exponentiation
Prefix ABS Absolute value
Infix & Concatenation
Infix = Equal to
Infix /= Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Infix XOR Logical Exclusive OR
Names
Supported constructs for Ada names:
Symbol Construct
-----------------------------------
( ) Subscripting
. Record component selection
.ALL Pointer dereferencing
Predefined Symbols
Supported predefined symbols for Ada:
Symbol Meaning
---------------------
TRUE Boolean True
FALSE Boolean False
null Null access value
Overloading
If a function F is overloaded, the debugger invents names of the
form F_1, F_2, and so on, to refer to the individual instances
of the overloaded function. You can find out about these names
as follows:
DBG> SET BREAK F
%DEBUG-W-NOUNIQUE, F is not unique due to overloading
DBG> SHOW SYMBOL F
Overloaded function F
Overloaded instance F_1
Overloaded instance F_2
DBG> SET BREAK F_1
The SEARCH and EXAMINE/SOURCE commands may also be useful in
locating the source associated with the definitions of F.
Packages
The debugger knows about Ada packages, and follows Ada scoping
rules (that is, takes into account WITH and USE clauses) when
looking up symbols.
Library packages are treated as modules that can be set and
canceled individually. If the library package has a spec and a
body then each has its own module. If the package name is P,
the module for the package body has the name P, while the module
with the package spec gets the name P_. Set the module P_ to
make visible the names declared in the spec. Set the module P
to make visible the names local to the body. The debugger
sometimes sets package spec modules for you to be able to
correctly follow Ada's scoping rules during symbol lookup. For
more information, see help on the SET MODULE/RELATED command.
Example:
package P is
...
end P;
package body P is
...
end P;
with P;
procedure M is
...
end M;
DBG> SHOW MODULE
module name symbols
M no
P no
P_ no
DBG> SET MODULE M
module name symbols
M yes
P no
P_ yes
Subunits
The debugger knows about Ada subunits. A subunit is treated as
a debugger module. If S is a subunit of M, then the module
containing S has the invented name M_S. It has a special
relationship with the parent module M: if you set the subunit
module M_S, the debugger also sets the parent module M. This
makes visible symbols that are up-level referenced.
Example:
procedure M is
...
procedure S is separate;
...
end M;
separate(M);
procedure S is
begin
...
end;
DBG> SHOW MODULE
module name symbols
M no
M_S no
DBG> SET MODULE S
DBG> SHOW MODULE
module name symbols
M yes
M_S no
Tick Operators
Supported Ada "tick operators":
'CONSTRAINED
'FIRST
'LAST
'LENGTH
'POS
'PRED
'SIZE
'SUCC
'VAL
Example:
DBG> EVALUATE DAY'SUCC(MONDAY)
TUESDAY
Restrictions
Restrictions in debugger support for Ada are as follows:
o With certain Ada record variables, the debugger fails to show
the record components correctly (possibly with a NOACCESSR
error message) when the type declaration is in a different
scope than the record (symbol) declaration.
o You cannot examine Ada objects requiring extended descriptor
DSTs (debug-symbol-table records) to describe them. These
objects are typically accessed arrays whose size is greater
than 65535 bytes.
BASIC
Debugger support for language BASIC
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported BASIC operators in language expressions:
Kind Symbol Function
-----------------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition, String concatenation
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix ^ Exponentiation
Infix = Equal to
Infix <> Not equal to
Infix >< Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix => Greater than or equal to
Infix < Less than
Infix >= Less than or equal to
Infix => Less than or equal to
Prefix NOT Bit-wise NOT
Infix AND Bit-wise AND
Infix OR Bit-wise OR
Infix XOR Bit-wise exclusive OR
Infix IMP Bit-wise implication
Infix EQV Bit-wise equivalence
Expressions
Supported constructs in language and address expressions for
BASIC:
Symbol Construct
------------------------------------
( ) Subscripting
:: Record component selection
Data Types
Supported BASIC data types:
BYTE HFLOAT
WORD DECIMAL
LONG STRING
SINGLE RFA
DOUBLE Arrays
GFLOAT Records
Notes
Expressions that overflow in the BASIC language do not
necessarily overflow when evaluated by the debugger. The
debugger tries to compute a numerically correct result, even
when the BASIC rules call for overflows. This difference is
particularly likely to affect DECIMAL computations.
BASIC constants of the forms [radix]"numeric-string"[type] (such
as "12.34"GFLOAT) or n% (such as 25% for integer 25) are not
supported in debugger expressions.
BLISS
Debugger support for language BLISS
Additional information available:
OperatorsExpressionsData Types
Operators
Supported BLISS operators in language expressions:
Kind Symbol Function
----------------------------------------
Prefix . Indirection
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix MOD Remainder
Infix ^ Left shift
Infix EQL Equal to
Infix EQLU Equal to
Infix EQLA Equal to
Infix NEQ Not equal to
Infix NEQU Not equal to
Infix NEQA Not equal to
Infix GTR Greater than
Infix GTRU Greater than unsigned
Infix GTRA Greater than unsigned
Infix GEQ Greater than or equal to
Infix GEQU Greater than or equal to unsigned
Infix GEQA Greater than or equal to unsigned
Infix LSS Less than
Infix LSSU Less than unsigned
Infix LSSA Less than unsigned
Infix LEQ Less than or equal to
Infix LEQU Less than or equal to unsigned
Infix LEQA Less than or equal to unsigned
Prefix NOT Bit-wise NOT
Infix AND Bit-wise AND
Infix OR Bit-wise OR
Infix XOR Bit-wise exclusive OR
Infix EQV Bit-wise equivalence
Expressions
Supported constructs in language and address expressions for
BLISS:
Symbol Construct
-------------------------------
[ ] Subscripting
[fldname] Field selection
<p,s,e> Bit field selection
Data Types
Supported BLISS data types:
BYTE BITVECTOR
WORD BLOCK
LONG BLOCKVECTOR
BYTE UNSIGNED REF VECTOR
WORD UNSIGNED REF BITVECTOR
LONG UNSIGNED REF BLOCK
VECTOR REF BLOCKVECTOR
CC
Debugger support for language C
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported C operators in language expressions:
Kind Symbol Function
-----------------------------
Prefix * Indirection
Prefix & Address of
Prefix SIZEOF Size of
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix % Remainder
Infix << Left shift
Infix >> Right shift
Infix == Equal to
Infix != Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix ~ Bit-wise NOT
Infix & Bit-wise AND
Infix | Bit-wise OR
Infix ^ Bit-wise exclusive OR
Prefix ! Logical NOT
Infix && Logical AND
Infix || Logical OR
Expressions
Supported constructs in language and address expressions for C:
Symbol Construct
---------------------------------------
[ ] Subscripting
. Structure component selection
-> Pointer dereferencing
Data Types
Supported C data types:
int double
short int enum
unsigned int struct
unsigned short int union
char Pointer type
unsigned char Array type
float
Notes
Symbol names are case-sensitive for the C language, meaning that
uppercase and lowercase letters are treated as different
characters.
Since the exclamation point (!) is an operator in C, it cannot
be used as the comment delimiter. When the language is set to
C, the debugger instead accepts /* as the comment delimiter.
The comment continues to the end of the current line. (A
matching */ is neither needed nor recognized.) To permit
debugger log files to be used as debugger input, the debugger
still recognizes ! as a comment delimiter if it is the first
non-blank character on a line.
The debugger accepts the prefix asterisk (*) as an indirection
operator in both C language expressions and debugger address
expressions. In address expressions, prefix * (asterisk) is
synonymous with prefix . (period) or @ (at sign) when the
language is set to C.
The debugger does not support any of the assignment operators in
C (or any other language) to prevent unintended changes to the
program being debugged. Therefore, such operators as =, +=, -=,
++, and -- are not recognized. If you wish to alter the
contents of a memory location, you must do so with an explicit
DEPOSIT command.
COBOL
Debugger support for language COBOL
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported COBOL operators in language expressions:
Kind Symbol Function
--------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix = Equal to
Infix NOT = Not equal to
Infix > Greater than
Infix NOT < Greater than or equal to
Infix < Less than
Infix NOT > Less than or equal to
Infix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Expressions
Supported constructs in language and address expressions for
COBOL:
Symbol Construct
------------------------------------
( ) Subscripting
OF Record component selection
IN Record component selection
Data Types
Supported COBOL data types:
COMP Records
COMP-1 Numeric Unsigned
COMP-2 Leading Separate Sign
COMP-3 Leading Overpunched Sign
INDEX Trailing Separate Sign
Alphanumeric Trailing Overpunched Sign
Notes
The debugger can show source text included in a program with the
COPY or COPY REPLACING verb. However, when COPY REPLACING is
used, the debugger always shows the original source text as it
appeared before text replacement. In other words, the original
source file is shown instead of the modified source text
generated by the COPY REPLACING verb.
The debugger cannot show the original source lines associated
with the code for a REPORT section. You can see the DATA
SECTION source lines associated with a REPORT, but no source
lines are associated with the compiled code that generates the
report.
VAX COBOL may use quadword, longword, or word to represent a
COMP data type.
DIBOL
Debugger support for language DIBOL
Additional information available:
OperatorsExpressionsData Types
Operators
Supported DIBOL operators in language expressions:
Kind Symbol Function
----------------------------------------
Prefix # Round
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix // Division with fractional result
Infix .EQ. Equal to
Infix .NE. Not equal to
Infix .GT. Greater than
Infix .GE. Greater than or equal to
Infix .LT. Less than
Infix .LE. Less than or equal to
Prefix .NOT. Logical NOT
Infix .AND. Logical AND
Infix .OR. Logical OR
Infix .XOR. Exclusive OR
Expressions
Supported constructs in language and address expressions for
DIBOL:
Symbol Construct
------------------------------------
( ) Substring
[ ] Subscripting
. Record component selection
Data Types
Supported DIBOL data types:
Byte integer (I1)
Word integer (I2)
Long integer (I4)
Packed decimal (Pn)
Implied packed decimal (Pn.m)
Zoned decimal (Dn)
Implied zoned decimal (Dn.m)
ASCII (An)
Arrays
Records
FORTRAN
Debugger support for language FORTRAN
Additional information available:
OperatorsExpressionsPredefined SymbolsData TypesNotes
Operators
Supported FORTRAN operators in language expressions:
Kind Symbol Function
----------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix // Concatenation
Infix .EQ. Equal to
Infix .NE. Not equal to
Infix .GT. Greater than
Infix .GE. Greater than or equal to
Infix .LT. Less than
Infix .LE. Less than or equal to
Prefix .NOT. Logical NOT
Infix .AND. Logical AND
Infix .OR. Logical OR
Infix .XOR. Exclusive OR
Infix .EQV. Equivalence
Infix .NEQV. Exclusive OR
Expressions
Supported constructs in language and address expressions for
FORTRAN:
Symbol Construct
------------------------------------
( ) Subscripting
. Record component selection
Predefined Symbols
Supported FORTRAN predefined symbols:
Symbol Meaning
-------------------------
.TRUE. Logical True
.FALSE. Logical False
Data Types
Supported FORTRAN data types:
LOGICAL*1 REAL*4 CHARACTER
LOGICAL*2 REAL*8 Records
LOGICAL*4 REAL*16 Arrays
INTEGER*2 COMPLEX*8
INTEGER*4 COMPLEX*16
Notes
Even though the VAX type codes for unsigned integers (BU, WU,
LU) are used internally to describe the LOGICAL data types, the
debugger (like the compiler) treats LOGICAL variables and values
as being signed when used in language expressions.
The debugger prints the numeric values of LOGICAL variables or
expressions instead of TRUE or FALSE. Normally, only the
low-order bit of a LOGICAL variable or value is significant (0
is FALSE and 1 is TRUE). However, VAX FORTRAN does allow all
bits in a LOGICAL value to be manipulated and LOGICAL values can
be used in integer expressions. For this reason, it is at times
necessary to see the entire integer value of a LOGICAL variable
or expression, and that is what the debugger shows.
COMPLEX constants such as (1.0,2.0) are not supported in
debugger expressions.
Floating point numbers of type REAL*8 and COMPLEX*16 may be
represented by D_Floating or G_Floating depending on compiler
switches.
MACRO
Debugger Support for language MACRO
Additional information available:
OperatorsExpressionsData Types
Operators
The MACRO language does not have expressions in the same sense
as high-level languages. Only assembly-time expressions and
only a limited set of operators are accepted. To permit the
MACRO programmer to use expressions at debug-time as freely as
in other languages, the debugger accepts a number of operators
in MACRO language expressions that are not found in MACRO
itself. In particular, the debugger accepts a complete set of
comparison and boolean operators modeled after BLISS. It also
accepts the indirection operator and the normal arithmetic
operators.
Kind Symbol Function
----------------------------------------
Prefix @ Indirection
Prefix . Indirection
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix MOD Remainder
Infix @ Left shift
Infix EQL Equal to
Infix EQLU Equal to
Infix NEQ Not equal to
Infix NEQU Not equal to
Infix GTR Greater than
Infix GTRU Greater than unsigned
Infix GEQ Greater than or equal to
Infix GEQU Greater than or equal to unsigned
Infix LSS Less than
Infix LSSU Less than unsigned
Infix LEQ Less than or equal to
Infix LEQU Less than or equal to unsigned
Prefix NOT Bit-wise NOT
Infix AND Bit-wise AND
Infix OR Bit-wise OR
Infix XOR Bit-wise exclusive OR
Infix EQV Bit-wise equivalence
Expressions
Supported constructs in language and address expressions for
MACRO:
Symbol Construct
-----------------------------------------
<p,s,e> Bit field selection as in BLISS
[ ] Subscripting
The DST information generated by the MACRO assembler treats a
label followed by an assembler directive for storage allocation
as an array variable whose name is the label. This lets you use
the array syntax of a high-level language when examining or
manipulating such data.
In the following example of MACRO source code, the label LAB4
designates hexadecimal data stored in four words:
LAB4: .WORD ^X3F,5[2],^X3C
The debugger treats LAB4 as an array variable. For example, the
following command displays the value stored in each element
(word):
DBG> EXAMINE LAB4
.MAIN.\MAIN\LAB4
[0]: 003F
[1]: 0005
[2]: 0005
[3]: 003C
The following command displays the value stored in the fourth
word (the first word is indexed as element 0):
DBG> EXAMINE LAB4[3]
.MAIN.\MAIN\LAB4[3]: 03C
Data Types
Supported MACRO data types:
Byte Unsigned (BU)
Word Unsigned (WU)
Longword Unsigned (LU)
Byte Integer (B)
Word Integer (W)
Longword Integer (L)
Pascal
Debugger support for language Pascal
Additional information available:
OperatorsExpressionsPredefined SymbolsData TypesNotesRestrictions
Operators
Supported Pascal operators in language expressions:
Kind Symbol Function
----------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition, concatenation
Infix - Subtraction
Infix * Multiplication
Infix / Real division
Infix DIV Integer division
Infix MOD Modulus
Infix REM Remainder
Infix ** Exponentiation
Infix IN Set membership
Infix = Equal to
Infix <> Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Expressions
Supported constructs in language and address expressions for
Pascal:
Symbol Construct
----------------------------------
[ ] Subscripting
. Record component selection
^ Pointer dereferencing
Predefined Symbols
Supported Pascal predefined symbols and functions:
Symbol Meaning
----------------------
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
Data Types
Supported Pascal data types:
INTEGER CHAR Subranges
UNSIGNED VARYING Typed
SINGLE SET Arrays
DOUBLE FILE Records
QUADRUPLE Enumerations Variant
BOOLEAN
Notes
The debugger accepts Pascal set constants such as [1,2,5,8..10]
or [RED, BLUE] in Pascal language expressions.
VAX PASCAL may use longword, word, or byte to represent INTEGER
or UNSIGNED data types. DOUBLE precision floating point numbers
may be represented by D_Floating or G_Floating depending on
compiler switches.
Restrictions
Restrictions in debugger support for Pascal are as follows:
You cannot examine the .LENGTH and .BODY fields of a Pascal
varying string variable using the normal language syntax. For
example, if VARS is the name of a string variable, the following
commands are not supported:
DBG> EXAMINE VARS.LENGTH
DBG> EXAMINE VARS.BODY
To examine these fields, use the techniques shown in the
following examples:
Use Instead of
------------------------------------------
EXAMINE/WORD VARS EXAMINE VARS.LENGTH
EXAMINE/ASCII VARS+2 EXAMINE VARS.BODY
PLI
Debugger support for language PL/I
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported PL/I operators in language expressions:
Kind Symbol Function
----------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix || Concatenation
Infix = Equal to
Infix ^= Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix ^< Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Infix ^> Less than or equal to
Prefix ^ Bit-wise NOT
Infix & Bit-wise AND
Infix | Bit-wise OR
Expressions
Supported constructs in language and address expressions for
PL/I:
Symbol Construct
-------------------------------------
( ) Subscripting
. Structure component selection
-> Pointer dereferencing
Data Types
Supported PL/I data types:
FIXED BINARY CHARACTER VARYING
FIXED DECIMAL FILE
FLOAT BINARY Labels
FLOAT DECIMAL Pointers
BIT Arrays
CHARACTER Structures
Notes
The debugger treats all numeric constants of the form n or n.n
in PL/I language expressions as packed decimal constants, not
integer or floating-point constants, to conform to PL/I language
rules. The internal representation of 10 is therefore 0C01
hexadecimal, not 0A hexadecimal. You can enter floating-point
constants using the syntax nEn or n.nEn. There is no PL/I
syntax for entering constants whose internal representation is
Longword Integer. This limitation is not normally significant
when debugging since the debugger supports the PL/I type
conversion rules. However, it is possible to enter integer
constants by using the debugger's %HEX, %OCT, and %BIN
operators.
VAX PL/I may use F_Floating, D_Floating, G_Floating, or
H_Floating to represent FLOAT BINARY or FLOAT DECIMAL data types
depending on compiler switches.
RPG
Debugger support for language RPG
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported RPG operators in language expressions:
Kind Symbol Function
----------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix = Equal to
Infix NOT = Not equal to
Infix > Greater than
Infix NOT < Greater than or equal to
Infix < Less than
Infix NOT > Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Expressions
Supported constructs in language and address expressions for
RPG:
Symbol Construct
---------------------
( ) Subscripting
Data Types
Supported RPG data types:
Longword
Word
Packed Decimal
Character
Overpunched Decimal
Arrays
Tables
Notes
The debugger supports access to all RPG indicators and labels
used in the current program. You can thus examine labels such
as *DETL and indicators such as *INLR and *IN01 through *IN99.
SCAN
Debugger support for language SCAN
Additional information available:
EventsOperatorsExpressionsPredefined SymbolsData Types
Events
The debugger lets you set breakpoints and tracepoints (known
generically as eventpoints) on certain types of events occurring
during the execution of your program which are defined and
detected by the SCAN RTL.
SCAN defines several events. By setting breaks or traces on
these events, you can observe the picture matching process. To
see what the defined events are for SCAN, use the SHOW EVENTS
command.
To set an eventpoint for the SCAN RTL to detect, use the SET
BREAK/EVENT=keyword or SET TRACE/EVENT=keyword command.
To display the eventpoints you have set, use the SHOW BREAK or
SHOW TRACE command.
To remove the eventpoints use CANCEL BREAK/EVENT=keyword or
CANCEL TRACE/EVENT=keyword command.
Where keyword is one of the defined events listed by the SHOW
EVENTS command. SCAN events may be abbreviated to 3 or more
characters.
Additional information available:
Examples
1. The following example sets two tracepoints that are triggered
when a SCAN Trigger or Syntax Macro is activated, and sets a
break point that is triggered whenever a SCAN token is built:
DBG> SET TRACE/EVENT=TRIGGER
DBG> SET TRACE/EVENT=SYNTAX
DBG> SET BREAK/EVENT=TOKEN
2. The following example shows the output from the program
execution after setting the eventpoints in the preceding
example:
DBG> GO
trace on event TRIGGER_MACRO
Trigger Macro EXPRESSION_TEST\PRINT_STMT Activated
break on event TOKEN
Token built: PRINT Triggerable Length:5 Line:1 Column:1
Token text: 'print'
DBG> GO
trace on event SYNTAX_MACRO
Syntax Macro EXPRESSION_TEST\EXP Activated
Operators
Supported operators in language expressions for SCAN:
Kind Symbol Function
--------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix & Concatenation
Infix = Equals
Infix <> Not equals
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix NOT Complement
Infix AND Intersection
Infix OR Union
Infix XOR Exclusive OR
Expressions
Supported constructs in language and address expressions for
SCAN:
Symbol Construct
----------------------------------
( ) Subscripting
. Record component selection
-> Pointer dereferencing
Predefined Symbols
Supported predefined symbols for SCAN:
Symbol Meaning
--------------------
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
Data Types
Supported SCAN data types:
BOOLEAN TREE
INTEGER TREEPTR
POINTER RECORD
STRING OVERLAY
There is no specific support for the following datatypes: FILE,
TOKEN, GROUP, SET. Examining a FILL variable displays the
contents of the specified variable displayed as a string by
default, and so may have little meaning. If the characteristics
of the fill are known, the appropriate qualifier (/HEX...)
applied to the command produces a more meaningful display.
Examining SCAN TREE and TREEPTR variables:
1. To dump an entire SCAN tree or subtree:
EXAMINE tree_variable( [subscript],...)
2. To dump the contents of a SCAN treeptr:
EXAMINE treeptr_variable
3. To dump an entire SCAN subtree:
EXAMINE treeptr_variable->
DEPOSIT is not supported for SCAN TREE variables at this time.
You may set breakpoints on any SCAN label, line number, MACRO,
or PROCEDURE.
UNKNOWN
Debugger Support for language UNKNOWN
Additional information available:
OperatorsExpressionsPredefined SymbolsData TypesNotes
Operators
Supported Operators in language expressions for UNKNOWN:
Kind Symbol Function
----------------------------------------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix & Concatenation
Infix // Concatenation
Infix = Equal to
Infix <> Not equal to
Infix /= Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Infix EQL Equal to
Infix NEQ Not equal to
Infix GTR Greater than
Infix GEQ Greater than or equal to
Infix LSS Less than
Infix LEQ Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Infix XOR Exclusive OR
Infix EQV Equivalence
Expressions
Supported constructs in language and address expressions for
UNKNOWN:
Symbol Construct
----------------------------------
[ ] Subscripting
( ) Subscripting
. Record component selection
^ Pointer dereferencing
Predefined Symbols
Supported predefined symbols for UNKNOWN:
Symbol Meaning
--------------------
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
Data Types
Supported data types for UNKNOWN:
When the language is set to UNKNOWN, the debugger understands
all data types accepted by other languages except a few very
language-specific types, such a picture types and file types.
In UNKNOWN language expressions, the debugger accepts most
scalar VAX Standard data types.
Notes
For language UNKNOWN, the debugger accepts the dot-notation for
record component selection. If C is a component of a record B
which in turn is a component of a record A, C can be referenced
as A.B.C. Subscripts can be attached to any array components;
if B is an array, for instance, C may be referenced as
A.B[2,3].C.
For language UNKNOWN, the debugger accepts both round and square
subscript parentheses. Thus, A[2,3] and A(2,3) are equivalent.
Logical Names
Logical name To define...
---------------------------------------------------------
DBG$INIT An initialization file used when you
invoke the debugger.
DBG$INPUT The debugger input device (default is
SYS$INPUT).
DBG$OUTPUT The debugger output device (default is
SYS$OUTPUT).
DBG$PROCESS The debugging configuration --- either
MULTIPROCESS or DEFAULT (single process).
DBG$DECW$DISPLAY The debugger command interface (either
DECwindows or command)
Additional information available:
DBG$INITDBG$INPUT_DBG$OUTPUTDBG$PROCESSDBG$DECW$DISPLAY
DBG$INIT
Defines an initialization file used when you invoke the
debugger. The commands in the file execute as if the file had
been called with the @ (execute procedure) command. This is
useful if there is a particular set of commands that you always
execute when you start up the debugger, for example to specify a
source directory search list, enable screen mode, log the
session, and so on.
Example:
$ CREATE DEBUG.COM
SET SOURCE [],SRC$
SET MODE SCREEN
SET STEP SILENT
$ DEFINE DBG$INIT [JONES.CMD]DEBUG_INIT.COM
DBG$INPUT_DBG$OUTPUT
Defines the debugger input device and output device respctively.
The defaults are SYS$INPUT and SYS$OUTPUT.
If you plan to debug a program that takes its input from a file
and your debugger input from the terminal, create the following
definitions before invoking the debugger:
$ DEFINE SYS$INPUT program-input-file
$ DEFINE/PROCESS DBG$INPUT 'F$LOGICAL("SYS$COMMAND")
That is, define DBG$INPUT to point to the translation of
SYS$COMMAND.
If you define DBG$INPUT to point to SYS$COMMAND, the debugger
will try to get its input from the file.
DBG$PROCESS
Determines the debugging configuration as follows:
DBG$PROCESS Configuration
-------------------------------------
Undefined or DEFAULT Default
MULTIPROCESS Multiprocess
Use the default configuration to debug programs that normally
run (without the debugger) in only one process. Use the
multiprocess configuration to debug programs that normally run
in more than one process.
When defining DBG$PROCESS for a multiprocess configuration, make
the definition job wide. This ensures that any processes that
are in the same job tree as the program being debugged (for
example, processes spawned by the program) can be controlled
from the same debugging session.
For more information, see help on Debugging_Configurations and
Multiprocess.
Additional information available:
Examples
1. $ DEFINE/JOB DBG$PROCESS MULTIPROCESS
$ RUN PROG1
...
DBG_1>
The DEFINE/JOB command specifies the multiprocess debugging
configuration. This is indicated by the process-specific prompt
suffix (_1) which is displayed initially when the debugger is
invoked with the RUN command. The prompt suffix indicates that
execution is suspended in process 1, the first process brought
under debugger control. Process 1 is currently the visible
process --- the context for executing process-specific commands
like STEP, EXAMINE, and so on.
2. $ DEFINE DBG$PROCESS DEFAULT
$ RUN PROG1
...
DBG>
The DEFINE command specifies the default debugging
configuration. This is indicated by the DBG> prompt, which is
displayed when the debugger is invoked with the RUN command.
DBG$DECW$DISPLAY
(Applies only to workstations running DECwindows.)
Specifies the debugger interface (DECwindows or command) or the
display device.
By default, DBG$DECW$DISPLAY is either undefined or has the same
definition as the application-wide logical name DECW$DISPLAY.
By default, the debugger displays the DECwindows interface on
workstations.
To display the command interface instead of the DECwindows
interface, enter the following definition before starting up the
debugger:
$ DEFINE DBG$DECW$DISPLAY " "
For more information, see the DECwindows-interface documentation
in the VMS Debugger Manual.
Messages
To get help about a debugger message, use the following general
command format:
DBG> HELP MESSAGES message-identifier
In this format, message-identifier is the keyword displayed to
the left of the message text.
The following information is provided for each message
identifier: message text, explanation, and user action. The
additional topics list all message identifiers alphabetically.
Additional information available:
ABORTEDABSDATSYNACCADDCOMACTIVATING
ADDRANCOVADDRESSMODEADDRMBZADDRREGAMBFIELD
AMBIGQUALAMPERSANDASTWASDISABLEDASTWASENABLED
ATTACHEDATTREQREFBADADDSPABADADDSTA
BADBODPACKBADDESCRBADDISCVALBADDSTBADEVNPAR
BADEXHBADFRAMEBADHANDLEBADOPCODEBADPARAM
BADSCOPEBADSIGARGBADSTACKBADSTARTPCBADSTATUS
BADSUBPARBADTAGVALBADTARGETBADUSEPACK
BADUSREVNTBADWATCHBADWIDGETBASVARNOTSET
BITRANGEBPTDIFMODBPTONDATABUFFEROVF
BWLGISMUSCANBRKWATCANTACCESSMAINCANTCREATEMAIN
CANTGETFIDCANTINTPROCANTOPNIMGCANTPAST
CIREXLSTCLIBRDFAICLIBRDLCKCMDISCORCMDISOBSCMDNOTDW
CMDNOTONECMDSYNERRCMPNOTFNDCNTRLWRDNOTACCESS
CONFLICTCONFROMEXCCONSTRCOMPCPOSTDECR
CPOSTINCRCPREDECRCPREINCRCRMPSCFAILCVTNEGUNS
DBGERRDBGSTOPPEDDECLARERRDECOVFDECROPRAND
DEFKEYDEFKEYERRDEFTOORECDELKEYDELKEYERR
DELTIMTOODESCNOTSETDISABLEASTDISNAMREQ
DISNOTSELDISPEXISTSDISPRLENSIZDIVBYZERO
DSTERRGDSTNESDEPDUPLVQUALDWERRDWNOT1PROC
DYNIMGSETDYNMODSETEDITDISVEREDITERROR
EDITFILEEDITNOFILEEDITREVVERENABLEAST
ENTRYMASKENUMRANGEERRACTIMGERRASSIGN
ERRCLSFILEERRCRELNMERRDEASSIGNERRFAO
ERRGETDVIERRGETEFERRINSDECERRINSIGNAL
ERRINVEDITERRORERRORLIMITERROR_BLOCK
ERRQIOWERRSMGERRSYSSERVERRTARGOPERRUSREVNT
EXABEYREGEXARANGEEXCBREREPEXCDURCAL
EXITARGEXITERREXITSTATUSEXPMEMPOOLFAILFINDIMG
FAILHEIRKYFAILXTINITFATALSTATUSFILEUNALFLTOVF
HEIGHTDIFFIDENTLONGIFIXUNDIFLTUNDIINTOVF
ILLADDCONILLASTERILLDEFNAMILLENUMVAL
ILLEVNSTRILLFILPTRILLFLOATILLINVNUMILLLENGTHILLNUMPATH
ILLPACSIZILLPATH1ILLPATH2ILLPATHELEMILLPATHIDENT
ILLPOSFLDILLQUALIFILLRANGEILLSETCONILLSIGEXTILLSIZFLDILLSUBLEN
ILLSUBSTRILLTYPEILLVQUALINCDSTNESINCOMPOPRINCOMPPTR
INCOMQUALINCOMTARGETINCOMVERSIONINDBASEQL
INITERRINITIALINPREADERRINSVIRMEMINTERR
INTERRUPTEDINTMEMERRINTOVFINTVECERR
INUMTRUNCINVARGLISINVARRDIMINVARRDSC
INVCHARINVCHRCONINVDESCINVDIGBININVDIGDECINVDIGHEX
INVDIGOCTINVDIRNAMINVDMTPTRINVDSPSIZ
INVDSTRECINVEXPRINVFIXDSTINVFLDREFINVGSTREC
INVGSTTYPINVMARINVNUMBERINVNUMSRC
INVNUMSTRINVOPADDRINVOPSYMINVPAGEINVPRCSYN
INVPRIORINVRANSPECINVSELDISINVSRCLININVTIMSLIINVWIDTH
INVWINPARIRFAOVFISTRTRUITMNOTAVAITMTRUNC
IVALNOFITIVALOUTBNDSIVPRCLOGKERFUNCNYIKEYNAMERR
KEYSTATERRLASTCHANCELINEINFOLOGFILEISLONGSTRING
LOOPINCRLOOPVARLOWBNDOPTMASKMISMATCHMASKNOTUSED
MASKNOTVMRMASKPARNREQMATQUOMISMISCLOSUB
MISINVNUMMISINVOPERMISMODBEGMISMODEND
MISOPEMISMODUSCOPEMOVED_1MOVED_2MOVED_3MOVED_4
MOVED_5MOVED_6MPARENREQMPCOMMANDNAMSTRMIS
NAMTOOLONGNEEDMORENEEDPARENNOACCESSR
NOACCESSWNOADDRREGNOALTERSPNOATTACH
NOBREAGGRNOBREAKATNOBREAKSNOCALLSNOCANMAIN
NOCLINOCONNECTNOCURLOCNODEFSCPENODELIMTR
NODEPDEBUGNODIRLISMNODIRLISTNOELABBODYNOELABSPEC
NOENDNOEPTSPECNOEVALEXPRNOEVENTFAC
NOEXCBRENOEXHNDNOFIELDNOFREENOGLOBALSNOHLPLIB
NOINPAVAILNOINPFOCNOINSTRANNOKEYDEFNOKEYPAD
NOLASTVALNOLINXXXNOLISTNOLOCALSNOMAINNOMARKCHNG
NOMATCHNOMORENONEXPRNONEXPRCNONUMSCOPENONXTLIN
NOOCCLDISPNOOUTAVAILNOPACKMEMBODYNOPACKMEMSPEC
NOPREDNOPROMPTNORECSYMNORMALNORSTBLDNOSAVPROG
NOSCOPENOSCOPELISTNOSCRDEVNOSCRMODENOSCROLL
NOSCROLLDISPNOSETTERMNOSPAWNNOSRCHSTR
NOSRCLINNOSTEPGONOSUCCNOSUCHBPTNOSUCHDISP
NOSUCHELPNOSUCHIMGNOSUCHMODUNOSUCHPACK
NOSUCHSCOPENOSUCHTASKNOSUCHTPTNOSUCHWIND
NOSUCHWPTNOSYMBOLNOSYMBOLRNOTADAPROG
NOTARRAYNOTASTRUCTNOTATMAINNOTCURPCNOTDECTHREADS
NOTDEFINENOTIMPLANNOTINLOOPNOTINSCOPE
NOTINSTNOTNUMSCOPENOTORIGSRCNOTPTRNOTRACES
NOTRAZERONOTRECORDNOTREENOTRUNDW
NOTTASKVALNOTUISOSCNOTUISV30NOTUNQOVR
NOTUPDATENOTYPEINFONOUNIQUENOUNIVERSALS
NOUSREVNTNOVALATPCNOVALTYPNOVALUENOVECT
NOWATCHESNOWATONOPTNOWATTARNOWATVARIA
NOWATVARSTGNOWBPTNOWILDNOWILDFILNOWOPCONOWPROT
NO_SYNC_FROM_EXC_BRENPROMPTNULLPTRNUMCONLONG
NUMTRUNCOBJECTINVOBJPTRINVOBJTYPMIS
OBSOLETE_1OBSOLETE_10OBSOLETE_11OBSOLETE_12
OBSOLETE_13OBSOLETE_14OBSOLETE_15OBSOLETE_16
OBSOLETE_17OBSOLETE_18OBSOLETE_19OBSOLETE_20
OBSOLETE_21OBSOLETE_22OBSOLETE_23OBSOLETE_24
OBSOLETE_25OBSOLETE_28OBSOLETE_29OBSOLETE_30
OBSOLETE_7OBSOLETE_8OBSOLETE_9OPCDEC
OPNOTALLOWOPSYNTAXOUTPUTLOSTPACSIZREQPARENREQ
PARSTKOVRPASTHRUPATHNOTACPPATHTLONG
PATHTOOLONGPCNOTALLPLICVTERRPREDEPTNOT
PROFRANOTPROMPTCLENPROMPTOCCLPROMPTRLEN
PROVRFLOWPSHINARYNYIPSHVALNYIPXCNQUALREQ
QUOSTRLONGREADERRREFUSEDREGMASKHIDDENREGMASKMISSING
REGREQRENAMENOTRESUMERRRETURNEDRNDFCTROUT
ROPRANDFRPCDBBDTRPCERRRPCINVDSCRPCOVFRPCUNF
RPCUNKARGRSTERRSCALEADDSCALESUBSCRNOACCESSR
SCRNOSRCLINSCRNOTORIGSRCSCRTOBIGSCRTOSMALL
SCRUNAOPNSRCSCRUNAREASRCSETKEYSETKEYERR
SFCNTNEGSHOKEYERRSHRPRCSIDEFFECTSIGVECTRUNC
SIZEATOMICSIZETRUNCSOURCESCOPESPAWNEDSRCLINNOT
SS_INTSTEPINTOSTGTRUNCSTRNGPADSTRTOOLONGSTRUCSIZE
SUBOUTBNDSUBSCRNGSUBSTRINGSUPERDEBUGSYMNOTACT
SYMNOTFNDSYNCDONESYNCREPCOMSYNC_ALREADY_IN_PROGRESS
SYNERREXPRSYNERRLABELSYNERRLINESYNTAX
TASKERRORTASKNONULLTASKNOREGSTASKNOTABORT
TASKNOTACTTASKNULLTERMINATINGTIMESLICETOOFEWSUB
TOOMANDIMTOOMANERRTOOMANINVTOOMANPARM
TOOMANSUBUNAACCREGUNACREDBGOUNACVT
UNACVTBYTTAUUNALIGNEDUNALLOCATEDUNAOPEDBGI
UNAOPESCRUNAOPNHLPUNAOPNINIUNAOPNSRC
UNAREASRCUNASAVVALUNASETIMGUNASETTAS
UNASWISTAUNBPARENUNDEXPNUNDKEYUNHANDLED
UNIMPLENTUNMTCHPARNUNREQVQUALUPBNDOPT
USREVNTERRVALNOTADDRVALRNGVARNESDEP
VECDISVECREASONVECSCP0VECTSUBRNGVERIFYICF
VERSIONNUMVFLTDIVVFLTOVFVFLTROPVFLTUNDWATCHSETUP
WATCHSIZEWATNOWCANWATNOWWATWATVARGSGONE
WATVARGSOVRWATVARNOWGBLWATVARPROTWATVARPTR
WATVARREMAPWATVARSCPWIDTHDIFFWORKSTACMD
WPTTRACEWRITE_FAILEDWRITE_INTO_KERNELWRITE_INTO_KERNEL_STACK
ZERLENDSTZEROINCR
ExamplesMessage FormatSeverity Levels
Examples
Suppose the debugger displays the following message:
%DEBUG-I-INITIAL, language is BASIC, module set to TEST
In this example, the message identifier is INITIAL. To get
information about this message, enter the following command:
DBG> HELP MESSAGE INITIAL
Message Format
The following example shows the elements of a debugger
diagnostic message:
%DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table
1 2 3 |________________ 4_________________|
1. The facility name (DEBUG).
2. The severity level (W, in this example).
3. The message identifier (NOSYMBOL, in this example). The
message identifier is an abbreviation of the message text.
4. The message text.
Severity Levels
The possible severity levels for diagnostic messages are as
follows:
S Success
I Informational
W Warning
E Error
F Fatal or severe error
Success and informational messages tell you that the debugger
has performed your request.
Warning messages indicate that the debugger might have performed
some, but not all, of your request and that you should verify
the result.
Error messages indicate that the debugger could not perform your
request, but that the state of the debugging session was not
changed. The only exceptions are if the message identifier was
DBGERR or INTERR. These identifiers signify an internal
debugger error, and you should submit a Software Performance
Report (SPR) in such cases.
Fatal messages indicate that the debugger could not perform your
request and that the debugging session is in an indeterminate
state from which you cannot recover reliably. Typically, the
error ends the debugging session.
ABORTED
Message: command aborted by user request
Severity: Warning
Explanation: The command being executed was stopped when you typed
CTRL-C.
User Action: No action necessary.
ABSDATSYN
Message: absolute date-time syntax error
Severity: Warning
Explanation: The date-time value could not be converted because it
is not in the proper VMS format.
User Action: Re-enter the date-time value using the correct VMS
date-time format.
ACCADDCOM
Message: access violation in address computation for address_value
Severity: Warning
Explanation: The address computation for the specified variable
resulted in an access violation. This normally means that a
register value or a descriptor needed in the address computation
is uninitialized or corrupted.
User Action: If the necessary register or descriptor is not yet
initialized, the variable is not available at this point in the
code. If the register or descriptor is corrupted, the cause of
this error should be located and corrected.
ACTIVATING
Message: process-specification is activating
Severity: Informational
Explanation: The process process-specification has just activated,
and is now connected to the main debugger. Any SET
BREAK/ACTIVATING or SET TRACE/ACTIVATING events will now take
effect.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
ADDRANCOV
Message: address range covers more than one module address_value is
in path_name address_value is in path_name
Severity: Warning
Explanation: The address range specified in a debugger
EXAMINE/SOURCE command covers more than a single module. This
is not allowed. The start address CZ is in module mod1 and the
end address yyy is in module mod2.
User Action: Re-enter the command with a valid address range.
ADDRESSMODE
Message: instruction uses illegal or undefined addressing modes Severity: Error
ADDRMBZ
Message: a must-be-zero field in an address was not zero
Severity: Error
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
ADDRREG
Message: & not allowed on register variables: operand bound to
register_name
Severity: Warning
Explanation: The C language & operator could not be applied to the
given operand because the operand is a register variable. This
is not allowed in the C language definition.
User Action: Do not use the & operator on a register variable.
AMBFIELD
Message: field_name is an ambiguous field name
Severity: Warning
Explanation: The reference to the given field cannot be resolved
because there is more than one field with the given name.
User Action: Fully qualify the reference with a complete name for
the desired field.
AMBIGQUAL
Message: qualifier qualifier_name is ambiguous
Severity: Warning
Explanation: The qualifier cannot be resolved to a single option.
There is more than one option to the command that starts with
these characters.
User Action: Add more of the characters to the qualifier string to
make the option unambiguous. The qualifier should be
unambiguous when it has at least four characters.
AMPERSAND
Message: operand of ampersand must be lvalue
Severity: Warning
Explanation: The C language & operator cannot be applied to the
result of an expression. This is not allowed in the C language
definition.
User Action: Do not use the & operator in this context.
ASTWASDISABLED
Message: ASTs were disabled, are still disabled
Severity: Informational
Explanation: The delivery of asynchronous system traps ASTs were
already turned off in your program when the DISABLE AST command
was issued.
User Action: None
ASTWASENABLED
Message: ASTs were enabled, are still enabled
Severity: Informational
Explanation: The delivery of asynchronous system traps ASTs were
already turned on in your program when the ENABLE AST command
was issued.
User Action: None
ATTACHED
Message: terminal now attached to process process_name
Severity: Informational
Explanation: The control of your terminal is being passed from the
current process to another process by means of the ATTACH
command.
User Action: None
ATTREQREF
Message: attach request refused
Severity: Error
Explanation: The specified process could not be attached to.
Either it was not detached or it did not belong to the caller's
job.
User Action: Ensure that the specified process is detached and
belongs to the caller's job.
BADADDSPA
Message: attempted to compare addresses in different address spaces
Severity: Error
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
BADADDSTA
Message: attempted to compare addresses with different address
states
Severity: Error
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
BADBODPACK
Message: incorrect package spec name in body-spec spec-name, module
mod-name
Severity: Informational
Explanation: The compiler has generated invalid Debug Symbol Table
information.
User Action: Please submit a Software Performance Report against
the compiler.
BADDESCR
Message: descriptor for 'symbol_name' is bad or is not set up yet
Severity: Warning
Explanation: The descriptor for the given symbol points into memory
that cannot be read by the Debugger.
User Action: Correct the descriptor.
BADDISCVAL
Message: incorrect value of tag_value in discriminant field
tag_name.
Severity: Informational
Explanation: The discriminate value you gave was out of range.
User Action: Supply a discriminate value that is within the correct
range.
BADDST
Message: bad debugger symbol table (compiler error)
Severity: Error
Explanation: The debugger has detected an error in the Debug Symbol
Table of your program. This indicates an internal error in
either the debugger or the compiler of this module.
User Action: Please submit a Software Performance Report.
BADEVNPAR
Message: parameter does not have permitted data type for this event
Severity: Error
Explanation: The event you specified cannot be used with the
specified symbol. For example, you cannot specify the RUN event
except on TASK type symbols. Please see the documentation for
details on which events can be specified with which symbol
types.
User Action: Specify the correct symbol type for this event.
BADEXH
Message: the user-mode exit handler list is corrupt
Severity: Error
Explanation: While walking the list of user-mode exit handlers, the
debugger detected a forward link which pointed to an
inaccessible exit control block.
User Action: Check for a call to the SYS$DCLEXH system service that
specifies an illegal exit control block argument. Also verify
that exit control blocks are not getting corrupted later in the
program.
BADFRAME
Message: bad FP or bad saved FP at pointer-addr in call stack,
can't read frame near frame-addr
Severity: Informational
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The FP register (if
pointer-addris "FFFFFFFF") or the saved frame pointer at
location pointer-addr points to a frame at least part of which
is not read accessible near location frame-addr.
User Action: Determine what part of your code is writing into the
FP register or overwriting the saved frame pointer on the call
stack (or a preceding saved frame pointer) and correct it.
Since the debugger looks at the call stack to symbolize
addresses, you may suppress some of these messages by typing the
command "SET MODE NOSYMBOLIC".
BADHANDLE
Message: non-existent object handle passed to routine
Severity: Error
Explanation: The debugger uses object handles for passing
information around within itself. The debugger has used a
non-existent or corrupt handle for an operation. The user
should never see this message.
User Action: Submit a Software Performance Report (SPR)
BADOPCODE
Message: opcode opcode_name is unknown
Severity: Error
Explanation: The opcode opcode_name specified as a command
parameter is unknown to the debugger. It may be the case that
an opcode synonym has been specified which is not recognized by
the debugger.
User Action: Specify a valid opcode or specify an opcode synonym
that the debugger recognizes.
BADPARAM
Message: bad parameter value Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
BADSCOPE
Message: invalid pathname path_name, SCOPE not changed
Severity: Error
Explanation: The scope path_name specified in the SET SCOPE command
contained a pathname that does not exist.
User Action: Specify a valid scope.
BADSIGARG
Message: bad sigarg pointer at pointer-addr or bad sigarg vector,
can't read sigarg vector near sigarg-addr
Severity: Informational
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers, and has encountered an
exception handler. The signal argument pointer at location
pointer-addrpoints to a signal argument vector at least part of
which is not read accessible near location sigarg-addr.
User Action: Determine what part of your code is overwriting the
stored signal argument pointer on the call stack, or part of the
signal argument vector itself, and correct it. Since the
debugger looks at the call stack to symbolize addresses, you may
suppress some of these messages by typing the command "SET MODE
NOSYMBOLIC".
BADSTACK
Message: stack corrupted - no further data available
Severity: Warning
Explanation: While displaying part of the call stack, the debugger
has determined that the stack is corrupted and cannot continue
executing the command.
User Action: See the secondary message for more information.
BADSTARTPC
Message: cannot access start PC = address_value
Severity: Error
Explanation: Location address_value is not an accessible address
and therefore cannot be executed. This is often caused when a
GO command with no address specification is entered after the
program has terminated. The debugger tries to execute an
instruction at location 0, which is not accessible.
User Action: Specify a different address specification in the GO
command or, if the program has terminated, you can exit from the
debugger and initiate the program with the DCL command RUN.
BADSTATUS
Message: bad status returned from routine-name
Severity: Error
Explanation: The debugger got an unexpected error status from the
system service or RTL routine routine-name.
User Action: Examine the error message and consider if the problem
is related to a lack of quota or otherwise related to your
program's behavior. If so, then take corrective action. If,
after this evaluation, you believe that the problem lies in the
debugger, then submit a Software Performance Report.
BADSUBPAR
Message: incorrect parent name in subunit sym-name, in module
mod-name
Severity: Informational
Explanation: The compiler has generated invalid Debug Symbol Table
information.
User Action: Please submit a Software Performance Report against
the compiler.
BADTAGVAL
Message: incorrect value of tag_value in tag field tag_name. Severity: Informational Explanation: The tag value you gave was out of range. User Action: Supply a tag that is within the correct range.
BADTARGET
Message: target location protected, cannot perform deposit
Severity: Warning
Explanation: The target address of the DEPOSIT command cannot be
made writeable. The DEPOSIT command cannot be performed.
User Action: None.
BADUSEPACK
Message: incorrect package name in use clause use-name, module
module-name
Severity: Informational
Explanation: The compiler has generated invalid Debug Symbol Table
information.
User Action: Please submit a Software Performance Report against
the compiler.
BADUSREVNT
Message: bad user-specified event table or event entry in user RTL
Severity: Error
Explanation: The debugger has detected an internal inconsistency in
the event tables of the Run Time Library. This indicates an
internal error in either the debugger or the Run Time Library.
User Action: Please submit a Software Performance Report.
BADWATCH
Message: cannot watch protect address address_value
Severity: Error
Explanation: A SET WATCH command specified a protected address.
Note that you cannot place a watchpoint on a dynamically
allocated variable because these variables are stored on the
stack.
User Action: Do not use watchpoint on this address.
BADWIDGET
Message: the debugger can not write to the command dialog box, is
not initialized.
Severity: Fatal
Explanation: The debugger got an unexpected status when trying to
write to the command dialog box. This prevents the debugger
from continuing this session.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
BASVARNOTSET
Message: base variable not set up yet
Severity: Warning
Explanation: The pointer to the based variable has not been set up
by an ALLOCATE statement. Without a valid pointer, the
reference cannot be made.
User Action: Execute the ALLOCATE statement that defines the
pointer for this based variable and then use the pointer to
dereference the desired variable.
BITRANGE
Message: bit range out of limits
Severity: Error
Explanation: The EVALUATE command specified a bit field that is too
wide.
User Action: The low limit of the bit field is 0 and the high limit
is 31; the maximum range is 31:0.
BPTDIFMOD
Message: breakpoint or tracepoint being set in a different module.
Severity: Informational
Explanation: The specified line number was not found in the current
module. Consequently, Debug is setting the breakpoint or
tracepoint in a module later in the call stack or in a set
module not on the call stack.
User Action: If the breakpoint or tracepoint was intended to be set
in the current module, cancel the breakpoint or tracepoint and
specify a line number in the current module.
BPTONDATA
Message: execution breakpoint or tracepoint set on data item
Severity: Informational
Explanation: The command requested a breakpoint or tracepoint for a
data item. Typically breakpoints are set only on code
locations.
User Action: See the following message.
BUFFEROVF
Message: buffer overflow Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
BWLGISMUS
Message: B, W, L, G, I, or S must precede ^ for operand number
operand_number
Severity: Error
Explanation: You must specify the type of offset as either B
(byte), W (word), or L (longword). You must specify the type of
literal as either I (immediate) or S (short). You may specify
the addressing mode as G (general).
User Action: Enter the instruction again, specifying the operand
using one of the above modes.
CANBRKWAT
Message: cancel it and set a watchpoint if that is what was
intended
Severity: Informational
Explanation: If you intended to get notified when the specified
location was modified rather than executed, then a watchpoint
should have been set rather than a breakpoint.
User Action: If a watchpoint was intended, then cancel the
breakpoint and set a watchpoint.
CANTACCESSMAIN
Message: cannot access the main debugger
Severity: Fatal
Explanation: The kernel debugger cannot access the main debugger.
The reason is given in the message following this message.
User Action: Correct the problem given by the messages following
this message. If the problem cannot be solved, submit a
Software Performance Report.
CANTCREATEMAIN
Message: could not create the debugger subprocess
Severity: Fatal
Explanation: An error occurred while trying to create a subprocess
to run the sharable main debugger image. The reason is given in
the message following this message.
User Action: Correct the problem given by the messages following
this message. If the problem cannot be solved, submit a
Software Performance Report.
CANTGETFID
Message: cannot get file-id for image file opened on channel
channel-number
Severity: Fatal
Explanation: An error occurred while trying to get the file-id of
the image file opened on channel channel-number. The reason is
given in the message following this message.
User Action: Correct the problem given by the messages following
this message. If the problem cannot be solved, submit a
Software Performance Report.
CANTINTPRO
Message: cannot interrupt process !AC
Severity: Informational
Explanation: The debugger could not interrupt the specified process
because it was deleted. This message usually indicates that the
specified process terminated abnormally -- either via the DCL
STOP command or via a call to $DELPRC.
User Action: The debugger failed to interrupt the process. Unless
the reason for this is apparent, submit a Software Performance
Report (SPR).
CANTOPNIMG
Message: cannot open image image_name (File:
device_name:(file_id,file_id,file_id))
Severity: Informational
Explanation: The information the debugger needs to allow you to
debug this section of code is in an image file that could not be
opened.
User Action: Check for the existence of the specified file and/or
its associated file protection attributes.
CANTPAST
Message: cannot paste to read-only window.
Severity: Warning
Explanation: The window which has the input focus is a read-only
window. You cannot paste to a read-only window.
User Action: Assign the input focus to a writeable window and, if
applicable, to the appropriate text-entry field.
CIREXLST
Message: command aborted after number_of_handlers exit handlers
displayed circular exit handler list suspected
Severity: Error
Explanation: After displaying information about 100 exit handlers,
the debugger suspects a circular exit handler list.
User Action: If there is a circular exit handler list, then
identify and correct the error in the user program.
CLIBRDFAI
Message: clipboard operation failure
Severity: Warning
Explanation: One of the DECtoolkit clipboard routines has failed.
The attempt to write to the clipboard may not have completed
successfully.
User Action: Verify that the clipboard contains the data that you
wrote to it. If it does not, attempt the operation again.
CLIBRDLCK
Message: clipboard locked
Severity: Warning
Explanation: Some other DECWINDOWS application has locked the
clipboard.
User Action: Wait until the other application has released the
clipboard.
CMDISCOR
Message: the correct command is command_name
Severity: Informational
Explanation: The previous message shows the obsolete command. The
command replacing it is shown in this message.
User Action: Use the correct command as shown. The obsolete
command will not be available in a future release of the
debugger.
CMDISOBS
Message: command command_name is obsolete
Severity: Informational
Explanation: This command is obsolete.
User Action: Do not use this command, it will not be available in a
future release of the debugger.
CMDNOTDW
Message: The !AC command is not allowed in the DECWindows debugger
Severity: Error
Explanation: The specified command may not be used with the
DECWindows debugger.
User Action: Do not use the command with the DECWindows debugger.
CMDNOTONE
Message: The !AC command is not allowed in the one process debugger
Severity: Error
Explanation: The specified command may not be used with the single
process debugger.
User Action: Do not use the command with the one process debugger.
CMDSYNERR
Message: command syntax error at or near 'the
debugger_command_segment'
Severity: Warning
Explanation: There is a syntax error in the Debug command somewhere
near the string shown in the message.
User Action: Correct the syntax error and re-enter the command.
CMPNOTFND
Message: specified component not found in this type
Severity: Warning
Explanation: The enumeration component named in this operation
could not be found in the list of components defined for this
type.
User Action: Correct the name of the enumeration component or
correct the expression.
CNTRLWRDNOTACCESS
Message: the vector control word is not accessible
Severity: Error
Explanation: The debugger does not have direct access to the vector
control word. Therefore the operands of this instruction cannot
be displayed correctly.
User Action: Do not attempt to display the operands of vector
instructions whose control word is not accessible to the
debugger.
CONFLICT
Message: illegal combination of command elements - check
documentation
Severity: Warning
Explanation: Command line elements conflict in their operations.
The command will not be performed.
User Action: Do not specify conflicting command line elements.
CONFROMEXC
Message: warning: you are continuing from a severe error
Severity: Informational
Explanation: The debugger has encountered a severe error and is
continuing. The validity of this debugging session can no
longer be guaranteed.
User Action: Determine and correct the cause of the severe error.
If the problem cannot be solved, submit a Software Performance
Report (SPR).
CONSTRCOMP
Message: illegal deposit to a constrained record component
Severity: Error
Explanation: The debugger cannot DEPOSIT into a constrained record
component.
User Action: Do not attempt to deposit into a constrained record
component.
CPOSTDECR
Message: side effect on post-decrement operation not performed
Severity: Informational
Explanation: The debugger does not support the evaluation of a
post-decrement expression.
User Action: None
CPOSTINCR
Message: side effect on post-increment operation not performed
Severity: Informational
Explanation: The debugger does not support the evaluation of a
post-increment expression.
User Action: None
CPREDECR
Message: side effect on pre-decrement operation not performed
Severity: Informational
Explanation: The debugger does not support the evaluation of a
pre-decrement expression.
User Action: None
CPREINCR
Message: side effect on pre-increment operation not performed
Severity: Informational
Explanation: The debugger does not support the evaluation of a
pre-increment expression.
User Action: None
CRMPSCFAIL
Message: failed to map-in the debugger Symbol Table (DST)
Severity: Informational
Explanation: There will always be a secondary message describing
why the debugger failed to map-in the debugger symbol table
(DST) or global symbol table (GST).
User Action: Please refer to the secondary message to take the
appropriate action.
CVTNEGUNS
Message: cannot convert negative value to unsigned value at or near
opcode_name
Severity: Warning
Explanation: The command is attempting to assign a negative value
to an unsigned type. This is not allowed.
User Action: Do not attempt to put a negative value into an
unsigned variable.
DBGERR
Message: internal debugger coding error.
Severity: Error
Explanation: An internal debugger error has been encountered.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
DBGSTOPPED
Message: a debugger process from a previous debugging session has
been terminated
Severity: Warning
Explanation: While attempting to create a process to run the
debugger, a debug process from a previous debugging session was
found and terminated.
User Action: Under normal circumstances, the debugger process will
exit when a debugging session ends via the EXIT or QUIT
commands. If the previous debugging session was terminated with
an EXIT or QUIT command and this error is reproducable, then
submit a Software Performance Report (SPR)
DECLARERR
Message: too many declarations, parameter_name ignored
Severity: Warning
Explanation: There is a mismatch between the number of declarations
in a command procedure and the number of parameters passed to
that command procedure.
User Action: Check the command procedure and the DECLARE statements
within to see if they agree with the number of parameters on the
command line.
DECOVF
Message: decimal overflow at or near opcode_name
Severity: Error
Explanation: The value being deposited does not fit into the
specified address.
User Action: Specify either a smaller value or a different target
address.
DECROPRAND
Message: illegal packed or decimal string value (Reserved Operand
fault occurred during conversion)
Severity: Error
Explanation: The debugger encountered a Reserved Operand Fault when
attempting to convert the specified value. This indicates that
the packed or decimal string value did not contain a valid
number.
User Action: Ensure that the string value contains only valid
digits.
DEFKEY
Message: state_name key key_name has been defined
Severity: Informational
Explanation: The defining of functions keys has just been performed
using the DEFINE/KEY command. This command assigns a string to
function key. This is the logging message for the DEFINE/KEY
command.
User Action: None
DEFKEYERR
Message: error in processing DEFINE/KEY command:
Severity: Warning
Explanation: There was an error in defining the given key in the
display system. The key may not be redefinable, either because
the display system will not allow it or because there are
protections that prevent it. The key definition may be invalid.
User Action: Correct the error in the key definition.
DEFTOOREC
Message: Command defined with too many levels of recursion.
Severity: Error
Explanation: Commands may only be defined to a specified depth of
recursion (now set at 100).
User Action: Redefine your command such that it uses less levels of
recursion.
DELKEY
Message: state_name key key_name has been deleted
Severity: Informational
Explanation: The undefining of functions keys has just been
performed using the DELETE/KEY command. This command deletes
the key definitions that were established by the DEFINE/KEY
command or, by default by the debugger.This is the logging
message for the DELETE/KEY command.
User Action: None
DELKEYERR
Message: error in processing DELETE/KEY command:
Severity: Warning
Explanation: There was an error in deleting the given key
definition from the display mechanism. The key may not be a
defined key. The key definition might also be protected against
deletions.
User Action: Correct the error in the command or correct the
protections of the key in the display mechanism being used.
DELTIMTOO
Message: delta time too large
Severity: Error
Explanation: The debugger encountered an error when attempting to
convert the string form of the delta time to binary.
User Action: Enter the delta time specifying a smaller value.
DESCNOTSET
Message: descriptor not set up yet
Severity: Warning
Explanation: A descriptor used in an expression in the command is
not yet fully initialized. Some of the fields are not valid,
which means that the Debugger cannot completely evaluate the
expression.
User Action: Examine the descriptor that caused the problem and
determine which fields are not correct. Fill in these fields
with the correct values.
DISABLEAST
Message: ASTs were enabled, are now disabled
Severity: Informational
Explanation: Delivery of asynchronous system traps (ASTs) has been
turned off in your program by a DISABLE AST command.
User Action: None
DISNAMREQ
Message: display name required with this command Severity: Error Explanation: user did not specify a display name with this command User Action: enter a display name with this command
DISNOTSEL
Message: display not selected because removed from screen
Severity: Error
Explanation: You specified a display which is removed from the
screen.
User Action: Either specify a display which is not removed from the
screen, or place the specified display onto the screen and
attempt the operation again.
DISPEXISTS
Message: display_name display already exists; cannot be set until
canceled
Severity: Error
Explanation: You attempted to create a display which already
exists, either by explicitly creating the display or by trying
to save the contents of a display into currently existing
display.
User Action: Specify a display which does not exist.
DISPRLENSIZ
Message: length of display_name display cannot exceed maximum size
increase /SIZE or specify fewer lines
Severity: Error
Explanation: You attempted to resize the display so that the number
of visible lines in the display is larger than the number of
lines which are saved for the display. The debugger has set the
number of visible lines of the display to the SIZE value of the
display.
User Action: Either decrease the number of visible lines in the
display, or increase the number of lines which are saved for
this display by the use of the SIZE value.
DIVBYZERO
Message: attempted to divide by zero
Severity: Error
Explanation: During the evaluation of an expression, the debugger
noticed an attempt to divide by zero.
User Action: Correct the expression so that it does not divide by
zero.
DSTERRG
Message: error in DST (compiler error). GOTO DST has been ignored
Severity: Informational
Explanation: This represents an internal compiler, linker or
debugger error. If this can be reproduced please submit an
Software Performance Report (SPR).
User Action: If this can be reproduced please submit an Software
Performance Report (SPR).
DSTNESDEP
Message: DST nesting depth too deep in module path_name
Severity: Error
Explanation: Symbol table nesting depth is too deep in the
specified module. This occurs if routine nesting or data record
nesting is very deep in the user program.
User Action: Simplify the user program and run again.
DUPLVQUAL
Message: Duplicate or conflicting vector qualifier specified at
'command_line'
Severity: Error
Explanation: The qualifier indicated in the shown command line
fragment has already been specified, or is conflicting with an
earlier specified qualifier.
User Action: Delete the qualifier in error.
DWERR
Message: a DECwindows toolkit error has occurred the message text
is '!AS'
Severity: Informational
Explanation: An error has been reported by the DECwindows toolkit.
This indicates that either the toolkit or the X server has
detected a problem with the debuggers DECwindows display(s).
User Action: Try to correct the problem specified in the message.
For further information or assistance on this problem, contact
your System Manager.
DWNOT1PROC
Message: the 1 process debugger cannot be run in DECwindows mode
Severity: Warning
Explanation: The debugger must have ASTs enabled at all times in
order to properly run as a DECwindows program. This is not
possible for a 1 process debugger. Therefore, the debugger is
defaulting to not run as a DECwindows debugger.
User Action: Correct the logical name assignment for DBG$PROCESS to
be either "MULTIPROCESS" or "DEFAULT", and try again.
DYNIMGSET
Message: setting image image_name
Severity: Informational
Explanation: The debugger is automatically setting to the image
containing the current PC. This is only an informational
message.
User Action: None
DYNMODSET
Message: setting module path_name
Severity: Informational
Explanation: The debugger is automatically setting to the module
containing the current PC. This is only an informational
message.
User Action: None
EDITDISVER
Message: the original version is file_specification
Severity: Informational
Explanation: The original file has been revised since the start of
the debug session. This message indicates that source lines may
not correspond to the ones used to compile this module
User Action: Use SET SOURCE command to point to the original source
file if possible and re-attempt operation.
EDITERROR
Message: error while trying to EDIT
Severity: Informational
Explanation: An error occurred because of specifying a bad command
line or because of choosing an editor which is not installed on
this system.
User Action: Check command line syntax and re-enter, or select an
editor which is installed on the system. For further
information on the installed editors contact your system
manager.
EDITFILE
Message: editing file file_specification
Severity: Informational
Explanation: The debugger is currently setup to edit the file as
specified in the message. This is only an informational
message.
User Action: None
EDITNOFILE
Message: no source file to use for editing
Severity: Informational
Explanation: This messages indicates that the debugger could not
find the specified source file to use for editing.
User Action: Use SET SOURCE command to point to the original source
file if possible and reattempt operation.
EDITREVVER
Message: editing a revised version of the original source file
Severity: Informational
Explanation: The original source file has been revised since the
start of the debug session. This message indicates that future
source line may not correspond to the ones used to compile this
module.
User Action: Use SET SOURCE command to point to the original source
file if possible and reattempt operation.
ENABLEAST
Message: ASTs were disabled, are now enabled
Severity: Informational
Explanation: Delivery of asynchronous system traps (ASTs) has been
turned off in your program by a DISABLE AST command.
User Action: None
ENTRYMASK
Message: entry mask has non-zero value in bits 12:13
Severity: Informational
Explanation: This is an internal status signal, it should never be
seen by the user. If this message does occur please submit a
Software Performance Report (SPR).
User Action: Submit a Software Performance Report (SPR).
ENUMRANGE
Message: enumeration value out of range
Severity: Informational
Explanation: An error in your program indicates that the value of
this enumeration is out of range.
User Action: Examine this field in numeric format to determine its
value. Determine the error in your code and make the
appropriate corrections.
ERRACTIMG
Message: unable to activate image
Severity: Informational
Explanation: A bad status was returned from LIB$FIND_IMAGE_SYMBOL.
This message should be issued in the $DBG_INFO context.
User Action: The image the debugger was trying to activate could
not be activated. The following error should help to resolve
the problem.
ERRASSIGN
Message: the attempt to acquire an I/O channel for the debugger
failed
Severity: Informational
Explanation: A bad status was returned from a $ASSIGN type of call.
This message should be issued in the $DBG_INFO context.
User Action: The debugger needs to acquire I/O channels to do I/O.
In this case the debugger failed to acquire such a channel.
Check your process quotas.
ERRCLSFILE
Message: unable to close file
Severity: Informational
Explanation: A bad status was returned from a call to close a file.
This message should be issued in the $DBG_INFO context.
User Action: The debugger failed to close a file. Unless the
reason for this is apparent, submit a Software Performance
Report (SPR).
ERRCRELNM
Message: unable to create a logical name
Severity: Informational
Explanation: The debugger creates logical names for input and
output redirection. This message should be issued in the
$DBG_INFO context.
User Action: Submit a Software Performance Report (SPR).
ERRDEASSIGN
Message: attempt to deassign an I/O channel acquired by the
debugger failed
Severity: Informational
Explanation: The debugger wanted to deassign an I/O channel that is
acquired for internal purposes. This error notes the failure of
the SYS$DASSGN system service, probably due to an invalid
channel.
User Action: Submit a Software Performance Report (SPR).
ERRFAO
Message: unable to format output string Severity: Informational Explanation: An error was returned from a call to $FAO. User Action: Submit a Software Performance Report (SPR).
ERRGETDVI
Message: unable to get device information
Severity: Informational
Explanation: The debugger needed some information from $GETDVI and
the call failed. This indicates a programming error. No doubt
bad parameters were passed in.
User Action: Submit a Software Performance Report (SPR).
ERRGETEF
Message: attempt to allocate an event flag failed
Severity: Informational
Explanation: The debugger wanted to allocate a local event flag for
it's own use. For some reason the routine called to allocate
the event flag failed. This message is usually issued in the
$DBG_INFO context.
User Action: The debugger needs event flags to operate. Check the
program being debugged for excessive allocation of event flags.
ERRINSDEC
Message: error occurred while decoding instruction at current PC
Severity: Informational
Explanation: The debugger has encountered an error during decoding
an instruction at the current PC
User Action: The address may be an entry mask, examine the
instruction 2 bytes beyond the specified address.
ERRINSIGNAL
Message: signal arguments were incorrect, signal cannot be decoded
Severity: Warning
Explanation: The arguments which were passed as part of the signal
in your program were incorrect. The debugger encountered an
error in trying to analyze the signal arguments. The error is
shown in the message following this message.
User Action: Analyze the arguments passed to LIB$SIGNAL by your
program, and correct the error.
ERRINVEDIT
Message: error invoking editor
Severity: Informational
Explanation: While trying to invoke an editor a bad status was
returned.
User Action: Is the requested editor available and working
properly. If so, submit a Software Performance Report (SPR).
ERROR
Message: internal debugger error detected
Severity: Error
Explanation: This message indicates an internal debugger error.
User Action: Correct the problem given by the messages following
this message. If the problem cannot be solved, submit a
Software Performance Report.
ERRORLIMIT
Message: Error limit = error-limit, dumping terminated
Severity: Fatal
Explanation: The error limit specified for the DST dump was
exceeded; the dumper was unable to continue processing the input
file. By default, the error limit is set at 5. Use the
/ERROR_LIMIT qualifier to change the value.
ERROR_BLOCK
Message: error handle signalled, address = address
Severity: Error
Explanation: The debugger signalled an error handle. This should
never happen. The error handles are an internal construct which
are used to obtain information within the debugger. They should
never appear in user-visible messages.
User Action: Submit a Software Performance Report (SPR)
ERRQIOW
Message: error from $QIOW Severity: Informational Explanation: A bad status was returned from a call to $QIOW. User Action: Submit a Software Performance Report (SPR).
ERRSMG
Message: error returned from a call to the Screen Management
Facility (SMG)
Severity: Informational
Explanation: A bad status was returned from a call to SMG. This
could be a result of any number of things which may or may not
be a debugger problem.
User Action: Check the user program for potential interactions
between it and the debugger; pasteboard sharing and the like.
Also, check the set up of the terminal which might cause SMG
some problem. If the error still can't be explained submit a
Software Performance Report (SPR).
ERRSYSSERV
Message: error returned from an internal debugger system service
call
Severity: Informational
Explanation: A bad status was returned from a call to a system
service. This message is to be in the context of the $DBG_INFO
macro which will list the particular system service.
User Action: Submit a Software Performance Report (SPR).
ERRTARGOP
Message: unable to perform operation for current target system
Severity: Error
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
ERRUSREVNT
Message: error in user-specified event
Severity: Error
Explanation: When attempting to process the specified event, the
debugger called the Run Time Library, which returned an error
status. The error status returned by the Run Time Library
follows this message.
User Action: Correct the problem based on the associated message
which follows the debugger error message.
EXABEYREG
Message: Attempt to examine beyond the end of a register detected.
Severity: Error
Explanation: A ranged examine command was specified that attempted
to examine beyond the end of a bounded register.
User Action: Respecify the command so that it does not go past the
end of the register.
EXARANGE
Message: invalid range of addresses
Severity: Error
Explanation: The first address of a range to examine must be less
than the second address in this range.
User Action: Enter the address range specifying the addresses in
increasing order.
EXCBREREP
Message: exception breakpoint replaced
Severity: Informational
Explanation: A SET BREAK/EXCEPTION was done when exception breaks
were already in effect. The old exception break was replaced
with the new one.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
EXCDURCAL
Message: error occurred while executing routine called from
exception break
Severity: Error
Explanation: While executing a routine called from an exception
break using the CALL command, an exception occurred. Any
exceptions from routines called from an exception break cause
this message to be displayed followed by the text of the
exception. Execution of the called routine is then terminated.
User Action: Either correct the CALL command if it was in error, or
correct the routine that caused the exception. To use the
debugger to help find the cause of the exception, try calling
the routine while not at an exception break.
EXITARG
Message: exitloop argument num_levels is too large
Severity: Warning
Explanation: The parameter specified on the EXITLOOP command is
greater than the number of loops nested at this time. It is
also possible that you have specified an EXITLOOP command when
you are not inside of a loop.
User Action: Reduce the parameter on the EXITLOOP command to no
more than the number of loops nested at the time the EXITLOOP
command is to be executed. If there are no loops currently
being executed, then the EXITLOOP command is redundant.
EXITERR
Message: an error occurred while trying to exit the program
Severity: Error
Explanation: An error status was returned from the call to the
debugger-kernel service that terminates program execution.
Depending on the severity of the error, the program may or may
not have terminated.
User Action: Examine the error message after this message and
consider if the problem is related to a lack of quota or
otherwise related to your program's behavior. If so, then take
corrective action. If, after this evaluation, you believe that
the problem lies in the debugger, then submit a Software
Performance Report.
EXITSTATUS
Message: is 'status_value' Severity: Informational Explanation: The program has exited with the status status_value. User Action: None.
EXPMEMPOOL
Message: expanding debugger memory pool
Severity: Informational
Explanation: The debugger kernel maintains a memory pool from which
it allocates data structures to keep track of breakpoints,
tracepoints, watchpoints, and so on. The initial size of the
memory pool is 256 pages. The memory pool is expanded
automatically when needed, and this informational is signaled
when memory pool expansion occurs. If you have set a large
number of breakpoints, tracepoints, or watchpoints, this message
is to be expected.
User Action: If this message appears for no evident reason (i.e.,
you have not set a large number of breakpoints, tracepoints, or
watchpoints), there may be something wrong with the debugger.
In this case, submit an SPR.
FAILFINDIMG
Message: the debugger could not find the DECwindows image to be
initialized.
Severity: Fatal
Explanation: The debugger could not find the DECwindows image that
it was trying to initialize.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
FAILHEIRKY
Message: the debugger could not open the user interface definition
file, SYS$LIBRARY:DEBUGUIL.UID.
Severity: Fatal
Explanation: The debugger could not find one of the necessary file
to support the DECWindows interface, preventing the debugger
from continuing this session.
User Action: Check for the exsistance and accessability of
SYS$LIBRARY:DEBUGUIL.UID. For further assistance and
information on this probelm check with your system manager.
FAILXTINIT
Message: the debugger detected an error when trying to connect to
the DECWindow software.
Severity: Fatal
Explanation: The debugger failed to establish a connection to the X
server preventing the debugger from continuing this session.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
FATALSTATUS
Message: a fatal condition was detected by the debugger.
Severity: Fatal
Explanation: The debugger got an unexpected status from the system
service or RTL routine routine-name which prevents this DEBUG
session from continuing.
User Action: Examine the error message and consider if the problem
is related to a lack of quota or otherwise related to your
program's behavior. If so, then take corrective action. If,
after this evaluation, you believe that the problem lies in the
debugger, then submit a Software Performance Report.
FILEUNAL
Message: file not available
Severity: Warning
Explanation: The source file for the given program cannot be read.
User Action: Change the protections on the source file, or use SET
SOURCE to tell the Debugger where the source file really exists.
FLTOVF
Message: floating overflow at or near opcode_name
Severity: Error
Explanation: The value being deposited does not fit into the
specified address.
User Action: Specify either a smaller value or a different target
address.
HEIGHTDIFF
Message: desired height of specified_height is not allowed, height
is set to actual_height
Severity: Informational
Explanation: The device specified by DBG$OUTPUT had a screen height
that wasn't in the range of 18-100.
User Action: Use SHOW TERMINAL command and verify that the terminal
height is correct, it is in the range 18-100, and is pointing to
a valid terminal type.
IDENTLONG
Message: identifier too long, please shorten
Severity: Error
Explanation: Identifiers in address expressions must be shorter
than 256 characters.
User Action: Enter a shorter identifier.
IFIXUND
Message: precision lost during fixed point operation
Severity: Informational
Explanation: While doing operations on fixed point data items, the
debugger recognized that some precision was lost.
User Action: You should understand that the result of the operation
is imprecise and may not be exactly what you expect.
IFLTUND
Message: floating underflow at or near opcode_name
Severity: Informational
Explanation: While performing the arithmetic operation, a
floating-point value became less than the smallest representable
value for that data type.
User Action: You should understand that the result of the operation
is imprecise and may not be exactly what you expect.
IINTOVF
Message: integer overflow at or near opcode_name
Severity: Informational
Explanation: While performing the arithmetic operation, a
floating-point value exceeded the largest representable value
for that data type.
User Action: You should understand that the result of the operation
is imprecise and may not be exactly what you expect.
ILLADDCON
Message: illegal constant constant_name in address expression
Severity: Warning
Explanation: The constant in the message evaluates to a non-integer
type. Only integer types can be used in an address expression.
User Action: Change the constant to the appropriate integer value.
ILLASTER
Message: subscript range ('*') not permitted here (must be at
lowest level of data structure)
Severity: Warning
Explanation: The debugger does not allow an asterisk as a range in
an EXAMINE except as the last index in the array. That is, the
memory to examine must be a contiguous region. Unconnected
slices of arrays are not allowed.
User Action: Remove the asterisk from the expression to examine.
Placing the corrected EXAMINE inside a Debugger FOR loop command
could provide the functionality needed to do the command as
originally desired.
ILLDEFNAM
Message: illegal name for DEFINE: defined_name Severity: Warning Explanation: A defined name must be non-null. User Action: Enter a non-null name to DEFINE.
ILLENUMVAL
Message: enumeration value out of legal range
Severity: Warning
Explanation: The predecessor (or successor) function has been used
on the first (or last) component of the enumeration. The result
would not be a valid value of the enumeration.
User Action: Do not use the predecessor (or successor) function on
the first (or last) component of the enumeration.
ILLEVNSTR
Message: Attempt to pass an illegal event structure, name =
structure-name
Severity: Fatal
Explanation: This message indicates an internal debugger error.
User Action: Submit an SPR.
ILLFILPTR
Message: file variable points to invalid file descriptor
Severity: Warning
Explanation: The file variable references a file descriptor that
cannot be read, is incomplete, or points to a file that is not
open.
User Action: Correct the file descriptor.
ILLFLOAT
Message: float_value is an illegal floating point value
Severity: Warning
Explanation: The Debugger attempted to parse the given floating
point number and encountered an illegal character.
User Action: Correct the floating point number.
ILLINVNUM
Message: invalid invocation number at invoc_num
Severity: Error
Explanation: An illegal invocation number was specified (must be in
decimal radix).
User Action: Specify a legal decimal invocation number.
ILLLENGTH
Message: illegal length field length_value in structure reference
Severity: Warning
Explanation: A negative value was given for the length of a field
in a structure reference.
User Action: Change the field length to a non-negative value.
ILLNUMPATH
Message: illegal numeric pathname at path_name
Severity: Error
Explanation: An illegal numeric pathname was specified (must be in
decimal radix).
User Action: Specify a legal decimal numeric pathname.
ILLPACSIZ
Message: illegal packed size size_value; must be 0..31
Severity: Warning
Explanation: The specified size on a /PACKED qualifier is illegal.
It must be a value between 0 and 31.
User Action: Specify a legal value with the /PACKED qualifier.
ILLPATH1
Message: illegal use of %SOURCE_SCOPE (must not be combined with
invocation numbers)
Warning %SOURCE_SCOPE has been used in the same path with other
scope numbers.
User Action: Remove all but one of the references to the desired
scope.
ILLPATH2
Message: illegal use of %SOURCE_SCOPE (must appear at the start of
the pathname)
Warning %SOURCE_SCOPE has been used in a path name in an illegal
position. The %SOURCE_SCOPE lexical must be the first item in
the path list.
User Action: Move the %SOURCE_SCOPE lexical to the first position
in the pathname.
ILLPATHELEM
Message: illegal pathname element at path_name
Severity: Error
Explanation: Invocation numbers cannot be used with other
pathnames.
User Action: Eliminate the continuation of the pathname after the
invocation number.
ILLPATHIDENT
Message: Unknown identifier in pathname at path_name Severity: Error Explanation: An illegal identifier was specified in the pathname. User Action: Specify a legal identifier.
ILLPOSFLD
Message: position field value position_value is too large
Severity: Warning
Explanation: The value of the position specifier in the BLISS field
reference is an incredibly large number, larger than the
Debugger can handle. The value may be negative, which is also
illegal.
User Action: Change the value of the position specifier in the
BLISS field reference to a smaller (or positive) value.
ILLQUALIF
Message: illegal or unsupported qualifier on SPAWN command
Severity: Warning
Explanation: One of the qualifiers to the SPAWN command is
incorrect.
User Action: Remove the incorrect qualifier to the SPAWN command.
ILLRANGE
Message: subscript range not permitted here (must be at lowest
level of data structure)
Severity: Warning
Explanation: The Debugger does not allow a range in an EXAMINE
except as the last index in the array. That is, the memory to
examine must be a contiguous region. Unconnected slices of
arrays are not allowed.
User Action: Remove the range from the expression to examine.
Placing the corrected EXAMINE inside a Debugger FOR loop command
could provide the functionality needed to do the command as
originally desired.
ILLSETCON
Message: illegal set constant in expression
Severity: Warning
Explanation: One of the constants specified in the given set
expression has a type that is inconsistent with the set type.
User Action: Change the erroneous set constant value to a constant
with a type that agrees with the set type.
ILLSIGEXT
Message: illegal sign extension field value extension_value
Severity: Warning
Explanation: An illegal value has been entered for the sign
extension field in a field reference.
User Action: Re-enter the command using a valid sign extension
field value.
ILLSIZFLD
Message: illegal size field size_value; must be 0..32
Severity: Warning
Explanation: The size value for a BLISS field reference contains an
illegal value.
User Action: Change the size value of the field reference to an
integer between 0 and 32, inclusive.
ILLSUBLEN
Message: substring length larger than 32K not supported
Severity: Warning
Explanation: The calculated length of a substring in the expression
is larger than can be handled by the Debugger.
User Action: Do not use a substring with a length greater than 32K
in an expression to be evaluated by the Debugger.
ILLSUBSTR
Message: can only apply substring operation to string data types
Severity: Warning
Explanation: The Debugger has found a substring operation, but the
data type of the operand is not a string type.
User Action: Correct the data type of the string operand in the
substring expression.
ILLTYPE
Message: illegal type of operand(s)
Severity: Warning
Explanation: The type of the operand is illegal for the operator
specified.
User Action: Change the operand.
ILLVQUAL
Message: Illegal vector instruction qualifier specified at
'command_line'
Severity: Error
Explanation: A vector instruction qualifier that is illegal for
this vector instruction was specified during a
DEPOSIT/INSTRUCTION command.
User Action: Do not specify that illegal qualifier on that
instruction.
INCDSTNES
Message: incorrect DST nesting in module path_name, compiler error
Severity: Error
Explanation: Incorrect symbol table nesting occurred, such as
improper routine or data record nesting in the specified module.
This message normally indicates a compiler error.
User Action: Submit a Software Performance Report.
INCOMPOPR
Message: operand number operand_number incomplete
Severity: Error
Explanation: When parsing an instruction, the debugger found an
incomplete operand.
User Action: Specify complete operands when entering machine
instructions.
INCOMPPTR
Message: pointers of different size, cannot perform subtraction
Severity: Warning
Explanation: The two pointers point to objects with incompatible
types. A computation involving these pointers does not have a
meaningful result.
User Action: Do not attempt to mix pointers of different types in
arithmetic computations.
INCOMQUAL
Message: qualifier qualifier_name is not compatible with
qualifier_name(s)
Severity: Warning
Explanation: Qualifiers specified with the command conflict in
their operations.
User Action: Specify non-conflicting qualifiers.
INCOMTARGET
Message: a debugger_type kernel debugger is incompatible with a
debugger_type main debugger
Severity: Error
Explanation: A kernel debugger attempted to connect to a main
debugger with which it is not compatible.
User Action: Make sure that the logical names used to point at the
sharable and non_sharable debugger images are defined to point
to the same type of debuggers.
INCOMVERSION
Message: the RPC versions of the main and kernel debuggers are
incompatible
Severity: Error
Explanation: A kernel debugger attempted to connect to a main
debugger with which it is not compatible.
User Action: Make sure that the logical names used to point at the
sharable and non_sharable debugger images are defined to point
to the same type of debuggers.
INDBASEQL
Message: index and base registers are equal for operand number
operand_number
Severity: Error
Explanation: When parsing an instruction, the debugger found an
operand whose base register and index registers were the same.
The VAX instruction architecture forbids this construction.
User Action: Specify different registers for the base and index
registers.
INITERR
Message: an error has occurred during debugger initialization,
unable to continue this session.
Severity: Fatal
Explanation: The debugger encountered an error during
initialization which does not allow this debugging session to
proceed.
User Action: Use the message which preceded this message to analyze
and correct the error, and try again.
INITIAL
Message: language is language_name, module set to path_name
Severity: Informational
Explanation: This message is displayed when the debugger is invoked
by the image activator. The language is set to language_name,
and the module to path_name. Module path_name is the first
module specified in the LINK command, and language language_name
is the language used in that module.
User Action: None.
INPREADERR
Message: error reading input line:
Severity: Warning
Explanation: There was an error from the system while trying to
read the input line.
User Action: Re-enter the command line. Check to see that the
Debugger has read access to the input source. If the problem
persists, submit a Software Performance Report (SPR).
INSVIRMEM
Message: insufficient virtual memory for the debugger memory pool
Severity: Informational
Explanation: An attempt to allocate additional memory for working
storage failed.
User Action: Cancel set modules to free space in memory.
INTERR
Message: internal debugger error in debugger_routine_name
Severity: Error
Explanation: An internal debugger error has been encountered.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
INTERRUPTED
Message: process interrupted via cross-process signal
Severity: Fatal
Explanation: This signal is delivered asyncronously to a process to
cause the debugger to be invoked in that process.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
INTMEMERR
Message: internal memory-pool error
Severity: Fatal
Explanation: The debugger's internal memory area has been corrupted
or is inconsistent. This can be caused by an internal debugger
error or by random stores by the user program.
User Action: Correct the user program or submit a Software
Performance Report.
INTOVF
Message: integer overflow at or near opcode_name
Severity: Error
Explanation: The value being deposited does not fit into the
specified address.
User Action: Specify either a smaller value or a different target
address.
INTVECERR
Message: internal debugger coding error in using vector
instruction(s)
Severity: Error
Explanation: An internal debugger error has been encountered when
attempting to execute a vector instruction. Messages will
follow this text which will more fully explain the error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
INUMTRUNC
Message: number truncated at or near opcode_name
Severity: Informational
Explanation: On some conversions packed numbers need to be
truncated to fit into their destination. Truncation is done
from the least significant digit to the most significant digit.
User Action: You should understand that the result of the operation
is imprecise and may not be exactly what you expect.
INVARGLIS
Message: invalid argument list for 'the debugger_command_segment'
Severity: Warning
Explanation: There is an error with the argument list. The
Debugger may be expecting an argument list when none was
supplied. The Debugger may have found an argument list where
one was not expected. The Debugger may have found an argument
list that was too long or too short. Finally, the Debugger may
have found an inconsistency in the argument list.
User Action: Correct the command. Supply the correct argument list
if one was missing or in error. Delete the inappropriate
argument list, if one was present.
INVARRDIM
Message: array dimension is out of range
Severity: Warning
Explanation: The array dimension is out of the range of the
declared size and shape of the array. Either the dimension
requested is less than zero, or it is greater than the number of
dimensions the array was declared with.
User Action: Correct the invalid array dimension.
INVARRDSC
Message: invalid array descriptor
Severity: Error
Explanation: An array descriptor in the image does not have the
correct format. This can be caused by a reference to a VAX
BASIC array when the first line of the program has not been
executed. The array is not set up correctly until the BASIC
program initialization is done. This message can also be caused
by a user program or DEPOSIT commands altering a compiler
generated array descriptor.
User Action: If the reference is to a VAX BASIC array, enter a STEP
or GO command to ensure that the BASIC program initialization is
done and then repeat the reference. Otherwise, if an array
descriptor has not been altered, submit a Software Performance
Report.
INVCHAR
Message: invalid character
Severity: Error
Explanation: When parsing the command, an invalid character was
detected.
User Action: Enter the command specifying only valid characters.
INVCHRCON
Message: invalid character constant in expression
Severity: Error
Explanation: When evaluating a language expression, the debugger
expected to find a closing single quote mark, or the end of the
command. Some other character was found, which resulted in an
illegal language expression.
User Action: Enter a valid language expression.
INVDESC
Message: invalid string descriptor Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
INVDIGBIN
Message: invalid digit in binary number: number_value
Severity: Error
Explanation: A numeric value other than '0' and '1' was found in a
binary number.
User Action: Enter binary numbers specifying only digits '0' and
'1'.
INVDIGDEC
Message: invalid digit in decimal number: number_value
Severity: Error
Explanation: A numeric value other than in the range '0' through
'9' was found in a decimal number.
User Action: Enter decimal numbers specifying only digits '0'
through '9'.
INVDIGHEX
Message: invalid digit in hexadecimal number: number_value
Severity: Error
Explanation: A numeric value other than in the range '0' through
'9' or an alphabetic value other than in the range 'A' through
'F' was found in a hexadecimal number. Hexadecimal numbers must
also start with a numeric character, for example '0F'.
User Action: Enter hexadecimal numbers specifying only digits '0'
through '9' and alphabetic values 'A' through 'F'.
INVDIGOCT
Message: invalid digit in octal number: number_value
Severity: Error
Explanation: A numeric value other than in the range '0' through
'7' was found in a decimal number.
User Action: Enter decimal numbers specifying only digits '0'
through '7'.
INVDIRNAM
Message: invalid directory name: file_specification
Severity: Error
Explanation: The directory name 'file_specification' given in a
DEBUGGER command SET SOURCE is not valid. Either the directory
syntax is incorrect or the directory does not exist.
User Action: Ensure that the directory exists and that the syntax
is correct.
INVDMTPTR
Message: invalid DMT pointer; internal linker or debugger error
Severity: Informational
Explanation: The debugger found that the pointer in the image
header to the Debug Module Table (DMT) was invalid. The
debugger will continue from this error trying to initialize
based on the Debug Symbol Table (DST).
User Action: Check that the image file hasn't been modified or
corrupted in some way. If not, submit a Software Performance
Report (SPR).
INVDSPSIZ
Message: invalid display size: display_size
Severity: Error
Explanation: The SIZE value for a display must be between 1 and
1000.
User Action: Specify the SIZE value between 1 and 1000.
INVDSTREC
Message: invalid DST record
Severity: Error
Explanation: The debugger has detected an error in the Debug Symbol
Table of your program. This indicates an internal error in
either the debugger or the compiler of this module.
User Action: Please submit a Software Performance Report.
INVEXPR
Message: invalid expression for operand number operand_number
Severity: Error
Explanation: The specified operand was not correct for this
instruction.
User Action: Please check the documentation for the correct
operands for this instruction, and re-enter the instruction with
the correct operands.
INVFIXDST
Message: invalid DST fixup records in image image_name, symbol
references to shareable images may be erroneous
Severity: Informational
Explanation: While attempting to read the symbol table information
in the specified image, the debugger found errors in the symbol
table address fixup records. These records are used to adjust
for the base addresses of shareable images. This means that any
symbols in this image which point to addresses in other
(shareable) images will most likely be incorrect. Symbols which
refer to addresses in this image will be correct unless this is
also a shareable image.
User Action: Relink the image and, if the error is reproducible,
submit a Software Performance Report explaining how the image
file was created.
INVFLDREF
Message: invalid field reference; too many or few parameters
Severity: Warning
Explanation: The Debugger could not complete the parse of the BLISS
field reference specification. Either the closing angle bracket
terminator was found too soon, or it was not found when it was
expected.
User Action: Correct the field reference.
INVGSTREC
Message: invalid GST record
Severity: Error
Explanation: The debugger has detected an error in the Global
Symbol Table of your program. This indicates an internal error
in either the debugger or the compiler of this module.
User Action: Please submit a Software Performance Report.
INVGSTTYP
Message: invalid GST record; GST is partially built
Severity: Informational
Explanation: The debugger found an invalid Global Symbol Table
(GST) record in the image. The debugger will discontinue
initializing the GST at this point. The debugger will continue
from this error, however global symbol information may not be
complete.
User Action: Check that the image file hasn't been modified or
corrupted in some way. If not, submit a Software Performance
Report (SPR).
INVMAR
Message: right margin must be greater than left
Severity: Warning
Explanation: You specified a right margin that was less than the
left margin in the debugger command SET MARGIN. The right
margin must be greater than the left margin.
User Action: Re-enter the command specifying a valid margin range.
INVNUMBER
Message: invalid numeric string 'number_value'
Severity: Error
Explanation: A numeric value which was not in the specified radix
was found in the language expression.
User Action: Enter numbers specifying only valid digits for that
radix.
INVNUMSRC
Message: invalid number of source files
Severity: Warning
Explanation: An invalid number of source files was specified on the
SET MAX_SOURCE_FILES command. The maximum number of source
files that the debugger will keep open simultaneously must be in
the range of 1 through 20.
User Action: Re-enter the command specifying a valid number within
the range.
INVNUMSTR
Message: invalid numeric string at or near 'number_value'
Severity: Error
Explanation: The debugger encountered an error when attempting to
convert the specified value. This indicates that the string
value did not contain a valid number.
User Action: Ensure that the string value contains only valid
digits.
INVOPADDR
Message: invalid operator 'operator_symbol' in address expression Severity: Error Explanation: Address expressions cannot contain operators. User Action: Enter the address expression without operators.
INVOPSYM
Message: invalid operator symbol 'operator_symbol' in expression
Severity: Error
Explanation: Identifiers in address expressions must be shorter
than 256 characters.
User Action: Enter a shorter identifier.
INVPAGE
Message: invalid screen height, value must be between
minimum_height and maximum_height
Severity: Error
Explanation: The height of the terminal which the debugger uses to
place it's windows must be between the values specified.
User Action: Specify the page size of the screen to be between the
values specified.
INVPRCSYN
Message: process specification syntax error
Severity: Error
Explanation: The specified process specification is syntactically
invalid
User Action: Re-enter the command specifying a correct process
specification
INVPRIOR
Message: invalid task priority value specified Severity: Error Explanation: The priority of an Ada task must be between 0 and 15. User Action: Specify a valid priority for the task.
INVRANSPEC
Message: invalid range specification in array subscript
Severity: Warning
Explanation: A range specification in an array reference is
illegal. The Debugger may have found a range where none is
allowed. An asterisk may have been used as a range where it is
not allowed. The array subscripts may have more than one set of
ranges, which is not allowed. The range may be invalid, with
bounds greater than the declared bounds of the array. Finally,
the lower bound of the range may be greater than the upper bound
of the array.
User Action: Correct the range specification in the array
subscript.
INVSELDIS
Message: invalid selection of display_name display; wrong display
kind
Severity: Error
Explanation: Some attributes can only be placed on certain types of
displays. For example, the SOURCE attribute can only be placed
on source displays. The attribute you specified cannot be
placed on the display you specified.
User Action: See the debugger documentation of the SELECT command
for details on which attributes can be placed on which displays.
Specify attributes which are compatible with the display kind.
INVSRCLIN
Message: invalid source line range
Severity: Warning
Explanation: An invalid source line range was entered in the
debugger TYPE command. The first line number of the range must
be non-negative and less than or equal to the second number in
the range.
User Action: Re-enter the command specifying a valid line number
range.
INVTIMSLI
Message: time slice was not set, parameter is out of range of Ada
type DURATION
Severity: Error
Explanation: The value specified for the time slice was out of
range of the Ada type DURATION.
User Action: See the Ada documentation for the range of the
DURATION type. Specify time slice values which are in range of
type DURATION.
INVWIDTH
Message: invalid screen width, value must be between minimum_width
and maximum_width
Severity: Error
Explanation: The width of the terminal which the debugger uses to
place its windows must be between the values specified.
User Action: Specify the width of the screen to be between the
values specified.
INVWINPAR
Message: invalid window parameter: number_value
Severity: Error
Explanation: The value specified was out of range of the screen on
which the window will be placed. If the debugger is placing its
windows on a terminal screen, the beginning row and column
numbers must be between 1 and the height and width of the
screen, and the beginning value plus the height or width of the
window must not exceed the height or width of the terminal
screen. If the debugger is running with the DECwindows
interface, the beginning row and column numbers must be greater
than 0.
User Action: Specify valid parameters for the window row and column
values, and for the height and width of the window.
IRFAOVF
Message: record file address overflow at or near opcode_name
Severity: Informational
Explanation: The conversion of the ASCII string to a record file
address caused an overflow. The conversion was performed
however.
User Action: Check the value to make sure the conversion performed
as expected.
ISTRTRU
Message: string truncated at or near opcode_name
Severity: Informational
Explanation: The string did not fit into the specified destination
resulting in lost trailing characters. The conversion was
performed however.
User Action: Check the value to make sure the conversion performed
as expected.
ITMNOTAVA
Message: item not available
Severity: Warning
Explanation: The user should never see this message. The debugger
uses an item list construct for passing information between its
parts. This message indicates that the requesting routine
requested data which the target routine was not capable of
providing. Appearance of this message indicates an internal
problem in the debugger.
User Action: Submit a Software Performance Report (SPR)
ITMTRUNC
Message: item truncated - buffer of insufficient size
Severity: Warning
Explanation: The user should never see this message. The debugger
uses an item list construct for passing information between its
parts. This message indicates that the requesting routine
allocated a buffer which was too small for the requested data.
Appearance of this message indicates an internal problem in the
debugger.
User Action: Submit a Software Performance Report (SPR)
IVALNOFIT
Message: value does not fit into target location at or near
opcode_name
Severity: Informational
Explanation: The value can not be represented in the target
location and may be truncated. The bit field is not large
enough to hold the value.
User Action: Check the value in the target location.
IVALOUTBNDS
Message: value assigned is out of bounds at or near opcode_name
Severity: Informational
Explanation: The value is out of the bounds defined for the data.
The operation was performed however.
User Action: Check the results of the operation to make sure they
are as you expected.
IVPRCLOG
Message: logical name DBG$PROCESS must be either MULTIPROCESS or
DEFAULT
Severity: Fatal
Explanation: The logical name DBG$PROCESS translates to something
other than "MULTIPROCESS" or "DEFAULT".
User Action: Correct the logical name assignment for DBG$PROCESS
and try again.
KERFUNCNYI
Message: Kernel Function function_name not yet implemented on this
architecture
Severity: Error
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report.
KEYNAMERR
Message: unrecognized key name: key_name
Severity: Error
Explanation: This keyname <key_name, !AS> is in error. It can not
be defined by the user.
User Action: Check spelling of the key name.
KEYSTATERR
Message: unrecognized state name: state_name
Severity: Error
Explanation: This key state <state_name, !AS> is in error. It has
not been defined by the user.
User Action: Check spelling of the state name or define the state.
LASTCHANCE
Message: stack exception handlers lost, re-initializing stack
Severity: Error
Explanation: The user's program contained an error that caused the
exception handling mechanism to fail. This error occurs when
the stack is overwritten by the user program or by deposit
commands.
User Action: Identify and correct the error in the user program.
LINEINFO
Message: line-description
Severity: Error
Explanation: This is either 'No line information available', or 'No
line <line_number, !UL>, previous line is <line_number, !UL>,
next line is <line_number, !UL>'
LOGFILEIS
Message: the error log is in file file_specification
Severity: Informational
Explanation: An internal debugger error has occurred, and
information which will be useful in locating the error has been
written to file_specification.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
LONGSTRING
Message: strings longer than 2**16 characters not supported
Severity: Warning
Explanation: The length of a string or the range of one array bound
is greater than 2**16. The string or array is too large for the
Debugger.
User Action: Do not use strings of this length with the Debugger.
LOOPINCR
Message: loop increment cannot be zero
Severity: Warning
Explanation: The loop increment specified on the FOR command is
zero.
User Action: Change the loop increment to be a non-zero value.
LOOPVAR
Message: loop var loop_variable has been redefined; exiting for
loop
Severity: Informational
Explanation: Since the loop variable has been redefined, the
debugger will exit the loop. No further comparison is possible.
User Action: None.
LOWBNDOPT
Message: lower bound of subrange was optimized away
Severity: Informational
Explanation: The lower bound of the subrange was optimized away.
The largest negative number on the machine is being used as the
lower bound.
User Action: You may wish to recompile the program without
optimizations.
MASKMISMATCH
Message: mask/target subscripts do not match, displaying mask
Severity: Informational
Explanation: The subscript values for the supplied mask value are
different then the subscript values for the target value. To
minimize confusion, Debug is showing the mask values as well as
the target values.
User Action: None, this message is informational.
MASKNOTUSED
Message: mask operations not allowed on record and SCAN tree
objects
Severity: Informational
Explanation: A mask operation (as specified by the /TMASK or /FMASK
qualifiers) cannot be performed on a record or SCAN tree object.
User Action: Specify an array or address range to perform the mask
operation on.
MASKNOTVMR
Message: mask used is not %VMR, displaying specified mask
Severity: Informational
Explanation: The supplied mask is not %VMR. To minimize confusion,
Debug is showing the mask values as well as the target values.
User Action: None, this message is informational.
MASKPARNREQ
Message: parenthesis required in 'EXAMINE/xMASK=(x)'
Severity: Warning
Explanation: Parentheses are required around the mask expression
specified with the /TMASK or /FMASK qualifiers on the Examine
command.
User Action: Include parantheses when specifying a mask expression.
MATQUOMIS
Message: matching quote is missing
Severity: Warning
Explanation: The matching quote at the end of a quoted string is
missing.
User Action: Correct the error and re-enter the command.
MISCLOSUB
Message: missing closing subscript parenthesis Severity: Warning Explanation: This is a syntax error in a Debug command User Action: Reinvoke the command with the proper syntax
MISINVNUM
Message: misplaced invocation number in path_name
Severity: Warning
Explanation: The invocation number was not placed after the
innermost (rightmost) routine name in the specified pathname.
User Action: Correct the pathname and re-enter the command.
MISINVOPER
Message: missing or invalid operator at 'operator_symbol'
Severity: Error
Explanation: An operand was encountered in a language expression
when an operator was expected. For example, 'EVALUATE A B'
instead of 'EVALUATE A + B'.
User Action: Specify valid operators between operands.
MISMODBEG
Message: missing Module-Begin record in DST (compiler error)
Severity: Informational
Explanation: An expected Module-Begin record was not found in the
debugger Symbol Table. This indicates a probable error in the
compiler output.
User Action: Submit a Software Performance Report.
MISMODEND
Message: missing Module-End in DST for path_name (compiler error)
Severity: Informational
Explanation: An expected Module-End record was not found in the
debugger Symbol Table. This indicates a probable error in the
compiler output.
User Action: Submit a Software Performance Report.
MISOPEMIS
Message: misplaced operator or missing operand at 'operator_symbol'
Severity: Error
Explanation: An operand was encountered in a language expression
when an operator was expected, or an operand did not follow an
operator. For example, 'EVALUATE A B' or 'EVALUATE A + '
instead of 'EVALUATE A + B'.
User Action: Specify valid operators between operands.
MODUSCOPE
Message: a module name was expected; path_name not valid Severity: Warning Explanation: This is a syntax error in a Debug command User Action: Reinvoke the command with the proper syntax
MOVED_1
Message: this message is available for reuse Severity: Informational Explanation: This message has been moved, and should not be seen. User Action: Please submit a Software Performance Report.
MOVED_2
Message: this message is available for reuse Severity: Informational Explanation: This message has been moved, and should not be seen. User Action: Please submit a Software Performance Report.
MOVED_3
Message: this message is available for reuse Severity: Informational Explanation: This message has been moved, and should not be seen. User Action: Please submit a Software Performance Report.
MOVED_4
Message: this message is available for reuse Severity: Warning Explanation: This message has been moved, and should not be seen. User Action: Please submit a Software Performance Report.
MOVED_5
Message: this message is available for reuse Severity: Fatal Explanation: This message has been moved, and should not be seen. User Action: Please submit a Software Performance Report.
MOVED_6
Message: this message is available for reuse Severity: Fatal Explanation: This message has been moved, and should not be seen. User Action: Please submit a Software Performance Report.
MPARENREQ
Message: parenthesis required around process list in debug_command
Severity: Warning
Explanation: Parentheses must be placed around the process list for
debugger commands SET/PROCESS=(process-list) or
DO/PROCESS=(process-list).
User Action: Place parentheses around the process list in the
command.
MPCOMMAND
Message: command is only valid when multiprocess support is enabled
Severity: Error
Explanation: The debugger was unable to execute the specified
command since it is only valid when the debugger's multiprocess
support is enabled.
User Action: Restart the debugging session with multiprocess
support enabled. Multiprocess support is enabled by defining
the logical name DBG$PROCESS as follows: ($ DEFINE/JOB
DBG$PROCESS MULTIPROCESS)
NAMSTRMIS
Message: name string missing or invalid in %NAME construct
Severity: Error
Explanation: The %NAME construct requires either a quoted string or
a name to be supplied.
User Action: Specify a valid name after the %NAME construct.
NAMTOOLONG
Message: name is too long: 'symbol_name'
Severity: Error
Explanation: Display and window names must be less than 80
characters in length.
User Action: Shorten the name to be less than 80 characters long.
NEEDMORE
Message: unexpected end of command line
Severity: Warning
Explanation: The command entered was not complete. A required part
of the command was omitted.
User Action: Re-enter the complete command.
NEEDPAREN
Message: parenthesis required in THEN, ELSE, and DO clauses
Severity: Informational
Explanation: Parenthesis are required in THEN, ELSE, and DO clauses
to group the containing debugger commands.
User Action: Correct the THEN, ELSE, or DO clause by including
parenthesis.
NOACCESSR
Message: no read access to address address_value
Severity: Error
Explanation: The address you specified cannot be read by the
debugger. Therefore the operation you requested cannot be
performed.
User Action: Verify that the address being read is correct. One
way to do this is to use EVALUATE to find the address of the
specified symbol, or to EXAMINE the descriptor to see if it
specifies a valid address.
NOACCESSW
Message: no write access to address address_value
Severity: Error
Explanation: A DEPOSIT, SET BREAK, or SET TRACE command specified
the address address_value. The debugger does not have write
access to that page. The debugger requires write access in
order to be able to set up breakpoints and tracepoints.
User Action: None. You cannot do the requested operation without
proper access.
NOADDRREG
Message: register register_name does not have an address use
@register_name to obtain the contents of register register_name
Severity: Warning
Explanation: The user has requested the address of a register but
registers do not have addresses
User Action: Examine the register directly
NOALTERSP
Message: deposit into register 14 (stack pointer) not allowed
Severity: Informational
Explanation: You can not deposit into the stack pointer register
because the debugger is on the stack and it would corrupt the
debugger or program stack frames.
User Action: None.
NOATTACH
Message: attach command failed
Severity: Error
Explanation: The ATTACH command could be not performed because of
an error which was returned by the system service called by the
debugger. The error status returned by the system service
routine follows this message.
User Action: Correct the problem based on the associated message
which follows the debugger error message.
NOBREAGGR
Message: breakpoints or tracepoints on registers, records or arrays
are not allowed
Severity: Error
Explanation: Only watchpoints are allowed on registers, records or
arrays.
User Action: Either change the address of the breakpoint or
tracepoint, or specify a watchpoint on the address.
NOBREAKAT
Message: cannot set breakpoint or tracepoint at address
address_value
Severity: Warning
Explanation: The user has requested that a breakpoint be set at an
address that is either non-writable, in Debug, or invalid in
some other way.
User Action: Correct the address and reissue the command
NOBREAKS
Message: no breakpoints are set
Severity: Informational
Explanation: The SHOW BREAK command was entered and no breakpoints
were set.
User Action: None.
NOCALLS
Message: no active call frames
Severity: Error
Explanation: The call stack cannot be displayed because your
program has run to completion, and there are no call frames on
the stack.
User Action: None.
NOCANMAIN
Message: cannot cancel main image
Severity: Warning
Explanation: The user has requested that the main image symbols be
canceled. This is an invalid operation.
User Action: No action required - operation invalid.
NOCLI
Message: no CLI present to perform function
Severity: Error
Explanation: There is no command line interpreter in the target
process from which to perform the operation.
User Action: None. You cannot perform the attempted operation.
NOCONNECT
Message: CONNECT command failed
Severity: Error
Explanation: The debugger was unable to execute the connect
command. The reason is given in the message following this
message.
User Action: Correct the problem given by the messages following
this message. Most often, the problem is due to specifying a
process that does not exist, or specifying a process that is not
in the same VMS job as the process being debugged. If the
problem cannot be solved, submit a Software Performance Report.
NOCURLOC
Message: current location not defined
Warning '.' is not currently defined.
User Action: Do not reference '.' until an EXAMINE or
EVALUATE/ADDRESS command has been performed.
NODEFSCPE
Message: No default scope list: error performing !AC
Severity: Error
Explanation: The specified command or built-in symbol requires that
the default scope list be established.
User Action: To establish the default scope list, perform a CANCEL
SCOPE command.
NODELIMTR
Message: missing or invalid instruction operand delimiter
Severity: Error
Explanation: A DEPOSIT command specified an invalid instruction
operand format.
User Action: Re-enter the command with valid operands.
NODEPDEBUG
Message: DEPOSIT into the debugger's address space is not allowed
Severity: Warning
Explanation: The user has tried to deposit into addresses occupied
by the Debugger. This is not allowed.
User Action: Correct the address and reissue the command.
NODIRLISM
Message: no source directory list in effect for path_name
Severity: Warning
Explanation: The debugger command CANCEL SOURCE/MODULE=path_name
failed because there is no source directory search list in
effect for module path_name.
User Action: This is an informational message. However, if the
wrong module was specified, the command should be re-entered
with the correct name.
NODIRLIST
Message: no source directory list in effect
Severity: Warning
Explanation: The debugger command CANCEL SOURCE had no effect
because no source directory search list is currently in effect.
User Action: None. This message is informational.
NOELABBODY
Message: package body path_name has no executable code Severity: Warning
NOELABSPEC
Message: package spec path_name has no executable code Severity: Warning
NOEND
Message: string beginning with 'string_value' is missing end
delimiter delimiter_character
Severity: Error
Explanation: A DEPOSIT command specified an ASCII string or
INSTRUCTION string beginning with characters string_value that
do not have a terminating apostrophe.
User Action: Re-enter the command with characters containing a
terminating apostrophe.
NOEPTSPEC
Message: no eventpoints were specified with a SHOW or CANCEL
command.
Severity: Error
Explanation: Eventpoints were not given with a SHOW or CANCEL
command.
User Action: Try the command again, specifying eventpoints to
operate on.
NOEVALEXPR
Message: unable to evaluate expression for following reason
Severity: Informational
Explanation: The expression could not be evaluated. The following
message indicates why.
User Action: See the following message.
NOEVENTFAC
Message: /EVENT qualifier not allowed: first type 'SET EVENT
facility' to specify an event facility
Severity: Error
Explanation: No event facility has been set up yet, therefore no
events which use an event facility can be set, canceled, or
displayed.
User Action: Set an event facility, and try the operation again.
NOEXCBRE
Message: no exception breaks were set
Severity: Informational
Explanation: A CANCEL BREAK/EXCEPTION command was entered when
exception breaks were not in effect. The CANCEL BREAK/EXCEPTION
command had no effect.
User Action: None. This message is informational.
NOEXHND
Message: no exit handlers are declared
Severity: Informational
Explanation: There are no user-mode exit handlers currently
declared.
User Action: None. This message is informational.
NOFIELD
Message: 'field_name' is not a field in this record
Severity: Warning
Explanation: An attempt was made to reference a field that is not
defined in the record.
User Action: Check the field specified to ensure that it is defined
in the record.
NOFREE
Message: no free storage available
Severity: Error
Explanation: The debugger has used all memory available.
User Action: Memory must be made available before the debugger can
continue executing. SET modules could be canceled, or the
debugging session can be stopped and system management can
increase the virtual memory on your system.
NOGLOBALS
Message: some or all global symbols not accessible
Severity: Informational
Explanation: The image was linked with the /NODEBUG qualifier, and
there are no global symbols in the symbol table.
User Action: Relink the image with the /DEBUG qualifier.
NOHLPLIB
Message: the debugger could not open the help library file
Severity: Warning
Explanation: The debugger could not open the help library file
because there was some low level file open error.
User Action: Check for user quotas being exceeded. For further
assistance and information on this problem check with your
system manager.
NOINPAVAIL
Message: input objects not available
Severity: Fatal
Explanation: The debugger was unable to open either DBG$INPUT or
SYS$INPUT.
User Action: Check that logicals used to point at input files or
devices are properly defined.
NOINPFOC
Message: debugger must have input focus to accept paste operation
Severity: Warning
Explanation: A writeable debugger window and, if applicable, a
text-entry field in that window must have the input focus before
the selection can be pasted to it from the clipboard.
User Action: Assign the input focus to a writeable window and, if
applicable, to the appropriate text-entry field.
NOINSTRAN
Message: cannot translate opcode at location address_value
Severity: Error
Explanation: The address specified in the EXAMINE command is not
the beginning of a valid instruction. This can be caused by
specifying an address that is in the middle of an instruction or
by an address that is in a data area.
User Action: Specify an address that contains a valid instruction.
NOKEYDEF
Message: cannot do keypad input, mode is set to NOKEYPAD
Severity: Warning
Explanation: The user is trying to define or set a keypad
definition which can not be performed due to the current
operating mode.
User Action: Use a terminal that supports keypad operations.
NOKEYPAD
Message: unable to set up keypad definitions
Severity: Informational
Explanation: An error status was returned from the Screen
Management Facility that indicates that the debugger keypad
definitions are corrupted.
User Action: Try to set keypad mode again (SET MODE KEYPAD). If
this fails to correct the problem submit a Software Performance
Report (SPR).
NOLASTVAL
Message: last value is not defined
Warning '\' is not currently defined.
User Action: Do not reference '\' until a DEPOSIT or EVALUATE
command has been performed.
NOLINXXX
Message: line_descriptor
Severity: Warning
Explanation: The line number range CZ:yyy specified on the DEBUGGER
command TYPE does not exist. There are no such line numbers in
the specified module (or the default module).
User Action: Re-enter the command specifying line numbers that do
exist.
NOLIST
Message: list of parameter values not allowed - check use of comma
(,)
Severity: Error
Explanation: A command that only accepts a single input value for a
parameter contains multiple values separated by commas (,).
User Action: Re-enter the command; specify one value. If
necessary, issue the command once for each value.
NOLOCALS
Message: image does not contain local symbols
Severity: Informational
Explanation: All the modules in the image were compiled or
assembled without traceback information. There is no local
symbol information in the image.
User Action: Recompile or reassemble the modules using the /DEBUG
qualifier and then relink them.
NOMAIN
Message: the debugger detected an error when trying to fetch the
main window from the Digital Resource Manager (DRM).
Severity: Fatal
Explanation: The debugger detected an error when trying to fetch
debuggers main window from the Digital Resource Manager (DRM).
This prevents the debugger from continuing this session.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
NOMARKCHNG
Message: [NO]MARK_CHANGE qualifier not applicable to display_name
display
Severity: Informational
Explanation: The /MARK_CHANGE and /NOMARK_CHANGE qualifiers can not
be applied to the indicated kind of display.
User Action: None.
NOMATCH
Message: no matches
Severity: Warning
Explanation: A SEARCH command was being used and no matches were
found
User Action: No action required
NOMORE
Message: wildcard request complete
Severity: Warning
Explanation: This is a debugger internal error code.
User Action: If the debugger reports this error please submit a
Software Performance Report.
NONEXPR
Message: nonexistent process
Severity: Error
Explanation: A process name or process identification specified in
a command is not valid.
User Action: Verify that the process name or identification is
correct and that the process was not already deleted. Also
verify that you have the required privilege to access the
process.
NONEXPRC
Message: process process-specification does not exist
Severity: Error
Explanation: The process-specification was not valid or the
specified process did not exist.
User Action: Verify that the process specification is correct and
that the process still exists and then re-enter the command.
NONUMSCOPE
Message: scope does not exist or is not in set module:
scope_number
Severity: Informational
Explanation: The debugger could not find the scope indicated by the
numbered scope in the scope list.
User Action: Set the module that contains that scope.
NONXTLIN
Message: next line for source display not defined
Severity: Warning
Explanation: The debugger command TYPE or SEARCH was entered
without specifying a line number (for example, the next line
after the last source line printed should be used). But no next
source line is currently defined.
User Action: Re-enter the command explicitly specifying the desired
line number.
NOOCCLDISP
Message: display_name display may not be occluded
Severity: Informational
Explanation: A display was positioned over the indicated display
that is not allowed to be occluded. The indicated display was
popped to the front.
User Action: You may wish to move the display so it is not occluded
by the display named in the message.
NOOUTAVAIL
Message: output objects are not available
Severity: Fatal
Explanation: The debugger was unable to open either DBG$OUTPUT or
SYS$OUTPUT.
User Action: Check that logicals used to point at output files or
devices are properly defined.
NOPACKMEMBODY
Message: 'symbol_name' is not a member of package body path_name Severity: Warning
NOPACKMEMSPEC
Message: 'symbol_name' is not a member of package spec path_name Severity: Warning
NOPRED
Message: logical predecessor not defined
Severity: Warning
Explanation: The logical predecessor of the identifier or
instruction referenced is not defined.
User Action: None. This message is informational.
NOPROMPT
Message: cannot delete, remove, unselect, or change kind of the
display_name display
Severity: Informational
Explanation: This display can not be deleted, removed, unselected,
or have it's kind changed.
User Action: None.
NORECSYM
Message: recursive symbol_type symbol definition encountered at or
near 'debugger_command_segment'
Severity: Error
Explanation: While attempting to expand a defined symbol, a
recursive symbol definition was encountered.
User Action: Redefine the symbol specified in the error message so
that it does not contain any circular dependencies and then
re-enter the command.
NORMAL
Message: successful debugger status
Severity: Success
Explanation: This is an internal status signal, it should never be
seen by the user. If this message does occur please submit a
Software Performance Report (SPR).
User Action: Submit a Software Performance Report (SPR).
NORSTBLD
Message: cannot build symbol table
Severity: Error
Explanation: The debugger is unable to build a symbol table because
of errors in the format of the image file.
User Action: Relink the image and, if the error is reproducible,
submit a Software Performance Report explaining how the image
file was created.
NOSAVPROG
Message: cannot save a program I/O display
Severity: Informational
Explanation: The SAVE command is not allowed on a program I/O
display since the debugger does not know the contents of the
display.
User Action: None.
NOSCOPE
Message: no scope exists to look up line line_number
Severity: Error
Explanation: The specified line_number cannot be found because
there is no current scope to look it up in.
User Action: Specify the module explicitly and retry the operation.
NOSCOPELIST
Message: a list of scopes is not allowed with this command.
Severity: Error
Explanation: You cannot enter a list of scopes with the previously
executed command.
User Action: Enter the command with only one scope item.
NOSCRDEV
Message: screen mode is not supported on this device screen mode
output is being lost
Severity: Informational
Explanation: The debugger output is being sent to a device that the
Screen Management Facility does can not write to. While the
debugger will continue to process commands, the screen mode
output will be lost.
User Action: Make sure the logical DBG$OUTPUT is pointed to a
device that the Screen Management Facility can write to.
NOSCRMODE
Message: screen mode is not supported on this terminal screen mode
is not set
Severity: Warning
Explanation: Screen mode is not allowed on the terminal type used
by the current session.
User Action: Use another terminal if screen mode is desired
NOSCROLL
Message: no scrolling display selected or missing display name
Severity: Error
Explanation: The user did not enter a display name with the
command, and the debugger attempted to use the display with the
SCROLL attribute. However, no display currently has the SCROLL
attribute.
User Action: Either reenter the command, specifying a display name,
or SELECT a display to have the SCROLL attribute and reenter the
command.
NOSCROLLDISP
Message: display_name display may not be scrolled Severity: Informational Explanation: This display can not be scrolled. User Action: None.
NOSETTERM
Message: the SET TERMINAL command is not supported on this terminal
Severity: Warning
Explanation: The SET TERMINAL command is not allowed on the
terminal being used for the current session
User Action: Use another type of terminal
NOSPAWN
Message: spawn command failed
Severity: Error
Explanation: The debugger failed to perform a SPAWN command or
SPAWN an editor. The error status returned from the SPAWN
command is appended to this error message.
User Action: If the SPAWN error is correctable, correct the problem
and reenter the command. If not, the SPAWN command is
unavailable.
NOSRCHSTR
Message: search string not set
Severity: Warning
Explanation: No current search string is defined for the debugger
command SEARCH. The SEARCH command was entered without a search
string indicating that the current search string should be used.
But no previous SEARCH command has been entered to define a
current search string.
User Action: Explicitly specify the desired search string on the
command.
NOSRCLIN
Message: no source line for address address_value
Severity: Warning
Explanation: No source line corresponds to the address
address_value specified on the debugger command EXAMINE/SOURCE.
User Action: None. This message is informational.
NOSTEPGO
Message: no STEP, GO, SET PROCESS/VISIBLE or CALL commands allowed
in screen displays
Severity: Error
Explanation: A STEP, GO, SET PROCESS/VISIBLE or CALL command was
used in a screen display command list. The debugger does not
allow the use of such commands in display command lists.
User Action: Re-specify the screen display command list without
using any of the disallowed commands.
NOSUCC
Message: logical successor not defined
Severity: Warning
Explanation: The logical successor of the referenced instruction or
identifier is not defined.
User Action: None. This message is informational.
NOSUCHBPT
Message: no such breakpoint
Severity: Informational
Explanation: The CANCEL BREAK command specified an address that is
not the address of a breakpoint.
User Action: Use the SHOW BREAK command to find the location of the
current breakpoints, and then cancel any of these breakpoints
that you want to cancel.
NOSUCHDISP
Message: no such display defined: display_name
Severity: Error
Explanation: The specified display <display_name, !AC> does not
exist.
User Action: Re-enter the command, specifying an existing display.
NOSUCHELP
Message: no such help topic or invalid HELP command
Severity: Warning
Explanation: The user has requested help for a topic for which
there is no help or the syntax used to request the help was
invalid
User Action: Try another topic or just type HELP for a topic list
NOSUCHIMG
Message: image image_name not found Severity: Error Explanation: The specified image <image_name, !AC> does not exist. User Action: Re-enter the command, specifying an existing image.
NOSUCHMODU
Message: module path_name is not in module chain
Severity: Error
Explanation: The module path_name, specified in the SET MODULE
command, does not exist in the image. This message can be
caused when: (1) a module name has been entered incorrectly or
(2) a module is compiled with the /NOTRACE switch.
User Action: Specify a module that is in the image.
NOSUCHPACK
Message: library package path_name is not in the symbol table Severity: Warning
NOSUCHSCOPE
Message: scope does not exist or is not in set module: scope_name
Severity: Warning
Explanation: The user has requested that the current scope be set
to a scope that is invalid for the current module
User Action: Correct the scope specification and reissue the
command
NOSUCHTASK
Message: no such task exists or no task satisfies criteria
Severity: Error
Explanation: The user entered a task expression that does not
correspond to an existing task, or no existing task satisfies
the task expression.
User Action: Reenter the command with a task expression that
specifies an existing task.
NOSUCHTPT
Message: no such tracepoint
Severity: Informational
Explanation: The CANCEL TRACE command specified an address that was
not the address of a tracepoint.
User Action: Use the SHOW TRACE command to display the current
tracepoints and then cancel any that you want to cancel.
NOSUCHWIND
Message: no such window defined: display_name
Severity: Error
Explanation: The specified, or defaulted window <window_name, !AC>
does not exist.
User Action: Reenter the command, specifying an existing window
name.
NOSUCHWPT
Message: no such watchpoint
Severity: Informational
Explanation: The CANCEL WATCH command specified an address that was
not the address of a watchpoint.
User Action: Use the SHOW WATCH command to display the current
watchpoints and then cancel any that you want to cancel.
NOSYMBOL
Message: symbol 'symbol_name' is not in the symbol table
Severity: Error
Explanation: The debugger could not find the symbol '<symbol_name,
!AC>' in its symbol table.
User Action: The symbol may have been entered incorrectly, in which
case the fix is to enter the symbol correctly. The other
possibility is that the module the symbol is defined in has not
been loaded into the debugger's symbol table; perform a SET
MODULE of the appropriate module.
NOSYMBOLR
Message: no symbol 'symbol_name' was declared in routine path_name Severity: Warning
NOTADAPROG
Message: program is not an ADA program; command ignored
Severity: Error
Explanation: The entered command applies only to Ada programs ;
since this is not an Ada program, the command cannot be
executed.
User Action: No user action required.
NOTARRAY
Message: type of variable is not array
Severity: Warning
Explanation: The variable being treated as an array has not been
defined as one.
User Action: Check that the correct variable reference is being
made.
NOTASTRUCT
Message: 'symbol_name' was not declared as a structure
Severity: Error
Explanation: A VAX BLISS-32 structure reference specified a symbol
symbol_name that was not declared a structure.
User Action: Re-enter the command with a valid symbol reference.
NOTATMAIN
Message: type GO to get to start of main program
Severity: Informational
Explanation: The debugger has started at the beginning of
LIB$INITIALIZE code.
User Action: If you want to get to the actual start of the main
program you should type GO at the debug prompt. The debugger
will allow the program to execute the LIB$INITIALIZE code and
then break at the start of the main program. If you'd like to
debug the LIB$INITIALIZE code you are positioned to do so at
this point.
NOTCURPC
Message: target of EXAMINE/OPERANDS is not the current PC results
may be unexpected
Severity: Informational
Explanation: The operands being examined will probably give
incorrect results, because the context for the instruction is
probably not set up properly. Specifically, the values of
registers used in address computations depend on the previous
series of instructions being executed, which was not done in
this case.
User Action: Only use EXAMINE/OPERANDS with .0\%PC
NOTDECTHREADS
Message: Program does not use DECthreads services.
Severity: Error
Explanation: The entered command applies only to programs using
DECthreads services.
User Action: No user action required.
NOTDEFINE
Message: defined_symbol was not defined
Severity: Informational
Explanation: The symbol was not found in the defined symbol table.
User Action: Check your spelling or use SHOW DEFINE to see what
symbols have been defined.
NOTIMPLAN
Message: expression_type is not implemented at command level
Severity: Error
Explanation: The expression_type is not supported at this type.
User Action: Specify a type of expression that the debugger
supports.
NOTINLOOP
Message: exitloop encountered when not in a loop
Severity: Warning
Explanation: An incorrect nesting of loops exist in the command
stream currently being executed.
User Action: Correct the command stream
NOTINSCOPE
Message: specified scope cannot be found in the default scope list
Severity: Error
Explanation: The specified scope was not in the current default
scope list.
User Action: Enter the command with a scope that is in the default
scope list.
NOTINST
Message: examined address is not the start of an instruction
Severity: Informational
Explanation: The examined address does not denote the start of an
instruction.
User Action: Specify an address that does denote the start of an
instruction.
NOTNUMSCOPE
Message: specified scope is not a numbered scope.
Severity: Error
Explanation: The SET SCOPE/CURRENT command requires a numbered
scope.
User Action: Enter the command with a numbered scope.
NOTORIGSRC
Message: original version of source file not found file used is
file_specification
Severity: Informational
Explanation: A source file was found for some module. But the
revision date and time or the file size indicates that this may
not be the same version of the file that was used in the
original compilation of the module. This warning message
indicates that future source line displays from this source file
may not correspond to the actual source used to compile the
module.
User Action: None, unless the original source is available. Then
you can use the debugger command SET SOURCE to indicate the
location of the source to the debugger.
NOTPTR
Message: variable must be of pointer or file type Severity: Warning Explanation: The variable should be a pointer or a file type. User Action: Specify a variable of pointer or file type.
NOTRACES
Message: no tracepoints are set, no opcode tracing Severity: Informational Explanation: There are no tracepoints or opcode tracing set. User Action: None. This message is informational.
NOTRAZERO
Message: Unable to find a trailing zero for ASCIZ object at address
address_value
Severity: Error
Explanation: The debugger was unable to find a trailing zero for
the specified ASCIZ string.
User Action: The ASCIZ string is missing a trailing zero, or the
object examined is not an ASCIZ string.
NOTRECORD
Message: variable is not record; cannot select component
component_name
Severity: Warning
Explanation: The user has requested a record operation on a
variable which is not a record.
User Action: Correct the command and reissue it
NOTREE
Message: SCAN tree or subtree not found SCAN error message Severity: Warning
NOTRUNDW
Message: the debugger is uncertain about the DECWindow
configuration.
Severity: Fatal
Explanation: The debugger is uncertain about the systems DECWindow
configuration
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
NOTTASKVAL
Message: expression does not specify an Ada task value
Severity: Informational
Explanation: The expression entered does not specify an Ada task
value. Only Ada task values are known as such in the symbol
table - CMA thread values are considered to be pointers.
User Action: Unless you are debugging CMA threads, reenter the
command, correctly specifying a task value.
NOTUISOSC
Message: the debugger will be unable to create a separate window;
OSC not enabled.
Severity: Informational
Explanation: The debugger requires OSC support enabled to create a
separate window (see SET MODE SEPARATE).
User Action: To allow the debugger to create a separate window,
type at DCL: DEFINE/SYSTEM UIS$VT_ENABLE_OSC_STRINGS TRUE. You
may wish to put this line in your private startup file.
NOTUISV30
Message: the debugger will be unable to create a separate window;
UIS too old.
Severity: Informational
Explanation: The debugger requires VWS V3.0 or later to create a
separate window (see SET MODE SEPERATE).
User Action: To allow the debugger to create a separate window,
install VWS V3.0 or later, and in your private startup file (or
at DCL), DEFINE/SYSTEM UIS$VT_ENABLE_OSC_STRINGS TRUE.
NOTUNQOVR
Message: symbol 'symbol_name' is overloaded use SHOW SYMBOL to find
the unique symbol names
Severity: Error
Explanation: More than one instance of the specified symbol
'<symbol_name, !AC>' exists in the user program. Without
further information, the debugger cannot determine which symbol
to use.
User Action: Re-enter the command, uniquely specifying the symbol
to be used. The SHOW SYMBOL command can be used to find the
unique symbol names.
NOTUPDATE
Message: instruction screen display not updated
Severity: Informational
Explanation: The instruction screen display was not updated because
of the preceding error message.
User Action: See the preceding error message.
NOTYPEINFO
Message: symbol type information not available please SET the
module that describes this type
Severity: Warning
Explanation: The user has requested information about a symbol
which cannot be provided in the current context.
User Action: SET the module containing the information and reissue
the command
NOUNIQUE
Message: symbol 'symbol_name' is not unique
Severity: Error
Explanation: The symbol specified was not in a default scope or was
defined in more than one scope.
User Action: Specify the scope of the symbol in a pathname or
change the default scope.
NOUNIVERSALS
Message: shareable image contains no universal symbols Severity: Informational Explanation: No universal symbols were found in the image. User Action: None.
NOUSREVNT
Message: no user-specified events are allowed; none are declared
Severity: Error
Explanation: A reference was made to an event, when no such event
had been defined (language not SCAN).
User Action: Reenter the last command, without specifying any
events.
NOVALATPC
Message: entity 'symbol_name' does not have a value at the current
PC (was optimized away)
Severity: Warning
Explanation: The value of the specified variable does not exist at
this point in the program's execution. For example, the
variable might be assigned to a register that is currently being
used for some other purpose.
User Action: Retry the operation at a point in the program's
execution when the variable is being referenced.
NOVALTYP
Message: 'symbol_name' does not have a value because it is a type
name
Severity: Warning
NOVALUE
Message: reference does not have a value Severity: Warning Explanation: The command specified a reference that has no value. User Action: Change the reference.
NOVECT
Message: no vector support - command cannot be performed
Severity: Error
Explanation: An attempt was made to modify vector state on a system
which has neither hardware vector capabilities nor the VVIEF.
This includes the EXAMINE vector-register, DEPOSIT
vector-register, and SET VECTOR_MODE commands.
User Action: Do not attempt to modify vector state on a system
which does not have vector capabilities.
NOWATCHES
Message: no watchpoints are set Severity: Informational Explanation: No watchpoints are set. User Action: None. This message is informational.
NOWATONOPT
Message: You cannot watch that entity, because it was not allocated
in m
Severity: Warning
Explanation: A watchpoint cannot be set on that entity due to
optimizations performed by the compiler
User Action: Recompile the program with no optimizations in effect
NOWATTAR
Message: cannot watch-protect target
Severity: Error
Explanation: You are attempting to set a /STATIC watchpoint on a
location that is either a register, is not in your program, or
is on the stack (P1 space). These kinds of locations cannot be
watchpointed with the /STATIC qualifier.
User Action: Either use the /NOSTATIC qualifier, or do not
watch-point this location.
NOWATVARIA
Message: cannot set watchpoints on variant records
Severity: Warning
Explanation: The user has requested that a watchpoint be set on a
variant record. This operation is not currently supported
User Action: No user action required
NOWATVARSTG
Message: watchpoints not allowed after SET TYPE ASCIC, ASCIW, or
ASCIZ
Severity: Warning
NOWBPT
Message: cannot insert breakpoint Severity: Informational Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
NOWILD
Message: no wildcard permitted Severity: Error Explanation: Wildcards are not permitted in this context User Action: Re-enter the command without using wildcards
NOWILDFIL
Message: file name, type, and version cannot be wildcarded
Severity: Error
Explanation: The components of a file specification entered in a
SET SOURCE command may not be wildcarded.
User Action: Reenter the command without wildcarding any file
specification components.
NOWOPCO
Message: cannot replace breakpoint with opcode Severity: Fatal Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
NOWPROT
Message: cannot set protection Severity: Fatal Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
NO_SYNC_FROM_EXC_BRE
Message: Synchronize can not be done from an exception break.
Severity: Error
Explanation: A synchronize command can not be done from an
exception break.
User Action: Do not perform a synchronization command when at an
exception break.
NPROMPT
Message: the debugger could not properly setup the state to accept
input.
Severity: Fatal
Explanation: The debugger it could not properly setup the state to
accept input. This prevents the debugger from continuing this
session.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
NULLPTR
Message: cannot dereference null pointer Severity: Warning
NUMCONLONG
Message: numeric constant too long, please shorten Severity: Error Explanation: A number entered in the command line is too long. User Action: Reenter the command, shortening the long number.
NUMTRUNC
Message: number truncated
Severity: Informational
Explanation: The number entered is greater than the largest signed
longword integer. The value has been truncated to the the
largest signed integer.
User Action: None.
OBJECTINV
Message: requested object is invalid Severity: Fatal Explanation: This message indicates an internal debugger error. User Action: Submit an SPR.
OBJPTRINV
Message: the pointer associated with the requested object is
invalid
Severity: Fatal
Explanation: This message indicates an internal debugger error.
User Action: Submit an SPR.
OBJTYPMIS
Message: the type associated with the requested object is incorrect Severity: Fatal Explanation: This message indicates an internal debugger error. User Action: Submit an SPR.
OBSOLETE_1
Message: this message is available for reuse Severity: Warning Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_10
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_11
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_12
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_13
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_14
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_15
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_16
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_17
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_18
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_19
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_20
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_21
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_22
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_23
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_24
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_25
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_28
Message: this message is available for reuse Severity: Warning Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_29
Message: this message is available for reuse Severity: Warning Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_30
Message: expression does not specify a task value
Severity: Error
Explanation: The expression entered does not specify a task value.
The command entered requires a task value.
User Action: Reenter the command, correctly specifying a task
value.
OBSOLETE_7
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_8
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OBSOLETE_9
Message: this message is available for reuse Severity: Informational Explanation: This message is obsolete, and should never be seen. User Action: Please submit a Software Performance Report.
OPCDEC
Message: no support for G/H instructions at or near opcode_name Severity: Warning
OPNOTALLOW
Message: operator 'operator_symbol' not allowed on given data types
Severity: Error
Explanation: The debugger encountered a problem when performing the
operation '<operator_symbol, !AC>' on the specified operands.
This may be a data type conversion error.
User Action: Reenter the command, specifying compatible operands.
OPSYNTAX
Message: instruction operand syntax error for operand number
operand_number
Severity: Error
Explanation: The debugger encountered an error in one of the
operands of a VAX instruction.
User Action: If the instruction was entered by the user, reenter
the instruction, correcting the operand error. If not, then
there may be an error in the user program instructions.
OUTPUTLOST
Message: output being lost, both NOTERMINAL and NOLOG are in effect
Severity: Informational
Explanation: The SET OUTPUT command has set the output conditions
to NOTERMINAL and NOLOG; consequently, the output is not
displayed on the terminal or written to a log file. The output
normally displayed by the debugger will not be available.
User Action: Use the SET OUTPUT command to send output to the
terminal or to a log file.
PACSIZREQ
Message: packed size required Severity: Warning Explanation: A size parameter is required User Action: Supply a size parameter and reissue the command
PARENREQ
Message: parenthesis required in 'debugger_command_segment
/TYPE=(X)'
Severity: Warning
Explanation: The debugger_command_segment is either SET TYPE,
DEPOSIT, or EXAMINE.
User Action: Place parentheses around the type of expression
specified
PARSTKOVR
Message: parse stack overflow, simplify expression
Severity: Warning
Explanation: The expression was too complex for the debugger to
evaluate.
User Action: Simplify the expression.
PASTHRU
Message: The primary handler should ignore this signal
Severity: Success
Explanation: This is an internal status signal, it should never be
seen by the user. If this message does occur please submit a
Software Performance Report (SPR).
User Action: Submit a Software Performance Report (SPR).
PATHNOTACP
Message: pathname qualifiers (path_name) not allowed in SHOW SYMBOL
data name
Severity: Warning
Explanation: The user has issued a command with invalid syntax
User Action: No user action required
PATHTLONG
Message: too many qualifiers on name
Severity: Error
Explanation: There are too many pathname elements in the entered
pathname for the debugger to handle.
User Action: Shorten the pathname entered, either by abbreviating
the pathname, defining a symbol for the pathname, or setting a
search scope so that you can use a shorter pathname.
PATHTOOLONG
Message: pathname too long at path_name
Severity: Error
Explanation: The entered pathname is too long for the debugger to
handle.
User Action: Shorten the pathname entered, either by abbreviating
the pathname, defining a symbol for the pathname, or setting a
search scope so that you can use a shorter pathname.
PCNOTALL
Message: PC not allowed in context for operand number
operand_number
Severity: Error
Explanation: Using the PC as an operand in the entered instruction
is not allowed.
User Action: If the instruction was entered by the user, reenter
the instruction, without using the PC in the operand. If not,
then there may be an error in the user program instructions.
PLICVTERR
Message: PLI conversion error at or near opcode_name
Severity: Error
Explanation: An error occurred in the PL/I RTL performing a data
type conversion, for the object <opcode_name, !AC>.
User Action: Reenter the command, specifying a legitimate object
for the operation desired.
PREDEPTNOT
Message: predefined eventpoint(s) not canceled
Severity: Informational
Explanation: Any existing predefined eventpoints have not been
canceled as the result of a CANCEL command.
User Action: Specify the /PREDEFINED qualifier with the CANCEL
command to cancel predefined eventpoints.
PROFRANOT
Message: proper frame not found on call stack for path_name
Severity: Warning
Explanation: You attempted to look at a variable in a routine
invocation that does not exist.
User Action: Specify a routine or routine invocation that is
currently active.
PROMPTCLEN
Message: display_name display width not changed, must be full width
of screen
Severity: Informational
Explanation: This display's width can not be changed. It must be
the full width of the screen.
User Action: None.
PROMPTOCCL
Message: display_name display now occludes some or all of
display_name display's text
Severity: Informational
Explanation: This display now occludes some or all of the specified
display.
User Action: None.
PROMPTRLEN
Message: display_name display length not changed, must be at least
2 lines long
Severity: Informational
Explanation: This display's length can not be changed to less than
the minimum value specified.
User Action: None.
PROVRFLOW
Message: too many levels of @ procedure nesting
Severity: Warning
Explanation: The user has nested indirect command processing too
deeply
User Action: Try to eliminate some of the levels of indirection or
look for a recursive invocation
PSHINARYNYI
Message: PUSH_INNER_ARRAY DST stack machine operator for array
'symbol_name' is not yet implemented
Severity: Error
Explanation: The named array is unconstrained, and its subscript
bounds live in different places at different points in the
program's execution. This cannot be denoted using DEBUG Symbol
Table (DST) features which this version of the debugger
supports.
User Action: Verify that you are using the latest releases of the
compiler and debugger. Examine the nearest object code which
references the variable and simulate the access algorithm by
hand.
PSHVALNYI
Message: PUSH_VALSPEC DST stack machine operator for variable
'symbol_name' is not yet implemented
Severity: Error
Explanation: The named variable's address is complex, and its
computation uses operands which live in different places at
different points in the program's execution. This cannot be
denoted using DEBUG Symbol Table (DST) features which this
version of the debugger supports.
User Action: Verify that you are using the latest releases of the
compiler and debugger. Try recompiling the application without
optimization. Examine the nearest object code which references
the variable and simulate the access algorithm by hand.
PXCN
Message: record object or record formal parameter must prefix
'CONSTRAINED
Severity: Warning
QUALREQ
Message: A direction qualifier must be specified with the EXPAND
and MOVE commands.
Severity: Error
Explanation: Direction ( UP, DOWN, LEFT, RIGHT ) information is
missing from the command.
User Action: Provide a direction with the command and try again.
QUOSTRLONG
Message: quoted string too long, please shorten
Severity: Error
Explanation: A quoted string was entered in a debugger command that
was too large for the debugger to handle.
User Action: Reenter the command, shortening the string entered.
READERR
Message: debugger input read error, force to exit
Severity: Warning
Explanation: Too many read errors have occurred from the input
command stream. The Debugger will exit after printing this
message
User Action: Check the physical integrity of the device containing
the input stream.
REFUSED
Message: attach request refused
Severity: Error
Explanation: Either you have attempted to attach to a process that
is your own process or that is not part of your process tree.
User Action: None. You cannot perform the attempted operation.
REGMASKHIDDEN
Message: register save mask hidden for stack frame frame_number
Severity: Warning
Explanation: Information on where the designated routine invocation
might save registers is in a module which has not been set.
Symbolic references to non-static variables of callers of this
routine may not be resolved correction by the debugger.
User Action: Set the module by using the SET MODULE or SET
MODULE/CALLS commands, or enable dynamic module setting with the
SET MODE DYNAMIC command. Then retry the action which produced
this message.
REGMASKMISSING
Message: register save mask missing for stack frame frame_number
Severity: Warning
Explanation: Information on where the designated routine invocation
might save registers is not available. Symbolic references to
non-static variables of callers of this routine may not be
resolved correction by the debugger.
User Action: Recompile or reassemble the modules using the /DEBUG
qualifier and then relink them.
REGREQ
Message: register required in context for operand number
operand_number
Severity: Error
Explanation: A register is required to establish context for the
specified operand.
User Action: If the instruction was entered by the user, reenter
the instruction, using a register with the specified operand.
If not, then there may be an error in the user program
instructions.
RENAMENOT
Message: Unable to look up 'symbol_name', object being renamed not
found in symbol table
Severity: Warning
Explanation: The user has requested an operation on an object that
was not found in the symbol table.
User Action: Correct and reissue the command
RESUMERR
Message: an error occurred while trying to resume execution of the
program
Severity: Error
Explanation: An error status was returned from the call to the
debugger-kernel service that resumes program execution.
Depending on the severity of the error, the program may or may
not have resumed execution.
User Action: Examine the error message after this message and
consider if the problem is related to a lack of quota or
otherwise related to your program's behavior. If so, then take
corrective action. If, after this evaluation, you believe that
the problem lies in the debugger, then submit a Software
Performance Report.
RETURNED
Message: control returned to process process_name Severity: Informational Explanation: Control has returned to the parent process. User Action: None.
RNDFCTROUT
Message: round factor out of range Severity: Warning Explanation: The DIBOL scale factor is out of the acceptable range
ROPRANDF
Message: reserved operand fault at or near opcode_name
Severity: Error
Explanation: The debugger encountered an opcode that is reserved to
Digital.
User Action: If the instruction was entered by the user, reenter
the instruction, without using an opcode reserved to Digital.
If not, then there may be an error in the user program
instructions.
RPCDBBDT
Message: Bad DTYPE for RPC Data Blocking. Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
RPCERR
Message: an internal inter-process communications error has
occurred
Severity: Error
Explanation: An internal communications error has occurred. The
reason is given in the message following this message.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
RPCINVDSC
Message: invalid RPC descriptor Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
RPCOVF
Message: RPC packet overflow Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
RPCUNF
Message: undefined RPC function encountered Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
RPCUNKARG
Message: undefined RPC argument encountered Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
RSTERR
Message: error in symbol table
Severity: Error
Explanation: There is a format error in the symbol table.
User Action: If the format error is not caused by a user program
error or a DEPOSIT command, submit a Software Performance
Report.
SCALEADD
Message: pointer addition: scale factor of scale_factor applied to
right/left argument
Severity: Informational
Explanation: Indicates the scale factor applied in computing the
address.
User Action: None.
SCALESUB
Message: pointer subtraction: scale factor of scale_factor applied
to right/left
Severity: Informational
Explanation: Indicates the scale factor applied in computing the
address.
User Action: None.
SCRNOACCESSR
Message: no read access to address address_value for display in
display_name
Severity: Error
SCRNOSRCLIN
Message: no source line for address address_value for display in
display_name
Severity: Warning
Explanation: No source line corresponds to the address
address_value specified on the debugger command EXAMINE/SOURCE.
User Action: None. This message is informational.
SCRNOTORIGSRC
Message: original version of source file not found for display in
display_name file used is file_specification
Severity: Informational
Explanation: A source file was found for some module. But the
revision date and time or the file size indicates that this may
not be the same version of the file that was used in the
original compilation of the module. This warning message
indicates that future source line displays from this source file
may not correspond to the actual source used to compile the
module.
User Action: None, unless the original source is available. Then
you can use the debugger command SET SOURCE to indicate the
location of the source to the debugger.
SCRTOBIG
Message: screen too big for Screen Mode width must be less than
maximum_width, height less than maximum_height
Severity: Error
Explanation: The current screen dimensions are too large for
debugger screen mode.
User Action: Change the screen dimensions to be small enough for
debugger screen mode.
SCRTOSMALL
Message: screen too small for Screen Mode width must be at least
minimum_width, height must be at least minimum_height
Severity: Error
Explanation: The current screen dimensions are too small for
debugger screen mode.
User Action: Change the screen dimensions to be large enough for
debugger screen mode.
SCRUNAOPNSRC
Message: unable to open source file file_specification for display
in display_name
Severity: Warning
Explanation: Source lines from the file file_specification cannot
be displayed because the debugger was unable to open the source
file (represented as file_specification). The accompanying VAX
RMS status message gives more information about the reasons for
the source file not being opened.
User Action: Examine the VAX RMS status message to determine the
reasons for the source file not being opened, and take the
appropriate action based on that information.
SCRUNAREASRC
Message: unable to read source file file_specification for display
in display_name
Severity: Warning
Explanation: Source lines from the file file_specification cannot
be displayed because the debugger was unable to read the source
file (represented as file_specification). The accompanying VAX
RMS status message gives more information about the reasons for
the source file not being opened.
User Action: Examine the VAX RMS status message to determine the
reasons for the source file not being read, and take the
appropriate action based on that information.
SETKEY
Message: keypad state has been set to state_name Severity: Informational Explanation: The specified keypad state has been set. User Action: None.
SETKEYERR
Message: error in processing SET KEY command: Severity: Warning Explanation: An error has occurred during a SET KEY command
SFCNTNEG
Message: shift count is negative Severity: Warning
SHOKEYERR
Message: error in processing SHOW KEY command:
Severity: Warning
Explanation: An error has occurred during the processing of a SHOW
KEY command
SHRPRC
Message: debugger will share user process
Severity: Informational
Explanation: An error occured while trying to create a subprocess
to run the main debugger image. This message indicates that the
debugger is reverting back to the old behavior of running in the
user process.
User Action: Correct the problem specified in the messages
preceding this message. If the problem cannot be solved, submit
a Software Performance Report (SPR).
SIDEFFECT
Message: operators with side effects not supported (++, --)
Severity: Warning
Explanation: The user has requested the use of an operator that has
side effects. This operation is not currently supported by the
Debugger.
User Action: Issue the operation and the side effects as individual
commands
SIGVECTRUNC
Message: signal vector was truncated
Severity: Warning
Explanation: The signal vector on this stack frame was too big to
fit into the DEBUG buffer.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
SIZEATOMIC
Message: only atomic data types are supported with 'SIZE Severity: Warning Explanation: SIZE is not supported on the item requested User Action: No user action required
SIZETRUNC
Message: size field truncated to 32 bits
Severity: Informational
Explanation: The size of the entry in a VAX BLISS-32 field
specification was larger then 32. The debugger set the entry
size to 32 and executed the command.
User Action: None. This message is informational.
SOURCESCOPE
Message: Source lines not available for .0
%PC Displaying source in a caller of the current routine
Severity: Informational
Explanation: There were no source lines available for the current
PC, so the debugger displayed the source lines for the calling
routine. The source lines may be unavailable because the code
associated with the current PC is not available (e.g. is in a
Digital-supplied shareable image) or was compiled or linked
/NODEBUG.
User Action: If source modules is available, then recompile and
relink the application using the /DEBUG qualifier.
SPAWNED
Message: subprocess spawned
Severity: Informational
Explanation: This message is output by the DEBUG command SPAWN when
it spawns a subprocess.
User Action: None. This message is informational.
SRCLINNOT
Message: source lines not available for module path_name
Severity: Warning
Explanation: The source lines from module CZ cannot be displayed or
searched because there is no source line information in the
symbol table for that module. Either the compiler is not able
to generate such information or the /DEBUG qualifier was not
used on the compilation or link command.
User Action: If the language in question supports source line
display, recompile and relink with the /DEBUG qualifier. If the
language does not support source line display, source lines will
not be available to the debugger for modules written in that
language.
SS_INT
Message: system service intercepted
Severity: Informational
Explanation: This error code is used by the debugger to indicate
that a system service has been intercepted.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
STEPINTO
Message: cannot step over PC = address_value
Severity: Informational
Explanation: The debugger was unable to step over the routine and
executed a step into the routine instead.
User Action: None. This message is informational.
STGTRUNC
Message: string truncated
Severity: Informational
Explanation: While processing the command, the debugger truncated a
text string.
User Action: The debugger failed to allocate a large enough buffer
to store the command output. Unless the reason for this is
apparent, submit a Software Performance Report (SPR).
STRNGPAD
Message: string operand lengths don't match, shorter padded with
blanks on the right
Severity: Informational
Explanation: The operands of a string comparison ( 'ABC' < 'AB' )
did not have the same length. The shorter one is blank extended
on the right.
User Action: Use strings of the same length.
STRTOOLONG
Message: strings longer than 255 characters not supported
Severity: Warning
Explanation: The string that was specified by the user is too large
for the debugger to handle
User Action: Try to redo the operation with a shorter string
STRUCSIZE
Message: structure size declared as num_units allocation units,
num_units was given
Severity: Informational
Explanation: The VAX BLISS-32 structure size was declared to be
num_units units but was referenced with num_units units.
User Action: None. This message is informational.
SUBOUTBND
Message: subscript subscript_number is out of bounds
Severity: Informational
Explanation: An attempt to subscript out of the bounds of an array
was made.
User Action: Change the value of the subscript.
SUBSCRNG
Message: subscript out of range, low/high bound for dimension
subscript_number is subscript_bound
Severity: Informational
Explanation: The subscript specification is not within the bounds
of the array.
User Action: Reenter the command, specifying a subscript
specification that is within the bounds defined for the array.
SUBSTRING
Message: invalid substring (start: low_bound, end: high_bound),
object has length string_size
Severity: Warning
Explanation: The substring specification (start: low_bound, end:
high_bound ) is not within the bounds defined for the data type.
User Action: Specify a substring specification within the bounds
defined for the data type.
SUPERDEBUG
Message: SUPERDEBUG not available
Severity: Error
Explanation: This is a Debug internal message. The user should
never see this message.
User Action: If you see this message, please submit an SPR
describing the circumstances.
SYMNOTACT
Message: non-static variable 'symbol_name' is not active
Severity: Warning
Explanation: The symbol symbol_name is not defined in an active
call frame.
User Action: Check the symbol specified; if correct, ensure that
you have defined the scope correctly.
SYMNOTFND
Message: no symbols matching defined_symbol are defined
Severity: Informational
Explanation: You attempted to use the SHOW SYMBOL command to show a
symbol that is not defined.
User Action: Verify that the symbol is defined and reenter the
command.
SYNCDONE
Message: vector synchronization complete
Severity: Error
Explanation: This signal is generated by the debugger kernel after
it has executed the synchronization instruction(s) necessary to
insure that all vector exceptions have been reported.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
SYNCREPCOM
Message: Synchronize reporting complete Severity: Informational Explanation: All current vector exceptions have been reported. User Action: None, this message is informational.
SYNC_ALREADY_IN_PROGRESS
Message: Synchronize already in progress.
Severity: Error
Explanation: Only one synchronize command is allowed at a time.
User Action: Do not perform a synchronization command until the
previous command has completed.
SYNERREXPR
Message: syntax error in expression at or near
'debugger_command_segment'
Severity: Error
Explanation: The debugger encountered text it does not understand
near '<debugger_command_segment, !AC>'.
User Action: Reenter the command, correcting the syntax error.
SYNERRLABEL
Message: syntax error in %LABEL construct, see HELP
Built_in_Symbols %LABEL
Severity: Error
Explanation: The debugger encountered an error in the use of the
%LABEL built-in symbol.
User Action: Reenter the command line, correcting the error in the
%LABEL construct.
SYNERRLINE
Message: syntax error in %LINE construct, see HELP Built_in_Symbols
%LINE
Severity: Error
Explanation: The debugger encountered an error in the use of the
%LINE built-in symbol.
User Action: Reenter the command line, correcting the error in the
%LINE construct.
SYNTAX
Message: command syntax error at or near 'debugger_command_segment'
Severity: Error
Explanation: The debugger encountered a command syntax error near
the element debugger_command_segment.
User Action: Re-enter the command.
TASKERROR
Message: error error_code from ADA multitasking
Severity: Error
Explanation: An unexpected error was returned to the debugger from
the Ada RTL. Additional information from the Ada RTL is
appended to this error message.
User Action: User action is dependent on the information returned
from the Ada RTL. If the error is not recoverable, the user may
wish to enter an SPR on the Ada compiler.
TASKNONULL
Message: Null task cannot be selected or modified Severity: Error
TASKNOREGS
Message: Task has no registers (it is the Null task) Severity: Error
TASKNOTABORT
Message: task not aborted; ADA multitasking is executing critical
section
Severity: Error
Explanation: The task specified may not be aborted at this time.
User Action: Retry the abort at a later time.
TASKNOTACT
Message: task cannot be made the active task; task is not ready or
running
Severity: Error
Explanation: The task specified to made the active task is not in
either the READY nor the RUNNING state. Tasks not in those
states cannot be made the active task. To determine the state
of the task, perform a SHOW TASK command.
User Action: If the task is in the TERMINATED state, no action is
possible. If the task is in the SUSPENDED state, the action
required to get the task in the READY or RUNNING state depends
on the user program and the state of the debugging session.
TASKNULL
Message: task is null; cannot set attributes of null task Severity: Error
TERMINATING
Message: process-specification is terminating
Severity: Informational
Explanation: The process process-specification has just finished
execution. All exit handlers in your program have run. Any SET
BREAK/TERMINATING or SET TRACE/TERMINATING events will now take
effect.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
TIMESLICE
Message: time slice interval has been slowed to 10.0 seconds
Severity: Informational
Explanation: DEBUG has changed the ADA time slice interval to 10.0
seconds. When you set watchpoints, DEBUG automatically
increases the value of pragma TIME_SLICE to 10.0. This is
because of interaction between the watchpoint implementation and
VAX Ada's time slicing. Slowing down the time-slice rate
prevents problems from occurring.
User Action: If the change in time-slice setting is undesirable,
then avoid the use of watchpoints.
TOOFEWSUB
Message: too few subscripts, array has num_dimensions dimensions
Severity: Warning
Explanation: The user has specified a symbol reference with too few
subscripts
User Action: Correct and reissue the command
TOOMANDIM
Message: too many dimensions in array Severity: Warning
TOOMANERR
Message: too many errors, some errors not reported
Severity: Informational
Explanation: Too many MISMODBEG or certain other errors occurred.
Other similar errors are not reported.
User Action: None. This message is informational.
TOOMANINV
Message: too many invocation numbers in symbol pathname Severity: Error
TOOMANPARM
Message: too many parameters on command Severity: Error
TOOMANSUB
Message: too many subscripts, array has num_dimensions dimensions
Severity: Warning
Explanation: The user has specified a symbol reference with too
many subscripts
User Action: Correct and reissue the command
UNAACCREG
Message: unable to access beyond end of register set
Severity: Error
Explanation: The command entered attempted to read or write beyond
the end of a register or register set.
User Action: Re-enter the command, insuring that you do not attempt
to access beyond the end of the register set.
UNACREDBGO
Message: unable to create DBG$OUTPUT, SYS$OUTPUT used Severity: Informational
UNACVT
Message: unable to convert radixvalue to datatype_name Severity: Warning Explanation: Debug was unable to perform the requested conversion User Action: No user action required
UNACVTBYTTAU
Message: error converting byte count into target addressable units
Severity: Error
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose both a copy of the
program being debugged and a logged debugging session that
reproduces the error.
UNALIGNED
Message: data is not aligned on a byte boundary
Severity: Warning
Explanation: The user has requested a type override that can not be
performed
User Action: No user action required
UNALLOCATED
Message: entity 'symbol_name' was not allocated in memory (was
optimized away)
Severity: Warning
Explanation: The requested entity is not available for use due to
optimizations performed by the compiler
User Action: Recompile the program with no optimizations in effect
UNAOPEDBGI
Message: unable to open DBG$INPUT, SYS$INPUT used Severity: Informational
UNAOPESCR
Message: unable to open DBG$OUTPUT for screen output Severity: Informational
UNAOPNHLP
Message: unable to open help library file_specification
Severity: Warning
Explanation: The help library file_specification cannot be opened
to look for the help you requested. The accompanying VAX RMS
status message gives you more information about the reasons for
the library not being opened.
User Action: Examine the VAX RMS status message to determine the
reasons for the help library not being opened, and take the
appropriate action based on that information. Also, verify that
the logical name DBG$HELP is either not defined, or is defined
to indicate the proper file.
UNAOPNINI
Message: unable to open initialization file file_specification
Severity: Informational
Explanation: The initialization file cannot be opened. The
accompanying VMS RMS status message gives you more information
about the reasons for the file not being opened.
User Action: Examine the VMS RMS status message to determine the
reasons for the initialization file not being opened, and take
action based on that information. Also, verify that the logical
name DBG$INIT is defined to indicate the proper file.
UNAOPNSRC
Message: unable to open source file file_specification
Severity: Warning
Explanation: Source lines from the file file_specification cannot
be displayed because the debugger was unable to open the source
file (represented as file_specification). The accompanying VAX
RMS status message gives more information about the reasons for
the source file not being opened.
User Action: Examine the VAX RMS status message to determine the
reasons for the source file not being opened, and take the
appropriate action based on that information.
UNAREASRC
Message: unable to read source file file_specification
Severity: Warning
Explanation: Source lines from the file file_specification cannot
be displayed because the debugger was unable to read the source
file (represented as file_specification). The accompanying VAX
RMS status message gives more information about the reasons for
the source file not being opened.
User Action: Examine the VAX RMS status message to determine the
reasons for the source file not being read, and take the
appropriate action based on that information.
UNASAVVAL
Message: unable to save value for defined_symbol, definition
ignored
Severity: Warning
UNASETIMG
Message: unable to set image image_name because it has no symbol
table
Severity: Informational
Explanation: The image is linked with the /NODEBUG qualifier, so
there is no symbol table.
User Action: Relink the image with the /DEBUG qualifier.
UNASETTAS
Message: unable to set visible task: registers not available Severity: Error
UNASWISTA
Message: Unable to create debugger stack, using program stack
Severity: Informational
Explanation: DEBUG failed to set the protection ($SETPRT) on the
DEBUG stack's guard pages. This message indicates an internal
debugger error.
User Action: Submit an SPR.
UNBPAREN
Message: unbalanced parentheses in expression Severity: Error
UNDEXPN
Message: undefined exponentiation at or near opcode_name Severity: Warning
UNDKEY
Message: state_name key key_name is undefined
Severity: Informational
Explanation: You attempted to use the SHOW/KEY or the DELETE/KEY
command to show or delete the definition of a key that is not
defined.
User Action: Verify that the key is defined and reenter the
command.
UNHANDLED
Message: The primary handler should now handle this unhandled
exception
Severity: Success
Explanation: This is an internal status signal, it should never be
seen by the user. If this message does occur please submit a
Software Performance Report (SPR).
User Action: Submit a Software Performance Report (SPR).
UNIMPLENT
Message: attempt to evaluate unimplemented type Severity: Warning
UNMTCHPARN
Message: unmatched left parenthesis found
Severity: Warning
Explanation: A left parenthesis (() was found, but the matching
right parenthesis ()) is missing.
User Action: Include the right parenthesis ()).
UNREQVQUAL
Message: Unreqcognized vector instruction qualifier specified at
'command_line'
Severity: Error
Explanation: The qualifier indicated in the shown command line
fragment is unreqcognized.
User Action: Specify a legal vector instruction qualifier.
UPBNDOPT
Message: upper bound of subrange was optimized away
Severity: Informational
Explanation: The upper bound of the specified subrange was
optimized away by the compiler. In place of the actual upper
bound, DEBUG used the hex value 7FFFFFFF.
User Action: None. This message is informational.
USREVNTERR
Message: user-specified event error code error_code returned by
user RTL
Severity: Error
VALNOTADDR
Message: value of variable 'symbol_name' not usable as address
Severity: Warning
Explanation: The value of the specified variable is not usable as
an address. The address must be a longword.
User Action: Modify the address and retry the operation.
VALRNG
Message: value is subscript_value, bounds are low_bound..high_bound
Severity: Informational
Explanation: An attempt to subscript out of the bounds of an array
was made.
User Action: Change the value of the subscript.
VARNESDEP
Message: variant nesting depth exceeds 20, cannot access record
component
Severity: Error
VECDIS
Message: debugger-generated vector disabled fault
Severity: Error
Explanation: This signal is generated by the debugger kernel while
it is processing a vector disabled fault that it has caused.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
VECREASON
Message: the reason values for this vector error are reason_values
Severity: Informational
Explanation: An internal error has occurred with the debuggers use
of vector instructions. The particular error code has two
values which are associated with it, which more fully explain
what went wrong.
User Action: None.
VECSCP0
Message: vector registers can be accessed only in scope 0
Severity: Error
Explanation: An attempt was made to reference a vector register
from a scope other than scope 0. DEBUG will not accept a
command which specifies any other scope for a vector register.
User Action: If the current scope has been set to a scope other
than scope 0 (using the SET SCOPE command), use an explicit 0\
pathname to access the vector register.
VECTSUBRNG
Message: vector register subscript out of bounds, bounds are
low_bound..high_bound
Severity: Error
Explanation: An attempt to subscript out of the bounds of an array
was made.
User Action: Change the value of the subscript.
VERIFYICF
Message: opening/closing command procedure file_specification
Severity: Informational
Explanation: The debugger is verifying a command procedure. This
message is displayed before the command procedure is executed
and after all the commands have been displayed.
User Action: None. This message is informational.
VERSIONNUM
Message: the debugger_type debugger has RPC version
major_version/minor_version
Severity: Informational
Explanation: This message is to inform you of the version number(s)
of the main and kernel debuggers. It will only appear as part
of another message, such as INCOMVERSION.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
VFLTDIV
Message: Reserved operand, encoded as floating divide by zero
Severity: Error
Explanation: During a floating-point operation, an attempt was made
to divide by zero.
User Action: Examine the code that caused the fault. Verify that
the operands or variables are specified correctly. Verify that
the encoded reserved operand was not deposited by a
non-floating-point operation.
VFLTOVF
Message: Reserved operand, encoded as floating overflow
Severity: Error
Explanation: During a floating-point operation, a floating point
value exceeded the largest representable value for that data
type.
User Action: Examine the code that caused the fault. Verify that
the operands or variables are specified correctly. Verify that
the encoded reserved operand was not deposited by a
non-floating-point operation.
VFLTROP
Message: Reserved operand, encoded as floating reserved operand
Severity: Error
Explanation: During a floating-point operation, an attempt is made
to divide by zero.
User Action: Examine the code that caused the fault. Verify that
the operands or variables are specified correctly. Verify that
the encoded reserved operand was not deposited by a
non-floating-point operation.
VFLTUND
Message: Reserved operand, encoded as floating underflow
Severity: Error
Explanation: An arithmetic exception condition occurred as a result
of floating-point underflow.
User Action: Examine the code that caused the fault. Verify that
the operands or variables are specified correctly. Verify that
the encoded reserved operand was not deposited by a
non-floating-point operation.
WATCHSETUP
Message: instruction at current PC may trigger a watchpoint
Severity: Error
Explanation: This signal is generated by the debugger kernel when
it is about to execute an instruction that may trigger a
watchpoint.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
WATCHSIZE
Message: cannot WATCH variables longer than 512 bytes Severity: Error
WATNOWCAN
Message: watchpoint now cancelled
Severity: Informational
Explanation: This message is a sub-message to WATVARSCP, WATVARPTR,
and WATVARPROT. This message indicates that the original
watchpoint has been cancelled (is no longer active).
User Action: None. This message is informational.
WATNOWWAT
Message: now watching variable name
Severity: Informational
Explanation: This message is a sub-message to WATVARSCP and
WATVARPTR. This message indicates the new name under which a
variable which either went out of scope or whose pointer(s)
changed is addressed by the debugger. If this message appears,
the watchpoint is still active under this new name.
User Action: None. This message is informational.
WATVARGSGONE
Message: global section associated with watched variable variable
name has been unmapped
Severity: Informational
Explanation: The global-section which contained a global-section
watchpoint is no longer mapped by any process that is under
debugger control. This message is always followed by the
WATNOWCAN message, since the debugger must delete the
watchpoint.
User Action: No action necessary.
WATVARGSOVR
Message: watched variable overlaps into a global section
Severity: Error
Explanation: The specified variable spans a range of virtual memory
which includes a global-section and a private-section. A
watched variable must either be entirely in a global-section or
entirely in a private-section.
User Action: Do not use watchpoint on this address.
WATVARNOWGBL
Message: watched variable variable name has been re-mapped to a
global section
Severity: Informational
Explanation: The program mapped a global-section over a watched
variable. This message indicates that the debugger made the
watchpoint a global-section watchpoint. If the global-section
is mapped by more than one process that is under the debugger
control, the watched variable will be watched in each process
that is mapped to the global section.
User Action: No action necessary.
WATVARPROT
Message: watched variable variable name is no longer accessible
Severity: Informational
Explanation: Some action by the program has made the target
variable inaccessible to the debugger. The program might have
deleted the virtual memory which contains some part of the
variable or one of the pointers in the pointer chain to the
variable, or the program might have set the protection of such
virtual memory such that the debugger can not read it. This
message is always followed by the WATNOWCAN message, since the
debugger must delete the watchpoint.
User Action: None. This message is informational.
WATVARPTR
Message: watched variable variable name now points to a different
address
Severity: Informational
Explanation: Some pointer in the variable reference has changed
value. This message is accompanied by a further message
indicating whether the debugger has cancelled the watchpoint or
re-defined the watchpoint to address the original data by a
different name.
User Action: None. This message is informational.
WATVARREMAP
Message: watched variable variable name touches a page which has
been re-mapped by the user program
Severity: Informational
Explanation: Some action by the user program has made it impossible
for the debugger to set the protection on part or all of the
variable. The debugger will therefore not detect changes to the
variable. This message is always followed by the WATNOWCAN
message, since the debugger must delete the watchpoint.
User Action: None. This message is informational.
WATVARSCP
Message: watched variable variable name has gone out of scope
Severity: Informational
Explanation: The identified variable is no longer accessible by its
original name. The program may have returned from the routine
in which the variable was defined, or it may have called another
routine. This message is accompanied by a further message
indicating whether the debugger has cancelled the watchpoint (in
the case that the variable is truly gone) or re-defined the
watchpoint to address the same data by a different name.
User Action: None. This message is informational.
WIDTHDIFF
Message: desired width of display_width is not allowed, width is
set to display_width
Severity: Informational
Explanation: After creating the display pasteboard using the SMG
routine SMG$CREATE_PASTEBOARD, DEBUG found that the display
width was not in the range 20-255.
User Action: Issue the DCL command SHOW TERMINAL and verify that
the terminal width is correct and in the range 20-255.
WORKSTACMD
Message: the command debugger-command is only supported on VWS
workstations
Severity: Warning
Explanation: The debugger only supports the command
debugger-commandon workstations running VWS.
User Action: None. This capability of the debugger does not exist
for your terminal or machine.
WPTTRACE
Message: non-static watchpoint, tracing every instruction
Severity: Informational
Explanation: Setting a watchpoint on a non-static location such as
the stack or on a register forces the debugger to trace every
instruction that is executed. This will slow down execution of
your program by a considerable amount.
User Action: If you do not want execution of your program slowed
down, then you must cancel the watchpoint.
WRITE_FAILED
Message: an attempt to write into a memory location failed Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
WRITE_INTO_KERNEL
Message: cannot write into the debugger kernel's address space Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
WRITE_INTO_KERNEL_STACK
Message: cannot write into the debugger kernel's stack Severity: Error Explanation: This message indicates an internal debugger error. User Action: Submit a Software Performance Report.
ZERLENDST
Message: zero length DST record has been ignored (compiler error)
Severity: Informational
Explanation: A zero-length DST record was encountered within a
module. This message normally indicates a compiler error.
User Action: Submit a Software Performance Report.
ZEROINCR
Message: increment for ranged examine is zero; exiting loop
Severity: Informational
Explanation: While performing a ranged examine, DEBUG no successor
to the current data item was found because the length of the
current data item was zero bytes.
User Action: None. This message is informational.
Multiprocess
To debug a multiprocess program, you must first set up a
multiprocess debugger configuration (see help on the
Multiprocess_Configuration subtopic). Other subtopics describe
concepts, commands, and qualifiers used in multiprocess
debugging.
For summary descriptions of commands and qualifiers associated
with multiprocess debugging, see help on New_Features V5.2.
Additional information available:
Activation OptionsAdvanced ConceptsCommand BroadcastGlobal Section Watchpoints
Multiprocess ConfigurationProcess InformationProgram ExecutionPrompt Suffix
Screen Mode FeaturesSpecifying ProcessesTermination OptionsVisible Process
Activation Options
You can bring a process under debugger control in any of the
following ways:
o You execute the image with the RUN[/DEBUG] command.
o If one or more processes in the same job tree as the
debugging session are waiting to be connected to the
debugger, you enter one of the following debugger commands:
* A command that starts execution, such as STEP.
* The CONNECT command, without specifying a parameter. This
is preferable if you do not want the program to execute.
For more information, see help on the CONNECT command.
o You use the CONNECT command and specify a process that is
running an image. This interrupts the execution of the image
and brings it under debugger control.
o You enter a Ctrl/Y--DEBUG sequence at the DCL level to
interrupt an image running without debugger control. For
more information, see help on CTRL_Y.
o A program not under debugger control signals SS$_DEBUG. For
more information, see help on SS$_DEBUG.
An image is debuggable if it was not linked with the
/NOTRACEBACK qualifier. Also, full symbolic information is
available only if the image's modules were compiled and linked
with the /DEBUG qualifier.
When a process comes under debugger control, it is initially in
the activated state (as indicated in a SHOW PROCESS display).
This condition is traced by default, as if you had entered the
SET TRACE/ACTIVATING command. As for a one-process program, the
debugger prompt is displayed when the first process comes under
debugger control. This lets you enter debugger commands before
the main image has started execution.
Within a debugging session, the debugger assigns a process
number sequentially, starting with process 1, to each process
that comes under debugger control. If a process is terminated
by an EXIT or QUIT command, its process number is not reused
during that debugging session.
Advanced Concepts
The debugging configuration (default or multiprocess) is
entirely controlled by the definition of DBG$PROCESS. If some
processes in a job tree have different definitions of
DBG$PROCESS, the resulting debugging configuration can be very
confusing. The value of DBG$PROCESS is checked when the kernel
debugger is first invoked.
Consider the following scenario:
$ DEFINE/JOB DBG$PROCESS MULTIPROCESS
$ RUN TEST
VAX DEBUG X5.0-3 MP
DBG_1> SET BREAK/ACTIVATING;GO
break at program activation in %PROCESS_NUMBER 2
DBG_2> SHOW PROCESS/ALL
Number Name Hold State Current PC
1 SMITH interrupted TEST\%LINE 50
* 2 SMITH_1 activated SUB1\%LINE 71
DBG_2> SPAWN DEFINE DBG$PROCESS DEFAULT
DBG_2> SET BREAK %LINE 100;GO ! Assume that TEST creates a new process
VAX DEBUG V5.0-3 MP
break at %LINE 100 in %PROCESS_NUMBER 2
DBG> SHOW PROCESS/ALL
Number Name Hold State Current PC
* 3 SMITH_2 activated MYPROG\%LINE 10
DBG_2> SHOW PROCESS/ALL
Number Name Hold State Current PC
1 SMITH interrupted TEST\%LINE 50
* 2 SMITH_1 break SUB1\%LINE 100
The VMS job tree at this point is symbolized in the following
figure, which shows a mixed separate-process and multiprocess
configuration:
SMITH
+--------+
| TEST |
/|--------|\
SMITH_1 / |kernel | \ SMITH_2
+--------+ |debugger| +--------+
| SUB1 | +--------+ | SUB2 |
|--------| | |--------|
|kernel | | |kernel |
|debugger| | |debugger|
+--------+ | +--------+
| | |
+--------------+ +--------+
| main | |main |
| debugger | |debugger|
+--------------+ +--------+
Command Broadcast
By default, process-specific commands execute in the context of
the visible process. The DO command lets you execute commands
in the context of one or more processes currently under debugger
control. This is also called as broadcasting commands to
processes.
Use the DO command without a qualifier to execute commands in
the context of all processes. For example, the following
command executes the SHOW CALLS command for all processes
currently under debugger control (processes 1 and 2, in this
case):
DBG_1> DO (SHOW CALLS)
For %PROCESS_NUMBER 1
module name routine name line rel PC abs PC
*MAIN_PROG MAIN_PROG 21 0000001E 0000041E
For %PROCESS_NUMBER 2
module name routine name line rel PC abs PC
*TEST TEST 1+2 0000000B 0000040B
As indicated in this example, the debugger identifies the
process associated with any debugger output.
Use the DO/PROCESS= command to execute commands in the context
of a specific process. For example, the following command
executes the SET MODULE START and EXAMINE X commands in the
context of process 2:
DBG_1> DO/PROCESS=(%PROC 2) (SET MODULE START; EXAMINE X)
Global Section Watchpoints
You can set watchpoints in global sections. A global section is
a region of virtual memory 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 changes the contents of that location.
Note that 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 not yet mapped to a global
section, the watchpoint is treated as a conventional static
watchpoint. For example:
DBG_1> SET WATCH ARR(1)
DBG_1> SHOW WATCH
watchpoint of PPL3\ARR(1)
When ARR is subsequently mapped to a global section, the
watchpoint is automatically treated as a global section
watchpoint and an informational message is issued. For example:
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
1: PROGRAM PPL3
predefined trace on activation at routine PPL3 in %PROCESS_NUMBER 3
1: PROGRAM PPL3
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
Once the watched location is mapped to a global section, the
watchpoint is visible from each process. For example:
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]
Multiprocess Configuration
The multiprocess configuration enables one debugging session to
communicate with and control images running in several
processes. To specify the multiprocess configuration, enter the
following command before invoking the debugger:
$ DEFINE/JOB DBG$PROCESS MULTIPROCESS
Use the /JOB qualifier to make the logical definition job wide.
This ensures that any subprocesses created (spawned) by the
program being debugged can be controlled from the same debugging
session. The debugging configuration (default or multiprocess)
depends only on the current definition of DBG$PROCESS. It does
not depend on whether a program runs in more than one process.
For more information, see help on Debugging_Configurations.
Additional information available:
Examples
$ DEFINE/JOB DBG$PROCESS MULTIPROCESS
$ RUN PROG1
...
DBG_1>
In this example, the DEFINE/JOB command specifies the
multiprocess configuration. This is indicated by the
process-specific prompt suffix (_1) which is displayed initially
when the debugger is invoked with the RUN command. The suffix
indicates that execution is suspended in process 1, the first
process brought under debugger control. Process 1 is currently
the visible process --- the context for executing
process-specific commands like STEP and EXAMINE.
Process Information
The SHOW PROCESS command displays information about any
processes currently under control of your debugging session. If
you do not specify a process, SHOW PROCESS displays information
about the visible process. For more information, see help on
the SHOW PROCESS command.
Program Execution
When you enter a command that starts program execution, such as
STEP or GO, the command executes in the context of the visible
process. However, images in any other unheld processes
(processes that have not been put on hold with a SET PROCESS
/HOLD command) are also allowed to execute. Similarly, if you
use the DO command to broadcast a command to start execution in
one or more processes, the command executes in the context of
each specified unheld process, but images in any other unheld
processes are also allowed to execute. In all cases, a hold
condition is ignored in the visible process. (For more
information, see help on the Holding_Processes subtopic.)
Once execution starts, the way in which it continues depends on
whether SET MODE NOINTERRUPT is in effect. By default (SET MODE
INTERRUPT), execution continues until it is suspended in any
process. At that point, execution is interrupted in any other
processes that were executing images, and the debugger prompts
for input.
Additional information available:
Holding Processes
A command that starts execution executes in the context of the
visible process, but it also causes execution to start in other
processes.
If you want to inhibit execution in a process, put it on hold.
For example, the following SET PROCESS /HOLD command puts
process 2 on hold. The subsequent STEP command executes in the
context of process 1, the visible process. Execution also
starts in any other processes that are not on hold, but not in
process 2:
DBG_1> SET PROCESS/HOLD %PROC 2
DBG_1> STEP
A SHOW PROCESS display indicates whether a process is on hold.
For example:
DBG_1> SHOW PROCESS/ALL
Number Name Hold State Current PC
* 1 JONES step MAIN_PROG\%LINE 24
2 JONES_1 HOLD interrupted TEST\%LINE 3+1
DBG_1>
To unhold a process, use the SET PROCESS/NOHOLD command,
specifying the process that you want released from the hold
condition.
Note that a hold condition is ignored in the visible process.
Therefore, the SET PROCESS/HOLD/ALL command is a convenient way
to confine execution to the visible process. In the following
example, execution starts only in the visible process:
DBG_1> SET PROCESS/HOLD/ALL
DBG_1> STEP
This feature is useful if, for example, you want to use the CALL
command to execute a dump routine that is not part of the
execution stream of your program.
The preceeding discussions also apply if you use the DO command
to broadcast a GO, STEP, or CALL command to several processes.
The GO, STEP or CALL command executes in the context of each
specified unheld process, and execution also starts in any other
unheld process. The following example illustrates the execution
behavior when all processes are put on hold and commands are
broadcast to all processes. Execution starts only in the
visible process (process 1, in this example):
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>
SET_MODE_NOINTERRUPT
Provides an alternative mode of execution to the default mode
(SET MODE INTERRUPT) and lets execution continue without
interruption in other processes when it is suspended in some
process. This is especially useful if, for example, you want to
broadcast a STEP command to several processes with the DO
command and complete execution of the STEP in all these
processes.
Example:
DBG_1> SET MODE NOINTERRUPT
DBG_1> DO (STEP)
In this example, the DO command executes the STEP command in the
context of all processes currently under debugger control. The
visible process and any other unheld processes start execution.
Because SET MODE NOINTERRUPT is in effect, the prompt is
displayed only after the STEP has completed (or execution has
been otherwise suspended at a breakpoint or watchpoint) in all
processes.
When SET MODE NOINTERRUPT is in effect, as long as execution
continues in one or more processes, the debugger does not prompt
for input. In such cases, use Ctrl/C to interrupt all processes
and display the prompt.
For more information, see help on SET MODE NOINTERRUPT.
Prompt Suffix
In a multiprocess configuration, dynamic prompt setting is
enabled by default. This means that the prompt has a
process-specific suffix that indicates the process number of the
visible process. The debugger assigns a process number
sequentially, starting with process 1, to each process that
comes under debugger control within a debugging session.
Dynamic prompt setting, as well as the process-specific prompt
suffix, is controlled by the SET PROMPT/[NO]SUFFIX command.
Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX),
the debugger prompt always identifies the visible process.
Screen Mode Features
Screen-mode displays, whether predefined or user-defined, are
associated with the visible process by default. For example,
SRC shows the source code where execution is suspended in the
visible process, OUT shows the output of commands executed in
the context of the visible process, and so on.
The DISPLAY/PROCESS command can create process-specific displays
or make existing displays process specific. 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. For example, the
following command creates the automatically updated source
display SRC_3, which shows the source code where execution is
suspended in process 3:
DBG_2> DISPLAY/PROCESS=(%PROC 3) SRC_3 AT RS23 -
SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC)
You assign attributes to process-specific displays as for
displays that are not process-specific. For example, the
following command makes display SRC_3 the current scrolling and
source display -- that is, the output of SCROLL, TYPE, and
EXAMINE/SOURCE commands are then directed at SRC_3:
DBG_2> SELECT/SCROLL/SOURCE SRC_3
If you use DISPLAY/PROCESS without specifying a process, the
specified display is then specific to the process that was the
visible process when you entered the command. For example, the
following command makes OUT_X specific to process 2:
DBG_2> DISPLAY/PROCESS OUT_X
The /SUFFIX qualifier appends a process identifying suffix that
denotes the visible process to a display name. Use /SUFFIX
directly after a display name in any command that specifies a
display (for example, DISPLAY, EXTRACT, SAVE). It is especially
useful within command procedures, in conjunction with display
definitions or with key definitions bound to display
definitions.
In a multiprocess configuration, the predefined tracepoint on
process activation automatically creates a new source display
and a new instruction display for each new process that comes
under debugger control. The displays have the names SRC_n and
INST_n, respectively, where n is the process number. These
displays are initially marked as removed. They are
automatically canceled by the predefined tracepoint on process
termination.
Additional information available:
Keypad Definitions
Several predefined keys let you configure your screen with the
process-specific source and instruction displays that are
created automatically when a process is activated. The
following table identifies the relevant keypad keys and their
general effect. Use the SHOW KEY command to check the exact
commands issued by these key combinations.
State Key Command Invoked or Function
----------------------------------------------------------------
GOLD COMMA SELECT/SOURCE %NEXT_SOURCE. Selects the next
source display in the display list as the current
source display. (This function was previously
assigned to BLUE-KP3.)
GOLD KP9 SET PROCESS/VISIBLE %NEXT_PROCESS. Makes the next
process in the process list the visible process.
BLUE KP9 Displays two predefined process-spespecific source
displays, SRC_n. These are located at Q1 and Q2,
respectively, for the visible process and next
process on the process list.
BLUE KP7 Displays two sets of predefined process-specific
source and instruction displays, SRC_n and INST_n.
These comprise source and instruction displays for
the visible process at Q1 and RQ1, respectively,
and source and instruction displays for the next
process on the process list at Q2 and RQ2,
respectively.
BLUE KP3 Displays three predefined process-specific source
displays, SRC_n. These are located at S1, S2,
and S3, respectively, for the previous, current
(visible), and next process on the process list.
BLUE KP1 Displays three sets of predefined process-specific
source and instruction displays, SRC_n and INST_n.
These comprise source and instruction displays for
the visible process at S2 and RS2, respectively;
source and instruction displays for the previous
process on the process list at S1 and RS1, respec-
tively; and source and instruction displays for
the next process on the process list at S3 and
RS3, respectively.
Specifying Processes
When specifying processes in debugger commands, you can use any
of the forms listed in the following table, except when
specifying processes with the CONNECT command.
CONNECT brings a process that is not yet known to the debugger
under debugger control. Therefore, when specifying a process
with the CONNECT command, you can use only its VMS process name
or VMS process identification (PID). You cannot use its
(debugger) process number or any of the process built-in symbols
(for example, %NEXT_PROCESS).
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
You can omit the %PROCESS_NAME built-in symbol when entering
commands. For example:
DBG_2> SHOW PROCESS %PROC 2, JONES_3
You can define a symbol to represent a group of processes
(DEFINE/PROCESS_GROUP). This lets you enter commands in
abbreviated form. For example:
DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER, NETWORK_SERVER
DBG_1> SHOW PROCESS SERVERS
Number Name Hold State Current PC
* 1 FILE_SERVER step FS_PROG\%LINE 37
2 NETWORK_SERVER break NET_PROG\%LINE 24
The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and
%PREVIOUS_PROCESS are useful in control structures (IF, WHILE,
REPEAT, and so on) and in command procedures.
Termination Options
When the main image of a process runs to completion, the process
goes into the terminated debugging state (not to be confused
with process termination in the VMS sense). This condition is
traced by default, as if you had entered the SET TRACE
/TERMINATING command.
When a process is in the terminated debugging state, it is still
known to the debugger and appears in a SHOW PROCESS /ALL
display. You can enter commands to examine variables, and so
on. When the last image of the program exits, the debugger
gains control and displays its prompt, rather than ending the
debugging session.
To end the entire debugging session, use the EXIT or QUIT
command without specifying any parameters. When you do not
specify any parameters, the behavior of EXIT and QUIT is
analogous to their behavior for the default debugging
configuration (QUIT does not execute any user-declared exit
handlers).
To terminate selected processes (in the VMS sense) without
ending the debugging session, use the EXIT or QUIT command,
specifying one or more processes to be terminated. For example,
the following command terminates the image running in process 2
and the process:
DBG_3> EXIT %PROC 2
DBG_3>
Subsequently, process 2 does not appear in a SHOW PROCESS
display. For more information, see help on the EXIT and QUIT
commands.
Visible Process
The visible process is the process that is the default context
for issuing process-specific commands. Process-specific
commands are those that start execution (STEP, GO, and so on)
and those used for looking up symbols, setting breakpoints,
looking at the call stack and registers, and so on. Commands
that are not process specific are those that do not depend on
the mapping of virtual memory but instead affect the entire
debugging environment --- for example, keypad-mode and
screen-mode commands.
Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX),
the debugger prompt suffix always identifies the visible process
(for example, DBG_1>). The SET PROMPT command has several
options for tailoring the prompt-string prefix and suffix to
your needs.
When you invoke the debugger, the visible process is the first
process that comes under debugger control, namely the process
running the main program. Within a debugging session, the
debugger assigns a process number sequentially, starting with 1,
to each process that comes under debugger control.
Additional information available:
Dynamic Process Setting
By default, dynamic process setting is enabled (SET PROCESS
/DYNAMIC). As a result, whenever the debugger interrupts
execution and displays its prompt, the process in which
execution is suspended becomes the visible process
automatically. Dynamic process setting occurs in the following
situations: when a breakpoint or watchpoint is triggered, at an
exception condition, on the completion of a STEP command, or
when the last process performs an image exit. Dynamic process
setting is illustrated in the following example, which also
illustrates dynamic prompt setting:
DBG_1> SHOW PROCESS/ALL
Number Name Hold State Current PC
* 1 JONES step MAIN_PROG\%LINE 22
2 JONES_1 interrupted TEST\%LINE 4
DBG_1> DO/PROCESS=(%PROC 2) (SET BREAK %LINE 11)
DBG_1> GO
break at TEST\%LINE 11 in %PROCESS_NUMBER 2
DBG_2> SHOW PROCESS/ALL
Number Name Hold State Current PC
1 JONES interrupted MAIN_PROG\%LINE 28
* 2 JONES_1 break TEST\%LINE 11
DBG_2>
In this example, initially process 1 is the visible process, as
indicated by the prompt suffix and the SHOW PROCESS display.
The DO command sets a breakpoint in the context of process 2.
Execution resumes with the GO command and is suspended at the
breakpoint in process 2. Process 2 is now the visible process,
as indicated by the prompt suffix and the SHOW PROCESS display.
If SET PROCESS/NODYNAMIC is in effect, the visible process
remains unchanged until you specify another process with the SET
PROCESS/VISIBLE command.
If SET MODE NOINTERRUPT is in effect and you start execution in
several processes with the DO command, the prompt is displayed
only after execution has been suspended in all processes. In
this case, the visible process remains unchanged, unless the
last process performs an image exit (and thereby becomes the
visible process).
SET_PROCESS
Use the SET PROCESS command (the default is /VISIBLE) to make
another process as the visible process. For example, the
following SET PROCESS command makes process 2 the visible
process (as indicated by the DBG_2> prompt):
DBG_1> SET PROCESS %PROC 2
DBG_2>
In this example, because dynamic prompt setting is enabled by
default, the SET PROCESS command has also caused the prompt
string suffix to change. It now indicates that process 2 is the
visible process. All process-specific commands now execute in
the context of process 2.
Path Names
If you have multiple symbols with the same name, you may need to
use path names to disambiguate symbol references. For example,
you may have a variable X in procedure A, another variable X in
procedure B which is nested in procedure A, and still another
variable X in procedure C. If you enter the EXAMINE X command,
the debugger tries to resolve which X you mean, based on your
current PC. If the debugger cannot do so, it issues the
following error message:
%DEBUG-W-NOUNIQUE,X is not unique.
In this case, you can specify which X you want using path names:
DBG> EXAMINE A\X
DBG> EXAMINE A\B\X
DBG> EXAMINE C\X
For more information, see help on the SET SCOPE command.
Screen Mode
The debugger provides a set of screen features designed to be
used on VT-series terminals and MicroVAX workstations. The SET
MODE SCREEN command enables screen mode and SET MODE NOSCREEN
disables it. In screen mode, screen displays can be defined and
viewed through windows on the terminal screen. A screen display
is a data structure which contains lines of text. The text may
be normal debugger output, the text of a source file, a special
register display, or a special assembly-language instruction
display. The text of a display may be viewed through a window
on the terminal screen and can be scrolled back and forth
through that window. When screen mode is first set, the
debugger provides the following predefined displays: a source
display (SRC), a debugger output display (OUT), and a special
display (PROMPT) where the debugger prompts for input.
Optionally, a register display (REG) and an instruction display
(INST) can also be displayed.
Several screen features are designed to facilitate debugging
multiprocess programs (see help on Multiprocess_Features).
Additional information available:
CommandsDisplay AttributesDisplay KindsExamplesInstruction Display
KeypadMoving DisplaysMultiprocess FeaturesPredefined Displays
PROMPT DisplayRegister DisplayResizing DisplaysScreen Mode
ScrollingSource DisplayWindows
Commands
A number of commands control the debugger's screen features.
They are grouped here according to their general purpose.
Control overall operation: SET MODE SCREEN SET TERMINAL
SET MODE NOSCREEN SHOW TERMINAL
Create screen windows: SET WINDOW CANCEL WINDOW
SHOW WINDOW
Create screen displays: DISPLAY CANCEL DISPLAY
SHOW DISPLAY
Modify screen displays: DISPLAY SCROLL
EXPAND SELECT
MOVE SHOW SELECT
Preserve screen displays: EXTRACT SAVE
You can get further information on each of these commands
through HELP. The most frequently used commands are:
DISPLAY Lets you change the absolute position of displays
on the screen, change display attributes, and
refresh the screen, among other things.
SCROLL Scrolls the text of a display through its screen
window.
EXPAND Changes the size or relative position of displays
or MOVE on the screen.
The EXPAND, MOVE, and SET TERMINAL commands are especially
useful for manipulating displays on the larger screen of a
MicroVAX workstation.
Display Attributes
You can assign attributes to displays by using the SELECT
command. The possible display attributes are:
Attribute Effect
----------------------------------------------------------------
ERROR Displays debugger diagnostic messages.
INPUT Echoes your debugger input.
INSTRUCTION Displays the decoded MACRO instruction stream of
the module being debugged. Pressing BLUE-COMMA
on the keypad selects the next instruction dis-
play on the display list as the current instruc-
tion display.
OUTPUT Displays debugger output that is not already
being directed to another display (for example,
diagnostic messages). Pressing GOLD-KP3 selects
the next output display on the display list as
the current output display.
PROGRAM Displays program output.
PROMPT Prompts for input.
SCROLL Can be scrolled with the SCROLL command or the
KP2, KP8, KP4, and KP6 keys. Pressing KP3 selects
the next display on the display list as the current
scrolling display (except for PROMPT, which cannot
be scrolled).
SOURCE Displays the source code of the module being debugged,
if available. Pressing BLUE-KP3 selects the next
source display on the display list as the current
source display.
Although a display can have more than one attribute, subject to
the kind of display it is, only one display can have a
particular attribute. That display is then known as the current
display with that attribute (for example, current scrolling
display, current input display).
In the following example, the display OUT is selected as the
current input, error, and scrolling display. After the command
executes, debugger input, debugger output (assuming OUT was
previously selected for output), and debugger diagnostic
messages are logged in the OUT display in the proper sequence,
and OUT is the current scrolling display:
DBG> SELECT/INPUT/ERROR/SCROLL OUT
Attributes can be assigned to the various display kinds only as
follows:
Display Kind
DO INSTRUCTION OUTPUT PROGRAM REGISTER SOURCE
---+-------------+--------+---------+----------+-------
Attribute | | | | |
ERROR | | yes | yes | |
INPUT | | yes | | |
INSTRUCTION | yes | | | |
OUTPUT | | yes | yes | |
PROGRAM | | | yes | |
PROMPT | | | yes | |
SCROLL yes | yes | yes | yes | yes | yes
SOURCE | | | | | yes
You unselect (or deassign) one or more attributes by using the
SELECT command with the appropriate qualifier(s), but without
specifying a display. For example, the following command
unselects the INSTRUCTION and SCROLL attributes:
DBG> SELECT/INSTRUCTION/SCROLL
After the command executes, no display has the INSTRUCTION or
SCROLL attribute. When the ERROR, OUTPUT, or PROGRAM attribute
is unselected only the PROMPT display shows diagnostic messages,
debugger output, or program output, respectively. When the
INPUT, INSTRUCTION, SCROLL, or SOURCE attribute is unselected,
no display, including the PROMPT display, has that attribute.
The PROMPT attribute cannot be unselected.
By default, when you invoke screen mode, the predefined displays
are selected for attributes as follows:
Attribute Predefined display
---------------------------------
ERROR PROMPT
INPUT
INSTRUCTION
OUTPUT OUT
PROGRAM PROMPT
PROMPT PROMPT
SCROLL SRC
SOURCE SRC
Display Kinds
There are five kinds of screen displays:
OUTPUT
SOURCE
REGISTER
INSTRUCTION
PROGRAM
(Only the predefined display named PROMPT has the display kind
PROGRAM.)
An output display holds normal debugger output lines up to some
maximum number of lines. An output display may also have a
debugger command list which is automatically executed to create
the display text each time the debugger gets control from the
user program.
A source display displays the program's source code. The output
from TYPE and EXAMINE/SOURCE commands can be directed to a
source display, and a source display can be automatically
updated through a list of debugger commands.
An instruction display is much like a source display, except
that it holds assembly language instructions instead of source
lines. The output from an EXAMINE/INSTRUCTION command can be
directed to an instruction display, and an instruction display
can be automatically updated through a list of debugger
commands.
A register display shows the contents of the VAX registers, and
is automatically updated as the program runs. The register
display is primarily intended for MACRO programmers. Except for
the PROGRAM display named PROMPT, displays of all kinds are
created with the DISPLAY command. They are manipulated on the
screen with the DISPLAY command, which takes a number of
qualifiers.
Examples
1. The following command puts the source display SRC in the left
top half of the screen, the instruction display INST in the
right top half, the output display OUT under these two in the
fourth and fifth sixths of the screen, and the PROMPT display in
the bottom sixth:
DBG> DISPLAY SRC AT LH1, INST AT RH1, OUT AT S45, PROMPT AT S6
2. The following commands put the register display REG at the top
of the screen, create a new display WATCHABCD in the middle of
the screen to watch variables A,B,C, and D, and place the OUT
display below these, above the PROMPT display:
DBG> DISPLAY REG AT T1
DBG> SET DISP/MARK WATCHABCD AT T2 DO (EXAMINE A,B,C,D)
DBG> DISPLAY OUT AT S5
Instruction Display
An instruction display gives you a scrollable window into the
assembly-language instruction stream. The predefined display
INST is an instruction display which is automatically updated so
that the arrow points to the instruction at your current PC.
DISPLAY INST makes it appear. The numbers to the left of the
instructions are line numbers.
If you select the instruction display by using the SELECT/INST
INST command (or by pressing PF4-COMMA on the keypad), then
output of an EXAMINE/INSTRUCTION command is directed to the
instruction display.
If you select the instruction diplay as the scrolling display
using SELECT/SCROLL INST (or by rotating the scrolling attribute
with the KP3 key), then you can scroll it up, down, left, or
right.
Pressing KP7 puts the predefined source display SRC in the upper
left half of the screen (LH1), INST in the upper right half of
the screen (RH1), the predefined output display OUT below these
two at S45, and the PROMPT display below OUT at S6. Pressing
BLUE-MINUS on the keypad redisplays SRC across the entire top
half of the screen (this is the default configuration).
Keypad
Many keypad keys are predefined to manipulate screen-mode
displays. For example, KP8, KP6, KP2, and KP4 are SCROLL/UP,
/RIGHT, /DOWN, and /LEFT, respectively. The display that is
scrolled is determined by which display has the scroll
attribute. This attribute can be cycled through the displays
pressing KP3.
There are a few predefined screen layouts that can be selected
with keypad keys:
o A source display on the top half of the screen, and an output
display on most of the bottom half, above the prompt display.
This is the default layout for most languages. The screen
can always be put in this state by pressing BLUE-MINUS on the
keypad.
o A source display in the top left half, and instruction
display in the top right half, and an output display under
these two, above the prompt display. This can be selected by
pressing KP7.
o An instruction display in the top left half, a register
display in the top right half, and an output display under
these two, above the prompt display. This can always be
selected by pressing GOLD-KP7.
If you are debugging a multiprocess program, several key
combinations let you manipulate process-specific source and
instruction displays. The debugger automatically creates these
displays whenever a new process comes under debugger control.
For more information, see help on Screen_Mode
Multiprocess_Features.
For diagrams identifying of key functions, see help on
Keypad_Defintions.
Moving Displays
You can use the MOVE command to move a display across the screen
vertically or horizontally or both.
Multiprocess Features
Screen-mode displays, whether predefined or user-defined, are
associated with the visible process by default. For example,
SRC shows the source code where execution is suspended in the
visible process, OUT shows the output of commands executed in
the context of the visible process, and so on.
By using the DISPLAY/PROCESS command, you can create
process-specific displays or make existing displays process
specific. 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.
For example, the following command creates the automatically
updated source display SRC_3, which shows the source code where
execution is suspended in process 3:
DBG_2> DISPLAY/PROCESS=(%PROC 3) SRC_3 AT RS23 -
SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC)
You assign attributes to process-specific displays as for
displays that are not. For example, the following command makes
display SRC_3 the current scrolling and source display --- that
is, the output of SCROLL, TYPE, and EXAMINE/SOURCE commands are
then directed to SRC_3:
DBG_2> SELECT/SCROLL/SOURCE SRC_3
If you use DISPLAY/PROCESS without specifying a process, the
specified display is then specific to the process that was the
visible process when you entered the command. For example, the
following command makes OUT_X specific to process 2:
DBG_2> DISPLAY/PROCESS OUT_X
The /SUFFIX qualifier appends a process identifying suffix that
denotes the visible process to a display name. Use /SUFFIX
directly after a display name in any command that specifies a
display (for example, DISPLAY, EXTRACT, SAVE). It is especially
useful within command procedures, in conjunction with display
definitions or with key definitions bound to display
definitions.
In a multiprocess configuration, the predefined tracepoint on
process activation automatically creates a new source display
and a new instruction display for each new process that comes
under debugger control. The displays have the names SRC_n and
INST_n, respectively, where n is the process number. These
displays are initially marked as removed. They are
automatically canceled by the predefined tracepoint on process
termination.
Additional information available:
Keypad Definitions
Several predefined keys let you to configure your screen with
the process-specific source and instruction displays that are
created automatically when a process is activated. The
following table identifies the relevant keypad keys and their
general effect. Use the SHOW KEY command to determine the exact
commands issued by these key combinations.
State Key Command Invoked or Function
----------------------------------------------------------------
GOLD COMMA SELECT/SOURCE %NEXT_SOURCE. Selects the next
source display in the display list as the current
source display. (This function was previously
assigned to BLUE-KP3.)
GOLD KP9 SET PROCESS/VISIBLE %NEXT_PROCESS. Makes the next
process in the process list the visible process.
BLUE KP9 Displays two predefined process-specific source
displays, SRC_n. These are located at Q1 and Q2,
respectively, for the visible process and next
process on the process list.
BLUE KP7 Displays two sets of predefined process-specific
source and instruction displays, SRC_n and INST_n.
These comprise source and instruction displays for
the visible process at Q1 and RQ1, respectively,
and source and instruction displays for the next
process on the process list at Q2 and RQ2,
respectively.
BLUE KP3 Displays three predefined process-specific source
displays, SRC_n. These are located at S1, S2,
and S3, respectively, for the previous, current
(visible), and next process on the process list.
BLUE KP1 Displays three sets of predefined process-specific
source and instruction displays, SRC_n and INST_n.
These comprise source and instruction displays for
the visible process at S2 and RS2, respectively;
source and instruction displays for the previous
process on the process list at S1 and RS1, respec-
tively; and source and instruction displays for the
next process on the process list at S3 and RS3,
respectively.
Predefined Displays
The debugger has five predefined displays when you invoke screen
mode:
Display Usage
----------------------------------------------------------------
SRC Source display which is automatically positioned at
your current PC. You can reposition SRC by using the
TYPE or EXAMINE/SOURCE command. You can scroll SRC
up and down by pressing KP8 and KP2. See help on
the Source_Display subtopic.
INST Assembly-language instruction display called INST,
which is automatically positioned at your current PC.
INST is initially removed but can be made to appear
by using DISPLAY INST. To scroll INST, first press
KP3 to to rotate the scroll attribute to INST, and
then press KP8 and KP2. See help on the Instruction
_Display subtopic.
REG Register display, which is automatically updated
to show the current values of your registers. REG
is initially removed but can be made to appear by
using the DISPLAY REG command. See help on the
Register_Display subtopic.
OUT Output display where debugger output is directed.
If you want to intermix debugger input and output
in the same display, you can copy debugger input
to OUT by by using the SELECT/INPUT OUT command.
PROMPT Prompt display called where the debugger prompts
for input, forces program output, and (by default)
displays diagnostic messages. See help on the
PROMPT_Display subtopic.
If you are debugging a multiprocess program, in addition to
these five displays, the debugger automatically creates
process-specific source and instruction displays whenever a new
process comes under debugger control. For more information, see
help on Multiprocess_Features.
PROMPT Display
The predefined PROMPT display is a non-scrollable display that
shows the debugger prompt, debugger input, and (by default)
program output and debugger diagnostic messages. By default,
PROMPT occupies the bottom sixth of the screen (the predefined
window S6). On a VT100 or VT200 series terminal, S6 includes
lines 21 through 24.
The PROMPT display is of the display kind PROGRAM and is the
only display of that kind (no other PROGRAM displays can be
created). Note that, compared to other displays, PROMPT has
several restrictions, to eliminate possible confusion when
manipulating that display:
o PROMPT can never be hidden by another display. It is always
on top of the display pasteboard.
o PROMPT can be moved anywhere on the screen, expanded to fill
the full screen height, and shrunk down to two lines. But
PROMPT must always occupy the full width of the screen and,
therefore, cannot be moved, expanded, or shrunk horizontally.
For more information, see help on the Display_Attributes
subtopic.
Register Display
The predefined REG display shows the current values (in
hexadecimal format) of all VAX machine registers (R0 through
R11), the four condition code bits (C, V, Z, and N) of the
processor status longword (PSL), and the top several values on
the stack and on the current argument list. Values in a
register display are highlighted when they change as you execute
the program. REG is an automatically updated display.
Initially, REG is marked as removed from the display pasteboard
and is not visible. You need to use the DISPLAY command (or
press GOLD-KP7) to show the REG display. Pressing GOLD-KP7 puts
the predefined instruction display INST in the upper left half
of the screen (LH1), REG in the upper right half of the screen
(RH1), the predefined output display OUT below these two at S45,
and the PROMPT display below OUT at S6. Pressing BLUE-MINUS on
the keypad redisplays SRC across the entire top half of the
screen (this is the default configuration).
Like other displays, register displays are dynamic by default.
This means that the window dimensions adjust proportionally when
you change the screen height or width with a SET TERMINAL
command. If the window of a register display is resized, the
debugger automatically reformats the displayed information to
adapt to the new window size. The debugger always displays the
contents of registers R0 through R11, AP, FP, SP, PC, and PSL.
If the resized window is too small to display all register
information, you can scroll vertically or horizontally to view
any information that may be hidden. If the resized window is
larger than necessary to display register information, the
debugger fills the remaining space with information (in
hexadecimal format) contained in the user stack.
Resizing Displays
To expand and contract displays, use the EXPAND command.
Screen Mode
When the debugger is invoked, five predefined displays are
created automatically. The first time you invoke screen mode
with the SET MODE SCREEN command, the debugger puts three of the
displays on the screen for you:
o A source display (SRC) which is automatically updated as you
STEP or GO through your program
o An output display (OUT) which captures your normal debugger
output
o A prompt display (PROMPT) where the debugger prompts for your
input
The instruction display (INST) and the register display (REG)
are also created but not displayed initially. These capture the
current instruction stream and registers respectively. Except
for the PROMPT display, each display can be scrolled back and
forth with the SCROLL command.
You can turn off screen mode with the SET MODE NOSCREEN command,
after which you can use the terminal in the normal manner
without the display windows. To restore the displays, use the
SET MODE SCREEN cmmand.
If you are debugging a multiprocess program, in addition to
these five predefined displays, the debugger automatically
creates process-specific source and instruction displays
whenever a new process comes under debugger control. For more
information, see help on Screen_Mode Multiprocess_Features.
Scrolling
All screen displays except for the PROMPT display can be
scrolled through their screen windows by using the SCROLL
command. For example, SCROLL/UP SRC scrolls the window up over
display SRC. To avoid having to specify the display name on
your SCROLL commands, you can select the display you want to
scroll as the current scrolling display with the SELECT command.
Thus, using SELECT/SCROLL SRC followed by SCROLL/UP scrolls up
through display SRC even through SRC was not explicitly named on
the SCROLL command. For more information, see help on the
SCROLL and SELECT commands.
Source Display
A source display gives you a scrollable window into your source
code. The predefined source display SRC has associated with it
the following command:
DBG> EXAMINE/SOURCE .%SOURCE_SCOPE\%PC
This command centers automatically at your current source line.
The built-in symbol %SOURCE_SCOPE means scope 0 when source
lines are available in scope 0. Otherwise, it is the same as
SCOPE n, where n is the first level going down the stack where
source lines are available.
The significance of the %SOURCE_SCOPE symbol is that if your PC
value is at a location where source lines are not available (for
example, in an RTL routine), the debugger attempts to display
source lines in the caller of the current routine (that is,
scope 1 or 1 level down the stack). If source lines are still
not available at that level, the debugger tries scope 2, and so
on. If the source display shows source lines that are not
associated with the current routine, an informational message to
that effect is displayed.
Pressing BLUE-MINUS on the keypad displays the predefined
displays SRC in the top half of the screen, OUT below SRC at
S45, and PROMPT at the bottom of the screen at S6. This is the
default. Pressing KP7 places SRC in the upper left half of the
screen (LH1), the instruction display INST in the upper right
half of the screen (RH1), OUT below these two at S45, and PROMPT
below OUT at S6.
Windows
A screen window is a rectangular region on the terminal screen
defined by the following four quantities:
RBEG Line number at which the window starts.
RLEN Number of lines of text in the window.
CBEG Column number at which the window starts.
CLEN Number of columns (width) of the window.
If the CBEG and CLEN numbers are omitted from a window
definition, the window defaults to the full width of the screen.
The debugger provides a number of predefined windows for regions
such as the top half of the screen, the top left quarter of the
screen, and so on. For example:
H1 Top half of screen = (1,11,1,80)
H2 Bottom half of screen = (13,11,1,80)
LH1 Top left quarter of screen = (1,11,1,40)
There are also T1, T2, and T3 for thirds of the screen, Q1
through Q4 for quarters, S1 through S6 for sixths, and E1
through E8 for eigths. Each of these also has a L for left half
(for example, LQ1) and and R for right half (for example, RQ1).
FS denotes the full screen. You can see all defined windows
through the SHOW WINDOW command. You can also define your own
named windows with the SET WINDOW command, or delete window
names with the CANCEL WINDOW command. Windows are specified on
the DISPLAY command to indicate where displays are to be shown
on the terminal screen.
Example:
DBG> DISPLAY SRC AT LH1
DBG> DISPLAY INST AT RH1
DBG> DISPLAY OUT AT S4
DBG> DISPLAY PROMPT AT S56
SS$_DEBUG
SS$_DEBUG (defined in STARLET) is a condition that you can
signal from your program to invoke the debugger. Signalling
SS$_DEBUG from your program is the same as pressing Ctrl/Y and
then using the DEBUG command at that point.
You can pass commands to the debugger at the time you signal it
with SS$_DEBUG. For example, to invoke the debugger and do a
SHOW CALLS command at a given point in your program, you could
put the following into your program (this example is coded in
BLISS):
SIGNAL(SS$_DEBUG, 1,
UPLIT BYTE(%ASCIC 'SHOW CALLS'));
System Management
The debugger consists of two parts (main and kernel), to
accommodate the debugging of multiprocess programs.
o For a program that runs in one process, a debugging session
requires two processes instead of one.
o For a multiprocess program, a debugging session requires as
many processes as are used by the program, plus an additional
process for the main debugger.
Under these conditions, multiple users who are simultaneously
debugging programs can place an additional load on a system.
The subtopics describe the resources used by the debugger so
that you can tune your system for this activity.
Note that the discussion covers only the resources used by the
debugger. In the case of multiprocess programs, you might also
have to tune your system to support the programs themselves.
Additional information available:
User Quotas
Each user needs a PRCLM quota sufficient to create an additional
subprocess for the debugger, beyond the number of processes
needed by the program.
BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may
need to be increased to account for the debugger subprocess as
follows:
o Each user's ENQLM quota should be increased by at least the
number of processes being debugged.
o Each user's PGFLQUOTA might need to be increased. If a user
has an insufficient PGFLQUOTA, the debugger might fail to
activate or cause "virtual memory exceeded" errors during
execution.
o Each user's BYTLM and FILLM quotas may need to be increased.
The debugger requires BYTLM and FILLM quotas sufficient to
open each image file being debugged, the corresponding source
files, and the debugger input, output, and log files. You
can use the SET MAX_SOURCE_FILES command to limit the number
of source files kept open by the debugger at any one time.
System Resources
The kernel and main debugger communicate through global
sections. The main debugger communicates with up to 8 kernel
debuggers through a 65-page global section. Therefore, the
SYSGEN global- page and global-section parameters (GBLPAGES and
GBLSECTIONS, respectively) might need to be increased. For
example, if 10 users are using the debugger simultaneously, 10
global sections using a total of 650 global pages are required
by the debugger.
@file spec
Executes debugger commands from the specified file.
Format:
@file-spec [parameter[,...]]
The optional parameters can be address expressions, language
expressions, or strings (corresponding to the three kinds of
DEFINE symbols). Inside the command procedure, the parameters
are bound to names with the DECLARE command.
If SET OUTPUT VERIFY is in effect, all commands read from a
command procedure are echoed on the terminal (the default is SET
OUTPUT NOVERIFY).
Additional information available:
Examples
The following example invokes a command file that specifies a
particular set of defaults. The commands in the command file
are echoed because of the SET OUTPUT VERIFY command.
DBG> SET OUTPUT VERIFY
DBG> @SETUP.COM
!entering command file SETUP.COM
! SET SOURCE [],SRC$
! SET MODE SCREEN
! SET STEP SILENT
! SET RADIX HEX
!exiting command file SETUP.COM
Parameters
file-spec
The command file to be executed. The default file type is .COM.
You can use a logical name for the file specification. To
change the default command file specification, use the SET
ATSIGN command.
parameter
(Optional.) An address or value expression in the current
language, or a quoted string. It is bound to a name within the
command procedure by using the DECLARE command.
Example:
DBG> @DUMP X
! entering command procedure DUMP.COM
! DECLARE P1:ADDRESS
! EXAMINE P1
X: 23
! exiting command procedure DUMP.COM
ATTACH
Switches to another process, same as with the ATTACH command at
the DCL level.
Format:
ATTACH process-name
Example:
DBG> SPAWN ! Create SMITH_1 subprocess
$ ATTACH SMITH ! Attach back to parent
DBG> ATTACH SMITH_1 ! Attach to subprocess
CALL
Executes a routine that was linked with your program,
independently of the normal flow of execution of your program.
The program does not have to include a call to that routine. A
common use of the CALL command is to invoke procedures that dump
debugging information.
Format:
CALL routine-name [(argument[,...])]
Additional information available:
DescriptionExamplesParametersQualifiersMultiprocess Programs
Description
CALL is one of the four debugger commands that can cause your
program to execute (the others are GO, STEP, and EXIT).
When you use CALL at an exception breakpoint, then any
breakpoints, tracepoints, or watchpoints that were previously
set within the called routine are temporarily disabled so that
the debugger does not lose the exception context. However, such
eventpoints are active if you use CALL at a location other than
an exception breakpoint.
The CALL command does the following:
1. Saves the current values of the general registers.
2. Constructs an argument list.
3. Executes a call to the routine specified in the command and
passes any arguments.
4. Executes the routine.
5. Displays the value returned by the routine in R0. By VMS
convention, after a called routine has executed, register R0
contains the function return value (if the routine is a
function) or the procedure completion status (if the routine
is a procedure that returns a status value). If a called
procedure does not return a status value or function value,
the value in R0 may be meaningless, and the "value returned"
message can be ignored.
6. Restores the values of the general registers to the values
they had just before the CALL command executed.
7. Displays the DBG> prompt.
Examples
1. DBG> CALL SUB1(X)
value returned is 19
Calls the routine SUB1, passing the address of X as the required
parameter (by default, the address of the argument specified is
passed). The routine is a function whose returned value is 19.
2. DBG> CALL SUB(%REF 1)
value returned is 1
Passes a pointer to a memory location containing the numeric
literal 1, into the routine SUB.
3. DBG> SET MODULE SHARE$LIBRTL
DBG> CALL LIB$SHOW_VM
1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM,
122216 bytes still allocated, value returned is 00000001
This example shows how you could call the run-time library
routine LIB$SHOW_VM (in the shareable image LIBRTL) to display
virtual memory statistics. The SET MODULE command makes the
universal symbols (routine names) in LIBRTL visible in the main
image. For more information, see help on the SHOW MODULE/SHARE
command.
Parameters
routine-name
The name or the virtual address of the procedure to be called.
argument
(Optional.) An argument required by the routine. Arguments can
be passed by address (the default), descriptor, reference, or
value, as described in the subtopics.
The debugger assumes that the called routine conforms to the VMS
procedure calling standard (see the VAX Architecture Handbook).
However, note that the debugger does not know about all
argument-passing mechanisms for all supported languages.
Therefore, you may need to specify how to pass parameters ---
for example, use the CALL SUB1(%VAL X) command rather than CALL
SUB1(X). For information on how arguments are passed to
routines, see your language documentation.
Additional information available:
%ADDR
(Default.) Passes the argument by address.
Format:
CALL routine-name (%ADDR address-expression)
The debugger evaluates the address expression and passes that
address to the routine specified. For simple variables (such as
X), the address of X is passed into the routine. This passing
mechanism is how FORTRAN implements ROUTINE(X). In other words,
for named variables, using %ADDR corresponds to a call by
reference in FORTRAN. For other expressions, however, you must
use the %REF function to call by reference. For complex or
structured variables (such as arrays, records, and access
types), the address is passed when you specify %ADDR, but the
called routine may not handle the passed data properly. Do not
specify a literal value (a number or an expression composed of
numbers) with %ADDR.
%DESCR
Passes the argument by descriptor.
Format:
CALL routine-name (%DESCR language-expression)
The debugger evaluates the language expression and builds a
VAX-standard descriptor to describe the value. The descriptor
is then passed to the routine you named. You would use this
technique to pass strings to a FORTRAN routine.
%REF
Passes the argument by reference.
Format:
CALL routine-name (%REF language-expression)
The debugger evaluates the language expression and passes a
pointer to the value, into the called routine. This passing
mechanism corresponds to the way FORTRAN passes the result of an
expression.
%VAL
Passes the argument by value.
Format:
CALL routine-name (%VAL language-expression)
The debugger evaluates the language expression and passes the
value directly to the called routine.
Qualifiers
Additional information available:
/AST/NOAST/SAVE_VECTOR_STATE/NOSAVE_VECTOR_STATE
/AST
Specifies that ASTs can be delivered during execution of the
called routine.
You can specify whether you want the delivery of asynchronous
system traps (ASTs) enabled or disabled during the routine call.
By default, if you do not specify /AST or /NOAST, delivery of
ASTs is enabled in the called routine if, and only if, delivery
was enabled before the CALL command executed.
/NOAST
Specifies that ASTs cannot be delivered during execution of the
called routine.
You can specify whether you want the delivery of asynchronous
system traps (ASTs) enabled or disabled during the routine call.
By default, if you do not specify /AST or /NOAST, delivery of
ASTs is enabled in the called routine if, and only if, delivery
was enabled before the CALL command executed.
/SAVE_VECTOR_STATE
(Applies to vectorized programs.) Controls whether the current
state of the vector processor is saved and then restored when a
routine is called with the CALL command. The state of the
vector processor comprises the following:
o The values of the vector registers (V0 to V15) and the vector
control registers (VCR, VLR, and VMR)
o Any vector exception (an exception caused by the execution of
a vector instruction) that might be pending delivery
When you use the CALL command to execute a routine, execution of
the routine might change the state of the vector processor as
follows:
o By changing the values of vector registers or vector control
registers
o By causing a vector exception
o By causing the delivery of a vector exception that was
pending when the CALL command executed
The /SAVE_VECTOR_STATE qualifier specifies that after a called
routine completes execution, the debugger restores the state of
the vector processor to whatever it was before the CALL command.
This ensures that after the called routine has completed
execution:
o Any vector exception that was pending delivery before the
CALL command executed is still pending delivery
o No vector exception that was triggered during the routine
call is still pending delivery
o The values of the vector registers are identical to their
values before the CALL command executed
The /NOSAVE_VECTOR_STATE qualifier, which is the default,
specifies that the state of the vector processor that exists
before the CALL command executes is not restored by the debugger
after the called routine has completed execution. In this case,
the state of the vector processor after the routine call depends
on the effect (if any) of the called routine.
The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the VAX
general registers. The values of these registers are always
saved and restored when you execute a routine with the CALL
command.
/NOSAVE_VECTOR_STATE
(Applies to vectorized programs. Default.) Specifies that the
state of the vector processor that exists before the CALL
command executes is not restored by the debugger after the
called routine has completed execution. In this case, the state
of the vector processor after the routine call depends on the
effect (if any) of the called routine.
See help on the /SAVE_VECTOR_STATE qualifier.
Multiprocess Programs
If you are using the multiprocess debugging configuration to
debug a multiprocess program (if the DBG$PROCESS logical name is
defined as MULTIPROCESS), note the following additional points:
o The CALL command executes in the context of the visible
process, but images in any other unheld processes (processes
that have not been put on hold with a SET PROCESS/HOLD
command) are also allowed to execute. If you use the DO
command to broadcast a CALL command to one or more processes,
the CALL command executes in the context of each specified
unheld process, but images in any other unheld processes are
also allowed to execute. In all cases, a hold condition in
the visible process is ignored.
o Once execution is started, the way in which it continues
depends on whether SET MODE NOINTERRUPT is in effect. By
default (SET MODE INTERRUPT), execution continues until it is
suspended in any process. At that point, execution is
interrupted in any other processes that were executing
images, and the debugger prompts for input.
CANCEL
Cancels breakpoints, tracepoints, and watchpoints, and restores
scope and source directory search list and user-set
entry/display modes, radix, and types to their default values.
Also cancels screen displays and wind. The item canceled
depends on the keyword you specify.
Format:
CANCEL keyword [/qualifier] [parameters]
Additional information available:
ALLBREAKDISPLAYIMAGEMODEMODULERADIX
SCOPESOURCETRACETYPEWATCHWINDOW
Parameters
keyword
The item to be canceled. Keyword can be one of the following:
ALL BREAK DISPLAY IMAGE
MODE MODULE RADIX SCOPE
SOURCE TRACE TYPE/OVERRIDE WATCH
WINDOW
qualifier
Depends on the keyword you specify.
parameters
Depends on the keyword you specify.
ALL
Cancels all breakpoints, tracepoints, and watchpoints. Restores
some modes, specified with the SET MODE command. to their
default values. Restores the scope and type to their default
values.
Format:
CANCEL ALL [/qualifier[...]]
Additional information available:
Description
The CANCEL ALL command does the following:
1. Cancels all breakpoints, tracepoints, and watchpoints. This
is the same as entering the CANCEL BREAK/ALL, CANCEL
TRACE/ALL, and CANCEL WATCH/ALL commands. Depending on the
type of program (for example Ada, multiprocess), certain
predefined breakpoints or tracepoints may be set
automatically when you invoke the debugger.
By default (CANCEL ALL/USER), only user-defined breakpoints,
tracepoints, and watchpoints are canceled --- those that
were previously set explicitly with SET BREAK, SET TRACE,
and SET WATCH commands.
If you specify /PREDEFINED but not /USER, all predefined
(but no user-defined) breakpoints, tracepoints, and
watchpoints are canceled.
If you specify both /PREDEFINED and /USER, all predefined
and user-defined breakpoints, tracepoints, and watchpoints
are canceled.
2. Restores the scope search list to its default value
(0,1,2, ... ,n). This is the same as entering the CANCEL
SCOPE command.
3. Restores the data type for memory locations associated with
a compiler generated type to the associated type. Restores
the type for locations that are not associated with a
compiler generated type to longword integer. This is the
same as entering the CANCEL TYPE/OVERRIDE and SET TYPE
LONGWORD commands.
4. Restores some modes, specified with the SET MODE command, to
their default values. This is the same as entering the
following command:
DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT
CANCEL ALL does not affect the current language setting or the
modules included in the debugger symbol table.
Examples
1. DBG> CANCEL ALL
Cancels all user-defined breakpoints, tracepoints, and
watchpoints and restores scopes, types, and some modes to their
default values. In this example, there are no predefined
breakpoints, tracepoints, or watchpoints.
2. DBG> CANCEL ALL
%DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled
Cancels all user-defined breakpoints, tracepoints, and
watchpoints and restores scopes, types, and some modes to their
default values. In this example, there are some predefined
breakpoints, tracepoints, or watchpoints, and these are not
canceled by default.
3. DBG> CANCEL ALL/PREDEFINED
Cancels all predefined breakpoints, tracepoints, and watchpoints
and restores scopes, types, and some modes to their default
values. User-defined breakpoints, tracepoints, or watchpoints
are not affected.
Qualifiers
Additional information available:
/PREDEFINED
Cancels all predefined (but no user-defined) breakpoints,
tracepoints, and watchpoints.
/USER
(Default.) Cancels all user-defined (but no predefined)
breakpoints, tracepoints, and watchpoints. /USER is the default
unless you specify /PREDEFINED.
BREAK
Cancels a breakpoint.
Format:
CANCEL BREAK [/qualifier[...]] [address-expression[,...]]
Additional information available:
DescriptionExamplesParametersQualifiers
Description
Breakpoints may be user-defined or predefined. User-defined
breakpoints are set explicitly with the SET BREAK command.
Predefined breakpoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are set
automatically when you invoke the debugger. Use the SHOW BREAK
command to identify all breakpoints currently set (including
predefined breakpoints).
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.
To cancel only user-defined breakpoints, do not specify
/PREDEFINED (the default is /USER). To cancel only predefined
breakpoints, specify /PREDEFINED but not /USER. To cancel both
user-defined and predefined breakpoints, specify both /USER and
/PREDEFINED.
In general, the effect of CANCEL BREAK is symmetrical with that
of SET BREAK (even though SET BREAK is used only with
user-defined breakpoints). Thus, to cancel a breakpoint that
was set at a specific location, specify that same location
(address expression) with SET BREAK. To cancel breakpoints that
were set on a class of instructions or events, specify the class
of instructions or events with the corresponding qualifier (for
example, /LINE, /BRANCH, /ACTIVATING, /EVENT=, and so on). For
more information, see help on the qualifiers.
Examples
1. DBG> SET BREAK/SILENT A\B DO (EX X)
DBG> CANCEL BREAK A\B
Cancels the effect of the previous SET BREAK command.
2. DBG> SET BREAK/INST WHEN (A .NE. 0)
DBG> CANCEL BREAK/INST
Cancels the effect of the previous SET BREAK/INST command.
3. DBG> CANCEL BREAK MAIN\LOOP+10
Cancels the user-defined breakpoint set at the address
expression MAIN\LOOP+10.
4. DBG> CANCEL BREAK/ALL
Cancels all user-defined breakpoints.
5. DBG> CANCEL BREAK/ALL/USER/PREDEFINED
Cancels all user-defined and predefined breakpoints.
6. DBG_1> CANCEL BREAK/ACTIVATING
Cancels a previous SET BREAK/ACTIVATING command. As a result,
the debugger does not suspend execution when a new process is
brought under debugger control.
7. DBG> CANCEL BREAK/EVENT=DEPENDENTS_EXCEPTION/PREDEFINED
Cancels the predefined breakpoint set on dependent exceptions.
This breakpoint is predefined for Ada programs.
Parameters
address-expression
A breakpoint to be canceled. Do not use the asterisk wildcard
(*). Do not specify an address expression with any of the
qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
Additional information available:
/ACTIVATING/ALL/BRANCH/CALL/EVENT/EXCEPTION
/INSTRUCTION/LINE/PREDEFINED/TERMINATING
/USER/VECTOR_INSTRUCTION
/ACTIVATING
Cancels the effect of a previous SET BREAK/ACTIVATING command.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
/ALL
By default, cancels all user-defined breakpoints. With
/PREDEFINED, cancels all predefined breakpoints but not
user-defined breakpoints.
To cancel all breakpoints (both predefined and user-defined),
use CANCEL/ALL/USER/PREDEFINED.
/BRANCH
Cancels the effect of a previous SET BREAK/BRANCH command.
/CALL
Cancels the effect of a previous SET BREAK/CALL command.
/EVENT=event-name
Cancels the effect of a previous SET BREAK/EVENT=event-name
command.
Format:
CANCEL BREAK/EVENT=event-name [expression[,...]]
Specify the event name (and address expression, if any) exactly
as they were specify with the SET BREAK/EVENT command.
To identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
For example, the following command cancels the predefined
breakpoint that is set on task terminations due to unhandled
exceptions. This breakpoint is predefined for Ada programs and
programs that call Ada or DECthreads routines.
DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED)
/EXCEPTION
Cancels the effect of a previous SET BREAK/EXCEPTION command.
/INSTRUCTION
Cancels the effect of a previous SET BREAK/INSTRUCTION command.
/LINE
Cancels the effect of a previous SET BREAK/LINE command.
/PREDEFINED
Cancels a specified predefined breakpoint without affecting any
user-defined breakpoints. With /ALL, cancels all predefined
breakpoints.
/TERMINATING
Cancels the effect of a previous SET BREAK/TERMINATING command.
/USER
(Default.) Cancels a user-defined breakpoint without affecting
any predefined breakpoints. With /ALL, cancels all user-defined
breakpoints. /USER is the default unless you specify
/PREDEFINED.
/VECTOR_INSTRUCTION
(Applies to vectorized programs.) Cancels the effect of a
previous SET BREAK/VECTOR_INSTRUCTION command. Do not specify
an address expression with /VECTOR_INSTRUCTION.
DISPLAY
Cancels a specified screen display or cancels all screen
displays. You must specify the names of the displays to be
canceled or the /ALL qualifier, but not both. When a screen
display is canceled, it is deleted entirely: its contents are
lost, it is removed from the screen display list, and all its
memory is released to the memory pool.
Format:
CANCEL DISPLAY [/qualifier] [display-name[,...]]
For example, the following command cancels the output display
and thus causes input and output to be intermixed:
DBG> CANCEL DISPLAY OUT
Additional information available:
Parameters
display-name
(Optional.) The screen display to be canceled. Do not specify
a display name with the /ALL qualifier.
Qualifiers
Additional information available:
/ALL
Cancels screen displays. Do not specify a display name
parameter with /ALL.
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
IMAGE
Cancels a previously set shareable image (see help on the SET
IMAGE and SHOW IMAGE commands). Cancelling an image deallocates
the data structures that were built when the image was set. If
you cancel the current image, the current image reverts back to
the main image. You cannot cancel the main image.
Format:
CANCEL IMAGE [/ALL] [image-name[,...]]
For example, the following commands set a breakpoint on routine
R in shareable image SHARE and then cancel the image:
DBG> SET IMAGE SHARE
DBG> SET BREAK R
DBG> CANCEL IMAGE SHARE
MODE
Cancels radix mode, symbolic/nosymbolic mode, and
G_float/D_float mode settings done by the SET MODE command, thus
restoring language-specific default mode values.
Format:
CANCEL MODE
MODULE
Removes symbols declared in the specified module(s) or in all
modules from the debugger symbol table. If debugger response
time becomes a problem, it may help to cancel modules that you
are not referencing. This removes symbols from those modules
from the debugger symbol table and thus may speed up searches of
the symbol table. You can remove the symbols from one module,
from a list of modules, or from all modules.
Format:
CANCEL MODULE [/qualifier] [module-name[,...]]
Examples:
DBG> CANCEL MODULE A,B,C
DBG> CANCEL MODULE/ALL
Additional information available:
Parameters
module-name
(Optional.) One or more modules whose symbols are to be removed
from the symbol table. Do not specify a module name with the
/ALL qualifier.
Qualifiers
Additional information available:
/ALL
Removes symbols in all modules from the symbol table. Do not
specify a module name parameter with /ALL.
/NORELATED
(Applies only to Ada.) Cancels only the module or modules
specified in this command. In the Ada language, related modules
may also be canceled unless you specify /NORELATED.
Example:
DBG> CANCEL MODULE/NORELATED M ! Cancels only M
DBG> CANCEL MODULE/RELATED M ! Cancel M and all packages it imports
/RELATED
(Applies only to Ada. Default.) Enables automatic module
cancelling and thereby cancels all those modules that are
related to the one specified.
RADIX
Cancels radix mode settings done by the SET RADIX command, thus
restoring language-specific default radix mode values.
Format:
CANCEL RADIX [/OVERRIDE]
Additional information available:
Qualifiers
/OVERRIDE is the only qualifier for the CANCEL/RADIX command.
It cancels the effect of a previous SET RADIX/OVERRIDE command.
SCOPE
Cancels the current scope search list done by the SET SCOPE
command. The scope search list is set back to its default value
of 0,1,2,3,4,...,N.
As a result of the CANCEL SCOPE command, symbols without
path-name prefixes are looked up relative to the current PC.
For more information, see help on the SET SCOPE command.
Format:
CANCEL SCOPE
SOURCE
Cancels the current source directory search list done by a
previous SET SOURCE command.
Format:
CANCEL SOURCE [/MODULE=module-name] [/EDIT]
Without the /MODULE qualifier, CANCEL SOURCE cancels the effect
of a previous SET SOURCE command. The CANCEL SOURCE
/MODULE=modname command cancels the effect of a previous SET
SOURCE/MODULE=modname command in which the same module name was
specified.
The CANCEL SOURCE/EDIT command cancels the effect of a previous
SET SOURCE /EDIT command. The /EDIT qualifier means that the
source directory search list is to be applied only on the EDIT
command.
Examples:
DBG> SET SOURCE [],SRC$
DBG> CANCEL SOURCE
DBG> SET SOURCE/MODULE=M []
DBG> CANCEL SOURCE/MODULE=M
Additional information available:
Qualifiers
Additional information available:
/EDIT
Cancels the effect of a previous SET SOURCE/EDIT command. This
means that the source directory search list is only to be used
on the EDIT command.
/MODULE=module-name
Specifies the module for which a source directory search list is
to be canceled.
TRACE
Cancels a tracepoint.
Format:
CANCEL TRACE [/qualifier[...]] [address-expression[,...]]
Additional information available:
DescriptionExamplesParametersQualifiers
Description
Tracepoints may be user-defined or predefined. User-defined
tracepoints are set explicitly with the SET TRACE command.
Predefined tracepoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are set
automatically when you invoke the debugger.
To identify all tracepoints currently set, use the SHOW TRACE
command (including predefined tracepoints).
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.
To cancel only user-defined tracepoints, do not specify
/PREDEFINED (the default is /USER).
To cancel only predefined tracepoints, specify /PREDEFINED but
not /USER.
To cancel both user-defined and predefined tracepoints, specify
both /USER and /PREDEFINED.
In general, the effect of CANCEL TRACE is symmetrical with that
of SET TRACE (even though SET TRACE is used only with
user-defined tracepoints). Thus, to cancel a tracepoint at a
particular location, specify the same location (address
expression) as with the SET TRACE command. To cancel
tracepoints that were set on a class of instructions or events,
specify the class of instructions or events with the
corresponding qualifier (for example, /LINE, /BRANCH,
/ACTIVATING, /EVENT=, and so on). For more information, see
help on the qualifiers.
Examples
1. DBG> SET TRACE X DO (SHOW CALLS)
DBG> CANCEL TRACE X
Cancels the effect of the previous SET TRACE X command.
2. DBG> SET TRACE/INST WHEN (A .NE. 0)
DBG> CANCEL TRACE/INST
Cancels the effect of the previous SET TRACE/INST command.
3. DBG> CANCEL TRACE MAIN\LOOP+10
Cancels the user-defined tracepoint at the location
MAIN\LOOP+10.
4. DBG> CANCEL TRACE/ALL
Cancels all user-defined tracepoints.
5. DBG_1> CANCEL TRACE/TERMINATING
Cancels a previous SET TRACE/TERMINATING command. As a result,
a tracepoint is not triggered when a process performs an image
exit.
Parameters
address-expression
(Optional.) A tracepoint to be canceled. Do not use the
asterisk wildcard (*). Do not specify an address expression
with any of the qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
Additional information available:
/ACTIVATING/ALL/BRANCH/CALL/EVENT/EXCEPTION
/INSTRUCTION/LINE/PREDEFINED/TERMINATING
/USER/VECTOR_INSTRUCTION
/ACTIVATING
Cancels the effect of a previous SET TRACE/ACTIVATING command.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
/ALL
Cancels all tracepoints.
/BRANCH
Cancels the effect of a previous SET TRACE/BRANCH command.
/CALL
Cancels the effect of a previous SET TRACE/CALL command.
/EVENT=event-name
Cancels the effect of a previous SET TRACE/EVENT=event-name
command.
Format:
CANCEL TRACE/EVENT=event-name [expression[,...]]
Specify the event name (and address expression, if any) exactly
as they were specify with the SET TRACE/EVENT command.
To identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
For example, the following command cancels the tracepoint that
was set to trigger when task 3 (task ID = 3) entered the RUN
state:
DBG> CANCEL TRACE/EVENT=RUN %TASK 3
/EXCEPTION
Cancels the effect of a previous SET TRACE/EXCEPTION command.
/INSTRUCTION
Cancels the effect of a previous SET TRACE/INSTRUCTION command.
/LINE
Cancels the effect of a previous SET TRACE/LINE command.
/PREDEFINED
Cancel a predefined tracepoint without affecting any
user-defined tracepoints. With /ALL, cancels all predefined
tracepoints.
/TERMINATING
Cancels the effect of a previous SET TRACE/TERMINATING command.
/USER
(Default.) Cancels a user-defined tracepoint without affecting
any predefined tracepoints. With /ALL, cancels all user-defined
tracepoints. /USER is the default unless you specify
/PREDEFINED.
/VECTOR_INSTRUCTION
(Applies to vectorized programs.) Cancels the effect of a
previous SET TRACE/VECTOR_INSTRUCTION command. Do not specify
an address expression with /VECTOR_INSTRUCTION.
TYPE
Cancels the debugger override type done by the SET TYPE/OVERRIDE
command, thus setting the current override type to none. As a
result of CANCEL TYPE/OVERRIDE, program entities are interpreted
in compiler-generated types or in the default type.
Format:
CANCEL TYPE/OVERRIDE
Additional information available:
Qualifiers
Additional information available:
/OVERRIDE
Must be specified. The minimum abbreviation is /OVERR.
WATCH
Cancels the specified watchpoint(s). If you specify an address
expression parameter, the watchpoint at the location denoted by
that address-expression is canceled. With /ALL, cancels all
watchpoints.
Format:
CANCEL WATCH { /ALL | address-expression[,...] }
Additional information available:
Examples
1. DBG> SET WATCH A[1] DO (SHOW CALLS)
DBG> CANCEL WATCH A[1]
Cancels the effect of the previous SET WATCH command.
2. DBG> CANCEL WATCH/ALL
Cancels all watchpoints.
Parameters
address-expression
(Optional.) The location of the watchpoint to be canceled. Do
not specify an address expression with the /ALL qualifier.
Qualifiers
Additional information available:
/ALL
Cancels all all watchpoints. Do not specify an address
expression parameter with /ALL.
WINDOW
Cancels one or more specified screen window definitions or
cancels all such definitions.
Format:
CANCEL WINDOW { /ALL | window-name[,...] }
You must specify the names of the screen windows to be canceled
or the /ALL qualifier, but not both. When you cancel a screen
window definition, the corresponding window name is no longer
available for use in a DISPLAY command. The CANCEL WINDOW
command does not affect any existing screen displays.
Example:
DBG> CANCEL WINDOW Q1,Q2
Additional information available:
Parameters
window-name
(Optional.) The screen window to be canceled. Do not specify a
window name with the /ALL qualifier.
Qualifiers
Additional information available:
/ALL
Cancels all screen window definitions. Note that this cancels
all predefined as well as user-defined window definitions. Do
not specify a window name parameter with /ALL.
CONNECT
Interrupts an image running without debugger control in another
process and brings that process under debugger control.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
Format:
CONNECT [process-spec[,...]]
Additional information available:
Description
Without a parameter, CONNECT brings any spawned process that is
waiting to connect to the debugger under debugger control.
If you specify a process, CONNECT interrupts an image running
without debugger control in that process and brings the process
under debugger control. This is useful if you run a debuggable
image with the DCL command RUN/NODEBUG or if your program issues
a LIB$SPAWN run-time library call or a $CREPRC system service
call that does not invoke the debugger.
You can bring a process under debugger control in this manner
only if that process is in the same job tree as the process
running the debugging session (the process running the main
debugger image, DEBUGSHR.EXE), and only if the image was not
linked with the /NOTRACEBACK qualifier. Also, you have full
symbolic information for that image only if its modules were
compiled and linked with the /DEBUG qualifier.
When the process is brought under debugger control, execution of
the image is suspended at the point at which it was interrupted.
Without a parameter, CONNECT brings any processes that are
waiting to connect to your debugging session under debugger
control. If no process is waiting, you can press Ctrl/C to
abort the CONNECT command.
By default, a tracepoint is triggered when a process is brought
under debugger control. This predefined tracepoint is the same
as that from the SET TRACE/ACTIVATING command. The process is
then known to the debugger and is identified in a SHOW PROCESS
display.
Examples
1. DBG_1> CONNECT
Brings any processes that are waiting to be connected to the
debugger under debugger control.
2. DBG_1> CONNECT JONES_3
Interrupts the image running in process JONES_3 and brings the
process under debugger control. Process JONES_3 must be in the
same job tree as the process where the debugger was invoked.
Also, the image must not have been linked with the /NOTRACEBACK
qualifier.
Parameters
process-spec
(Optional.) The process in which an image to be interrupted is
running. The process must be in the same job tree as the
debugging session. Use any of the following forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification
number (PID, a hexadecimal number).
Ctrl C
Pressing Ctrl/C during a debugging session aborts the execution
of a debugger command or interrupts program execution without
interrupting the debugging session. This is useful if the
program is executing an infinite loop that does not have a
breakpoint or if you want to abort a debugger command that takes
a long time to complete. The debugger prompt is then displayed,
so that you can enter debugger commands.
Format:
<Ctrl/C>
(This format means you hold down the CTRL key and type a C.)
After a Ctrl/C interruption, any processes of a multiprocess
program that were executing images are in the interrupted state.
If your program already has a Ctrl/C AST service routine
enabled, use the SET ABORT_KEY command to assign the debugger's
abort function to another control key. However, many control
keys have VMS predefined functions, and the SET ABORT_KEY
command lets you override such definitions (see the VMS DCL
Concepts Manual). Some control keys not used by the VMS
operating system are Ctrl/G, Ctrl/K, Ctrl/N, and Ctrl/P.
If your program does not have a Ctrl/C AST service routine
enabled, and you assign the debugger's abort function to another
control key, then Ctrl/C behaves like Ctrl/Y --- that is, it
interrupts the debugging session and returns you to the DCL
level.
Do not use Ctrl/Y from within a debugging session. Always use
either Ctrl/C or an equivalent control key specified with the
SET ABORT_KEY command.
Note that you can use the SPAWN and ATTACH commands to leave and
return to a debugging session without losing the debugging
context.
Additional information available:
Examples
The following example shows how to use Ctrl/C to interrupt
program execution and then to abort the execution of a debugger
command:
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>
Ctrl W
Pressing Ctrl/W in screen mode is the same as the
DISPLAY/REFRESH command.
Format:
<Ctrl/W>
(This format means you hold down the CTRL key and type a W.)
Ctrl Y
Pressing Ctrl/Y at the DCL level interrupts an image running
without debugger control, so that you can then invoke the
debugger with the DEBUG command at the DCL level.
Format:
<Ctrl/Y>
(This format means you hold down the CTRL key and type a Y.)
Note that you can bring an image under debugger control only if,
as a minimum, that image was linked with the /TRACEBACK
qualifier (the default). Also, you can reference all of the
image's symbols while debugging only if its modules were
compiled and linked with the /DEBUG qualifier (in that case, you
could use the RUN/NODEBUG command at the DCL level to execute
the image without the debugger).
When you press Ctrl/Y to interrupt the image's execution,
control is passed to the DCL command interpreter. If you then
type the DEBUG command, the interrupted image is brought under
control of the debugger. The debugger sets its language
dependent parameters to the source language of the module where
execution was interrupted and displays its prompt. You can then
determine where execution was suspended by issuing a SHOW CALLS
command (and a SHOW PROCESS command, in the case of a
multiprocess program).
When a new debugging session is started, a process is created to
run the main debugger image (DEBUGSHR.EXE) that controls the
session. The main debugger process is a subprocess of the
process that is running the image to be debugged. The debugger
displays its banner when a new session is started.
Other effects of a Ctrl/Y--DEBUG sequence depend on the
debugging configuration (default or multiprocess), which is
determined by the current definition of the DBG$PROCESS logical
name in the process where the interrupted image was executing.
Do not use Ctrl/Y from within a debugging session. Instead, use
Ctrl/C (or another control key specifed with the SET_ABORT_KEY
command). This lets you abort the execution of a debugger
command or to interrupt program execution without interrupting
the debugging session.
Additional information available:
ExamplesDefault ConfigurationMultiprocess Configuration
Examples
1. $ RUN/NODEBUG TEST_B
...
<Ctrl/Y>
Interrupt
$ DEBUG
VAX DEBUG Version *****
%DEBUG-I-INITIAL, language is ADA, module set to SWAP
DBG>
The RUN/NODEBUG command executes the image TEST_B without
debugger control. Execution is interrupted with Ctrl/Y. The
DEBUG command then invokes the debugger. The debugger displays
its banner, sets the language-dependent parameters to the
language (Ada, in this case) of the module (SWAP) where
execution was interrupted, and displays the prompt. This is the
default debugging configuration, as indicated by the DBG>
prompt.
2. $ DEFINE/JOB DBG$PROCESS MULTIPROCESS
$ RUN/NODEBUG PROG2
...
<Ctrl/Y>
Interrupt
$ DEBUG
VAX DEBUG Version *****
%DEBUG-I-INITIAL, language is FORTRAN, module set to SUB4
predefined trace on activation at SUB4\%LINE 12
in %PROCESS_NUMBER 1
12: K = K + 1
DBG_1>
The DEFINE/JOB command specifies a multiprocess debugging
configuration. The RUN/NODEBUG command executes the image PROG2
without debugger control. The Ctrl/Y--DEBUG sequence interrupts
execution and invokes the debugger. The VAX DEBUG banner
indicates that a new debugging session has been started. The
process-specific prompt (DBG_1>) indicates that this is a
multiprocess configuration and that execution is suspended in
process 1, which is running PROG2. The activation tracepoint
identifies the location where execution was interrupted (and
where the debugger took control of the process).
Default Configuration
The default debugging configuration applies when the DBG$PROCESS
logical name is either undefined or is defined as DEFAULT. In
this case a new default debugging session is started every time
you invoke the debugger with the Ctrl/Y--DEBUG sequence.
Multiprocess Configuration
The multiprocess debugging configuration is achieved when the
DBG$PROCESS logical name has the job-wide definition
MULTIPROCESS. In this case, the effect of a Ctrl/Y--DEBUG
sequence is as follows:
o If a multiprocess debugging session does not already exist in
the same job tree as the process running the interrupted
image, a new multiprocess debugging session is created.
o If a multiprocess debugging session already exists in the
same job tree, the interrupted image and its process come
under control of that session. In this case the debugger
does not display its banner.
Note that within a debugging session, you can use the CONNECT
command to connect an image that is running without debugger
control in another process (of the same job tree) to that
debugging session.
Ctrl Z
Pressing Ctrl/Z is the same as the EXIT command --- ends the
debugging session.
Format:
<Ctrl/Z>
(This format means you hold down the CTRL key and type a Z.)
DECLARE
(Valid only inside a debugger command procedure.) Binds the
actual parameters to names of formal parameters inside a command
procedure.
Format:
DECLARE formal-name[:kind] [,formal-name[:kind],...]
In the simplest case, this could look like:
DECLARE A,B,C
Then, if three parameters were passed to the command procedure,
they can be referenced inside the command procedure by the names
A, B, and C. The number of parameters to the procedure is given
by the %PARCNT symbol (see help on Built_in_Symbols %PARCNT).
Additional information available:
Examples
$ CREATE DUMPMEM.COM
DECLARE P1:ADDRESS,P2:VALUE
EXAMINE P1:P1+P2
Parameters
formal-name
The formal parameter. The name can be composed of alphabetics
(A--Z) and numerics (0--9) and must start with an alphabetic.
kind
(Optional.) Can be ADDRESS, COMMAND, or VALUE, corresponding to
the three kinds of DEFINE symbols.
DEFINE
Assigns a symbolic name (a string) to an address expression, a
debugger command, a group of processes, or a value, depending on
the qualifiers:
/ADDRESS (default)
/COMMAND
/PROCESS_GROUP
/VALUE
This lets you define an abbreviated name or string that you can
then use to refer to an address, a command, a group of
processes, or a value.
Format for /ADDRESS, /COMMAND, or /VALUE:
DEFINE [/qualifier] symbol-name=expression[,...]
The DEFINE/KEY command assigns a string to a function key. (See
help on /KEY.)
For information about DEFINE/PROCESS_GROUP, see help on the
/PROCESS_GROUP qualifier.
Additional information available:
/ADDRESS/COMMAND/KEY/LOCAL/PROCESS_GROUP
/VALUE
Examples
1. In the following example, you define a short name X for a
program location whose name is long. Note that /ADDRESS is the
default, so you do not need to specify it here.
DBG> DEFINE X = ROUTINENAME\SUBROUTINENAME\VARNAME
DBG> EXAMINE X
ROUTINENAME\SUBROUTINENAME\VARNAME: 17
2. The following command abbreviates a debugger command.:
DBG> DEFINE/COMMMAND Z = "STEP/SILENT; EX ARR[I]"
DBG> Z ! This now does the above command
3. The following command redefines the KP0 key:
DBG> DEFINE/KEY/TERM/NOECHO KP0 "STEP/SILENT; EX ARR[I]"
NOTE: For more examples of DEFINE/KEY see help on the /KEY
qualifier. For example of DEFINE/PROCESS_GROUP, see help
on the /PROCESS_GROUP qualifier.
Parameters
symbol-name
The symbol to be defined. This can be composed of alphabetics
(A--Z) and numerics (0--9) and must start with an alphabetic.
For the DEFINE/KEY command, the name of a keypad key.
expression
For the DEFINE/ADDRESS command, any address expression.
For the DEFINE/COMMAND or DEFINE/KEY command, any string
enclosed in quotes ("). Quotes inside quotes must be doubled.
For the DEFINE/VALUE command, any language expression in the
currently set language.
/ADDRESS
(Default.) Defines a symbol for an address which can then be
used anywhere that an address expression is allowed, for
example, in the EXAMINE command, in the SET WATCH command, and
so on.
Example:
DBG> DEFINE X = PROGRAM\VARNAME[4].COMPNAME
DBG> SET WATCH X
DBG> EXAMINE X
/COMMAND
Defines a symbol for a debugger command or the initial portion
of a debugger command.
Example:
DBG> DEFINE/COMMAND EB = "EXAMINE/BINARY/LONG "
DBG> EB Y
PROGRAM\Y: 11000111 00000000 10000001 01111110
/KEY
Defines a keypad key, using the same syntax as the DEFINE/KEY
command at DCL. SET MODE KEYPAD must be in effect. The
debugger provides some default key definitions. The DEFINE/KEY
command lets you override the default definitions.
Format:
DEFINE/KEY [/qualifier[...]] key-name "key-definition"
Examples:
DBG> DEFINE/KEY/NOECHO/TERMINATE KP0 "STEP"
DBG> DEFINE/KEY/IF_STATE=GOLD KP1 "EXAMINE X"
Additional information available:
/ECHO/IF_STATE/LOCK_STATE/LOG/NOECHO/NOIF_STATE
/NOLOCK_STATE/NOLOG/NOSET_STATE/NOTERMINATE
/SET_STATE/TERMINATE
Key Names
The key you want to define. Use any of the following key names.
Note that some keys are not available on VT100 and VT52 series
terminals.
Key name LK201 VT100-type VT52-type
---------------------------------------------------------
PF1 PF1 PF1 PF1
PF2 PF2 PF2 PF2
PF3 PF3 PF3 PF3
PF4 PF4 PF4 PF4
KP0,...,KP9 0,1,...,9 0,1,...,9 0,1,...,9
PERIOD . . .
COMMA , , ,
MINUS - - -
ENTER Enter ENTER ENTER
UP ^ ^ ^
DOWN v v v
LEFT <- <- <-
RIGHT -> -> ->
E1 Find n/a n/a
E2 Insert Here n/a n/a
E3 Remove n/a n/a
E4 Select n/a n/a
E5 Prev Screen n/a n/a
E6 Next Screen n/a n/a
HELP Help n/a n/a
DO Do n/a n/a
F6,F7,...,F20 F6,F7,...,F20 n/a n/a
/ECHO
(Default.) Displays (echoes) the key definition when you press
the key.
/IF_STATE=state-name
Applies the key definition only to the specified state.
For example, if the PF1 key sets you to GOLD state, and you
enter:
DBG> DEFINE/KEY/IF_STATE=GOLD KP0 "EXAMINE X"
then the PF1-KP0 sequence expands to EXAMINE X.
/LOCK_STATE
Specifies that the state set by the /SET_STATE qualifier is to
remain the active state until explicitly changed. The default
is /NOLOCK_STATE.
/LOG
(Default.) Displays a message confirming the key definition.
/NOECHO
Specifies that the key definition is not to be echoed on the
terminal when the key is used. The default is /ECHO.
/NOIF_STATE
(Default.) Defines the key only for the current state.
/NOLOCK_STATE
(Default.) Specifies that the state transition specified by the
current key takes effect only until the next terminator
character is typed or until after the next function key is
pressed.
/NOLOG
Suppresses the message confirming the key definition.
/NOSET_STATE
(Default.) Specifies that the current state is not to change
when the function key being defined is entered.
/NOTERMINATE
(Default.) Specifies that the key does not terminate the
command.
/SET_STATE=state-name
Enables the specified state when the key being defined is used.
The default is /NOSET_STATE.
/TERMINATE
Specifies that the key terminates the command. The default is
/NOTERMINATE.
/LOCAL
Specifies that the symbol definition is local to the command
procedure and is deleted when the command procedure is exited.
You can use /LOCAL only only with /ADDRESS, /COMMAND, or /VALUE.
/PROCESS_GROUP
Assigns a symbolic name to a list of process specifications.
You can then use the symbol in any command where a list of
process specifications is allowed. This lets you specify
processes that do not yet exist, but does not verify the
existence of a specified process.
Format:
DEFINE/PROCESS_GROUP process-group-name [=process-spec[,...]]
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
To identify a symbol that was defined with DEFINE/PROCESS_GROUP,
use the SHOW SYMBOL/DEFINED command.
To delete a symbol that was defined with DEFINE/PROCESS_GROUP,
use the DELETE command.
Additional information available:
Examples
1. DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER, NETWORK_SERVER
DBG_1> SHOW PROCESS SERVERS
Number Name Hold State Current PC
* 1 FILE_SERVER step FS_PROG\%LINE 37
2 NETWORK_SERVER break NET_PROG\%LINE 24
Assigns the SERVERS symbolic name to the process group
consisting of FILE_SERVER and NETWORK_SERVER. The SHOW PROCESS
SERVERS command displays information about the processes that
make up the group SERVERS.
2. USER_3> DEFINE/PROCESS_GR G1 = %PROCESS_NUMBER 1,%VISIBLE_PROCESS
USER_3> SHOW SYMBOL/DEFINED G1
defined G1
bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS"
was defined /process_group
USER_3> DELETE G1
Assigns the G1 symbolic name to the process group consisting of
process 1 and the visible process (process 3), identifies the
defined symbol G1, and then deletes the symbol from the DEFINE
symbol table.
3. DBG_2> DEFINE/PROCESS_GROUP A = B,C,D
DBG_2> DEFINE/PROCESS_GROUP B = E,F,G
DBG_2> DEFINE/PROCESS_GROUP E = I,J,A
%DEBUG-E-NORECSYM, recursive PROCESS_GROUP symbol
definition encountered at or near "A"
This series of DEFINE/PROCESS_GROUP commands illustrate valid
and invalid uses of the command.
Parameters
process-group-name
A symbolic name to be assigned to a list of process
specifications. The symbolic name can be composed of
alphanumeric characters and underscores. The debugger converts
lowercase alphabetic characters to uppercase. The first
character must not be a number. The symbolic name must be no
more than 31 characters long.
process-spec
(Optional.) Specifies a process. Use any of the following
forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
If you do not specify a process, the symbolic name is created
but contains no process entries.
/VALUE
Interprets the expression as a value in the current language.
The defined symbol can then be used anywhere a value expression
is allowed, such as in an EVALUATE command.
For example, the following commands define an abbreviation for a
double-floating number and then use that abbreviation in an
evaulation:
DBG> DEFINE/VAL F = 1.103763783D27
DBG> EVALUATE F + 1.0D27
2.103763783D27
DELETE
Deletes a symbol definition that you specified with the DEFINE
command.
The DELETE/KEY command deletes a key definition.
Format:
DELETE [/qualifier] [symbol-name[,...]]
Examples:
DBG> DEFINE A = MAIN\VAR1
DBG> EXAMINE A
MAIN\VAR1: 5
DBG> DELETE A ! Cancels effect of "DEFINE A"
DBG> EXAMINE A
%DEBUG-E-NOSYMBOL, symbol 'A' is not in the symbol table
Additional information available:
Parameters
symbol-name
(Optional.) Any symbol previously defined with the DEFINE
command. Do not specify a symbol name with the /ALL qualifier.
Qualifiers
Additional information available:
Key Names
The key you want to undefine. Use any of the following key
names. Note that some keys are not available on VT100 and VT52
series terminals.
Key name LK201 VT100-type VT52-type
---------------------------------------------------------
PF1 PF1 PF1 PF1
PF2 PF2 PF2 PF2
PF3 PF3 PF3 PF3
PF4 PF4 PF4 PF4
KP0,...,KP9 0,1,...,9 0,1,...,9 0,1,...,9
PERIOD . . .
COMMA , , ,
MINUS - - -
ENTER Enter ENTER ENTER
UP ^ ^ ^
DOWN v v v
LEFT <- <- <-
RIGHT -> -> ->
E1 Find n/a n/a
E2 Insert Here n/a n/a
E3 Remove n/a n/a
E4 Select n/a n/a
E5 Prev Screen n/a n/a
E6 Next Screen n/a n/a
HELP Help n/a n/a
DO Do n/a n/a
F6,F7,...,F20 F6,F7,...,F20 n/a n/a
Do not specify a key name with the /ALL qualifier.
Additional information available:
/ALL/LOG/NOLOG/NOSTATE/STATE/LOCAL
/ALL
Deletes all key definitions in the specified states. Do not
specify a key name parameter with /ALL.
/LOG
(Default.) Displays an informational message for each key
deleted.
/NOLOG
Supresses the informational messages for the deleted keys. The
default is /LOG.
/NOSTATE
(Default.) Applies the DELETE command only to the current
state.
/STATE=(state-name[,...])
Deletes key definitions for the specified state(s). The default
is /NOSTATE.
/LOCAL
Deletes the (local) definition of the specified symbol from the
current command procedure. The symbol must have been previously
defined with the DEFINE/LOCAL command.
/ALL
Deletes all global definitions specified with the DEFINE
command.
With the /LOCAL qualifier, /ALL deletes all local definitions
specified with the DEFINE command that are associated with the
current command procedure (but not the global definitions). Do
not specify a symbol name parameter with /ALL.
/KEY
Deletes a key definition created with the DEFINE/KEY command or
a debugger default key definition.
Format:
DELETE/KEY [/qualifier[...]] [key-name]
Examples:
DBG> DEFINE/KEY F6 "STEP"
DBG> DELETE/KEY F6
DEPOSIT
Changes the contents of memory locations in your program.
Format:
DEPOSIT [/qualifier] address-expression = expression
For Pascal or Ada:
DEPOSIT [/qualifier] address-expression := expression
The value specified to the right of the equal sign is deposited
into the location specified to the left of the equal sign. Type
conversion is done, if necessary, according to the rules of the
currently set language. Thus, the DEPOSIT A = B command should
have the same effect as the assignment statement A = B in your
program. (Note: For Pascal and Ada, substitute := for = in the
previous sentence).
To change change the assembly-language instructions being
executed, use DEPOSIT/INSTRUCTION (see help on the /INSTRUCTION
qualifier).
Additional information available:
Examples
DBG> DEPOSIT L = 10
DBG> DEPOSIT/FLOAT L = 1.1
DBG> DEPOSIT/INSTRUCTION %LINE 100 = 'MOVL R0,R1'
DBG> DEPOSIT X = %HEX 10
Parameters
address-expression
The location to be deposited.
expression
The value to be deposited. This is usually a constant (for
example, DEPOSIT X = 2), but it may be an expression (for
example, DEPOSIT X = X + 2).
Qualifiers
The qualifiers for the DEPOSIT command override the type
information associated with the location. For example, suppose
F is a floating point number. If you do the following
command ---
DBG> DEPOSIT F = 1
then the debugger converts integer 1 to floating 1.0 and puts
the 1.0 into location F. But if you want to put integer 1 into
the location, you must override the F type with the /LONG
(integer longword) qualifier:
DBG> DEPOSIT/LONG F = 1
See help on the qualifier subtopics.
Additional information available:
/ASCIC/ASCID/ASCII/ASCIW/ASCIZ/BYTE/D_FLOAT
/DATE_TIME/FLOAT/G_FLOAT/H_FLOAT/INSTRUCTION
/LONGWORD/OCTAWORD/PACKED:n/QUADWORD
/TASK/TYPE/WORD
/ASCIC
Deposits a counted ASCII string into the target. The first byte
in the string specifies the length.
/AC is also accepted.
Example:
DBG> DEPOSIT/AC X = "111"
DBG> EXAMINE/HEX/LONG X
X: 31313103
/ASCID
Deposits a string into the address given by the string
descriptor. The target of the deposit must contain a string
descriptor. The expression on the righthand side must be a
string.
If the lengths do not match, the string is either truncated on
the right or padded with blanks on the right.
/AD is also accepted.
Example:
DBG> EXAMINE/QUAD/HEX D
D: 7FFF0000 01E00004
DBG> DEPOSIT/AD D = "ABCD"
DBG> EXAMINE/ASCII:4 7FFF0000
7FFF0000: "ABCD"
DBG> EXAMINE/AD D
D: "ABCD"
/ASCII[:n]
Deposits n bytes of string into the target location. The
expression on the righthand side must be a string. If its
length is not n, then the string is truncated or padded with
blanks on the right. If you omit n, then the debugger uses the
actual length of the data item at the target location.
Example:
DBG> DEPOSIT/ASCII:5 X = "ABCDE"
DBG> EXAMINE/ASCII:5 X
X: "ABCDE"
/ASCIW
Deposits an "asciw string" (a string with a word count at the
beginning) into the target location. The righthand side of the
deposit must specify a string.
/AD is also accepted.
Example:
DBG> DEPOSIT/AW X = "11"
DBG> EXAMINE/HEX/LONG X
X: 31310002
/ASCIZ
Deposits a string into the target followed by a zero byte
indicating end of string. The righthand side must be a string.
/AZ is also accepted.
Example:
DBG> DEPOSIT/AZ X = "AAA"
DBG> EXAMINE/LONG/HEX X
X: 00313131
/BYTE
Deposits one byte into the target location.
Example:
DBG> EXAMINE/HEX X
X: 0FFFFFFFF
DBG> DEPOSIT/BYTE X = 0
DBG> EXAMINE/HEX X
X: 0FFFFFF00
/D_FLOAT
Converts the righthand side to D_floating point (length 8 bytes)
and deposits that value into the location specified by the
lefthand side.
Example:
DBG> DEPOSIT/D_FLOAT X = 1.1
DBG> EXAMINE/D_FLOAT X
X: 1.1000000000000000
/DATE_TIME
Converts a string representing a date and time (for example,
"14-Oct-1984 12:00:00") to a quadword representation and
deposits that representation into 8 bytes at the target address.
Example:
DBG> DEPOSIT/DATE_TIME X = "14-Oct-1984 12:00:00"
DBG> EXAMINE/DATE_TIME X
X: "14-Oct-1984 12:00:00"
/FLOAT
Converts the righthand side to floating point and deposits that
value into the location specified by the lefthand side.
Example:
DBG> DEPOSIT/FLOAT X = 1.1
DBG> EXAMINE/FLOAT X
X: 1.100000
/G_FLOAT
Converts the righthand side to G-format floating point and
deposits that value into the location specified by the lefthand
side.
Example:
DBG> DEPOSIT/G_FLOAT X = 1.1
DBG> EXAMINE/G_FLOAT X
X: 1.100000000000000
/H_FLOAT
Converts the righthand side to H-format floating point and
deposits that value into the location specified by the lefthand
side.
Example:
DBG> DEPOSIT/H_FLOAT X = 1.1
DBG> EXAMINE/H_FLOAT X X: 1.10000000000000000000000000000
/INSTRUCTION
Deposits the instuction into the location specified by the
lefthand side. The righthand side must be a string representing
a VAX instruction.
Example:
DBG> DEPOSIT/INS %LINE 100 = 'MOVL 2,B^4(R1)'
DBG> EXAMINE/INS %LINE 100
%LINE 100: "MOVL 2,B^4(R1)"
/LONGWORD
Deposits a longword into the target location.
Example:
DBG> EXAMINE/HEX X
X: 0FFFFFFFF
DBG> DEPOSIT/LONG X = 0
DBG> EXAMINE/HEX X
X: 00000000
/OCTAWORD
Deposits an octaword (16 bytes) into the target location.
Example:
DBG> EXAMINE/OCTAW/HEX X
X: 00000000 00000000 00000000 00000000
DBG> DEPOSIT/OCTAW X = -1
DBG> EXAMINE/OCTAW/HEX X
X: 0FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF
/PACKED:n
Converts the righthand side to a packed decimal representation
(length n nibbles) before doing the deposit, and deposits n
nibbles ((n+1)/2 bytes) into the lefthand side.
Example:
DBG> DEPOSIT/PACKED:5 X = 12345
DBG> EXAMINE/PACKED:5 X
X: 12345
/QUADWORD
Deposits a quadword (8 bytes) into the target location.
Example:
DBG> EXAMINE/QUAD/HEX X
X: 0FFFFFFFF FFFFFFFF
DBG> DEPOSIT/QUAD X = 0
DBG> EXAMINE/QUAD/HEX X
X: 00000000 00000000
/TASK
(Applies to tasking, or multithread, programs.) Deposits a task
value (a task name or a task ID, such as %TASK 3) into the
specified location. The deposited value must be a valid task
value.
/TYPE=(expression)
Treats the lefthand side as if it were of the specified type.
This qualifier is normally used only with the EXAMINE command
--- for example, EXAMINE/TYPE=(T) 1000. For more information,
see help on the EXAMINE/TYPE command. The /TYPE qualifier is
supplied for the DEPOSIT command for completeness.
/WORD
Deposits a word (2 bytes) into the target location.
Example:
DBG> EXAMINE X
X: 0FFFFFFFF
DBG> DEPOSIT/WORD X = 0
DBG> EXAMINE X
X: 0FFFF0000
DISABLE
Disables ASTs in the user program. To disable ASTs during a
debugging session, use the DISABLE AST command. To re-enable
ASTs, use the ENABLE AST command. Temporarily disabling ASTs in
this fashion prevents interrupts from occuring while you are
debugging a particular piece of code.
Format:
DISABLE AST
Example:
DBG> SHOW AST
ASTs are enabled
DBG> DISABLE AST
%DEBUG-I-DISABLEAST, ASTs were enabled, are now disabled
DBG> SHOW AST
ASTs are disabled
DISPLAY
Creates a display or modifies an existing display.
Format:
DISPLAY [display-name [AT window-spec] [display-kind]][,...]
To create a display, specify a name that is not already used as
a display name. For a list of the existing displays, use the
SHOW DISPLAY command.
By default, the DISPLAY command puts a specified display on top
of the display pasteboard, ahead of any other displays but
behind the PROMPT display, which cannot be hidden. The
specified display thus hides the portions of other displays
(except the PROMPT display) that share the same region of the
screen.
For more information, see help on see help on Keypad_Defintions.
Additional information available:
Examples
1. DBG> DISPLAY REG
Shows the predefined register display, REG, at its current
window location.
2. DBG> DISPLAY/PUSH INST
Pushes display INST to the bottom of the display pasteboard,
behind all other displays.
3. DBG> DISPLAY NEWDISP AT RT2
DBG> SELECT/INPUT NEWDISP
Shows the user-defined display NEWDISP at the right middle third
of the screen. The SELECT/INPUT command selects NEWDISP as the
current input display. NEWDISP now echoes debugger input.
4. DBG> DISPLAY DISP2 AT RS45
DBG> SELECT/OUTPUT DISP2
Creates a display named DISP2 essentially at the right bottom
half of the screen, above the PROMPT display, which is located
at S6. By default, this is an output display. The
SELECT/OUTPUT command then selects DISP2 as the current output
display.
5. DBG> SET WINDOW TOP AT (1,8,45,30)
DBG> 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 DISPLAY command
creates an instruction display named NEWINST to be displayed
through TOP. The SELECT/INST command selects NEWINST as the
current instruction display.
6. DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)
Creates a DO display named CALLS at window Q3. Each time the
debugger gains control from the program, the SHOW CALLS command
executes and the output is displayed in display CALLS, replacing
any previous contents.
7. DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C)
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.
8. DBG_3> DISPLAY/PROCESS OUT_X AT S4
Makes display OUT_X specific to the visible process (process 3)
and puts the display at window S4.
9. DBG_2> DISPLAY/PROCESS OUT_/SUFFIX AT S45 OUTPUT
Creates an output display at window S45. By default, /PROCESS
makes the display specific to the visible process (process 2, in
this example). The /SUFFIX qualifier appends a process
identifier suffix, which denotes the visible process, to the
display name OUT_. By default, /SUFFIX appends the same process
identifier suffix that appears on the prompt. Therefore, the
full display name is OUT_2.
Parameters
display-name
(Optional.) The display to be created or modified. If you are
creating a new display, specify a name that is not already used
as a display name.
If you are modifying an existing display, you can specify any of
the following:
o A predefined display: SRC, OUT, PROMPT, INST, REG
o A display previously created with the DISPLAY command
o A pseudo-display name:
%CURDISP %CURSCROLL %NEXTDISP %NEXTINST
%NEXTOUTPUT %NEXTSCROLL %NEXTSOURCE
You must specify a display unless you use /GENERATE (parameter
optional), or /REFRESH (parameter not allowed).
You can specify more than one display, each with an optional
window specification and display kind.
window-spec
(Optional.) The screen window where the display is to be
positioned. You can specify any of the following:
o A predefined window. For example, RH1 (right top half).
o A window definition previously specified with the SET WINDOW
command.
o A window specification of the form (start-line, line-count
[,start-column, column-count]). The specification can
include expressions which may be based on the built-in
symbols %PAGE and %WIDTH (for example, %WIDTH/4).
If you do not specify a window, the screen position depends on
whether you specify an existing display or a new display:
o For an existing display, the position of the display is not
changed.
o For a new display, it is positioned at window H1 or H2,
alternating between H1 and H2 each time you create another
display.
display-kind
(Optional.) Valid keywords are the following:
Keyword Effect
----------------------------------------------------------------
DO (command[; ...]) Specifies an automatically updated output
display. The commands execute in the
order listed each time the debugger gains
control. Their output forms the contents
of the display. If you specify more than
one command, they must be separated by
semicolons (;).
INSTRUCTION Specifies an instruction display. If
selected as the current instruction dis-
play with the SELECT/INSTRUCTION command,
it displays the output from subsequent
EXAMINE/INSTRUCTION commands.
INSTRUCTION (command) Specifies an automatically updated in-
struction display. The command specified
must be an EXAMINE/INSTRUCTION command.
The instruction display is updated each
time the debugger gains control.
OUTPUT Specifies an output display. If selected
as the current output display with the
SELECT/OUTPUT command, it displays any
debugger output that is not directed
to another display. If selected as the
current input display with the SELECT
/INPUT command, it echoes debugger input.
If selected as the current error display
with the SELECT/ERROR command, it dis-
plays debugger diagnostic messages.
REGISTER Specifies an automatically updated
register display. The display is updated
each time the debugger gains control.
SOURCE Specifies a source display. If selected
as the current source display with
the SELECT/SOURCE command, it displays
the output from subsequent TYPE or
EXAMINE/SOURCE commands.
SOURCE (command) Specifies an automatically updated source
display. The command specified must be a
TYPE or EXAMINE/SOURCE command. The source
display is updated each time the debugger
gains control.
You cannot change the display kind of the PROMPT display.
If you omit the display-kind parameter, the display kind depends
on whether you specify an existing display or a new display:
o For an existing display, the display kind is not changed.
o For a new display, an OUTPUT display is created.
Qualifiers
Additional information available:
/CLEAR/DYNAMIC/GENERATE/HIDE/MARK_CHANGE
/NODYNAMIC/NOMARK_CHANGE/NOPOP/NOPROCESS
/NOPUSH/POP/PROCESS/PUSH/REFRESH/REMOVE/SIZE:n
/SUFFIX
/CLEAR
Erases the entire contents of a specified display. Do not use
/CLEAR when creating a new display or with /GENERATE.
/DYNAMIC
(Default.) Controls whether a display automatically adjusts its
window dimensions proportionally when the screen height or width
is changed by a SET TERMINAL command. By default, all
user-defined and predefined displays, adjust their dimensions
automatically.
/GENERATE
Regenerates the contents of a specified display. Only
automatically generated displays are regenerated. These include
DO displays, register displays, source (cmd-list) displays, and
instruction (cmd-list) displays. The debugger automatically
regenerates all these kinds of displays before each prompt.
If you do not specify a display, the debugger regenerates the
contents of all automatically generated displays. Do not use
/GENERATE when creating a new display or with /CLEAR.
/HIDE
Same as /PUSH. Puts a specified display at the bottom of the
display pasteboard. This hides the specified display behind any
other displays that share the same region of the screen. You
cannot hide the PROMPT display.
/MARK_CHANGE
Marks the lines that change in a DO display each time it is
automatically updated. Any lines in which some contents have
changed since the last time the display was updated are
highlighted in reverse video. This is particularly useful when
you want any variables in an automatically updated display to be
highlighted when they change.
/NOMARK_CHANGE (default) specifies that any lines that change in
DO displays are not to be marked. This cancels the effect of a
previous /MARK_CHANGE for the specified displays; not applicable
to other kinds of displays.
/NODYNAMIC
Specifies that a display is not to automatically adjust its
window dimensions when you change the screen height or width
with a SET TERMINAL command. The default is /DYNAMIC.
/NOMARK_CHANGE
(Default.) Specifies that changed lines of a DO(debug-cmd-list)
display are not marked when the display is automatically
updated. This cancels the effect of a previous /MARK_CHANGE for
the specified displays; not applicable to other kinds of
displays.
/NOPOP
Same as /NOPUSH. Does not pop the specified screen displays to
the front of the other displays. This preserves the pasting
order of all the displays. The default is /POP.
/NOPROCESS
(Default.) Causes the specified display to always be associated
with the visible process, which may change during program
execution.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
/NOPUSH
Same as /NOPOP. Does not push or hide the specified screen
displays under any other displays. This preserves the pasting
order of all the displays.
/POP
(Default.) Pops the specified screen displays to the front of
all other displays that occupy the same region on the terminal
screen.
/PROCESS[=(process-spec)]
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.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
/PROCESS=(process-spec) causes the specified display to be
associated with the specified process. You must include the
parentheses. Use any of the following forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
/PROCESS without a process-spec causes the specified display to
be associated with the process that was the visible process when
the DISPLAY/PROCESS command executed. If you do not use
/PROCESS, the current process-specific behavior (if any) of the
specified display remains unchanged. See also /SUFFIX.
/PUSH
Same as /HIDE. Pushes the specified screen displays under any
other displays that occupy the same region on the terminal
screen. This makes visible any displays that were occluded by
the specified displays.
/REFRESH
Refreshes the terminal screen. Do not specify command
parameters with /REFRESH. In screen mode, you can press Ctrl/W.
/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
Specifies the maximum size of a display --- the number of lines
(n). If more than n lines are written to the display, the
oldest lines are lost as the new lines are added. If you omit
/SIZE:n, the maximum size of the display is as follows:
o For an existing display, the maximum size is unchanged.
o For a new a display, the default size is 64 lines.
For an output or DO display, /SIZE:n specifies that the display
should hold the n most recent lines of output. For a source or
instruction display, n gives the number of source lines or lines
of instructions that can be placed in the memory buffer at any
one time. However, you can scroll a source display over the
entire source code of the module whose code is displayed (source
lines are paged into the buffer as needed). Similarly, you can
scroll an instruction display over all of the instructions of
the routine whose instructions are displayed (instructions are
decoded from the image as needed).
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command). See also /[NO]PROCESS.
DO
Executes commands in the context of one or more processes. By
default, commands execute in the context of the visible process.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
Format:
DO [/qualifier] (debug-cmd-list)
The DO command lets you execute commands in the context of
specific processes or all processes. The DO command is the same
as to entering a SET PROCESS/VISIBLE command for each process
specified with the /PROCESS qualifier (or for all processes, if
you do not specify /PROCESS) and then entering the specified
commands. To change the visible process, use the SET PROCESS
command.
Additional information available:
Examples
1. The following example executes a SHOW CALLS command in the
context of all processes:
DBG_2> DO (SHOW CALLS)
For %PROCESS_NUMBER 1
module name routine name line rel PC abs PC
*MAIN_MODULE MAIN 31 0000001E 0000041E
For %PROCESS_NUMBER 2
module name routine name line rel PC abs PC
*SUB_MODULE SUB 4 0000000B 0000040B
2. The following example executes the two commands EVAL/ADDR X and
EXAM X in the context of processes 2 and 1:
DBG_3> DO/PROCESS=(%PROC 2,%PROC 1) (EVAL/ADDR X;EXAM X)
For %PROCESS_NUMBER 2
%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table
For %Process_number 1
512
TEST\X: 1
Parameters
debug-cmd-list
A single debugger command or a sequence of debugger commands
separated by semicolons (;). The commands are executed in the
context of the processes specified.
Qualifiers
Additional information available:
/PROCESS=(process-spec)
Specifies one or more processes in whose context the commands
are to execute. You must include the parentheses even if you
specify only one process.
If you do not use /PROCESS or if you use the asterisk wildcard
(*) for the process-spec, the commands execute in the context of
all processes.
Use any of the following forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
EDIT
In screen mode, begins editing the file that you were viewing in
your source window. If you use the LSE editor, the cursor is
positioned at the place your source window was centered.
Optionally, you can override the default file and start position
by specifying a location in the same way as with the TYPE
command --- for example, EDIT MODNAME\10.
EDIT invokes the editor specified in the SET EDITOR command.
The default is to spawn the following DCL command:
$ LSEDIT/START_POSITION=(n,1) filespec
In this command, n is a number corresponding to the central line
in your source window. For more information, see help on the
SET EDITOR command. (To use the default state of the EDIT
command, you must have the LSE editor on your system.)
Format:
EDIT [/[NO]EXIT] [[module-name\] line-number]
Additional information available:
Parameters
The normal usage is to not specify any parameters. In this
case, if you are using the LSE editor, the editing cursor is
positioned on the same text that is displayed in the debugger
source window.
DBG> EDIT
Optionally, you can specify a module name and line number,
indicating a different place that you want to come up in the
editor:
EDIT module-name\line-number
You can specify the line number by itself, in which case the
module is assumed to be the same as the one currently in your
source window.
EDIT line-number
Qualifiers
Additional information available:
/EXIT
Ends the debugging session and starts an editing session. In
this case, the debugger does a $EXIT call after leaving the
editor. The default is /NOEXIT.
/NOEXIT
(Default.) Specifies that you want to continue the debugging
session after you make your edits.
ENABLE
Enables ASTs in the user program. To disable ASTs during a
debugging session, use the DISABLE AST command. To re-enable
ASTs, use the ENABLE AST command. Temporarily disabling ASTs in
this way prevents interrupts from occuring while you are
debugging a particular piece of code.
Format:
ENABLE AST
Example:
DBG> SHOW AST
ASTs are disabled
DBG> ENABLE AST
%DEBUG-I-ENABLEAST, ASTs were disabled, are now enabled
DBG> SHOW AST
ASTs are enabled
EVALUATE
Evaluates an expression in the currently set language.
Format:
EVALUATE [/qualifier[...]] expression[,...]
The debugger interprets the parameter in an EVALUATE command as
a source-language expression, evaluates it in the semantics of
the source language, and displays its value as a literal in the
source-language.
If an expression contains symbols with different
compiler-generated types, the debugger uses the type-conversion
rules of the current language to evaluate the expression.
Additional information available:
Examples
DBG> SET LANGUAGE FORTRAN
DBG> EVALUATE 1+1*2
3
DBG> EVALUATE 1+1.1
2.10000
DBG> EVALUATE 3 .EQ. X(1)
True
DBG> SET LANGUAGE PASCAL
DBG> EVALUATE 3 = X[1]
True
Parameters
expression
Any legal expression in the source language. The expression may
comprise one or more operators, operands, or delimiters. See
help on Language_Support for tables specifying what operators
and datatypes are accepted for each language.
Qualifiers
Additional information available:
/ADDRESS/BINARY/CONDITION_VALUE/DECIMAL/HEXADECIMAL
/OCTAL
/ADDRESS
Interprets the expression as an address expression whose value
is a virtual memory address.
Example:
DBG> EVALUATE/ADDRESS X
512
DBG> EXAMINE 512
X: 3
DBG> EVALUATE X
3
/BINARY
Displays the result in binary radix.
Example:
DBG> EVALUATE/BINARY X
00000000 00000000 00000000 0000011
/CONDITION_VALUE
Interprets the expression as a return status and displays the
message associated with that return status.
Example:
DBG> EVALUATE/COND 12
"%SYSTEM-F-ACCVIO, access violation at address !XL, PC=!XL"
/DECIMAL
Displays the result in decimal radix.
Example:
DBG> EVALUATE/DECIMAL %HEX 10
16
/HEXADECIMAL
Displays the result in hexadecimal radix.
Example:
DBG> EVALUATE/HEX %DEC 10
0A
/OCTAL
Displays the result in octal radix.
Example:
DBG> EVALUATE/OCTAL %DEC 10
12
EXAMINE
Displays the current value of a program variable. More
generally, displays the value of the entity denoted by an
address expression.
In general, you can specify a location in the same way it is
specified in your source program (for example, EXAM X, EXAM
A[1], EXAM R.C, and so on).
Format:
EXAMINE [address-expression[:address-expression]
[,address-expression[:address-expression]...]]
The value of the object is displayed according to its
compiler-generated type.
Examples:
DBG> EXAMINE X ! X is floating point
PROG\X: 1.12340
DBG> EXAMINE A^.B[1] ! Language is Pascal
PROG\X^.B[1]: 3
Additional information available:
Aggregate ExamineComposite ExamineParametersQualifiers
Aggregate Examine
Aggregate examine allows display of entire arrays or records.
Format:
EXAMINE aggregate-name
A related feature is the ability to examine slices of arrays:
EXAMINE array_name(lower_bound:upper_bound)
Example:
DBG> EXAMINE R ! R is a record
PROG\R
A: 12
B: 1.3
Composite Examine
When using the EXAMINE command, you can specify various forms of
composite address expressions --- expressions that include byte
offsets from a given address. For example, if X is an integer
variable, the following EXAMINE command displays the value
currently stored at the memory location 6 bytes beyond the
address of X:
DBG> EXAMINE X + 6
MOD3\X+6: 274903
You can examine composite address expressions of a complex form.
For example, the following command lines might be appropriate
for a vectorized program:
DBG> EXAMINE ARRX(1) + .%V9(0:VLR-1)
DBG> EXAMINE ARRZ(1) + .%V1(0:3) + .%V3(0:2)
Parameters
address-expression
The entity to be examined. In general, you use the same syntax
as in your source program --- for example, A(1) for a FORTRAN
array component.
Sometimes you may need to use a path name to avoid ambiguity ---
for example, EXAMINE A\B\C. See help on Path_Names.
You can also examine arbitrary addresses in your program that
are not necessarily associated with program data --- for
example, EXAM 1000. See help on Address_Expressions.
You can specify a range of addresses (for example, EXAMINE
A(1):A(100)) or a list of objects (for example, EXAMINE A,B,C).
Qualifiers
The qualifiers for the EXAMINE command specify a format, data
type, or radix other than the default. See help on the
individual qualifiers.
Example:
DBG> EXAMINE X ! default radix is decimal
PROG\X: 17
DBG> EXAMINE/HEX X ! hexadecimal
PROG\X: 11
Additional information available:
/ASCIC/ASCID/ASCII/ASCIW/ASCIZ/BINARY/BYTE
/CONDITION_VALUE/D_FLOAT/DATE_TIME/DECIMAL/DEFAULT
/FLOAT/FMASK/G_FLOAT/H_FLOAT/HEXADECIMAL/INSTRUCTION
/LINE/LONGWORD/NOLINE/NOSYMBOL/OCTAL
/OCTAWORD/OPERANDS/PACKED:n/PSL/PSW
/QUADWORD/SOURCE/SYMBOL/TASK/TMASK/TYPE
/WORD
/ASCIC
Interprets the memory location as an ASCIC string. This is a
string with a count byte at the beginning indicating its length.
/AC is also accepted.
Example:
DBG> EXAMINE/HEX X
X: 33323103
DBG> EXAMINE/AC X
X: "123"
/ASCID
Interprets the memory location as a VAX string descriptor and
displays the string.
/AD is also accepted.
Example:
DBG> EXAMINE/HEX/QUAD X
X: 7FFF0000 010E0003
DBG> EXAMINE/ASCII:3 7FFF0000
7FFF0000: "123"
DBG> EXAMINE/AD X
X: "123"
/ASCII[:n]
Interprets the memory location as an ASCII string of length n.
If you omit n, the length used is the length of the object as
given in the symbol table.
Example:
DBG> EXAMINE/ASCII:3 X
X: "123"
DBG> EXA/ASCII:4 X
X: "1234"
/ASCIW
Interprets the contents of the memory location as a counted
ASCII string with a word count.
/AW is also accepted.
Example:
DBG> EXAMINE/HEX X
X: 31310002
DBG> EXAMINE/AW X
X: "11"
/ASCIZ
Interprets the contents of the memory location as a
zero-terminated string.
/AZ is also accepted.
Example:
DBG> EXAMINE/HEX X
X: 00313131
DBG> EXAMINE/AZ X
X: "111"
/BINARY
Displays the output as an integer in binary radix.
Example:
DBG> EXAMINE X
X: 3
DBG> EXAMINE/BINARY X
X: 00000000 00000000 00000000 00000011
/BYTE
Displays the examined entity or entities in the type byte
integer (length 1 byte).
Example:
DBG> EXAMINE/LONG/HEX X
X: 12345678
DBG> EXAMINE/BYTE/HEX X
X: 78
/CONDITION_VALUE
Interprets the contents of the memory location (usually %R0 in
this case) as a return status, and displays the message
associated with that return status.
Example:
DBG> EXAMINE R0
%R0: 12
DBG> EXAMINE/COND R0
R0: "%SYSTEM-F-ACCVIO, access violation at PC = !XL,
virtual address = !XL
/D_FLOAT
Displays the examined entity or entities in the D_floating type
(length 8 bytes).
Example:
DBG> EXAMINE/D_FLOAT X
X: 3.13332884848421D12
/DATE_TIME
Interpets the memory location as a quadword integer containing
the internal VMS representation of date-time. This value is
converted to printable format and displayed.
Example:
DBG> EXAMINE/DATE_TIME X
X: "12-OCT-1984 12:00:00"
/DECIMAL
Displays the output as an integer in decimal radix.
Example:
DBG> EXAMINE/HEX X
X: 0FFFFFFFF
DBG> EXAMINAL/DECIMAL X
X: -1
/DEFAULT
Displays the output in the default radix.
/FLOAT
Displays the examined entity or entities in the F_floating type
(length 4 bytes).
/F_FLOAT is also accepted.
Example:
DBG> EXAMINE/F_FLOAT X
X: 2.345671
/FMASK
See the description of the /TMASK qualifier.
/G_FLOAT
Displays the examined entity or entities in the G_floating type
(length 8 bytes).
Example:
DBG> EXAMINE/G_FLOAT X
X: 2.34747474722222
/H_FLOAT
Displays the examined entity or entities in the H_floating type
(length 16 bytes).
Example:
DBG> EXAMPLE/H_FLOAT X
X: 2.174389247892374892324879487923
/HEXADECIMAL
Displays the output as an integer in hexadecimal radix.
Example:
DBG> EXAMINE/DECIMAL X
X: -1
DBG> EXAMINE/HEX X
X: 0FFFFFFFF
/INSTRUCTION
Displays the examined entity or entities as a VAX
assembly-language instruction. See help on /OPERANDS.
Example:
DBG> EXAMINE/INSTR .PC
%LINE 100: "MOVL B^10(R4),R7"
/LINE
Enables symbolization to line numbers, so that code locations
are displayed as %LINE x instead of "routine + offset." Most
useful in the SET MODE LINE form (see the following example);
the /LINE qualifier is included on EXAMINE for completeness.
Example:
DBG> SET MODE LINE
DBG> STEP
stepped to %LINE 100
DBG> SET MODE NOLINE
DBG> STEP
stepped to ROUTINENAME + 0B7
/LONGWORD
Displays examined entity or entities in the type long integer
(length 4 bytes).
Example:
DBG> EXAMINE F
F: 1.000000
DBG> EXAMINE/LONG F
F: 1024
/NOLINE
Disables symbolization to line numbers, so that code locations
are displayed as "routine + offset" instead of %LINE x. Most
useful in the SET MODE NOLINE form (see the following example);
the /NOLINE qualifier is included on EXAMINE for completeness.
Example:
DBG> SET MODE LINE
DBG> STEP
stepped to %LINE 100
DBG> SET MODE NOLINE
DBG> STEP
stepped to ROUTINENAME + 0B7
/NOSYMBOL
Disables symbolization of addresses, so that locations entered
as absolute addresses are displayed as absolute addresses.
Example:
DBG> EXAMINE 512
X: 3
DBG> EXAMINE/NOSYMBOL 512
512: 3
/OCTAL
Displays the output as an integer in octal radix.
Example:
DBG> EXAMINE X
X: 8
DBG> EXAMINE/OCTAL X
X: 10
/OCTAWORD
Displays the examined entity or entities in the type octaword
integer (length 16 bytes).
Example:
DBG> EXAMINE/OCTAWORD/HEX X
X: 00000000 00000000 00000000 00000001
/OPERANDS[=keyword]
Displays operand information associated with an examined
instruction --- displays each operand's address and its
contents, using the operand's data type.
The keywords BRIEF and FULL vary the amount of information
displayed about any nonregister operands. The default is
/OPERANDS=BRIEF.
Use /OPERANDS only when examining the instruction at the current
PC value (for example, EXAMINE/OPERANDS .0\%PC). Examining the
operands of an instruction that is not at the current PC value
can give erroneous results, because the state of the machine
(the contents of the registers) is not set up for that
instruction.
In screen mode, operand information is directed at the current
output display.
When you examine the operands of a vector instruction, any
operand-element masking that might be associated with that
instruction is performed by default. The /TMASK and /FMASK
qualifiers let you specify some other mask. The current value
of the vector length register (VLR) limits the highest element
of a vector register that you can examine.
See also the SET MODE [NO]OPERANDS=keyword command which
specifies a default level for the amount of operand information
displayed when examining instructions.
Example:
DBG> EXAMINE/OPERANDS .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> EXAMINE/OPERANDS=FULL .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
/PACKED:n
Interprets the examined entity as a packed decimal number of
length n nibbles.
Example:
DBG> EXAMINE/PACKED:5 X
X: -23412
/PSL
Displays the location in PSL format (which is used when
displaying the processor status longword --- that is, EXAMINE
%PSL). This is intended for use in displaying copies of the PSL
which are saved in call frames on the stack.
Example:
DBG> EXAMINE/PSL .SP+40
7FFF0000:
CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C
0 0 0 0 USER USER 0 0 0 1 0 0 0 0 0
/PSW
Same as /PSL, except that only the low-order 16 bits are
displayed (the processor status word).
Example:
DBG> EXAMINE/PSW .SP+40
7FFF0000:
DV FU IV T N Z V C
0 0 1 0 0 0 0 0
/QUADWORD
Displays the examined entity or entities in the the type
quadword integer (length 8 bytes).
Example:
DBG> EXAMINE/QUAD/HEX X
X: 00000000 00000000
/SOURCE
Interprets the parameter as an address, and displays the source
line corresponding to the address. In screen mode,
EXAMINE/SOURCE repositions the source window around the
specified address.
Example:
DBG> EXAMINE .PC
%LINE 12: INCL R0
DBG> EXAMINE/SOURCE .PC
module M
12: X = X + 1
/SYMBOL
Attempts to symbolize absolute addresses.
Example:
DBG> EXAMINE/SYMBOL 512
PROG\X: 3
DBG> EXAMINE/NOSYMBOL 512
512: 3
/TASK
(Applies to tasking, or multithread, programs.) Interprets each
examined entity as a task (thread) object and displays the task
value (the name or task ID) of that task object.
When examining a task object, use /TASK only if the programming
language does not have built-in tasking services.
The address-expression parameter is interpreted as the address
of an Ada task object. Its contents are displayed as an Ada
task value.
Example:
The following command displays the task ID of a task object
named SORT_INPUT:
DBG> EXAMINE/TASK SORT_INPUT
MOD3\SORT_INPUT: %TASK 12
/TMASK
/TMASK[=(mask-address-expression)]
/FMASK[=(mask-address-expression)]
(Applies to vectorized programs.) Specifies a mask to display
certain elements of a vector register (V0 to V15), or of an
array in memory, while not displaying other elements.
For example, when you examine the operands of a vector
instruction (by using the /OPERANDS qualifier), these qualifiers
override any operand-element masking that might be associated
with that instruction.
The /TMASK qualifier applies the EXAMINE command only to the
elements of the register or array that correspond to the set
bits (bit value: 1) of the mask.
The /FMASK qualifier applies the EXAMINE command only to the
elements that correspond to the clear bits (bit value: 0) of
the mask. The current value of the vector length register (VLR)
limits the highest register element that you can examine but not
the highest array element.
By default, if you do not specify a mask address expression with
/TMASK or /FMASK, the vector mask register (VMR) is used. The
EXAMINE command then applies only to the elements of the vector
register or array that correspond to the set bits (in the case
of /TMASK) or clear bits (in the case of /FMASK) of VMR.
If you specify a mask address expression with /TMASK or /FMASK,
the value at that address is used as the mask, subject to the
following conventions:
o You must use parentheses around the address expression.
o The number of mask elements limits the number of register or
array elements that you can examine.
o If the mask address expression denotes a Boolean array, its
values are used as the mask in the same basic way that VMR is
used in the default case.
o If the mask address expression denotes a non-Boolean array,
the least significant bit value of each array element is used
as the mask for the corresponding element of the register or
target array.
o If the mask address expression denotes a Boolean scalar type,
its value is used as the mask for the first element of the
register or target array. No other elements are examined.
o If the mask address expression denotes any other type, its
least significant bit value is used as the mask for the first
element of the register or target array. No other elements
are examined.
o For a multi-element mask, the lowest specified element of the
mask is applied to the lowest specified element of the
register or target array.
/TYPE=(expression)
Provides a way of type casting. The specified expression should
be the name of a data object in your program, and the location
you are examining should be an untyped address. The debugger
then displays the address as if it were of the specified type.
Example:
In the following commands, R is the name of a record in your
program. It has components A, an integer, and B, a floating
point number. You have also allocated an object of type R at
address 2000.
DBG> EXAMINE 2000 ! The debugger has no type
! information for address 2000.
2000: 12
DBG> EXAMINE/TYPE=(R) 2000 ! Show the location as if
! it were a record R.
2000:
A: 12
B: 1.7
/WORD
Displays the examined entity or entities as a word integer
(length 2 bytes).
Example:
DBG> EXAMINE/HEX X
X: 12345678
DBG> EXAMINE/WORD/HEX X
X: 5678
EXIT
Ends the debugging session or terminates one or more processes
of a multiprocess program, letting any user-declared exit
handlers run.
Format:
EXIT [process-spec[,...]]
Using EXIT within a command procedure or DO clause and without
specifying a process exits the command procedure or DO clause at
that point.
EXIT is one of the four debugger commands that can cause your
program to execute (the others are CALL, GO, and STEP).
Additional information available:
Ending Debugging SessionExiting Command ProceduresTerminating Processes
ExamplesParameters
Ending Debugging Session
To end a debugging session, enter the EXIT command at the
debugger prompt without specifying any parameters.
EXIT causes orderly termination of the session:
1. The program's user-declared exit handlers (if any) execute
2. The debugger exit handler executes (closing log files,
restoring the screen and keypad states, and so on).
3. Control returns to the command interpreter.
You cannot then continue to debug your program by entering
the DCL commands DEBUG or CONTINUE. To restart the
debugger, you must run the program again.
Since EXIT runs any user-declared exit handlers, you can set
breakpoints in such exit handlers, and the breakpoints are
triggered upon entering EXIT. Thus, you can use EXIT to debug
your exit handlers.
To end a debugging session without running any user-declared
exit handlers, use the QUIT command instead of EXIT.
Exiting Command Procedures
When the debugger executes an EXIT command (without any
parameters) in a command procedure, control returns to the
command stream that invoked the command procedure. A command
stream can be the terminal, an outer (containing) command
procedure, or a DO clause in a command or screen display
definition. For example, if the command procedure was invoked
from within a DO clause, control returns to that DO clause,
where the debugger executes the next command (if any remain in
the command sequence).
When the debugger executes an EXIT command (without any
parameters) in a DO clause, it ignores any remaining commands in
that clause and displays its prompt.
Terminating Processes
If you are using the multiprocess debugging configuration to
debug a multiprocess program (if the DBG$PROCESS logical name is
defined as MULTIPROCESS), you can use the EXIT command to
terminate selected processes without ending the debugging
session. The same techniques and behavior apply, whether you
enter the EXIT command at the prompt or use it within a command
procedure or DO clause.
To terminate one or more processes, use the EXIT command,
specifying these processes as parameters. This causes orderly
termination of the images in these processes, executing any
user-declared exit handlers associated with these images.
Subsequently, the specified processes are no longer identified
in a SHOW PROCESS/ALL display. If any specified processes were
on hold, as the result of a SET PROCESS/HOLD command, the hold
condition is ignored.
When the specified processes begin to exit, any unspecified
process not on hold begins execution. Once execution is
started, the way in which it continues depends on whether SET
MODE NOINTERRUPT is in effect. By default (SET MODE INTERRUPT),
execution continues until it is suspended in any process. At
that point, execution is interrupted in any other processes that
were executing images, and the debugger prompts for input.
To terminate selected processes without running any
user-declared exit handlers or otherwise starting execution, use
the QUIT command instead of EXIT.
Examples
1. DBG> EXIT
$
Ends the debugging session and returns you to the DCL level.
2. JONES_1> EXIT %NEXT_PROCESS, %PROCESS_NAME JONES_3, %PROC 5
JONES_1>
Causes orderly termination of three processes of a multiprocess
program: the next process after the visible process on the
process list, process JONES_3, and process 5. Control returns
to the debugger after the specified processes have exited.
Parameters
process-spec
(Applies to a multiprocess debugging configuration when the
DBG$PROCESS logical name is defined as MULTIPROCESS.)
Use any of the following forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
You can also use the asterisk wildcard (*) to specify all
processes.
EXITLOOP
Exits from an enclosing WHILE, REPEAT, or FOR loop.
Format:
EXITLOOP [number]
If you specify a number, EXITLOOP exits from that many levels of
loops.
Example:
DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN (EXITLOOP))
Additional information available:
Parameters
number
(Optional.) An integer specifying how many levels of loops to
exit from.
EXPAND
Expands or contracts the window associated with a screen
display.
Format:
EXPAND /qualifier[...] [display-name[,...]]
The EXPAND command moves one or more display-window borders
according to the qualifier(s) specified (/UP, /DOWN, RIGHT,
/LEFT). For example, the following command moves the right
border of display SRC four columns to the right, and the bottom
border six lines up:
DBG> EXPAND/RIGHT:4/DOWN:-6 SRC
The EXPAND command does not affect the order of a display in the
pasteboard circular list. Depending on the relative order of
displays, the EXPAND command may cause the specified display to
hide or uncover another display or be hidden by another display,
partially or totally.
Except for the PROMPT display, any display can be shrunk to the
point where it disappears (at which point it is marked as
removed). It can then be expanded from that point. The PROMPT
display cannot be shrunk (or expanded) horizontally, but can be
shrunk vertically to a height of 2 lines. Contracting a display
to the point where it disappears causes it to lose any
attributes that were selected for it.
A window border can be expanded only up to the edge of the
screen. Thus, EXPAND/DOWN:99 SRC lowers the bottom border of
display SRC to the bottom edge of the screen.
The left and top window borders cannot be expanded beyond the
left and top edges of the display. The right border can be
expanded up to 255 columns from the left display edge. The
bottom border of a source or instruction display can be expanded
down only to the bottom edge of the display (last line of the
source module or last instruction of the routine). A register
display cannot be expanded beyond its full size.
In the case of an OUTPUT or DO display, the scrolling region
preserved in memory extends to 64 lines by default but may be
increased or decreased by using the DISPLAY/SIZE command.
Additional information available:
ExamplesKey DefinitionsParametersQualifiers
Examples
1. DBG> EXPAND/DOWN:99 FOO
Moves the bottom border of display FOO down to the bottom edge
of the screen.
2. DBG> EXPAND/UP/RIGHT:-6
Moves the top border of the current scrolling display up by 1
line, and the right border to the left by 6 columns.
Key Definitions
Several keypad keys have been bound to the EXPAND and MOVE
commands, to facilitate expanding, contracting, and moving
displays. For more information, see help on Keypad_Defintions.
Parameters
display-name
(Optional.) The screen display(s) to be expanded or shrunk. If
you do not specify a name, the current selected scrolling
display is used (see help on the SELECT/SCROLL command).
Qualifiers
Additional information available:
/DOWN[:n]
Moves the bottom border of the display down by n lines (if n is
positive) or up by n lines (if n is negative). If you do not
specify a number, the border moves down by 1 line. (For
restrictions, see help on the EXPAND command.)
/LEFT[:n]
Moves the left border of the display to the left by n lines (if
n is positive) or to the right by n lines (if n is negative).
If you do not specify a number, the border moves to the left by
1 line. (For restrictions, see help on the EXPAND command.)
/RIGHT[:n]
Moves the right border of the display to the right by n lines
(if n is positive) or to the left by n lines (if n is negative).
If you do not specify a number, the border moves to the right by
1 line. (For restrictions, see help on the EXPAND command.)
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
/UP[:n]
Moves the top border of the display up by n lines (if n is
positive) or down by n lines (if n is negative). If you do not
specify a number, the border moves up by 1 line. (For
restrictions, see help on the EXPAND command.)
EXTRACT
Saves screen displays into a file, or creates a file with all of
the debugger commands necessary to re-create the current screen
state at a later time.
Format:
EXTRACT [/qualifier[...]] [display-name[,...]] file-spec]
Additional information available:
Examples
1. DBG> EXTRACT SRC
Writes all lines in the SRC display to the DEBUG.TXT file in
your current directory.
2. DBG> EXTRACT SRC,OUT MYFILE.TXT
Writes all lines in displays SRC and OUT to the MYFILE.TXT file
in your current directory.
3. DBG> EXTRACT/ALL [MYDIR]MYFILE
Writes all lines in all the displays to the MYFILE.TXT file in
the [MYDIR] directory..
4. DBG> EXTRACT/APPEND SRC MYFILE
Appends all lines in display SRC to the end of the MYFILE.TXT
file in your current directory.
5. DBG> EXTRACT/SCREEN_LAYOUT
Writes the debugger commands needed to re-construct the screen
into file DBGSCREEN.COM in the current directory.
Parameters
display-name
(Optional.) The screen display(s) to be extracted. You can use
wildcards (such as *). You must specify either one or more
display names or the /ALL qualifier, but not both.
file-spec
(Optional.) The file to write the information to. The default
is DEBUG.TXT or if you use the /SCREEN_LAYOUT qualifier,
DBGSCREEN.COM. You can specify a logical name. To change the
default command file specification for /SCREEN_LAYOUT, use the
SET ATSIGN command.
Qualifiers
Additional information available:
/ALL/APPEND/SCREEN_LAYOUT/SUFFIX
/ALL
Extracts all displays. Do not specify a display name and do not
use /ALL with /SCREEN_LAYOUT.
/APPEND
Appends the information at the end of the file, rather than
creating a new file. The default is to create a new file. Do
not use /APPEND with /SCREEN_LAYOUT.
/SCREEN_LAYOUT
Writes a file which contains the debugger commands that describe
the current state of the screen. This information includes the
screen height and width, and the position, kind, and SELECT
attributes of every display which exists at the current time.
This file can then be executed with the @ (at sign) command to
re-construct the screen at a later time. Do not use
/SCREEN_LAYOUT with /ALL or /APPEND.
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
FOR
Provides a way of repeating a sequence of debugger commands.
Format:
FOR name = expr1 TO expr2 [BY expr3] DO (debug-cmd-list)
Example:
DBG> FOR I = 1 TO 3 DO (STEP)
stepped to ...
stepped to ...
stepped to ...
Additional information available:
Parameters
name
A name initially bound to the value of expr1, as if you had done
the DEFINE /VALUE name = expr1 command.
expr1
A language expression of integer or enumeration type.
expr2
A language expression of integer or enumeration type.
expr3
A language expression of integer or enumeration type; can be
negative but not be 0 (zero).
debug-cmd-list
A sequence of debugger commands separated by semicolons (;) and
enclosed in parentheses.
GO
Starts program execution or resumes execution from the point at
which it is currently suspended. GO is one of the four debugger
commands that can cause your program to execute (the others are
CALL, EXIT, and STEP).
Format:
GO [address-expression]
Note that specifying an address expression with the GO command
can produce unexpected results because it alters the normal
control flow of your program. For example, during a debugging
session you can restart execution at the beginning of the
program by entering GO %LINE 1. However, because the program
has executed, the contents of some variables may now be
initialized differently from when you first invoked the
debugger.
Additional information available:
ExamplesMultiprocess ProgramsParameters
Examples
1. DBG> GO
...
%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion
Starts program execution, which then completes successfully.
2. DBG> SET BREAK RESTORE
DBG> GO
...
break at routine INVENTORY\RESTORE
137: procedure RESTORE;
DBG> GO
...
The SET BREAK command sets a breakpoint on routine RESTORE. The
first GO command starts program execution, which is then
suspended at the breakpoint on routine RESTORE. The second GO
command resumes execution from the breakpoint.
3. DBG> GO %LINE 42
Resumes program execution at line 42 of the module where
execution is currently suspended.
Multiprocess Programs
If you are using the multiprocess debugging configuration to
debug a multiprocess program (if the DBG$PROCESS logical name is
defined as MULTIPROCESS), note the following additional points:
o The GO command executes in the context of the visible
process, but images in any other unheld processes (processes
that have not been put on hold with a SET PROCESS/HOLD
command) are also allowed to execute.
o If you use the DO command to broadcast a GO command to one or
more processes, GO executes in the context of each specified
unheld process, but images in any other unheld processes are
also allowed to execute. In all cases, a hold condition in
the visible process is ignored.
o Once execution starts, the way in which it continues depends
on whether SET MODE NOINTERRUPT is in effect. By default
(SET MODE INTERRUPT), execution continues until it is
suspended in any process. At that point, execution is
interrupted in any other processes that were executing
images, and the debugger prompts for input.
Parameters
address-expression
(Optional.) The location where program execution will resume.
If you do not specify an address expression, execution resumes
at the point of suspension or, in the case of debugger start up,
at the image transfer address.
HELP
Invokes the HELP facility to display information about a
debugger command or other topic.
Format:
HELP [topic]
You can abbreviate any topic name, although ambiguous
abbreviations result in all matches being displayed.
In response to the Topic? prompt, you can:
o Type the name of the command or topic for which you need
help.
o Type a question mark (?) to redisplay the most recently
requested text.
o Exit from HELP by pressing the RETURN key one or more times
or by pressing Ctrl/Z.
Additional information available:
Parameters
topic
(Optional.) The command or feature on which you want help. In
general, you can get help on a command by specifying the command
after HELP. For example, to get help on the EXAMINE/SOURCE
command, enter
DBG> HELP EXAMINE/SOURCE
There is also help on general features (for example, HELP
Screen_Mode).
If you use an asterisk (*) in place of any topic or subtopic,
the HELP command displays all information available at the level
that the asterisk replaces. For example, to get help on all the
subtopics under the topic SET BREAK, enter
DBG> HELP SET BREAK *
If you use an ellipsis (...) immediately after any topic, HELP
displays all the information on the specified topic and all
subtopics of that topic. For example, to display information on
the SHOW topic as well as information on all the subtopics under
SHOW, enter
DBG> HELP SHOW ...
IF
Provides conditional execution of a debugger command. This is
primarily useful in debugger command procedures and in the DO
clause of breakpoints.
Format:
IF language-exp THEN (debug-cmd-list) [ELSE (debug-cmd-list)]
If the language expression in the IF clause is true, the
commands in the THEN clause execute. If the language expression
is false, and there is an ELSE clause, the commands in the ELSE
clause execute.
For example, the following commands are equivalent:
DBG> SET BREAK/SILENT X DO (IF Y .NE. 3 THEN (GO))
DBG> SET BREAK/SILENT X WHEN (Y .EQ. 3)
Additional information available:
Parameters
language-exp
Any expression in the currently set language which evaluates to
TRUE or FALSE. For example:
In FORTRAN: (X .EQ. 5)
-----------
In Pascal: (Y[3] > 2)
----------
For more informtion about the syntax of each language, see help
on Language_Support *.
debug-cmd-list
A sequence of debugger commands separated by semicolons (;) and
enclosed in parentheses.
MOVE
Moves a screen display vertically or horizontally or both. This
creates a new window of the same dimensions elsewhere on the
screen and maps the display to the new window, while maintaining
the relative position of the text within the window.
Format:
MOVE /qualifier[...] [display-name[,...]]
The MOVE command does not change the order of a display in the
pasteboard circular list. Depending on the relative order of
displays, MOVE may cause the display to hide or uncover another
display or be hidden by another display, partially or totally.
A display can be moved only up to the edge of the screen. Thus,
the MOVE/DOWN:99 SRC command moves the SRC display down so that
its bottom border is at the bottom edge of the screen.
Additional information available:
ExamplesKey DefinitionsParametersQualifiers
Examples
1. DBG> MOVE/UP:3/RIGHT:5 FOO
Moves display FOO up by 3 lines and to the right by 5 columns.
2. DBG> MOVE/LEFT
Moves the current scrolling display left by 1 column.
Key Definitions
Several keypad keys have been bound to the EXPAND and MOVE
commands, to facilitate expanding, contracting, and moving
displays.
For more information, see help on Keypad State_Keys.
Parameters
display-name
(Optional.) The screen display(s) to be moved. If you do not
specify a name, the currently selected scrolling display is
used. See help on the SELECT/SCROLL command.
Qualifiers
Additional information available:
/DOWN[:n]
Moves the display down by n lines (if n is positive) or up by n
lines (if n is negative). If you do not specify a number, the
border moves down by 1 line. (For restrictions, see help on the
MOVE command.)
/LEFT[:n]
Moves the display to the left by n lines (if n is positive) or
right by n lines (if n is negative). If you do not specify a
number, the border moves to the left by 1 line. (For
restrictions, see help on the MOVE command.)
/RIGHT[:n]
Moves the display to the right by n lines (if n is positive) or
left by n lines (if n is negative). If you do not specify a
number, the border moves to the right by 1 line. (For
restrictions, see help on the MOVE command.)
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
/UP[:n]
Moves the display up by n lines (if n is positive) or down by n
lines (if n is negative). If you do not specify a number, the
border moves up by 1 line. (For restrictions, see help on the
MOVE command.)
QUIT
Ends a debugging session, or terminates one or more processes of
a multiprocess program.
Using QUIT within a command procedure or DO clause and without
specifying a process exits the command procedure or DO clause at
that point.
Format:
QUIT [process-spec[,...]]
QUIT is like the EXIT command, except that QUIT does not cause
your program to execute and, therefore, does not execute any
user-declared exit handlers in your program.
Additional information available:
Ending Debugging SessionExiting Command ProceduresTerminating Processes
ExamplesParameters
Ending Debugging Session
To end a debugging session, enter the QUIT command at the
debugger prompt without specifying any parameters.
QUIT causes orderly termination of the debugging session:
1. The debugger exit handler executes (closing log files,
restoring the screen and keypad states, and so on).
2. Control returns to the command interpreter.
You cannot then continue to debug your program by entering
the DCL commands DEBUG or CONTINUE. To restart the
debugger, you must run the program again.
Exiting Command Procedures
When the debugger executes a QUIT command (without any
parameters) in a command procedure, control returns to the
command stream that invoked the command procedure. A command
stream can be the terminal, an outer (containing) command
procedure, or a DO clause in a command or screen display
definition. For example, if the command procedure was invoked
from within a DO clause, control returns to that DO clause,
where the debugger executes the next command (if any remain in
the command sequence).
When the debugger executes a QUIT command (without any
parameters) in a DO clause, it ignores any remaining commands in
that clause and displays its prompt.
Terminating Processes
If you are using the multiprocess debugging configuration to
debug a multiprocess program (if the DBG$PROCESS logical name is
defined as MULTIPROCESS), you can use the QUIT command to
terminate selected processes without ending the debugging
session. The same techniques and behavior apply, whether you
enter the QUIT command at the prompt or use it within a command
procedure or DO clause.
To terminate one or more processes, enter the QUIT command,
specifying these processes as parameters. This causes orderly
termination of the images in these processes without executing
any user-declared exit handlers associated with these images.
Subsequently, the specified processes are no longer identified
in a SHOW PROCESS/ALL display.
In contrast to the EXIT command, QUIT does not cause any process
to start execution.
Examples
1. DBG> QUIT
$
Ends the debugging session and returns you to DCL command level.
2. JONES_1> QUIT %NEXT_PROCESS, %PROCESS_NAME JONES_3, %PROC 5
JONES_1>
Causes orderly termination of three processes of a multiprocess
program: the next process after the visible process on the
process list, process JONES_3, and process 5. Control returns
to the debugger after the specified processes have exited.
Parameters
process-spec
(Applies to a multiprocess debugging configuration when the
DBG$PROCESS logical name is defined as MULTIPROCESS.)
Specifies a process. Use any of the following forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
You can also use the asterisk wildcard (*) to specify all
processes.
REPEAT
Provides a way of repeating a sequence of debugger commands.
Format:
REPEAT language-exp DO (debug-cmd-list)
Example:
DBG> REPEAT 3 DO (STEP)
stepped to %LINE 2
stepped to %LINE 3
stepped to %LINE 4
Additional information available:
Parameters
language-exp
Any expression in the currently set language which evaluates to
a positive integer.
debug-cmd-list
A sequence of debugger commands separated by semicolons (;) and
enclosed in parentheses.
SAVE
Saves the contents of an existing screen display in a new screen
display. This command thus permits a "snapshot" of a display to
be saved for later reference.
Format:
SAVE [/qualifier] old-display AS new-display [,old-disp AS new-disp...]
The new display is created with the same textual contents as the
existing display. It also inherits all other attributes of the
existing display except that it is removed from the screen and
it is never automatically updated. The saved display can later
be displayed on the screen with the DISPLAY command.
For example, the following commands save the source display,
step to another place, and then bring back the saved source
display:
DBG> SAVE SRC AS SAVESRC
DBG> STEP;STEP;STEP
DBG> DISPLAY SAVESRC
Additional information available:
Parameters
old-display
The screen display whose contents are to be saved.
new-display
The new screen display to be created with the contents of the
old display.
Qualifiers
Additional information available:
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
SCROLL
Scrolls a display's screen window horizontally or vertically
over the text of the display. This makes additional display
contents visible.
Format:
SCROLL /qualifier [display-name]
If you do not specify a display name, the current scrolling
display, as selected with a previous SELECT command, is
scrolled. Note the use of KP8, KP2, KP4 and KP6 for scrolling.
Also note that you can use KP3 to rotate the scrolling attribute
around the various displays.
Additional information available:
Examples
1. DBG> SCROLL/UP
Scrolls up the "--scroll--" display.
2. DBG> SCROLL/UP OUT
Scrolls up the OUT display.
3. DBG> SCROLL/UP:1 OUT
Scrolls up the OUT display by only 1 line.
Parameters
display-name
(Optional.) The screen display to be scrolled. If you do not
specify a name, the current scrolling display, as selected by
the SELECT command, is scrolled.
Qualifiers
Additional information available:
/BOTTOM/DOWN/LEFT/RIGHT/SUFFIX/UP/TOP
/BOTTOM
Scrolls down to the bottom of the display's text.
/DOWN[:n]
Scrolls down through the display text by n lines to reveal text
further down in the display. If you do not specify a number,
the display is scrolled by approximately 3/4 of its window
height.
/LEFT[:n]
Scrolls left over the display text by n columns to reveal text
beyond the left margin. You cannot scroll past column 1. If
you do not specify a number, the display is scrolled left by 8
columns.
/RIGHT[:n]
Scrolls right over the display text by n columns to reveal text
beyond the right margin. You cannot scroll past column 132. If
you do not specify a number, the display is scrolled right by 8
columns.
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
/UP[:n]
Scrolls up through the display text by n lines to reveal text
further up in the display. If you do not specify a number, the
display is scrolled by approximately 3/4 of its window height.
/TOP
Scrolls up to the top of the display's text.
SEARCH
Searches the source code for the specified string and to display
the source line or lines containing an occurrence of the string.
Format:
SEARCH [/qualifier[...]] [range] [string]
The range parameter designates a program region to be searched.
The string parameter specifies the source code characters for
which to search. If you do not specify a string, the debugger
uses the last specified search string --- that is, the string
parameter specified in the last SEARCH command.
Additional information available:
Examples
1. To see the first occurence of string XYZ in module M:
DBG> SEARCH M XYZ
module M
10: XYZ := 3
2. To see the next occurence of string XYZ in module M:
DBG> SEARCH
module M
13: XYZ := XYZ + 1
3. To see all occurences of string "XYZ" in module M:
DBG> SEARCH/ALL M XYZ
module M
10: XYZ := 3
13: XYZ := XYZ + 1
Parameters
range
(Optional.) Limits the debugger's search for occurrences of the
string to specified program regions. If you do not specify a
range, the debugger searches the same module as that from which
a source line was most recently displayed (as a result of a TYPE
or EXAMINE/SOURCE command), beginning at the first line after
the line most recently displayed and continuing to the end of
the module.
See help on the Range_Format subtopic.
string
(Optional.) The string to find in the source code. You can
enclose the string in in quotation marks (") apostrophes (').
If the string contains spaces and tabs, enclose the string in
quotation marks or apostrophes. If you do not specify a string,
the debugger uses the last specified search string --- that is,
the string parameter specified in the last SEARCH command.
Additional information available:
Range Format
Use any of the following:
Format Effects
----------------------------------------------------------------
module-name To search the specified module from
line 0 to the end of the module.
module-name\line-num To search the specified module from the
specified line number (line-num) to the
end of the module.
module-name\line-num:line-num
To search the specified module from the
line number given to the left of the
colon until the line number given to
the right of the colon.
line-num To search the module designated by the
current scope setting, from the speci-
fied line number (line-num) to the end
of the module.
line-num:line-num To search the module designated by the
current scope setting, from the line
number given to the left of the colon
until the line number given to the
right of the colon.
null (nothing To search the same module as that from
specified) which a source line was most recently
displayed (as a result of a TYPE or
EXAMINE/SOURCE command), beginning at
the first line after the line most
recently displayed and continuing to
the end of the module.
Qualifiers
Additional information available:
/ALL
Searches for all occurrences of the string in the specified
range and displays every line containing an occurrence of the
string.
/IDENTIFIER
Searches for an occurrence of the string in the specified range
and displays the string only if it is bounded on either side by
a character that cannot be part of an identifier in the current
language.
/NEXT
(Default.) Searches for the first occurrence of the string in
the specified range and displays only the line containing this
occurrence.
/STRING
(Default.) Searches for and display the string as specified and
does not interpret the context surrounding an occurrence of the
string (as in the case of /IDENTIFIER).
SELECT
Selects a screen display with a specified attribute.
Format:
SELECT [/qualifier[...]] [display-name]
For example, the SELECT/SCROLL OUT command selects the OUT
display with the scroll attribute (attributes are indicated on
the top border of the display). The scroll attribute means that
the KP2, KP4, KP6, and KP8 keypad keys scroll, expand, or move
that display.
Other attributes include:
ERROR Error messages are directed to that display.
INPUT Input lines are echoed in the display.
OUTPUT Debugger output is written to that display.
PROGRAM Your program's output goes to the display.
INSTRUCTION EXAMINE/INST centers the display.
SOURCE TYPE or EXAMINE/SOURCE centers the display.
You unselect an attribute from a display by omitting the display
name, for example, SELECT/INPUT to remove the input attribute
from whatever display it is on.
Additional information available:
Examples
1. DBG> SELECT/INPUT/ERROR OUT
Selects OUT as the input and error display as well as being the
output display. This causes debugger input, output, and error
messages to be intermixed in the scrollable display OUT.
2. DBG> SELECT/SOURCE/SCROLL SRC2
Selects SRC2 as the current source and scrolling display.
3. DBG> SELECT/SOURCE
Removes the source attribute from any display. Output from TYPE
commands then goes to the OUT display.
Parameters
display-name
(Optional.) The screen display to be selected. If you do not
specify a name, the current select setting is canceled.
Qualifiers
Additional information available:
/ERROR/INPUT/INSTRUCTION/OUTPUT/PROGRAM/SCROLL
/SOURCE/SUFFIX
/ERROR
Selects the specified screen display as the current error
display. This means that debugger error messages are directed
to that display. By default, debugger error messages go to the
PROMPT display, which is not scrollable.
If you use the SELECT/ERROR OUT command, the error messages go
to the scrollable display OUT. Using SELECT/ERROR with no
display name puts the error attribute back on the PROMPT
display, which is the default. Thus, SELECT/ERROR PROMPT and
SELECT/ERROR are equivalent.
/INPUT
Selects the specified screen display as the current input
display. This means that debugger input lines are echoed in
that display. Note that you are always prompted for input in
the PROMPT display; selecting another display with the input
attribute means that your input lines are also echoed in that
other display.
By default, no display is selected with the input attribute. If
you use SELECT/INPUT OUT, your input lines are echoed in the
scrollable OUT display --- that is, your input and debugger
output are intermixed in that display. You may prefer this so
that you can see what input line caused what line of debugger
output.
/INSTRUCTION
Selects the specified screen display as the current instruction
display. This means that output of an EXAMINE/INSTRUCTION
command goes to the specified display. In this case, the
specified display must be an instruction display.
/OUTPUT
Selects the specified screen display as the current output
display, thus directing all normal debugger output that display.
In this case, the specified display cannot be source display or
an instruction display.
SELECT/OUTPUT with no display name puts the output attribute on
the PROMPT display. Thus, SELECT/OUTPUT PROMPT and
SELECT/OUTPUT are equivalent.
/PROGRAM
By default, your program's I/O is directed to the PROMPT
display. This is done by setting the scrolling region to that
display just before the debugger returns control to your
program. Currently, the SELECT/PROGRAM command is very
restricted: you cannot give the PROGRAM attribute to any
display other than PROMPT.
SELECT/PROGRAM removes the program attribute from the PROMPT
display. Then the debugger takes no special action to redirect
your program's I/O (which may be desirable if your program does
no I/O or if you have explicitly redirected your program's I/O
to another terminal). SELECT/PROGRAM PROMPT puts the program
attribute back on the PROMPT display.
On VAXstations, the debugger comes up in a different window from
your program, so there is no need to direct program I/O to the
PROMPT display in this environment. Therefore the default for
VAXstations is for the program attribute to be un-selected.
/SCROLL
Selects the specified screen display as the current scrolling
display. This means that the SCROLL command by default scrolls
this display unless a different display is explicitly specified.
The EXPAND and MOVE commands also manipulate this display by
default. Note, although the PROMPT display may be selected as
the current scrolling display, the PROMPT display may not be
scrolled. It may however be moved and expanded. (For more
information, see help on the MOVE and EXPAND commands.)
/SOURCE
Select the specified screen display as the current source
display. This means that the output of all TYPE and EXAMINE
/SOURCE commands go to the specified display. The specified
display must be a source display in this case.
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
SET
The meaning of the command depends on the keyword specified.
Format:
SET keyword [/qualifier[...]] parameter[...]
For example, SET BREAK specifies breakpoints, SET MODULE loads
the symbol table for a module, and so on. See the help topic
for each keyword.
Additional information available:
ABORT_KEYATSIGNBREAKDEFINEEDITOREVENT_FACILITY
IMAGEKEYLANGUAGELOGMARGINSMAX_SOURCE_FILES
MODEMODULEOUTPUTPROCESSPROMPTRADIXSCOPE
SEARCHSOURCESTEPTASKTERMINALTRACETYPE
VECTOR_MODEWATCHWINDOW
Parameters
keyword
One of the following:
ABORT_KEY ATSIGN BREAK DEFINE
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 VECTOR_MODE
WATCH WINDOW
qualifier
Depends on the keyword you specify.
parameter
Depends on the keyword you specify.
ABORT_KEY
Assigns the abort function to a control key other than Ctrl/C.
Format:
SET ABORT_KEY = CTRL_character
By default, Ctrl/C aborts a debugger command and interrupts
program execution. This may be necessary if your program has a
Ctrl/C AST service routine enabled.
Many control keys have VMS predefined functions. The SET
ABORT_KEY command lets you override such definitions (see the
VMS DCL Concepts Manual). Some control keys not used by the VMS
operating system are Ctrl/G, Ctrl/K, Ctrl/N, and Ctrl/P.
Do not use Ctrl/Y from within a debugging session. Instead, use
either Ctrl/C or an equivalent control key specified with SET
ABORT_KEY.
To find out the control key that is currently set for the abort
function, use the SHOW ABORT_KEY command.
Additional information available:
Examples
The following examples shows the use of Ctrl/C for the abort
function and then the SET ABORT_KEY command to reassign the
abort function to Ctrl/P:
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>
Parameters
character
The key you press while holding down the CTRL key. You can
specify any alphabetic character.
ATSIGN
Specifies the default file specification for processing debugger
command procedures. This is useful if you want to change the
file type of your debugger command procedures from .COM to .DBG.
Also, if you have several debugger command procedures, you can
keep 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
BREAK
Sets 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 [/qualifier[...]] [address-expression[,...]]
[ WHEN (conditional-expression)]
[ DO (dbg-cmd-list)]
Additional information available:
DescriptionExamplesParametersQualifiers
Description
When a breakpoint is triggered, the debugger does the following:
1. Suspends program execution at the breakpoint location.
2. Checks the AFTER count --- if you specified /AFTER when you
set the breakpoint. If the specified number of counts has
not been reached, execution resumes and the debugger does
not do the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the breakpoint. If the value of the
expression is FALSE, execution resumes and the debugger does
not do the remaining steps.
4. Reports that execution has reached the breakpoint location
by issuing a "break..." message, unless you specified
/SILENT.
5. Displays the line of source code where execution is
suspended, unless you specified /NOSOURCE or /SILENT when
you set the breakpoint or unless SET STEP NOSOURCE is in
effect.
6. Executes the commands in a DO clause, if you specified one
when you set the breakpoint. If the DO clause contains a GO
command, execution continues and the debugger does not
perform the next step.
7. Displays the DBG> 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 lets you also 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 conversely.
Breakpoints can be user-defined or predefined. User-defined
breakpoints are set explicitly with the SET BREAK command.
Predefined breakpoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are set
automatically when you invoke the debugger. Use the SHOW BREAK
command to identify all breakpoints that are currently set
(including predefined breakpoints).
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.
Examples
1. DBG> SET BREAK SWAP\%LINE 12
Breaks on line 12 of module SWAP.
2. DBG> SET BREAK/AFTER:3 SUB2
Breaks on the third and subsequent times that SUB2 (a routine)
executes.
3. DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAM D; STEP; EXAM Y; GO)
Breaks at location LOOP1. At the breakpoint, the following
commands are issued, in the order given:
EXAMINE D
STEP
EXAMINE Y
GO
The /NOSOURCE qualifier suppresses the display of source code at
the breakpoint.
4. DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y)
Breaks on routine ROUT3 when X is greater than 4. At the
breakpoint, the EXAMINE Y command is issued.
5. DBG> SET BREAK/TEMPORARY 1440
DBG> SHOW BREAK
breakpoint at 1440 [temporary]
Sets a temporary breakpoint at location 1440. After that
breakpoint is triggered, it disappears.
6. DBG> SET BREAK/LINE
Breaks 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 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
Breaks whenever the ADDL3 instruction is about to execute.
9. DBG> SET BREAK/LINE/INTO/NOSHARE/NOSYSTEM
Breaks 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
Breaks whenever the RET instruction of routine ROUT4 is about to
execute.
11. DBG> SET BREAK/RETURN %LINE 14
Breaks whenever the RET instruction of the routine that includes
line 14 is about to execute. 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)
Breaks whenever an exception is signaled. At the breakpoint,
the SET MODULE/CALLS and SHOW CALLS commands are issued.
13. DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3
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
Breaks whenever a process of a multiprocess program is brought
under debugger control.
Parameters
address-expression
(Optional.) A program location where 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 wildcard (*). Do not specify an
address expression with:
/ACTIVATING /BRANCH /CALL
/EXCEPTION /INSTRUCTION[=(opcode-list)] /INTO
/[NO]JSB /LINE /OVER
/[NO]SHARE /[NO]SYSTEM /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 executes. 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.
conditional-expression
A conditional expression in the currently set language which is
to be evaluated when execution reaches the breakpoint.
o If the expression is TRUE, break action occurs, and the
debugger reports that a break has occurred.
o 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 do not execute, and program execution
continues.
debug-cmd-list
A single debugger command or a sequence of debugger commands
separated by semicolons (;). The commands are executed as part
of the DO clause when break action is taken.
Qualifiers
The /LINE qualifier sets a breakpoint on each line of source
code.
The following qualifiers set breakpoints on classes of
instructions. Note that using these qualifiers and /LINE traces
every instruction of your program as it executes and thus
significantly slows down execution:
/BRANCH /CALL /INSTRUCTION[=(opcode-list)]
/RETURN /VECTOR_INSTRUCTION
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 monitors changes at program locations
(typically changes in the values of variables).
Additional information available:
/ACTIVATING/AFTER:n/BRANCH/CALL/EVENT/EXCEPTION
/INSTRUCTION/INTO/JSB/LINE/MODIFY/NOJSB
/NOSHARE/NOSILENT/NOSOURCE/NOSYSTEM/OVER
/RETURN/SHARE/SILENT/SOURCE/SYSTEM/TEMPORARY
/TERMINATING/VECTOR_INSTRUCTION
/ACTIVATING
Breaks when a new process comes under debugger control. The
debugger prompt is displayed when the first process comes under
debugger control. This lets you enter debugger commands before
the program has started execution. Do not specify an address
expression with /ACTIVATING. See also /TERMINATING.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
/AFTER:n
Specifies that break action not be taken until the nth time the
breakpoint is encountered (n is a decimal integer). Thereafter,
the break action is done every time it is encountered so long as
conditions in the WHEN clause (if specified) are TRUE. The SET
BREAK/AFTER:1 command is the same as the SET BREAK command.
/BRANCH
Breaks on every branch instruction encountered during execution.
Do not specify an address expression with /BRANCH. See also
/INTO and /OVER.
/CALL
Breaks on every call instruction encountered during execution,
including the RET instruction. Do not specify an address
expression with /CALL. See also /INTO and /OVER.
/EVENT=event-name
Causes the debugger to break on the specified event (if that
event is defined and detected by the current event facility.) If
you specify an address expression with /EVENT, causes the
debugger to break whenever the specified event occurs for that
address expression. You cannot specify an address expression
with certain event names.
Event facilities are available for programs that call Ada or
SCAN routines or that use DECthreads services. To identify the
current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
For example, the following command sets two breakpoints, which
are associated with task RESERVE and task 3 (task ID = 3),
respectively. Each breakpoint is triggered whenever its
associated task makes a transition to the RUN state.
DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3
/EXCEPTION
Breaks 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 letting any
user-declared exception handler 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 specified routine executes.
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 used at another time.
/INSTRUCTION
/INSTRUCTION[=(opcode[,...])]
Breaks on every instruction whose opcode you specify or if you
do not specify an opcode, breaks on every instruction
encountered during program execution. Do not specify an address
expression with /INSTRUCTION. If you specify a vector
instruction, do not include an instruction qualifier (/U, /V,
/M, /0, or /1) with the instruction mnemonic. See also /INTO
and /OVER.
/INTO
(Default.) Applies only to breakpoints set when an address
expression is not explicitly specified -- that is, with
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Used with those qualifiers, /INTO breaks at the specified points
within called routines (as well as within the routine where
execution is currently suspended). /INTO is the opposite of
/OVER.
You can alter the break action using /[NO]JSB, /[NO]SHARE, and
/[NO]SYSTEM.
/JSB
Lets the debugger break within routines that are called by the
JSB or CALL instruction. Use with /INTO and one of the
following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
/JSB is the default for all languages except DIBOL. Do not
specify an address expression with /[NO]JSB.
/LINE
Breaks at the start of each new line. Do not specify an address
expression with /LINE. See also /INTO and /OVER.
/MODIFY
Breaks at every instruction that writes to and changes 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 SET WATCH and has
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 using SET TYPE WORD, which changes the default length to 2
bytes, or SET TYPE BYTE, which changes the default length to 1
byte. To restore the default length of 4 bytes, use SET TYPE
LONGWORD.
/NOJSB
Specifies that breakpoints not be set within routines called by
JSB instructions. Use with /INTO and one of the following
qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
/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
Specifies that breakpoints not be set within shareable images.
Do not specify an address expression with /[NO]SHARE. Use with
/INTO and one of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
/NOSILENT
(Default.) Displays the "break... " message at the breakpoint.
/NOSOURCE
Suppresses display of the source line for the current location
at the breakpoint. The default is /SOURCE. See help on the SET
STEP [NO]SOURCE command.
/NOSYSTEM
Specifies that breakpoints not be set within system routines (P1
space). Use with /INTO and one of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
/OVER
Applies only to breakpoints set when an address expression is
not explicitly specified -- that is, with
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Used with those qualifiers, /OVER breaks at the specified points
only within the routine where execution is currently suspended
(not within called routines). /OVER is the opposite of /INTO
(which is the default).
/RETURN
Breaks 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). /RETURN applies only to routines
called with a CALLS or CALLG instruction; it cannot be used with
JSB routines. Breaking on the RET instruction lets you inspect
the local environment (for example, get the values of local
variables) before the RET instruction deletes the routine's call
frame from the call stack.
For /RETURN, 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 you specify the same address expression.
/SHARE
(Default.) Lets the debugger break within shareable image
routines as well as other routines. Use with /INTO and one of
the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Do not specify an address expression with /[NO]SHARE.
/SILENT
Supresses the "break... " message and the displays of the
source line for the current location at the breakpoint. /SILENT
overrides /SOURCE. The default is /NOSILENT. See help on the
SET STEP [NO]SOURCE command.
/SOURCE
(Default.) Displays the source line for the current location at
the breakpoint. /SILENT overrides /SOURCE. See help on the SET
STEP [NO]SOURCE command.
/SYSTEM
(Default.) Lets the debugger break within system routines (P1
space) as well as other routines. Use with /INTO and one of the
following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
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
Breaks 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 executes
the $EXIT system service and all of its exit handlers have
executed.
Do not specify an address expression with /TERMINATING. See
also /ACTIVATING.
/VECTOR_INSTRUCTION
(Applies to vectorized programs.) Breaks on every vector
instruction encountered during program execution. Do not
specify an address expression with /VECTOR_INSTRUCTION. See
also /INTO and /OVER.
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:
Parameters
ADDRESS
Treats subsequent DEFINE commands as DEFINE/ADDRESS.
COMMAND
Treats subsequent DEFINE commands as DEFINE/COMMAND.
PROCESS_GROUP
Treats subsequent DEFINE commands as DEFINE/PROCESS_GROUP
VALUE
Treats subsequent DEFINE commands as DEFINE/VALUE.
ADDRESS
Treats subsequent DEFINE commands as DEFINE/ADDRESS.
COMMAND
Treats subsequent DEFINE commands as DEFINE/COMMAND.
PROCESS_GROUP
Treats subsequent DEFINE commands as DEFINE/PROCESS_GROUP.
VALUE
Treats subsequent DEFINE commands as DEFINE/VALUE.
EDITOR
Specifies the editor to be invoked by the EDIT command.
Format:
SET EDITOR [{ /CALLABLE_EDT | /CALLABLE_LSEDIT | /CALLABLE_TPU }]
[/[NO]START_POSITION] [command_line]
The /CALLABLE_EDT, /CALLABLE_LSEDIT, and /CALLABLE_TPU
qualifiers specified the callable versions of the editor chosen.
If you do not specify one of these qualifiers, you must specify
a command_line parameter, which is spawned to DCL when you enter
the EDIT command.
For /CALLABLE_LSEDIT and /CALLABLE_TPU, you can specify a
command_line parameter, which is passed to the callable editor
as the command line to use. The default is LSEDIT or TPU,
respectively. (The parameter is ignored for /CALLABLE_EDT
because it does not allow for a command line.)
The /START_POSITION qualifier for the SET EDITOR command appends
/START_POSITION to the command line for invoking the editor.
You can use /START_POSITION only with LSEDIT and TPU (EVE) (both
spawned and callable).
The default is spawned LSEDIT, with the /START_POSITION
qualifier --- effectively the same as:
DBG> SET EDITOR/START_POSITION LSEDIT
Additional information available:
Examples
1. DBG> SET EDITOR '@MAIL$EDIT ""'
Causes EDIT to spawn the command line @MAIL$EDIT "", which
invokes the same editor used in MAIL.
2. DBG> SET EDITOR/CALLABLE_EDT
Causes EDIT to invoke CALLABLE_EDT. No command line is allowed
with CALLABLE_EDT.
3. DBG> SET EDITOR/CALLABLE_TPU
Causes EDIT to invoke CALLABLE_TPU with the default command line
of TPU.
4. DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI
Causes EDIT to invoke CALLABLE_TPU with the command line
TPU/SECTION=MYSECINI.
5. DBG> SET EDITOR/CALLABLE_LSEDIT/START_POSITION
Causes EDIT to invoke CALLABLE_LSEDIT with the default command
line of LSEDIT. Also, appends the /START_POSITION qualifier to
the command line, so that the editing session starts on the
source line that the debugger is currently pointing to.
EVENT_FACILITY
Establishes the current event facility. Event facilities are
available for programs that call Ada or SCAN routines or that
use DECthreads services.
Format:
SET EVENT_FACILITY facility_name
Additional information available:
Parameters
facility-name
An event facility. Valid keywords are as follows:
Keyword Effect
----------------------------------------------------------------
ADA If the event facility is set to ADA, the (SET,
CANCEL) BREAK and (SET, CANCEL) TRACE commands
recognize Ada-specific events as well as generic,
low-level task events. (Ada events consist of task
and exception events.) You can set the event
facility to ADA only if the main program is written
in Ada or if the program calls an Ada routine.
THREADS If the event facility is set to THREADS, the (SET,
CANCEL) BREAK and (SET, CANCEL) TRACE commands
recognize DECthreads-specific as well as generic,
low-level task events. All DECthreads events are
task (thread) events. You can set the event
facility to THREADS only if the shareable image
CMA$RTL is currently part of the program's process
(if that image is listed in a SHOW IMAGE display).
SCAN If the event facility is set to SCAN, the (SET,
CANCEL) BREAK and (SET, CANCEL) TRACE commands
recognize SCAN (pattern-matching) events. You can
set the event facility to SCAN only if the main
program is written in SCAN or if the program calls
a SCAN routine.
Description
The current event facility (ADA, THREADS, or SCAN) defines the
eventpoints that you can set with the SET BREAK/EVENT and SET
TRACE/EVENT commands.
When invoked with a program that is linked with an event
facility, the debugger automatically sets the facility in a
manner appropriate for the type of program. For example, if the
main program is written in Ada or SCAN, the event facility is
set to ADA or SCAN, respectively.
The SET EVENT_FACILITY command lets you change the event
facility and thereby change your debugging context. This is
useful if you have a multilanguage program and want to debug a
routine that is associated with an event facility but that
facility is not currently set.
NOTE Currently you cannot use both Ada and DECthreads tasking
services in the same program. This implies that you can
change the event facility only from ADA to SCAN or from
DECthreads to SCAN, or conversely.
Use the SHOW EVENT_FACILITY command to identify the event names
associated with the current event facility. These are the
keywords that you can specify with the (SET, CANCEL) BREAK/EVENT
and (SET, CANCEL) TRACE/EVENT commands.
Related commands:
SHOW EVENT FACILITY
(SET,CANCEL) BREAK/EVENT SHOW BREAK
(SET,CANCEL) TRACE/EVENT SHOW TRACE
SHOW TASK SHOW IMAGE
Examples
DBG> SET EVENT_FACILITY THREADS
Establishes THREADS (DECthreads) as the current event facility.
IMAGE
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, to set a breakpoint in routine SUBR in module SUBR
in shareable image SHARE1, enter the following commands:
DBG> SET IMAGE SHARE1
DBG> SET MODULE SUBR
DBG> SET BREAK SUBR
The specified image should have been linked with the /DEBUG or
/TRACE qualifiers. If the image was linked with /NOTRACE, then
no symbol table is available for that image and you cannot use
SET IMAGE with it.
KEY
Changes the current key definition state. Note that keys are
defined by using the DEFINE/KEY command.
Format:
SET KEY [/qualifier[...]]
Qualifiers Defaults
--------------------------------------
/[NO]LOG /LOG
/[NO]STATE=state-name current state
For example, the following command command makes DEFINE/KEY
redefine the GOLD keys by default:
DBG> SET KEY/STATE=GOLD
Additional information available:
Qualifiers
Additional information available:
/LOG
(Default.) Displays an informational message indicating whether
the key state has been set.
/NOLOG
Suppresses the informational message associated with the
command. The default is /LOG.
/NOSTATE
(Default.) Does not change the current state.
/STATE
Sets the specified state.
Format:
SET KEY/STATE=state-name
LANGUAGE
Specifies the current language. This affects what expressions
are allowed in commands that accept language expressions
(EXAMINE, EVALUATE, DEPOSIT, and so on). It 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
Valid languages are the following:
Ada BASIC BLISS C COBOL
DIBOL FORTRAN MACRO Pascal PLI
RPG SCAN UNKNOWN
UNKNOWN gives a kind of generic language support and is intended
to be used by any language not in the above list. See help on
Language_Support for information on specific support.
LOG
Specifies the log file to which the debugger writes when the
output parameter is set to LOG. This specifies only the name of
the file; you must do a SET OUTPUT LOG command to actually
enable logging.
Format:
SET LOG file-spec
The default log file is DEBUG.LOG.
Example:
DBG> SET LOG MARCH24.DBG
DBG> SET OUTPUT LOG
Additional information available:
Parameters
file-spec
The log file's file specification. The default log file is
DEBUG.LOG.
MARGINS
Specifies the leftmost source-line character position at which
to begin display of a line of source code (the left margin) or
the rightmost source-line character position at which to end
display of a line of source code.
Format:
SET MARGINS [lm:]rm
SET MARGINS affects only the display of lines of source code ---
that is, the display resulting from commands such as TYPE and
EXAMINE/SOURCE. It does not affect the display resulting from
commands that do not display source code (such as EXAMINE,
EVALUATE, SHOW MODE, and so on).
Example:
DBG> SET MARGINS 10:70
Additional information available:
Parameters:
lm:
(Optional.) The left margin --- the source-line character
position at which to begin display of the line of source code.
The colon separates the left margin value from the right margin
value. The default left margin is 1.
rm
The right marggin --- the source-line character position at
which to end display of the line of source code.
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 is 5.
Format:
SET MAX_SOURCE_FILES number
The value does not limit the number of source files that the
debugger can open, but limits the number that may be kept open
at any one time. Thus, if the debugger reaches this limit, it
must close a file to open another one.
Specifying a very small number can make the debugger's use of
source files inefficient. Specifying a large number runs the
risk of exceeding your open file quota. It is usually best to
keep the default value of 5.
Additional information available:
Parameters
number
The maximum number of source files that the debugger may keep
open at any one time. The default is 5.
MODE
Specifies one or more modes.
Format:
SET MODE mode-keyword[,...]
The two most important modes are:
o Screen mode or noscreen mode, which affects whether you want to
view debugger output line-by-line or in a screen-oriented fashio
o Keypad or nokeypad mode, which affects whether the numeric keypad
can be used to enter debugger commands or to enter number
There are also several other modes that affect the debugger's
behavior; for more information, see help on the subtopics.
Additional information available:
DYNAMICG_FLOATINTERRUPTKEYPADLINENODYNAMIC
NOG_FLOATNOINTERRUPTNOKEYPADNOLINENOOPERANDS
NOSCREENNOSCROLLNOSEPARATENOSYMBOLICOPERANDS
SCREENSCROLLSEPARATESYMBOLIC
Parameters
mode-keyword
One of the following:
Keyword Effect
----------------------------------------------------------------
DYNAMIC (Default.) Enables dynamic module setting.
NODYNAMIC Disables dynamic module setting.
G_FLOAT Specifies that the debugger pick up D exponent
constant as G_float.
NOG_FLOAT (Default.) Specifies that the debugger pick
up D exponent constant as D_float.
INTERRUPT (Default.) Enables interrupt mode for
debugging multiprocess programs.
NOINTERRUPT Disables interrupt mode for debugging multi-
process programs.
KEYPAD (Default.) Enables keypad mode.
NOKEYPAD Disables keypad mode.
LINE (Default.) Displays code locations in terms of
line numbers (%LINE), if possible.
NOLINE Specifies that the debugger symbolize code
locations to "routine + offset" instead of
line number.
OPERANDS (Default.) Enables display of operands when
examining VAX instructions. The default is
OPERANDS=BRIEF.
NOOPERANDS Disables display of operands when examining
VAX instructions.
SCREEN Enables screen mode.
NOSCREEN (Default.) Disables screen mode.
SCROLL (Default.) Specifies that output be scrolled
through the output display as it is generated.
NOSCROLL Specifies that the output display be updated
only once per command, instead of scrolling
the output line-by-line as it is generated.
SEPARATE (Only on VAXstations.) Runs debugger I/O in
a separate VAXstation window.
NOSEPARATE (Default.) Runs debugger I/O in the window
where the debugger initially started. (Only
on VAXstations.)
SYMBOLIC (Default.) Specifies that the debugger display
the locations denoted by address-expressions
symbolically, if possible.
NOSYMBOLIC Disables symbolization of addresses.
DYNAMIC
(Default.) Enables dynamic module setting. Whenever you are at
the DBG> prompt, if your PC is in a module that is not set, 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. If performance is a problem, use the SET MODE
NODYNAMIC command.
Example:
DBG> SET MODE DYNAMIC
DBG> STEP/INTO
stepped to routine SUBR
%DEBUG-I-DYNMODSET, setting module SUBR
G_FLOAT
Interprets all double-precision constants in expressions 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.
The default is NOG_FLOAT.
INTERRUPT
(Default.) 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.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
KEYPAD
(Default.) Enables keypad mode. For more information, see help
on Keypad.
LINE
(Default.) Displays code locations in terms of line numbers
(%LINE), if possible.
Example:
DBG> SET MODE LINE; STEP
stepped to %LINE 20
DBG> SET MODE NOLINE; STEP
stepped to SUBR + 36
NODYNAMIC
Disables dynamic module setting. This may be useful if
performance is a problem. For more information, see help on SET
MODE DYNAMIC, which is the default.
NOG_FLOAT
(Default.) Interprets all double-precision constants in
expressions as D_Floating. This affects only 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.
NOINTERRUPT
Specifies that when program execution is suspended in any
process, the debugger does the following:
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, press Ctrl/C to
interrupt all processes and display the prompt.
The default is INTERRUPT. This applies only to a multiprocess
debugging configuration (when the DBG$PROCESS logical name is
defined as MULTIPROCESS). For more information, see help on
Multiprocess Specifying_Processes.
NOKEYPAD
Disables keypad mode. This may be necessary if want to use the
keypad to enter numbers instead of debugger commands. The
default is KEYPAD.
NOLINE
Symbolizes code locations to "routine + offset" instead of line
number. The default is LINE.
Example:
DBG> SET MODE LINE
DBG> STEP
stepped to %LINE 20
DBG> SET MODE NOLINE
DBG> STEP
stepped to SUBR + 36
NOOPERANDS
Specifies that the operands of VAX instructions are not to be
evaluated when you enter the EXAMINE/INSTRUCTION command. 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 NOOPERANDS
DBG> EXAMINE .0\%PC
X\X$START+0C: MOVL B^04(R4),R7
NOSCREEN
(Default.) Disables screen mode.
NOSCROLL
Updates the output display 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. The default is SCROLL.
NOSEPARATE
(Applies only to VAXstations. Default.) Directs debugger input
and output to the window in which the debugger was invoked.
NOSYMBOLIC
Disables symbolization of adresses. 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. The
default is SYMBOLIC.
Example:
DBG> EVALUTE/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 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 (default) or OPERANDS=FULL.
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. The default is NOSCREEN. For more
information, see help on Screen_Mode.
SCROLL
(Default.) Specifies that in screen mode, output be scrolled
through the output display as it is generated.
SEPARATE
(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. The default is NOSEPARATE.
Example:
DBG> SET MODE SEPARATE
[... new window ...]
SYMBOLIC
(Default.) Enables symbolization of addresses.
Example:
DBG> EVALUATE/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 [,...]]
Example:
DBG> EXAMINE X ! X is declared in SUBR
%DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table
DBG> SET MODULE SUBR
DBG> EXAMINE X ! Now can examine X
SUBR\X: 5
Additional information available:
Parameters
module-name
(Optional.) The module to be set.
Qualifiers
Additional information available:
/ALL
Sets all modules in your program. However, your shareable image
modules are not set by SET MODULE/ALL --- you must explicitly
set each one.
/CALLS
Sets all modules that currently have routines on the call stack.
These are the modules listed by a SHOW CALLS command. Use
/CALLS to set modules that might not have been dynamically set
by the debugger.
/NORELATED
(Applies only to Ada.) Sets 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. The
default is /RELATED.
/RELATED
(Applies only to Ada. 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 to send output to the terminal or to a log
file.
Format:
SET OUTPUT option[,...]
Example:
The following commands enable logging and turn off terminal
output:
DBG> SET OUTPUT LOG
DBG> SET OUTPUT NOTERM
As a result, output is going to the log file, not to the
terminal. To restore the defaults, enter the following command:
DBG> SET OUT TERM,NOLOG
Additional information available:
LOGNOLOGNOSCREEN_LOGNOTERMINALNOVERIFY
SCREEN_LOGTERMINALVERIFY
Parameters
option
One of the following output parameters:
LOG NOLOG NOTERMINAL NOVERIFY
TERMINAL VERIFY SCREEN_LOG NOSCREEN_LOG
LOG
Records both debugger output and user input in a log file. You
can specify the log file by using the SET LOG command (the
default log file is DEBUG.LOG). The default is NOLOG.
NOLOG
(Default.) Specifies that debugger output and user input not be
recorded in a log file.
NOSCREEN_LOG
(Default.) Specifies that screen images should not be written
to the log file, even when logging is otherwise enabled.
NOTERMINAL
Specifies that debugger output, except for diagnostic messages,
not be displayed at the terminal. The default is TERMINAL.
NOVERIFY
(Default.) Excludes the debugger's echoing of commands in
command procedures and in DO command sequences.
SCREEN_LOG
Writes to the log file whenever screen mode is enables and
logging is enabled by the LOG option. This can cause log file
to get very large, and should be used with caution. The default
is NOSCREEN_LOG.
TERMINAL
(Default.) Displays debugger output at the terminal.
VERIFY
Includes the debugger's echoing of commands in command
procedures and in DO command sequences as debugger output. The
default is NOVERIFY.
PROCESS
Specifies the visible process, modifies characteristics of one
or more processes, or enables/disables dynamic process setting.
Format:
SET PROCESS [/qualifier[...]] [process-spec[,...]]
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
By default, commands execute 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 lets you execute commands in the context of
specific processes or of all processes. The DO command is the
same as 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. If 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
Puts 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
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
Makes process TEST_Y the visible process. The SHOW PROCESS
command 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>
Puts all processes on hold. The DO command broadcasts the
EXAMINE X and STEP commands to all processes (processes 1 and 2
in this case). STEP executes 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
(Optional.) Specifies a process. Use any of the following
forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
You can also use the asterisk wildcard (*) 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 parameter with /ALL and do not use with
/[NO]DYNAMIC, /[NO]HOLD, or /VISIBLE.
/DYNAMIC
(Default.) Enables dynamic process setting. Thus, 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
use /DYNAMIC with /ALL, /[NO]HOLD, or /VISIBLE.
/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 you do not specify a process, /HOLD puts the visible process
on hold. See help on the GO, STEP, CALL, EXIT, and QUIT
commands for the effects of these commands on held processes.
Do not use /HOLD with /[NO]DYNAMIC.
/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.
The default is /DYNAMIC.
Do not specify a process parameter with /NODYNAMIC and do not
use with /ALL, /[NO]HOLD, or /VISIBLE.
/NOHOLD
Unholds a specified process. This lets images in that process
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 you do not specify a prcoess, /NOHOLD unholds the visible
process. See help on the GO, STEP, CALL, EXIT, and QUIT
commands for the effects of these commands on unheld processes.
Do not use /NOHOLD with /[NO]DYNAMIC.
/VISIBLE
(Default.) 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. Do not
use /VISIBLE with /ALL or /[NO]DYNAMIC.
PROMPT
Changes the debugger prompt string from DBG> to a string of your
choice.
Format:
SET PROMPT [/qualifier] [prompt-string]
The /[NO]SUFFIX and /[NO]POP qualifiers control convenience
features for debugging multiprocess programs or using the
debugger at a VAXstation, respectively.
Additional information available:
Examples
1. DBG> SET PROMPT "$ "
$ SET PROMPT "d b g : "
d b g : SET PROMPT "DBG> "
DBG>
These commands change the debugger prompt from DBG> to $ to
d b g : and 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>
These commands show the effect of the /[NO]SUFFIX qualifier and
the prompt string for multiprocess programs.
Parameters
prompt-string
(Optional.) The string for 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.
For a default, non-multiprocess configuration, the default
prompt string is DBG>.
For a multiprocess configuration, the prompt string is consists
of a process-independent prefix and a process-specific suffix
(specified by the /[NO]SUFFIX qualifier). The suffix changes
automatically as the visible process changes.
Qualifiers
Additional information available:
/NOPOP
(Applies only to VAXstations. Default.) Prevents the debugger
window from popping over other windows and from attaching to the
keyboard automatically when the debugger prompts for input.
/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.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
/POP
(Applies only to VAXstations.) Pops the debugger window over
other windows and attaches it to the keyboard when the debugger
prompts for input. The default is /NOPOP.
/SUFFIX
/SUFFIX[=process-identifier-type]
Used directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
When you invoke the debugger with the RUN command to debug a
multiprocess program, the default prompt string is DBG_1>. 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 keywords with the
/SUFFIX qualifier:
Keyword Effects
----------------------------------------------------------------
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).
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
(prefix) (suffix) Resulting prompt string
--------------------------------------------------------------
none none unchanged
none /NOSUFFIX DBG>
none /SUFFIX DBG_process-number>
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>
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_"
RADIX
Specifies the radix (decimal, hex, octal, binary) of numbers.
You can set the input and output radices separately.
Format:
SET RADIX [/qualifier[...]] radix
SET RADIX is the new syntax, in place of SET MODE.
Example:
DBG> SET RADIX DECIMAL
DBG> EVALUATE 5 + 5
10
DBG> SET RADIX HEX
DBG> EVALUATE 5 + 5
0A
Additional information available:
BINARYDECIMALDEFAULTHEXADECIMALOCTAL
Parameters
radix
One of the following keywords:
BINARY Sets the radix to binary.
DECIMAL Sets the radix to decimal.
DEFAULT Sets the radix back to the language default.
HEXADECIMAL Sets the radix to hexadecimal.
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
Sets only the input radix.
Example:
DBG> SET RADIX/INPUT DECIMAL; SET RADIX/OUTPUT HEX
DBG> EVALUATE 31
1F
/OUTPUT
Sets only the output radix.
Example:
DBG> SET RADIX/INPUT DECIMAL; SET RADIX/OUTPUT HEX
DBG> EVALUATE 31
1F
/OVERRIDE
Sets the override radix. The override radix is like output
radix except that it also displays all data as integer --- that
is, the type is overriden.
SCOPE
Specifies how the debugger looks up symbols (variable names,
routine names, line numbers, and so on) when a path name prefix
is not specified.
Format:
SET SCOPE location[,...]
Additional information available:
DescriptionExamplesParametersQualifiers
Description
By default, the debugger looks up a symbol specified without a
path-name prefix according to the scope search list 0,1,2,...
,n, where n is the number of calls in the call stack. This
scope search list is based on the current PC value and changes
dynamically as the program executes. The default scope means
that a symbol lookup such as EXAMINE X first looks for X in the
routine currently executing (scope 0); if no X is visible there,
the debugger looks in the caller of that routine (scope 1), and
so on down the call stack; if X is not found in scope n, the
debugger searches the rest of the run-time symbol table (RST)
--- that is, all set modules and the global symbol table (GST),
if necessary.
In most cases, this default scope search list lets you specify
multiply defined symbols uniquely by resolving ambiguities in a
predictable, natural way that is consistent with language rules.
But if you cannot access a multiply-defined symbol, use either
of the following techniques:
o Specify the symbol with a path-name prefix. The path-name
prefix consists of any nesting program units (for example,
module\routine\block) that are necessary to specify the
symbol uniquely. For example:
DBG> EXAMINE MOD4\ROUT3\X
DBG> TYPE MOD4\27
o Specify a new default scope for symbol lookup by using the
SET SCOPE command. You can then specify the symbol without
using a path-name prefix. For example:
DBG> SET SCOPE MOD4\ROUT3
DBG> EXAMINE X
DBG> TYPE 27
The SET SCOPE command is useful in those cases where otherwise
you would need to use a path name repeatedly to specify symbols.
To restore the default scope search list, use the CANCEL SCOPE
command.
When the default scope search list is in effect, you can use SET
SCOPE/CURRENT to specify that symbol searches start at a numeric
scope other than scope 0, relative to the call stack (for
example, scope 2).
When you use SET SCOPE, the debugger searches only the program
locations you specify explicitly, unless you use the /CURRENT
qualifier. Also, the scope or scope search list specified with
a SET SCOPE command remains in effect until you restore the
default scope search list or enter another SET SCOPE command.
However, if you /CURRENT, the default scope search list is
restored whenever program execution resumes.
If a name you specify in a SET SCOPE command is the name of both
a module and a routine, the debugger sets the scope to the
routine. In such cases, use the SET SCOPE/MODULE command if you
want to set the scope to the module.
If you specify a module name in a SET SCOPE command, the
debugger sets that module if it is not already set. However, if
you want only to set a module, use the SET MODULE command rather
than the SET SCOPE command, to avoid the possibility of
disturbing the current scope search list.
Examples
1. DBG> EXAMINE Y
%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique
DBG> SHOW SYMBOL Y
data CHECK_IN\Y
data INVENTORY\COUNT\Y
DBG> SET SCOPE INVENTORY\COUNT
DBG> EXAMINE Y
INVENTORY\COUNT\Y: 347.15
In this example, the first EXAMINE Y command indicates that
symbol Y is multiply defined and cannot be resolved from the
current scope search list. The SHOW SYMBOL command displays the
different declarations of symbol Y. The SET SCOPE command tells
the debugger to look for symbols without path name prefixes in
routine COUNT of module INVENTORY. The subsequent EXAMINE
command can now interpret Y unambiguously.
2. DBG> CANCEL SCOPE
DBG> SET SCOPE/CURRENT 1
In this example, the CANCEL SCOPE command restores the default
scope search list (0,1,2,... ,n). The SET SCOPE/CURRENT
command then changes the scope search list to 1,2,...,n, so that
symbol searches start with scope 1 --- that is, with the caller
of the routine in which execution is currently suspended. The
default source and instruction displays (SRC and INST) are
updated and now show the source and instructions, respectively,
for the caller of the routine in which execution is suspended.
3. DBG> SET SCOPE 1
DBG> EXAMINE %R5
In this example, the SET SCOPE command tells the debugger to
look for symbols without path-name prefixes in scope 1 --- that
is, in the caller of the routine in which execution is
suspended. The EXAMINE command then displays the value of
register R5 in the caller routine. Note that the SET SCOPE
command without the /CURRENT qualifier does not update any
source or instruction display.
4. DBG> SET SCOPE 0, STACKS\R2, SCREEN
Tells the debugger to look for symbols without path-name
prefixes according to the following scope search list. First
the debugger looks in the PC scope (denoted by 0). If the
debugger cannot find a specified symbol in the PC scope, it then
looks in routine R2 of module STACKS. If necessary, it then
looks in module SCREEN. If the debugger still cannot find a
specified symbol, it looks no further.
5. DBG> SHOW SYMBOL X
data ALPHA\X ! global X
data ALPHA\BETA\X ! local X
data X (global) ! same as ALPHA\X
DBG> SHOW SCOPE
scope: 0 [ = ALPHA\BETA ]
DBG> SYMBOLIZE X
address ALPHA\BETA\%R0:
ALPHA\BETA\X
DBG> SET SCOPE \
DBG> SYMBOLIZE X
address 00000200:
ALPHA\X
address 00000200: (global)
X
In this example, the SHOW SYMBOL command indicates that there
are two declarations of the symbol X-a global ALPHA\X (shown
twice) and a local ALPHA\BETA\X. Within the current scope, the
local declaration of X (ALPHA\BETA\X) is visible. After the
scope is set to the global scope (SET SCOPE \), the global
declaration of X is made visible.
Parameters
location
The program region (scope) to be used for the interpretation of
symbols that you specify without a path-name prefix. A location
can be any of the following, unless you specify /CURRENT or
/MODULE (see help on the qualifiers):
path-name Specifies the scope denoted by the path-name prefix.
prefix A path-name prefix consists of the names of one or
more nesting program elements (module, routine, block,
and so on), with each name separated by a backslash
(\). If the prefix consists of more than one name,
list a nesting element to the left of the \ and a
a nested element to the right of the \. A common
format is module\routine\block\.
If you specify only a module name and that name is
the same as the name of a routine, use the /MODULE
qualifier; otherwise, the debugger assumes that you
are specifying the routine.
n A decimal integer, specifying the scope denoted by
the routine that is n levels down the call stack.
A scope specified by an integer changes dynamically
as the program executes. A 0 (zero) denotes the
routine currently executing, a 1 denotes the
caller of that routine, and so on down the call
stack. The default scope is 0,1,2,...,n, where n
is the number of calls on the call stack.
\ The backlash, specifying the global scope --- that
is, the set of all program locations in which a
global symbol is known. The definition of a global
symbol; the way it is declared depends on the
current language.
When you specify more than one location parameter, you set up a
scope search list. If the debugger cannot interpret the symbol
using the first parameter, it uses the next parameter, and
continues using parameters in order of their specification until
it successfully interprets the symbol or until it exhausts the
parameters specified.
Qualifiers
Additional information available:
/CURRENT
Specifies a scope search list that is like the default search
list (0,1,2, ... ,n) but starts at the numeric scope specified
as the command parameter. Scope 0 is the PC scope, and n is the
number of calls in the call stack. When using SET SCOPE
/CURRENT, note the following conventions and behavior:
o The default scope search list must be in effect when the
command is issued.
o The command parameter specified must be one (and only one)
decimal integer from 0 to n.
o In screen mode, the command updates the default source and
instruction displays (SRC and INST) to show the routine on
the call stack in which symbol searches are to start.
o The default scope search list is restored when program
execution resumes.
/MODULE
Indicates that the name specified as the command parameter is a
module name and not a routine name. You need to use /MODULE
only if you specify a module name as the command parameter and
that module name is the same as the name of a routine.
SEARCH
Specifies the search parameters for subsequent SEARCH commands
that do not have qualifiers.
Format:
SET SEARCH option[,...]
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.
Additional information available:
Parameters
option
The current SEARCH parameters. Valid keywords are as follows:
Keyword Effect on SEARCH
----------------------------------------------------------------
ALL Search for all occurrences of the string in the
specified range and display every line containing
an occurrence of the string.
NEXT (Default.) Search for the first occurrence of the
string in the specified range and display the line
containing this occurrence.
IDENTIFIER Search for an occurrence in the specified range
but display the string only if it is bounded on
either side by a character that cannot be part of
an identifier in the current language.
STRING (Default.) Search for and display the string as
specified without interpreting the context
surrounding an occurrence (as with IDENTIFIER).
ALL
Enables searching for all occurrences of the string in the
specified range and display every line containing an occurrence
of the string.
IDENTIFIER
Enables searching for an occurrence of the string in the
specified range but displaying the string only if it is bounded
on either side by a character that cannot be part of an
identifier in the current language.
NEXT
(Default.) Enables searching for the first occurrence of the
string in the specified range and displaying the line containing
this occurrence.
STRING
(Default.) Enables searching for and displaying the string as
specified without interpreting the context surrounding an
occurrence (as with IDENTIFIER).
Examples
The following example searches for all occurences of X in module
FOO:
DBG> SET SEARCH ALL,IDENT
DBG> SEARCH FOO X
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
specify a directory, or a search list of directories.
Format:
SET SOURCE [/MODULE=module-name] [/EDIT] dir-name[,...]
Example:
DBG> SET SOURCE [],SRC$
This command says to first look for the source file in the
current working directory and then 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.
Additional information available:
Parameters
dir-name
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). These fields may be
one or more or all of the following fields in the full file
specification:
node::device:[directory]file-name.file-type;version-number
Typically, you use SET SOURCE if the file has been copied to
another directory (in which case you would specify only the
[directory] field).
Qualifiers
Additional information available:
/MODULE=module-name
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
Specifies 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 (LINE, INTO, and so
on).
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 by pressing PF1-PF3, the SET STEP
NOSOURCE command is entered in addition to the SET MODE SCREEN
command. Therefore, any display of source code in output and DO
displays that would result from a STEP command or from a
breakpoint, tracepoint, or watchpoint being triggered is
suppressed, to eliminate redundancy with the source display.
Additional information available:
BRANCHCALLEXCEPTIONINSTRUCTIONINTO
JSBLINENOJSBNOSHARENOSILENTNOSOURCENOSYSTEM
OVERRETURNSHARESILENTSOURCESYSTEMVECTOR_INSTRUCTION
Parameters
step-default
The following parameters affect where the STEP command suspends
execution after a step:
BRANCH CALL EXCEPTION
INSTRUCTION[=(opcode-list)] LINE RETURN
The following parameters affect what output is seen when a STEP
command executes:
[NO]SILENT [NO]SOURCE
The following parameters affect what happens at a routine call:
INTO [NO]JSB OVER
[NO]SHARE [NO]SYSTEM
BRANCH
Treats subsequent STEP commands as STEP/BRANCH (step to the next
branch instruction).
CALL
Treats subsequent STEP commands as STEP/CALL (step to the next
call instruction).
EXCEPTION
Treats subsequent STEP commands as STEP/EXCEPTION (step to the
next exception condition).
INSTRUCTION
Treats subsequent STEP commands as STEP/INSTRUCTION (step to the
next instruction or the instruction specified).
Format:
SET STEP INSTRUCTION[=(opcode-list)]
If you can specify one or more instructions, the debugger then
steps to the next instruction in the specified list. If you
specify a vector instruction, do not include an instruction
qualifier (/U, /V, /M, /0, or /1) with the instruction mnemonic.
INTO
Treats subsequent STEP commands as STEP/INTO (step into called
routines) rather than STEP/OVER (step over called routines).
When INTO is in effect, you can qualify the types of routines to
step into by using the [NO]JSB, [NO]SHARE, and [NO]SYSTEM
parameters, or by using the /[NO]JSB, /[NO]SHARE, and
/[NO]SYSTEM qualifiers. (The qualifiers apply only to that STEP
command).
JSB
(Default except for DIBOL.) If INTO is in effect, treats
subsequent STEP commands as STEP/INTO/JSB (step into routines
called by a JSB instruction as well as those called by a CALL
instruction).
LINE
(Default.) Treats subsequent STEP commands as STEP/LINE (step
to the next line).
NOJSB
(Default for DIBOL.) If INTO is in effect, treats subsequent
STEP commands as STEP/INTO/NOJSB (step over routines called by a
JSB instruction, but step into routines called by a CALL
instruction).
NOSHARE
If INTO is in effect, treats subsequent STEP commands as
STEP/INTO/NOSHARE (step over called routines in shareable
images, but step into other routines).
NOSILENT
(Default.) Treats subsequent STEP commands as STEP/NOSILENT
(after a step, display the "stepped to..." message).
NOSOURCE
Treats subsequent STEP commands as STEP/NOSOURCE (after a step,
do not display the source line for the current location). Also,
treats subsequent SET BREAK, SET TRACE, and SET WATCH commands
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, treats subsequent STEP commands as
STEP/INTO/NOSYSTEM (step over called routines in system space,
but step into other routines).
OVER
(Default.) Treats subsequent STEP commands are treated as
STEP/OVER (step over all called routines) rather than STEP/INTO
(step into called routines).
RETURN
Treats subsequent STEP commands as STEP/RETURN (step to the RET
instruction of the routine currently executing --- that is, up
to the point just prior to transferring control back to the
calling routine).
SHARE
(Default.) If INTO is in effect, treats subsequent STEP
commands as STEP/INTO/SHARE (step into called routines in
shareable images as well as into other called routines).
SILENT
Treats subsequent STEP commands as STEP/SILENT (after a step, do
not display the "stepped to..." message or the source line for
the current location).
SOURCE
(Default.) Treats subsequent STEP commands are treated as
STEP/SOURCE (after a step, display the source line for the
current location). Also, treats subsequent SET BREAK, SET
TRACE, and SET WATCH commands 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).
SYSTEM
(Default.) If INTO is in effect, treats subsequent STEP
commands as STEP/INTO/SYSTEM (step into called routines in
system space (P1 space) as well as into other called routines).
VECTOR_INSTRUCTION
(Applies to vectorized programs.) Treats subsequent STEP
INSTRUCTION commands are treated as STEP/VECTOR_INSTRUCTION
(step to the next vector instruction).
Examples
1. DBG> SET STEP INSTRUCTION,NOSOURCE
Makes the STEP command execute the program to the next
instruction and not display lines of source code with each STEP.
2. DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE
Makes the STEP command execute the program to the next line and
step into called routines in user space only. The debugger
steps over routines in system space and in shareable images.
TASK
Changes characteristics of one or more tasks of a tasking
program (also called a multithread program).
Format:
SET TASK [/qualifier[...]] [task-spec [,...]]
Additional information available:
DescriptionParametersSelection QualifiersAttribute QualifiersExamples
Description
The SET TASK command enables you to establish the visible task
and the active task, control the execution of tasks, and cause
task state transitions, directly or indirectly.
To determine the current state of a task, use the SHOW TASK
command. The possible states are RUNNING, READY, SUSPENDED, and
TERMINTED.
Related commands:
SHOW TASK SET BREAK/EVENT
EXAMINE/TASK SET TRACE/EVENT
DEPOSIT/TASK
Parameters
task-spec
(Optional.) A task value. Use any of the following forms:
o A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
o A task ID (for example, %TASK 2), as indicated in a SHOW TASK
display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL,
or EXIT command executes.)
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_TASK The task previous to the visible task in
the debugger's task list.
%VISIBLE_TASK The task whose call stack and register set
are the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard. Instead, use the /ALL
qualifier. For more information about specifying tasks with
particular qualifiers, see help on the qualifiers.
If you do not specify a task with the /ABORT, /[NO]HOLD,
/PRIORITY, or /RESTORE qualifier, the visible task
(%VISIBLE_TASK) is selected.
Selection Qualifiers
The only task-selection qualifier is /ALL. It cannot be used in
combination with task-name parameters.
Additional information available:
/ALL
Applies the SET TASK command to all tasks. Do not specify a
task name parameter with /ALL and do not use /ALL with /ACTIVE,
/VISIBLE, or /TIME_SLICE.
Attribute Qualifiers
These qualifiers determine what task attributes are to be
changed. If you do not use a task attribute qualifier, /VISIBLE
is assumed by default.
Additional information available:
/ABORT/ACTIVE/ALL/HOLD/PRIORITY/RESTORE/TIME_SLICE
/VISIBLE
/ABORT
Marks the specified tasks for termination. Termination occurs
at the next allowable point after a specified task resumes
execution. If you do not specify a task, marks the visible task
for termination.
For Ada tasks, the effect is the same as executing an Ada abort
statement for the tasks specified and causes these tasks to be
marked as abnormal. Any dependent tasks are also marked for
termination.
For DECthreads threads, the effect is the same as doing an alert
operation for the threads specified. Only the specified threads
are marked for termination.
/ACTIVE
Makes the specified task the active task (which runs when a
STEP, GO, CALL, or EXIT command executes), causes a task switch
to the new active task, and makes that task the visible task.
The specified task must be in either the RUNNING or READY state.
When using /ACTIVE, you must specify one task.
/ALL
Applies the SET TASK command to all tasks. Do not specify a
task parameter with /ALL do not use /ALL with /ACTIVE, /VISIBLE,
or /TIME_SLICE qualifiers.
/HOLD
/NOHOLD
Controls whether a specified task is put on hold. The /HOLD
qualifier puts a specified task on hold. If you do not specify
a task, /HOLD puts the visible task on hold.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED to
the READY state.
A task already in the RUNNING state (the active task) can
continue to execute as long as it remains in the RUNNING state,
even though it is put on hold. If the task leaves the RUNNING
state for any reason (including expiration of a time slice, if
time slicing is enabled), it will not return to the RUNNING
state until released from the hold condition.
You can override the hold condition and force a task into the
RUNNING state with the SET TASK/ACTIVE command even if the task
is on hold.
The /NOHOLD qualifier releases a specified task from hold. If
you do not specify a task, /NOHOLD releases the visible task
from hold.
/PRIORITY=n
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example while
executing an Ada rendezvous or DECthreads synchronization event.
The /PRIORITY qualifier does not affect a task's scheduling
policy.
/RESTORE
Restores the priority of a specified task to the priority the
task had when it was created. Does not affect the scheduling
priority of the task.
/TIME_SLICE=t
Sets the time-slice duration to the value t, where t is a
decimal integer or real value representing seconds. The set
value overrides the time-slice value specified in the program,
if any.
To disable time slicing, use the SET TASK/TIME_SLICE=0.0
command.
/VISIBLE
Makes the specified task the visible task --- the task whose
call stack and register set are the current context for looking
up symbols, register values, routine calls, breakpoints, and so
on. Commands such as EXAMINE are directed at the visible task.
The /VISIBLE qualifier does not affect the active task. When
using /VISIBLE, you must specify one task.
Examples
1. DBG> SET TASK/ACTIVE %TASK 3
Makes task 3 (task ID = 3) the active task.
2. DBG> SET TASK %NEXT_TASK
Makes the next task in the debugger's task list the visible
task. (The /VISIBLE qualifier is the default for SET TASK.)
3. DBG> SET TASK/HOLD/ALL
DBG> SET TASK/ACTIVE %TASK 1
DBG> GO
...
DBG> SET TASK/ACTIVE %TASK 3
DBG> STEP
...
The SET TASK/HOLD/ALL command freezes the state of all tasks
except the active task. Then SET TASK/ACTIVE is used
selectively (along with the GO and STEP commands) to observe the
behavior of one or more specified tasks in isolation.
TERMINAL
Adjusts all predefined windows according to the new screen size.
(For example, H1 changes size to remain at the top half of the
new screen.)
The debugger gets the size of your terminal when you begin your
debugging session, and uses this size information (width and
height) when formatting output.
The SET TERMINAL command also adjusts screen displays. Displays
marked as DYNAMIC (see help on the SET DISPLAY/DYNAMIC command)
are adjusted like all the windows. Displays marked NODYNAMIC
are not affected.
Additional information available:
Examples
DBG> SET TERMINAL/WIDTH:132
Or on a VAXstation:
DBG> SET TERMINAL/PAGE=55/WIDTH=155
Qualifiers
Additional information available:
/PAGE:n
Sets the terminal page size --- the number of lines (n) on the
screen. This qualifier is most commonly used on a VAXstation.
You can specify any value between 18 and 100.
/WIDTH:n
Sets the terminal screen width --- the number of columns (n) on
the screen. Typically, you specify a width of 80 or 132 on
VT100 type terminals, but you can specify 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 [/qualifier[...]] [address-expression[,...]]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
Additional information available:
DescriptionExamplesParametersQualifiers
Description
When a tracepoint is triggered, the debugger does the following:
1. Suspends program execution at the tracepoint location.
2. Checks the AFTER count --- if you used /AFTER when you set
the tracepoint. If the specified number of counts has not
been reached, execution resumes and the debugger does not
perform the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the tracepoint. If the value of the
expression is FALSE, execution resumes and the debugger does
not do the remaining steps.
4. Reports that execution has reached the tracepoint location
by issuing a "trace..." message, unless you specified
/SILENT.
5. Displays the line of source code corresponding to the
tracepoint, unless you specified /NOSOURCE or /SILENT when
you set the breakpoint or unless SET STEP NOSOURCE is in
effect.
6. Executes the commands in a DO clause, if you specified one
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 lets you also 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 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 set
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.
Examples
1. DBG> SET TRACE SUB3
Traces the start of routine SUB3 when that routine executes.
2. DBG> SET TRACE/BRANCH/CALL
Traces every BRANCH instruction and every CALL instruction
encountered during program execution.
3. DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM
Traces 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)
Traces line 14 of module TEST5 when X is not equal to 2. At the
tracepoint, the DO clause issues the EXAMINE Y command. The
/NOSOURCE qualifier suppresses the display of source code at the
tracepoint.
5. DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0)
Traces 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)
Traces the start of routine SUB2 during execution. At the
tracepoint, the DO clause sets a watchpoint on variable K. The
SET TRACE/SILENT 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 (EXAM X)
Traces the RET instruction of routine ROUT4 (that is, just
before execution returns to the calling routine). At the
tracepoint, the DO clause issues the EXAMINE X command. This
example shows a convenient way of getting the value of a
nonstatic variable just before execution leaves that variable's
defining routine.
8. DBG> SET TRACE/EVENT=TERMINATED
Traces when any task makes a transition to the TERMINATED state.
Parameters
address-expression
(Optional.) A program location where 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 (*).
/ACTIVATING /BRANCH /CALL
/EXCEPTION /INSTRUCTION[=(opcode-list)] /INTO
/[NO]JSB /LINE /OVER
/[NO]SHARE /[NO]SYSTEM /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 executes. 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.
conditional-expression
A conditional expression in the currently set language which is
to be evaluated whenever execution reaches the tracepoint.
A conditional expression in the currently set language which is
to be evaluated when execution reaches the breakpoint.
o If the expression is TRUE, trace action occurs, and the
debugger reports that a break has occurred.
o 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 do not execute, and program execution
continues.
debug-cmd-list
A single debugger command or a sequence of debugger commands
separated by semicolons (;). The commands are executed as part
of the DO clause when execution reaches the tracepoint.
Qualifiers
The /LINE qualifier sets a tracepoint on each line of source
code.
The following qualifiers set tracepoints on classes of
instructions. Note that using these qualifiers and /LINE traces
every instruction of your program as it executes and thus
significantly slows down execution:
/BRANCH /CALL /INSTRUCTION[=(opcode-list)]
/RETURN /VECTOR_INSTRUCTION
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 monitors changes at program locations
(typically changes in the values of variables).
Additional information available:
/ACTIVATING/AFTER:n/BRANCH/CALL/EVENT/EXCEPTION
/INSTRUCTION/INTO/JSB/LINE/MODIFY/NOJSB
/NOSHARE/NOSILENT/NOSOURCE/NOSYSTEM/OVER
/RETURN/SHARE/SILENT/SOURCE/SYSTEM/TEMPORARY
/TERMINATING/VECTOR_INSTRUCTION
/ACTIVATING
(Default.) Traces when a new process comes under debugger
control. Do not specify an address expression with /ACTIVATING.
See also /TERMINATING.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
/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
so long as that conditions in the WHEN clause (if specified) are
TRUE. The SET TRACE/AFTER:1 command is the same as SET TRACE.
/BRANCH
Traces every branch instruction encountered during program
execution. Do not specify an address expression with /BRANCH.
See also /INTO and /OVER.
/CALL
Traces every call instruction encountered during program
execution, including the RET instruction. Do not specify an
address expression with /CALL. See also /INTO and /OVER.
/EVENT=event-name
Causes the debugger to trace the specified event (if that event
is defined and detected by the current event facility.) If you
specify an address expression with /EVENT, causes the debugger
to trace whenever the specified event occurs for that address
expression. You cannot specify an address expression with
certain event names.
Event facilities are available for programs that call Ada or
SCAN routines or that use DECthreads services. To identify the
current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
Example:
DBG> SET TRACE/EVENT=TERMINATED
Traces the point at which any task makes a transition to the
TERMINATED state.
/EXCEPTION
Traces 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
lettting any user-declared exception handler execute.
/INSTRUCTION
/INSTRUCTION[=(opcode[,...])]
Traces every instruction whose opcode you specify or if you do
not specify an opcode, traces every instruction encountered
during program execution. Do not specify an address expression
with /INSTRUCTION. If you specify a vector instruction, do not
include an instruction qualifier (/U, /V, /M, /0, or /1) with
the instruction mnemonic. See also /INTO and /OVER.
/INTO
(Default.) Applies only to tracepoints set when an address
expression is not explicitly specified -- that is, with
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Used with those qualifiers, traces the specified points within
called routines (as well as within the routine where execution
is currently suspended).
/INTO is the opposite of /OVER. You can alter the trace action
by using /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM.
/JSB
Lets the debugger set tracepoints within routines that are
called by the JSB or CALL instruction. Use with /INTO and one
of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
/JSB is the default for all languages except DIBOL. Do not
specify an address expression with /[NO]JSB.
/LINE
Traces the start of each new line. Do not specify an address
expression with /LINE. See also /INTO and /OVER.
/MODIFY
Reports 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 SET TRACE/MODIFY X command is the same as SET WATCH X
DO(GO). Also, SET TRACE/MODIFY has 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 using SET TYPE WORD, which changes the default length to 2
bytes, or SET TYPE BYTE, which changes the default length to 1
byte. To restore the default length of 4 bytes, use SET TYPE
LONGWORD.
/NOJSB
Specifies that tracepoints not be set within routines called by
JSB instructions. Use with /INTO and one of the following
qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
/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
Specifies that tracepoints not be set within shareable images.
Use with /INTO and one of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Do not specify an address expression with /[NO]SHARE.
/NOSILENT
(Default.) Displays that the "trace... " message at the
tracepoint.
/NOSOURCE
Supresses display of the source line for the current location at
the tracepoint. The default is /SOURCE. See help on the SET
STEP [NO]SOURCE command.
/NOSYSTEM
Specifies that tracepoints not be set within system routines (P1
space). Use with /INTO and one of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Do not specify an address expression with /SYSTEM.
/OVER
Applies only to tracepoints set when an address expression is
not explicitly specified -- that is, with
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Used with those qualifiers, traces the specified points only
within the routine where execution is currently suspended (not
within called routines). /OVER is the opposite of /INTO (which
is the default).
/RETURN
Traces the RET (return) instruction of the routine associated
with the specified address expression (which may be a routine
name, line number, and so on). /RETURN applies only to routines
called with a CALLS or CALLG instruction; it cannot be used with
JSB routines. Tracing the RET instruction lets you 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 /RETURN, 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 you specify the same address expression.
/SHARE
(Default.) Lets the debugger set tracepoints within shareable
image routines as well as other routines. Use with /INTO and
one of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
Do not specify an address expression with /[NO]SHARE.
/SILENT
Supresses the "trace... " message and the display of the source
line for the current location at the tracepoint. /SILENT
overrides /SOURCE. The default is /NOSILENT.
/SOURCE
(Default.) Displays the source line for the current location at
the tracepoint. See help on the SET STEP [NO]SOURCE command.
/SYSTEM
(Default.) Lets the debugger set tracepoints within system
routines (P1 space) as well as other routines. Use with /INTO
and one of the following qualifiers:
/BRANCH /CALL
/INSTRUCTION[=(opcode-list)] /LINE
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
(Default.) Trace 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. Do not specify an address expression with /TERMINATING.
See also /ACTIVATING.
/VECTOR_INSTRUCTION
(Applies to vectorized programs.) Traces every vector
instruction encountered during program execution. Do not
specify an address expression with /VECTOR_INSTRUCTION. See
also /INTO and /OVER.
TYPE
Specifies the default type to be associated with untyped program
locations and, if you use the /OVERRIDE qualifier, 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
One of the following debugger types:
Keyword Effect
-----------------------------------------------------
BYTE Byte integer (length 1 byte).
WORD Word integer (length 2 bytes).
LONGWORD Longword integer (length 4 bytes).
QUADWORD Quadword integer (length 8 bytes).
OCTAWORD Octaword integer (length 16 bytes).
PACKED:n Packed decimal (length n nibbles).
ASCII:n ASCII character (length n bytes). Each character
occupies one byte of memory. If you do not
specify a length, the debugger assumes a default
length of 4 bytes. The value n is interpreted
in decimal radix.
ASCIC Counted ASCII string (byte count).
ASCIW Counted ASCII string (word count).
ASCIZ Zero-terminated ASCII string.
DATE_TIME Date-time (internal VMS representation).
INSTRUCTION Instruction, whose length is variable, depending
on the number of instruction operands and the
kind of addressing modes used.
FLOAT F_floating (length 4 bytes). Values can range
from .29*10**-38 to 1.7*10**38 with approximately
7 decimal digits of precision.
D_FLOAT D_floating (length 8 bytes). Values can range
from .29*10**-38 to 1.7*10**38 with approximately
16 decimal digits of precision.
G_FLOAT G_floating (length 8 bytes). Values can range
from .56*10**-308 to .9*10**308 with approximately
15 decimal digits of precision.
H_FLOAT H_floating (length 16 bytes). Values can range
from .84*10**-4932 to .59*10**4932 with approxi-
mately 33 decimal digits of precision.
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> EXAMINE 1000 ! Location 1000 has no compiler-generated type.
1000: "...."
DBG> SHOW SYMBOL/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/OVERRIDE ASCII
DBG> EXAMINE X
FOO\X: "...." ! X now displayed as ASCII because of /OVERRIDE on SET TYPE.
VECTOR_MODE
(Applies to vectorized programs.) Enables or disables a
debugger vector mode option. Vector mode options control the
way in which the debugger interacts with the vector processor.
Format:
SET VECTOR_MODE vector-mode-option
The default is NOSYNCHRONIZED.
Additional information available:
Parameters
vector-mode-option
The vector mode option. Valid keywords are as follows:
Keyword Effect
-------------------------------------------------------------------
SYNCHRONIZED Forces automatic synchronization between the scalar
and vector processors whenever a vector instruc-
tion executes. Specifically, the debugger issues
a SYNC instruction after every vector instruction
and also issues an MSYNC instruction after any
vector instruction that accesses memory. This
forces completion of all activities associated
with the vector instruction being synchronized:
o Any exception that was caused by a vector
instruction is delivered before the next
scalar instruction executes. Note that
forcing the delivery of a pending exception
triggers an exception breakpoint or trace-
point (if one was set) or invokes an exception
handler (if one is available at that location
in the program).
o Any read or write operation between vector
registers and either the general registers
or memory is completed before the next scalar
instruction executes.
This does not issue an immediate SYNC or MSYNC
instruction. Use SYNCHRONIZE VECTOR_MODE to
force immediate synchronization.
NOSYNCHRONIZED (Default.) Forces synchronization of the scalar
and vector processors except for internal debugger
purposes. As a result, any synchronization is
controlled entirely by the program, and the pro-
gram runs as if it were not under debugger control.
Examples
1. DBG> SET VECTOR_MODE SYNCHRONIZED
Forces synchronization between the scalar and vector processors
after each vector instruction executes.
2. DBG> SHOW VECTOR_MODE
Vector mode is nonsynchronized
DBG> SET VECTOR_MODE SYNCHRONIZED [1]
DBG> SHOW VECTOR_MODE
Vector mode is synchronized
DBG> STEP [2]
stepped to .MAIN.\SUB\%LINE 99
99: VVDIVD V1,V0,V2
DBG> STEP [3]
%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002,
mask=00000004, PC=000002E1, PSL=03C00010
break on unhandled exception preceding .MAIN.\SUB\%LINE 100
100: CLRL R0
The comments that follow refer to the callouts in the preceding
example.
[1] The SET VECTOR_MODE SYNCHRONIZED command forces automatic
synchronization between the scalar and vector processors
whenever a vector instruction executes.
[2] This STEP command suspends program execution on line 99,
just before a VVDIVD instruction executes. In this
example, assume that the instruction will trigger a
floating-point divide-by-zero exception.
[3] This STEP command executes the VVDIVD instruction, which
triggers the exception. Note that the vector exception is
delivered immediately because the debugger is running in
synchronized vector mode.
WATCH
Sets a watchpoint at the location denoted by an address
expression.
Format:
SET WATCH [/qualifier[...]] address-expression[,...]
[ WHEN (conditional-expression)]
[ DO (debug-cmd-list)]
Additional information available:
DescriptionExamplesGlobal Section WatchpointsParametersStatic Nonstatic Watchpoints
Shareable Image WatchpointsQualifiers
Description
When an instruction modifies a watched location, the debugger
does the following:
1. Suspends program execution after that instruction has
completed execution.
2. Checks the AFTER count --- if you specified /AFTER when you
set the watchpoint. If the specified number of counts has
not been reached, execution continues and the debugger does
not perform the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one specified when you set the watchpoint. If the value of
the expression is FALSE, execution continues and the
debugger does not perform the remaining steps.
4. Reports that execution has reached the watchpoint location,
unless you specified /SILENT.
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 you use /NOSOURCE or /SILENT when you set
the watchpoint or unless SET STEP NOSOURCE is in effect.
8. Executes the commands in a DO clause, if you specified one
when you set the watchpoint. If the DO clause contains a GO
command, execution continues and the debugger does not do
the next step.
9. Displays the DBG> 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 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
using SET TYPE WORD, which changes the default length to 2
bytes, or SET TYPE BYTE, which changes the default length to 1
byte. To restore the default length of 4 bytes, use SET TYPE
LONGWORD.
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.
Examples
1. DBG> SET WATCH MAXCOUNT
Sets 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
In this example, the SET WATCH command sets a watchpoint on the
three-element integer array, ARR. Execution then resumes 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
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, and then the
watchpoint is triggered in process 2, interrupting execution.
At this point, SHOW WATCH 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 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
changes 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 you set 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 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
The program location where 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
(*).
conditional-expression
A conditional expression in the currently set language which is
to be evaluated whenever execution reaches the watchpoint.
o If the expression is TRUE, watch action occurs, and the
debugger reports that a break has occurred.
o 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 do not execute, and program execution
continues.
debug-cmd-list
A single debugger command or a sequence of debugger commands
separated by semicolons (;). The commands are executed as part
of the DO clause when execution reaches the watchpoint.
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 canceled 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 override the default behavior. For
example, if you have allocated nonstack storage in P1 space, use
/STATIC when setting a watchpoint on a variable that is
allocated in that storage area. This enables the debugger to
use the faster write-protection method of watching the location
instead of tracing every instruction. Conversely, if, for
example, you have allocated your own stack in P0 space, use
/NOSTATIC 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 executed.
Since this significantly slows down execution, the debugger
issues a message when you set a nonstatic watchpoint. The /INTO
and /OVER qualifiers let you 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.
Shareable Image Watchpoints
When setting a watchpoint in an installed writeable shareble
image, use the SET WATCH/NOSTATIC command.
The reason you must set a nonstatic watchpoint is as follows.
Variables declared in such shareable images are typically static
variables. By default, the debugger watches a static variable
by write-protecting the page containing that variable. However,
the debugger cannot write-protect a page in an installed
writeable shareable image. Therefore, the debugger must use the
slower method of detecting changes, as for nonstatic variables
--- that is, by checking the value at the watched location after
each instruction has executed.
Note that if any other process modifies the watched location's
value, the debugger may report that your program modified the
watched location.
Qualifiers
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 /[NO]STATIC qualifier overrides the debugger's determination
of whether a variable is static or nonstatic.
Additional information available:
/AFTER:n/INTO/NOSILENT/NOSOURCE/NOSTATIC/OVER
/SILENT/SOURCE/STATIC/TEMPORARY
/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
so long as that conditions in the WHEN clause are TRUE. The SET
WATCH /AFTER:1 command is the same 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 called from the defining routine (and
any other such nested calls).
The SET WATCH/INTO command monitors 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
(Default.) Displays the "watch..." message at the watchpoint.
/NOSOURCE
Suppresses the display of the source line for the current
location at the watchpoint. The default is /SOURCE. See help
on the SET STEP [NO]SOURCE command.
/NOSTATIC
Overrides the debugger's default determination of whether a
specified variable (location) is static or nonstatic. Thus, the
debugger treats the variable as a nonstatic variable, even
though it may be allocated in P0 space, and the debugger
monitors the location by tracing every instruction.
Be careful 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 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
Supresses the "watch ..." message and the display of the source
line for the current location at the watchpoint. /SILENT
overrides /SOURCE. The default is /NOSILENT.
/SOURCE
(Default.) Displays the source line for the current location at
the watchpoint. /SILENT overrides /SOURCE. See help on the SET
STEP [NO]SOURCE command.
/STATIC
Overrides the debugger's default determination of whether a
specified variable (location) is static or nonstatic. Thus, the
debugger treats the variable as a static variable, even though
it may be allocated in P1 space, and the debugger monitors the
location by using the faster write-protection method rather than
by tracing every instruction.
Be careful when using this qualifier.
/TEMPORARY
Causes the watchpoint to disappear after it is triggered --- the
watchpoint does not remain permanently set.
WINDOW
Specifies a screen window definition.
Format:
SET WINDOW window-name AT (start-line,line_count
[,start-column,column-count])
A screen window is a region on the terminal screen where 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;
defaults are column 1 for beginning column and the current
terminal screen width for the width of the windows. Once
defined, the name of a screen window can be used in a DISPLAY
command to position screen displays on the screen.
Additional information available:
Parameters
window-name
The window being defined.
start-line
The starting line number of the window --- the line where 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. Must be at least 1. The sum of the start-line and
line-count must not exceed the current screen height.
start-column
(Optional.) The starting column number of the window. This is
the column at which the first character in the window is
displayed. Note that the lefthand border may occupy the column
just to the left of the starting column number. The leftmost
column on the screen is column 1.
column-count
(Optional.) The number of characters per line in the window.
Must be at least 1 and less than the current terminal screen
width.
The sum of the start-column and column-count may not exceed the
current screen width.
Examples
1. DBG> SET WINDOW ONELINE AT (1,1)
Creates a window named ONELINE at the top of the screen that
spans the entire width of the screen.
2. DBG> SET WINDOW MIDDLE AT (9,4,30,20)
Creates a window named MIDDLE for the central region of the
screen.
SHOW
Shows information, depending on the keyword you specify.
Format:
SHOW keyword [/qualifier[...]] [parameter[,...]]
For example, the SHOW BREAK command displays the current
breakpoints.
For more information, see help on the subtopics.
Additional information available:
ABORT_KEYASTATSIGNBREAKCALLSDEFINE
DISPLAYEDITOREVENT_FACILITYEXIT_HANDLERSIMAGE
KEYLANGUAGELOGMARGINSMAX_SOURCE_FILESMODE
MODULEOUTPUTPROCESSRADIXSCOPESEARCHSELECT
SOURCESTACKSTEPSYMBOLTASKTERMINALTRACE
TYPEVECTOR_MODEWATCHWINDOW
Parameters
keyword
(Optional.) The item to be displayed. Valid keywords are as
follows:
ABORT_KEY AST
ATSIGN BREAK
CALLS DEFINE
DISPLAY EDITOR
EVENT_FACILITY EXIT_HANDLERS
IMAGE KEY
LANGUAGE LOG
MARGINS MAX_SOURCE_FILES
MODE MODULE
OUTPUT PROCESS
RADIX SCOPE
SEARCH SELECT
SOURCE STACK
STEP SYMBOL
TASK TERMINAL
TRACE TYPE
VECTOR_MODE WATCH
WINDOW
qualifiers
Depends on the keyword you specify.
parameters
Depends on the keyword you specify.
ABORT_KEY
Identifies the control key currently defined to abort the
execution of a debugger command or to interrupt program
execution.
Format:
SHOW ABORT_KEY
By default, pressing Ctrl/C within a debugging session aborts
the execution of a debugger command and interrupts program
execution. To assign the the abort function to another control
key, use the SET ABORT_KEY command.
Additional information available:
Examples
In the following example, the first SHOW ABORT_KEY command
identifies the default abort command key, Ctrl/C. You then set
Ctrl/P to be the abort key, as verified by the second SHOW
ABORT_KEY command.
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> SET ABORT_KEY = CTRL_P
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_P
AST
SHOW AST tells you whether ASTs are enabled or disabled in your
program (see help on the ENABLE AST and DISABLE AST commands)
but does does not tell you about what ASTs are pending.
Example:
DBG> SHOW AST
ASTs are enabled
DBG> DISABLE AST
ASTs were enabled, are now disabled
DBG> SHOW AST
ASTs are disabled
ATSIGN
Shows the default file specification for the @ (at sign)
command, as previously specified with the SET ATSIGN command.
Example:
DBG> SHOW ATSIGN
No indirect command file default in effect, using DEBUG.COM
DBG> SET ATSIGN MYDISK:[MYDIR.DEBUG].DBG
DBG> SHOW ATSIGN
Indirect command file default is MYDISK:[MYDIR.DEBUG].DBG
BREAK
Shows information about breakpoints that are currently set,
including any options such as WHEN or DO clauses, /AFTER counts,
and so on.
Format:
SHOW BREAK [/qualifier[...]]
By default, the SHOW BREAK command displays information about
both user-defined and predefined breakpoints (if any). This is
the same as SHOW BREAK/USER/PREDEFINED. User-defined
breakpoints are set with the SET BREAK command. Predefined
breakpoints are set automatically when you invoke the debugger,
and they depend on the type of program you are debugging.
If you set a breakpoint with the SET BREAK/AFTER:n command, then
SHOW BREAK displays the current value of the decimal integer n
(that is, the originally specified integer value minus one for
each time the breakpoint location was reached.) The debugger
decrements n each time the breakpoint location is reached until
n is 0 (zero), at which time the debugger takes break action.
Additional information available:
Examples
1. DBG> SET BREAK/AFTER:3 MAIN WHEN (A .EQ. B)
DBG> SHOW BREAK
breakpoint at routine MAIN
/after: 3
WHEN (A .EQ. B)
Identifies the user-defined breakpoint set with the previous SET
BREAK command.
2. DBG> SHOW BREAK
breakpoint at SUB1\LOOP
breakpoint at MAIN\MAIN+1F
do (EX SUB1\D ; EX/SYMBOLIC PSL; GO)
breakpoint at routine SUB2\SUB2
/after: 2
Identifies all breakpoints currently set. This example
indicates user-defined breakpoints that are triggered whenever
execution reaches SUB1\LOOP, MAIN\MAIN, and SUB2\SUB2,
respectively.
3. DBG> SHOW BREAK/PREDEFINED
predefined breakpoint on Ada event "DEPENDENTS_EXCEPTION"
for any value
predefined breakpoint on Ada event "EXCEPTION_TERMINATED"
for any value
Identifies the predefined breakpoints currently set. The
example shows two predefined breakpoints, which are associated
with Ada task exception events. These breakpoints are set
automatically by the debugger for all Ada programs and for any
mixed language program linked with an Ada module.
Qualifiers
Additional information available:
/PREDEFINED
Shows information about predefined breakpoints.
/USER
Shows information about user-defined breakpoints.
CALLS
Shows information about the sequence of currently active
procedure calls. This indicates where you are in the execution
of your program.
Format:
SHOW CALLS [number]
Optionally, you can specify the number of call frames that you
want information about. If you do not specify a number, the
debugger shows information about all call frames.
Additional information available:
Parameters
number
(Optional.) The number of call frames that you want information
about. If you do not specify a number, the debugger shows
information about all call frames.
Examples
In the following example, you are at line 117 of routine PRIMES,
which was called from line 141 of routine LISTPRIMES. An
asterisk (*) to the left of the module name indicates that the
module is set.
DBG> SHOW CALLS
module name routine name line rel PC abs PC
*PRIMES PRIME 117 00000002 000009B8
*PRIMES LISTPRIMES 141 0000004D 00000A29
DEFINE
Shows what define setting was specified by a previous SET DEFINE
command.
Format:
SHOW DEFINE
Example:
! The default is DEFINE/ADDRESS
DBG> SHOW DEFINE
current setting is: DEFINE/ADDRESS
DBG> SET DEFINE VALUE
! Treat all DEFINEs as DEFINE/VALUE
DBG> SHOW DEFINE
current setting is: DEFINE/VALUE
To display all defined symbols, use the SHOW SYMBOL/DEFINED
command.
DISPLAY
Lists defined screen displays --- name, maximum size, screen
window, kind, and debugger command list (if any). The screen
displays are listed in their pasting order with the most hidden
display listed first.
Format:
SHOW DISPLAY [/qualifier[...]] [display-name]
If you use the /ALL qualifier, the asterisk wildcard (*), or no
parameters, then SHOW DISPLAY lists names and attributes of all
displays.
You can use the astrisk (*) in the display name, in which case
all matching names names are displayed.
Additional information available:
Examples
DBG> SHOW DISPLAY
display SRC at H1, size = 64
kind = SOURCE (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC)
display INST at H1, size = 64, removed
kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\%PC)
display REG at RH1, size = 64, removed, kind = REGISTER
display OUT at S45, size = 100, kind = OUTPUT
display FOO at (10,4,24,30), size = 64, kind = OUTPUT
display PROMPT at S6, size = 64, kind = PROGRAM
DBG> SHOW DISPLAY SRC
display SRC at H1, size = 64
kind = SOURCE (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC)
Parameters
display-name
(Optional.) The display you want information about. If you do
not specify a a name, the debugger shows information about all
displays. You can use the asterisk wildcard (*). Do not
specify a display name with the /ALL qualifier.
Example:
The following command gives information about all displays whose
name begins with S:
DBG> SHOW DISPLAY S*
Qualifiers
Additional information available:
/ALL
Lists all display definitions. Do not specify a display name
parameter with /ALL.
/SUFFIX
/SUFFIX[=process-identifier-type]
Appends a process-identifying suffix to a display name. The
suffix denotes the visible process.
Use /SUFFIX directly after a display name, primarily in command
procedures when specifying display definitions or key
definitions bound to display definitions. This applies only to
a multiprocess debugging configuration (when the DBG$PROCESS
logical name is defined as MULTIPROCESS). For more information,
see help on Multiprocess Specifying_Processes.
Use any of the following process-identifier-type keywords:
Keyword Effects
----------------------------------------------------------------
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 use /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
help on the SET PROMPT/SUFFIX command).
EDITOR
Shows the action taken by the EDIT command, as set by the SET
EDITOR command.
Example:
DBG> SHOW EDITOR
The editor is SPAWNed, with command line "LSEDIT/START=(n,1)"
DBG> SET EDITOR/CALLABLE_TPU
DBG> SHOW EDITOR
The editor is CALLABLE_TPU, with command line "TPU"
EVENT_FACILITY
Identifies the current event facility and the associated event
names. Event facilities are available for programs that call
Ada or SCAN routines or that use DECthreads services.
Format:
SHOW EVENT_FACILITY
Additional information available:
Description
The current event facility (ADA, THREADS, or SCAN) defines the
eventpoints that you can set with the SET BREAK/EVENT and SET
TRACE/EVENT commands.
The SHOW EVENT_FACILITY command identifies the event names
associated with the current event facility. These are the
keywords that you can specify with the (SET,CANCEL) BREAK/EVENT
and (SET,CANCEL) TRACE/EVENT commands.
Related commands:
SET EVENT_FACILITY SHOW TASK
(SET,CANCEL) BREAK/EVENT SHOW BREAK
(SET,CANCEL) TRACE/EVENT SHOW TRACE
Examples
DBG> SHOW EVENT_FACILITY
event facility is THREADS
...
Identifies the current event facility as THREADS (DECthreads)
and lists the associated event names that can be used with a SET
BREAK/EVENT or SET TRACE/EVENT command.
EXIT_HANDLERS
Lists the exit handlers that your program has declared. The
exit handler routines are displayed in the order in which they
are called (last in, first out). The routine name is displayed
symbolically if possible; otherwise its address is displayed.
The debugger's exit handlers are not displayed.
Example:
DBG> SHOW EXIT
exit handler at MODNAME\EXIT_ROUT1
exit handler at MODNAME\EXIT_ROUT2
IMAGE
Shows information about the shareable images that are part of
your running program --- name start address, end addresses, and
whether the image is set (see help on the SET IMAGE command).
Format:
SHOW IMAGE [image-name]
If you do not specify an image name, all images are displayed.
You can include wildcards (*).
Example:
DBG> SHOW IMAGE SHARE$*
image name set base address end address
*SHARE yes 00000200 00000FFF
SHARE1 no 00001000 000017FF
SHARE2 no 00018C00 000191FF
SHARE3 no 00019200 000195FF
SHARE4 no 00019600 0001B7FF
total images: 5 bytes allocated: 33032
The asterisk (*) to the left of the image name indicates the
current image.
KEY
Shows current definitions of the specified keys for the
specified states.
Format:
SHOW KEY [/qualifier[...]] [key-name[,...]]
Example:
DBG> DEFINE/KEY KP0 "STEP"
DBG> SHOW KEY KP0
DEFAULT definition for key KP0:
"STEP"
Additional information available:
Parameters
key-name
(Optional.) The key you want information about. You can
specify one key or a list of keys. Do not specify a key name or
key-name list with the /ALL qualifier. Use any of the following
key names. Note that some keys are not available on VT100 and
VT52 series terminals.
Key name LK201 VT100-type VT52-type
---------------------------------------------------------
PF1 PF1 PF1 PF1
PF2 PF2 PF2 PF2
PF3 PF3 PF3 PF3
PF4 PF4 PF4 PF4
KP0,...,KP9 0,1,...,9 0,1,...,9 0,1,...,9
PERIOD . . .
COMMA , , ,
MINUS - - -
ENTER Enter ENTER ENTER
UP ^ ^ ^
DOWN v v v
LEFT <- <- <-
RIGHT -> -> ->
E1 Find n/a n/a
E2 Insert Here n/a n/a
E3 Remove n/a n/a
E4 Select n/a n/a
E5 Prev Screen n/a n/a
E6 Next Screen n/a n/a
HELP Help n/a n/a
DO Do n/a n/a
F6,F7,...,F20 F6,F7,...,F20 n/a n/a
Qualifiers
Additional information available:
/ALL/BRIEF/DIRECTORY/NOSTATE/STATE
/ALL
Shows all keys defined in the current state(s). Do not specify
a key name parameter with /ALL.
/BRIEF
Shows only the key definition and state. By default, the
debugger provides other information including qualifiers
associated with the definition, and so on.
/DIRECTORY
Shows only the names of keys that have been defined.
/NOSTATE
(Default.) Shows the definitions of the specified keys for the
current state.
/STATE=state-name
Shows the definitions of the specified keys for the specified
state(s). The default is /NOSTATE.
Format:
SHOW KEY/STATE=state-name-list [/qualifier[...]] [key-name[,...]]
For example, the following command lists the keys defined for
the GOLD state:
DBG> SHOW KEY/STATE=GOLD/DIR
LANGUAGE
Shows the current language.
Format:
SHOW LANGUAGE
The current language is the language last specified by the SET
LANGUAGE command or the language specified at debugger start-up.
Supported languages are:
Ada BASIC BLISS C COBOL DIBOL
FORTRAN MACRO Pascal PLI RPG SCAN
For more information, see help on Language_Support.
LOG
Shows the name of the current log file and tells you whether the
debugger is writing to that log file.
Format:
SHOW LOG
The current log file is the log file last specified by a SET LOG
command or the default log file (DEBUG.LOG).
MARGINS
Shows the current source-line margin settings for displaying
source code.
Format:
SHOW MARGINS
You can specify margin settings with the SET MARGIN command.
The default left margin is 1 and the default right margin is
255.
MAX_SOURCE_FILES
Shows the maximum number of source files that the debugger may
keep open at any one time.
Format:
SHOW MAX_SOURCE_FILES
To set this number, use the SET MAX_SOURCE_FILES command. The
default is 5.
MODE
Identifies the current debugger modes (screen or noscreen,
keypad or nokeypad, and so on) and the current radix.
Format:
SHOW MODE
The current debugger modes are the modes last specified with the
SET MODE command or the following:
DYNAMIC NOG_FLOAT (D_float) INTERRUPT
KEYPAD LINE NOSCREEN
SCROLL NOSEPARATE SYMBOLIC
MODULE
Provides a formatted alphabetized display giving information
about all modules in your program.
Format:
SHOW MODULE [/qualifier[...]] [module-name]
Included in the display is a column telling you whether the
module is set, and a column telling you how many bytes are
required to set the module. At the bottom of the display is a
number which tells you how many bytes are currently allocated in
the debugger's memory pool.
Additional information available:
Parameters
module-name
(Optional.) The module you want displayed. If you do not
specify a name, the debugger shows information about all
modules. You can use the asterisk wildcard (*).
Example:
The following command gives information about all modules whose
name begins with DBG:
DBG> SHOW MODULE DBG*
Examples
DBG> SHOW MODULE
module name symbols size
X1 no 1504
X2 no 1520
X3 yes 396
total PASCAL modules: 3. bytes allocated: 35928.
Qualifiers
Additional information available:
/NORELATED/NOSHARE/RELATED/SHARE
/NORELATED
(Ada only. Default.) Specifies that no information about
related modules is to be output.
/NOSHARE
(Default.) Specifies that shareable image modules not be
included in the SHOW MODULE output.
/RELATED
(Ada only.) Shows information about modules that are related to
each module normally displayed. It lists the relationship of
each of these subordinate modules to the main module along with
the normal information you get with each module. Ada packages
and Ada subunits are the language constructs which give rise to
relationships between modules. The default is /RELATED.
/SHARE
Includes shareable images in the SHOW MODULE display (for
example, SHARE$LIBRTL, SHARE$FORRTL). By default, these are
omitted since there is only limited support for debugging
shareable images. The default is/NOSHARE.
OUTPUT
Tells you whether the debugger is displaying output on the
terminal (term or noterm), whether the debugger is writing
output to a log file (log or nolog), and whether the debugger
echoes commands from command procedures and DO clauses
(verify/noverify).
Format:
SHOW OUTPUT
PROCESS
Shows information about specified processes and any images
running in those processes.
Format:
SHOW PROCESS [/qualifier] [process-spec[,...]]
A process can first appear in a SHOW PROCESS display as soon as
it comes under debugger control. A process can no longer appear
in a SHOW PROCESS display if the process is terminated by an
EXIT or QUIT command.
By default (/BRIEF), one line of information is displayed for
each process, including the following:
o The process number assigned by the debugger. A process
number is assigned sequentially, starting with 1, to each
process that comes under debugger control. If a process is
terminated by an EXIT or QUIT command, its process number is
not reused during that debugging session. The visible
process is marked with an asterisk (*) in the leftmost
column.
o The VMS process name.
o Whether the process has been put on hold with a SET
PROCESS/HOLD command.
o The current debugging state for that process (see help on the
States subtopic).
o The location (symbolized, if possible) where execution of the
image is suspended in that process.
The SHOW PROCESS/FULL command gives additional information about
processes.
This applies only to a multiprocess debugging configuration
(when the DBG$PROCESS logical name is defined as MULTIPROCESS).
For more information, see help on Multiprocess
Specifying_Processes.
Additional information available:
ExamplesParametersQualifiersStates
Examples
1. DBG_2> SHOW PROCESS
Number Name Hold State Current PC
* 2 _WTA3: HOLD break SCREEN_IO\%LINE 47
In this example, the SHOW PROCESS command displays (by default)
one line of information about the visible process (which is
identified with an asterisk (*) in the leftmost column. The
process has the VMS process name _WTA3:. It is the second
process brought under debugger control (process number 2). It
has been put on hold, and the image's execution is suspended at
a breakpoint at line 47 of module SCREEN_IO.
2. DBG_2> SHOW PROCESS/FULL %PREVIOUS_PROCESS
Shows the maximum level of information about the previous
process in the circular list of processes (process number 1, in
this case).
3. DBG_2> SHOW PROCESS %PROCESS_NAME TEST_3
Number Name Hold State Current PC
7 TEST_3 watch of TEST_3\ROUT4\COUNT
TEST_3\%LINE 54
Displays one line of information about process TEST_3. The
image is suspended at a watchpoint of variable COUNT.
4. DBG_2> SHOW PROCESS/DYNAMIC
Dynamic process setting is enabled
Indicates that dynamic process setting is enabled.
Parameters
process-spec
(Optional.) Specifies a process. Use any of the following
forms:
Format Effects
----------------------------------------------------------------
[%PROCESS_NAME] ["]process-name["]
The VMS process name. If it contains
spaces or lowercase characters, en-
close it in apostrophes (') or quota-
tion marks ("). You can use the
asterisk (*) wildcard.
%PROCESS_PID process_id The VMS process identification number
(PID, a hexadecimal number).
%PROCESS_NUMBER process-number
(or %PROC process-number)
The number assigned to a process when
it comes under debugger control. A
new number is assigned sequentially,
starting with 1, to each process. If
a process is terminated with EXIT or
QUIT, the number is not reused during
the debugging session. Process numbers
appear in a SHOW PROCESS display.
Processes are ordered in a circular
list so they can be indexed with the
%PREVIOUS_PROCESS and %NEXT_PROCESS.
built-in symbols.
process-group-name A symbol defined with DEFINE/PROCESS_
GROUP to represent a group of processes.
%NEXT_PROCESS The next process after the visible
process in in the debugger's circular
process list.
%PREVIOUS_PROCESS The previous process before the vis-
ible process in the debugger's cir-
cular process list.
%VISIBLE_PROCESS The process whose stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
You can also use the asterisk wildcard (*) to specify all
processes. If you do not specify a process, the visible process
is selected, unless you specify the /ALL qualifier.
Qualifiers
Additional information available:
/ALL/BRIEF/DYNAMIC/FULL/HOLD/NOHOLD/VISIBLE
/ALL
Selects all processes known to the debugger for display. Do not
specify a process with /ALL.
/BRIEF
(Default.) Displays only one line of information for each
process selected for display.
/DYNAMIC
Shows whether dynamic process setting is enabled or disabled.
Dynamic process setting is enabled by default and is controlled
with the SET PROCESS/[NO]DYNAMIC command.
Do not specify a process parameter with /DYNAMIC and do not use
with /ALL, /BRIEF, /FULL, /[NO]HOLD, or /VISIBLE.
/FULL
Shows maximum information for each process selected for display.
/HOLD
Selects processes that are on hold for display. If you do not
specify a process, /HOLD selects all processes that are on hold.
If you specify a process list, /HOLD selects the processes in
the list that are on hold.
If you use both /HOLD and /NOHOLD on the same command line, the
effect is to select processes that are on hold and processes
that are not on hold for display (the qualifier specified last
on the command line does not override the other).
/NOHOLD
Selects processes that are not on hold for display. If you do
not specify a process, /NOHOLD selects all processes that are
not on hold. If you specify a process list, /NOHOLD selects the
processes in the list that are not on hold.
If you use both /HOLD and /NOHOLD on the same command line, the
effect is to select processes that are on hold and processes
that are not on hold for display (the qualifier specified last
on the command line does not override the other).
/VISIBLE
(Default.) Selects the visible process for display.
States
The debugging states that may appear in a SHOW PROCESS display
are as follows:
State Effects
----------------------------------------------------------------
Activated The image and its process have just
been brought under debugger control,
either through a RUN/DEBUG command
at the DCL level, a CONNECT command
in the debugger, a Ctrl/Y--DEBUG
sequence, or the program signalling
SS$_DEBUG while it was not under
debugger control.
Break A breakpoint was triggered.
Break on branch
Break on call
Break on instruction
Break on lines
Break on modify of
Break on return
Exception break
Excep. break preceding
Interrupted Execution was interrupted in that
process, either because execution
was suspended in some other process,
or because you interrupted program
execution with the abort key (the
default is Ctrl/C).
Step A STEP command has completed.
Step on return
Terminated The image indicated has terminated
execution but the process is still
under debugger control. Therefore,
you can get information about the
image and its process. To terminate
the process, use the EXIT or QUIT
command.
Trace A tracepoint was triggered.
Trace on branch
Trace on call
Trace on instruction
Trace on lines
Trace on modify of
Trace on return
Exception trace
Excep. trace preceding
Unhandled exception at An unhandled exception was encountered.
Watch of A watchpoint was triggered.
RADIX
Shows the current radix settings (input and output radix). The
radix may be one of the following:
BINARY OCTAL DECIMAL HEXADECIMAL
SCOPE
Shows the current scope search list --- that is, the scope
search list specified by the last SET SCOPE command.
Format:
SHOW SCOPE
The current scope search list designates one or more program
locations (specified by path names or other special characters)
to be used in the interpretation of symbols that are specified
without path-name prefixes in debugger commands.
SEARCH
Shows the current SEARCH parameters.
Format:
SHOW SEARCH
The current SEARCH parameters are specified by the SET SEARCH
command or are the default values ALL and STRING. 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).
SELECT
Shows the current screen display select settings as done by the
SELECT command.
Format:
SHOW SELECT
SOURCE
Shows the source directory search list(s) currently in effect.
Format:
SHOW SOURCE [/EDIT]
The SET SOURCE command specifies a source directory search list
for a particular module (specified with the /MODULE= qualifier)
or for all modules.
If you did not specify a directory search list with a SET SOURCE
command, SHOW SOURCE indicates that no directory search list is
currently in effect. In this case, the debugger expects all
source files to be in the same directory as they were at compile
time.
Additional information available:
Qualifiers
Additional information available:
/EDIT
Shows the directory search lists that were specified with the
SET SOURCE/EDIT command.
STACK
Shows information from the current call stack. For each frame,
SHOW STACK displays information such as the condition handler
and saved register values.
Format:
SHOW STACK [number]
Optionally, you can specify the number of frames you want
information about. If you do not specify a number, the debugger
shows information about all stack frames.
Additional information available:
Argument ListExamplesParameters
Argument List
One part of the output of SHOW STACK (if existing) for each
frame, is the Argument List --- the list of arguments passed
along with the call to a subroutine.
In some cases the list may contain addresses to actual
arguments. In these cases, the EXAMINE address command returns
the values of these arguments.
Examples
DBG> SHOW STACK
stack frame 0 (2146814812)
condition handler: 0
SPA: 0
S: 0
mask: ^M<R2>
PSW: 0000 (hexadecimal)
saved AP: 7
saved FP: 2146814852
saved PC: EIGHTQUEENS\%LINE 69
saved R2: 0
argument list:(1) EIGHTQUEENS\%LINE 68+2
stack frame 1 (2146814852)
condition handler: SHARE$PASRTL+888
SPA: 0
S: 0
mask: none saved
PSW: 0000 (hexadecimal)
saved AP: 2146814924
saved FP: 2146814904
saved PC: SHARE$DEBUG+667
Parameters
number
(Optional.) The number of frames you want information about.
If you do not =specify a number, the debugger shows information
about all stack frames.
STEP
Shows the current step conditions.
Format:
SHOW STEP
Current step conditions are the step conditions specified by the
last SET STEP command or the default step conditions specified
by the current language. The current step conditions include:
o Whether the debugger steps by lines or by instructions
o Whether the debugger steps into or over routines in the user
program
o Whether source is displayed on each STEP command ([NO]SOURCE)
o Whether any output is given on each STEP command ([NO]SILENT)
SYMBOL
Shows information about the symbols in the debugger's run-time
symbol table (RST) for the current image.
Format:
SHOW SYMBOL symbol-name[,...] [IN scope[,...]]
Additional information available:
DescriptionExamplesParametersQualifiers
Description
The current image is either the main image (by default) or the
image specified as the current image by a previous SET IMAGE
command.
The SHOW SYMBOL command displays information that the debugger
has about a given symbol in the current image. This information
might not be the same as what the compiler had or even what you
see in your source code. Nonetheless, it is useful for
understanding why the debugger might act as it does when
handling symbols.
Without a qualifier, SHOW SYMBOL lists all possible declarations
or definitions of a specified symbol that exist in the RST for
the current image-that is, in all set modules and in the GST for
that image. Symbols are displayed with their path names. A
path name identifies the search scope (module, nested routines,
blocks, and so on) that the debugger must follow to reach a
particular declaration of a symbol. When specifying symbolic
address expressions in debugger commands, you need to use path
names only if a symbol is defined multiple times and the
debugger cannot resolve the ambiguity.
The /DEFINED and /LOCAL qualifiers display information about
symbols defined with the DEFINE command (not the symbols that
are derived from your program). The other qualifiers display
information about symbols defined within your program.
Examples
1. DBG> SHOW SYMBOL I
data FORARRAY\I
DBG>
Shows that symbol I is defined in module FORARRAY and is a
variable (data) rather than a routine.
2. DBG> SHOW SYMBOL/ADDRESS INTARRAY1
data FORARRAY\INTARRAY1
descriptor address: 0009DE8B
Shows that symbol INTARRAY1 is defined in module FORARRAY and
has a memory address of 0009DE8B.
3. DBG> SHOW SYMBOL *PL*
Lists all symbols whose names contain the string PL.
4. DBG> SHOW SYMBOL/TYPE/ADDRESS *
Shows all information about all symbols.
5. DBG> SHOW SYMBOL * IN MOD3\COUNTER
routine MOD3\COUNTER
data MOD3\COUNTER\X
data MOD3\COUNTER\Y
Lists all symbols defined in the scope denoted by the path name
\MOD3\COUNTER.
6. DBG> DEFINE/COMMAND SB=SET BREAK
DBG> SHOW SYMBOL/DEFINED SB
defined SB
bound to: SET BREAK
was defined /command
In this example, the DEFINE/COMMAND command defines SB as a
symbol for the command SET BREAK. The SHOW SYMBOL/DEFINED
command displays that definition.
Parameters
symbol-name
The symbol to be identified. A valid symbol name is a single
identifier or a label name of the form %LABEL n, where n is an
integer (you cannot use compound names such as RECORD.FIELD or
ARRAY[1,2]). If you specify the asterisk wildcard (*) by
itself, all symbols are listed. You can also use the asterisk
within a symbol name.
scope
The name of a module, routine, or lexical block, or a numeric
scope. It has the same syntax as the scope specification in a
SET SCOPE command and can include path-name qualification. All
specified scopes must be in set modules in the current image.
The SHOW SYMBOL command displays only those symbols in the RST
for the current image that both match the specified name and are
declared within the lexical entity specified by the scope
parameter. If you omit the scope parameter, the debugger
searches all set modules and the global symbol table (GST) for
the current image for symbols that match the symbol name you
specified.
Qualifiers
Additional information available:
/ADDRESS/DEFINED/DIRECT/LOCAL/TYPE/USE_CLAUSE
/ADDRESS
Shows the address specification for each selected symbol. The
address specification is the method of computing the symbol's
address. It can merely be the symbol's memory address, but it
can also involve indirection or an offset from a register value.
Some symbols have address specifications too complicated to
present in any understandable way. These address specifications
are labeled "complex address specifications."
/DEFINED
Shows symbols you have defined with the DEFINE command (symbol
definitions that are in the DEFINE symbol table).
/DIRECT
Shows only those symbols declared directly in the scope
parameter. Does not show symbols declared in lexical entities
nested within the scope specified by the scope parameters.
/LOCAL
Shows symbols that are defined with the DEFINE/LOCAL command
(symbol definitions that are in the DEFINE symbol table).
/TYPE
Shows data type information for each selected symbol.
/USE_CLAUSE
(Applies only to Ada.) Identifies any Ada package that a
specified block, subprogram, or package names in a use clause.
If the symbol specified is a package, also identifies any block,
subprogram, package, and so on that names the specified symbol
in a use clause.
TASK
Shows information about the tasks of a tasking program (also
called a multithread program).
Format:
SHOW TASK [/qualifier...] [task-spec[,...]]
Additional information available:
ParametersDescriptionSelection QualifiersInformation QualifiersExamples
Parameters
task-spec
A task value. Use any of the following forms:
o A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
o A task ID (for example, %TASK 2), as indicated in a SHOW TASK
display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL,
or EXIT command executes.)
%CALLER_TASK (Applies only to Ada.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_TASK The task previous to the visible task in
the debugger's task list.
%VISIBLE_TASK The task whose call stack and register set
are the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk wildcard (*). Instead, use the /ALL
qualifier. If you do not specify a task or a task selection
qualifier (/ALL, /[NO]HOLD, /PRIORITY, /STATE), the visible task
is selected for display.
Description
A task can first appear in a SHOW TASK display as soon as it is
created. A task can no longer appear in a SHOW TASK display if
it is terminated or (in the case of an Ada tasking program) if
its master is terminated. By default, the SHOW TASK command
displays one line of information for each task selected.
Related commands:
SET TASK (SET,SHOW) EVENT_FACILITY
EXAMINE/TASK DEPOSIT/TASK
Selection Qualifiers
You can use task-selection qualifiers singly or in combination.
Except for the /ALL qualifier, they can also be used with
task-spec parameters. When you use task-selection qualifiers in
combination, the logical AND of the selection criterea is
applied. This gives the you a powerful and flexible mechanism
to select the tasks of interest from the many tasks a
complicated program may create. There are five ways to indicate
what tasks are of interest:
o A task list selects an explicit set of tasks.
o The /ALL qualifier selects all tasks.
o The /PRIORITY, /STATE, and /[NO]HOLD qualifiers can be used
singly or in combination to select all tasks having the
logical AND of the specified criteria.
o The /PRIORITY, /STATE, and /[NO]HOLD qualifiers can be used
with a task list to select from a small set of "interesting"
tasks.
o By default, the visible task is selected if no other
selection is specified.
Additional information available:
/ALL
Selects all existing tasks for display --- namely, tasks that
have been created and (in the cse of Ada tasks) whose master has
not yet been terminated.
See the Description subtopic for the effect of the current event
facility. Do not use specify a task parameter with /ALL.
/HOLD
/NOHOLD
Selects either tasks that are on hold, or tasks that are not on
hold for display.
If you do not specify a task, /HOLD selects all tasks that are
on hold. If you specify a task list, /HOLD selects the tasks in
the task list that are on hold.
If you do not specify a task, /NOHOLD selects all tasks that are
not on hold. If you specify a task list, /NOHOLD selects the
tasks in the task list that are not on hold. <P> See the
Description subtopic for the effect of the current event
facility.
/PRIORITY=(n[,...])
If you do not specify a task, selects all tasks having any of
the specified priorities, n, where n is a decimal integer from 0
to 15. If you specify a task list, selects the tasks in the
task list that have any of the priorities specified.
See the Description subtopic for the effect of the current event
facility.
/STATE=(state[,...])
If you do not specify a task, selects all tasks that are in any
of the specified states --- RUNNING, READY, SUSPENDED, or
TERMINATED. If you specify a task list, selects the tasks in
the task list that are in any of the states specified.
See the Description subtopic for the effect of the current event
facility.
Information Qualifiers
These qualifiers determine what type of information to display.
If yuou do not specify a task information qualifier, the default
is to display a brief one line status report for each task
selected by other qualifiers, or explicitly given in the list of
task names.
Additional information available:
/CALLS/FULL/STATISTICS/TIME_SLICE
/CALLS
Does a SHOW CALLS command for each task selected for display.
This identifies the currently active routine calls (the call
stack) for a task.
/FULL
Displays additional information for each task selected for
display. The /FULL qualifier provides additional information if
used either by itself or with the /CALLS or /STATISTICS
qualifier.
/STATISTICS
Displays task statistics for the entire tasking system. This
information enables you to measure the performance of your
tasking program. The larger the number of total schedulings
(also known as context switches), the more tasking overhead
there is. When you specify /STATISTICS, the only other
permissible qualifier is /FULL.
/TIME_SLICE
Displays the current time-slice value, in seconds, as specified
by a previous SET TASK/TIME_SLICE command. If no SET
TASK/TIME_SLICE command was previously entered, displays the
time-slice value, if any, specified in the program.
If no time-slice value was previously established, the value is
0.0 --- that is, time slicing is disabled.
Do not specify another qualifier when you specify /TIME_SLICE.
Examples
1. DBG> SHOW TASK
Shows information for the visible task (typically the task that
entered the debugger).
2. DBG> SHOW TASK/ALL/FULL
Shows detailed information for all currently existing tasks.
3. DBG> SHOW TASK/ALL/PRIO=(4,5)/STATE=(READY,RUN)/NOHOLD/CALLS=3
Shows information for all priority 4 or 5 tasks, in the READY or
RUN state, and not on hold. In addition, shows the last 3
procedure calls in each task.
4. DBG> SHOW TASK/PRIORITY=(3,4)/STATE=READY X,Y,Z
Shows which of X, Y, and Z have priority 3 or 4 and are in the
READY state.
5. DBG> SHOW TASK/STATISTICS/FULL
Shows full statistics for the tasking system.
6. SHOW TASK/ALL/STATE=READY
Shows all tasks which are ready to be run.
7. SHOW TASK/PRI=3/STATE=SUSP X,Y,Z
Shows which tasks of X, Y, and Z have priority 3 and are
suspended.
TERMINAL
Shows the terminal width and height used to format debugger
output.
Format:
SHOW TERMINAL
To set the width and height, use the SET TERMINAL command.
TRACE
Shows information about tracepoints that are currently set,
including any options such as WHEN or DO clauses, /AFTER counts,
and so on.
Format:
SHOW TRACE [/qualifier[...]]
By default, the SHOW TRACE command displays information about
both user defined and predefined tracepoints (if any). This is
the same as SHOW TRACE/USER/PREDEFINED. User-defined
tracepoints are set with the SET TRACE command. Predefined
tracepoints are set automatically when you invoke the debugger,
and they depend on the type of program you are debugging.
If you set a tracepoint using the SET TRACE/AFTER:n command,
then SHOW TRACE displays the current value of the decimal
integer (n) --- that is, the originally specified integer value
minus one for each time the tracepoint location was reached.
(The debugger decrements n each time the tracepoint location is
reached until the value of n is zero, at which time the debugger
takes trace action.)
Additional information available:
Examples
1. DBG> SET TRACE/INST WHEN (A .NE. 0)
DBG> SHOW TRACE
tracepoint on instructions
WHEN (A .NE. 0)
Identifies the user-defined tracepoint set with the previous SET
TRACE command.
2. DBG> SHOW TRACE
tracepoint at routine CALC\MULT
tracepoint on calls:
RET RSB BSBB JSB BSBW CALLG CALLS
Identifies all tracepoints that are currently set. This example
indicates user defined tracepoints that are triggered whenever
execution reaches routine MULT in module CALC or one of the
instructions RET, RSB, BSBB, JSB, BSBW, CALLG, or CALLS.
3. DBG_2> SHOW TRACE/PREDEFINED
predefined tracepoint on program activation
DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_/SUF=PROCESS_NU AT H1
SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC);
SET DISP/DYN/REM/SIZE:64/PROC INST_/SUF=PROCESS_NU AT H1
INSTRUCTION (EXAM/INSTRUCTION .0\%PC))
predefined tracepoint on program termination
Identifies the predefined tracepoints that are currently set.
The example shows the predefined tracepoints that are set
automatically by the debugger for a multiprocess program (when
the DBG$PROCESS logical name is defined MULTIPROCESS). The
tracepoint on program activation triggers whenever a new process
comes under debugger control. The DO clause creates a
process-specific source display named SRC_n and a
process-specific instruction display named INST_n whenever a
process activation tracepoint is triggered. The tracepoint on
program termination triggers whenever a process performs an
image exit.
Qualifiers
Additional information available:
/PREDEFINED
Shows information about predefined tracepoints.
/USER
Shows information about user defined tracepoints.
TYPE
Shows the current default type or, if the you specify the
/OVERRIDE qualifier, shows the current override type.
Format:
SHOW TYPE [/qualifier]
Additional information available:
Qualifiers
Additional information available:
/OVERRIDE
Shows the current override type.
VECTOR_MODE
(Applies only to vectorized programs.) Identifies the current
vector mode --- synchronized or nonsynchronized.
Format:
SHOW VECTOR_MODE
The current vector mode is determined by the SET VECTOR_MODE
command. The default is nonsynchronized.
Additional information available:
Examples
DBG> SHOW VECTOR_MODE
Vector mode is nonsynchronized
DBG> SET VECTOR_MODE SYNCHRONIZED
DBG> SHOW VECTOR_MODE
Vector mode is synchronized
WATCH
Shows the locations of watchpoints (set with the SET WATCH
command), including WHEN and DO clauses, /AFTER count, and so
on.
Format:
SHOW WATCH
Example:
DBG> SET WATCH X DO (SHOW CALLS)
DBG> SHOW WATCH
watchpoint of X
DO (SHOW CALLS)
WINDOW
Lists the defined screen windows --- name and screen position.
This list includes all user-defined windows as well as the
predefined windows. The windows are listed in alphabetical
order.
Format:
SHOW WINDOW {/ALL | window-name[,...]}
You can use tghe /ALL qualifier or you can specify one or more
window names but not both. Using /ALL or the asterisk wildcard
(*) lists the names and attributes of all windows.
You can use the asterisk (*) as part of a window name, in which
case the debugger lists all matching windows.
Additional information available:
Parameters
window-name
(Optional.) The window you want displayed. If you do not
specify a window name, the debugger lists information about all
windows. You can use the asterisk wildcard (*).
For example, the following command shows information about all
windows whose name begin with S:
DBG> SHOW WINDOW S*
Qualifiers
Additional information available:
/ALL
Lists all screen window definitions --- same as SHOW WINDOW *.
SPAWN
Creates a subprocess so you can execute DCL commands without
leaving the debugging session.
Format:
SPAWN [/qualifier] ["]dcl-command["]
If you specify a DCL command as the parameter to SPAWN, that
command executes in the context of a subprocess. For example,
the SPAWN MAIL command invokes the VMS MAIL utility. Exiting
from MAIL terminates the subprocess and resumes your debugging
session.
If you do not specify a DCL command, SPAWN returns you to the
DCL level in the subprocess. You can then enter DCL commands.
To terminate the subprocess and resume the debugging session,
log out of the subprocess.
Additional information available:
Examples
DBG> SPAWN MAIL
You have 2 new messages
MAIL> ...
MAIL> EXIT
%DEBUG-I-RETURNED, control returned to process TITLE
DBG>
Parameters
dcl-command
The DCL command you want to execute. If the command contains a
semicolon (;), put the command in quotes. (Otherwise, the
debugger interprets the semicolon as the end of a debugger
command.)
Qualifiers
Additional information available:
/INPUT=file-spec
Specifies an input file containing one or more DCL commands to
be executed by the spawned subprocess. If you specify a
DCL-command string with the SPAWN command and an input file with
the /INPUT qualifier, the DCL-command string is processed before
the input file. Once processing of the input file is complete,
the subprocess is terminated.
You cannot use wildcards in the file specification.
/NOWAIT
Specifies that the parent process continue in parallel with the
spawned subprocess. This is the same as the SPAWN/NOWAIT
command in DCL. The default is /WAIT.
/OUTPUT=file-spec
Directs the output from the SPAWN operation to the specified
file. You cannot use wildcards in the file specification.
/WAIT
(Default.) Suspends the parent process and attaches the
terminal to the subprocess.
STEP
Executes your program by line, instruction, or some other step
unit. STEP is one of the four debugger commands that can cause
your program to execute (the others are CALL, EXIT, and GO).
Format:
STEP [/qualifier[...]] [number]
Additional information available:
DescriptionExamplesMultiprocess ProgramsParametersQualifiers
Description
The STEP command depends on the following:
o The default STEP mode, which you can specify with the SET
STEP command
o The qualifier specified with the STEP command, if any
o The number of step units, if any, specified as parameter to
the STEP command
If you have not done a SET STEP command and you use STEP without
specifying a parameter or qualifier, then STEP does the
following:
1. Executes a line of source code (STEP/LINE is the default).
2. Reports that execution has completed by issuing a "stepped
to..." message (the default is STEP/NOSILENT).
3. Displays the line of source code where execution is
suspended (the default is STEP/SOURCE).
4. Displays the DBG> prompt.
If you plan to enter several STEP commands with the same
qualifiers, you can first use the SET STEP command to specify
new default qualifiers (for example, SET STEP INTO NOSYSTEM
makes the STEP command behave like STEP/INTO/NOSYSTEM). Then
you do not have to use those qualifiers with the STEP command.
You can override the current default qualifiers for the duration
of a single STEP command by specifying other qualifiers.
To check the current STEP defaults, use the SHOW STEP command.
Examples
1. DBG> SHOW STEP
step type: source, nosilent, by line, over routine calls
DBG> STEP
stepped to SQUARES$MAIN\%LINE 4
4: OPEN(UNIT=8, FILE='DATAFILE.DAT', STATUS='OLD')
The SHOW STEP command identifies the current default qualifiers
for the STEP command. In this case, STEP, without any
parameters or qualifiers, executes the next line of source code.
After the STEP command has completed, execution is suspended at
the beginning of line 4.
2. DBG> STEP 5
stepped to MAIN\%LINE 47
47: SWAP(X,Y);
Executes the next 5 lines of source code. After the STEP
command has completed, execution is suspended at the beginning
of line 47.
3. DBG> STEP/INTO
stepped to routine SWAP
23: procedure SWAP (A,B: in out integer) is
DBG> STEP
stepped to MAIN\SWAP\%LINE 24
24: TEMP: integer := 0;
DBG> STEP/RETURN
stepped on return from MAIN\SWAP\%LINE 24 to MAIN\SWAP\%LINE 29
29: end SWAP;
In this example, the STEP/INTO command executes the program up
to the start of the routine that is being called at the current
PC value (SWAP, in this case). The STEP command executes the
next line of source code. The STEP/RETURN command finishes
executing the SWAP routine up to its RET instruction (that is,
up to the point just prior to transferring control back to the
calling routine).
4. DBG> SET STEP INSTRUCTION
DBG> SHOW STEP
step type: source, nosilent, by instruction, over routine calls
DBG> STEP
stepped to SUB1\%LINE 26: MOVL S^ 4,B^-20(FP)
26: Z:integer:=4;
The SET STEP INSTRUCTION command makes /INSTRUCTION the default
STEP command qualifier. This is confirmed by the SHOW STEP
command. The STEP command executes the next instruction. After
the STEP command has completed, execution is suspended at the
first instruction (MOVL) of line 26 in module SUB1.
Multiprocess Programs
If you are using the multiprocess debugging configuration to
debug a multiprocess program (when the DBG$PROCESS logical name
is defined as MULTIPROCESS), note the following additional
points:
o The STEP command executes in the context of the visible
process, but images in any other unheld processes (processes
that have not been put on hold with a SET PROCESS/HOLD
command) are also allowed to execute.
o If you use the DO command to broadcast a STEP command to one
or more processes, the STEP command executes in the context
of each specified unheld process, but images in any other
unheld processes are also allowed to execute. In all cases,
a hold condition in the visible process is ignored.
o Once execution is started, the way in which it continues
depends on whether the SET MODE NOINTERRUPT is in effect. By
default (SET MODE INTERRUPT), execution continues until it is
suspended in any process. At that point, execution is
interrupted in any other processes that were executing
images, and the debugger prompts for input.
Parameters
number
(Optional.) A decimal integer specifying the number of step
units (lines, instructions, and so on) to be executed. The
default is 1.
Qualifiers
STEP command qualifiers determine the exact stepping behavior.
The following qualifiers affect the location to which you step:
/BRANCH /CALL
/EXCEPTION /INSTRUCTION[=(opcode-list)]
/LINE /RETURN
/VECTOR_INSTRUCTION
The following qualifiers affect what output is seen upon
completion of a step:
/[NO]SILENT /[NO]SOURCE
The following qualifiers affect what happens at a routine call:
/INTO /[NO]JSB /OVER
/[NO]SHARE /[NO]SYSTEM
Additional information available:
/BRANCH/CALL/EXCEPTION/INSTRUCTION/INTO
/JSB/LINE/NOJSB/NOSHARE/NOSILENT/NOSOURCE
/NOSYSTEM/OVER/RETURN/SHARE/SILENT/SOURCE
/SYSTEM/VECTOR_INSTRUCTION
/BRANCH
Executes the program to the next branch instruction. Same as
SET BREAK/TEMPORARY/BRANCH;GO.
/CALL
Executes the program to the next call or RET instruction. Same
as SET BREAK/TEMPORARY/CALL;GO.
/EXCEPTION
Executes the program to the next exception condition, if any.
Same as SET BREAK/TEMPORARY/EXCEPTION;GO.
If no exception condition occurs, STEP/EXCEPTION is the same as
GO.
/INSTRUCTION
/INSTRUCTION[=(opcode[,....)]]
Executes the program to the next instruction. Same as SET
BREAK/TEMPORARY/INSTRUCTION;GO.
If you specify one or more opcodes, executes the program to the
next instruction whose opcode you specify in the list. Same as
SET BREAK/TEMPORARY/INSTRUCTION=(opcode[,...]);GO.
If you specify a vector instruction, do not include an
instruction qualifier (/U, /V, /M, /0, or /1) with the
instruction mnemonic.
/INTO
If execution is currently suspended at a routine call, executes
the program up to the start of that routine (steps into that
routine). Otherwise, same as STEP without a qualifier.
/INTO is the opposite of /OVER (which is the default). To alter
the STEP/INTO behavior, use the /[NO]JSB, /[NO]SHARE, and
/[NO]SYSTEM qualifiers.
/JSB
(Default except for DIBOL.) Used with /INTO to override a
previous SET STEP NOJSB command. Steps into routines that are
called by a JSB instruction, as well as into routines that are
called by a CALL instruction.
/LINE
(Default.) Executes the program to the next line of source
code. (The debugger skips over any source lines that do not
result in executable code when compiled, such as comment lines.)
Same as SET BREAK/TEMPORARY/LINE;GO
/NOJSB
Used with /INTO. If execution is currently suspended at a
routine call and the routine is called by a JSB instruction,
same as STEP/OVER. Otherwise, same as STEP/INTO.
/NOJSB is the default for DIBOL. In DIBOL, user-written
routines are called by the CALL instruction and DIBOL run-time
library routines are called by the JSB instruction.
/NOSHARE
Used with /INTO. If execution is currently suspended at a call
to a shareable image routine, same as STEP/OVER. Otherwise,
same as STEP/INTO.
/NOSILENT
(Default.) Displays the "stepped to..." message after the STEP
has completed.
/NOSOURCE
Supresses the display of the source line for the current
location after the STEP has completed. The default is /SOURCE.
See also SET STEP [NO]SOURCE.
/NOSYSTEM
Use with /INTO. If execution is currently suspended at a call
to a system routine (in P1 space), same as STEP/OVER.
Otherwise, same as STEP/INTO.
/OVER
(Default.) If execution is currently suspended at a routine
call, executes the routine up to and including the routine's RET
instruction (steps over that routine). Opposite of /INTO.
/RETURN
/RETURN [n]
Executes the routine in which execution is currently suspended
up to its RET instruction (that is, up to the point just prior
to transferring control back to the calling routine). This lets
you inspect the local environment (for example, to get the
values of local variables) before the RET instruction deletes
the routine's call frame from the call stack. Same as SET
BREAK/TEMPORARY/RETURN;GO.
Optionally, you can specify a number to execute the program up n
levels of the call stack.
/SHARE
(Default.) Overrides a previous SET STEP NOSHARE command, thus
letting STEP/INTO command step into shareable image routines as
well as into other kinds of routines.
/SILENT
Supresses the "stepped to..." message and the display of source
line for the current location after the STEP has completed.
/SILENT overrides /SOURCE. The default is /NOSILENT.
/SOURCE
(Default.) Displays the source line for the current location
after the STEP has completed. See also SET STEP [NO]SOURCE.
/SYSTEM
(Default.) Overrides a previous SET STEP NOSYSTEM command, thus
letting STEP/INTO step into system routines (in P1 space) as
well as into other kinds of routines.
/VECTOR_INSTRUCTION
(Applies only to to vectorized programs.) Executes the program
to the next vector instruction. Same as SET
BREAK/TEMPORARY/VECTOR_INSTRUCTION;GO.
SYMBOLIZE
Converts a virtual address to a symbolic representation.
Format:
SYMBOLIZE address-expression[,...]
If the given address is a static address, the address is
symbolized as the nearest preceding symbol name plus an offset.
If it is also a code address, a line number is included in the
symbolization if a line number can be found that covers the
address. If the address is a register name, the debugger
displays symbols in all SET modules that are bound to that
register. If the address is a stack address, the debugger tries
to symbolize to a variable in the routine whose call frame
contains that address.
The debugger does symbolization automatically on EXAMINE
commands, so SYMBOLIZE now has limited usefulness.
Additional information available:
Examples
DBG> EVALUATE/ADDR X
400
DBG> SYMBOLIZE 400
address 400:
FOO\X
DBG> EXAMINE 400
FOO\X: 3
DBG> SYMBOLIZE R0
address %R0:
FOO\Y
FOO\Z
Parameters
address-expression
Any address expression that is valid in the currently set
language.
SYNCHRONIZE
Additional information available:
VECTOR_MODE
(Applies only to applies to vectorized programs.) Forces
immediate synchronization between the scalar and vector
processors.
Format:
SYNCHRONIZE VECTOR_MODE
Additional information available:
Description
The SYNCHRONIZE VECTOR_MODE command forces immediate
synchronization between the scalar and vector processors by
issuing a SYNC and an MSYNC instruction. The effects are as
follows:
o Any exception that was caused by a vector instruction and was
still pending delivery is immediately delivered. Note that
forcing the delivery of a pending exception triggers an
exception breakpoint or tracepoint (if one was set) or
invokes an exception handler (if one is available at that
location in the program).
o Any read or write operation between vector registers and
either the general registers or memory is completed
immediately-that is, any vector memory instruction that was
still being executed completes execution.
Entering the SYNCHRONIZE VECTOR_MODE command is equivalent to
issuing SYNC and MSYNC instructions at the location in the
program where execution is suspended.
By default, the debugger does not force synchronization between
the scalar and vector processors during program execution. To
force such synchronization, use the SET VECTOR_MODE SYNCHRONIZED
command.
Examples
1. DBG> SYNCHRONIZE VECTOR_MODE
%DEBUG-I-SYNCREPCOM, Synchronize reporting complete
Forces immediate synchronization between the scalar and vector
processors. In this example, the diagnostic message indicates
that the synchronization operation has completed and that all
pending vector exceptions have been delivered and reported.
2. DBG> STEP [1]
stepped to .MAIN.\SUB\%LINE 99
99: VVDIVD V1,V0,V2
DBG> STEP [2]
stepped to .MAIN.\SUB\%LINE 100
100: CLRL R0
DBG> EXAMINE/FLOAT %V2 [3]
0\%V2
[0]: 13.53400
[1]: Reserved operand, encoded as floating divide by zero
[2]: 247.2450
...
DBG> SYNCHRONIZE VECTOR_MODE [4]
%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002,
mask=00000004, PC=000002E1, PSL=03C00010
break on unhandled exception preceding .MAIN.\SUB\%LINE 100
100: CLRL R0
The comments that follow refer to the callouts in the preceding
example.
[1] This STEP command suspends program execution on line 99,
just before a VVDIVD instruction is executed. In this
exampsle, assume that the instruction will trigger a
floating-point divide-by-zero exception.
[2] This STEP command executes the VVDIVD instruction. Note,
however, that the exception is not delivered at this point
in the execution of the program.
[3] The EXAMINE/FLOAT command displays a decoded exception
message in element 1 of the destination register, V2. This
confirms that a floating-point divide-by-zero exception was
triggered and is pending delivery.
[4] The SYNCHRONIZE VECTOR_MODE command forces the immediate
delivery of the pending vector exception.
TYPE
Displays source code corresponding to the specified line number
or specified line number range.
Format:
TYPE [[module-name\]line-number[:line-number]...]
In noscreen mode, TYPE writes the source code to the terminal.
In screen mode, with a source window displayed, TYPE puts the
source window around the specified line.
Additional information available:
Example
DBG> TYPE 1
module FORARRAY
1: PROGRAM FORARRAY
DBG> TYPE
module FORARRAY
2: C
DBG> TYPE 1:5
module FORARRAY
1: PROGRAM FORARRAY
2: C
3: C This test program is used to test
4: C FORTRAN array references in the Debugger.
5: C It allows testing of straight array references,
Parameters
line-number
(Optional.) The listing line number for the source line. You
can specify a single line, a list of lines, or a range of lines.
If you do not specify a line number, the debugger displays the
next line after the one it last displayed.
module-name
(Optional.) The module whose source you want displayed. If you
omit the module name, the debugger determines the module from
the current scope.
WHILE
Provides a way of iteratively executing debugger commands.
Format:
WHILE lang-exp DO (debug-cmd-list)
As long as the language expression given as the WHILE clause is
true, the debugger command list given in the DO clause is
executed.
For example, to repeatedly STEP until the variable X is not
equal to zero:
DBG> WHILE (X .EQ. 0) DO (STEP/SILENT/INTO)
Additional information available:
Parameters
lang-exp
Any expression in the currently set language which evaluates to
TRUE or FALSE.
debug-cmd-list
A single debugger command or a sequence of debugger commands
separated by semicolons (;).