1 DEBUG
The Debugger Command Dictionary contains detailed reference
information about all debugger commands, organized as follows:
o Command Format explains how to enter debugger commands.
o Commands Disabled in DECwindows lists commands that are
disabled in the command/message view of the debugger's Compaq
DECwindows Motif for OpenVMS user interface.
o Messages gives general information about debugger diagnostic
messages. The Debugger Command Dictionary contains detailed
reference information about the debugger commands.
2 New_Features
For more information, see the OpenVMS Debugger Manual.
This section describes the following new OpenVMS Debugger
features:
o New commands for examining process dumps
o Multiprocess debugging
o New /VARIANT qualifier to the EXAMINE command
3 New_Process_Dump_Tools_(Alpha_only)
The OpenVMS Version 7.3 debugger contains new comands for
processing dump files. Note that these new-style process dump
and process dump analysis tools are not compatible with the old-
style process dumps. That is, if you have a problem you want to
analyze with the new tools, you must generate a new process dump
using the new process dump image.
The following subtopics describe the new tools.
4 Debugger_ANALYZE_PROCESS_DUMP_Command
The debugger has a new command:
ANALYZE/PROCESS_DUMP/IMAGE_PATH[=directory-spec] dumpfile.
This command is available only in the kept debugger. The kept
debugger is the image you invoke with the command DEBUG/KEEP,
which allows you to run and rerun programs from the same
debugging session.
The qualifier /PROCESS_DUMP is required, and distinguishes this
command from the one that invokes the System Dump Debugger (SDD),
ANALYZE/CRASH_DUMP.
For more information, see the OpenVMS Debugger Manual
4 Debugger_SDA_Command
The new debugger SDA command invokes the System Dump Analyzer
(SDA) from within the OpenVMS debugger. You can then use SDA for
additional process dump analysis. For example:
DBG> SDA
OpenVMS (TM) Alpha process dump analyzer
SDA> ..
.
.
SDA> EXIT
DBG>
This allows you to use SDA for additional analysis of a system
dump without terminating a debugger session.
For more information, see the OpenVMS Debugger Manual
3 Multiprocess_Debugging_Enhanced
For Version 7.3, debugger support for multiprocess programs has
been extensively overhauled. Bugs have been fixed and the user-
interface has been improved.
The multiprocess debugging enhancements include the following
features:
o Greater control over individual process and groups of
processes, including:
Execution of processes (or groups of processes)
Suspension of processes (or groups of processes)
Exiting processes (or groups of processes), with or without
exit handler execution
o Ability to create user-defined groups of processes
o Simpler to start a multiprocess debugging session; the default
configuration of the kept debugger is for a multiprocess
session
o Applications that use $HIBER WAIT (LIB$WAIT, $SCHDWH, and so
on) can now be debugged using normal debugger configurations
These enhancements make it much easier to debug multiprocess
programs.
For more detailed information, refer to the OpenVMS Debugger
Manual.
3 EXAMINE/VARIANT_Command
The EXAMINE command has a new /VARIANT qualifier that enables
the debugger to display the correct item when it encounters an
anonymous variant.
In a C program, a union contains members, only one of which is
valid at any one time. When displaying a union, the debugger does
not know which member is currently valid. In a PASCAL program,
a record with a variant part contains variants, only one of
which is valid at any one time. When displaying a record with an
anonymous variant part, the debugger does not know which variant
is currently valid, and displays all variants by default.
You can use the /VARIANT qualifier to select which member of
a union (C program) or anonymous variant (PASCAL program) to
display. The format is as follows:
DBG> EXAMINE /VARIANT=var-selector address-exp
DBG> EXAMINE /VARIANT=(var-selector,...) address-exp
The variant selector var-selector specifies a name, a
discriminant (PASCAL only), or a position; that is, one of the
following:
o NAME = name-string
o DISCRIMINANT = expression
o POSITION = expression
For more information, see the EXAMINE topic.
2 Address_Expressions
Several debugger commands require that you specify an address
expression. An address expression is an entity that denotes a
memory address or a register. Commands for which you specify
address expressions are:
(SET,ACTIVATE,DEACTIVATE,CANCEL) BREAK
(SET,ACTIVATE,DEACTIVATE,CANCEL) TRACE
(SET,ACTIVATE,DEACTIVATE,CANCEL) WATCH
EVALUATE/ADDRESS
EXAMINE
DEPOSIT (at the left of the equal sign)
In general, you can specify address expressions using the syntax
of the currently set language. For example:
DBG> EXAMINE A(1) ! FORTRAN
DBG> SET WATCH A[1] ! Pascal
DBG> EXAMINE C OF R ! COBOL
In addition, you can specify address expressions numerically, and
you can also use the built-in symbols %LINE and %LABEL to refer
to code locations:
DBG> EXAMINE 512
DBG> SET BREAK %LINE 10
You can also use the following operators to specify addresses
that you might not be able to access by name (nonsymbolic
addresses):
+ - * Arithmetic operators
/
@ or . Indirection
<p,s> Select bit field
For example, examine the instruction 3 bytes after line 10:
DBG> EXAMINE %LINE 10 + 3
Examine the location pointed to by P:
DBG> EXAMINE @P
Do not confuse an address expression with a language expression,
which denotes a value rather than a program location. The
following examples show how the same command parameter is treated
either as an address expression or as a language expression
depending on the command:
Show the address of the variable X (address expression):
DBG> EVALUATE/ADDR X
512
Show the current value of X (address expression):
DBG> EXAMINE X
X: 0
Evaluate X (language expression):
DBG> EVALUATE X
0
Evaluate X+1 (language expression):
DBG> EVALUATE X+1
1
Show value at location X plus 1 byte (address expression):
DBG> EXAMINE X+1
513: 0
3 Using_Symbols_and_Operators_in_Address_Expressions
The symbols and operators that can be used in address expressions
are listed below. A unary operator has one operand. A binary
operator has two operands.
Symbol Description
%LABEL Specifies that the numeric literal that follows
is a program label (for languages like FORTRAN
that have numeric program labels). You can
qualify the label with a path-name prefix that
specifies the containing module.
%LINE Specifies that the numeric literal that follows
is a line number in your program. You can
qualify the line number with a path-name prefix
that specifies the containing module.
Backslash (\) When used within a path name, delimits each
element of the path name. In this context, the
backslash cannot be the leftmost element of the
complete path name.
When used as the prefix to a symbol, specifies
that the symbol is to be interpreted as a global
symbol. In this context, the backslash must be
the leftmost element of the symbol's complete
path name.
At sign (@) Unary operators. In an address expression, the
Period (.) at sign (@) and period (.) each function as
a "contents-of" operator. The "contents-of"
operator causes its operand to be interpreted as
a memory address and thus requests the contents
of (or value residing at) that address.
Bit field Unary operator. You can apply bit field
<p,s,e> selection to an address-expression. To select
a bit field, you supply a bit offset (p), a
bit length (s), and a sign extension bit (e),
which is optional.
Plus sign (+) Unary or binary operator. As a unary operator,
indicates the unchanged value of its operand.
As a binary operator, adds the preceding operand
and succeeding operand together.
Minus sign (-) Unary or binary operator. As a unary operator,
indicates the negation of the value of its
operand. As a binary operator, subtracts the
succeeding operand from the preceding operand.
Multiplication Binary operator. Multiplies the preceding
sign (*) operand by the succeeding operand.
Division sign Binary operator. Divides the preceding operand
(/) by the succeeding operand.
The examples in the additional topics illustrate the use of
built-in symbols and operators in address expressions.
4 %LINE_and_%LABEL_Operators
The following command sets a tracepoint at line 26 of the module
in which execution is currently suspended:
DBG> SET TRACE %LINE 26
The next command displays the source line associated with line
47:
DBG> EXAMINE/SOURCE %LINE 47
module MAIN
47: procedure SWAP(X,Y: in out INTEGER) is
DBG>
The next command sets a breakpoint at label 10 of module MOD4:
DBG> SET BREAK MOD4\%LABEL 10
4 Path-Name_Operators
The following command displays the value of the variable COUNT
that is declared in routine ROUT2 of module MOD4. The backslash
(\) path-name delimiter separates the path-name elements:
DBG> EXAMINE MOD4\ROUT2\COUNT
MOD4\ROUT2\COUNT: 12
DBG>
The following command sets a breakpoint on line 26 of the module
QUEUMAN:
DBG> SET BREAK QUEUMAN\%LINE 26
The following command displays the value of the global symbol X:
DBG> EXAMINE \X
4 Arithmetic_Operators
The order in which the debugger evaluates the elements of an
address expression is similar to that used by most programming
languages. The order is determined by the following three
factors, listed in decreasing order of precedence (first listed
have higher precedence):
1. The use of delimiters (usually parentheses or brackets) to
group operands with particular operators
2. The assignment of relative priority to each operator
3. Left-to-right priority of operators
The debugger operators are listed in decreasing order of
precedence as follows:
1. Unary operators ((.), (@), (+), (-))
2. Multiplication and division operators ((*), (/))
3. Addition and subtraction operators ((+), (-))
For example, when evaluating the following expression, the
debugger first adds the operands within parentheses, then divides
the result by 4, then subtracts the result from 5.
5--(T+5)/4
The following command displays the value contained in the memory
location X + 4 bytes:
DBG> EXAMINE X + 4
4 Contents-of_Operator
The following examples illustrate use of the contents-of
operator. In the next example, the instruction at the current
PC value is obtained (the instruction whose address is contained
in the PC and which is about to execute):
DBG> EXAMINE .%PC
MOD\%LINE 5: PUSHL S^#8
DBG>
In the next example, the source line at the PC value one level
down the call stack is obtained (at the call to routine SWAP):
DBG> EXAMINE/SOURCE .1\%PC
module MAIN
MAIN\%LINE 134: SWAP(X,Y);
DBG>
For the next example, assume that the value of pointer variable
PTR is 7FF00000 hexadecimal, the address of an entity that you
want to examine. Assume further that the value of this entity is
3FF00000 hexadecimal. The following command shows how to examine
the entity:
DBG> EXAMINE/LONG .PTR
7FF00000: 3FF00000
DBG>
In the next example, the contents-of operator (at sign or
period) is used with the current location operator (period) to
examine a linked list of three quadword-integer pointer variables
(identified as L1, L2, and L3 in the illustration that follows).
P is a pointer to the start of the list. The low longword of each
pointer variable contains the address of the next variable; the
high longword of each variable contains its integer value (8, 6,
and 12, respectively).
+------+
P: | 9B40 |--+ L1 L2 L3
+------+ | +------+ +------+ +------+
+-->| 9BDA |--->| 9BF4 |--->| 0000 |
|------| |------| |------|
| 8 | | 6 | | 12 |
+------+ +------+ +------+
DBG> SET TYPE QUADWORD; SET RADIX HEX
DBG> EXAMINE .P ! Examine the entity whose address
! is contained in P.
00009BC2: 00000008 00009BDA ! High word has value 8, low word
! has address of next entity (9BDA).
DBG> EXAMINE @. ! Examine the entity whose address
! is contained in the current entity.
00009BDA: 00000006 00009BF4 ! High word has value 6, low word
! has address of next entity (9BF4).
DBG> EXAMINE .. ! Examine the entity whose address
! is contained in the current entity.
00009BF4: 0000000C 00000000 ! High word has value 12 (dec.), low word
! has address 0 (end of list).
4 Bit-Field_Operator
The following example shows how to use the bit-field operator.
For example, to examine the address expression X_NAME starting
at bit 3 with a length of 4 bits and no sign extension, you would
enter the following command:
DBG> EXAMINE X_NAME <3,4,0>
2 Built_in_Symbols
The debugger built-in symbols provide options for specifying
program entities and values in debugger commands, as follows:
Function Symbols
Specify %Rn, %R31, %AP, %FP, %SP, %PC, %PSL, %Vn, %VCR,
Alpha %VLR, %VMR, %Fn, %F31
and VAX
registers
%LANGUAGE Specify the current language
%NAME Construct identifiers
%PARCNT Count parameters passed in command procedures
%BIN, %DEC, Control radix
%HEX, %OCT
%CURLOC, Specify consecutive program locations and the
%NEXTLOC, current value of an entity
%PREVLOC,
%CURVAL
%LABEL, Specify numeric labels and line numbers
%LINE
%ADDR, Specify the argument passing mechanism for the
%DESCR, CALL command
%REF, %VAL
Specify %ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_
processes, NUM, %EXC_SEVERITY, %PROCESS_NAME, %PROCESS_PID,
tasks, or %PROCESS_NUMBER, %NEXT_PROCESS, %PREVIOUS_PROCESS,
information %VISIBLE_PROCESS, %ACTIVE_TASK, %CALLER_TASK,
about %NEXT_TASK, %TASK. %VISIBLE_TASK
exceptions
Specify %PAGE, %WIDTH, %DECWINDOWS, %CURDISP, %CURSCROLL,
information %NEXTDISP, %NEXTINST, %NEXTOUTPUT, %NEXTSCROLL,
about the %NEXTSOURCE, %SOURCE_SCOPE, %INST_SCOPE, %CURRENT_
interface SCOPE_ENTRY, %NEXT_SCOPE_ENTRY, %PREVIOUS_SCOPE_
ENTRY
3 %Rn
On VAX systems, specifies the VAX general purpose registers
%R0 through %R11. On Alpha systems, specifies the Alpha integer
registers %R0 through %R28.
Example:
DBG> DEPOSIT %R1 = 23
3 %AP
On VAX systems, specifies the VAX argument pointer register
(%R12).
3 %FP
On VAX systems, specifies the VAX frame pointer register (%R13).
On Alpha systems, specifies the Alpha stack frame base register
(%R29).
3 %SP
On VAX systems, specifies the VAX stack pointer register (%R14).
On Alpha systems, specifies the Alpha stack pointer register
(%R30).
3 %PC
Specifies the VAX or Alpha program counter register. The PC
contains the address of the next instruction to be executed by
the processor.
VAX Examples:
DBG> EXAMINE %PC ! Display the value in the PC
MOD3\%PC: 1554 ! address of next instruction to execute
DBG> EXAMINE %PC ! Display the value at the address in the PC
MOD3\%LINE 12: MOVL B^12(R11),R1
! next instruction to execute
3 %PSL
On VAX systems, specifies the VAX processor status longword.
3 %Vn
On VAX systems, specifies the VAX vector registers %V0 through
%V15.
3 %VCR
On VAX systems, specifies the VAX vector count register (%VCR).
The VCR specifies the length of the offset vector generated by
the IOTA instruction.
3 %VLR
On VAX systems, specifies the VAX vector length register (%VLR).
The VLR limits the highest element of a vector register that is
processed by a vector instruction.
3 %VMR
On VAX systems, specifies the VAX vector mask register (%VMR).
The VMR specifies a mask (a bit pattern) that a vector
instruction uses in order to operate on only certain elements
of a vector register operand.
3 %R31
On Alpha systems, specifies the ReadAsZero/Sink register. This
register is permanently assigned the value zero.
3 %PS
On Alpha systems, specifies the Alpha processor status register.
3 %Fn
On Alpha systems, specifies the Alpha floating-point registers
%F0 through %F30.
3 %F31
On Alpha systems, specifies the ReadAsZero/Sink floating-point
register. This register is permanently assigned the value zero.
3 %LANGUAGE
Specifies the current language. The current language is the
language last established with the SET LANGUAGE command. BY
default, if you did not enter a SET LANGUAGE command, the current
language is the language of the module containing the main
program (image transfer address).
Example:
DBG> EVALUATE %LANGUAGE
'FORTRAN'
DBG> SET LANGUAGE ADA
DBG> EVALUATE %LANGUAGE
"ADA"
3 %NAME
Enables you to constuct identifiers that are not ordinarily legal
in the current language.
Format:
%NAME id-char-string
%NAME 'any-char-string'
Examples:
DBG> EXAMINE %NAME 12 ! Examine variable nameD '12'
DBG> EXAMINE %NAME 'P.AAA' ! Examine generated label P.AAA
3 %PARCNT
Specifies the number of actual parameters to the current command
procedure. Use %PARCNT in command procedures that can take a
variable number of actual parameters. You can use %PARCNT only
inside command procedures; it is not defined when commands are
entered from the terminal.
For example, suppose the command procedure ABC is executed with
the command @ABC 111,222,333. Inside ABC, %PARCNT then has the
value 3 because there are three parameters on this particular
call to ABC.
Example:
EVALUATE %PARCNT
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
3 %BIN
Specifies that a following numeric literal (or all numeric
literals in a following parenthesized expression) be interpreted
in binary radix.
Examples:
DBG> EVALUATE/DEC %BIN 10
2
DBG> EVALUATE/DEC %BIN (10 + 10)
4
3 %DEC
Specifies that a following numeric literal (or all numeric
literals in a following parenthesized expression) be interpreted
in decimal radix.
Examples:
DBG> EVALUATE/HEX %DEC 10
0A
DBG> EVALUATE/HEX %DEC (10 + 10)
14
3 %HEX
Specifies that a following numeric literal (or all numeric
literals in a following parenthesized expression) be interpreted
in hexadecimal radix.
Examples:
DBG> EVALUATE/HEX %DEC 10
16
DBG> EVALUATE/DEC %HEX (10 + 10)
32
3 %OCT
Specifies that a following numeric literal (or all numeric
literals in a following parenthesized expression) be interpreted
in octal radix.
Examples:
DBG> EVALUATE/DEC %OCT 10
8
DBG> EVALUATE/DEC %OCT (10 + 10)
16
3 %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 character
(.) for this purpose.
Example:
DBG> EXAMINE RADIUS
CIRCLE\RADIUS: 0.0000000E+00
DBG> DEPOSIT %CURLOC = 1 ! Set RADIUS to 1
DBG> DEPOSIT . = 2 ! Set RADIUS to 2
3 %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 equivalent to EXAMINE
%NEXTLOC.
Example:
DBG> EXAMINE PRIMES(4)
SIEVE\PRIMES(4): 7
DBG> EXAMINE %NEXTLOC
SIEVE\PRIMES(5): 11
DBG> EXAMINE ! Equivalent to EXAMINE %NEXTLOC
SIEVE\PRIMES(6): 13
3 %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 character (^) for this purpose.
Examples:
DBG> EXAMINE PRIMES(6)
SIEVE\PRIMES(6): 13
DBG> EXAMINE %PREVLOC
SIEVE\PRIMES(5): 11
DBG> EXAMINE ^ ! Equivalent to EXAMINE %PREVLOC
SIEVE\PRIMES(4): 7
3 %CURVAL
Specifies the value last displayed by an EVALUATE or EXAMINE
command, or deposited by a DEPOSIT command. You can also use the
backslash character (\) for this purpose. These two symbols are
not affected by an EVALUATE/ADDRESS command.
Example:
DBG> EXAMINE RADIUS
CIRCLE\RADIUS: 0.0000000E+00
DBG> EVALUATE %CURVAL
0.0000000E+00
3 %LABEL
%LABEL n is the debugger syntax for referring to label n in your
program. This is intended for languages like FORTRAN which 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\n is no longer accepted.
3 %LINE
%LINE n is the debugger syntax for referring to line n 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\n is no longer accepted.
3 %PAGE
Specifies the current height of the screen, in lines, as used by
the debbuger.
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 -
_DBG> (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
3 %WIDTH
Specifies the current width of the screen, in columns, as used by
the debugger.
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 -
_DBG> (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
3 %DECWINDOWS
Enables you to determine whether you are using the debugger's
command interface or Compaq DECwindows Motif for OpenVMS user
interface. With the Compaq DECwindows Motif for OpenVMS user
interface, the value of %DECWINDOWS is 1 (TRUE). With the command
interface, the value is 0 (FALSE). For 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 Motif (workstation) syntax:
(DISPLAY SRC AT (100,300,100,700))
ELSE
! Screen-mode (terminal) syntax:
(DISPLAY SRC AT (AT H1))
3 %ADDR
(Default) Used with the CALL command to specify the argument
passing mechanism. The %ADDR symbol specifies that the argument
is passed by address. See the CALL command.
3 %DESCR
Used with the CALL command to specify the argument passing
mechanism. The %DESCR symbol specifies that the argument is
passed by descriptor. See the CALL command.
3 %REF
Used with the CALL command to specify the argument passing
mechanism. The %REF symbol specifies that the argument is passed
by reference. See the CALL command.
3 %VAL
Used with the CALL command to specify the argument passing
mechanism. The %VAL symbol specifies that the argument is passed
by value. See the CALL command.
3 %CURDISP
Specifies the current display (screen mode). This is the display
most recently referenced with a DISPLAY command (that is, the
least occluded display.)
Example:
DBG> SELECT/SCROLL %CURDISP
3 %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 keypad keys (KP2, KP4, KP6, and KP8).
Example:
DBG> EXPAND/DOWN:5 %CURSCROLL
3 %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
3 %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
3 %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
3 %NEXTSCROLL
Specifies the next display after the current scrolling display in
the screen-mode display list.
Example:
DBG> SELECT/SCROLL %NEXTSCROLL
3 %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
3 %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.
The %SOURCE_SCOPE symbol is used in the definition of the
predefined screen-mode source display SRC:
DBG> DISPLAY SRC AT H1 SOURCE -
_DBG> (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC)
3 %INST_SCOPE
Specifies the scope, relative to the call stack, for which
decoded instructions are displayed in a screen-mode instruction
display.
The %INST_SCOPE symbol is used in the definition of the
predefined screen-mode instruction display INST:
DBG> DISPLAY INST AT H1 INSTRUCTION -
_DBG> (EXAMINE/INST .%INST_SCOPE\%PC)
3 %CURRENT_SCOPE_ENTRY
Specifies the call frame that the debugger is currently using as
reference when displaying source code or decoded instructions, or
when searching for symbols. By default, this is call frame 0.
The %CURRENT_SCOPE_ENTRY symbol 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.
3 %NEXT_SCOPE_ENTRY
Specifies the next frame down the call stack from the call frame
denoted by %CURRENT_SCOPE_ENTRY.
The %NEXT_SCOPE_ENTRY symbol 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.
3 %PREVIOUS_SCOPE_ENTRY
Specifies the next frame up the call stack from the call frame
denoted by %CURRENT_SCOPE_ENTRY.
The %PREVIOUS_SCOPE_ENTRY symbol 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.
3 %PROCESS_NAME
When specifying a process name in a debugger command string, you
can optionally precede the name with the symbol %PROCESS_NAME.
Example:
all> EXIT %PROCESS_NAME JONES_4
3 %PROCESS_PID
When specifying a process identifier (PID) in a debugger command
string, you must precede the PID with the symbol %PROCESS_PID.
Example:
all> CONNECT %PROCESS_PID 258001B6
3 %PROCESS_NUMBER
When specifying a debugger-assigned process number in a debugger
command string, you can precede the number with %PROCESS_NUMBER
(or the abbreviation %PROC).
Example:
all> SHOW PROCESS %PROC 3
3 %NEXT_PROCESS
Specifies the next process in the debugger's process list after
the visible process.
Example:
all> SET PROCESS %NEXT_PROCESS
3 %PREVIOUS_PROCESS
Specifies the previous process in the debugger's process list
before the visible process.
Example:
all> SHOW PROCESS/FULL %PREVIOUS_PROCESS
3 %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:
all> %VISIBLE_PROCESS,%NEXT_PROCESS > EXAMINE X
3 %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 operating system sense is
just "EXCEPTION," which is what %E returns. The Ada exception
name ("XXX") is returned by %ADAEXC_NAME.
Example:
DBG> SET BREAK/EXCEPTION WHEN -
_DBG> (%ADAEXC_NAME = "XXX")
3 %EXC_FACILITY
Gives you the facility of the current exception. This provides a
way of qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_FACILITY
"SYSTEM"
DBG> SET BREAK/EXCEPTION WHEN -
_DBG> (%EXC_FAC = "SYSTEM")
3 %EXC_NAME
Gives you the name of the current exception. This provides a way
of qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_NAME
"FLTDIV_F"
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NAME = "FLTDIV_F")
3 %EXC_NUM
Gives you 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/EXCEPTION WHEN (%EXC_NUM = 12)
3 %EXC_SEVERITY
Gives you the severity code of the current exception. This
provides a way of qualifying exception breaks.
Example:
DBG> EVALUATE %EXC_SEVERITY
"F"
DBG> SET BREAK/EXCEPTION WHEN (%EXC_SEV = "F")
3 %ACTIVE_TASK
(Applies only to tasking programs.) Gives you the currently
active task (the one that was running when the debugger last
took control). See the SET TASK/ACTIVE command.
Example:
DBG> EVALUATE %ACTIVE_TASK
%TASK 2
3 %CALLER_TASK
(Applies only to Ada tasking programs.) Gives you the task which
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.
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)
3 %NEXT_TASK
(Applies only to tasking programs.) Gives you the next task after
the one currently visible (%VISIBLE_TASK). "Next" in this context
is just an internal ordering that cycles through all the tasks.
This lets you set up command procedures that cycle through all
tasks.
Example:
DBG> WHILE %NEXT NEQ %ACTIVE DO -
_DBG> (SET TASK %NEXT; SHOW CALLS)
3 %TASK
(Applies only to tasking programs.)
%TASK n (where n is a positive decimal integer) 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. The task number n can be obtained using the SHOW
TASK/ALL command or by examining task objects.
Example:
DBG> EXAMINE T1
T1: %TASK 2
DBG> SET TASK %TASK 2
3 %VISIBLE_TASK
(Applies only to tasking programs.) Gives you the task that the
debugger is using to do symbol lookups. This 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.
This is normally the same as %ACTIVE_TASK but can be changed
using the SET TASK command.
Example:
DBG> SET TASK %TASK 2
DBG> EVALUATE %VISIBLE
%TASK 2
2 Client-Server_Interface
The OpenVMS Debugger has an optional client/server configuration
that allows you to access the debugger and its functions from a
PC or a workstation.
The debugger client/server retains the functionality of the
OpenVMS kept debugger, but splits the debugger into two
components, the debug server and the debug client. The interface
of the Compaq DECwindows Motif for OpenVMS debug client is
similar to the Motif interface of the standalone debugger.
The debug server runs on an OpenVMS system, similar to the kept
debugger without the user interface. The debug client contains
the user interface, and runs on an OpenVMS system using Compaq
DECwindows Motif for OpenVMS, or on a PC running Microsoft
Windows 95 or Microsoft Windows NT.
The following table shows the systems on which the debug client
and the debug server run:
Debug Debug
Client Server System
X X OpenVMS VAX
X X OpenVMS Alpha
X Microsoft Windows 95 Intel
X Microsoft Windows 98 Intel
X Microsoft Windows NT Alpha
X Microsoft Windows NT Intel
The OpenVMS client-server configuration allows the following:
o Remote access to OpenVMS Debug Servers from other OpenVMS
systems or from PCs running Windows 95 or Windows NT Version
3.51 or later
o Client access to multiple servers, each running on the same or
different OpenVMS nodes
o Multiple clients on different nodes to simultaneously connect
to the same server for teaching or team debugging
o Debugging of multi-tier client/server applications that are
distributed among several mixed-platform systems
3 Required_Software
The Compaq DECwindows Motif for OpenVMS debug client requires the
following system software:
OpenVMS Version 7.0 or later (VAX or Alpha)
Compaq DECwindows Motif for OpenVMS Version 1.2 or later
The debug server requires OpenVMS Version 7.0 or later running on
a VAX or Alpha node.
The OpenVMS debugger client/server configuration also requires
that the following be installed on the OpenVMS node running the
server and any nodes running the Compaq DECwindows Motif for
OpenVMS client:
o A TCP/IP stack
o DCE RPC
NOTE
If you are running TCP/IP Services for OpenVMS (UCX) Version
4.1, you must have ECO2 installed. You can also run a later
version of UCX.
The client and server communicate using DCE RPC over one of the
following transports:
TCP/IP
UDP
DECnet
3 Starting_the_Debug_Server
You can start the debug server after logging in directly to the
OpenVMS system. You can also log in remotely with a product such
as eXcursion, or a terminal emulator such as Telnet. Note that
you can run Telnet directly from the Microsoft Windows client.
To start the server on an OpenVMS node, enter the following
command:
$ DEBUG/SERVER
The server displays its network binding strings, which allow
Compaq DECwindows Motif for OpenVMS and Microsoft Windows clients
to specify this server for connection. For example:
$ DEBUG/SERVER
%DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: YES
%DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.138[1034]
%DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001]
%DEBUG-I-WATCH: Network Binding: ncadg_ip_udp:16.32.16.138[1045]
%DEBUG-I-AWAIT: Ready for client connection...
To connect to the server, you must know the nodename of the
node running the server, and the port number. The port number is
displayed in the square brackets of the network binding string.
The following table matches the network binding string prefix
with its associated network transport:
Network
Transport NetworK Binding String Prefix
TCP/IP ncacn_ip_tcp
DECnet ncacn_dnet_nsp:
UDP ncadg_ip_udp
NOTE
You must hold the DBG$ENABLE_SERVER identifier in the rights
database to be able to run the debug server. Exercise care
when using the debug server. Once a debug server is running,
anyone on the network has the ability to connect to the
debug server.
Before granting the DBG$ENABLE_SERVER identifier, the system
manager must create it by entering the command DEBUG/SERVER
from an account with write access to the rights database. The
system manager needs to do this only once. The system manager
can then run the Authorize utility to grant the DBG$ENABLE_SERVER
identifier to the user's account in the rights database.
3 Starting_the_Motif_Debug_Client
Once the debug server is running, start the Motif debug client.
To do so, enter the following command:
$
DEBUG/CLIENT
The debugger displays the Server Connection dialog.
From the Server Connection dialog, you can
o Select a session for connection
o Select a network transport protocol
o Specify the number of secondary clients allowed
o Connect to a selected server to begin and activate a new
session or reactivate an existing session
o Disconnect from a session
o Test whether a server is available
o Stop the server
o Cancel a connection operation and dismiss the dialog
NOTE
Messages and program output appear by default in the window
in which you start the server. You can redirect program
output to another window as required.
3 Primary_Clients_and_Secondary_Clients
The primary client is the first client to connect to the server.
A secondary client is an additional client that has connected to
the same server. The primary client controls whether or not any
secondary clients can connect to the server through the Server
Options dialog. Click Options on the Server Connection dialog to
display the Server Options dialog.
3 Establishing_a_Server_Session
A session is the connection between a particular client and a
particular server. Each session is identified within the client
by the network binding string the client used to connect to the
server.
When you start the client, the debugger displays the Server
Connection dialog, to let you specify the server, the network
transport protocol, and the number of secondary clients allowed.
In the Server Connection dialog the Connection [local]: dialog
bar contains the default network binding string. This string is
based on the last string you entered, or the node on which the
client is running. There is not necessarily a server associated
with the default binding string.
To specify the server, you can accept the default, or you can
enter the node name of the OpenVMS node running the debug server
and the port number. For example:
NODNAM[1234]
To specify the network transport protocol and the number of
secondary clients allowed, perform the following steps:
1. Click Options to display the Server Options dialog.
2. In the Server Options dialog, click on the network transport:
TCP/IP, DECnet, or UDP.
3. In the Server Options dialog, enter the number of secondary
clients (0-30) to be allowed.
4. Click OK to dismiss the Server Options dialog.
Click Connect to connect the client to the server.
3 Switching_Between_Sessions
Each time you connect to a server and initiate a session, the
session is listed in the Active Sessions dialog bar in the
Server Connection dialog. You can switch back and forth between
sessions. Each time you switch to a new session, the debugger
updates the contents of any open debugger displays with the new
context.
To switch to a different session, perform the following steps:
1. Open the File menu.
2. Click Server Connection.
3. Click the Active Sessions dialog bar to display the list of
active sessions.
4. Double click the required session in the Active Sessions list.
This selects the session as the current session, dismisses the
Server Connection dialog, and updates the debugger displays
with the current context.
Note that you cannot change the number of secondary clients
allowed on a session while that session is active. To change the
number of clients allowed on a session, you must be the primary
client, and perform the following steps:
1. Open the File menu.
2. Specify the network binding string of the session.
3. Click Disconnect.
4. Click Options.
5. In the Server Options dialog, click on the network transport:
TCP/IP, DECnet, or UDP.
6. In the Server Options dialog, select the number of secondary
clients (0-31) to be allowed.
7. Click OK to dismiss the Server Options dialog.
8. In the Server Connection dialog, click Connect.
3 Closing_a_Client/Server_Session
Click on Exit Debug? from the File menu to invoke the Confirm
Exit dialog.
Once you have invoked the Confirm Exit dialog, perform one of the
following:
o To terminate both the client and the server (default) click
OK.
o To dismiss the Confirm Exit dialog without taking any action,
click Cancel.
o To terminate only the debug client, perform the following
steps:
o Click Exit Server.
o Click OK.
o To terminate only the debug server, perform the following
steps:
o Click Exit Client.
o Click OK.
If you do not terminate the debug server, you can connect to the
server from another debug client. If you do not terminate the
client, you can connect to another server for which you know the
network binding string.
2 Command_Format
You can enter debugger commands interactively at the keyboard or
store them within a command procedure to be executed later with
the execute procedure (@) command.
3 General_Rules
A command string is the complete specification of a debugger
command. Although you can continue a command on more than one
line, the term command string is used to define an entire command
that is passed to the debugger.
A debugger command string consists of a verb and, possibly,
parameters and qualifiers.
The verb specifies the command to be executed. Some debugger
command strings might consist of only a verb or a verb pair. For
example:
DBG> GO
DBG> SHOW IMAGE
A parameter specifies what the verb acts on (for example, a file
specification). A qualifier describes or modifies the action
taken by the verb. Some command strings might include one or more
parameters or qualifiers. In the following examples, COUNT, I,
J, and K, OUT2, and PROG4.COM are parameters (@ is the execute
procedure command); /SCROLL and /OUTPUT are qualifiers.
DBG> SET WATCH COUNT
DBG> EXAMINE I,J,K
DBG> SELECT/SCROLL/OUTPUT OUT2
DBG> @PROG4.COM
Some commands accept optional WHEN or DO clauses. DO clauses are
also used in some screen display definitions.
A WHEN clause consists of the keyword WHEN followed by a
conditional expression (within parentheses) that evaluates to
true or false in the current language. A DO clause consists
of the keyword DO followed by one or more command strings
(within parentheses) that are to be executed in the order that
they are listed. You must separate multiple command strings
with semicolons (;). These points are illustrated in the next
example.
The following command string sets a breakpoint on routine SWAP.
The breakpoint is triggered whenever the value of J equals 4
during execution. When the breakpoint is triggered, the debugger
executes the two commands SHOW CALLS and EXAMINE I,K, in the
order indicated.
DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K)
The debugger checks the syntax of the commands in a DO clause
when it executes the DO clause. You can nest commands within DO
clauses.
3 Interactive_Input_Rules
When entering a debugger command interactively at the keyboard,
you can abbreviate a keyword (verb, qualifier, parameter) to as
few characters as are needed to make it unique within the set of
all debugger keywords. However, some commonly used commands (for
example, EXAMINE, DEPOSIT, GO, STEP) can be abbreviated to their
first characters. Also, in some cases, the debugger interprets
nonunique abbreviations correctly on the basis of context.
Pressing the Return key terminates the current line, causing
the debugger to process it. To continue a long command string
on another line, type a hyphen (-) before pressing Return. As
a result, the debugger prompt is prefixed with an underscore
character (_DBG>), indicating that the command string is still
being accepted.
You can enter more than one command string on one line by
separating command strings with semicolons (;).
To enter a comment (explanatory text recorded in a debugger log
file but otherwise ignored by the debugger), precede the comment
text with an exclamation point (!). If the comment wraps to
another line, start that line with an exclamation point.
The command line editing functions that are available at the
DCL prompt ($) are also available at the debugger prompt (DBG>),
including command recall with the up arrow and down arrow keys.
For example, pressing the left arrow and right arrow keys moves
the cursor one character to the left and right, respectively;
pressing Ctrl/H or Ctrl/E moves the cursor to the start or
end of the line, respectively; pressing Ctrl/U deletes all the
characters to the left of the cursor, and so on.
To interrupt a command that is being processed by the debugger,
press Ctrl/C. See the Ctrl/C command.
3 Command_Procedure_Rules
To maximize legibility, it is best not to abbreviate command
keywords in a command procedure. Do not abbreviate command
keywords to less than four significant characters (not counting
the negation /NO . . . ), to avoid potential conflicts in future
releases.
Start a debugger command line at the left margin. (Do not start a
command line with a dollar sign ($) as you do when writing a DCL
command procedure.)
The beginning of a new line ends the previous command line (the
end-of-file character also ends the previous command line). To
continue a command string on another line, type a hyphen (-)
before starting the new line.
You can enter more than one command string on one line by
separating command strings with semicolons (;).
To enter a comment (explanatory text that does not affect the
execution of the command procedure), precede the comment text
with an exclamation point (!). If the comment wraps to another
line, start that line with an exclamation point.
2 Command_Summary
The additional topics list all the debugger commands and any
related DCL commands in functional groupings, along with brief
descriptions.
3 Starting_and_Ending_a_Debugging_Session
The commands listed below are used to start the debugger, bring a
program under debugger control, and interrupt and end a debugging
session. Except where otherwise specified, all commands are
debugger commands.
DEBUG/KEEP (DCL) Starts the debugger
RUN filespec Brings a program under debugger control
RERUN Reruns the program currently under
debugger control
RUN filespec (DCL) If the specified image was linked using
LINK/DEBUG, starts the debugger and
also brings the image under debugger
control. When you start the debugger in
this manner, you cannot then use the
debugger RUN or RERUN commands. You
can use the /[NO]DEBUG qualifiers with
the RUN command to control whether the
debugger is started when the program is
executed.
EXIT, Ctrl/Z Ends a debugging session, executing all
exit handlers
QUIT Ends a debugging session without
executing any exit handlers declared
in the program
Ctrl/C Aborts program execution or a debugger
command without interrupting the
debugging session
(SET,SHOW) ABORT_KEY (Assigns, identifies) the default
Ctrl/C abort function to another Ctrl-
key sequence, identifies the Ctrl-key
sequence currently defined for the abort
function
Ctrl/Y-DEBUG (DCL) Interrupts a program that is running
without debugger control and starts
the debugger; not supported in the Kept
Debugger configuration
ATTACH Passes control of your terminal from the
current process to another process
SPAWN Creates a subprocess, enabling you to
execute DCL commands without ending
a debugging session or losing your
debugging context
3 Controlling_and_Monitoring_Program_Execution
The following commands are used to control and monitor program
execution:
GO Starts or resumes program execution
STEP Executes the program up to the next line,
instruction, or specified instruction
(SET,SHOW) STEP (Establishes, displays) the default
qualifiers for the STEP command
(SET,SHOW,CANCEL) (Sets, displays, cancels) breakpoints
BREAK
(ACTIVATE,DEACTIVATE) (Activates, deactivates) previously set
BREAK breakpoints
(SET,SHOW,CANCEL) (Sets, displays, cancels) tracepoints
TRACE
(ACTIVATE,DEACTIVATE) (Activates, deactivates) previously set
TRACE tracepoints
(SET,SHOW,CANCEL) (Sets, displays, cancels) watchpoints
WATCH
(ACTIVATE,DEACTIVATE) (Activates, deactivates) previously set
WATCH watchpoints
SHOW CALLS Identifies the currently active routine
calls
SHOW STACK Gives additional information about the
currently active routine calls
CALL Calls a routine
3 Examining_and_Manipulating_Data
The following commands are used to examine and manipulate data:
EXAMINE Displays the value of a variable or the
contents of a program location
SET MODE [NO]OPERANDS Controls whether the address and contents
of the instruction operands are displayed
when you examine an instruction
DEPOSIT Changes the value of a variable or the
contents of a program location
DUMP Displays the contents of memory in a
manner similar to the DCL command DUMP.
EVALUATE Evaluates a language or address expression
MONITOR (Applies only to the debugger's Compaq
DECwindows Motif for OpenVMS user
interface). Displays the current value
of a variable or language expression in
the Monitor View of the Compaq DECwindows
Motif for OpenVMS user interface.
3 Type_Selection_and_Radix
The following commands are used to control type selection and
radix:
(SET,SHOW,CANCEL) (Establishes, displays, restores) the
RADIX radix for data entry and display
(SET,SHOW,CANCEL) (Establishes, displays, restores) the
TYPE type for program locations that are not
associated with a compiler-generated type
SET MODE [NO]G_FLOAT Controls whether double-precision
floating-point constants are interpreted
as G_FLOAT or D_FLOAT
3 Symbol_Searches_and_Symbolization
The following commands are used to control symbol searches and
symbolization:
SHOW SYMBOL Displays symbols in your program
(SET,SHOW,CANCEL) Sets a module by loading its symbol
MODULE information into the debugger's symbol
table, identifies, cancels a set module
(SET,SHOW,CANCEL) Sets a shareable image by loading data
IMAGE structures into the debugger's symbol
table, identifies, cancels a set image
SET MODE [NO]DYNAMIC Controls whether or not modules and
shareable images are set automatically
when the debugger interrupts execution
(SET,SHOW,CANCEL) (Establishes, displays, restores) the
SCOPE scope for symbol searches
SYMBOLIZE Converts a memory address to a symbolic
address expression
SET MODE [NO]LINE Controls whether program locations are
displayed in terms of line numbers or
routine-name + byte offset
SET MODE [NO]SYMBOLIC Controls whether program locations are
displayed symbolically or in terms of
numeric addresses
3 Displaying_Source_Code
The following commands are used to control the display of source
code:
TYPE Displays lines of source code
EXAMINE/SOURCE Displays the source code at the location
specified by the address expression
SEARCH Searches the source code for the specified
string
(SET,SHOW) SEARCH (Establishes, displays) the default
qualifiers for the SEARCH command
SET STEP [NO]SOURCE Enables/disables the display of source
code after a STEP command has been
executed or at a breakpoint, tracepoint,
or watchpoint
(SET,SHOW) MARGINS (Establishes, displays) the left and right
margin settings for displaying source code
(SET,SHOW,CANCEL) (Creates, displays, cancels) a source
SOURCE directory search list
3 Screen_Mode
The following commands are used to control screen mode and screen
displays:
SET MODE [NO]SCREEN Enables/disables screen mode
DISPLAY Creates or modifies a display
SCROLL Scrolls a display
EXPAND Expands or contracts a display
MOVE Moves a display across the screen
(SHOW,CANCEL) DISPLAY (Identifies, deletes) a display
(SET,SHOW,CANCEL) (Creates, identifies, deletes) a window
WINDOW definition
SELECT Selects a display for a display attribute
SHOW SELECT Identifies the displays selected for each
of the display attributes
SAVE Saves the current contents of a display
into another display
EXTRACT Saves a display or the current screen
state into a file
(SET,SHOW) TERMINAL (Establishes, displays) the terminal
screen height and width that the debugger
uses when it formats displays and other
output
SET MODE [NO]SCROLL Controls whether an output display is
updated line by line or once per command
Ctrl/W Refreshes the screen
DISPLAY/REFRESH
3 Editing_Source_Code
The following commands are used to control source editing from a
debugging session:
EDIT Starts an editor during a debugging
session
(SET,SHOW) EDITOR (Establishes, identifies) the editor
started by the EDIT command
3 Defining_Symbols
The following commands are used to define and delete symbols for
addresses, commands, or values:
DEFINE Defines a symbol as an address, command,
or value
DELETE Deletes symbol definitions
(SET,SHOW) DEFINE (Establishes, displays) the default
qualifier for the DEFINE command
SHOW SYMBOL/DEFINED Identifies symbols that have been defined
with the DEFINE command
3 Keypad_Mode
The following commands are used to control keypad mode and key
definitions:
SET MODE [NO]KEYPAD Enables/disables keypad mode
DEFINE/KEY Creates key definitions
DELETE/KEY Deletes key definitions
SET KEY Establishes the key definition state
SHOW KEY Displays key definitions
3 Command_Files__Log_Files__Initialization_Files_
The following commands are used with command procedures and log
files:
@ (Execute Procedure) Executes a command procedure
(SET,SHOW) ATSIGN (Establishes, displays) the default file
specification that the debugger uses to
search for command procedures
DECLARE Defines parameters to be passed to command
procedures
(SET,SHOW) LOG (Specifies, identifies) the debugger log
file
SET OUTPUT [NO]LOG Controls whether a debugging session is
logged
SET OUTPUT Controls whether, in screen mode, the
[NO]SCREEN_LOG screen contents are logged as the screen
is updated
SET OUTPUT [NO]VERIFY Controls whether debugger commands are
displayed as a command procedure is
executed
SHOW OUTPUT Identifies the current output options
established by the SET OUTPUT command
3 Control_Structures
The following commands are used to establish conditional and
looping structures for debugger commands:
FOR Executes a list of commands while
incrementing a variable
IF Executes a list of commands conditionally
REPEAT Executes a list of commands a specified
number of times
WHILE Executes a list of commands while a
condition is true
EXITLOOP Exits an enclosing WHILE, REPEAT, or FOR
loop
3 Multiprocess_Programs
The following commands are used to debug multiprocess programs.
Note that these commands are specific to multiprocess programs.
Many of the commands listed under other categories have
qualifiers or parameters that are specific to multiprocess
programs (for example, SET BREAK/ACTIVATING, EXIT process-spec,
DISPLAY/PROCESS=).
CONNECT Brings a process under debugger control
DISCONNECT Release a process from debugger control
DEFINE/PROCESS_SET Assigns a symbolic name to a list of
process specifications
SET MODE Controls whether execution is interrupted
[NO]INTERRUPT in other processes when it is paused in
some process
SET MODE [NO]WAIT Controls whether the debugger waits for
all processes to stop executing before it
prompts for another command
(SET,SHOW) PROCESS Modifies the multiprocess debugging
environment, displays process information
WAIT Controls whether the debugger waits
until all processes have stopped before
prompting for another command.
3 Additional_Commands
The following commands are used for miscellaneous purposes:
HELP Displays online help on debugger commands
and selected topics
(DISABLE,ENABLE,SHOW) (Disables, enables) the delivery of
AST ASTs in the program, identifies whether
delivery is enabled or disabled
(SET,SHOW) EVENT_ (Establishes, identifies) the current run-
FACILITY time facility for Ada, POSIX Threads, and
SCAN events
(SET,SHOW) LANGUAGE (Establishes, identifies) the current
language
SET MODE [NO]SEPARATE Controls whether the debugger, when used
on a workstation running VWS, creates a
separate window for debugger input and
output
SET OUTPUT Controls whether debugger output, except
[NO]TERMINAL for diagnostic messages, is displayed or
suppressed
SET PROMPT Specifies the debugger prompt
(SET,SHOW) TASK Modifies the tasking environment, displays
task information
(SET,SHOW) VECTOR_ Enables or disables a debugger vector mode
MODE option, identifies the current vector mode
option (for vectorized programs).
SHOW EXIT_HANDLERS Identifies the exit handlers declared in
the program
SHOW MODE Identifies the current debugger modes
established by the SET MODE command (for
example, screen mode, step mode)
SHOW OUTPUT Identifies the current output options
established by the SET OUTPUT command
SYNCHRONIZE VECTOR_ Forces immediate synchronization between
MODE the scalar and vector processors (for
vectorized programs)
2 Process_Relationships
The debugger consists of two parts: A main debugger image
(DEBUGSHR.EXE) that contains most of the debugger code and
a smaller kernel debugger image (DEBUG.EXE). This separation
reduces potential interference between the debugger and the
program being debugged and also makes it possible to have a
multiprocess debugging configuration.
When you start the debugger, a process is created to run the
main debugger. Regardless of the configuration (default or
multiprocess), the presence of a main debugger running in some
process establishes a unique debugging session.
When you bring a program under debugger control, the main
debugger spawns a subprocess to run the program along with the
kernel debugger.
In the multiprocess configuration, the program being debugged
runs in several processes. Each process that is running one or
more images under debugger control is also running a local copy
of the kernel debugger. The main debugger, running in its own
process, communicates with the other processes through their
kernel debuggers.
Although all processes of a multiprocess configuration must be in
the same job, they do not have to be related in a particular
process/subprocess hierarchy. Moreover, the program images
running in separate processes do not have to communicate with
each other.
2 Compaq_DECwindows_Interface
The debugger has a Compaq DECwindows Motif for OpenVMS user
interface for workstations. When using this interface, you
interact with the debugger by using a mouse and pointer to choose
items from menus, click on buttons, select names in windows,
and so on. The default DECwindows interface provides the basic
debugging and convenience features that you will need most of the
time.
You can customize the Compaq DECwindows Motif for OpenVMS user
interface with many of the special features of the command
interface by modifying the control-panel buttons and their
associated commands or by adding new buttons. You can customize
other Compaq DECwindows Motif for OpenVMS user interface
features by modifying the debugger resource file (DECW$USER_
DEFAULTS:VMSDEBUG.DAT).
Occasionally, you may find you prefer to disable the Compaq
DECwindows Motif for OpenVMS user interface, in order to use
the somewhat faster command-line interface. If you redefine
the DBG$DECW$DISPLAY logical name, as follows, you can use
the debugger command-line interface while retaining a windows
interface for your application:
$ DEFINE DBG$DECW$DISPLAY " "
For complete information about the Compaq DECwindows Motif for
OpenVMS user interface, see the OpenVMS Debugger Manual.
3 Invocation
To invoke the debugger's Compaq DECwindows Motif for OpenVMS user
interface from the DCL command line, issue the following command:
$ DEBUG/KEEP
3 Online_Help
To access online help within the Compaq DECwindows Motif for
OpenVMS user interface, choose one of the following items from
the Help menu on the debugger's main window:
o On Context: context-sensitive help.
o On Window: task-oriented help.
o On Help: how to use online help.
o On Version: copyright and version information.
o On Commands: debugger command help.
o On Commands, Messages item: diagnostic message help.
3 DBG$DECW$DISPLAY_Logical_Name
Specifies the debugger interface (Compaq DECwindows Motif for
OpenVMS or command) or the display device (if you are displaying
the interface on a workstation).
By default, DBG$DECW$DISPLAY is either undefined or has the same
definition as the application-wide logical name DECW$DISPLAY (see
help on Logical_Names).
The Compaq DECwindows Motif for OpenVMS user interface is the
default on workstations. To display the command interface instead
of the Compaq DECwindows Motif for OpenVMS user interface, enter
the following definition before starting the debugger:
$ DEFINE DBG$DECW$DISPLAY " "
For complete information about the Compaq DECwindows Motif for
OpenVMS user interface, see the debugger's Compaq DECwindows
Motif for OpenVMS documentation.
2 Commands_Disabled_in_DECwindows
The following commands are disabled in the debugger's Compaq
DECwindows Motif for OpenVMS user interface. Many of them are
relevant only to the command interface's screen mode.
ATTACH SELECT
CANCEL MODE (SET,SHOW) ABORT_KEY
CANCEL WINDOW (SET,SHOW) KEY
DEFINE/KEY (SET,SHOW) MARGINS
DELETE/KEY SET MODE [NO]KEYPAD
DISPLAY SET MODE [NO]SCREEN
EXAMINE/SOURCE SET MODE [NO]SCROLL
EXPAND SET OUTPUT [NO]TERMINAL
EXTRACT (SET,SHOW) TERMINAL
HELP (SET,SHOW) WINDOW
MOVE (SHOW,CANCEL) DISPLAY
SAVE SHOW SELECT
SCROLL SPAWN
The debugger issues an error message if you try to enter any
of these disabled commands at the command prompt or when the
debugger executes a command procedure containing any of these
commands.
The MONITOR command works only with the Compaq DECwindows Motif
for OpenVMS user interface (because the command uses the Monitor
View).
2 Keypad_Definitions_CI
This help topic describes the keypad definitions in the
debugger's command interface. For information on keypad
definitions in the graphical user interface (GUI), type HELP
Keypad_Definitions_GUI.
On Digital VT-series terminals and MicroVAX workstations, you
can use the numeric keypad to enter debugger commands provided
you are in "keypad mode." Keypad mode is enabled by default, but
can be disabled and enabled by the SET MODE [NO]KEYPAD commands.
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 is executed immediately. Others are
not: 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.
3 DEFAULT
Keypad definitions when +--------+--------+--------+--------+
you do not use the GOLD | | Help | Set | |
or BLUE key. | GOLD | Keypad | Mode | BLUE |
| | Default| Screen | |
For more information +--------+--------+--------+--------+
see help on: | Src LH1| | | Disp |
|Inst RH1| Scroll | Disp | next |
KEYPAD BLUE | Out S45| Up | next | S12345 |
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | Exam | | | |
| Scroll | Source | Scroll | Go |
Ctrl/W does a | Left | .0\%PC | Right | |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. | | | Select | |
| Exam | Scroll | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
3 GOLD
Keypad definitions when +--------+--------+--------+--------+
you press the GOLD key. | | Help |Set Mode| |
| GOLD | Keypad | No | BLUE |
Reset cancels the | | Gold | Screen | |
GOLD key. +--------+--------+--------+--------+
|Inst LH1| | Set | |
For more information, | Reg RH1| Scroll | Process| |
see help on: | Out S45| Top | next | |
+--------+--------+--------+--------+
KEYPAD BLUE | Scroll | | Scroll | Select |
KEYPAD DEFAULT | Left | Show | Right | Source |
KEYPAD STATE_KEYS | 255 | Calls | 255 | next |
+--------+--------+--------+--------+
Ctrl/W does a | Exam | | Select | |
DISPLAY/REFRESH | prev | Scroll | Output | E |
in screen mode. | | Bottom | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
3 BLUE
Keypad definitions when +--------+--------+--------+--------+
you press the BLUE key. | | Help | | |
| GOLD | Keypad | Disp | BLUE |
"..." means you must | | Blue | Gener | |
type more input after +--------+--------+--------+--------+
pressing the key. |2 SRC Qn| Scroll | 2 SRC | Disp |
| 2 INST | Up | at | Src H1 |
Reset cancels the | at RQn | ... | Q1,Q2 | Out S45|
BLUE key. +--------+--------+--------+--------+
| Scroll | Show | Scroll | Select |
For more information, | Left | Calls | Right | Inst |
see help on: | ... | 3 | ... | next |
+--------+--------+--------+--------+
KEYPAD DEFAULT |3 SRC Sn| Scroll | 3 SRC | |
KEYPAD GOLD | 3 INST | Down | at | E |
KEYPAD STATE_KEYS | at RSn | ... |S1,S2,S3| N |
+--------+--------+--------+ T |
Ctrl/W does a | | | E |
DISPLAY/REFRESH | Step/Over | Reset | R |
in screen mode. | | | |
+-----------------+--------+--------+
3 MOVE
Keypad definitions in +--------+--------+--------+--------+
the MOVE state when you | | Help | Set | |
do not use GOLD or BLUE. | GOLD | Keypad | Mode | BLUE |
| | Move | Screen | |
For more information, +--------+--------+--------+--------+
see help on: | 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 a | Left | .0\%PC | Right | |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. | | | Select | |
| Exam | Move | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
3 EXPAND
Keypad definitions in +--------+--------+--------+--------+
the EXPAND state when | | Help | Set | |
you do not use the GOLD | GOLD | Keypad | Mode | BLUE |
or BLUE key. | | Expand | Screen | |
+--------+--------+--------+--------+
For more information, | Src LH1| | | Disp |
see help on: |Inst RH1| Expand | Disp | next |
| Out S45| Up | next | S12345 |
KEYPAD BLUE +--------+--------+--------+--------+
KEYPAD GOLD | | Exam | | |
KEYPAD STATE_KEYS | Expand | Source | Expand | Go |
| Left | .0\%PC | Right | |
Ctrl/W does a +--------+--------+--------+--------+
DISPLAY/REFRESH | | | Select | |
in screen mode. | Exam | Expand | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
3 CONTRACT
Keypad definitions in +--------+--------+--------+--------+
the CONTRACT state when | | Help | Set | |
you do not use the GOLD | GOLD | Keypad | Mode | BLUE |
or BLUE key. | |Contract| Screen | |
+--------+--------+--------+--------+
For more information, | Src LH1| Expand | | Disp |
see help on: |Inst RH1| Up= | Disp | next |
| Out S45| -1 | next | S12345 |
KEYPAD BLUE +--------+--------+--------+--------+
KEYPAD GOLD | Expand | Exam | Expand | |
KEYPAD STATE_KEYS | Left= | Source | Right= | Go |
| -1 | .0\%PC | -1 | |
Ctrl/W does a +--------+--------+--------+--------+
DISPLAY/REFRESH | | Expand | Select | |
in screen mode. | Exam | Down= | Scroll | E |
| | -1 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
3 MOVE_GOLD
Keypad definitions in +--------+--------+--------+--------+
the MOVE state when | | Help |Set Mode| |
you press the GOLD key. | GOLD | Keypad | No | BLUE |
| |MoveGold| Screen | |
For more information, +--------+--------+--------+--------+
see help on: |Inst LH1| Move | Set | |
| Reg RH1| Up= | Process| |
KEYPAD BLUE | Out S45| 999 | next | |
KEYPAD DEFAULT +--------+--------+--------+--------+
KEYPAD STATE_KEYS | Move | | Move | Select |
| Left= | Show | Right= | Source |
Ctrl/W does a | 999 | Calls | 999 | next |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. | Exam | Move | Select | |
| prev | Down= | Output | E |
| | 999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
3 EXPAND_GOLD
Keypad definitions in +--------+--------+--------+--------+
the EXPAND state when | | Help |Set Mode| |
you press the GOLD key. | GOLD | Keypad | No | BLUE |
| |ExpaGold| Screen | |
For more information, +--------+--------+--------+--------+
see help on: |Inst LH1| Expand | Set | |
| Reg RH1| Up= | Process| |
KEYPAD BLUE | Out S45| 999 | next | |
KEYPAD DEFAULT +--------+--------+--------+--------+
KEYPAD STATE_KEYS | Expand | | Expand | Select |
| Left= | Show | Right= | Source |
Ctrl/W does a | 999 | Calls | 999 | next |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. | Exam | Expand | Select | |
| prev | Down= | Output | E |
| | 999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
3 CONTRACT_GOLD
Keypad definitions in +--------+--------+--------+--------+
the CONTRACT state when | | Help |Set Mode| |
you press the GOLD key. | GOLD | Keypad | No | BLUE |
| |CntrGold| Screen | |
For more information, +--------+--------+--------+--------+
see help on: |Inst LH1| Expand | Set | |
| Reg RH1| Up= | Process| |
KEYPAD BLUE | Out S45| -999 | next | |
KEYPAD DEFAULT +--------+--------+--------+--------+
KEYPAD STATE_KEYS | Expand | | Expand | Select |
| Left= | Show | Right= | Source |
Ctrl/W does a | -999 | Calls | -999 | next |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. | Exam | Expand | Select | |
| prev | Down= | Output | E |
| | -999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
3 MOVE_BLUE
Keypad definitions in +--------+--------+--------+--------+
the MOVE state when | | Help | | |
you press the BLUE key. | GOLD | Keypad | Disp | BLUE |
| |MoveBlue| Gener | |
For more information +--------+--------+--------+--------+
see help on: |2 SRC Qn| | 2 SRC | Disp |
| 2 INST | Move | at | Src H1 |
KEYPAD DEFAULT | at RQn | Up=5 | Q1,Q2 | Out S45|
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | | Show | | Select |
| Move | Calls | Move | Inst |
Ctrl/W does a | Left=10| 3 |Right=10| next |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. |3 SRC Sn| | 3 SRC | |
| 3 INST | Move | at | E |
| at RSn | Down=5 |S1,S2,S3| N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
3 EXPAND_BLUE
Keypad definitions in +--------+--------+--------+--------+
the EXPAND state when | | Help | | |
you press the BLUE key. | GOLD | Keypad | Disp | BLUE |
| |ExpaBlue| Gener | |
For more information +--------+--------+--------+--------+
see help on: |2 SRC Qn| | 2 SRC | Disp |
| 2 INST | Expand | at | Src H1 |
KEYPAD DEFAULT | at RQn | Up=5 | Q1,Q2 | Out S45|
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | | Show | | Select |
| Expand | Calls | Expand | Inst |
Ctrl/W does a | Left=10| 3 |Right=10| next |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. |3 SRC Sn| | 3 SRC | |
| 3 INST | Expand | at | E |
| at RSn | Down=5 |S1,S2,S3| N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
3 CONTRACT_BLUE
Keypad definitions in +--------+--------+--------+--------+
the CONTRACT state when | | Help | | |
you press the BLUE key. | GOLD | Keypad | Disp | BLUE |
| |CntrBlue| Gener | |
For more information, +--------+--------+--------+--------+
see help on: |2 SRC Qn| Expand | 2 SRC | Disp |
| 2 INST | Up= | at | Src H1 |
KEYPAD DEFAULT | at RQn | -5 | Q1,Q2 | Out S45|
KEYPAD GOLD +--------+--------+--------+--------+
KEYPAD STATE_KEYS | Expand | Show | Expand | Select |
| Left= | Calls | Right= | Inst |
Ctrl/W does a | -10 | 3 | -10 | next |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. |3 SRC Sn| Expand | 3 SRC | |
| 3 INST | Down= | at | E |
| at RSn | -5 |S1,S2,S3| N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
3 State_Keys
You can use the four scrolling keys (KP8, KP2, KP4, and KP6)
to expand, contract, and move displays, depending on the keypad
state in effect. Thus, the keys do a SCROLL/UP, /DOWN, /LEFT, or
/RIGHT, or a corresponding MOVE. You can press the GOLD key to
make the operation to advance more than one line or column. The
commands apply to the current scrolling display. Pressing KP3
selects the current scrolling display from the display circular
list.
Four keys on the LK201 keyboard let you set the keypad state to
DEFAULT, MOVE, EXPAND, or CONTRACT. The keypad state changes the
definitions of KP8, KP2, KP4, and KP6. The meaning of all other
keys remains unchanged.
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 command:
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 | | | | |
+--------+--------+--------+--------+
For example, in the MOVE state (key F18), pressing KP2 moves the
default scrolling display down by one character position, and
pressing GOLD-KP2 moves the display down by a larger increment.
The keypad remains in the MOVE state until you select another
state, such as the DEFAULT state (key F17).
3 Summary
Summary of debugger +--------+--------+--------+--------+
keypad definitions. | | | | |
| GOLD | Help | Screen | BLUE |
For more information, | | | Mode | |
see help on: +--------+--------+--------+--------+
| 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 a | | am I? | | |
DISPLAY/REFRESH +--------+--------+--------+--------+
in screen mode. | | | | |
| Exam | Down | Select | E |
| | | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
2 Keypad_Definitions_GUI
This section describes the keypad definitions in the debugger's
graphical user interface. For information on the keypad
definitions in the command interface, type HELP Keypad_
Definitions_CI.
On workstations running the debugger's GUI, you can use the
numeric keypad to enter predefined debugger commands, as follows:
Key Predefined Command
KP0 Step/Line
KP1 Examine
KPcomma Go
GOLD-KP0 Step/Into
BLUE-KP0 Step/Over
GOLD-KP1 Examine^
KP5 Show Calls
GOLD-KP5 Show Calls 3
To issue one of these commands, press the key indicated, followed
by the Enter key on the keypad.
You can change the commands represented by each key, or map
commands to other keys on your keyboard, by customizing the
EnterCmdOnCmdLine entry in the debugger resource file. For more
information, see the OpenVMS Debugger Manual. If you are mapping
to other keys, you also need to consult the key designations
listed in the KeySym Encoding chapter of the X and Motif Quick
Reference Guide.
Users of the debugger's command interface keypad definitions
should note that you do not need to be in keypad mode to use
keypad definitions in the GUI.
2 Language_Support
On VAX processors, you can use the debugger with programs written
in the following Compaq languages:
Ada BASIC BLISS C
C++ COBOL DIBOL Fortran
MACRO-32 Pascal PL-I RPG II
SCAN
On Alpha processors, you can use the debugger with programs
written in the following Compaq languages:
Ada BASIC BLISS C
C++ COBOL Fortran MACRO-32
MACRO-64 Pascal PL/I
3 Overview
The debugger recognizes the syntax, data typing, and scoping
rules of each language. It also recognizes each language's
operators and expression syntax. Therefore, when using debugger
commands you can specify variables and other program entities as
you might in the source code of the program. You can also compute
the value of a source-language expression using the syntax of
that language.
This appendix describes debugging techniques that are common to
most of the supported languages. The help topics provide further
information specific to 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 information, including
restrictions in debugger support, if any
For more information about language-specific debugger support,
refer to the documentation furnished with a particular language.
If your program is written in more than one language, you can
change the debugging context from one language to another during
a debugging session. Use the SET LANGUAGE command with the
keyword corresponding to your language choice.
On VAX processors, you can specify one of the following keywords:
ADA BASIC BLISS C
C++ COBOL DIBOL FORTRAN
MACRO PASCAL PLI RPG
SCAN UNKNOWN
On Alpha processors, you can specify one of the following
keywords:
ADA AMACRO BASIC BLISS
C C++ COBOL FORTRAN
MACRO MACRO64 PASCAL UNKNOWN
When you are debugging a program written in an unsupported
language, enter the SET LANGUAGE UNKNOWN command. 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, type Help Language_UNKNOWN.
3 Ada
The following subtopics describe debugger support for Ada.
For information specific to Ada tasking programs, see also the
debugger manual.
4 Ada_Names_and_Symbols
The following subtopics describe debugger support for Ada names
and symbols, including predefined attributes.
Note that parts of names may be language expressions-for example,
attributes such as 'FIRST or 'POS. This affects how you use the
EXAMINE, EVALUATE, and DEPOSIT commands with such names. For
examples of enumeration types, type Help Specifying_Attributes_
with_Enumeration_Types.
5 Ada_Names
Supported Ada names follow:
Kind of Name Debugger Support
Lexical Full support for Ada rules for the syntax of
elements identifiers.
Function designators that are operator symbols
(for example, + and *) rather than identifiers
must be prefixed with %NAME. Also, the operator
symbol must be enclosed in quotation marks.
Full support for Ada rules for numeric literals,
character literals, string literals, and reserved
words.
The debugger accepts signed integer literals in
the range -2147483648 to 2147483647.
Depending on context and architecture, the
debugger interprets floating-point types as F_
floating, D_floating, G_floating, H_floating, S_
floating, or T_floating.
Indexed Full support.
components
Slices You can examine and evaluate an entire slice or
an indexed component of a slice.
You can deposit only to an indexed component of a
slice. You cannot deposit an entire slice.
Selected Full support, including use of the keyword all in
components .all.
Literals Full support, including the keyword null.
Boolean Full support (TRUE, FALSE).
symbols
Aggregates You can examine the entire record and array
objects with the EXAMINE command. You can deposit
a value in a component of an array or record. You
cannot use the DEPOSIT command with aggregates,
except to deposit character string values.
5 Predefined_Attributes
Supported Ada predefined attributes follow. Note that the
debugger SHOW SYMBOL/TYPE command provides the same information
that is provided by the P'FIRST, P'LAST, P'LENGTH, P'SIZE, and
P'CONSTRAINED attributes.
Attribute Debugger Support
P'CONSTRAINEDFor a prefix P that denotes a record object
with discriminants. The value of P'CONSTRAINED
reflects the current state of P (constrained or
unconstrained).
P'FIRST For a prefix P that denotes an enumeration type or
a subtype of an enumeration type. Yields the lower
bound of P.
P'FIRST For a prefix P that is appropriate for an array
type, or that denotes a constrained array subtype.
Yields the lower bound of the first index range.
P'FIRST(N) For a prefix P that is appropriate for an array
type, or that denotes a constrained array subtype.
Yields the lower bound of the Nth index range.
P'LAST For a prefix P that denotes an enumeration type, or
a subtype of an enumeration type. Yields the upper
bound of P.
P'LAST For a prefix P that is appropriate for an array
type, or that denotes a constrained array subtype.
Yields the upper bound of the first index range.
P'LAST(N) For a prefix P that is appropriate for an array
type, or that denotes a constrained array subtype.
Yields the upper bound of the Nth index range.
P'LENGTH For a prefix P that is appropriate for an array
type, or that denotes a constrained array subtype.
Yields the number of values of the first index range
(zero for a null range).
P'LENGTH(N) For a prefix P that is appropriate for an array
type, or that denotes a constrained array subtype.
Yields the number of values of the Nth index range
(zero for a null range).
P'POS(X) For a prefix P that denotes an enumeration type or a
subtype of an enumeration type. Yields the position
number of the value X. The first position is 0.
P'PRED(X) For a prefix P that denotes an enumeration type or
a subtype of an enumeration type. Yields the value
of type P which has a position number one less than
that of X.
P'SIZE For a prefix P that denotes an object. Yields the
number of bits allocated to hold the object.
P'SUCC(X) For a prefix P that denotes an enumeration type or
a subtype of an enumeration type. Yields the value
of type P which has a position number one more than
that of X.
P'VAL(N) For a prefix P that denotes an enumeration type or
a subtype of an enumeration type. Yields the value
of type P which has the position number N. The first
position is 0.
6 Specifying_Attributes_with_Enumeration_Types
Consider the following declarations:
type DAY is
(MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY,SUNDAY);
MY_DAY : DAY;
The following examples show the use of attributes with
enumeration types. Note that you cannot use the EXAMINE command
to determine the value of attributes, because attributes are not
variable names. You must use the EVALUATE command instead. For
the same reason, attributes can appear only on the right of the
:= operator in a DEPOSIT command.
DBG> EVALUATE DAY'FIRST
MON
DBG> EVALUATE DAY'POS(WEDNESDAY)
2
DBG> EVALUATE DAY'VAL(4)
FRI
DBG> DEPOSIT MY_DAY := TUESDAY
DBG> EVALUATE DAY'SUCC(MY_DAY)
WED
DBG> DEPOSIT . := DAY'PRED(MY_DAY)
DBG> EXAMINE .
EXAMPLE.MY_DAY: MONDAY
DBG> EVALUATE DAY'PRED(MY_DAY)
%DEBUG-W-ILLENUMVAL, enumeration value out of legal range
6 Resolving_Overloaded_Enumeration_Literals
Consider the following declarations:
type MASK is (DEC,FIX,EXP);
type CODE is (FIX,CLA,DEC);
MY_MASK : MASK;
MY_CODE : CODE;
In the following example, the qualified expression CODE'(FIX)
resolves the overloaded enumeration literal FIX, which belongs to
both type CODE and type MASK:
DBG> DEPOSIT MY_CODE := FIX
%DEBUG-W-NOUNIQUE, symbol 'FIX' is not unique
DBG> SHOW SYMBOL/TYPE FIX
data EXAMPLE.FIX
enumeration type (CODE, 3 elements), size: 1 byte
data EXAMPLE.FIX
enumeration type (MASK, 3 elements), size: 1 byte
DBG> DEPOSIT MY_CODE := CODE'(FIX)
DBG> EXAMINE MY_CODE
EXAMPLE.MY_CODE: FIX
4 Operators_and_Expressions
The following sections describe debugger support for Ada
operators and language expressions.
5 Operators_in_Language_Expressions
Supported Ada operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus (identity)
Infix + Addition
Infix * Multiplication
Infix / Division
Infix MOD Modulus
Infix REM Remainder
Infix ** Exponentiation (VAX specific)
Prefix ABS Absolute value
Infix & Concatenation (only string types)
Infix = Equality (only scalar and string types)
Infix /= Inequality (only scalar and string types)
Infix > Greater than (only scalar and string types)
Infix >= Greater than or equal (only scalar and string
types)
Infix < Less than (only scalar and string types)
Infix <= Less than or equal (only scalar and string types)
Prefix NOT Logical NOT
Infix AND Logical AND (not for bit arrays)
Infix OR Logical OR (not for bit arrays)
Infix XOR Logical exclusive OR (not for bit arrays)
The debugger does not support the following items:
o Operations on entire arrays or records
o The short-circuit control forms: and then, or else
o The membership tests: in, not in
o User-defined operators
5 Language_Expressions
Supported Ada expressions include:
Kind of
Expression Debugger Support
Type No support for any of the explicit type
conversions conversions specified in Ada. However, the
debugger performs certain implicit type
conversions between numeric types during the
evaluation of expressions.
The debugger converts lower-precision types
to higher-precision types before evaluating
expressions involving types of different
precision:
o If integer and floating-point types are mixed,
the integer type is converted to floating-point
type.
o If integer and fixed-point types are mixed, the
integer type is converted to fixed-point type.
o If integer types of different sizes are mixed
(for example, byte-integer and word-integer),
the one with the smaller size is converted to
the larger size.
Subtypes Full support. Note that the debugger denotes
subtypes and types that have range constraints
as "subrange" types.
Qualified Supported as required to resolve overloaded
expressions enumeration literals (literals that have the same
identifier but belong to different enumeration
types). The debugger does not support qualified
expressions for any other purpose.
Allocators No support for any operations with allocators.
Universal No support.
expressions
4 Data_Types
Supported Ada data types follow:
Ada Data Type Operating System Data Type Name
INTEGER Longword Integer (L)
SHORT_INTEGER Word Integer (W)
SHORT_SHORT_INTEGER Byte Integer (B)
SYSTEM.UNSIGNED_QUADWORD Quadword Unsigned (QU)
SYSTEM.UNSIGNED_LONGWORD Longword Unsigned (LU)
SYSTEM.UNSIGNED_WORD Word Unsigned (WU)
SYSTEM.UNSIGNED_BYTE Byte Unsigned (BU)
FLOAT F_Floating (F)
SYSTEM.F_FLOAT F_Floating (F)
SYSTEM.D_FLOAT D_Floating (D)
LONG_FLOAT D_Floating (D), if pragma LONG_FLOAT
(D_FLOAT) is in effect.
G_Floating (G), if pragma LONG_FLOAT
(G_FLOAT) is in effect.
SYSTEM.G_FLOAT G_Floating (G)
SYSTEM.H_FLOAT H_Floating (H)
(VAX specific)
LONG_LONG_FLOAT H_Floating (H)
(VAX specific)
IEEE_SINGLE_FLOAT S_Floating (FS)
(Alpha specific)
IEEE_DOUBLE_FLOAT T_Floating (FT)
(Alpha specific)
Fixed (None)
STRING ASCII Text (T)
BOOLEAN Aligned Bit String (V)
BOOLEAN Unaligned Bit String (VU)
Enumeration For any enumeration type whose value
fits into an unsigned byte or word:
Byte Unsigned (BU) or Word Unsigned
(WU), respectively. Otherwise: No
corresponding operating system data
type.
Arrays (None)
Records (None)
Access (pointers) (None)
Tasks (None)
4 Compiling_and_Linking
The Ada predefined units in the ADA$PREDEFINED program library
on your system have been compiled with the /NODEBUG qualifier.
Before using the debugger to refer to names declared in the
predefined units, you must first copy the predefined unit source
files using the ACS EXTRACT SOURCE command. Then, you must
compile the copies into the appropriate library with the /DEBUG
qualifier, and relink the program with the /DEBUG qualifier.
If you use the /NODEBUG qualifier with one of the Ada compilation
commands, only global symbol records are included in the modules
for debugging. Global symbols in this case are names that the
program exports to modules in other languages by means of the Ada
export pragmas:
EXPORT_PROCEDURE
EXPORT_VALUED_PROCEDURE
EXPORT_FUNCTION
EXPORT_OBJECT
EXPORT_EXCEPTION
PSECT_OBJECT
The /DEBUG qualifier on the ACS LINK command causes the linker to
include all debugging information in the closure of the specified
unit in the executable image.
4 Source_Display
Source code may not be available for display for the following
reasons that are specific to Ada programs:
o Execution is paused within Ada initialization or elaboration
code, for which no source code is available.
o The copied source file is not in the program library where the
unit was originally compiled.
o The external source file is not where it was when the unit was
originally compiled.
o The source file has been modified since the executable image
was generated, and the original copied source file or external
source file no longer exists.
The following paragraphs explain how to control the display of
source code with Ada programs.
If the compiler command's /COPY_SOURCE qualifier (the default)
was in effect when you compiled your program, the debugger
obtains the displayed Ada source code from the copied source
files located in the program library where the program was
originally compiled. If you compiled your program with the
/NOCOPY_SOURCE qualifier, the debugger obtains the displayed
Ada source code from the external source files associated with
your program's compilation units.
The file specifications of the copied or external source files
are embedded in the associated object files. For example, if you
have used the ACS COPY UNIT command to copy units, or the DCL
command COPY or BACKUP to copy an entire library, the debugger
still searches the original program library for copied source
files. If, after copying, the original units have been modified
or the original library has been deleted, the debugger may not
find the original copied source files. Similarly, if you have
moved the external source files to another disk or directory, the
debugger may not find them.
In such cases, use the SET SOURCE command to locate the correct
files for source display. You can specify a search list of one
or more program library or source code directories. For example
(ADA$LIB is the logical name that the program library manager
equates to the current program library):
DBG> SET SOURCE ADA$LIB,DISK:[SMITH.SHARE.ADALIB]
The SET SOURCE command does not affect the search list for the
external source files that the debugger fetches when you use the
debugger EDIT command. To tell the EDIT command where to look for
your source files, use the SET SOURCE/EDIT command.
4 EDIT_Command
With Ada programs, by default the debugger EDIT command fetches
the external source file that was compiled to produce the
compilation unit in which execution is currently paused. You
do not edit the copied source file, in the program library, that
the debugger uses for source display.
The file specifications of the source files you edit are embedded
in the associated object files during compilation (unless you
specify /NODEBUG). If some source files have been relocated after
compilation, the debugger may not find them.
In such cases, you can use the debugger SET SOURCE/EDIT command
to specify a search list of one or more directories where the
debugger should look for source files. For example:
DBG> SET SOURCE/EDIT [],USER:[JONES.PROJ.SOURCES]
The SET SOURCE/EDIT command does not affect the search list for
copied source files that the debugger uses for source display.
The SHOW SOURCE/EDIT command displays the source-file search list
currently being used for the EDIT command. The CANCEL SOURCE/EDIT
command cancels the source-file search list currently being used
for the EDIT command and restores the default search mode.
4 GO_and_STEP_Commands
Note the following points about using the GO and STEP commands
with Ada programs:
o When starting a debugging session, use the GO command rather
than the STEP command to avoid stepping through compiler-
generated initialization code.
- Use the GO command to go directly to the preset breakpoint
at the start of the main program, past the initialization
and package elaboration code.
- Use the GO command and breakpoints to suspend execution at
the start of the elaboration of library packages, before
execution reaches the main program.
For information on how to monitor the package elaboration
phase, type Help Debugging_Ada_Library_Packages.
o If a line contains more than one statement, a STEP command
executes all the statements on that line as part of a single
step.
o Ada task entry calls are not the same as subprogram calls
because task entry calls are queued and may not execute right
away. If you use the STEP command to move execution into a
task entry call, the results might not be what you expect.
4 Debugging_Ada_Library_Packages
When an Ada main program (or a non-Ada main program that calls
Ada code) is executed, initialization code is executed for the
Ada run-time library and elaboration code for all library units
that the program depends on. The elaboration code causes the
library units to be elaborated in appropriate order before the
main program is executed. Library specifications, bodies, and
some of their subunits are also elaborated by this process.
The elaboration of library packages accomplishes the following
operations:
o Causes package declarations to take effect
o Initializes any variables whose declaration includes
initialization code
o Executes any sequence of statements that appear between the
begin and end statements of package bodies
When you bring an Ada program under debugger control, execution
is paused initially before the initialization code is executed
and before the elaboration of library units. For example:
DBG> RUN FORMS
Language: ADA, Module: FORMS
Type GO to reach main program
DBG>
At that point, before typing GO to get to the start of the main
program, you can step through and examine parts of the library
packages by setting breakpoints at the package specifications
or bodies you are interested in. You then use the GO command
to get to the start of each package. To set a breakpoint on a
package body, specify the package unit name with the SET BREAK
command. To set a breakpoint on a package specification, specify
the package unit name followed by a trailing underscore character
(_).
Even if you have set a breakpoint on a package body, the break
will not occur if the debugger module for that body is not
set. If the module is not set, the break will occur at the
package specification. This effect occurs because the debugger
automatically sets modules for the specifications of packages
named in with clauses; it does not automatically set modules
for the associated package bodies (see the Language_Support Ada
subtopic Setting_Modules).
Also, to set a breakpoint on a subprogram declared in a package
specification, you must set the module for the package body.
Note that the compiler generates unique names for subprograms
declared in library packages that are or could be overloaded
names. The debugger uses these unique names in its output, and
requires them in commands where the names would otherwise be
ambiguous. For more information on resolving overloaded names
and symbols, see the Language_Support Ada subtopic Resolving_
Overloaded_Names_and_Symbols.
4 Predefined_Breakpoints
When you start the debugger with an Ada program (or a non-Ada
program that calls Ada code), two breakpoints that are associated
with Ada tasking exception events are automatically established.
These breakpoints are established automatically during debugger
initialization when the Ada run-time library is present.
When you enter a SHOW BREAK command under these conditions, the
following breakpoints are displayed:
DBG> SHOW BREAK
Predefined breakpoint on ADA event "EXCEPTION_TERMINATED"
for any value
Predefined breakpoint on ADA event "DEPENDENTS_EXCEPTION"
for any value
DBG>
4 Monitoring_Exceptions
The debugger recognizes three kinds of exceptions in Ada
programs:
o A user-defined exception-an exception declared with the Ada
reserved word exception in an Ada compilation unit
o An Ada predefined exception, such as PROGRAM_ERROR or
CONSTRAINT_ERROR
o Any other (non-Ada) exception or condition
The following subtopics explain how to monitor such exceptions.
5 Monitoring_Any_Exception
The SET BREAK/EXCEPTION command enables you to set a breakpoint
on any exception or condition. This includes certain conditions
that are signaled internally within the Ada run-time library.
These conditions are an implementation mechanism; they do not
represent program failures, and they cannot be handled by Ada
exception handlers. If these conditions appear while you are
debugging your program, you may want to consider specifying the
kind of exceptions when setting breakpoints.
The following example shows a tracepoint occurring for an Ada
CONSTRAINT_ERROR exception as the result of a SET TRACE/EXCEPTION
command:
DBG> SET TRACE/EXCEPTION
DBG> GO
. . .
%ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR
-ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C
trace on exception preceding
ADA$RAISE\ADA$RAISE_CONDITION.%LINE 333+12
. . .
In the next example, the SHOW CALLS command displays a traceback
of the calls leading to the subprogram where the exception
occurred or to which the exception was raised:
DBG> SET BREAK/EXCEPTION DO (SHOW CALLS)
DBG> GO
. . .
%SYSTEM-F-INTDIV, arithmetic trap, integer divide
by zero at PC=000008AF,
PSL=03C000A2 break on exception preceding
SYSTEM_OPS.DIVIDE.%LINE 17+6
17: return X/Y;
module name routine name line rel PC abs PC
*SYSTEM_OPS DIVIDE 17 00000015 000008AF
*PROCESSOR PROCESSOR 19 000000AE 00000BAD
*ADA$ELAB_PROCESSOR
ADA$ELAB_PROCESSOR 00000009 00000809
LIB$INITIALIZE 00000054 00000C36
SHARE$ADARTL 00000000 000398BE
*ADA$ELAB_PROCESSOR
ADA$ELAB_PROCESSOR 0000001B 0000081B
LIB$INITIALIZE 0000002F 00000C21
In this example, the condition SS$_INTDIV is raised at line
17 of the subprogram DIVIDE in the package SYSTEM_OPS. The
example shows an important effect: some conditions (such as SS$_
INTDIV) are treated as being equivalent to some Ada predefined
exceptions.
The matching of a condition and an Ada predefined exception is
performed by the condition handler provided by Ada for any frame
that includes an exception part. Therefore, when an exception
breakpoint or tracepoint is triggered by a condition that has
an equivalent Ada exception name, the message displays only the
system condition code name, and not the name of the corresponding
Ada exception.
5 Monitoring_Specific_Exceptions
Whenever an exception is raised, the debugger sets the following
built-in symbols. You can use them to qualify exception
breakpoints or tracepoints so that they trigger only on certain
exceptions.
%EXC_ A string that names the facility that issued the
FACILITY exception. The facility name for Ada predefined
exceptions and user-defined exceptions is ADA.
%EXC_NAME An uppercase string that names the exception.
If the exception raised is an Ada predefined
exception, its name is truncated if it exceeds
15 characters. For example, CONSTRAINT_ERROR is
truncated to CONSTRAINT_ERRO. If the exception is
a user-defined exception, %EXC_NAME contains the
string "EXCEPTION", and the name of the user-defined
exception is contained in %ADAEXC_NAME.
%ADAEXC_ If the exception raised is user-defined, %ADAEXC_
NAME NAME contains a string that names the exception, and
%EXC_NAME contains the string "EXCEPTION". If the
exception is not user-defined, %ADAEXC_NAME contains
a null string, and the name of the exception is
contained in %EXC_NAME.
%EXC_NUM The number of the exception.
%EXC_ A string that gives the exception severity level (F,
SEVERITY E, W, I, S, or ?).
5 Monitoring_Handled_Exceptions_and_Exception_Handlers
The SET BREAK/EVENT and SET TRACE/EVENT commands let you set
breakpoints and tracepoints on exceptions that are about to be
handled by Ada exception handlers. These commands let you observe
the execution of each Ada exception handler that gains control.
You can specify two event names with these commands:
HANDLED Triggers when an exception is about to be handled
in an Ada exception handler (includes HANDLED_
OTHERS events).
HANDLED_ Triggers only when an exception is about to be
OTHERS handled in an Ada exception handler choice others.
For example, the following command sets a breakpoint that
triggers whenever an exception is about to be handled by an Ada
exception handler:
DBG> SET BREAK/EVENT=HANDLED
When the breakpoint triggers, the debugger identifies the
exception that is about to be handled and the exception handler
that is about to be executed. You can then use that information
to set a breakpoint on a particular handler, or you can enter the
GO command, and see which Ada handler next attempts to handle the
exception. For example:
DBG> GO
. . .
break on Ada event HANDLED
task %TASK 1 is about to handle an exception
The Ada exception handler is at: PROCESSOR.%LINE 21
%ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR
-ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C
DBG> SET BREAK PROCESSOR.%LINE 21; GO
4 Examining_and_Manipulating_Data
When examining and manipulating data, note the following
considerations:
o Before you can examine or deposit into a nonstatic variable
(any variable not declared in a library package), its defining
subprogram, task, and so on, must be active on the call stack.
o Before you can examine, deposit, or evaluate an Ada subprogram
formal parameter or an Ada variable, the parameter or variable
must be elaborated. In other words, you should step or
otherwise move execution past the parameter or variable's
declaration. The value contained in any variable or formal
parameter whose declaration has not been elaborated might be
invalid.
In most cases, the debugger enables you to specify variables
and expressions in debugger commands exactly as you would
specify them in the source code of the program, including use
of qualified expressions. The following subtopics discuss some
additional points about debugger support for records and access
types.
5 Records
Note the following points about debugger support for records:
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 With variant records, the debugger lets you examine or assign
a value to a component of a variant part that is not active.
But because this is an illegal action in Ada, the debugger
also issues an informational message. For example, assume
that record REC1 has a variant field named STATUS and that the
value of STATUS is such that REC1.COMP3 is inactive:
DBG> EXAMINE REC1.COMP3
%DEBUG-I-BADDISCVAL, incorrect value of 1 in discriminant
field STATUS
MAIN.REC1.COMP3: 438
5 Access_Types
Note the following points about debugger support for access
types:
o The debugger does not support allocators, so you cannot create
new access objects with the debugger.
o When you specify the name of an access object with the EXAMINE
command, the debugger displays the memory location of the
object it designates.
o To examine the value of a designated object, you must use
selected component notation, specifying .ALL. For example, to
examine the value of a record access object designated by A:
DBG> EXAMINE A.ALL
EXAMPLE.A.ALL
NAME(1..10): "John Doe "
AGE : 6
NEXT: 1462808
o To examine one component of a designated object, you can omit
.ALL from the selected component syntax. For example:
DBG> EXAMINE A.NAME
EXAMPLE.A.ALL.NAME(1..10): "John Doe "
The following example shows the debugger support for incomplete
types. Consider the following declarations:
package P is
type T is private;
private
type T_TYPE;
type T is access T_TYPE;
end P;
package body P is
type T_TYPE is
record
A: NATURAL := 5;
B: NATURAL := 4;
end record;
T_REC: T_TYPE;
T_PTR: T := new T_TYPE'(T_REC);
end P;
with P; use P;
procedure INCOMPLETE is
VAR: T;
begin
. . .
end INCOMPLETE;
The debugger does not have complete information about the type T,
so you cannot manipulate the variable VAR. However, the debugger
does have information about objects declared in the package body
P. Thus, you can manipulate the variables T_PTR and T_REC.
4 Module_Names_and_Path_Names
The names of Ada debugger modules are the same as the names
of the corresponding compilation units, with the following
provision. To eliminate ambiguity, an underscore character (_)
is appended to a specification name to distinguish it from its
body name. For example, TEST (body), TEST_ (specification). To
determine the exact names of the modules in your program, use the
SHOW MODULE command.
In most cases when you specify a path name, the debugger can
distinguish body names and specification names from the context.
Therefore, use this naming convention only if needed to resolve
an ambiguity.
When the debugger language is set to Ada, the debugger generally
constructs pathnames that follow the Ada rules, using selected
component notation to separate path name elements (with other
languages, a backslash is used to separate elements). For
example:
TEST_.A1 ! A1 is declared in the package
! specification of unit TEST
TEST.B1 ! B1 is declared in the package
! body of unit TEST
The maximum length that you can specify for a subunit path name
(expanded name) is 247 characters.
When a use clause makes a symbol declared in a package directly
visible outside the package, you do not need to specify an
expanded name (package-name.symbol) to refer to the symbol,
either in the program itself or in debugger commands.
The SHOW SYMBOL/USE_CLAUSE command identifies any package
(library or otherwise) that a specified block, subprogram, or
package mentions in a use clause. If the entity specified is a
package (library or otherwise), the command also identifies any
block, subprogram, package, and so on, that names the specified
module in a use clause. For example:
DBG> SHOW SYMBOL/USE_CLAUSE B_
package spec B_
used by: F
uses: A_
If a label has been assigned to a loop statement or declare block
in the source code, the debugger displays the label; otherwise,
the debugger displays LOOP$n for a loop statement or BLOCK$n
for a declare block, where n is the line number at which the
statement or block begins.
4 Symbol_Lookup_Conventions
For Ada programs, when you do not specify a path name (including
an Ada expanded name), the debugger searches the run-time symbol
table as follows.
1. The debugger looks for the symbol within the block or routine
surrounding the current PC value (where execution is currently
paused).
2. If the symbol is not found, the debugger then searches any
package that is mentioned in a use clause. The debugger does
not distinguish between a library package and a package whose
declaration is in the same module as the current scope region.
If the same symbol is declared in two or more packages that
are visible, the symbol is not unique (according to Ada
rules), and the debugger issues a message similar to the
following:
%DEBUG-E-NOUNIQUE, symbol 'X' is not unique
3. If the symbol is still not found, the debugger searches the
call stack and other scopes, as for other languages.
4 Setting_Modules
When you or the debugger sets an Ada module, by default the
debugger also sets any "related" module (that is, any module
whose symbols should be visible within the module being set).
Such modules are related to the one being set through either a
with-clause or a subunit relationship.
Related module setting takes place as follows. If M1 is the
module that is being set, then the following modules are
considered related and are also set:
o If M1 is a library body, the debugger also sets the associated
library specification, if any.
o If M1 is a subunit, the debugger also sets its parent unit
and, therefore, any parent of the parent.
o If M1 mentions a library package P1 in a with clause, the
debugger also sets P1's specification. Neither the body of
P1 nor any possible subunits of P1 are set, because symbols
declared within them should not be visible outside.
If P1's specification mentions a package P2 in a with clause,
the debugger also sets P2's specification. Likewise, if
P2's specification mentions a package P3 in a with clause,
the debugger also sets P3's specification, and so on. The
specifications of all such library packages are set so
that you can access data components (for example, record
components) that may have been declared in other packages.
o If M1 mentions a library subprogram in a with clause, the
debugger does not set the subprogram. Only the subprogram
name needs to be visible in M1 (no declaration within a
library subprogram should be visible outside the subprogram).
Therefore, the debugger inserts the name of the library
subprogram into the RST when M1 is set.
If debugger performance becomes a problem as more modules are
set, use the SET MODE NODYNAMIC command, which disables related
module setting as well as dynamic module setting. You must then
set individual modules explicitly with the SET MODULE command.
By default, the SET MODULE command sets related modules
simultaneously with the module specified in the command.
The SET MODULE/NORELATED command sets only the modules you
specify explicitly. However, if you use SET MODULE/NORELATED, you
may find that a symbol that is declared in another unit and that
should be visible at the point of execution is no longer visible
or that a symbol which should be hidden by a redeclaration of
that same symbol is now visible.
The CANCEL MODULE/NORELATED command deletes from the RST only
the modules you specify explicitly. This command, which is the
default, deletes related modules in a manner consistent with
the intent of Ada's scope and visibility rules. The exact effect
depends on module relationships.
The distinction between related and directly related for subunits
is analogous to that for library packages.
5 Setting_Modules_for_Package_Bodies
Modules for package bodies are not automatically set by the
debugger.
You may need to set the modules for library package bodies
yourself so that you can debug the package body or debug
subprograms declared in the corresponding package specification.
4 Resolving_Overloaded_Names_and_Symbols
When you encounter overloaded names and symbols, the debugger
issues a message like the following:
%DEBUG-E-NOTUNQOVR, symbol 'ADD' is overloaded
use SHOW SYMBOL to find the unique symbol names
If the overloaded symbol is an enumeration literal, you can use
qualified expressions to resolve the overloadings.
If the overloaded symbol represents a subprogram or task accept
statement, you can use the unique name generated by the compiler
for the debugger. The compiler always generates unique names for
subprograms declared in library package specifications, because
the names might later be overloaded in the package body. Unique
names are generated for task accept statements and subprograms
declared in other places only if the task accept statements or
subprograms are actually overloaded.
Overloaded task accept statement names and subprogram names are
distinguished by a suffix consisting of two underscores followed
by an integer that uniquely identifies the given symbol. You must
use the unique naming notation in debugger commands to uniquely
specify a subprogram whose name is overloaded. However, if there
is no ambiguity, you do not need to use the unique name, even
though one was generated.
4 CALL_Command
With Ada programs, you can use the CALL command reliably only
with a subprogram that has been exported. An exported subprogram
must be a library subprogram or must be declared in the outermost
declarative part of a library package.
The CALL command does not check whether or not the subprogram can
be exported, nor does it check the parameter-passing mechanisms
that you specify. Note that you cannot use the CALL command to
modify the value of a parameter.
A CALL command may result in a deadlock if it is entered when the
Ada run-time library is executing. The run-time library routines
acquire and release internal locks that allow the routines to
operate in a tasking environment. Deadlock can result if a
subprogram called from the CALL command requires a resource
that has been locked by an executing run-time library routine.
To avoid this situation in a nontasking program, enter the CALL
command immediately before or after an Ada statement has been
executed. However, this approach is not sufficient to assure
that deadlock will not occur in a tasking program, as some other
task may be executing a run-time library routine at the time of
the call. If you must use the CALL command in a tasking program,
you can avoid deadlock if the called subprogram does not do any
tasking or input-output operations.
3 BASIC
The following subtopics describe debugger support for BASIC.
4 Operators_in_Language_Expressions
Supported BASIC operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition, String concatenation
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
BASIC follow:
Symbol Construct
( ) Subscripting
:: Record component selection
4 Data_Types
Supported BASIC data types follow:
BASIC Data Type Operating System Data Type Name
BYTE Byte Integer (B)
WORD Word Integer (W)
LONG Longword Integer (L)
SINGLE F_Floating (F)
DOUBLE D_Floating (D)
GFLOAT G_Floating (G)
HFLOAT (VAX specific) H_Floating (H)
DECIMAL Packed Decimal (P)
STRING ASCII Text (T)
RFA (None)
RECORD (None)
Arrays (None)
4 Compiling_for_Debugging
If you make changes to a program in the BASIC environment and
attempt to compile the program with the /DEBUG qualifier without
first saving or replacing the program, BASIC signals the error
"Unsaved changes, no source line debugging available." To avoid
this problem, save or replace the program, and then recompile the
program with the /DEBUG qualifier.
4 Constants
BASIC constants of the form [radix]"numeric-string"[type] (such
as "12.34"GFLOAT) or the form n% (such as 25% for integer 25) are
not supported in debugger expressions.
4 Evaluating_Expressions
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.
4 Line_Numbers
The sequential line numbers that you refer to in a debugging
session and that are displayed in a source code display are
those generated by the compiler. When a BASIC program includes
or appends code from another file, the included lines of code are
also numbered in sequence by the compiler.
4 Stepping_into_Routines
The STEP/INTO command is useful for examining external functions.
However, if you use this command to stop execution at an internal
subroutine or a DEF, the debugger initially steps into run-time
library (RTL) routines, providing you with no useful information.
In the following example, execution is paused at line 8, at a
call to Print_routine:
. . .
-> 8 GOSUB Print_routine
9 STOP
. . .
20 Print_routine:
21 IF Competition = Done
22 THEN PRINT "The winning ticket is #";Winning_ticket
23 ELSE PRINT "The game goes on."
24 END IF
25 RETURN
A STEP/INTO command would cause the debugger to step into the
relevant RTL code and would inform you that no source lines
are available for display. On the other hand, a STEP command
alone would cause the debugger to proceed directly to source
line 9, past the call to Print_routine. To examine the source
code of subroutines or DEF functions, set a breakpoint on the
routine label (for example, enter the SET BREAK PRINT_ROUTINE
command). You can then suspend execution exactly at the start
of the routine (line 20, in this example) and then step directly
into the code.
4 Symbolic_References
All variable and label names within a single BASIC program must
be unique. Otherwise the debugger cannot resolve the symbol
ambiguity.
4 Watchpoints
In BASIC, you can set a watchpoint only on variables that are
declared in COMMON or MAP statements (static variables). You
cannot set watchpoints on variables explicitly declared with the
DECLARE statement.
3 BLISS
The following subtopics describe debugger support for BLISS.
4 Operators_in_Language_Expressions
Supported BLISS operators in language expressions include:
Kind Symbol Function
Prefix . Indirection
Prefix + Unary plus
Infix + Addition
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
BLISS follow:
Symbol Construct
[ ] Subscripting
[fldname] Field selection
<p,s,e> Bit field selection
4 Data_Types
Supported BLISS data types follow:
BLISS Data Type Operating System Data Type Name
BYTE Byte Integer (B)
WORD Word Integer (W)
LONG Longword Integer (L)
QUAD (Alpha specific) Quadword (Q)
BYTE UNSIGNED Byte Unsigned (BU)
WORD UNSIGNED Word Unsigned (WU)
LONG UNSIGNED Longword Unsigned (LU)
QUAD UNSIGNED (Alpha Quadword Unsigned (QU)
specific)
VECTOR (None)
BITVECTOR (None)
BLOCK (None)
BLOCKVECTOR (None)
REF VECTOR (None)
REF BITVECTOR (None)
REF BLOCK (None)
REF BLOCKVECTOR (None)
3 CC
The following subtopics describe debugger support for C.
4 Operators_in_Language_Expressions
Supported C operators in language expressions include:
Kind Symbol Function
Prefix * Indirection
Prefix & Address of
Prefix sizeof size of
Infix + Addition
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
(tilde)
Infix & Bit-wise AND
Infix | Bit-wise OR
Infix ^ Bit-wise exclusive OR
Prefix ! Logical NOT
Infix && Logical AND
Infix || Logical OR
Because 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 an
exclamation point (!) as a comment delimiter if it is the first
nonspace 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 "*" is synonymous to
prefix "." or "@" when the language is set to C.
The debugger does not support any of the assignment operators
in C (or any other language) in order to prevent unintended
modifications to the program being debugged. Hence such operators
as =, +=, ++, and -- are not recognized. To alter the contents of
a memory location, you must use an explicit DEPOSIT command.
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for C
follow:
Symbol Construct
[ ] Subscripting
. Structure component selection
(period)
-> Pointer dereferencing
4 Data_Types
Supported C data types follow:
C Data Type Operating System Data Type Name
__int64 (Alpha specific) Quadword Integer (Q)
unsigned __int64 (Alpha Quadword Unsigned (QU)
specific)
__int32 (Alpha specific) Longword Integer (L)
unsigned __int32 (Alpha Longword Unsigned (LU)
specific)
int Longword Integer (L)
unsigned int Longword Unsigned (LU)
__int16 (Alpha specific) Word Integer (W)
unsigned __int16 (Alpha Word Unsigned (WU)
specific)
short int Word Integer (W)
unsigned short int Word Unsigned (WU)
char Byte Integer (B)
unsigned char Byte Unsigned (BU)
float F_Floating (F)
__f_float (Alpha F_Floating (F)
specific)
double D_Floating (D)
double G_Floating (G)
__g_float (Alpha G_Floating (G)
specific)
float (Alpha specific) IEEE S_Floating (FS)
__s_float (Alpha IEEE S_Floating (FS)
specific)
double (Alpha specific) IEEE T_Floating (FT)
__t_float (Alpha IEEE T_Floating (FT)
specific)
enum (None)
struct (None)
union (None)
Pointer Type (None)
Array Type (None)
Floating-point numbers of type float may be represented by F_
Floating or IEEE S_Floating, depending on compiler switches.
Floating-point numbers of type double may be represented by IEEE
T_Floating, D_Floating, or G_Floating, depending on compiler
switches.
4 Case_Sensitivity
Symbol names are case sensitive for language C, meaning that
uppercase and lowercase letters are treated as different
characters.
4 Static_and_Nonstatic_Variables
Variables of the following storage classes are allocated
statically: static, globaldef, globalref, and extern.
Variables of the following storage classes are allocated
nonstatically (on the stack or in registers): auto and register.
Such variables can be accessed only when their defining routine
is active (on the call stack).
4 Scalar_Variables
You can specify scalar variables of any C type in debugger
commands exactly as you would specify them in the source code
of the program.
The following paragraphs provide additional information about
char variables and pointers.
The char variables are interpreted by the debugger as byte
integers, not ASCII characters. To display the contents of a char
variable ch as a character, you must use the /ASCII qualifier:
DBG> EXAMINE/ASCII ch
SCALARS\main\ch: "A"
You also must use the /ASCII qualifier when depositing into
a char variable, to translate the byte integer into its ASCII
equivalent. For example:
DBG> DEPOSIT/ASCII ch = 'z'
DBG> EXAMINE/ASCII ch
SCALARS\main\ch: "z"
The following example shows use of pointer syntax with the
EXAMINE command. Assume the following declarations and
assignments:
static long li = 790374270;
static int *ptr = &li;
DBG> EXAMINE *ptr
*SCALARS\main\ptr: 790374270
4 Arrays
The debugger handles C arrays as for most other languages. That
is, you can examine an entire array aggregate, a slice of an
array, or an individual array element, using array syntax (for
example EXAMINE arr[3]). And you can deposit into only one array
element at a time.
4 Character_Strings
Character strings are implemented in C as null-terminated ASCII
strings (ASCIZ strings). To examine and deposit data in an entire
string, use the /ASCIZ (or /AZ) qualifier so that the debugger
can interpret the end of the string properly. You can examine
and deposit individual characters in the string using the C
array subscripting operators ([ ]). When you examine and deposit
individual characters, use the /ASCII qualifier.
Assume the following declarations and assignments:
static char *s = "vaxie";
static char **t = &s;
The EXAMINE/AZ command displays the contents of the character
string pointed to by *s and **t:
DBG> EXAMINE/AZ *s
*STRING\main\s: "vaxie"
DBG> EXAMINE/AZ **t
**STRING\main\t: "vaxie"
The DEPOSIT/AZ command deposits a new ASCIZ string in the
variable pointed to by *s. The EXAMINE/AZ command displays the
new contents of the string:
DBG> DEPOSIT/AZ *s = "DEC C"
DBG> EXAMINE/AZ *s, **t
*STRING\main\s: "DEC C"
**STRING\main\t: "DEC C"
You can use array subscripting to examine individual characters
in the string and deposit new ASCII values at specific locations
within the string. When accessing individual members of a string,
use the /ASCII qualifier. A subsequent EXAMINE/AZ command shows
the entire string containing the deposited value:
DBG> EXAMINE/ASCII s[3]
[3]: " "
DBG> DEPOSIT/ASCII s[3] = "-"
DBG> EXAMINE/AZ *s, **t
*STRING\main\s: "VAX-C"
**STRING\main\t: "VAX-C"
4 Structures_and_Unions
You can examine structures in their entirety or on a member-by-
member basis, and deposit data into structures one member at a
time.
To reference members of a structure or union, use the usual C
syntax for such references. That is, if variable p is a pointer
to a structure, you can reference member y of that structure with
the expression p ->y. If variable x refers to the base of the
storage allocated for a structure, you can refer to a member of
that structure with the x.y expression.
The debugger uses C type-checking rules to reference members of
a structure or union. For example, in the case of x.y, y need
not be a member of x; it is treated as an offset with a type.
When such a reference is ambiguous-when there is more than one
structure with a member y-the debugger attempts to resolve the
reference according to the following rules. The same rules for
resolving the ambiguity of a reference to a member of a structure
or union apply to both x.y and p ->y.
o If only one of the members, y, belongs in the structure or
union, x, that is the one that is referenced.
o If only one of the members, y, is in the same scope as x, then
that is the one that is referenced.
You can always give a path name with the reference to x to narrow
the scope that is used and to resolve the ambiguity. The same
path name is used to look up both x and y.
3 C++_V5.5_and_Later
(Alpha only.)
On Alpha systems, the OpenVMS debugger provides enhanced support
for debugging C++ modules compiled with the Version 5.5 compiler
or later (Alpha only).
The debugger supports the following C++ features:
o C++ names and expressions, including:
- Explicit and implicit this pointer to refer to class
members
- Scope resolution operator (::)
- Member access operators: period (.) and right arrow (->)
- Template instantiations
o Setting breakpoints in:
- Member functions, including static and virtual functions
- Overloaded functions
- Constructors and destructors
- Template instantiations
- Operators
o Calling functions, including overloaded functions
o Debugging programs containing a mixture of C++ code and code
in other languages
The following subtopics describe debugger support for C++
(Compiler Version 5.5 (Alpha only)).
4 Operators_in_Language_Expressions
Supported C++ operators in language expressions follow:
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
(tilde)
Infix & Bit-wise AND
Infix | Bit-wise OR
Infix ^ Bit-wise exclusive OR
Prefix ! Logical NOT
Infix && Logical AND
Infix || Logical OR
Because the exclamation point (!) is an operator, it cannot be
used in C++ programs as a comment delimiter. However, to permit
debugger log files to be used as debugger input, the debugger
interprets ! as a comment delimiter when it is the first nonspace
character on a line. In C++ language mode, the debugger also
interprets /* or // as preceding a comment that continues to the
end of the current line.
The debugger accepts the asterisk (*) prefix as an indirection
operator in both C++ language expressions and debugger address
expressions. In address expressions, the * prefix is synonymous
with either the period (.) prefix or at sign (@) prefix when the
debugger is in C++ language mode.
To prevent unintended modifications to the program being
debugged, the debugger does not support any of the assignment
operators in C++ (or any other language). Thus, such operators
as =, +=, -=, ++, and -- are not recognized in debugger commands.
To alter the contents of a memory location, you must use the
debugger DEPOSIT command.
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for C++
follow:
Symbol Construct
[ ] Subscripting
. Structure component selection
(period)
-> Pointer dereferencing
:: Scope resolution
4 Data_Types
Supported C++ data types follow:
C++ Data Type Operating System Data Type Name
__int64 (Alpha) Quadword Integer (Q)
unsigned __int64 (Alpha) Quadword Unsigned (QU)
__int32 (Alpha) Longword Integer (L)
unsigned __int32 (Alpha) Longword Unsigned (LU)
int Longword Integer (L)
unsigned int Longword Unsigned (LU)
__int16 (Alpha) Word Integer (W)
unsigned __int16 (Alpha) Word Unsigned (WU)
short int Word Integer (W)
unsigned short int Word Unsigned (WU)
char Byte Integer (B)
unsigned char Byte Unsigned (BU)
float F_Floating (F)
__f_float (Alpha) F_Floating (F)
double D_Floating (D)
double G_Floating (G)
__g_float (Alpha) G_Floating (G)
float (Alpha) IEEE S_Floating (FS)
__s_float (Alpha) IEEE S_Floating (FS)
double (Alpha) IEEE T_Floating (FT)
__t_float (Alpha) IEEE T_Floating (FT)
enum (None)
struct (None)
class (None)
union (None)
Pointer Type (None)
Array Type (None)
Floating-point numbers of type float may be represented by F_
Floating or IEEE S_Floating, depending on compiler switches.
Floating-point numbers of type double may be represented by IEEE
T_Floating, D_Floating, or G_Floating, depending on compiler
switches.
4 Case_Sensitivity
Symbol names are case sensitive in C++. This means that uppercase
and lowercase letters are treated as different characters.
4 Displaying_Information_About_a_Class
Use the command SHOW SYMBOL to display static information about
a class declaration. Use the command EXAMINE to view dynamic
information about class objects (see Displaying Information About
an Object).
The command SHOW SYMBOL/FULL displays the class type declaration,
including:
Data members (including static data members)
Member functions (including static member functions)
Constructors and destructors
Base classes and derived classes
For example:
dbg> SHOW SYMBOL /TYPE C
type C
struct (C, 13 components), size: 40 bytes
overloaded name C
instance C::C(void)
instance C::C(const C &)
dbg> SHOW SYMBOL /FULL C
type C
struct (C, 13 components), size: 40 bytes
inherits: B1, size: 24 bytes, offset: 0 bytes
B2, size: 24 bytes, offset: 12 bytes
contains the following members:
overloaded name C::g
instance C::g(int)
instance C::g(long)
instance C::g(char)
j : longword integer, size: 4 bytes, offset: 24 bytes
s : longword integer, size: 4 bytes, address: # [static]
overloaded name C
int ==(C &)
C & =(const C &)
void h(void) [virtual]
~C(void)
__vptr : typed pointer type, size: 4 bytes, offset: 4 bytes
__bptr : typed pointer type, size: 4 bytes, offset: 8 bytes
structure has been padded, size: 4 bytes, offset: 36 bytes
overloaded name C
instance C::C(void)
instance C::C(const C &)
DBG>
Note that SHOW SYMBOL/FULL does not display members of base
classes or derived classes. Use the commands SHOW SYMBOL/FULL
base_class_name and SHOW SYMBOL/FULL derived_class_name to
display information about members of those classes. For example:
DBG> SHOW SYMBOL /FULL B1
type B1
struct (B1, 8 components), size: 24 bytes
inherits: virtual A
is inherited by: C
contains the following members:
i : longword integer, size: 4 bytes, offset: 0 bytes
overloaded name B1
void f(void)
B1 & =(const B1 &)
void h(void) [virtual]
__vptr : typed pointer type, size: 4 bytes, offset: 4 bytes
__bptr : typed pointer type, size: 4 bytes, offset: 8 bytes
structure has been padded, size: 12 bytes, offset: 12 bytes
overloaded name B1
instance B1::B1(void)
instance B1::B1(const B1 &)
DBG>
Use the command SHOW SYMBOL/FULL class_member_name to display
information about class members. For example:
DBG> SHOW SYMBOL /FULL j
record component C::j
address: offset 24 bytes from beginning of record
atomic type, longword integer, size: 4 bytes
record component A::j
address: offset 4 bytes from beginning of record
atomic type, longword integer, size: 4 bytes
DBG>
Use the SHOW SYMBOL/FULL command to display detailed information
about an object.
Note that SHOW SYMBOL does not currently support qualified names.
For example, the following commands are not currently supported:
SHOW SYMBOL object_name.function_name
SHOW SYMBOL class_name::member_name
4 Displaying_Information_About_an_Object
The debugger uses C++ symbol lookup rules to display information
about objects. Use the command EXAMINE to display the current
value of an object. For example:
DBG> EXAMINE a
CXXDOCEXAMPLE\main\a: struct A
i: 0
j: 1
__vptr: 131168
DBG>
You can also display individual object members using the member
access operators, period (.) and right arrow (->), with the
EXAMINE command. For example:
DBG> EXAMINE ptr
CXXDOCEXAMPLE\main\ptr: 40
DBG> EXAMINE *ptr
*CXXDOCEXAMPLE\main\ptr: struct A
i: 0
j: 1
__vptr: 131168
DBG> EXAMINE a.i
CXXDOCEXAMPLE\main\a.i: 0
DBG> EXAMINE ptr->i
CXXDOCEXAMPLE\main\ptr->i: 0
DBG>
The debugger correctly interprets virtual inheritance. For
example:
DBG> EXAMINE c
CXXDOCEXAMPLE\main\c: struct C
inherit B1
inherit virtual A
i: 8
j: 9
__vptr: 131200
i: 10
__vptr: 131232
__bptr: 131104
inherit B2
inherit virtual A (already printed, see above)
i: 11
__vptr: 131280
__bptr: 131152
j: 12
__vptr: 131232
__bptr: 131104
DBG>
Use the scope resolution operator (::) to reference global
variables, to reference hidden members in base classes, to
explicitly reference a member that is inherited, or otherwise
to name a member hidden by the current context. For example:
DBG> EXAMINE c.j
CXXDOCEXAMPLE\main\c.j: 12
DBG> EXAMINE c.A::j
CXXDOCEXAMPLE\main\c.A::j: 9
DBG> EXAMINE x
CXXDOCEXAMPLE\main\x: 101
DBG> EXAMINE ::x
CXXDOCEXAMPLE\x: 13
DBG>
To resolve ambiguous member references, the debugger lists the
members that satisfy the reference and requests an unambiguous
reference to the member. For example:
DBG> EXAMINE c.i
%DEBUG-I-AMBIGUOUS, 'i' is ambiguous, matching the following
CXXDOCEXAMPLE\main\c.B1::i
CXXDOCEXAMPLE\main\c.B2::i
%DEBUG-E-REENTER, reenter the command using a more precise pathname
DBG> EXAMINE c.B1::i
CXXDOCEXAMPLE\main\c.B1::i: 10
DBG>
Use the scope resolution operator (::) to refer to static data
members. For example:
DBG> EXAMINE c.s
CXXDOCEXAMPLE\main\c.s: 42
DBG> EXAMINE C::s
C::s: 42
DBG>
Use the SHOW SYMBOL/FULL to display the class type of an object
(see Displaying Information About a Class).
4 Setting_Watchpoints
You can set watchpoints on objects. All nonstatic data members
are watched (including those in base classes). Static data
members are not watched when you set a watchpoint on the object.
However, you can explicitly set watchpoints on static data
members. For example:
DBG> SET WATCH c
%DEBUG-I-WPTTRACE, non-static watchpoint, tracing every instruction
DBG> GO
watch of CXXDOCEXAMPLE\main\c.i at CXXDOCEXAMPLE\main\%LINE 50+8
50: c.B2::i++;
old value: 11
new value: 12
break at CXXDOCEXAMPLE\main\%LINE 51
51: c.s++;
DBG> SET WATCH c.s
DBG> GO
watch of CXXDOCEXAMPLE\main\c.s at CXXDOCEXAMPLE\main\%LINE 51+16
51: c.s++;
old value: 43
new value: 44
break at CXXDOCEXAMPLE\main\%LINE 53
53: b1.f();
DBG>
4 Debugging_Functions
The debugger uses C++ symbol lookup rules to display information
on member functions. For example:
DBG> EXAMINE /SOURCE b1.f
module CXXDOCEXAMPLE
14: void f() {}
DBG> SET BREAK B1::f
DBG> GO
break at routine B1::f
14: void f() {}
DBG>
The debugger correctly interprets references to the this pointer.
For example:
DBG> EXAMINE this
B1::f::this: 16
DBG> EXAMINE *this
*B1::f::this: struct B1
inherit virtual A
i: 2
j: 3
__vptr: 131184
i: 4
__vptr: 131248
__bptr: 131120
DBG> EXAMINE this->i
B1::f::this->i: 4
DBG> EXAMINE this->j
B1::f::this->A::j: 3
DBG>EXAMINE i
B1::f::this->i: 4
DBG> EXAMINE j
B1::f::this->A::j: 3
DBG>
The debugger correctly references virtual member functions. For
example:
DBG> EXAMINE /SOURCE %LINE 53
module CXXDOCEXAMPLE
53: b1.f();
DBG> SET BREAK this->h
DBG> SHOW BREAK
breakpoint at routine B1::f
breakpoint at routine B1::h
!!
!! We are at the call to B1::f made at 'c.B1::f()'.
!! Here this->h matches C::h.
!!
DBG> GO
break at routine B1::f
14: void f() {}
DBG> EXAMINE /SOURCE %LINE 54
module CXXDOCEXAMPLE
54: c.B1::f();
DBG> SET BREAK this->h
DBG> SHOW BREAK
breakpoint at routine B1::f
breakpoint at routine B1::h
breakpoint at routine C::h
!!
!! Handling overloaded functions
!!
DBG> SET BREAK g
%DEBUG-I-NOTUNQOVR, symbol 'g' is overloaded
overloaded name C::g
instance C::g(int)
instance C::g(long)
instance C::g(char)
%DEBUG-E-REENTER, reenter the command using a more precise pathname
DBG> SET BREAK g(int)
DBG> CANCEL BREAK/ALL
DBG>
If you try to set a break on an overloaded function, the debugger
lists the instances of the function and requests that you specify
the correct instance. For example, with Debugger Version 7.2:
DBG> SET BREAK g
%DEBUG-I-NOTUNQOVR, symbol 'g' is overloaded
overloaded name C::g
instance void g(int)
instance void g(long)
instance void g(char *)
%DEBUG-E-REENTER, reenter the command using a more precise pathname
DBG> SET BREAK g(int)
DBG>
NOTE
The means of displaying and specifying overloaded functions
is different than in the OpenVMS Debugger Version 7.1C.
The debugger provides support for debugging constructors,
destructors, and operators. For example:
DBG> SET BREAK C
%DEBUG-I-NOTUNQOVR, symbol 'C' is overloaded
overloaded name C
instance C::C(void)
instance C::C(const C &)
%DEBUG-E-REENTER, reenter the command using a more precise pathname
DBG> SHOW SYMBOL /FULL ~C
routine C::~C
type signature: ~C(void)
code address: #, size: 152 bytes
procedure descriptor address: #
DBG> SET BREAK %NAME'~C'
DBG> SET BREAK %NAME'=='
%DEBUG-W-UNALLOCATED, '==' is not allocated in memory (optimized away)
%DEBUG-E-CMDFAILED, the SET BREAK command has failed
DBG> SHOW SYMBOL /FULL ==
routine C::==
type signature: int ==(C &)
address: unallocated
DBG> SHOW BREAK
breakpoint at routine C::~C
DBG>
4 Limitations_on_Debugger_Support_for_C++
The following limitations apply when you debug a C++ program:
o You cannot specify a template by name in a debugger command.
You must use the name of the instantiation of the template.
o In C++, expressions in the instantiated template name can be
full constant expressions, such as stack<double,f*10>. This
form is not yet supported in the debugger; you must enter the
value of the expression (for example, if f is 10 in the stack
example, you must enter 100).
3 C++
The following subtopics describe debugger support for C++
programs compiled with C++ compiler versions prior to Version
5.5.
4 The_%name_Lexical_Function
Use of the %name lexical function is required with debugger
commands to reference certain entities in Compaq C++, such as
functions and data members. When used, this function is always
placed between the command and the reference. Examples of correct
usage are shown in the following sections for cases where its use
is required.
4 Operators_in_Language_Expressions
Supported C++ operators in language expressions include:
Kind Symbol Function
Prefix * Indirection
Prefix & Address of
Prefix sizeof size of
Infix + Addition
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
(tilde)
Infix & Bit-wise AND
Infix | Bit-wise OR
Infix ^ Bit-wise exclusive OR
Prefix ! Logical NOT
Infix && Logical AND
Infix || Logical OR
Because the exclamation point (!) is an operator, it cannot be
used in C++ programs as a comment delimiter. However, to permit
debugger log files to be used as debugger input, the debugger
still recognizes an exclamation point as a comment delimiter if
it is the first nonspace character on a line. In C++ language
mode, the debugger accepts /* as the comment delimiter. The
comment continues to the end of the current line. (A matching
*/ is neither needed nor recognized.)
The debugger accepts the asterisk (*) prefix as an indirection
operator in both C++ language expressions and debugger address
expressions. In address expressions, the * prefix is synonymous
to the period (.) prefix or at sign @ prefix when the language is
set to C++.
To prevent unintended modifications to the program being
debugged, the debugger does not support any of the assignment
operators in C++ (or any other language). Thus, such operators
as =, +=, ++, and -- are not recognized. To alter the contents
of a memory location, you must do so with an explicit deposit
command.
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for C++
follow:
Symbol Construct
[ ] Subscripting
. Structure component selection
(period)
-> Pointer dereferencing
4 Data_Types
Supported C++ data types follow:
C++ Data Type Operating System Data Type Name
__int64 (Alpha specific) Quadword Integer (Q)
unsigned __int64 (Alpha Quadword Unsigned (QU)
specific)
__int32 (Alpha specific) Longword Integer (L)
unsigned __int32 (Alpha Longword Unsigned (LU)
specific)
int Longword Integer (L)
unsigned int Longword Unsigned (LU)
__int16 (Alpha specific) Word Integer (W)
unsigned __int16 (Alpha Word Unsigned (WU)
specific)
short int Word Integer (W)
unsigned short int Word Unsigned (WU)
char Byte Integer (B)
unsigned char Byte Unsigned (BU)
float F_Floating (F)
__f_float (Alpha F_Floating (F)
specific)
double D_Floating (D)
double G_Floating (G)
__g_float (Alpha G_Floating (G)
specific)
float (Alpha specific) IEEE S_Floating (FS)
__s_float (Alpha IEEE S_Floating (FS)
specific)
double (Alpha specific) IEEE T_Floating (FT)
__t_float (Alpha IEEE T_Floating (FT)
specific)
enum (None)
struct (None)
union (None)
Pointer Type (None)
Array Type (None)
Floating-point numbers of type float may be represented by F_
Floating or IEEE S_Floating, depending on compiler switches.
Floating-point numbers of type double may be represented by IEEE
T_Floating, D_Floating, or G_Floating, depending on compiler
switches.
4 Case_Sensitivity
Symbol names are case sensitive for C++, meaning that uppercase
and lowercase letters are treated as different characters.
4 Qualified_Class_Names
Discussions in some of the following sections use the term
qualified class names to describe how to compose the names of
class members when using the debugger. If a class is not defined
within another class, the qualified class name is merely the name
of the class itself. However, if a class is nested within another
class, the name of the immediately containing class must precede
it, separated with a pair of colons (::). If the containing class
is itself nested, its name must be prefixed, and so on.
The following are examples of properly qualified class names:
DBG> set break %name 'C::f' ! f is a member of class C
DBG> set break %name 'FOO::BAR::BAZ::g' ! g is a member of BAZ,
! which is nested in BAR,
! which is nested in FOO
4 Using_the_Debugger_with_C++_Data
This section describes how to use the debugger with C++ data.
5 Nonstatic_Data_Members
This section describes how to refer to data members that are not
declared static.
6 Noninherited_Data_Members
To refer to a nonstatic data member that is defined directly in a
C++ class (or a struct or union), use its name just as with a C
language struct or union member. The following example shows the
correct use of a nonstatic data member reference:
DBG> examine x.m, p->m
6 Inherited_Data_Members
Currently, debugger support distinguishes nonstatic data members
inherited from various base classes by prefixing their names with
a sequence of significant base class names on the inheritance
path to the member, and then the class that the member is
declared in. A base class on a path from an object to a member
is significant if the base class in question is derived from
using multiple inheritances. Thus, a base class is significant
if it is mentioned in a base list containing more than one base
specifier.
This notation generates the minimum number of base class prefixes
necessary to describe the inheritance path to a base class,
because it involves naming only those base classes where one
must choose where to proceed next when traversing the path. When
no multiple inheritance is involved, the reference is of the
following form:
%name'CLASS::member'
To refer to nonstatic data members inherited from base classes
of an object, quote the sequence of significant qualified base
class names and the member name (separated by double colons)
with %name. Specify the sequence of significant base classes, in
the order from the object's most derived significant class, to
the significant base class closest to the object. For example,
consider the inheritance graph for the following declarations:
struct A { int a_member; };
struct B : A { int b_member; };
struct C { int c_member; };
struct D : B, C { int d_member; };
struct E : D { int e_member; };
struct F { int f_member; };
struct G : F { int g_member; };
struct H : E, G { int h_member; };
struct I : H { int i_member; };
struct J : I { int j_member; };
static J j_object;
Because classes B, C, E and G are mentioned in base lists, which
involve multiple inheritance, they are the significant classes
that appear as prefixes. The following examples are references to
all the members through debugger deposit commands. Note that
the class of the inherited member itself appears before the
member name, regardless of whether or not the member belongs
to a significant class.
6 Inherited_Virtual_Data_Members
In the debugger, symbolic access to data members of virtual base
classes is currently not supported. The one exception to this is
that the pointer member named __bptr is present in such objects.
5 Static_Data_Members
To refer to a static data member, quote its qualified class name,
two colons (::), and then the member name, with %name.
The following examples show the correct use of static data member
references:
DBG> examine %name 'C::s'
DBG> examine %name 'FOO::BAR::BAZ::sdm'
5 Reference_Objects_and_Reference_Members
To access the values of objects declared with a reference, use
the name of the object.
The debugger treats data members declared with a reference type
as though they were pointer variables; thus, you must use the *
or -> dereference operators on their names. For example, consider
the following code:
class C {
public:
int &ref_mem;
C(int &arg) : ref_mem(arg) {}
};
main()
{
auto int obj = 5;
auto int &ref_obj = obj;
auto C c(obj);
obj = 23;
}
.
.
.
The following sequence shows the correct way to use the debugger to
examine the members:
stepped on return from routine REF\main
to REF\main\%LINE 13+16
13: }
DBG> examine obj, ref_obj
REF\main\obj: 23
REF\main\ref_obj: 23
DBG> examine c
REF\main\c
ref_mem: 2144211292
DBG> symbolize c.ref_mem
address 7FCE1154:
REF\main\c
DBG> examine *c.ref_mem
*REF\main\c.ref_mem: 23
5 Pointers_to_Members
Objects that are pointers to members are represented as 64-bit
integers.
5 Referencing_Entities_by_Type
To examine and display the value of an object or member by type,
use the command EXAMINE/TYPE. Similarly, you can modify the value
of an expression to be deposited to a type you specify by using
the DEPOSIT/TYPE command. With the /TYPE qualifier, the syntax
for these commands is as follows:
deposit/type=(name)
examine/type=(name)
The type denoted by name must be the name of a variable or data
type declared in the program. The /type qualifier is particularly
useful for referencing C++ objects that have been declared with
more than one type.
4 Using_the_Debugger_with_C++_Functions
This section describes how to reference the various kinds of
functions and function arguments.
5 Referring_to_Overloaded_Functions
To find the symbolic names of functions in your code, use the
SHOW SYMBOL command. If the function is overloaded, use the
asterisk wildcard character (*) in the name specification to
display the overloaded symbol names.
For example, consider the following code:
class base
{
public:
base();
base( int );
~base();
int base_f1();
void base_f2();
void base_f2( int );
void base_f2( char );
};
The following sequence shows how to display overloaded symbols
and determine the appropriate function reference:
DBG> set break %name 'base::base_f2'
%DEBUG-E-NOTUNQOVR, symbol 'base::base_f2' is overloaded
use SHOW SYMBOL to find the unique symbol names
DBG> show symbol *base_f2
overloaded symbol CXX_T10_179\base::base_f2
overloaded instance CXX_T10_179\base::base_f2__1
overloaded instance CXX_T10_179\base::base_f2__2
overloaded instance CXX_T10_179\base::base_f2__3
DBG> set break %name 'base::base_f2__2'
DBG> step
stepped to CXX_T10_179\main\%LINE 20
20: x.base_f2();
DBG> step
stepped to CXX_T10_179\main\%LINE 21
21: x.base_f2(5);
DBG> step
break at routine CXX_T10_179\base::base_f2__2
12: void base_f2( int ) {}
DBG> step
stepped to CXX_T10_179\main\%LINE 22
22: x.base_f2('W');
stepped to CXX_T10_179\main\%LINE 22
DBG> go
'Normal successful completion'
DBG> ^Z
5 Referring_to_Static_and_Nonstatic_Member_Functions
To refer to a member function, quote, with %name, its qualified
class name, two colons (::), and the name of the member
function. If the member function is overloaded, append the suffix
__integer-number.
The following examples show the correct use of member function
references:
DBG> set break %name 'MYSTRING::length'
DBG> set break %name 'MYCOMPLEX::format__1', %name 'MYCOMPLEX::format__2'
5 Referring_to_Constructors
To refer to a constructor, state the name. If a constructor is
overloaded, append the suffix __integer-number.
The following examples show the correct use of constructor
references:
DBG> set break FOO
DBG> set break MYSTRING__1
5 Referring_to_Destructors
To refer to a destructor, quote its name, including the tilde
(~), with %name.
The following example shows the correct use of a destructor
reference:
DBG> set break %name '~FOO'
5 Referring_to_Conversions
To refer to conversion operators from a class SRC to a type dest,
quote SRC, two colons (::), and then dest with %name.
The set of atomic types is drawn from the following set of names:
void char signed_char unsigned_char signed_short
unsigned_short int signed_int unsigned_int signed_long
unsigned_long float double long_double
Pointer types are named (type*). Reference types are named
(type&). The types struct, union class and enum are named by
their tags and the qualifiers const and volatile precede their
types with a space in between. For example:
DBG> set break %name 'C::int', %name 'C::(const S)&'
5 Referring_to_User-Defined_Operators
The following operators may be overloaded by user-defined
functions:
+ - * / % ^ & | ~ !
= < > += -= *= /= %= ^= &=
|= << >> >>= <<= == != <= >= &&
| ++ -- ->* , -> [] () delete new
See Section 7.2 of The Annotated C++ Reference Manual (shipped
with C++ documentation) for more details.
To refer to such user-defined functions, quote the operator
characters with %name. As with regular functions, prefix the
string quoted by %name with a qualified class name and two
colons (::) if the user-defined operator is a member function.
Similarly, if the function is overloaded, append the suffix
__integer_number to the operator characters. In particular,
this suffix is necessary if both unary and binary instances of
an operator such as + are defined, or if prefix instances of ++
or - are defined.
The following examples show the correct use of user-defined
function references:
DBG> set break %name 'MYSTRING::+'
DBG> set break %name 'COUNTER::++__1', %name 'COUNTER::++__2'
5 Referring_to_Function_Arguments
In debugger referencing, you use this, *this, and this->m as
follows:
o All nonstatic member functions have a pointer parameter
available named this. For example:
DBG> examine this
o Use *this to examine the prefix object that a member function
is invoked against. For example:
DBG> examine *this
o Use the this parameter to refer to a data member m of the
prefix argument to a member function. For example:
DBG> examine this->m
3 COBOL
The following subtopics describe debugger support for COBOL.
4 Operators_in_Language_Expressions
Supported COBOL operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition
Infix * Multiplication
Infix / Division
Infix ** Exponentiation (VAX specific)
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
COBOL follow:
Symbol Construct
( ) Subscripting
OF Record component selection
IN Record component selection
4 Data_Types
Supported COBOL data types follow:
COBOL Data Type Operating System Data Type Name
COMP Longword Integer (L,LU)
COMP Word Integer (W,WU)
COMP Quadword Integer (Q,QU)
COMP-1 F_Floating (F)
COMP-1 (Alpha specific) S_Floating (FS)
COMP-2 D_Floating (D)
COMP-2 (Alpha specific) T_Floating (FT)
COMP-3 Packed Decimal (P)
INDEX Longword Integer (L)
Alphanumeric ASCII Text (T)
Records (None)
Numeric Unsigned Numeric string, unsigned (NU)
Leading Separate Sign Numeric string, left separate sign
(NL)
Leading Overpunched Sign Numeric string, left overpunched sign
(NLO)
Trailing Separate Sign Numeric string, right separate sign
(NR)
Trailing Overpunched Sign Numeric string, right overpunched
sign (NRO)
Floating-point numbers of type COMP-1 may be represented by F_
Floating or IEEE S_Floating, depending on compiler switches.
Floating-point numbers of type COMP-2 may be represented by D_
Floating or IEEE T_Floating, depending on compiler switches.
4 Source_Display
The debugger can show source text included in a program with the
COPY, COPY REPLACING, or REPLACE statement. However, when COPY
REPLACING or REPLACE is used, the debugger shows the original
source text instead of the modified source text generated by the
COPY REPLACING or REPLACE statement.
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.
4 COBOL_INITIALIZE_Statement_and_Large_Tables_(Arrays)_(Alpha_Only)_
On OpenVMS Alpha systems, the debugger can take an unusually
great amount of time and resources if you use the STEP command to
execute an INITIALIZE statement in a COBOL program when a large
table (array) is being initialized.
To work around this problem, set a breakpoint on the first
executable line past the INITIALIZE statement, rather than
stepping across the INITIALIZE statement.
3 DIBOL
(VAX only)
4 Operators_in_Language_Expressions
Supported DIBOL operators in language expressions include:
Kind Symbol Function
Prefix # Round
Prefix + Unary plus
Infix + Addition
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
Infix .NOT. Logical NOT
Infix .AND. Logical AND
Infix .OR. Logical OR
Infix .XOR. Exclusive OR
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
DIBOL follow:
Symbol Construct
( ) Substring
[ ] Subscripting
. Record component selection
(period)
4 Data_Types
Supported DIBOL data types follow:
DIBOL Data
Type Operating System Data Type Name
I1 Byte Integer (B)
I2 Word Integer (W)
I4 Longword Integer (L)
Pn Packed Decimal String (P)
Pn.m Packed Decimal String (P)
Dn Numeric String, Zoned Sign (NZ)
Dn.m Numeric String, Zoned Sign (NZ)
An ASCII Text (T)
Arrays (None)
Records (None)
3 Fortran
The following subtopics describe debugger support for Fortran.
4 Operators_in_Language_Expressions
Supported Fortran operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition
Infix * Multiplication
Infix / Division
Infix ** Exponentiation (VAX specific)
Infix // Concatenation
Infix .EQ. Equal to
Infix == Equal to
Infix .NE. Not equal to
Infix /= Not equal to
Infix .GT. Greater than
Infix > Greater than
Infix .GE. Greater than or equal to
Infix >= Greater than or equal to
Infix .LT. Less than
Infix < Less than
Infix .LE. Less than or equal to
Infix <= 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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
Fortran follow:
Symbol Construct
( ) Subscripting
. (period) Record component selection
% (percent Record component selection
sign)
4 Predefined_Symbols
Supported Fortran predefined symbols follow:
Symbol Description
.TRUE. Logical True
.FALSE. Logical False
4 Data_Types
Supported Fortran data types follow:
Fortran Data Type Operating System Data Type Name
LOGICAL*1 Byte Unsigned (BU)
LOGICAL*2 Word Unsigned (WU)
LOGICAL*4 Longword Unsigned (LU)
LOGICAL*8 (Alpha Quadword Unsigned (QU)
specific)
BYTE Byte (B)
INTEGER*1 Byte Integer (B)
INTEGER*2 Word Integer (W)
INTEGER*4 Longword Integer (L)
INTEGER*8 (Alpha Quadword Integer (Q)
specific)
REAL*4 F_Floating (F)
REAL*4 (Alpha specific) IEEE S_Floating (FS)
REAL*8 D_Floating (D)
REAL*8 G_Floating (G)
REAL*8 (Alpha specific) IEEE T_Floating (FT)
REAL*16 (Alpha specific) H_Floating (H)
COMPLEX*8 F_Complex (FC)
COMPLEX*8 (Alpha IEEE S_Floating (SC)
specific)
COMPLEX*16 D_Complex (DC)
COMPLEX*16 G_Complex (GC)
COMPLEX*16 (Alpha IEEE T_Floating (TC)
specific)
CHARACTER ASCII Text (T)
Arrays (None)
Records (None)
Even though the data type codes for unsigned integers (BU,
WU, LU, QU) are used internally to describe the LOGICAL data
types, the debugger (like the compiler) treats LOGICAL variables
and values as being signed when they are 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, 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*4 and COMPLEX*8 may be
represented by F_Floating or IEEE S_Floating, depending on
compiler switches.
Floating-point numbers of type REAL*8 and COMPLEX*16 may be
represented by D_Floating, G_Floating, or IEEE T_Floating,
depending on compiler switches.
On OpenVMS Alpha systems, the debugger cannot evaluate
expressions that contain complex variables. To work around this
problem, examine the complex variable and then evaluate the
expression using the real and imaginary parts of the complex
variable as shown by the EXAMINE command.
4 Initialization_Code
When you debug a program that compiled with the /CHECK=UNDERFLOW
or /PARALLEL qualifier, a message appears, as in the following
example:
DBG> RUN FORMS
Language: FORTRAN, Module: FORMS
Type GO to reach main program
DBG>
The "Type GO to reach MAIN program" message indicates that
execution is supended before the start of the main program, so
that you can execute initialization code under debugger control.
Entering the GO command places you at the start of the main
program. At that point, enter the GO command again to start
program execution, as with other types of Fortran programs.
3 MACRO-32
The following subtopics describe debugger support for MACRO-32.
4 Operators_in_Language_Expressions
The MACRO-32 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-32
programmer to use expressions at debug-time as freely as in other
languages, the debugger accepts a number of operators in MACRO-
32 language expressions that are not found in MACRO-32 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
Infix + Addition
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
MACRO-32 follow:
Symbol Construct
[ ] Subscripting
<p,s,e> Bit field selection as in BLISS
The DST information generated by the MACRO-32 assembler treats
a label that is followed by an assembler directive for storage
allocation as an array variable whose name is the label. This
enables you to use the array syntax of a high-level language when
examining or manipulating such data.
In the following example of MACRO-32 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
4 Data_Types
MACRO-32 binds a data type to a label name according to the
assembler directive that follows the label definition. Supported
MACRO-32 directives follow:
MACRO-32
Directives Operating System Data Type Name
.BYTE Byte Unsigned (BU)
.WORD Word Unsigned (WU)
.LONG Longword Unsigned (LU)
.SIGNED_BYTE Byte Integer (B)
.SIGNED_WORD Word Integer (W)
.LONG Longword Integer (L)
.QUAD Quadword Integer (Q)
.F_FLOATING F_Floating (F)
.D_FLOATING D_Floating (D)
.G_FLOATING G_Floating (G)
.H_FLOATING H_Floating (H) (VAX specific)
(Not Packed decimal (P)
applicable)
4 MACRO-32_Compiler_(AMACRO)
(Alpha only) Programmers who are porting applications written in
MACRO-32 to Alpha systems use the MACRO-32 compiler (AMACRO). A
debugging session for compiled MACRO-32 code is similar to that
for assembled code. However, there are some important differences
that are described in this section. For complete information on
porting these applications, see the Porting VAX MACRO Code from
OpenVMS VAX to OpenVMS Alpha manual.
5 Code_Relocation
One major difference is the fact that the code is compiled. On
a VAX system, each MACRO-32 instruction is a single machine
instruction. On an Alpha system, each MACRO-32 instruction may
be compiled into many Alpha machine instructions. A major side
effect of this difference is the relocation and rescheduling of
code if you do not specify /NOOPTIMIZE in your compile command.
After you have debugged your code, you can recompile without
/NOOPTIMIZE to improve performance.
5 Symbolic_Variables
Another major difference between debugging compiled code and
debugging assembled code is a new concept to MACRO-2, the
definition of symbolic variables for examining routine arguments.
On VAX systems, when you were debugging a routine and wanted to
examine the arguments, you would typically do something like the
following:
DBG> EXAMINE @AP ; to see the argument count
DBG> EXAMINE @AP+4 ; to examine the first arg
or
DBG> EXAMINE @AP ; to see arg count
DBG> EXAMINE .+4:.+20 ; to see first 5 args
On Alpha systems, the arguments do not reside in a vector in
memory as they did on VAX systems. Furthermore, there is no AP
register on Alpha systems. If you type EXAMINE @AP when debugging
MACRO compiled code, the debugger reports that AP is an undefined
symbol.
In the compiled code, the arguments can reside in some
combination of:
o Registers
o On the stack above the routine's stack frame
o In the stack frame, if the argument list was "homed" (that is,
placed in the fixed position of the stack frame to resolve VAX
AP references) or if there are calls out of the routine that
would require the register arguments to be saved
The compiler does not require that you read the generated code
to locate the arguments. Instead, it provides $ARGn symbols that
point to the correct argument locations. $ARG0 is the same as
@AP+0 is on VAX systems, that is, the argument count. $ARG1 is
the first argument, $ARG2 is the second argument, and so forth.
These symbols are defined in CALL_ENTRY and JSB_ENTRY directives,
but not in EXCEPTION_ENTRY directives.
5 Locating_Arguments_Without_$ARGn_Symbols
There may be additional arguments in your code for which the
compiler did not generate a $ARGn symbol. The number of $ARGn
symbols defined for a .CALL_ENTRY routine is the maximum number
detected by the compiler (either by automatic detection or as
specified by MAX_ARGS) or 16, whichever is less. For a .JSB_ENTRY
routine, since the arguments are homed in the caller's stack
frame and the compiler cannot detect the actual number, it always
creates eight $ARGn symbols.
In most cases, you can easily find any additional arguments, but
in some cases you cannot.
5 Arguments_That_Are_Easy_to_Locate
You can easily find additional arguments if:
o The argument list is not homed, and $ARGn symbols are defined
to $ARG7 or higher. If the argument list is not homed, the
$ARGn symbols $ARG7 and above always point into the list
of parameters passed as quadwords on the stack. Subsequent
arguments will be in quadwords following the last defined
$ARGn symbol.
o The argument list has been homed, and you want to examine
an argument that is less than or equal to the maximum number
detected by the compiler (either by automatic detection or as
specified by MAX_ARGS). If the argument list is homed, $ARGn
symbols always point into the homed argument list. Subsequent
arguments will be in longwords following the last defined
$ARGn symbol.
For example, you can examine arguments beyond the eighth argument
in a JSB routine (where the argument list must be homed in the
caller), as follows:
DBG> EX $ARG8 ; highest defined $ARGn
.
.
.
DBG> EX .+4 ; next arg is in next longword
.
.
.
DBG> EX .+4 ; and so on
This example assumes that the caller detected at least ten
arguments when homing the argument list.
To find arguments beyond the last $ARGn symbol in a routine that
did not home the arguments, proceed exactly as in the previous
example except substitute EX .+8 for EX .+4.
5 Arguments_That_Are_Not_Easy_to_Locate
You cannot easily find additional arguments if:
o The argument list is homed, and you want to examine arguments
beyond the number detected by the compiler. The $ARGn symbols
point to the longwords that are stored in the homed argument
list. The compiler only moves as many arguments as it can
detect into this list. Examining longwords beyond the last
argument that was homed will result in examining various other
stack context.
o The argument list is not homed, and $ARGn symbols are
defined only as high as $ARG6. In this case, the existing
$ARGn symbols will either point to registers or to quadword
locations in the stack frame. In both cases, subsequent
arguments cannot be examined by looking at quadword locations
beyond the defined $ARGn symbols.
The only way to find the additional arguments in these cases
is to examine the compiled machine code to determine where the
arguments reside. Both of these problems are eliminated if MAX_
ARGS is specified correctly for the maximum argument that you
want to examine.
5 Debugging_Code_with_Floating-Point_Data
The following list provides important information about debugging
compiled MACRO-32 code with floating-point data on an Alpha
system:
o You can use the EXAMINE/FLOAT command to examine an Alpha
integer register for a floating-point value.
Even though there is a set of registers for floating-point
operations on Alpha systems, those registers are not used
by compiled MACRO-32 code that contains floating-point
operations. Only the Alpha integer registers are used.
Floating-point operations in compiled MACRO-32 code are
performed by emulation routines that operate outside the
compiler. Therefore, performing MACRO-32 floating-point
operations on, say, R7, has no effect on Alpha floating-point
register 7.
o When using the EXAMINE command to examine a location that
was declared with a .FLOAT directive or other floating-point
storage directives, the debugger automatically displays the
value as floating-point data.
o When using the EXAMINE command to examine the G_FLOAT data
type, the debugger does not use the contents of two registers
to build the value for VAX data.
Consider the following example:
EXAMINE/G_FLOAT R4
In this example, the lower longwords of R4 and R5 are not
used to build the value as is the case on VAX. Instead, the
quadword contents of R4 are used.
The code the compiler generates for D_FLOAT and G_FLOAT
operations preserves the VAX format of the data in the low
longwords of two consecutive registers. Therefore, using
EXAMINE/G_FLOAT on either of these two registers will not give
the true floating-point value, and issuing DEPOSIT/G_FLOAT to
one of these registers will not give the desired results. You
can manually combine the two halves of such a value, however.
For example, assume you executed the following instruction:
MOVG DATA, R6
You could then read the G_FLOAT value which now resides in R6
and R7 with a sequence like the following:
DBG> EX R6
.MAIN.\%LINE 100\%R6: 0FFFFFFFF D8E640D1
DBG> EX R7
.MAIN.\%LINE 100\%R7: 00000000 2F1B24DD
DBG> DEP R0 = 2F1B24DDD8E640D1
DBG> EX/G_FLOAT R0
.MAIN.\%LINE 100\%R0: 4568.89900000000
o You can deposit floating-point data in an Alpha integer
register with the DEPOSIT command. The syntax is the same
as it is on VAX.
o H_FLOAT is unsupported.
5 Debugging_Code_with_Packed_Decimal_Data
The following list provides important information about debugging
compiled MACRO-32 code with packed decimal data on an Alpha
system:
o When using the EXAMINE command to examine a location that was
declared with a .PACKED directive, the debugger automatically
displays the value as a packed decimal data type.
o You can deposit packed decimal data. The syntax is the same as
it is on VAX.
3 MACRO-64
(Alpha only) The following subtopics describe debugger support
for MACRO-64.
4 Operators_in_Language_Expressions
Language MACRO-64 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-64
programmer to use expressions at debug-time as freely as in other
languages, the debugger accepts a number of operators in MACRO-
64 language expressions that are not found in MACRO-64 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
Infix + Addition
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
MACRO-64 follow:
Symbol Construct
<p,s,e> Bit field selection as in BLISS
4 Data_Types
MACRO-64 binds a data type to a label name according to the data
directive that follows the label definition. For example, in the
following code fragment, the .LONG data directive directs MACRO-
64 to bind the longword integer data type to labels V1, V2, and
V3:
.PSECT A, NOEXE
.BYTE 5
V1:
V2:
V3: .LONG 7
To confirm the type bound to V1, V2, and V3, issue a SHOW
SYMBOL/TYPE command with a V* parameter. The following display
results:
data .MAIN.\V1
atomic type, longword integer, size: 4 bytes
data .MAIN.\V2
atomic type, longword integer, size: 4 bytes
data .MAIN.\V3
atomic type, longword integer, size: 4 bytes)
Supported MACRO-64 directives follow:
MACRO-64
Directives Operating System Data Type Name
.BYTE Byte Unsigned (BU)
.WORD Word Unsigned (WU)
.LONG Longword Unsigned (LU)
.SIGNED_BYTE Byte Integer (B)
.SIGNED_WORD Word Integer (W)
.LONG Longword Integer (L)
.QUAD Quadword Integer (Q)
.F_FLOATING F_Floating (F)
.D_FLOATING D_Floating (D)
.G_FLOATING G_Floating (G)
.S_FLOATING S_Floating (S)
(Alpha
specific)
.T_FLOATING T_Floating (T)
(Alpha
specific)
(Not Packed decimal (P)
applicable)
3 Pascal
The following subtopics describe debugger support for Pascal.
4 Operators_in_Language_Expressions
Supported Pascal operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition, concatenation
Infix * Multiplication
Infix / Real division
Infix DIV Integer division
Infix MOD Modulus
Infix REM Remainder
Infix ** Exponentiation (VAX specific)
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
The typecast operator (::) is not supported in language
expressions.
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
Pascal follow:
Symbol Construct
[ ] Subscripting
. (period) Record component selection
^ Pointer dereferencing
(circumflex)
4 Predefined_Symbols
Supported Pascal predefined symbols follow:
Symbol Meaning
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
4 Built-In_Functions
Supported Pascal built-in functions follow:
Symbol Meaning
SUCC Logical successor
PRED Logical predecessor
4 Data_Types
Supported Pascal data types follow:
Pascal Data Type Operating System Data Type Name
INTEGER Longword Integer (L)
INTEGER Word Integer (W,WU)
INTEGER Byte Integer (B,BU)
UNSIGNED Longword Unsigned (LU)
UNSIGNED Word Unsigned (WU)
UNSIGNED Byte Unsigned (BU)
SINGLE, REAL F_Floating (F)
REAL (Alpha IEEE S_Floating (FS)
specific)
DOUBLE D_Floating (D)
DOUBLE G_Floating (G)
DOUBLE (Alpha IEEE T_Floating (FT)
specific)
QUADRUPLE (VAX H_Floating (H)
specific)
BOOLEAN (None)
CHAR ASCII Text (T)
VARYING OF CHAR Varying Text (VT)
SET (None)
FILE (None)
Enumerations (None)
Subranges (None)
Typed Pointers (None)
Arrays (None)
Records (None)
Variant records (None)
The debugger accepts Pascal set constants such as [1,2,5,8..10]
or [RED, BLUE] in Pascal language expressions.
Floating-point numbers of type REAL may be represented by F_
Floating or IEEE S_Floating, depending on compiler switches or
source code attributes.
Floating-point numbers of type DOUBLE may be represented by D_
Floating, G_Floating, or IEEE T_Floating, depending on compiler
switches or source code attributes.
4 Additional_Information
In general, you can examine, evaluate, and deposit into
variables, record fields, and array components. An exception
to this occurs under the following circumstances: if a variable
is not referenced in a program, the Pascal compiler might not
allocate the variable. If the variable is not allocated and you
try to examine it or deposit into it, you will receive an error
message.
When you deposit data into a variable, the debugger truncates
the high-order bits if the value being deposited is larger than
the variable; the debugger fills the high-order bits with zeros
if the value being deposited is smaller than the variable. If
the deposit violates the rules of assignment compatibility, the
debugger displays an informational message.
You can examine and deposit into automatic variables (within any
active block); however, because automatic variables are allocated
in stack storage and are contained in registers, their values
are considered undefined until the variables are initialized or
assigned a value.
4 Restrictions
Restrictions in debugger support for Pascal are as follows.
You can examine a VARYING OF CHAR string, but you cannot examine
the .LENGTH or .BODY fields 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 illustrated in the
following examples.
Use Instead of
EXAMINE/WORD VARS EXAMINE VARS.LENGTH
EXAMINE/ASCII EXAMINE VARS.BODY
VARS+2
3 PL-I
The following subtopics describe debugger support for PL/I.
4 Operators_in_Language_Expressions
Supported PL/I operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for PL/I
follow:
Symbol Construct
( ) Subscripting
. Structure component selection
(period)
-> Pointer dereferencing
4 Data_Types
Supported PL/I data types follow:
PL/I Data Type Operating System Data Type Name
FIXED BINARY Byte- (B), Word- (W), or Longword- (L)
Integer
FIXED DECIMAL Packed Decimal (P)
FLOAT BIN/DEC F_Floating (F)
FLOAT BIN/ DEC D_Floating (D)
FLOAT BIN/DEC G_Floating (G)
FLOAT BIN/DEC (VAX H_Floating (H)
specific)
BIT Bit (V)
BIT Bit Unaligned (VU)
CHARACTER ASCII Text (T)
CHARACTER VARYING Varying Text (VT)
FILE (None)
Labels (None)
Pointers (None)
Arrays (None)
Structures (None)
4 Static_and_Nonstatic_Variables
Variables of the following storage classes are allocated
statically:
STATIC
EXTERNAL
GLOBALDEF
GLOBALREF
Variables of the following storage classes are allocated
nonstatically (on the stack or in registers):
AUTOMATIC
BASED
CONTROLLED
DEFINED
PARAMETER
4 Examining_and_Manipulating_Data
The following subtopics give examples of the EXAMINE command with
PL/I data types. They also highlight aspects of debugger support
that are specific to PL/I.
5 EXAMINE_Command_Examples
The following examples show use of the EXAMINE command with a few
selected PL/I data types.
o Examine the value of a variable declared as FIXED DECIMAL
(10,5):
DBG> EXAMINE X
PROG4\X: 540.02700
o Examine the value of a structure variable:
DBG> EXAMINE PART
MAIN_PROG\INVENTORY_PROG\PART
ITEM: "WF-1247"
PRICE: 49.95
IN_STOCK: 24
o Examine the value of a pictured variable (note that the
debugger displays the value in quotation marks):
DBG> EXAMINE Q
MAIN\Q: "666.3330"
o Examine the value of a pointer (which is the virtual address
of the variable it accesses) and display the value in
hexadecimal radix instead of decimal (the default):
DBG> EXAMINE/HEXADECIMAL P
PROG4\SAMPLE.P: 0000B2A4
o Examine the value of a variable with the BASED attribute; in
this case, the variable X has been declared as BASED(PTR),
with PTR its pointer:
DBG> EXAMINE X
PROG\X: "A"
o Examine the value of a variable X declared as BASED with a
variable PTR declared as POINTER; here, PTR is associated with
X by the following line of PL/I code (instead of X having been
declared as BASED(PTR) as in the preceding example):
ALLOCATE X SET (PTR);
In this case, you examine the value of X as follows:
DBG> EXAMINE PTR->X
PROG6\PTR->X: "A"
5 Notes_on_Debugger_Support
Note the following points about debugger support for PL/I.
You cannot use the DEPOSIT command with entry or label variables
or formats, or with entire arrays or structures. You cannot use
the EXAMINE command with entry or label variables or formats;
instead, use the EVALUATE/ADDRESS command.
You cannot use the EXAMINE command to determine the values or
attributes of global literals (such as GLOBALDEF VALUE literals)
because they are static expressions. Instead, use the EVALUATE
command.
You cannot use the EXAMINE, EVALUATE, and DEPOSIT commands
with compile-time variables and procedures. However, you can
use EVALUATE and DEPOSIT (but not EXAMINE) with a compile-time
constant, as long as the constant is the source and not the
destination.
Note that an uninitialized automatic variable does not have
valid contents until after a value has been assigned to it.
If you examine it before that point, the value displayed is
unpredictable.
You can deposit a value into a pointer variable either by
depositing another pointer's value into it, thus making symbolic
reference to both pointers, or by depositing a virtual address
into it. (You can find out the virtual address of a variable by
using the EVALUATE/ADDRESS command, and then deposit that address
into the pointer.) When you examine a pointer, the debugger
displays its value in the form of the virtual address of the
variable that the pointer points to.
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, in order 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, because nondecimal radix constants are assumed to be
FIXED BINARY. For example, the EVALUATE/HEXADECIMAL 53 + %HEX 0
command displays 00000035.
3 RPG_II
(VAX only) The follow subtopics describe debugger support for
RPG II.
4 Operators_in_Language_Expressions
The following operators are supported in language expressions
when the language is set to RPG II:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for RPG
II follow:
Symbol Construct
( ) Subscripting
4 Data_Types
Supported RPG II data types follow:
RPG II Data Type Operating System Data Type Name
Longword binary Longword Integer (L)
numeric
Word binary Word Integer (W)
numeric
Packed decimal Packed Decimal (P)
Character ASCII Text (T)
Overpunched Right Overpunched Sign (NRO)
decimal
Arrays (None)
Tables (None)
4 Setting_Breakpoints_or_Tracepoints
With RPG II programs, you can set breakpoints using source
line numbers, logic cycle labels, user-defined tag names,
and subroutine labels. Debugging RPG II programs is somewhat
different from debugging programs in other languages, and the
additional topics explain where and how you can set breakpoints
or tracepoints.
5 Specifications
The following paragraphs describe where you can set breakpoints
(or tracepoints) in specifications, using line numbers.
The RPG II program cycle determines the order in which program
lines are processed. When setting breakpoints or tracepoints,
you can reference the line numbers that RPG II assigns to your
program and appear in a listing file or in a debugger source
display. The line numbers you specify in columns 1 through 5 of a
specification are not used.
The compiler assigns line numbers only to certain specifications
at specific points in the logic cycle; therefore, you can specify
a breakpoint or tracepoint at these points in the program:
o A breakpoint at a File Description specification occurs
before an input or update file is opened or just before an
output file is created. The line number of this breakpoint
corresponds to the File Description specification for this
file.
o A breakpoint at an Input specification occurs before the
fields are loaded with data from a record. The line number
of this breakpoint corresponds to the record definition in an
Input specification.
o You can set two breakpoints for each Calculation
specification. The first breakpoint occurs just after testing
control-level indicators, if used, and just before testing
conditioning indicators. The second breakpoint occurs just
before executing the operation code. Use the following syntax:
SET BREAK line-number.statement-number
For example, assume that a Calculation specification begins
with line number 25. The SET BREAK 25.1 command enables you to
test indicators. The SET BREAK 25.2 command puts a breakpoint
just before the operation code is executed. If a Calculation
specification has no conditioning indicators, the SET BREAK
25 command puts a breakpoint just before the operation code is
executed.
You can specify statement numbers only with Calculation
specifications that have conditioning indicators.
o A breakpoint at an Output specification occurs after the
output buffer has been built but before the record is output.
The line number of the breakpoint corresponds to the record
definition in an Output specification.
5 Labels
You can specify an RPG II label as a breakpoint or a tracepoint.
The following RPG II labels, which correspond to specific points
in the logic cycle, are provided in addition to user-defined
tags. Note that these labels do not appear in the source code
but are accessible from the debugger. The labels do appear in the
machine code listing.
RPG II
Label Description and Breakpoint Behavior
*DETL Breaks just before outputting heading and detail
lines
*GETIN Breaks just before reading the next record from the
primary or secondary file
*TOTC Breaks just before performing total-time calculations
*TOTL Breaks just before performing total-time output
*OFL Breaks just before performing overflow output
*DETC Breaks just before performing detail-time
calculations
For example:
DBG> SET BREAK *TOTL
4 EXAMINE_Command
The EXAMINE command enables you to look at the contents of a
variable, the current table entry, an array element, or the I/O
buffer.
To examine an array variable, use array syntax as in the
following example:
DBG> EXAMINE ARR3(9) ! Display element 9 of array ARR3
DBG> EXAMINE ARRY(1:7) ! Display elements 1-7 of array ARRY
Specifying a table name enables you to examine the entry
retrieved from the last LOOKUP operation.
To display the contents of the I/O buffer, specify the name of
the input file, update file, or output file, followed by the
string $BUF. For example, the following command displays the
contents of the I/O buffer for the input file INPUT:
DBG> EXAMINE INPUT$BUF
The following command displays the ASCII equivalent of the string
STRING, which is 6 characters long:
DBG> EXAMINE/ASCII:6 STRING
To examine a variable which contains the at sign (@), use %NAME
as follows:
DBG> EXAMINE %NAME 'ITEM@'
To examine a nonexternal indicator, precede it with the string
*IN. For example:
DBG> EXAMINE *IN56
*IN56: "0"
If an indicator is set off, 0 is displayed. If an indicator is
set on, 1 is displayed.
You cannot examine external indicators in this manner. To examine
external indicators, you must first link the program with the
/NOSYSSHR qualifier; then, use the CALL command, as in the
following example which displays the value of U5:
DBG> CALL RPG$EXT_INDS(5)
value returned is 0
4 DEPOSIT_Command
Note the following points when using the DEPOSIT command:
o You can deposit a single value into an element of an array
using array syntax as in the following example, which deposits
the value 150 into element 2 of array ARR:
DBG> DEPOSIT ARR(2) = 150
o You can deposit multiple values into an array of character
strings, by using the /ASCII qualifier with the DEPOSIT
command. For example, assume PARTS is an array of 10 elements
in program INV.RPG, each a character string of length 3. The
following DEPOSIT command deposits the strings P04, P05, and
P06 into elements 4, 5, and 6, respectively, of array PARTS:
DBG> DEPOSIT/ASCII PARTS(4) = "P04P05P06"
DBG> EXAMINE PARTS(4:6)
INV\PARTS
(4): 'P04'
(5): 'P05'
(6): 'P06'
o Values deposited into numeric fields are aligned on the
decimal point. Shorter fields are padded with zeros to the
left and right of the decimal point.
o Values deposited into character fields are left justified. If
the value contains fewer characters than the character field,
the field is padded on the right with spaces.
o To set a nonexternal indicator on or off with the DEPOSIT
command, precede the indicator with the string *IN. Depositing
the value 1 or 0 sets the indicator on or off, respectively.
For example, the following command sets indicator 56 on:
DBG> DEPOSIT *IN56 = "1"
4 EDIT_Command
The EDIT command invokes the RPG II editor rather than the
Language-Sensitive Editor.
3 SCAN
(VAX only) The following subtopics describe debugger support for
SCAN.
4 Operators_in_Language_Expressions
Supported SCAN operators in language expressions include:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition
Infix * Multiplication
Infix / Division
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 Complement
Infix AND Intersection
Infix OR Union
Infix XOR Exclusive OR
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for SCAN
follow:
Symbol Construct
( ) Subscripting
. Record component selection
(period)
-> Pointer dereferencing
4 Predefined_Symbols
Supported SCAN predefined symbols follow:
Symbol Meaning
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
4 Data_Types
Supported SCAN data types follow:
SCAN Data Type Operating System Data Type Name
BOOLEAN (None)
INTEGER Longword Integer (L)
POINTER (None)
FIXED STRING TEXT with CLASS=S
(n)
VARYING STRING TEXT with CLASS=VS
(n)
DYNAMIC STRING TEXT with CLASS=D
TREE (None)
TREEPTR (None)
RECORD (None)
OVERLAY (None)
There is no specific support for the following data types:
FILE
TOKEN
GROUP
SET
4 Names
You can use the names of the following SCAN constructs in
debugger commands:
procedures
macros
constants
variables
labels
4 Controlling_Execution
Note the following points about SCAN breakpoints, tracepoints,
and watchpoints.
5 Breakpoints_and_Tracepoints
You can set breakpoints and tracepoints on procedures, trigger
macros, syntax macros, and labels, as well as line numbers. For
example:
DBG> SET BREAK find_keyword ! break on a trigger macro
DBG> CANCEL BREAK exit ! cancel break on label
DBG> SET BREAK compare_trees ! break on a procedure
Conventional breakpoints and tracepoints are not especially
convenient for monitoring SCAN's picture matching. Where do you
set a breakpoint or tracepoint to observe the tokens built by
your program? There is no statement in your program on which to
set such a breakpoint.
To solve this problem, VAX SCAN defines several events. By
setting breakpoints or tracepoints on these events, you can
observe the picture matching process.
The following event keywords are defined for SCAN programs:
Event
Keyword Description
TOKEN A token is built.
PICTURE An operand in a picture is being matched.
INPUT A new line of the input stream is read.
OUTPUT A new line of the output stream is written.
TRIGGER A trigger macro is starting or terminating.
SYNTAX A syntax macro is starting or terminating.
ERROR Picture matching error recovery is starting or
terminating.
Use these keywords with the /EVENT qualifier of the following
commands:
(SET,CANCEL,ACTIVATE,DEACTIVATE) BREAK
(SET,CANCEL,ACTIVATE,DEACTIVATE) TRACE
For example, the following command sets a breakpoint that
triggers whenever a TOKEN is built:
DBG> SET BREAK/EVENT=TOKEN
Recognition of SCAN events is enabled automatically by the
debugger if the main program is written in SCAN. If you are
debugging a program written in another language that calls a
SCAN routine, proceed as follows to set up the SCAN environment:
1. Enter the SET LANGUAGE SCAN command to enable recognition
of language-dependent operators, expressions, and other
constructs (see the SET LANGUAGE command).
2. Enter the SET EVENT_FACILITY SCAN command to enable
recognition of SCAN events (see the SET EVENT_FACILITY
command). The SHOW EVENT_FACILITY command identifies the
current facility and its events.
5 Watchpoints
Note the following points about SCAN watchpoints:
o Variables declared at MODULE level are static by default.
o Variables declared at PROCEDURE or MACRO level are automatic
(nonstatic) by default.
o DYNAMIC STRING variables are dynamically built. The storage
used to hold the value of the string can change when the
value of the string changes. Thus, the storage the debugger
is watching may not be the correct storage if the string's
value is changed.
4 Examining_and_Depositing
The following subtopics explain how to examine and deposit into
the following SCAN variables:
STRING
FILL
POINTER
TREE
TREEPTR
RECORD
OVERLAY
5 STRING_Variables
If you deposit into a FIXED STRING variable, truncation will
occur if the deposited string is longer than the size established
by the declaration of that variable.
If you deposit into a VARYING STRING variable, truncation will
occur if the deposited string is longer than the maximum size
established by the declaration of that variable.
If you deposit into a DYNAMIC STRING variable, truncation will
occur if the deposited string is longer than the current size of
the variable.
With FIXED and DYNAMIC STRING variables, if the deposited string
is shorter than the current size of the variable, the unfilled
portion of the variable will be blank padded to the right, with
the new string left justified in the variable.
In the case of VARYING STRING variables, the current size of
the variable storage space will be adjusted to the size of the
deposited string.
5 FILL_Variables
Examining a FILL variable causes the contents of the specified
variable to be displayed as a string, by default, and so may
have little meaning. If the characteristics (or type) of the fill
are known, the appropriate qualifier applied to the command will
produce a more meaningful display. The following command example
shows a fill x that is known to be a single floating number:
DBG> EXAMINE/FLOAT x
5 POINTER_Variables
You can examine a POINTER by name to find the address of the
variable it points to. Use the operator that combines the minus
sign and the greater than symbol to examine the variable that is
based on the POINTER.
Consider these declarations and assignments:
TYPE symnode: RECORD
ptr: POINTER TO symnode,
vstr: VARYING STRING( 20 ),
END RECORD;
DECLARE x : symnode;
DECLARE xptr: POINTER TO symnode;
xptr = POINTER(x);
x.vstr = 'prehensile';
The following command displays the value of the vstr component of
x:
DBG> EXAMINE x.vstr
POINTER\MAINPOINTER\X.VSTR: 'prehensile'
The following command displays the value of vstr based on the
POINTER:
DBG> EXAMINE xptr->.vstr
POINTER\MAINPOINTER\XPTR->.VSTR: 'prehensile '
5 TREE_and_TREEPTR_Variables
You can examine the contents of the nodes in a tree using the
following syntax:
EXAMINE tree_variable([subscript], . . . )
You cannot deposit into a TREE variable.
If you specify the name of a tree with the EXAMINE command, the
debugger displays the contents of all nodes and leaves of the
tree. For example:
DBG> EXAMINE voters
You can specify an interior node by entering the subscript for
that node. For example:
DBG> EXAMINE voters('salem')
You can examine the leaf node in a tree by specifying all
subscripts leading to the desired leaf. For example:
DBG> EXAMINE voters('salem',ward2)
If you examine a TREEPTR variable, such as cityptr or wardptr,
the debugger displays the address of that tree node. You examine
what a TREEPTR variable is pointing to as follows:
DBG> EXAMINE cityptr->
5 RECORD_and_OVERLAY_Variables
If you specify a RECORD by name with the EXAMINE command, all
components of the RECORD are presented. To examine individual
components of the RECORD, specify the full name of each
component.
The general format is as follows:
EXAMINE recordname
EXAMINE recordname.componentname.componentname . . .
You examine an OVERLAY in the same way. All components are again
presented; thus, if a four-byte region is a FILL(4), an INTEGER,
and a VARYING STRING(2), the four bytes will be displayed three
different ways.
3 Language_UNKNOWN
The following subtopics describe debugger support for language
UNKNOWN.
4 Operators_in_Language_Expressions
Supported operators in language expressions for language UNKNOWN
follow:
Kind Symbol Function
Prefix + Unary plus
Infix + Addition
Infix * Multiplication
Infix / Division
Infix ** Exponentiation (VAX specific)
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
4 Constructs_in_Language_and_Address_Expressions
Supported constructs in language and address expressions for
language UNKNOWN follow:
Symbol Construct
[ ] Subscripting
( ) Subscripting
. (period) Record component selection
^ Pointer dereferencing
(circumflex)
4 Predefined_Symbols
Supported predefined symbols for language UNKNOWN follow:
Symbol Meaning
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
4 Data_Types
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 as picture types and file types.
In UNKNOWN language expressions, the debugger accepts most scalar
OpenVMS calling standard data types.
o For language UNKNOWN, the debugger accepts the dot-notation
for record component selection. For example, if C is a
component of a record B which in turn is a component of a
record A, then C can be referenced as A.B.C. Subscripts can
be attached to any array components; for example, if B is an
array, then C can be referenced as A.B[2,3].C.
o For language UNKNOWN, the debugger accepts brackets and
parentheses for subscripts. For example, A[2,3] and A(2,3)
are equivalent.
2 Logical_Names
3 DBG$DECW$DISPLAY
Specifies the debugger interface (Compaq DECwindows Motif for
OpenVMS or command) or the display device (if you are displaying
the interface on a workstation).
By default, DBG$DECW$DISPLAY is either undefined or has the same
definition as the application-wide logical name DECW$DISPLAY.
The Compaq DECwindows Motif for OpenVMS user interface is the
default on workstations. To display the command interface instead
of the Compaq DECwindows Motif for OpenVMS user interface, enter
the following definition before starting the debugger:
$ DEFINE DBG$DECW$DISPLAY " "
For complete information about the Compaq DECwindows Motif for
OpenVMS user interface, see the debugger's Compaq DECwindows
Motif for OpenVMS documentation.
3 DBG$IMAGE_DSF_PATH
(Alpha only) Specifies the directory in which a separate Debug
Symbol File (.DSF) file resides.
Debugging an executable file that has a separate .DSF file
requires the following:
o The name of the .DSF file must match the name of the .EXE file
being debugged.
o You must define DBG$IMAGE_DSF_PATH to point to the directory
that contains the .DSF file.
3 DBGHK$IMAGE_PATH
(Alpha only) Specifies the directory path of .DSF files when you
are using the OpenVMS Alpha System-Code Debugger. For complete
information on using this debugger, see the Writing OpenVMS Alpha
Device Drivers in C.
3 DBG$INIT
If the logical name DBG$INIT is defined at the start of a
debugging session, then the file that it translates to is used
as an initialization file. The commands in the file are executed
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.
Example:
$ CREATE MY_DEBUG.COM
SET SOURCE SYS$DISK:[],SRC$
SET MODE SCREEN
SET STEP SILENT
. . .
$ DEFINE DBG$INIT [JONES.CMD]DEBUG_INIT.COM
3 DBG$INPUT_and_DBG$OUTPUT
The value of the logical name DBG$INPUT determines the debugger
input device. By default, this is SYS$INPUT.
The value of the logical name DBG$OUTPUT determines the debugger
output device. By default, this is SYS$OUTPUT.
If you plan to debug a program that takes its input from a
file and your debugger input from the terminal, establish the
following definitions before starting 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.
2 Messages
To get help about a debugger message, use the following general
command format:
DBG> HELP Messages message-identifier
where message-identifier is the keyword displayed to the left
of the message text. The additional topics list all message
identifiers alphabetically.
The following information is provided for each message
identifier: message text, explanation, and user action.
3 Example
For example, suppose the debugger displays the following message:
Language: BASIC, Module: TEST
In this example, the message identifier is INITIAL. To get
information about this message, enter the following command:
DBG> HELP Messages INITIAL
3 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.
The identifier enables you to find the explanation for a
diagnostic message from the debugger's online help (and the
action you need to take, if any).
3 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 inform 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 contact your Compaq support representative.
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.
3 ABORTCMD
aborting command due to kernel debugger termination
Facility: DEBUG, VMS Debugger
Explanation: The kernel debugger terminated so the current
command was aborted.
User Action: Check the reason the kernel debugger terminated.
3 ABORTED
command aborted by user request
Facility: DEBUG, VMS Debugger
Explanation: The command being executed was stopped when you
typed CTRL-C.
User Action: No action necessary.
3 ABSDATSYN
absolute date-time syntax error
Facility: DEBUG, VMS Debugger
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.
3 ACCADDCOM
access violation in address computation for address_value
Facility: DEBUG, VMS Debugger
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.
3 ACTIVATING
program is activating
Facility: DEBUG, VMS Debugger
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.
3 ADDRANCOV
address range covers more than one module address_value is in path_
name address_value is in path_name
Facility: DEBUG, VMS Debugger
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.
3 ADDRESSMODE
instruction uses illegal or undefined addressing modes
Facility: DEBUG, VMS Debugger
3 ADDRMBZ
a must-be-zero field in an address was not zero
Facility: DEBUG, VMS Debugger
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose a copy of the
program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 ADDRREG
& not allowed on register variables: operand bound to register_name
Facility: DEBUG, VMS Debugger
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.
3 ALOCMEMERR
error allocating memory for an object in routine function_name.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when allocating
memory.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 ALRDYCONNECTED
a debugger has already connected to the desired process.
Facility: DEBUG, VMS Debugger
Explanation: The process you are trying to connect to is already
connected to a debugger (maybe your current debugger). There can
only be one connection at a time.
User Action: Check to see if you have already connected (SHOW
PROCESS/ALL) to the desired process. If not, then some other
debug session is connected to it. Disconnect the other debugger
from the desired process before attempting to reconnect your
session.
3 AMBFIELD
field_name is an ambiguous field name
Facility: DEBUG, VMS Debugger
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.
3 AMBIGQUAL
qualifier qualifier_name is ambiguous
Facility: DEBUG, VMS Debugger
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.
3 AMBIGUOUS
'member_name' is ambiguous, matching the following
Facility: DEBUG, VMS Debugger
Explanation: The reference to the given member cannot be resolved
because there is more than one member with the given name.
User Action: Fully qualify the reference with a complete name for
the desired member.
3 AMPERSAND
operand of ampersand must be lvalue
Facility: DEBUG, VMS Debugger
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.
3 ANPKERNOTAVAIL
analyze process dump kernel of the VMS debugger not available
Facility: DEBUG, VMS Debugger
Explanation: The analyze process dump kernel for the VMS debugger
is not available on this system.
User Action: Contact your Digital Representative on the
availability of this feature.
3 ARGLSTNOREAD
argument list for frame frame-addr is not readable at address arg-
addr
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined
that part or all of the argument list for the frame at frame-addr
is not accessible for reading. This argument list lies at arg-
addr. This usually indicates a corrupt frame list, but could also
indicate that the program has protected part of memory in which
the frame lies. In either case, this is an error.
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".
3 ARGNEEDSCOM
a VMS command must be specified in order to pass arguments in a RUN
or RERUN command
Facility: DEBUG, VMS Debugger
Explanation: In order to specify arguments on a VMS run command,
the command must be specified using a foreign command, or set
using SET COMMAND. This VMS definition must be supplied to the
Debugger RUN command using the /COMMAND qualifier.
User Action: Supply the proper /COMMAND qualifier along with the
/ARGUMENT switch.
3 ASTARGNOREAD
AST arguments for AST frame frame-addr at astarg-addr is not
readable
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined
that part or all of the AST argument array for the AST frame at
frame-addr is not accessible for reading. This vector lies at
astarg-addr. This usually indicates a corrupt frame list, but
could also indicate that the program has protected part of memory
in which the frame lies. In either case, this is an error.
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".
3 ASTWASDISABLED
ASTs were disabled, and are still disabled
Facility: DEBUG, VMS Debugger
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
3 ASTWASENABLED
ASTs were enabled, and are still enabled
Facility: DEBUG, VMS Debugger
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
3 ATNEEDSENABLE
the /AT qualifier was specified, /ENABLE was not
Facility: DEBUG, VMS Debugger
Explanation: The /AT qualifier is only appropriate with the
/ENABLE qualifier.
User Action: Reenter the command, specifying /ENABLE.
3 ATTACHED
terminal is now attached to process process_name
Facility: DEBUG, VMS Debugger
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
3 ATTREQREF
attach request refused
Facility: DEBUG, VMS Debugger
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.
3 BADADDSPA
attempted to compare addresses in different address spaces
Facility: DEBUG, VMS Debugger
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose a copy of the
program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 BADADDSTA
attempted to compare addresses with different address states, error
occurred comparing address with address
Facility: DEBUG, VMS Debugger
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose a copy of the
program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 BADBODPACK
incorrect package spec name in body-spec spec-name, module mod-name
Facility: DEBUG, VMS Debugger
Explanation: The compiler has generated invalid Debug Symbol
Table information.
User Action: Please submit a Software Performance Report against
the compiler.
3 BADDESCR
descriptor for 'symbol_name' is bad or is not set up yet
Facility: DEBUG, VMS Debugger
Explanation: The descriptor for the given symbol points into
memory that cannot be read by the Debugger.
User Action: Correct the descriptor.
3 BADDISCVAL
incorrect value of tag_value in discriminant field tag_name.
Facility: DEBUG, VMS Debugger
Explanation: The discriminate value you gave was out of range.
User Action: Supply a discriminate value that is within the
correct range.
3 BADDST
bad Debugger Symbol Table (DST) (compiler error)
Facility: DEBUG, VMS Debugger
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 (SPR).
3 BADEVNPAR
parameter does not have permitted data type for this event
Facility: DEBUG, VMS Debugger
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.
3 BADEXH
the user-mode exit handler list is corrupt
Facility: DEBUG, VMS Debugger
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.
3 BADFRAME
bad FP or bad saved FP at pointer-addr in call stack, can't read
frame near frame-addr
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The FP register (if pointer-
addr is "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".
3 BADHANDLE
non-existent object handle passed to routine
Facility: DEBUG, VMS Debugger
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).
3 BADINCAR
the target system has the wrong incarnation
Facility: DEBUG, VMS Debugger
Explanation: After a network failure, the debugger has attempted
to re-connect to the target system. However, the target systems
incarnation value does not match the last known incarnation,
therefore this debug session is no longer valid. This is most
likely due to the target system rebooting.
User Action: Start up the debugger and target system again from
scratch.
3 BADOPCODE
opcode opcode_name is unknown
Facility: DEBUG, VMS Debugger
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.
3 BADPARAM
bad parameter value
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 BADSCOPE
invalid pathname path_name, SCOPE not changed
Facility: DEBUG, VMS Debugger
Explanation: The scope path_name specified in the SET SCOPE
command contained a pathname that does not exist.
User Action: Specify a valid scope.
3 BADSIGARG
bad sigarg pointer at pointer-addr or bad sigarg vector, can't read
sigarg vector near sigarg-addr
Facility: DEBUG, VMS Debugger
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-addr
points 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".
3 BADSTACK
WARNING: stack corrupted; session integrity not guaranteed
Facility: DEBUG, VMS Debugger
Explanation: While walking the call stack, the debugger has
determined that the stack is corrupted. The debugger will attempt
to establish some context and give the user control. Continuation
in the presence of a corrupted stack typically results in
unpredictable program and debugger behavior.
User Action: See the secondary message, if any, for more
information. Look at what little valid information is left and
then start over. Attempt to find and fix the point where the
stack gets corrupted. It may be possible to examine program
state, but continuing instruction execution typically results
in unpredictable program and debugger behavior.
3 BADSTARTPC
cannot start from PC address_value
Facility: DEBUG, VMS Debugger
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.
3 BADSTATUS
bad status returned from routine-name
Facility: DEBUG, VMS Debugger
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.
3 BADSUBPAR
incorrect parent name in subunit sym-name, in module mod-name
Facility: DEBUG, VMS Debugger
Explanation: The compiler has generated invalid Debug Symbol
Table information.
User Action: Please submit a Software Performance Report (SPR)
against the compiler.
3 BADTAGVAL
incorrect value of tag_value in tag field tag_name.
Facility: DEBUG, VMS Debugger
Explanation: The tag value you gave was out of range.
User Action: Supply a tag that is within the correct range.
3 BADTARGET
target location protected, cannot perform deposit
Facility: DEBUG, VMS Debugger
Explanation: The target address of the DEPOSIT command cannot be
made writeable. The DEPOSIT command cannot be performed.
User Action: None.
3 BADUSEPACK
incorrect package name in use clause use-name, module module-name
Facility: DEBUG, VMS Debugger
Explanation: The compiler has generated invalid Debug Symbol
Table information.
User Action: Please submit a Software Performance Report against
the compiler.
3 BADUSREVNT
bad user-specified event table or event entry in user RTL
Facility: DEBUG, VMS Debugger
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.
3 BADWATCH
cannot watch protected address address_value
Facility: DEBUG, VMS Debugger
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.
3 BADWIDGET
the debugger can not write to the command dialog box, is not
initialized.
Facility: DEBUG, VMS Debugger
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).
3 BASVARNOTSET
base variable not set up yet
Facility: DEBUG, VMS Debugger
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.
3 BEPOSITIVE
length 'number_value' must be greater than zero
Facility: DEBUG, VMS Debugger
Explanation: The specified length expression yielded a non-
positive value, in a context in which that does not make sense.
User Action: Enter a length expression that yields a value which
is greater than zero.
3 BITRANGE
bit range out of limits
Facility: DEBUG, VMS Debugger
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.
3 BKPTNOTFOUND
error searching for this breakpoint.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected and error when searching for
the existence of the breakpoint in the list current breakpoints.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 BPTDIFMOD
breakpoint or tracepoint being set in a different module.
Facility: DEBUG, VMS Debugger
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.
3 BPTONDATA
execution breakpoint or tracepoint set on data item
Facility: DEBUG, VMS Debugger
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.
3 BUFFEROVF
buffer overflow
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 BUFOVRFLOW
an internal buffer overflow has been detected.
Facility: DEBUG, VMS Debugger
Explanation: The size of an internal buffer is insufficient to
perform this operation
User Action: Please submit a Software Performance Report (SPR).
3 BUTTONEXISTS
button !AC already exists in the button list.
Facility: DEBUG, VMS Debugger
3 BUTTONNOTFOUND
button !AC not found in the internal button list
Facility: DEBUG, VMS Debugger
3 BUTTONTOOMANY
too many buttons, cannot generate a unique button name.
Facility: DEBUG, VMS Debugger
3 BWLGISMUS
B, W, L, G, I, or S must precede ^ for operand number operand_number
Facility: DEBUG, VMS Debugger
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.
3 CALLDONE
call to user program complete
Facility: DEBUG, VMS Debugger
Explanation: This signal is generated by the debugger kernel
after a called routine returns.
User Action: Submit an SPR. This message is handled internally,
and should never be signaled to the user.
3 CALLINGNONSTATIC
calling non-static member function in a static fashion
Facility: DEBUG, VMS Debugger
Explanation: You are attempting to use the CALL command to
call a non-static member function using a static syntax, eg.
Class::Func. This may result in incorrect parameters being passed
to the called routine, resulting in unpredictable results.
User Action: Use a non-static syntax when calling the routine,
eg. Obj.Func()
3 CANBRKWAT
cancel it and set a watchpoint if that is what was intended
Facility: DEBUG, VMS Debugger
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.
3 CANTACCESSMAIN
cannot access the main debugger
Facility: DEBUG, VMS Debugger
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 (SPR).
3 CANTBLDATTRLIST
cannot build an ACA Services attribute list.
Facility: DEBUG, VMS Debugger
Explanation: Debug could not build the attribute list needed to
invoke an ACA Services function. The ACA Services function will
not be executed.
User Action: Submit a Software Performance Report (SPR).
3 CANTCREATEMAIN
could not create the debugger subprocess
Facility: DEBUG, VMS Debugger
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 (SPR).
3 CANTDELLNM
unable to delete logical logical name
Facility: DEBUG, VMS Debugger
Explanation: The debugger process lacks the privleges necessary
to delete this logical.
User Action: Deassign the logical and redefine it in a less
privleged table and mode, e.g. /job/user_mode.
3 CANTFINDELEM
cannot retrieve optional arguments to the DEBUG message.
Facility: DEBUG, VMS Debugger
Explanation: Optional arguments were specified to the DEBUG
message however Debug cannot retrieve these arguments from ACA
Services.
User Action: Submit a Software Performance Report (SPR).
3 CANTFREEATTRLIST
cannot deallocate an ACA Services attribute list.
Facility: DEBUG, VMS Debugger
Explanation: Debug could not deallocate the attribute list needed
to invoke an ACA Services function.
User Action: No action necessary.
3 CANTGETFID
cannot get file-id for image file opened on channel channel-number
Facility: DEBUG, VMS Debugger
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 (SPR).
3 CANTGETLISTCNT
cannot retrieve the list count on an item list.
Facility: DEBUG, VMS Debugger
Explanation: An item list was secified in an ACA Services message
to Debug, however, in the course of processing the message, Debug
could not retrieve the count of the number of items in the list
from ACA Services.
User Action: Submit a Software Performance Report (SPR).
3 CANTGETMAINFID
cannot get file-id for the main image file opened on channel
channel-number
Facility: DEBUG, VMS Debugger
Explanation: An error occurred while trying to get the file-id of
the main 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. Note that trying to debug a remote image is NOT
currently supported. If you are not trying to debug a remote
image and the problem cannot be solved, submit a Software
Performance Report.
3 CANTINTPRO
cannot interrupt process !AC
Facility: DEBUG, VMS Debugger
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).
3 CANTOPNIMG
cannot open image image_name (File: device_name:(file_id,file_
id,file_id))
Facility: DEBUG, VMS Debugger
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.
3 CANTPAST
cannot paste to read-only window.
Facility: DEBUG, VMS Debugger
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.
3 CANTREGSERVER
could not register Debug as ACA Services server.
Facility: DEBUG, VMS Debugger
Explanation: Debug could not register itself as an ACA Services
Server.
User Action: Verify that ACA Services is installed and that the
Control Server is running on the current system. If ACA Services
is installed and the Control Server is running on the current
system and this problem still exist, submit a Software Performace
Report, otherwise install ACA Services and start the Control
Server.
3 CANTUNREGSERVER
could not unregister Debug as ACA Services server.
Facility: DEBUG, VMS Debugger
Explanation: Debug could not unregister itself as an ACA Services
Server.
User Action: Use ACA Services command, STOP SERVER, to unregister
Debug as an ACA Services server.
3 CIRCSTK
circular stack at frame address frame-addr
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined that
the linked frames loop back on themselves at 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".
3 CIREXLST
command aborted after number_of_handlers exit handlers displayed
circular exit handler list suspected
Facility: DEBUG, VMS Debugger
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.
3 CLIBRDFAI
clipboard operation failure
Facility: DEBUG, VMS Debugger
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.
3 CLIBRDLCK
clipboard locked
Facility: DEBUG, VMS Debugger
Explanation: Some other DECWINDOWS application has locked the
clipboard.
User Action: Wait until the other application has released the
clipboard.
3 CMDBUFFERR
error in the command buffer size.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when trying to
process the input command. Debug determined that the command
buffer size was to small to store the command buffer.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 CMDFAILED
the !AC command has failed
Facility: DEBUG, VMS Debugger
Explanation: The command has failed. The command has had no
effect on the current debugging session.
User Action: Reenter the command after correcting the problem.
3 CMDISCOR
the correct command is command_name
Facility: DEBUG, VMS Debugger
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.
3 CMDISOBS
command command_name is obsolete
Facility: DEBUG, VMS Debugger
Explanation: This command is obsolete.
User Action: Do not use this command, it will not be available in
a future release of the debugger.
3 CMDNOTANAPROC
The !AC command is not allowed when analyzing a process dump
Facility: DEBUG, VMS Debugger
Explanation: The specified command may not be used within a
process dump analysis.
User Action: Do not use the command when analyzing a process
dump.
3 CMDNOTAVAIL
the command command_name is not available
Facility: DEBUG, VMS Debugger
Explanation: The specified command, although available in
some debug implementations, is not available in this one. One
reason why is that the qualifier just doesn't make sense on the
platform. For example, the /JSB qualifier on a STEP command
doesn't make sense on Alpha VMS because there is no "JSB"
instruction like there is on VAX VMS.
User Action: Choose another command.
3 CMDNOTDW
The !AC command is not allowed in the DECWindows debugger
Facility: DEBUG, VMS Debugger
Explanation: The specified command may not be used with the
DECWindows debugger.
User Action: Do not use the command with the DECWindows debugger.
3 CMDNOTONE
The !AC command is not allowed in the one process debugger
Facility: DEBUG, VMS Debugger
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.
3 CMDSYNERR
command syntax error at or near 'the debugger_command_segment'
Facility: DEBUG, VMS Debugger
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.
3 CMPNOTFND
specified component not found in this type
Facility: DEBUG, VMS Debugger
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.
3 CNTRLWRDNOTACCESS
the vector control word is not accessible
Facility: DEBUG, VMS Debugger
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.
3 COMPNAME
variant selector 'compname' must be an unqualified component name
Facility: DEBUG, VMS Debugger
Explanation: When the language is C or C++, a variant selector
must specify a component of the union being selected.
User Action: Specify a component name.
3 COMPNDSTRNG
error generating a compound string.
Facility: DEBUG, VMS Debugger
Explanation: The debugger could not generate a compound string
that is utilized by the Xtoolkit.
User Action: No action necessary.
3 CONFLICT
illegal combination of command elements - check documentation
Facility: DEBUG, VMS Debugger
Explanation: Command line elements conflict in their operations.
The command will not be performed.
User Action: Do not specify conflicting command line elements.
3 CONFROMEXC
WARNING: continuing after severe error; integrity not guaranteed
Facility: DEBUG, VMS Debugger
Explanation: The debugger has encountered a severe error in the
users program and is continuing. The integrity of this debugging
session can no longer be guaranteed.
User Action: Determine and correct the cause of the severe error.
3 CONSTRCOMP
illegal deposit to a constrained record component
Facility: DEBUG, VMS Debugger
Explanation: The debugger cannot DEPOSIT into a constrained
record component.
User Action: Do not attempt to deposit into a constrained record
component.
3 COULDNOTRUN
the RUN or RERUN command did not succeed
Facility: DEBUG, VMS Debugger
Explanation: An error occurred while trying to create a
subprocess for the program to run. The error status returned
from the RUN or RERUN command is appended to this message.
User Action: If the error is correctable, correct the problem
and reenter the command. If not, the RUN and RERUN commands are
unavailable.
3 CPOSTDECR
side effect on post-decrement operation not performed
Facility: DEBUG, VMS Debugger
Explanation: The debugger does not support the evaluation of a
post-decrement expression.
User Action: None
3 CPOSTINCR
side effect on post-increment operation not performed
Facility: DEBUG, VMS Debugger
Explanation: The debugger does not support the evaluation of a
post-increment expression.
User Action: None
3 CPREDECR
side effect on pre-decrement operation not performed
Facility: DEBUG, VMS Debugger
Explanation: The debugger does not support the evaluation of a
pre-decrement expression.
User Action: None
3 CPREINCR
side effect on pre-increment operation not performed
Facility: DEBUG, VMS Debugger
Explanation: The debugger does not support the evaluation of a
pre-increment expression.
User Action: None
3 CRMPSCFAIL
failed to map-in the Debugger Symbol Table (DST)
Facility: DEBUG, VMS Debugger
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.
3 CVTNEGUNS
cannot convert negative value to unsigned value at or near opcode_
name
Facility: DEBUG, VMS Debugger
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.
3 DBGERR
debugger error or session corruption.
Facility: DEBUG, VMS Debugger
Explanation: The debugger has encountered an internal error or
session corruption.
User Action: If the error is reproducible, and is not an obvious
side effect of the user program (i.e. stack corruption, resource
exhaustion, etc.) submit a Software Performance Report (SPR) and
if possible, enclose a copy of the program being debugged, its
build procedure, and a logged debugging session that reproduces
the error.
3 DBGSTOPPED
a debugger process from a previous debugging session has been
terminated
Facility: DEBUG, VMS Debugger
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)
3 DECLARERR
too many declarations, parameter_name ignored
Facility: DEBUG, VMS Debugger
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.
3 DECOVF
decimal overflow at or near opcode_name
Facility: DEBUG, VMS Debugger
Explanation: The value being deposited does not fit into the
specified address.
User Action: Specify either a smaller value or a different target
address.
3 DECROPRAND
illegal packed or decimal string value (Reserved Operand fault
occurred during conversion)
Facility: DEBUG, VMS Debugger
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.
3 DEFKEY
state_name key key_name has been defined
Facility: DEBUG, VMS Debugger
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
3 DEFKEYERR
error in processing DEFINE/KEY command:
Facility: DEBUG, VMS Debugger
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.
3 DEFTOOREC
command defined with too many levels of recursion.
Facility: DEBUG, VMS Debugger
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.
3 DELKEY
state_name key key_name has been deleted
Facility: DEBUG, VMS Debugger
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
3 DELKEYERR
error in processing DELETE/KEY command:
Facility: DEBUG, VMS Debugger
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.
3 DELTIMTOO
delta time too large
Facility: DEBUG, VMS Debugger
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.
3 DESCNOTSET
descriptor not set up yet
Facility: DEBUG, VMS Debugger
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.
3 DISABLEAST
ASTs were enabled, and are now disabled
Facility: DEBUG, VMS Debugger
Explanation: Delivery of asynchronous system traps (ASTs) has
been turned off in your program by a DISABLE AST command.
User Action: None
3 DISNAMREQ
display name required with this command
Facility: DEBUG, VMS Debugger
Explanation: user did not specify a display name with this
command
User Action: enter a display name with this command
3 DISNOTSEL
display not selected; was removed from screen
Facility: DEBUG, VMS Debugger
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.
3 DISPEXISTS
display_name display already exists
Facility: DEBUG, VMS Debugger
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.
3 DISPKINDINV
the display kind display_name is not available
Facility: DEBUG, VMS Debugger
Explanation: The specified display kind, although available in
some debug implementations, is not available in this one.
User Action: Do not select the display kind.
3 DISPRLENSIZ
the size of display_name is too small for its display-window
increase the display size or decrease the display-window length
Facility: DEBUG, VMS Debugger
Explanation: You attempted to (re)size a display, e.g.
DISPLAY/SIZE=n or EXPAND/DOWN=m, such that the defined display
size is less than its display-window length. (See the SHOW
DISPLAY command.) This is not allowed. The command was aborted.
User Action: Try again with either a larger display size, e.g.
bigger n in DISPLAY/SIZE=n, OR a smaller expansion, e.g. smaller
m in EXPAND/DOWN=m.
3 DIVBYZERO
attempted to divide by zero
Facility: DEBUG, VMS Debugger
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.
3 DSFMISMATCH
using file_specification BUT it does NOT appear to match with file_
specification
Facility: DEBUG, VMS Debugger
Explanation: The debugger is pulling debug symbol information
for an image from the image DSF file BUT the link time in the
image header for the DSF does NOT match with the image EXE.
This means there may be symbolic and/or source line correlation
misinterpretations or omissions.
User Action: Verify that, if defined, the dbg$image_dsf_path is
set up correctly. Verify that your DSF was created by the same
link that created your image EXE.
3 DSTERRG
error in DST (compiler error). GOTO DST has been ignored
Facility: DEBUG, VMS Debugger
Explanation: This represents an internal compiler, linker or
debugger error.
User Action: If this can be reproduced please submit a Software
Performance Report (SPR).
3 DSTLOC
error occurs offset byte!%S from beginning of DST
Facility: DEBUG, VMS Debugger
Explanation: This is a secondary message which gives detailed
information about where the DST error occurs. It is intended
primarily to be used by Digital.
User Action: If you are submitting a problem report on the
primary error message, be sure to include this one, too.
3 DSTNESDEP
DST nesting depth too deep in module path_name
Facility: DEBUG, VMS Debugger
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.
3 DUPLVQUAL
duplicate or conflicting vector qualifier specified at 'command_
line'
Facility: DEBUG, VMS Debugger
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.
3 DUPSTATLINK
more than one static link DST encountered in path_name, compiler
error
Facility: DEBUG, VMS Debugger
Explanation: Only one static link DST record is permitted for
a given module, Ada package, or routine. This message indicates
that this constraint was violated somewhere within the specified
module. This message usually indicates a compiler error.
User Action: Submit a Software Performance Report (SPR).
3 DWERR
a DECwindows toolkit error has occurred the message text is '!AS'
Facility: DEBUG, VMS Debugger
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.
3 DWNOT1PROC
the 1 process debugger cannot be run in DECwindows mode
Facility: DEBUG, VMS Debugger
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.
3 DYNIMGSET
setting image image_name
Facility: DEBUG, VMS Debugger
Explanation: The debugger is automatically setting the image
containing the current PC. This is only an informational message.
User Action: None
3 DYNLNGSET
setting language language_name
Facility: DEBUG, VMS Debugger
Explanation: The debugger is automatically setting up the
language to correspond to the the module containing the current
PC. This is only an informational message.
User Action: None
3 DYNMODSET
setting module path_name
Facility: DEBUG, VMS Debugger
Explanation: The debugger is automatically setting the module
containing the current PC. This is only an informational message.
User Action: None
3 EDITDISVER
the original version is file_specification
Facility: DEBUG, VMS Debugger
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 retry operation.
3 EDITERROR
error while trying to EDIT
Facility: DEBUG, VMS Debugger
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.
3 EDITFILE
editing file file_specification
Facility: DEBUG, VMS Debugger
Explanation: The debugger is currently setup to edit the file as
specified in the message. This is only an informational message.
User Action: None
3 EDITNOFILE
no source file to use for editing
Facility: DEBUG, VMS Debugger
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 retry operation.
3 EDITREVVER
editing a revised version of the original source file
Facility: DEBUG, VMS Debugger
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 retry operation.
3 EMPTFIELDVIEW
error retrieving information from view.
Facility: DEBUG, VMS Debugger
Explanation: The debugger could not retrieve the necessary
information for a particular view display. This inhibits the
debugger from manipulating the contents of the window at this
time.
User Action: No action necessary.
3 ENABLEAST
ASTs were disabled, and are now enabled
Facility: DEBUG, VMS Debugger
Explanation: Delivery of asynchronous system traps (ASTs) has
been turned off in your program by a DISABLE AST command.
User Action: None
3 ENTRYMASK
entry mask has non-zero value in bits 12:13
Facility: DEBUG, VMS Debugger
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).
3 ENTRYNOTFND
error searching for a window object.
Facility: DEBUG, VMS Debugger
Explanation: When looking for a window object, the debugger
detected an error.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 ENUMRANGE
enumeration value out of range
Facility: DEBUG, VMS Debugger
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.
3 ERRACTIMG
unable to activate image
Facility: DEBUG, VMS Debugger
Explanation: A bad status was returned from LIB$FIND_IMAGE_
SYMBOL.
User Action: The image the debugger was trying to activate could
not be activated. The following error should help to resolve the
problem.
3 ERRASSIGN
failed to acquire an I/O channel for the debugger
Facility: DEBUG, VMS Debugger
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.
3 ERRCLSFILE
unable to close file
Facility: DEBUG, VMS Debugger
Explanation: A bad status was returned from a call to close a
file.
User Action: The debugger failed to close a file. Unless the
reason for this is apparent, submit a Software Performance Report
(SPR).
3 ERRCREATPB
error trying to create a user defined button.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected and error when trying to
create the user defined push button.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 ERRCREATWIND
error trying to create a window in routine function_name.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when trying to create
a window.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 ERRCRELNM
unable to create a logical name
Facility: DEBUG, VMS Debugger
Explanation: The debugger failed to create the required logical
names for input and output redirection.
User Action: Submit a Software Performance Report (SPR).
3 ERRDEASSIGN
failed to deassign an I/O channel acquired by the debugger
Facility: DEBUG, VMS Debugger
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).
3 ERRFAO
unable to format output string
Facility: DEBUG, VMS Debugger
Explanation: An error was returned from a call to $FAO.
User Action: Submit a Software Performance Report (SPR).
3 ERRFETCHWID
error fetching objects from MRM in routine function_name.
Facility: DEBUG, VMS Debugger
Explanation: The debugger could not find one of the necessary
objects in the Motif Resource Manager (MRM). This may prevent the
debugger from continuing the session.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 ERRGETDVI
unable to get device information
Facility: DEBUG, VMS Debugger
Explanation: The debugger needed some information from $GETDVI
and the call failed. This indicates an internal programming
error.
User Action: Submit a Software Performance Report (SPR).
3 ERRGETEF
attempt to allocate an event flag failed
Facility: DEBUG, VMS Debugger
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.
3 ERRINSDEC
error decoding instruction at current PC
Facility: DEBUG, VMS Debugger
Explanation: The debugger has encountered an error during
decoding of an instruction at the current PC
User Action: The address may be an entry mask, examine the
instruction 2 bytes beyond the specified address.
3 ERRINSIGNAL
signal arguments were incorrect, signal cannot be decoded
Facility: DEBUG, VMS Debugger
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.
3 ERRINVEDIT
error invoking editor
Facility: DEBUG, VMS Debugger
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).
3 ERROPENHIER
error opening the Motif resource (UID) file, in routine function_
name.
Facility: DEBUG, VMS Debugger
User Action: Please make sure that resource (UID) file for the
debugger is in appropriate directory (Usually SYS$SYSTEM). Please
consult your system manager.
3 ERROR
debugger error or session corruption
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error or
session corruption.
User Action: Correct the problem given by the messages following
this message. If the problem cannot be solved, submit a Software
Performance Report (SPR).
3 ERRORLIMIT
Error limit = error-limit, dumping terminated
Facility: DEBUG, VMS Debugger
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.
3 ERRORTEXT
!AS
Facility: DEBUG, VMS Debugger
Explanation: Unspecified error.
3 ERROR_BLOCK
error handle signalled, address = address
Facility: DEBUG, VMS Debugger
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).
3 ERRQIOW
error from $QIOW
Facility: DEBUG, VMS Debugger
Explanation: A bad status was returned from a call to $QIOW.
User Action: If problem can be recreated, submit a Software
Performance Report (SPR).
3 ERRSMG
error returned from a call to the Screen Management Facility (SMG)
Facility: DEBUG, VMS Debugger
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).
3 ERRSYSSERV
error returned from an internal debugger system service call
Facility: DEBUG, VMS Debugger
Explanation: A bad status was returned from a call to a system
service. This message will list the particular system service.
User Action: Submit a Software Performance Report (SPR).
3 ERRTARGOP
unable to perform operation for current target system
Facility: DEBUG, VMS Debugger
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose a copy of the
program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 ERRUSREVNT
error in user-specified event
Facility: DEBUG, VMS Debugger
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.
3 EXABEYREG
attempt to examine beyond the end of a register
Facility: DEBUG, VMS Debugger
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.
3 EXARANGE
invalid range of addresses
Facility: DEBUG, VMS Debugger
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.
3 EXCBREREP
exception breakpoint replaced
Facility: DEBUG, VMS Debugger
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.
3 EXCDURCAL
error occurred while executing routine called from exception break
Facility: DEBUG, VMS Debugger
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.
3 EXITARG
exitloop argument num_levels is too large
Facility: DEBUG, VMS Debugger
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.
3 EXITERR
an error occurred while trying to exit the program
Facility: DEBUG, VMS Debugger
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 (SPR).
3 EXITSTATUS
is 'status_value'
Facility: DEBUG, VMS Debugger
Explanation: The program has exited with the status status_value.
User Action: None.
3 EXPMEMPOOL
expanding debugger memory pool
Facility: DEBUG, VMS Debugger
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 a Software Performance Report (SPR).
3 FAILFINDIMG
could not find the DECwindows image to be initialized.
Facility: DEBUG, VMS Debugger
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).
3 FAILHANDLERBRK
failed to set breakpoint on a condition handler address
Facility: DEBUG, VMS Debugger
Explanation: The user had requested a SET BREAK/HANDLERS but a
frame based condition handler was found that Debug was unable to
set a breakpoint on.
User Action: You have several options. If the particular
handler is NOT of interest, then it is safe to ignore the set
the breakpoint error messages. You also have the option to
CANCEL BREAK/HANDLERS and SET BREAK on only the breakpointable
handlers of interest. Finally, if the handler IS of interest
AND IS in an installed resident image, then you should activate
the image privately via a logical, e.g. "DEFINE LIBOTS
SYS$LIBRARY:LIBOTS.EXE;". That should bring the handler's
activated address into the process's writeable address space.
3 FAILHEIRKY
could not open the user interface definition (UID) file,
SYS$LIBRARY:DEBUGUIL.UID.
Facility: DEBUG, VMS Debugger
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 existance and accessability of
SYS$LIBRARY:DEBUGUIL.UID. For further assistance and information
on this probelm check with your system manager.
3 FAILXTINIT
error trying to connect to the DECWindows software.
Facility: DEBUG, VMS Debugger
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).
3 FATALSTATUS
a fatal condition was detected by the debugger.
Facility: DEBUG, VMS Debugger
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.
3 FETCHLITERAL
error fetching literals from MRM.
Facility: DEBUG, VMS Debugger
Explanation: The debugger could not find one of the necessary
literals in the Motif Resource Manager (MRM). 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).
3 FILENAMETOOLONG
maximum file name length is 251 characters
Facility: DEBUG, VMS Debugger
Explanation: The name of the file specified by the user is too
large for the debugger to handle
User Action: Try to redo the operation with a shorter string.
3 FILEUNAL
file not available
Facility: DEBUG, VMS Debugger
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.
3 FLTOVF
floating overflow at or near opcode_name
Facility: DEBUG, VMS Debugger
Explanation: The value being deposited does not fit into the
specified address.
User Action: Specify either a smaller value or a different target
address.
3 FRAMENOREAD
stack frame at frame address frame-addr is not readable
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined
that part or all of the frame at frame-addr is not accessible for
reading. This usually indicates a corrupt frame list, but could
also indicate that the program has protected part of memory in
which the frame lies. In either case, this is an error.
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".
3 HEIGHTDIFF
desired height of specified_height is not allowed, height is set to
actual_height
Facility: DEBUG, VMS Debugger
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.
3 IDENTLONG
identifier too long, please shorten
Facility: DEBUG, VMS Debugger
Explanation: Identifiers in address expressions must be shorter
than 256 characters.
User Action: Enter a shorter identifier.
3 IFIXUND
precision lost during fixed point operation
Facility: DEBUG, VMS Debugger
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.
3 IFLTUND
floating underflow at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 IGNORELNM
ignoring logical logical name
Facility: DEBUG, VMS Debugger
Explanation: The debugger is ignoring this logical likely because
a previous error, e.g. unable to delete logical.
User Action: If there was an error message previous to this one,
see its user action and correct it.
3 IINTOVF
integer overflow at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 ILLADDCON
illegal constant constant_name in address expression
Facility: DEBUG, VMS Debugger
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.
3 ILLASTER
subscript range ('*') not permitted here (must be at lowest level of
data structure)
Facility: DEBUG, VMS Debugger
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.
3 ILLDEFNAM
illegal name for DEFINE: defined_name
Facility: DEBUG, VMS Debugger
Explanation: A defined name must be non-null.
User Action: Enter a non-null name to DEFINE.
3 ILLENUMVAL
enumeration value out of legal range
Facility: DEBUG, VMS Debugger
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.
3 ILLEVNSTR
Attempt to pass an illegal event structure: structure-name
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit an SPR.
3 ILLFILPTR
file variable points to invalid file descriptor
Facility: DEBUG, VMS Debugger
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.
3 ILLFLOAT
float_value is an illegal floating point value
Facility: DEBUG, VMS Debugger
Explanation: The Debugger attempted to parse the given floating
point number and encountered an illegal character.
User Action: Correct the floating point number.
3 ILLINVNUM
invalid invocation number at invoc_num
Facility: DEBUG, VMS Debugger
Explanation: An illegal invocation number was specified (must be
in decimal radix).
User Action: Specify a legal decimal invocation number.
3 ILLLENGTH
illegal length field length_value in structure reference
Facility: DEBUG, VMS Debugger
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.
3 ILLNUMPATH
illegal numeric pathname at path_name
Facility: DEBUG, VMS Debugger
Explanation: An illegal numeric pathname was specified (must be
in decimal radix).
User Action: Specify a legal decimal numeric pathname.
3 ILLPACSIZ
illegal packed size size_value; must be 0..31
Facility: DEBUG, VMS Debugger
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.
3 ILLPATH1
illegal use of %SOURCE_SCOPE (must not be combined with invocation
numbers)
Facility: DEBUG, VMS Debugger
Explanation: %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.
3 ILLPATH2
illegal use of %SOURCE_SCOPE (must appear at the start of the
pathname)
Facility: DEBUG, VMS Debugger
Explanation: %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.
3 ILLPATHELEM
illegal pathname element at path_name
Facility: DEBUG, VMS Debugger
Explanation: Invocation numbers cannot be used with other
pathnames.
User Action: Eliminate the continuation of the pathname after the
invocation number.
3 ILLPATHIDENT
unknown identifier in pathname at path_name
Facility: DEBUG, VMS Debugger
Explanation: An illegal identifier was specified in the pathname.
User Action: Specify a legal identifier.
3 ILLPOSFLD
position field value position_value is too large
Facility: DEBUG, VMS Debugger
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.
3 ILLQUALIF
illegal or unsupported qualifier on command
Facility: DEBUG, VMS Debugger
Explanation: One of the qualifiers to the command is incorrect.
User Action: Remove the incorrect qualifier to the command.
3 ILLRANGE
subscript range not permitted here (must be at lowest level of data
structure)
Facility: DEBUG, VMS Debugger
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.
3 ILLSETCON
illegal set constant in expression
Facility: DEBUG, VMS Debugger
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.
3 ILLSIGEXT
illegal sign extension field value extension_value
Facility: DEBUG, VMS Debugger
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.
3 ILLSIZFLD
illegal size field size_value; must be 0..size_limit
Facility: DEBUG, VMS Debugger
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 size_limit, inclusive.
3 ILLSUBLEN
substring length larger than 32K not supported
Facility: DEBUG, VMS Debugger
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.
3 ILLSUBSTR
can only apply substring operation to string data types
Facility: DEBUG, VMS Debugger
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.
3 ILLTHUNKADDR
illegal thunk call address
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected a 0 addressed compiler-
supplied routine during Value Spec evaluation.
User Action: Submit a Software Performance Report (SPR) to the
appropriate compiler.
3 ILLTYPE
illegal type of operand(s)
Facility: DEBUG, VMS Debugger
Explanation: The type of the operand is illegal for the operator
specified.
User Action: Change the operand.
3 ILLVQUAL
illegal vector instruction qualifier specified at 'command_line'
Facility: DEBUG, VMS Debugger
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.
3 IMAGENF
target image file_specification not found on host system
Facility: DEBUG, VMS Debugger
Explanation: An image that is loaded on the target system or
represented in the dump file does not have a matching copy on
the host system. The debugger can not load any information about
this image, therefore, symbolic debugging of code in the image is
impossible.
User Action: Check the the image search path on the host system
for this image. Either fix the search path or place a copy of
this image in that path and restart the debug session.
3 IMGMISMATCH
target system image file_specification does not match host copy
Facility: DEBUG, VMS Debugger
Explanation: An image that is loaded on the target system does
not match the host copy of that image. This occurs when the link
time in the image header for the DSF or EXE file on the host does
not match the link time of the target system's image.
User Action: Verify that the image path is set up correctly and
that it points to the same images as are loaded on the target
system.
3 INCDSTNES
incorrect DST nesting in module path_name, compiler error
Facility: DEBUG, VMS Debugger
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.
3 INCMPSTACK
WARNING: stack corrupted; session integrity not guaranteed
Facility: DEBUG, VMS Debugger
Explanation: While walking the call stack, the debugger has
determined that the stack has been corrupted. It did however,
find some valid call frames and will attempt to continue with
that information. Continuation in the presence of a corrupted
stack typically results in unpredictable program and debugger
behavior.
User Action: Look at what little valid information is left and
then start over. Attempt to find and fix the point where the
stack gets corrupted. It may be possible to examine program
state, but continuing instruction execution typically results
in unpredictable program and debugger behavior.
3 INCOMPOPR
operand number operand_number incomplete
Facility: DEBUG, VMS Debugger
Explanation: When parsing an instruction, the debugger found an
incomplete operand.
User Action: Specify complete operands when entering machine
instructions.
3 INCOMPPTR
pointers of different size, cannot perform subtraction
Facility: DEBUG, VMS Debugger
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.
3 INCOMQUAL
qualifier qualifier_name is not compatible with qualifier_name(s)
Facility: DEBUG, VMS Debugger
Explanation: Qualifiers specified with the command conflict in
their operations.
User Action: Specify non-conflicting qualifiers.
3 INCOMTARGET
a debugger_type kernel debugger is incompatible with a debugger_type
main debugger
Facility: DEBUG, VMS Debugger
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.
3 INCOMVERSION
the RPC versions of the main and kernel debuggers are incompatible
Facility: DEBUG, VMS Debugger
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.
3 INDBASEQL
index and base registers are equal for operand number operand_number
Facility: DEBUG, VMS Debugger
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.
3 INIBRK
target system interrupted
Facility: DEBUG, VMS Debugger
Explanation: The target system has hit a break point in the
INI$BRK system routine. The system code calls this routine in
order to return control to the debugger either because the call
is compiled into the code or an IPL 14 interrupt was generated.
User Action: None.
3 INITERR
an error has occurred during debugger initialization, unable to
continue this session.
Facility: DEBUG, VMS Debugger
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.
3 INITIAL
Language: language_name, Module: path_name
Facility: DEBUG, VMS Debugger
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.
3 INPREADERR
error reading input line:
Facility: DEBUG, VMS Debugger
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).
3 INSNOTCURAV
No instructions for address address_value
Facility: DEBUG, VMS Debugger
Explanation: No instructions correspond to the address address_
value.
User Action: None. This message is informational.
3 INSVIRMEM
insufficient virtual memory for the debugger memory pool
Facility: DEBUG, VMS Debugger
Explanation: Failed to allocate additional memory for working
storage.
User Action: Cancel set modules to free space in memory and try
again.
3 INTERR
debugger error in debugger_routine_name or session corruption
Facility: DEBUG, VMS Debugger
Explanation: The debugger has encountered an internal error or
session corruption.
User Action: If the error is reproducible, and is not an obvious
side effect of the user program (i.e. stack corruption, resource
exhaustion, etc.) submit a Software Performance Report (SPR) and
if possible, enclose a copy of the program being debugged, its
build procedure, and a logged debugging session that reproduces
the error.
3 INTERRUPTED
process interrupted via cross-process signal
Facility: DEBUG, VMS Debugger
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.
3 INTMEMERR
internal memory-pool error
Facility: DEBUG, VMS Debugger
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. If the problem still
exists, submit a Software Performance Report (SPR).
3 INTOVF
integer overflow at or near opcode_name
Facility: DEBUG, VMS Debugger
Explanation: The value being deposited does not fit into the
specified address.
User Action: Specify either a smaller value or a different target
address.
3 INTVECERR
internal debugger coding error in using vector instruction(s)
Facility: DEBUG, VMS Debugger
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 a copy of the
program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 INUMTRUNC
number truncated at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 INVALTEXTRANG
error retrieving text from an object.
Facility: DEBUG, VMS Debugger
Explanation: The debugger found a discrepancy in the ranges of
the text string that was retrieved.
User Action: No action necessary.
3 INVARGLIS
invalid argument list for 'the debugger_command_segment'
Facility: DEBUG, VMS Debugger
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.
3 INVARRDIM
array dimension is out of range
Facility: DEBUG, VMS Debugger
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.
3 INVARRDSC
invalid array descriptor
Facility: DEBUG, VMS Debugger
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. This can also be caused by an incomplete array
declaration in C or C++. For example, the declaration extern int
element_array[] can result in an array descriptor with a zero
stride.
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. If the
reference is to an Alpha C array, try accessing the global symbol
table definition for the array by upper-casing the array name.
Otherwise, submit a Software Performance Report (SPR).
3 INVCHAR
invalid character
Facility: DEBUG, VMS Debugger
Explanation: When parsing the command, an invalid character was
detected.
User Action: Enter the command specifying only valid characters.
3 INVCHARLOCALE
invalid character in current locale
Facility: DEBUG, VMS Debugger
Explanation: An illegal character in the current locale has been
found.
User Action: Reenter the string using valid characters.
3 INVCHRCON
invalid character constant in expression
Facility: DEBUG, VMS Debugger
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.
3 INVCMD
command is not available for this configuration
Facility: DEBUG, VMS Debugger
Explanation: This command is not available for this configuration
of the debugger. It may be available in a future version.
User Action: None.
3 INVDEPTH
unable to access stack to depth of depth
Facility: DEBUG, VMS Debugger
Explanation: The debugger is trying to access the register set of
a frame depth frames down on the stack.
User Action: If you explictly requested for information about
that frame, (e.g. via a previous SET SCOPE command), modify your
command such that it is requesting information about a valid
frame.
3 INVDESC
invalid string descriptor
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 INVDIGBIN
invalid digit in binary number: number_value
Facility: DEBUG, VMS Debugger
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'.
3 INVDIGDEC
invalid digit in decimal number: number_value
Facility: DEBUG, VMS Debugger
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'.
3 INVDIGHEX
invalid digit in hexadecimal number: number_value
Facility: DEBUG, VMS Debugger
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'.
3 INVDIGOCT
invalid digit in octal number: number_value
Facility: DEBUG, VMS Debugger
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'.
3 INVDIRNAM
invalid directory name: file_specification
Facility: DEBUG, VMS Debugger
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.
3 INVDMTPTR
invalid DMT pointer; internal linker or debugger error
Facility: DEBUG, VMS Debugger
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).
3 INVDSPSIZ
invalid display size: display_size
Facility: DEBUG, VMS Debugger
Explanation: The SIZE value for a display must be between 1 and
1000.
User Action: Specify the SIZE value between 1 and 1000.
3 INVDSTREC
invalid DST record
Facility: DEBUG, VMS Debugger
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 (SPR).
3 INVEXPR
invalid expression for operand number operand_number
Facility: DEBUG, VMS Debugger
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.
3 INVFILHNDL
invalid file handle
Facility: DEBUG, VMS Debugger
Explanation: The debugger has detected an invalid file handle for
the given context connection. This indicates an internal error in
either the debugger or the compiler.
User Action: Please submit a Software Performance Report.
3 INVFIXDST
invalid DST fixup records in image image_name, symbol references to
shareable images may be erroneous
Facility: DEBUG, VMS Debugger
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.
3 INVFLDREF
invalid field reference; too many or few parameters
Facility: DEBUG, VMS Debugger
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.
3 INVGSTREC
invalid GST record
Facility: DEBUG, VMS Debugger
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 (SPR).
3 INVGSTTYP
invalid GST record; GST is partially built
Facility: DEBUG, VMS Debugger
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).
3 INVMAR
right margin must be greater than left
Facility: DEBUG, VMS Debugger
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.
3 INVNUMBER
invalid numeric string 'number_value'
Facility: DEBUG, VMS Debugger
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.
3 INVNUMSRC
invalid number of source files
Facility: DEBUG, VMS Debugger
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 is 20.
User Action: Re-enter the command specifying a valid number
within the range.
3 INVNUMSTR
invalid numeric string at or near 'number_value'
Facility: DEBUG, VMS Debugger
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.
3 INVOPADDR
invalid operator 'operator_symbol' in address expression
Facility: DEBUG, VMS Debugger
Explanation: Address expressions cannot contain operators.
User Action: Enter the address expression without operators.
3 INVOPSYM
invalid operator symbol 'operator_symbol' in expression
Facility: DEBUG, VMS Debugger
Explanation: Identifiers in address expressions must be shorter
than 256 characters.
User Action: Enter a shorter identifier.
3 INVPAGE
invalid screen height, value must be between minimum_height and
maximum_height
Facility: DEBUG, VMS Debugger
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.
3 INVPASS
the password does not match the target system password
Facility: DEBUG, VMS Debugger
Explanation: The password specified in the connect command does
not match the password in the target systems password file. Or,
no password was specified and the target system requires one.
User Action: Check to make sure the correct node name and
password were specified. Check the target system to make sure
both were set up correctly.
3 INVPRCSYN
process specification syntax error
Facility: DEBUG, VMS Debugger
Explanation: The specified process specification is syntactically
invalid
User Action: Re-enter the command specifying a correct process
specification
3 INVPRIOR
invalid task priority value specified
Facility: DEBUG, VMS Debugger
Explanation: The priority of an Ada task must be between 0 and
15.
User Action: Specify a valid priority for the task.
3 INVRANSPEC
invalid range specification in array subscript
Facility: DEBUG, VMS Debugger
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.
3 INVSELDIS
invalid selection of display_name display; wrong display kind
Facility: DEBUG, VMS Debugger
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.
3 INVSRCLIN
invalid source line range
Facility: DEBUG, VMS Debugger
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.
3 INVTIMSLI
time slice was not set, parameter is out of range
Facility: DEBUG, VMS Debugger
Explanation: The value specified for the time slice was out of
range for the Ada type DURATION used by the debugger.
User Action: See the Ada documentation for the range of the
DURATION type. Specify time slice values which are in range.
3 INVWIDTH
invalid screen width, must be between minimum_width and maximum_
width
Facility: DEBUG, VMS Debugger
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.
3 INVWINPAR
invalid window parameter: number_value
Facility: DEBUG, VMS Debugger
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.
3 IRFAOVF
record file address overflow at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 ISTRTRU
string truncated at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 ITMNOTAVA
item not available
Facility: DEBUG, VMS Debugger
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)
3 ITMTRUNC
item truncated - buffer of insufficient size
Facility: DEBUG, VMS Debugger
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)
3 IVALNOFIT
value does not fit into target location at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 IVALOUTBNDS
value assigned is out of bounds at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 IVPRCLOG
logical name DBG$PROCESS must be either MULTIPROCESS or DEFAULT
Facility: DEBUG, VMS Debugger
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.
3 KEPTNOT1PROC
the Kept Debugger must be run as a multi-process debugger
Facility: DEBUG, VMS Debugger
Explanation: The kept debugger must be a master process running
and rerunning programs as subprocesses. This is not possible for
a one process debugger. The kept debugger must be run using more
than one process.
User Action: Correct the logical name assignment for DBG$PROCESS
to be either "MULTIPROCESS" or "DEFAULT", and try again.
3 KERFUNCNYI
Kernel Function function_name not yet implemented on this
architecture
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 KERNOTAVAIL
host kernel of the VMS system debugger not available
Facility: DEBUG, VMS Debugger
Explanation: The host kernel for the VMS system debugger is not
available on this system so a connection could not be made.
User Action: Contact your Digital Representative on the
availability of this feature.
3 KEYNAMERR
unrecognized key name: key_name
Facility: DEBUG, VMS Debugger
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.
3 KEYSTATERR
unrecognized state name: state_name
Facility: DEBUG, VMS Debugger
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.
3 LASTCHANCE
stack exception handlers lost, re-initializing stack
Facility: DEBUG, VMS Debugger
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.
3 LINEINFO
line-description
Facility: DEBUG, VMS Debugger
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>'
3 LOGFILEIS
the error log is in file file_specification
Facility: DEBUG, VMS Debugger
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 (SPR) and, if possible, enclose a copy of
the program being debugged, program build steps, and a logged
debugging session that reproduces the error.
3 LONGSTRING
strings longer than 2**16 characters not supported
Facility: DEBUG, VMS Debugger
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.
3 LOOPINCR
loop increment cannot be zero
Facility: DEBUG, VMS Debugger
Explanation: The loop increment specified on the FOR command is
zero.
User Action: Change the loop increment to be a non-zero value.
3 LOOPVAR
loop var loop_variable has been redefined; exiting for loop
Facility: DEBUG, VMS Debugger
Explanation: Since the loop variable has been redefined, the
debugger will exit the loop. No further comparison is possible.
User Action: None.
3 LOWBNDOPT
lower bound of subrange was optimized away
Facility: DEBUG, VMS Debugger
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.
3 MAINFUNCNYI
Main Function function_name not yet implemented on this architecture
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 MASKMISMATCH
mask/target subscripts do not match, displaying mask
Facility: DEBUG, VMS Debugger
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.
3 MASKNOTUSED
mask operations not allowed on record and SCAN tree objects
Facility: DEBUG, VMS Debugger
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.
3 MASKNOTVMR
mask used is not %VMR, displaying specified mask
Facility: DEBUG, VMS Debugger
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.
3 MASKPARNREQ
parenthesis required in 'EXAMINE/xMASK=(x)'
Facility: DEBUG, VMS Debugger
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.
3 MATQUOMIS
matching quote is missing
Facility: DEBUG, VMS Debugger
Explanation: The matching quote at the end of a quoted string is
missing.
User Action: Correct the error and re-enter the command.
3 MCHVECNOREAD
mechanism array for exception frame frame-addr at mchvec-addr is not
readable
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined that
part or all of the mechanism array for the exception frame at
frame-addr is not accessible for reading. This vector lies at
mchvec-addr. This usually indicates a corrupt frame list, but
could also indicate that the program has protected part of memory
in which the frame lies. In either case, this is an error.
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".
3 MISCLOSUB
missing closing subscript parenthesis
Facility: DEBUG, VMS Debugger
Explanation: This is a syntax error in a Debug command
User Action: Reinvoke the command with the proper syntax
3 MISINVNUM
misplaced invocation number in path_name
Facility: DEBUG, VMS Debugger
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.
3 MISINVOPER
missing or invalid operator at 'operator_symbol'
Facility: DEBUG, VMS Debugger
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.
3 MISMODBEG
missing Module-Begin record in DST (compiler error)
Facility: DEBUG, VMS Debugger
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 (SPR).
3 MISMODEND
missing Module-End in DST for path_name (compiler error)
Facility: DEBUG, VMS Debugger
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 (SPR).
3 MISOPEMIS
misplaced operator or missing operand at 'operator_symbol'
Facility: DEBUG, VMS Debugger
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.
3 MODUSCOPE
a module name was expected; path_name not valid
Facility: DEBUG, VMS Debugger
Explanation: This is a syntax error in a Debug command
User Action: Reinvoke the command with the proper syntax
3 MONITMNOTFND
error searching for information on a monitor item.
Facility: DEBUG, VMS Debugger
Explanation: When looking for up information for a particular
monitor item, the debugger detected an error.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 MONVALTRUNC
monitor value truncated to 256 characters.
Facility: DEBUG, VMS Debugger
Explanation: The monitor view displays a maximum of 256 character
values.
User Action: You may monitor specific character ranges or monitor
the value in hex.
3 MPARENREQ
parenthesis required around process list in debug_command
Facility: DEBUG, VMS Debugger
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.
3 MPCOMMAND
command is only valid when multiprocess support is enabled
Facility: DEBUG, VMS Debugger
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)
3 NAMSTRMIS
name string missing or invalid in %NAME construct
Facility: DEBUG, VMS Debugger
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.
3 NAMTOOLONG
name is too long: 'symbol_name'
Facility: DEBUG, VMS Debugger
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.
3 NEEDMORE
unexpected end of command line
Facility: DEBUG, VMS Debugger
Explanation: The command entered was not complete. A required
part of the command was omitted.
User Action: Re-enter the complete command.
3 NEEDPAREN
parenthesis required in THEN, ELSE, and DO clauses
Facility: DEBUG, VMS Debugger
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.
3 NETFAIL
network connection failed, reason = reason_code
Facility: DEBUG, VMS Debugger
Explanation: The network connection between the host debugger
and target system can fail for a variaty of reasons. The target
system may have stopped responding or crashed. Or there could
have been too many collisions on the network.
User Action: Check the reason code in the documentation.
3 NETRETRY
connection to target system failed, retrying
Facility: DEBUG, VMS Debugger
Explanation: Either the connection could not be started or was
interrupted due to a failure. The host debugger will try to re-
connect to the target system.
User Action: If no connection is re-made after many retries,
check the target system's console for errors. Also check the
network.
3 NOACCESSR
no read access to address address_value
Facility: DEBUG, VMS Debugger
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.
3 NOACCESSW
no write access to address address_value
Facility: DEBUG, VMS Debugger
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.
3 NOADDRREG
register register_name does not have an address use @register_name
to obtain the contents of register register_name
Facility: DEBUG, VMS Debugger
Explanation: The user has requested the address of a register but
registers do not have addresses
User Action: Examine the register directly
3 NOALOCERRLIST
could not allocate an error list.
Facility: DEBUG, VMS Debugger
Explanation: A problem was detected in the processing of an ACA
Services message and Debug could not allocate an error list so
that this error could be reported to ACA Services.
User Action: Submit a Software Performance Report (SPR).
3 NOALTERSP
deposit into register 14 (stack pointer) not allowed
Facility: DEBUG, VMS Debugger
Explanation: You cannot 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.
3 NOATTACH
attach command failed
Facility: DEBUG, VMS Debugger
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.
3 NOBKPTEXT
error retrieving the text associated with a breakpoint.
Facility: DEBUG, VMS Debugger
Explanation: The debugger could not retrieve the associated text
which belongs to a breakpoint.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 NOBKPTVIEW
the breakpoint view has not been activated.
Facility: DEBUG, VMS Debugger
User Action: Create the breakpoint view from the "VIEW" menu.
3 NOBREAGGR
break or trace points on registers, records or arrays are not
allowed
Facility: DEBUG, VMS Debugger
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.
3 NOBREAKAT
cannot set break or trace at address address_value
Facility: DEBUG, VMS Debugger
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
3 NOBREAKS
no breakpoints are set
Facility: DEBUG, VMS Debugger
Explanation: The SHOW BREAK command was entered and no
breakpoints were set.
User Action: None.
3 NOCALLS
no active call frames
Facility: DEBUG, VMS Debugger
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.
3 NOCANMAIN
cannot cancel main image
Facility: DEBUG, VMS Debugger
Explanation: The user has requested that the main image symbols
be canceled. This is an invalid operation.
User Action: No action required - operation invalid.
3 NOCLI
no CLI present to perform function
Facility: DEBUG, VMS Debugger
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.
3 NOCONNECT
CONNECT command failed
Facility: DEBUG, VMS Debugger
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.
3 NOCONNECTDEBUG
you cannot connect a debugger to itself
Facility: DEBUG, VMS Debugger
Explanation: The process you are trying to connect to is this
debugger.
User Action: Use the connect command with a process name or
process id of the process you actually want to connect to and
that is NOT your current main debugger.
3 NOCORRFAC
cannot perform operation without the Correlation Facility
Facility: DEBUG, VMS Debugger
Explanation: The given operation requires the Correlation
Facility and the appropriate correlation data. Without this
information, the debugger cannot determine how to complete the
operation.
User Action: Make sure that the Correlation Facility is
appropriately set up and in use when compiling and debugging
the given program.
3 NOCROSSPROC
cross-process signal system service is not available
Facility: DEBUG, VMS Debugger
Explanation: The debugger was unable to execute the specified
command because the cross-process signal system service is not
available in this version of VMS.
User Action: Upgrade to a version of VMS that has the cross-
process signal system service.
3 NOCROSSUICGRP
cannot connect to a process with a different UIC group
Facility: DEBUG, VMS Debugger
Explanation: The given operation is not supported by the
Debugger. You can only connect to processes with the same UIC
group as the process running the Debugger.
User Action: Make sure that the process you want to connect to is
in the same UIC group as the process running the Debugger.
3 NOCURLOC
current location not defined
Facility: DEBUG, VMS Debugger
Explanation: '.' is not currently defined.
User Action: Do not reference '.' until an EXAMINE or
EVALUATE/ADDRESS command has been performed.
3 NODECTHREADSUP
this command qualifier is not supported by POSIX Threads
Facility: DEBUG, VMS Debugger
Explanation: The POSIX Threads facility does not support this
feature.
User Action: None.
3 NODEFSCPE
No default scope list: error performing !AC
Facility: DEBUG, VMS Debugger
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.
3 NODEFWIND
no default window in which to attach your display.
Facility: DEBUG, VMS Debugger
Explanation: The display specified did not have a window
associated with it. The Debugger attempted to attach it to a
default window called H1. Debugger discovered that the H1 window
had been deleted.
User Action: Either re-create window H1 or specifically specify a
window that exists when creating a new display.
3 NODELIMTR
missing or invalid instruction operand delimiter
Facility: DEBUG, VMS Debugger
Explanation: A DEPOSIT command specified an invalid instruction
operand format.
User Action: Re-enter the command with valid operands.
3 NODEPDEBUG
depositing into the debugger's address space is not allowed
Facility: DEBUG, VMS Debugger
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.
3 NODIRLISM
no source directory list in effect for path_name
Facility: DEBUG, VMS Debugger
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.
3 NODIRLIST
no source directory list in effect
Facility: DEBUG, VMS Debugger
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.
3 NODIRNAMESELECTED
no directory is selected.
Facility: DEBUG, VMS Debugger
3 NODISCONNECT
DISCONNECT command failed
Facility: DEBUG, VMS Debugger
Explanation: The debugger was unable to execute the disconnect
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.
3 NODSTIMG
no symbols in image_name
Facility: DEBUG, VMS Debugger
Explanation: The image is linked with the /NODEBUG qualifier, so
there is no symbol table.
User Action: Relink the image with the /DEBUG qualifier.
3 NODSTS
no Debugger Symbol Table: no DSF file found and
Facility: DEBUG, VMS Debugger
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.
3 NOELABBODY
package body path_name has no executable code
Facility: DEBUG, VMS Debugger
3 NOELABSPEC
package spec path_name has no executable code
Facility: DEBUG, VMS Debugger
3 NOEND
string beginning with 'string_value' is missing end delimiter
delimiter_character
Facility: DEBUG, VMS Debugger
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.
3 NOEPTSPEC
no eventpoints were specified with a SHOW or CANCEL command.
Facility: DEBUG, VMS Debugger
Explanation: Eventpoints were not given with a SHOW or CANCEL
command.
User Action: Try the command again, specifying eventpoints to
operate on.
3 NOEVALEXPR
unable to evaluate expression for following reason
Facility: DEBUG, VMS Debugger
Explanation: The expression could not be evaluated. The following
message indicates why.
User Action: See the following message.
3 NOEVENTFAC
the /EVENT qualifier is not allowed: first type 'SET EVENT facility'
to specify an event facility
Facility: DEBUG, VMS Debugger
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.
3 NOEXCBRE
no exception breaks were set
Facility: DEBUG, VMS Debugger
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.
3 NOEXHND
no exit handlers are declared
Facility: DEBUG, VMS Debugger
Explanation: There are no user-mode exit handlers currently
declared.
User Action: None. This message is informational.
3 NOEXITRUN
cannot exit running process !UL-you must STOP it first
Facility: DEBUG, VMS Debugger
Explanation: The debugger cannot exit from the indicated process
because it is running. In order exit the process, it must first
be stopped.
User Action: Use the STOP command to exit the process.
3 NOFIELD
'field_name' is not a field in this record
Facility: DEBUG, VMS Debugger
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.
3 NOFREE
no free storage available
Facility: DEBUG, VMS Debugger
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 the system manager can
increase the virtual memory on your system.
3 NOGLOBALS
some or all global symbols not accessible
Facility: DEBUG, VMS Debugger
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.
3 NOHEAP
the Heap Analyzer will not be invoked
Facility: DEBUG, VMS Debugger
Explanation: The debugger encountered a problem trying to define
the librtl logical required to invoke the Heap Analyzer.
User Action: Insure there is enough room in the process logical
name table for the debugger to define the librtl logical. If so,
and the command still fails, define the librtl logical at the
DCL level, restart the debugger and reexecute the RUN or RERUN
command.
3 NOHIDDENDEBUG
message cannot be executed when the UI is hidden.
Facility: DEBUG, VMS Debugger
Explanation: The Debug message cannot be executed when a HideUI
message is in effect.
User Action: Send the ShowUI message and then re-execute the
Debug message.
3 NOHLPLIB
the debugger could not open the help library file
Facility: DEBUG, VMS Debugger
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.
3 NOINPAVAIL
input objects not available
Facility: DEBUG, VMS Debugger
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.
3 NOINPFOC
debugger must have input focus to accept paste operation
Facility: DEBUG, VMS Debugger
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.
3 NOINSTRAN
cannot translate opcode at location address_value
Facility: DEBUG, VMS Debugger
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.
3 NOINVCTXINSTHAN
cannot retrieve the invocation context instance handle.
Facility: DEBUG, VMS Debugger
Explanation: In the course of trying to execute an ACA Services
message, Debug has tried and failed to retrieve the invocation
context instance handle from ACA Services.
User Action: Submit a Software Performance Report (SPR).
3 NOKERNEL
this kernel debugger does not exist in this context
Facility: DEBUG, VMS Debugger
Explanation: Debug main is trying to communicate with the kernel
debugger in a context where the kernel debugger does not exist.
User Action: Submit a Software Performance Report (SPR).
3 NOKEYDEF
cannot accept keypad input, mode is set to NOKEYPAD
Facility: DEBUG, VMS Debugger
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.
3 NOKEYPAD
unable to set up keypad definitions
Facility: DEBUG, VMS Debugger
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).
3 NOLASTVAL
last value is not defined
Facility: DEBUG, VMS Debugger
Explanation: '\' is not currently defined.
User Action: Do not reference '\' until a DEPOSIT or EVALUATE
command has been performed.
3 NOLINXXX
line_descriptor
Facility: DEBUG, VMS Debugger
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.
3 NOLIST
list of parameter values not allowed - check use of comma (,)
Facility: DEBUG, VMS Debugger
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.
3 NOLOCALS
image does not contain local symbols
Facility: DEBUG, VMS Debugger
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.
3 NOMAIN
error trying to fetch the main window from the Motif Resource
Manager (MRM).
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when trying to fetch
debuggers main window from the Resource Manager. 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).
3 NOMAINIMAGE
host copy of the main system image not found
Facility: DEBUG, VMS Debugger
Explanation: The debugger running on the host system could not
find a local copy of the target system's main image - SYS$BASE_
IMAGE.
User Action: Check to make sure the image search path for
the host is set up correctly. See the System-Code Debugger
documentation for details.
3 NOMARKCHNG
[NO]MARK_CHANGE qualifier not applicable to display_name display
Facility: DEBUG, VMS Debugger
Explanation: The /MARK_CHANGE and /NOMARK_CHANGE qualifiers can
not be applied to the indicated kind of display.
User Action: None.
3 NOMATCH
no matches
Facility: DEBUG, VMS Debugger
Explanation: A SEARCH command was being used and no matches were
found
User Action: No action required
3 NOMONEXPR
no monitor entry was found matching "expression"
Facility: DEBUG, VMS Debugger
Explanation: The input "monitor /delete" expression does not
match with any currenly monitored item.
User Action: Retry "monitor /delete" with corrected expression.
3 NOMORE
wildcard request complete
Facility: DEBUG, VMS Debugger
Explanation: This is a debugger internal error code.
User Action: If the debugger reports this error please submit a
Software Performance Report.
3 NOMOTIF
Motif images not found; defaulting to command interface
Facility: DEBUG, VMS Debugger
Explanation: The images of the Motif layered product are
optionally installed. If the Motif user interface to the debugger
is desired, then Motif must be properly installed, otherwise the
default character cell mode will run.
User Action: If desiring the Motif user interface, check that
Motif is installed correctly.
3 NONAMEDWIDGET
widget by name !AC not found in the UID file.
Facility: DEBUG, VMS Debugger
3 NONAMEMATCH
specified name does not match any name in the selection box.
Facility: DEBUG, VMS Debugger
Explanation: A name was entered as the selection that is not in
the selection box.
User Action: Select a name from the box.
3 NONEXPR
nonexistent process
Facility: DEBUG, VMS Debugger
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.
3 NONEXPRC
process process-specification does not exist
Facility: DEBUG, VMS Debugger
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.
3 NONUMSCOPE
scope does not exist or is not in set module: scope_number
Facility: DEBUG, VMS Debugger
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.
3 NONXTLIN
next line for source display not defined
Facility: DEBUG, VMS Debugger
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.
3 NOOCCLDISP
display_name display may not be occluded
Facility: DEBUG, VMS Debugger
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.
3 NOOPNIMAGE
cannot open image image_name
Facility: DEBUG, VMS Debugger
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.
3 NOOUTAVAIL
output objects are not available
Facility: DEBUG, VMS Debugger
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.
3 NOOUTVIEW
error writing to the Message view.
Facility: DEBUG, VMS Debugger
Explanation: The debugger got an unexpected status when trying
to write to the Message view . 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).
3 NOPACKMEMBODY
'symbol_name' is not a member of package body path_name
Facility: DEBUG, VMS Debugger
3 NOPACKMEMSPEC
'symbol_name' is not a member of package spec path_name
Facility: DEBUG, VMS Debugger
3 NOPARSEINSTHAND
cannot parse the invocation context instance handle.
Facility: DEBUG, VMS Debugger
Explanation: Debug cannot parse the invocation context instance
handle retrieved from ACA Services.
User Action: Submit a Software Performance Report (SPR).
3 NOPRED
logical predecessor not defined
Facility: DEBUG, VMS Debugger
Explanation: The logical predecessor of the identifier or
instruction referenced is not defined.
User Action: None. This message is informational.
3 NOPROCDEBUG
there are currently no processes being debugged
Facility: DEBUG, VMS Debugger
Explanation: The debug session is currently not connected to any
user processes.
User Action: Either RUN a program or CONNECT to a program.
3 NOPROCESSES
the current command is targetted at an empty process set
Facility: DEBUG, VMS Debugger
Explanation: The set of processes at which the current command is
targetted is empty.
User Action: Either change the current process set, run a
program, connect to a program, stop a program or wait for a
program
3 NOPROGRAM
function function_name requires a running program.
Facility: DEBUG, VMS Debugger
Explanation: There is no program currently being debugged.
User Action: Start a program using RUN or RERUN, then reenter the
command.
3 NOPROMPT
cannot delete, remove, unselect, or change kind of the display_name
display
Facility: DEBUG, VMS Debugger
Explanation: This display can not be deleted, removed,
unselected, or have it's kind changed.
User Action: None.
3 NOPTHDBG
no compatible pthread debugger established
Facility: DEBUG, VMS Debugger
Explanation: Either this threaded application is not controlled
by PTHREAD$RTL or else this debugger was built to interface with
a PTHREAD$DBGSHR that is incompatible with the system PTHREAD$RTL
version
User Action: pthread commands are not possible, use older task
commands, for example, SHOW TASK/ALL, or upgrade your POSIX
Threads environment
3 NORADBLIFLD
radix override not allowed with BLISS fields
Facility: DEBUG, VMS Debugger
Explanation: The use of a radix override qualifier is not
supported when evaluating a BLISS field reference. BLISS field
references are always displayed using a decimal notation. It is,
however, possible to use a radix override qualifier when refering
to the contents of a BLISS field.
User Action: Don't use a radix switch with a BLISS field.
3 NORECSYM
recursive symbol_type symbol definition encountered at or near
'debugger_command_segment'
Facility: DEBUG, VMS Debugger
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.
3 NOREDEFINE
predefined process set !AC cannot be redefined
Facility: DEBUG, VMS Debugger
Explanation: Predefined process set cannot be redefined.
User Action: Choose a different name for the user-defined process
set.
3 NORERUNPGM
there is no program to RERUN.
Facility: DEBUG, VMS Debugger
Explanation: You must RUN a program first before you can RERUN
it.
User Action: Use the RUN command and specify a program.
3 NORESUME
unable to resume execution, stack or PC corrupted in %PROCESS_NUMBER
process_id
Facility: DEBUG, VMS Debugger
Explanation: The debugger has determined that the stack or PC
is corrupted. The top application frame is so corrupted that the
debugger is unable to do normal STEPs and GOs.
User Action: Look at what little valid information is left,
especially the call stack, machine instruction view, current
PC, FP, etc. It may be possible to realize the stack corruption
and fix it by hand through deposits to stack locations and
registers. It should also be possible to CALL or GO newPC if
the call target or newPC is valid. More likely, you will need
exit/quit, start over, and attempt to find and fix the point
where your application corrupts the stack or PC.
3 NORETBRKALTBRK
unable to set return break; breakpoint set on caller's return PC.
Facility: DEBUG, VMS Debugger
Explanation: This is a debugger internal error code.
User Action: If the debugger reports this error please submit a
Software Performance Report.
3 NORETBRKSTEP
unable to set return break, stepping to caller's return PC.
Facility: DEBUG, VMS Debugger
Explanation: This is a debugger internal error code.
User Action: If the debugger reports this error please submit a
Software Performance Report.
3 NORMAL
successful debugger status
Facility: DEBUG, VMS Debugger
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).
3 NORSTBLD
cannot build symbol table
Facility: DEBUG, VMS Debugger
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.
3 NOSAVEDREGS
can't find the saved registers for the CALL command for frame frame-
addr
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined
that the frame at frame-addr was caused by a CALL command from
the debugger. The debugger is unable to find the register set it
saved for the context before the CALL command.
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".
3 NOSAVPROG
cannot save a program I/O display
Facility: DEBUG, VMS Debugger
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.
3 NOSCOPE
no scope exists to look up line line_number
Facility: DEBUG, VMS Debugger
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.
3 NOSCOPELIST
a list of scopes is not allowed with this command.
Facility: DEBUG, VMS Debugger
Explanation: You cannot enter a list of scopes with the
previously executed command.
User Action: Enter the command with only one scope item.
3 NOSCRATCHSPACE
the target system has run out of scratch space
Facility: DEBUG, VMS Debugger
Explanation: Scratch space is allocated on the target system to
implement single stepping. The target system has run out of this
space so no more work can be done.
User Action: Reboot the target system with more scratch space and
try the debugger again. See the documentation for more details.
3 NOSCRDEV
screen mode is not supported on this device screen mode output is
being lost
Facility: DEBUG, VMS Debugger
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.
3 NOSCRMODE
screen mode is not supported on this terminal screen mode is not set
Facility: DEBUG, VMS Debugger
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
3 NOSCROLL
no scrolling display selected or missing display name
Facility: DEBUG, VMS Debugger
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.
3 NOSCROLLDISP
display_name display may not be scrolled
Facility: DEBUG, VMS Debugger
Explanation: This display can not be scrolled.
User Action: None.
3 NOSEGLIST
error trying to access a source display segment in routine function_
name.
Facility: DEBUG, VMS Debugger
Explanation: The debugger got an unexpected status when trying to
access a source display segment. 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).
3 NOSEMEVENTS
no semantic events defined for the specified symbol
Facility: DEBUG, VMS Debugger
Explanation: There are no semantic events defined for the
specified symbol.
User Action: Pick a different symbol.
3 NOSETTERM
the SET TERMINAL command is not supported on this terminal
Facility: DEBUG, VMS Debugger
Explanation: The SET TERMINAL command is not allowed on the
terminal being used for the current session
User Action: Use another type of terminal
3 NOSMG
could not locate SMGSHR (or locale specific equivalent)
Facility: DEBUG, VMS Debugger
Explanation: The debugger relies on the ability to dynamically
link to the SMGSHR.EXE (or a locale specific equivalent) at
runtime. (The locale specific equivalent of SMGSHR.EXE is denoted
by defining logical, DBG$SMGSHR.) When this error occurs, the
debugger cannot locate the SMG sharable image and hence, cannot
run.
User Action: Verify that the SMG sharable image exists. If so,
please submit a Software Performance Report.
3 NOSPAWN
spawn command failed
Facility: DEBUG, VMS Debugger
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.
3 NOSRCHSTR
search string not set
Facility: DEBUG, VMS Debugger
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.
3 NOSRCLIN
no source line for address address_value
Facility: DEBUG, VMS Debugger
Explanation: No source line corresponds to the address address_
value specified on the debugger command EXAMINE/SOURCE.
User Action: None. This message is informational.
3 NOSTEPGO
no STEP, GO, SET PROCESS/VISIBLE or CALL commands allowed in screen
displays
Facility: DEBUG, VMS Debugger
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.
3 NOSUCC
logical successor not defined
Facility: DEBUG, VMS Debugger
Explanation: The logical successor of the referenced instruction
or identifier is not defined.
User Action: None. This message is informational.
3 NOSUCHBPT
no such breakpoint
Facility: DEBUG, VMS Debugger
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.
3 NOSUCHDISP
no such display defined: display_name
Facility: DEBUG, VMS Debugger
Explanation: The specified display <display_name, !AC> does not
exist.
User Action: Re-enter the command, specifying an existing
display.
3 NOSUCHELP
no such help topic or invalid HELP command
Facility: DEBUG, VMS Debugger
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
3 NOSUCHIMG
image image_name not found
Facility: DEBUG, VMS Debugger
Explanation: The specified image <image_name, !AC> does not
exist.
User Action: Re-enter the command, specifying an existing image.
3 NOSUCHMODU
module path_name is not in module chain
Facility: DEBUG, VMS Debugger
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.
3 NOSUCHPACK
library package path_name is not in the symbol table
Facility: DEBUG, VMS Debugger
3 NOSUCHSCOPE
scope does not exist or is not in set module: scope_name
Facility: DEBUG, VMS Debugger
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
3 NOSUCHTASK
no such task exists or no task satisfies criteria
Facility: DEBUG, VMS Debugger
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.
3 NOSUCHTPT
no such tracepoint
Facility: DEBUG, VMS Debugger
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.
3 NOSUCHWIND
no such window defined: display_name
Facility: DEBUG, VMS Debugger
Explanation: The specified, or defaulted window <window_name,
!AC> does not exist.
User Action: Reenter the command, specifying an existing window
name.
3 NOSUCHWPT
no such watchpoint
Facility: DEBUG, VMS Debugger
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.
3 NOSYMBOL
symbol 'symbol_name' is not in the symbol table
Facility: DEBUG, VMS Debugger
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.
3 NOSYMBOLR
no symbol 'symbol_name' was declared in routine path_name
Facility: DEBUG, VMS Debugger
3 NOTADAPROG
program is not an ADA program; command ignored
Facility: DEBUG, VMS Debugger
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.
3 NOTARRAY
type of variable is not array
Facility: DEBUG, VMS Debugger
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.
3 NOTASTRUCT
'symbol_name' was not declared as a structure
Facility: DEBUG, VMS Debugger
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.
3 NOTATMAIN
Type GO to reach MAIN program
Facility: DEBUG, VMS Debugger
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.
3 NOTCURPC
target of EXAMINE/OPERANDS is not the current PC results may be
unexpected
Facility: DEBUG, VMS Debugger
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
3 NOTDECTHREADS
program does not use POSIX Threads services.
Facility: DEBUG, VMS Debugger
Explanation: The entered command applies only to programs using
POSIX Threads services.
User Action: No user action required.
3 NOTDEFINE
defined_symbol was not defined
Facility: DEBUG, VMS Debugger
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.
3 NOTEDITABLE
this text can not be edited.
Facility: DEBUG, VMS Debugger
3 NOTEXPANDABLE
this entry cannot be expanded.
Facility: DEBUG, VMS Debugger
3 NOTEXTSELECTED
select some text and try again.
Facility: DEBUG, VMS Debugger
3 NOTIMPLAN
expression_type is not implemented at command level
Facility: DEBUG, VMS Debugger
Explanation: The expression_type is not supported at this type.
User Action: Specify a type of expression that the debugger
supports.
3 NOTIMSLI
time slice modification not supported by this event facility
Facility: DEBUG, VMS Debugger
Explanation: The current event facility does not support the
ability to to dynamically modify time slicing in the debugger.
User Action: This operation is not supported by the debugger. The
user must recode his application to change time slicing.
3 NOTINLOOP
exitloop encountered when not in a loop
Facility: DEBUG, VMS Debugger
Explanation: An incorrect nesting of loops exist in the command
stream currently being executed.
User Action: Correct the command stream
3 NOTINSCOPE
specified scope cannot be found in the default scope list
Facility: DEBUG, VMS Debugger
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.
3 NOTINST
examined address is not the start of an instruction
Facility: DEBUG, VMS Debugger
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.
3 NOTKEPT
Function function_name applies only to Kept Debugger configuration.
Facility: DEBUG, VMS Debugger
Explanation: This command only makes sense when executed from the
Kept Debugger configuration of DECdebug.
User Action: Restart debugger using the Kept Debugger
configuration and re-enter the command.
3 NOTNUMSCOPE
specified scope is not a numbered scope.
Facility: DEBUG, VMS Debugger
Explanation: The SET SCOPE/CURRENT command requires a numbered
scope.
User Action: Enter the command with a numbered scope.
3 NOTORIGSRC
original version of source file not found file used is file_
specification
Facility: DEBUG, VMS Debugger
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.
3 NOTPTR
variable must be of pointer or file type
Facility: DEBUG, VMS Debugger
Explanation: The variable should be a pointer or a file type.
User Action: Specify a variable of pointer or file type.
3 NOTRACES
no tracepoints are set, no opcode tracing
Facility: DEBUG, VMS Debugger
Explanation: There are no tracepoints or opcode tracing set.
User Action: None. This message is informational.
3 NOTRAZERO
Unable to find a trailing zero for ASCIZ object at address address_
value
Facility: DEBUG, VMS Debugger
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.
3 NOTRECORD
variable is not record; cannot select component component_name
Facility: DEBUG, VMS Debugger
Explanation: The user has requested a record operation on a
variable which is not a record.
User Action: Correct the command and reissue it
3 NOTREE
SCAN tree or subtree not found SCAN error message
Facility: DEBUG, VMS Debugger
3 NOTRUNDW
the debugger is uncertain about the DECWindow configuration.
Facility: DEBUG, VMS Debugger
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).
3 NOTSAVED
Unable to save configuration options.
Facility: DEBUG, VMS Debugger
Explanation: The Debugger was unable to access the necessary
resource file.
User Action: If attempting to SAVE OPTIONS, check to be sure
that the logical name DECW$USER_DEFAULTS is properly defined
and that the assigned directory has write access. If attempting
to RESTORE DEFAULT OPTIONS, check to be sure both logicals
DECW$USER_DEFAULTS and DECW$SYSTEM_DEFAULTS are properly defined
and are accessible. The user defaults directory must have write
access while the system defaults directory must have read access.
Finally, be sure that the file DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT
exists (installed during Operating System installation). If not,
contact your system manager.
3 NOTTASKVAL
expression does not specify a valid task value
Facility: DEBUG, VMS Debugger
Explanation: The expression entered does not specify a valid task
value. Only Ada task values are known as such in the symbol table
- Thread values are considered to be pointers.
User Action: Unless you are debugging threads, reenter the
command, correctly specifying a task value.
3 NOTTHREADNUM
expression does not specify a valid thread number
Facility: DEBUG, VMS Debugger
Explanation: The expression entered does not specify a valid
thread sequence number.
User Action: Reenter the command, correctly specifying a thread
number.
3 NOTUISOSC
the debugger will be unable to create a separate window; OSC not
enabled.
Facility: DEBUG, VMS Debugger
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.
3 NOTUISV30
the debugger will be unable to create a separate window; UIS too
old.
Facility: DEBUG, VMS Debugger
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.
3 NOTUNQOVR
symbol 'symbol_name' is overloaded
Facility: DEBUG, VMS Debugger
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.
3 NOTUPDATE
instruction screen display not updated
Facility: DEBUG, VMS Debugger
Explanation: The instruction screen display was not updated
because of the preceding error message.
User Action: See the preceding error message.
3 NOTYPEINFO
symbol type information not available please SET the module that
describes this type
Facility: DEBUG, VMS Debugger
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
3 NOTYPELEN
'symbol_name' has no type or length information, cannot proceed.
Facility: DEBUG, VMS Debugger
Explanation: The requested information cannot be obtained because
the entity in question doesn't have all the attributes necessary
to follow through with the request.
User Action: None. This message is informational.
3 NOUI
debugger user interface image not found; defaulting to command
interface
Facility: DEBUG, VMS Debugger
Explanation: The user interface portion of the debugger is a
separate image which cannot be located.
User Action: Check that the debugger is properly installed. If
so, please submit a Software Performance Report (SPR).
3 NOUNIQ
symbol 'symbol_name' is not unique
Facility: DEBUG, VMS Debugger
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.
3 NOUNIQUE
symbol 'symbol_name' is not unique
Facility: DEBUG, VMS Debugger
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.
3 NOUNIVERSALS
shareable image contains no universal symbols
Facility: DEBUG, VMS Debugger
Explanation: No universal symbols were found in the image.
User Action: None.
3 NOUSREVNT
no user-specified events are allowed; none are declared
Facility: DEBUG, VMS Debugger
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.
3 NOVALATPC
entity 'symbol_name' does not have a value at the current PC
Facility: DEBUG, VMS Debugger
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.
3 NOVALTYP
'symbol_name' has no value because it is a type name
Facility: DEBUG, VMS Debugger
3 NOVALUE
reference does not have a value
Facility: DEBUG, VMS Debugger
Explanation: The command specified a reference that has no value.
User Action: Change the reference.
3 NOVECT
no vector support - command cannot be performed
Facility: DEBUG, VMS Debugger
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.
3 NOVIEWQUAL
no qualifier specified on the VIEW command
Facility: DEBUG, VMS Debugger
Explanation: There were no qualifiers specified on the VIEW
command.
User Action: Reenter the command, specifying a qualifier for the
VIEW command.
3 NOWATCHES
no watchpoints are set
Facility: DEBUG, VMS Debugger
Explanation: No watchpoints are set.
User Action: None. This message is informational.
3 NOWATONOPT
cannot watch entity; not in memory (was optimized away)
Facility: DEBUG, VMS Debugger
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
3 NOWATTAR
cannot watch protected target
Facility: DEBUG, VMS Debugger
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.
3 NOWATVARIA
cannot set watchpoints on variant records
Facility: DEBUG, VMS Debugger
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
3 NOWATVARSTG
watchpoints not allowed after SET TYPE ASCIC, ASCIW, or ASCIZ
Facility: DEBUG, VMS Debugger
3 NOWBPT
cannot insert breakpoint
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 NOWILD
no wildcard permitted
Facility: DEBUG, VMS Debugger
Explanation: Wildcards are not permitted in this context
User Action: Re-enter the command without using wildcards
3 NOWILDFIL
file name, type, and version cannot be wildcarded
Facility: DEBUG, VMS Debugger
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.
3 NOWOPCO
cannot replace breakpoint with opcode
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 NOWPROT
cannot set protection
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 NOWRITEACCESS
unable to set breakpoint at break-addr, no write access.
Facility: DEBUG, VMS Debugger
Explanation: Most debugger startups set a breakpoint in the user
program and then return control to that program. The debugger
regains control when that breakpoint is hit. It is necessary for
the debugger to have write access to the user program in order to
set breakpoints.
User Action: Change/allow write access to your program's code.
3 NO_SYNC_FROM_EXC_BRE
synchronize can not be done from an exception break.
Facility: DEBUG, VMS Debugger
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.
3 NPROMPT
could not initialize state to accept input.
Facility: DEBUG, VMS Debugger
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).
3 NULLPTR
cannot dereference null pointer
Facility: DEBUG, VMS Debugger
3 NULWIDGET
error retrieving widget information in routine function_name.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when retrieving
information on a particular widget in the MOTIF toolkit. 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).
3 NUMCONLONG
numeric constant too long, please shorten
Facility: DEBUG, VMS Debugger
Explanation: A number entered in the command line is too long.
User Action: Reenter the command, shortening the long number.
3 NUMTRUNC
number truncated
Facility: DEBUG, VMS Debugger
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.
3 NYI
function is not yet implemented.
Facility: DEBUG, VMS Debugger
3 OBJECTINV
requested object is invalid
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit an SPR.
3 OBJPTRINV
the pointer associated with the requested object is invalid
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit an SPR.
3 OBJTYPMIS
the type associated with the requested object is incorrect
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit an SPR.
3 OBSOLETE_1
this message is available for reuse
Facility: DEBUG, VMS Debugger
Explanation: This message is obsolete, and should never be seen.
User Action: Please submit a Software Performance Report.
3 OBSOLETE_2
this message is available for reuse
Facility: DEBUG, VMS Debugger
Explanation: This message is obsolete, and should never be seen.
User Action: Please submit a Software Performance Report.
3 OBSOLETE_3
this message is available for reuse
Facility: DEBUG, VMS Debugger
Explanation: This message is obsolete, and should never be seen.
User Action: Please submit a Software Performance Report.
3 OBSOLETE_4
this message is available for reuse
Facility: DEBUG, VMS Debugger
Explanation: This message is obsolete, and should never be seen.
User Action: Please submit a Software Performance Report.
3 OBSOLETE_5
this message is available for reuse
Facility: DEBUG, VMS Debugger
Explanation: This message is obsolete, and should never be seen.
User Action: Please submit a Software Performance Report.
3 OPCDEC
no support for G/H instructions at or near opcode_name
Facility: DEBUG, VMS Debugger
3 OPNOTALLOW
operator 'operator_symbol' not allowed on given data types
Facility: DEBUG, VMS Debugger
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.
3 OPSYNTAX
instruction operand syntax error for operand number operand_number
Facility: DEBUG, VMS Debugger
Explanation: The debugger encountered an error in one of the
operands of an 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.
3 OUTPUTLOST
output being lost, both NOTERMINAL and NOLOG are in effect
Facility: DEBUG, VMS Debugger
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.
3 OVRWIDGETFAIL
error trying to fetch and override an object from MRM in routine
function_name.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when fetching an
object from the Motif Resource Manager (MRM) for the purpose of
overriding behavior. 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).
3 PACSIZREQ
packed size required
Facility: DEBUG, VMS Debugger
Explanation: A size parameter is required
User Action: Supply a size parameter and reissue the command
3 PARENREQ
parentheses required around qualifier value in 'debug_cmd_segment'
Facility: DEBUG, VMS Debugger
Explanation: The indicated qualifier value must be surrounded by
parentheses.
User Action: Place parentheses around the type of expression
specified.
3 PARSTKOVR
parse stack overflow, simplify expression
Facility: DEBUG, VMS Debugger
Explanation: The expression was too complex for the debugger to
evaluate.
User Action: Simplify the expression.
3 PASTHRU
The primary handler should ignore this signal
Facility: DEBUG, VMS Debugger
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).
3 PATHNOTACP
pathname qualifiers (path_name) not allowed in SHOW SYMBOL data name
Facility: DEBUG, VMS Debugger
Explanation: The user has issued a command with invalid syntax
User Action: No user action required
3 PATHTLONG
too many qualifiers on name
Facility: DEBUG, VMS Debugger
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.
3 PATHTOOLONG
pathname too long at path_name
Facility: DEBUG, VMS Debugger
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.
3 PCLINLOOKUP
error trying to associate the PC with a line number.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when looking up the
PC to line number correlation.
User Action: Try the debugger again, if the same results exist
submit a Software Performance Report (SPR).
3 PCNOTALL
PC not allowed in context for operand number operand_number
Facility: DEBUG, VMS Debugger
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.
3 PLICVTERR
PLI conversion error at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 PREDEPTNOT
predefined eventpoint(s) not canceled
Facility: DEBUG, VMS Debugger
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.
3 PRMNOTAVAIL
the command parameter parameter_name is not available
Facility: DEBUG, VMS Debugger
Explanation: The specified command parameter, although available
in some debug implementations, is not available in this one.
One reason why is that the parameter just doesn't make sense
on the platform. For example, the JSB parameter on a SET STEP
command doesn't make sense on Alpha VMS because there is no "JSB"
instruction like there is on VAX VMS.
User Action: Reissue the command without the parameter.
3 PRNOTRDY
process not ready
Facility: DEBUG, VMS Debugger
Explanation: A process name or process identification specified
in a command is either delete pending or not fully connected to
yet.
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.
3 PROFRANOT
proper frame not found on call stack for path_name
Facility: DEBUG, VMS Debugger
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.
3 PROMPTCLEN
display_name display width not changed, must be full width of screen
Facility: DEBUG, VMS Debugger
Explanation: This display's width can not be changed. It must be
the full width of the screen.
User Action: None.
3 PROMPTOCCL
display_name display now occludes some or all of display_name
display's text
Facility: DEBUG, VMS Debugger
Explanation: This display now occludes some or all of the
specified display.
User Action: None.
3 PROMPTRLEN
display_name display length not changed, must be at least 2 lines
long
Facility: DEBUG, VMS Debugger
Explanation: This display's length can not be changed to less
than the minimum value specified.
User Action: None.
3 PROVRFLOW
too many levels of @ procedure nesting
Facility: DEBUG, VMS Debugger
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
3 PSHINARYNYI
PUSH_INNER_ARRAY DST stack machine operator for array 'symbol_name'
is not yet implemented
Facility: DEBUG, VMS Debugger
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.
3 PSHVALNYI
PUSH_VALSPEC DST stack machine operator for variable 'symbol_name'
is not yet implemented
Facility: DEBUG, VMS Debugger
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.
3 PTHDBGFAIL
PTHREAD debugger call failed, error code (hex) status
Facility: DEBUG, VMS Debugger
Explanation: The OpenVMS Debug PTHREAD command calls a POSIX
Threads Debugger image. That call failed.
User Action: Check your POSIX Threads Debugger command syntax and
semantics (see Guide to POSIX Threads, debugging appendix).
3 PTHREADINVALCMD
invalid POSIX Threads debugger command
Facility: DEBUG, VMS Debugger
Explanation: Your PTHREAD command had an invalid POSIX Threads
debugger command string. See Debugger Manual and Guide To POSIX
Threads for legal POSIX Threads debugger command strings.
User Action: Re-issue the command with a legal POSIX Threads
debugger command string.
3 PTRNOTSET
'symbol_name' is not initialized (try a STEP command first)
Facility: DEBUG, VMS Debugger
Explanation: An object containing either virtual member functions
or virtual base classes contain pointers to tables which are used
to implement those features of the C++ language. Such a pointer
is initialized by a constructor, and hence is not valid prior to
the execution of that constructor. Certain debugger operations
applied to such an object require that such a pointer to be valid
in order for the debugger operation to complete successfully.
User Action: Advance the program until the appropriate
constructor has been executed. Usually, a single STEP command
will suffice.
3 PXCN
record object or record formal parameter must prefix 'CONSTRAINED
Facility: DEBUG, VMS Debugger
3 QUALNOTAVAIL
the command qualifier qualifier_name is not available
Facility: DEBUG, VMS Debugger
Explanation: The specified command qualifier, although available
in some debug implementations, is not available in this one.
One reason why is that the qualifier just doesn't make sense
on the platform. For example, the /JSB qualifier on a STEP
command doesn't make sense on Alpha VMS because there is no "JSB"
instruction like there is on VAX VMS.
User Action: Reissue the command without the qualifier.
3 QUALREQ
A direction qualifier must be specified with the EXPAND and MOVE
commands.
Facility: DEBUG, VMS Debugger
Explanation: Direction ( UP, DOWN, LEFT, RIGHT ) information is
missing from the command.
User Action: Provide a direction with the command and try again.
3 QUOSTRLONG
quoted string too long, please shorten
Facility: DEBUG, VMS Debugger
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.
3 READERR
debugger input read error; session may terminate
Facility: DEBUG, VMS Debugger
Explanation: Excessive read errors have occurred from the
input command stream. The Debugger may exit after printing this
message.
User Action: Check the physical integrity of the device
containing the input stream. Also check that the input buffer
is large enough to handle the input stream or reduce the rate of
command entry.
3 REENTER
reenter the command using a more precise pathname
Facility: DEBUG, VMS Debugger
Explanation: More than one instance of the specified symbol
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.
3 REFUSED
attach request refused
Facility: DEBUG, VMS Debugger
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.
3 REGMASKHIDDEN
register save mask hidden for stack frame frame_number
Facility: DEBUG, VMS Debugger
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.
3 REGMASKMISSING
register save mask missing for stack frame frame_number
Facility: DEBUG, VMS Debugger
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.
3 REGNAMEFAIL
error registering resources with MRM.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when registering
resources with the Motif Resource Manager (MRM). 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).
3 REGREQ
register required in context for operand number operand_number
Facility: DEBUG, VMS Debugger
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.
3 REGWRERR
unable to write/update register set, stack likely corrupted.
Facility: DEBUG, VMS Debugger
Explanation: Debug kernel failed to write/update the current
context register set. Any pending deposits or steps may fail.
Continuation in the presence of a corrupted stack typically
results in unpredictable program and/or debugger behavior.
User Action: Look at what little valid information is left and
then start over. Attempt to find and fix the point where the
stack gets corrupted. It may be possible to examine program
state, but continuing instruction execution typically results
in unpredictable program and/or debugger behavior.
3 RENAMENOT
Unable to look up 'symbol_name', object being renamed not found in
symbol table
Facility: DEBUG, VMS Debugger
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
3 RESUMERR
an error occurred while trying to resume execution of the program
Facility: DEBUG, VMS Debugger
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 (SPR).
3 RETURNED
control returned to process process_name
Facility: DEBUG, VMS Debugger
Explanation: Control has returned to the parent process.
User Action: None.
3 RNDFCTROUT
round factor out of range
Facility: DEBUG, VMS Debugger
Explanation: The DIBOL scale factor is out of the acceptable
range
3 ROPRANDF
reserved operand fault at or near opcode_name
Facility: DEBUG, VMS Debugger
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.
3 ROUTNOTAVAIL
the source to routine !AC is not available
Facility: DEBUG, VMS Debugger
Explanation: There is no source available for this routine.
3 RPCDBBDT
Bad DTYPE for RPC Data Blocking.
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 RPCERR
an internal inter-process communications error has occurred
Facility: DEBUG, VMS Debugger
Explanation: An internal communications error has occurred. The
reason is given in the message following this message.
User Action: If the error is reproducible, and not a result of
continued instruction execution after a severe error (stack
corruption, resource exhaustion, etc.) submit a Software
Performance Report (SPR) and if possible, enclose a copy of
the program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 RPCINVDSC
invalid RPC descriptor
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 RPCOVF
RPC packet overflow
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 RPCUNF
undefined RPC function encountered
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 RPCUNKARG
undefined RPC argument encountered
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 RSTERR
error in symbol table
Facility: DEBUG, VMS Debugger
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.
3 SAVED
File: DECW$USER_DEFAULTS:VMSDEBUG.DAT
Facility: DEBUG, VMS Debugger
Explanation: The Debuggers current customization resources have
been written to the DECW$USER_DEFAULTS directory (typically
sys$login). If the user selected RESTORE DEFAULT OPTIONS,
then a copy of the system-wide resource file, DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT, has been copied to the users resource
directory, DECW$USER_DEFAULTS.
User Action: The resources will be activated the next time the
Debugger is started.
3 SCALEADD
pointer addition: scale factor of scale_factor applied to right/left
argument
Facility: DEBUG, VMS Debugger
Explanation: Indicates the scale factor applied in computing the
address.
User Action: None.
3 SCALESUB
pointer subtraction: a scale factor of scale_factor applied to the
right/left
Facility: DEBUG, VMS Debugger
Explanation: Indicates the scale factor applied in computing the
address.
User Action: None.
3 SCRNOACCESSR
no read access to address address_value for display in display_name
Facility: DEBUG, VMS Debugger
3 SCRNOSRCLIN
No source line for address: address_value
Facility: DEBUG, VMS Debugger
Explanation: No source line corresponds to the address address_
value specified on the debugger command EXAMINE/SOURCE.
User Action: None. This message is informational.
3 SCRNOTORIGSRC
original version of source file not found for display in display_
name file used is file_specification
Facility: DEBUG, VMS Debugger
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.
3 SCRTOBIG
screen too big for Screen Mode width must be less than maximum_
width, height less than maximum_height
Facility: DEBUG, VMS Debugger
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.
3 SCRTOSMALL
screen too small for Screen Mode width must be at least minimum_
width, height must be at least minimum_height
Facility: DEBUG, VMS Debugger
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.
3 SCRUNAOPNSRC
unable to open source file file_specification
Facility: DEBUG, VMS Debugger
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 RMS
status message gives more information about the reasons for the
source file not being opened.
User Action: Examine the RMS status message to determine the
reasons for the source file not being opened, and take the
appropriate action based on that information.
3 SCRUNAREASRC
unable to read source file file_specification
Facility: DEBUG, VMS Debugger
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 RMS
status message gives more information about the reasons for the
source file not being opened.
User Action: Examine the RMS status message to determine
the reasons for the source file not being read, and take the
appropriate action based on that information.
3 SDDKERNOTAVAIL
system dump kernel of the VMS system dump debugger not available
Facility: DEBUG, VMS Debugger
Explanation: The system dump kernel for the VMS system dump
debugger is not available on this system.
User Action: Contact your Digital Representative on the
availability of this feature.
3 SELECTFAIL
error processing the user's selection.
Facility: DEBUG, VMS Debugger
Explanation: The debugger detected an error when processing
the user's selection. The selection did not match any of the
specified selections in the list 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).
3 SENDRETRY
network failure occurred during a send, retrying
Facility: DEBUG, VMS Debugger
Explanation: A network failure occurred during a send. This is
most likely due to excessive network traffic. The debugger will
retry the send until it sees a network time-out. Then it will try
to re-establish the connection.
User Action: Wait for progress or network failure.
3 SETKEY
keypad state has been set to state_name
Facility: DEBUG, VMS Debugger
Explanation: The specified keypad state has been set.
User Action: None.
3 SETKEYERR
error in processing SET KEY command:
Facility: DEBUG, VMS Debugger
Explanation: An error has occurred during a SET KEY command
3 SFCNTNEG
shift count is negative
Facility: DEBUG, VMS Debugger
3 SHOKEYERR
error in processing SHOW KEY command:
Facility: DEBUG, VMS Debugger
Explanation: An error has occurred during the processing of a
SHOW KEY command
3 SHRPRC
debugger sharing users process
Facility: DEBUG, VMS Debugger
Explanation: An error occurred while trying to create a
subprocess to run the main debugger image. This message indicates
that the debugger is attempting to run 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).
3 SIDEFFECT
operators with side effects not supported (++, -)
Facility: DEBUG, VMS Debugger
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
3 SIGVECNOREAD
signal vector for exception frame frame-addr at sigvec-addr is not
readable
Facility: DEBUG, VMS Debugger
Explanation: The debugger is attempting to chain down the call
stack, following frame pointers. The debugger has determined
that part or all of the signal vector for the exception frame
at frame-addr is not accessible for reading. This vector lies
at sigvec-addr. This usually indicates a corrupt frame list, but
could also indicate that the program has protected part of memory
in which the frame lies. In either case, this is an error.
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".
3 SIGVECTRUNC
signal vector was truncated
Facility: DEBUG, VMS Debugger
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.
3 SILENTERROR
silent error
Facility: DEBUG, VMS Debugger
Explanation: This error should never be displayed to the debug
user. It is an internal debuger only condition code.
User Action: None.
3 SIZEATOMIC
only atomic data types are supported with 'SIZE
Facility: DEBUG, VMS Debugger
Explanation: SIZE is not supported on the item requested
User Action: No user action required
3 SIZETRUNC
size field truncated to size_limit bits
Facility: DEBUG, VMS Debugger
Explanation: The size of the entry in a BLISS field specification
was larger then size_limit. The debugger set the entry size to
size_limit and executed the command.
User Action: None. This message is informational.
3 SOURCESCOPE
Source lines not available for .0
Facility: DEBUG, VMS Debugger
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.
3 SPAWNED
subprocess spawned
Facility: DEBUG, VMS Debugger
Explanation: This message is output by the DEBUG command SPAWN
when it spawns a subprocess.
User Action: None. This message is informational.
3 SRCLINNOT
source lines not available for module path_name
Facility: DEBUG, VMS Debugger
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.
3 SRCNOTCURAV
source code for line !UL in module !AC not currently available.
Facility: DEBUG, VMS Debugger
3 SSIEARLYSTOP
checking for static watchpoint hits before the actual system service
return address
Facility: DEBUG, VMS Debugger
Explanation: The debugger was unable to set a breakpoint at or
step to a system sevice return address. It attempts to do this
when intercepting system service calls during static watchpoint
event processing.
User Action: If there was a watchpoint hit, examine the call
stack and find the frame before the DBGSSISHR (or SYS$SSISHR)
frame in order to realize the correct context and instruction for
the watchpoint hit. Otherwise, it is safe to ignore this message.
3 SS_INT
system service intercepted
Facility: DEBUG, VMS Debugger
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.
3 SS_INT_END
system service intercept cycle end
Facility: DEBUG, VMS Debugger
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.
3 SS_INT_START
system service intercept cycle start
Facility: DEBUG, VMS Debugger
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.
3 STEPINTO
cannot step over PC = address_value
Facility: DEBUG, VMS Debugger
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.
3 STGTRUNC
string truncated
Facility: DEBUG, VMS Debugger
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).
3 STRNGPAD
string operand lengths don't match, shorter padded with blanks on
the right
Facility: DEBUG, VMS Debugger
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.
3 STRTOOLONG
strings longer than 255 characters not supported
Facility: DEBUG, VMS Debugger
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
3 STRUCSIZE
structure size declared as num_units allocation units, num_units was
given
Facility: DEBUG, VMS Debugger
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.
3 SUBOUTBND
subscript subscript_number is out of bounds
Facility: DEBUG, VMS Debugger
Explanation: An attempt to subscript out of the bounds of an
array was made.
User Action: Change the value of the subscript.
3 SUBSCRNG
subscript out of range, low/high bound for dimension subscript_
number is subscript_bound
Facility: DEBUG, VMS Debugger
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.
3 SUBSTRING
invalid substring (start: low_bound, end: high_bound), object has
length string_size
Facility: DEBUG, VMS Debugger
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.
3 SUPERDEBUG
SUPERDEBUG not available
Facility: DEBUG, VMS Debugger
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.
3 SYMNOTACT
non-static variable 'symbol_name' is not active
Facility: DEBUG, VMS Debugger
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.
3 SYMNOTFND
no symbols matching defined_symbol are defined
Facility: DEBUG, VMS Debugger
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.
3 SYNCDONE
vector synchronization complete
Facility: DEBUG, VMS Debugger
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.
3 SYNCREPCOM
Synchronize reporting complete
Facility: DEBUG, VMS Debugger
Explanation: All current vector exceptions have been reported.
User Action: None, this message is informational.
3 SYNC_ALREADY_IN_PROGRESS
synchronize already in progress.
Facility: DEBUG, VMS Debugger
Explanation: Only one synchronize command is allowed at a time.
User Action: Do not perform a synchronization command until the
previous command has completed.
3 SYNERREXPR
syntax error in expression at or near 'debugger_command_segment'
Facility: DEBUG, VMS Debugger
Explanation: The debugger encountered text it does not understand
near '<debugger_command_segment, !AC>'.
User Action: Reenter the command, correcting the syntax error.
3 SYNERRLABEL
syntax error in %LABEL construct, see HELP Built_in_Symbols %LABEL
Facility: DEBUG, VMS Debugger
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.
3 SYNERRLINE
syntax error in %LINE construct, see HELP Built_in_Symbols %LINE
Facility: DEBUG, VMS Debugger
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.
3 SYNTAX
command syntax error at or near 'debugger_command_segment'
Facility: DEBUG, VMS Debugger
Explanation: The debugger encountered a command syntax error near
the element debugger_command_segment.
User Action: Re-enter the command.
3 TARGREJ
target system rejected the connection request
Facility: DEBUG, VMS Debugger
Explanation: The target system rejected. This can be because the
target system is not in a debuggable state, you have specified
the password incorrectly, or a system with this name does not
exist on the network.
User Action: Check spelling of the node name or password. Also
verify that the system is in a debuggable state (booted with the
correct flags).
3 TASKERROR
error error_code from ADA multitasking
Facility: DEBUG, VMS Debugger
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.
3 TASKNONULL
Null task cannot be selected or modified
Facility: DEBUG, VMS Debugger
3 TASKNOREGS
Task has no registers (it is the Null task)
Facility: DEBUG, VMS Debugger
3 TASKNOTABORT
task not aborted; ADA multitasking is executing critical section
Facility: DEBUG, VMS Debugger
Explanation: The task specified may not be aborted at this time.
User Action: Retry the abort at a later time.
3 TASKNOTACT
task cannot be made the active task; task is not ready or running
Facility: DEBUG, VMS Debugger
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.
3 TASKNULL
task is null; cannot set attributes of null task
Facility: DEBUG, VMS Debugger
3 TERMINATING
program is terminating
Facility: DEBUG, VMS Debugger
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.
3 THDSTACKOVER
thread thread_number's stack is close to overflowing
Facility: DEBUG, VMS Debugger
Explanation: This thread's stack is close to overflowing, it is
over 66% full. Note that the debug kernel image runs on the user
stacks, i.e. consumes user stack resources. Also the debug main
image will run on the user stacks IF the debugger configuration
is one process (DBG$PROCESS logical set to "NONE"). If a stack
does overflow, memory errors, e.g. access violations, bus errors,
segmentation faults, will likely occur.
User Action: Your code may need to change to create this thread
with a larger stack, see the Guide to POSIX Threads. Also always
run the debugger in its DEFAULT or MULTIPROCESS configuration
when debugging threaded applications.
3 THISMEMBER
primary (at address) has already been built for this->membername
Facility: DEBUG, VMS Debugger
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).
3 TIMESLICE
time slice interval has been slowed to 10.0 seconds
Facility: DEBUG, VMS Debugger
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.
3 TOOFEWSUB
too few subscripts, array has num_dimensions dimensions
Facility: DEBUG, VMS Debugger
Explanation: The user has specified a symbol reference with too
few subscripts
User Action: Correct and reissue the command
3 TOOMANDIM
too many dimensions in array
Facility: DEBUG, VMS Debugger
3 TOOMANERR
too many errors, some errors not reported
Facility: DEBUG, VMS Debugger
Explanation: Too many MISMODBEG or certain other errors occurred.
Other similar errors are not reported.
User Action: None. This message is informational.
3 TOOMANINV
too many invocation numbers in symbol pathname
Facility: DEBUG, VMS Debugger
3 TOOMANPARM
too many parameters on command
Facility: DEBUG, VMS Debugger
3 TOOMANSUB
too many subscripts, array has num_dimensions dimensions
Facility: DEBUG, VMS Debugger
Explanation: The user has specified a symbol reference with too
many subscripts
User Action: Correct and reissue the command
3 TRUNC64
address !@XH being truncated in !AC
Facility: DEBUG, VMS Debugger
Explanation: A 64-bit address is being truncated to 32-bits,
such that information is being lost. This is a debugger internal
error.
User Action: Please submit a Software Performance Report (SPR).
3 UIISHIDDEN
the User Interface is currently hidden.
Facility: DEBUG, VMS Debugger
Explanation: Debug did not hide the UI because it is already
hidden.
User Action: No action necessary.
3 UIISSHOWN
the User Interface is currently displayed.
Facility: DEBUG, VMS Debugger
Explanation: Debug did not show the UI because it is currently
displayed.
User Action: No action necessary.
3 UNAACCREG
unable to access beyond end of register set
Facility: DEBUG, VMS Debugger
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.
3 UNACREDBGO
unable to create DBG$OUTPUT, SYS$OUTPUT used
Facility: DEBUG, VMS Debugger
3 UNACVT
unable to convert radixvalue to datatype_name
Facility: DEBUG, VMS Debugger
Explanation: Debug was unable to perform the requested conversion
User Action: No user action required
3 UNACVTBYTTAU
error converting byte count into target addressable units
Facility: DEBUG, VMS Debugger
Explanation: This is an internal debugger error.
User Action: If the error is reproducible, submit a Software
Performance Report and, if possible, enclose a copy of the
program being debugged, its build procedure, and a logged
debugging session that reproduces the error.
3 UNALIGNED
data is not aligned on a byte boundary
Facility: DEBUG, VMS Debugger
Explanation: The user has requested a type override that can not
be performed
User Action: No user action required
3 UNALLOCATED
'symbol_name' is not allocated in memory (optimized away)
Facility: DEBUG, VMS Debugger
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
3 UNAOPEDBGI
unable to open DBG$INPUT, SYS$INPUT used
Facility: DEBUG, VMS Debugger
3 UNAOPESCR
unable to open DBG$OUTPUT for screen output
Facility: DEBUG, VMS Debugger
3 UNAOPNDSF
unable to open Debugger Symbol File file_specification
Facility: DEBUG, VMS Debugger
Explanation: The Debugger Symbol File (DSF) 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 debugger symbol file not being opened, and take
action based on that information. Also, verify that the logical
name DBG$IMAGE_DSF_PATH is defined to indicate the proper file.
3 UNAOPNHLP
unable to open help library file_specification
Facility: DEBUG, VMS Debugger
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.
3 UNAOPNINI
unable to open initialization file file_specification
Facility: DEBUG, VMS Debugger
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.
3 UNAOPNSRC
unable to open source file file_specification
Facility: DEBUG, VMS Debugger
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 RMS
status message gives more information about the reasons for the
source file not being opened.
User Action: Examine the RMS status message to determine the
reasons for the source file not being opened, and take the
appropriate action based on that information.
3 UNAORIGSRC
unable to open the original source file file specification
Facility: DEBUG, VMS Debugger
Explanation: Source lines from the original (before
preprocessing) source file cannot be displayed because the
debugger could not get the necessary information from the
Correlation Facility.
User Action: Check your Correlation Facility logicals and library
to see that they are referencing the proper files.
3 UNAREASRC
unable to read source file file_specification
Facility: DEBUG, VMS Debugger
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 RMS
status message gives more information about the reasons for the
source file not being opened.
User Action: Examine the RMS status message to determine
the reasons for the source file not being read, and take the
appropriate action based on that information.
3 UNASAVVAL
unable to save value for defined_symbol, definition ignored
Facility: DEBUG, VMS Debugger
3 UNASETEVENT
unable to set thread event
Facility: DEBUG, VMS Debugger
Explanation: This is likely an internal error in either the
debugger or the thread facility. Please submit a Software
Performance Report (SPR).
User Action: Submit a Software Performance Report (SPR).
3 UNASETIMG
unable to set image image_name because it has no symbol table
Facility: DEBUG, VMS Debugger
Explanation: The image is linked with the /NODEBUG qualifier, so
there is no symbol table.
User Action: Relink the image with the /DEBUG qualifier.
3 UNASETTAS
unable to set visible task: registers not available
Facility: DEBUG, VMS Debugger
3 UNASWISTA
Unable to create debugger stack, using program stack
Facility: DEBUG, VMS Debugger
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.
3 UNBPAREN
unbalanced parentheses in expression
Facility: DEBUG, VMS Debugger
3 UNDEXPN
undefined exponentiation at or near opcode_name
Facility: DEBUG, VMS Debugger
3 UNDKEY
state_name key key_name is undefined
Facility: DEBUG, VMS Debugger
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.
3 UNHANDLED
The primary handler should now handle this unhandled exception
Facility: DEBUG, VMS Debugger
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).
3 UNIMPLENT
attempt to evaluate unimplemented type, cannot proceed.
Facility: DEBUG, VMS Debugger
Explanation: The data type of the entity in question has not been
implemented in the debugger. The debugger doesn't have the needed
information on the entity's type to follow through with request.
3 UNKNOWNCODE
unknown debugger function code !UL.
Facility: DEBUG, VMS Debugger
User Action: Make sure that none of the user definable function
codes reference numbers that are not documented.
3 UNMTCHPARN
unmatched left parenthesis found
Facility: DEBUG, VMS Debugger
Explanation: A left parenthesis (() was found, but the matching
right parenthesis ()) is missing.
User Action: Include the right parenthesis ()).
3 UNREQVQUAL
unrecognized vector instruction qualifier specified at 'command_
line'
Facility: DEBUG, VMS Debugger
Explanation: The qualifier indicated in the shown command line
fragment is unreqcognized.
User Action: Specify a legal vector instruction qualifier.
3 UPBNDOPT
upper bound of subrange was optimized away
Facility: DEBUG, VMS Debugger
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.
3 USEPTHREADCMD
this command qualifier is obsolete, use PTHREAD command equivalent
Facility: DEBUG, VMS Debugger
Explanation: This is a POSIX Threads application in which the
debugger has interfaced with a POSIX Threads debugger image.
Thread, mutex, condition value, and more state can be accessed
via the "PTHREAD debugger-command-string" command, e.g. "PTHREAD
THREAD 2 -F". See Debugger Manual and Guide To POSIX Threads
or the "PTHREAD HELP" command for legal POSIX Threads debugger
command strings.
User Action: Use PTHREAD "debugger command string" command
instead.
3 USERINPUTBUSY
user input thread is busy
Facility: DEBUG, VMS Debugger
Explanation: The debugger's user input thread is busy trying
to collect a new input line. User's should never see this
informational.
User Action: Please submit a Software Performance Report.
3 USREVNIGN
DEBUG detected a bad RTL EVCB sentinel-Event ignored.
Facility: DEBUG, VMS Debugger
Explanation: While process a pseudo-go operation, the EVCB sent
to the debugger by the RTL had a bogus sentinel field. Therefore,
the debugger ignored the event.
User Action: None.
3 USREVNTERR
user-specified event error code error_code returned by user RTL
Facility: DEBUG, VMS Debugger
3 VALNOTADDR
value of variable 'symbol_name' not usable as address
Facility: DEBUG, VMS Debugger
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.
3 VALRNG
value is subscript_value, bounds are low_bound..high_bound
Facility: DEBUG, VMS Debugger
Explanation: An attempt to subscript out of the bounds of an
array was made.
User Action: Change the value of the subscript.
3 VARNESDEP
variant nesting depth exceeds 20, cannot access record component
Facility: DEBUG, VMS Debugger
3 VECDIS
debugger-generated vector disabled fault
Facility: DEBUG, VMS Debugger
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.
3 VECREASON
the reason values for this vector error are reason_values
Facility: DEBUG, VMS Debugger
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.
3 VECSCP0
vector registers can be accessed only in scope 0
Facility: DEBUG, VMS Debugger
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.
3 VECTSUBRNG
vector register subscript out of bounds, bounds are low_bound..high_
bound
Facility: DEBUG, VMS Debugger
Explanation: An attempt to subscript out of the bounds of an
array was made.
User Action: Change the value of the subscript.
3 VERIFYICF
opening/closing command procedure file_specification
Facility: DEBUG, VMS Debugger
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.
3 VERSIONNUM
the debugger_type debugger has the following RPC version: major_
version/minor_version
Facility: DEBUG, VMS Debugger
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.
3 VERSMISMATCH
the host (!AC) and target (!AC) versions are incompatible
Facility: DEBUG, VMS Debugger
Explanation: The host kernel and target kernel versions are
incompatible. This is usually due to different versions of the
operating system on the host and target systems.
User Action: Check the versions of the operating systems. Review
the System-Code Debugger documentation to find out which versions
are compatible.
3 VFLTDIV
Reserved operand, encoded as floating divide by zero
Facility: DEBUG, VMS Debugger
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.
3 VFLTOVF
Reserved operand, encoded as floating overflow
Facility: DEBUG, VMS Debugger
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.
3 VFLTROP
Reserved operand, encoded as floating reserved operand
Facility: DEBUG, VMS Debugger
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.
3 VFLTUND
Reserved operand, encoded as floating underflow
Facility: DEBUG, VMS Debugger
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.
3 WATCHSETUP
instruction at current PC may trigger a watchpoint
Facility: DEBUG, VMS Debugger
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.
3 WATCHSIZE
cannot WATCH variables longer than 512 bytes
Facility: DEBUG, VMS Debugger
3 WATCHSIZESMALL
cannot WATCH variable of 0 or negative size
Facility: DEBUG, VMS Debugger
3 WATNOWCAN
watchpoint now cancelled
Facility: DEBUG, VMS Debugger
Explanation: This message is a sub-message to WATVARSCP,
WATVARPTR, WATVARPROT, etc. This message indicates that the
original watchpoint has been cancelled (is no longer active).
User Action: None. This message is informational.
3 WATNOWWAT
now watching variable name
Facility: DEBUG, VMS Debugger
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.
3 WATVARGSGONE
global section associated with watched variable variable name has
been unmapped
Facility: DEBUG, VMS Debugger
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.
3 WATVARGSOVR
watched variable overlaps into a global section
Facility: DEBUG, VMS Debugger
Explanation: The specified variable spans a range of virtual
memory which includes a global-section and a private-section or
two different global-sections. A watched variable must either be
entirely in one global-section or entirely in a private-section.
User Action: Do not use watchpoint on this address range.
3 WATVARINAC
watched variable variable name is no longer accessible
Facility: DEBUG, VMS Debugger
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.
3 WATVARNOWGBL
watched variable variable name has been re-mapped to a global
section
Facility: DEBUG, VMS Debugger
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.
3 WATVARNOWOVR
watched variable variable name now overlaps different sections
Facility: DEBUG, VMS Debugger
Explanation: The specified variable spans a range of virtual
memory which has been re-mapped to include a global-section and
a private-section or two different global-sections. A watched
variable must either be entirely in one global-section or
entirely in a private-section.
User Action: Do not use watchpoint on this address range.
3 WATVARNOWPVT
watched variable variable name has been re-mapped to a private
section
Facility: DEBUG, VMS Debugger
Explanation: The program mapped a private-section over a watched
global section variable. This message indicates that the debugger
made the watchpoint a private-section watchpoint.
User Action: No action necessary.
3 WATVARPROT
watched variable variable name has been protected by the program
Facility: DEBUG, VMS Debugger
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.
3 WATVARPTR
watched variable variable name now points to a different address
Facility: DEBUG, VMS Debugger
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.
3 WATVARSCP
watched variable variable name has gone out of scope
Facility: DEBUG, VMS Debugger
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.
3 WIDTHDIFF
desired width of display_width is not allowed, width is set to
display_width
Facility: DEBUG, VMS Debugger
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.
3 WORKSTACMD
the command debugger-command is only supported on VWS workstations
Facility: DEBUG, VMS Debugger
Explanation: The debugger only supports the command debugger-
command on workstations running VWS.
User Action: None. This capability of the debugger does not exist
for your terminal or machine.
3 WPTTRACE
non-static watchpoint, tracing every instruction
Facility: DEBUG, VMS Debugger
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.
3 WRITE_FAILED
an attempt to write into a memory location failed
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 WRITE_INTO_KERNEL
cannot write into the debugger kernel's address space
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 WRITE_INTO_KERNEL_STACK
cannot write into the debugger kernel's stack
Facility: DEBUG, VMS Debugger
Explanation: This message indicates an internal debugger error.
User Action: Submit a Software Performance Report (SPR).
3 ZERLENDST
zero length DST record has been ignored (compiler error)
Facility: DEBUG, VMS Debugger
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.
3 ZEROINCR
increment for ranged examine is zero; exiting loop
Facility: DEBUG, VMS Debugger
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.
2 Path_Names
If your program has multiple symbols with the same name, you
may need to use path names to resolve symbol ambiguities. For
example, your program 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 specify X,
as in this example, the debugger uses symbol search conventions
(based on the PC scope) to resolve the ambiguity:
DBG> EXAMINE X
If the debugger cannot do so, it issues the following message:
%DEBUG-W-NOUNIQUE, X is not unique.
To resolve the ambiguity, you can specify which X you want by
using a path name. For example:
DBG> EXAMINE A\X
DBG> EXAMINE A\B\X
DBG> EXAMINE C\X
For more information, see the SET SCOPE command.
2 SS$_DEBUG
SS$_DEBUG (defined in STARLET) is a condition you can signal from
your program to start the debugger. Signalling SS$_DEBUG from
your program is equivalent to entering Ctrl/Y followed by DEBUG
at that point.
You can pass commands to the debugger at the time you signal it
with SS$_DEBUG. For example, to start the debugger and issue 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'));
2 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, several 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.
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.
3 User_Quotas
Each user needs a PRCLM quota sufficient to create an additional
process 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 process 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 might 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.
4 Behavior_After_Stack_Corruption
The debugger allocates a certain amount of memory at startup
and shares the stack with the user's program. If a user process
exception results in exhaustion of resources or corruption of the
stack, the debugger may be incapable of regaining control, and
the debug session may terminate.
Be aware of this potential behavior after the occurrence of stack
corruption messages or warnings about continuing from a severe
error. In either case, the integrity of the debug session cannot
be guaranteed.
It is recommended that you try one of the following measures:
o Change your source code, temporarily or permanently, to reduce
resource consumption or lessen the use of stack space
o Increase quotas
o Specify a larger stack size when linking your program
3 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 system 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.
2 VWS_Workstations
The following commands are recognized only when you are using
the debugger at a workstation running VWS (not Compaq DECwindows
Motif for OpenVMS):
o SET MODE [NO]SEPARATE
o SET PROMPT/[NO]POP
2 @_(Execute_Procedure)
Executes a debugger command procedure.
Format
@file-spec [parameter[, . . . ]]
3 Parameters
file-spec
Specifies the command procedure to be executed. For any part
of the full file specification not provided, the debugger uses
the file specification established with the last SET ATSIGN
command, if any. If the missing part of the file specification
was not established by a SET ATSIGN command, the debugger assumes
SYS$DISK:[]DEBUG.COM as the default file specification. You can
specify a logical name.
parameter
Specifies a parameter that is passed to the command procedure.
The parameter can be an address expression, a value expression
in the current language, or a debugger command; the command must
be enclosed within quotation marks ("). Unlike with DCL, you
must separate parameters by commas. Also, you can pass as many
parameters as there are formal parameter declarations within the
command procedure. For more information about passing parameters
to command procedures, see the DECLARE command.
3 Description
A debugger command procedure can contain any debugger commands,
including another execute procedure (@) command. The debugger
executes commands from the command procedure until it reaches an
EXIT or QUIT command or reaches the end of the command procedure.
At that point, the debugger returns control to the command stream
that invoked the command procedure. A command stream can be the
terminal, an outer (containing) command procedure, a DO clause in
a command such as SET BREAK, or a DO clause in a screen display
definition.
By default, commands read from a command procedure are not
echoed. If you enter the SET OUTPUT VERIFY command, all commands
read from a command procedure are echoed on the current output
device, as specified by DBG$OUTPUT (the default output device is
SYS$OUTPUT).
For information about passing parameters to command procedures,
see the DECLARE command.
Related commands:
DECLARE
(SET,SHOW) ATSIGN
SET OUTPUT [NO]VERIFY
SHOW OUTPUT
3 Example
DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> SET OUTPUT VERIFY
DBG> @CHECKOUT
%DEBUG-I-VERIFYICF, entering command procedure CHECKOUT
SET MODULE/ALL
SET BREAK SUB1
GO
break at routine PROG5\SUB2
EXAMINE X
PROG5\SUB2\X: 376
. . .
%DEBUG-I-VERIFYICF, exiting command procedure MAIN
DBG>
In this example, the SET ATSIGN command establishes
that debugger command procedures are, by default,
in USER:[JONES.DEBUG] and have a file type of .DBG.
The @CHECKOUT command executes the command procedure
USER:[JONES.DEBUG]CHECKOUT.DBG. The debugger echoes commands
in the command because of the SET OUTPUT VERIFY command.
2 ACTIVATE
3 BREAK
Activates a breakpoint that you have previously set and then
deactivated.
Format
ACTIVATE BREAK [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a breakpoint to be activated. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression when using any qualifiers except
/EVENT, /PREDEFINED, or /USER.
4 Qualifiers
/ACTIVATING
Activates a breakpoint established by a previous SET
BREAK/ACTIVATING command.
/ALL
By default, activates all user-defined breakpoints. When used
with /PREDEFINED, activates all predefined breakpoints but
no user-defined breakpoints. To activate all breakpoints, use
/ALL/USER/PREDEFINED.
/BRANCH
Activates a breakpoint established by a previous SET BREAK/BRANCH
command.
/CALL
Activates a breakpoint established by a previous SET BREAK/CALL
command.
/EVENT
/EVENT=event-name
Activates a breakpoint established by a previous SET
BREAK/EVENT=event-name command. Specify the event name (and
address expression, if any) exactly as specified with the SET
BREAK/EVENT command.
To identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Activates a breakpoint established by a previous SET
BREAK/EXCEPTION command.
/HANDLER
Activates a breakpoint established by a previous SET
BREAK/HANDLER command.
/INSTRUCTION
Activates a breakpoint established by a previous SET
BREAK/INSTRUCTION command.
/LINE
Activates a breakpoint established by a previous SET BREAK/LINE
command. Do not specify an address expression with this
qualifier.
/PREDEFINED
Activates a specified predefined breakpoint without affecting
any user-defined breakpoints. When used with /ALL, activates all
predefined breakpoints.
/SYSEMULATE
(Alpha only) Activates a breakpoint established by a previous SET
BREAK/SYSEMULATE command.
/TERMINATING
Activates a breakpoint established by a previous SET
BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Activates a breakpoint established by a previous
SET BREAK/UNALIGNED_DATA command, or reactivates a breakpoint
previously disabled by a DEACTIVATE BREAK/UNALIGNED_DATA command.
/USER
Activates a specified user-defined breakpoint without affecting
any predefined breakpoints. To activate all user-defined
breakpoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Activates a breakpoint established by a previous SET
BREAK/VECTOR_INSTRUCTION command.
4 Description
User-defined breakpoints are activated when you set them with
the SET BREAK command. Predefined breakpoints are activated by
default. Use the ACTIVATE BREAK command to activate one or more
breakpoints that you deactivated with DEACTIVATE BREAK.
Activating and deactivating breakpoints enables you to run and
rerun your program with or without breakpoints without having to
cancel and then reset them. By default, the RERUN command saves
the current state of all breakpoints (activated or deactivated).
You can activate and deactivate user-defined breakpoints or
predefined breakpoints or both. To check if a breakpoint is
activated, use the SHOW BREAK command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY
4 Examples
1.DBG> ACTIVATE BREAK MAIN\LOOP+10
This command activates the user-defined breakpoint set at the
address expression MAIN\LOOP+10.
2.DBG> ACTIVATE BREAK/ALL
This command activates all user-defined breakpoints.
3.DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED
This command activates all breakpoints, both user-defined and
predefined.
3 TRACE
Activates a tracepoint that you have previously set and then
deactivated.
Format
ACTIVATE TRACE [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a tracepoint to be activated. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression when using any qualifiers except
/EVENT, /PREDEFINED, or /USER.
4 Qualifiers
/ACTIVATING
Activates a tracepoint established with a previous SET
TRACE/ACTIVATING command.
/ALL
By default, activates all user-defined tracepoints. When used
with /PREDEFINED, activates all predefined tracepoints but
no user-defined tracepoints. To activate all tracepoints, use
/ALL/USER/PREDEFINED.
/BRANCH
Activates a tracepoint established with a previous SET
TRACE/BRANCH command.
/CALL
Activates a tracepoint established with a previous SET TRACE/CALL
command.
/EVENT
/EVENT=event-name
Activates a tracepoint established with a previous SET
TRACE/EVENT=event-name command. Specify the event name (and
address expression, if any) exactly as specified with the SET
TRACE/EVENT command.
To identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Activates a tracepoint established with a previous SET
TRACE/EXCEPTION command.
/INSTRUCTION
Activates a tracepoint established with a previous SET
TRACE/INSTRUCTION command.
/LINE
Activates a tracepoint established with a previous SET TRACE/LINE
command.
/PREDEFINED
Activates a specified predefined tracepoint without affecting
any user-defined tracepoints. When used with /ALL, activates all
predefined tracepoints.
/TERMINATING
Activates a tracepoint established with a previous SET
TRACE/TERMINATING command.
/USER
Activates a specified user-defined tracepoint without affecting
any predefined tracepoints. To activate all user-defined
tracepoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Activates a tracepoint established with a previous SET
TRACE/VECTOR_INSTRUCTION command.
4 Description
User-defined tracepoints are activated when you set them with
the SET TRACE command. Predefined tracepoints are activated by
default. Use the ACTIVATE TRACE command to activate one or more
tracepoints that you deactivated with DEACTIVATE TRACE.
Activating and deactivating tracepoints enables you to run and
rerun your program with or without tracepoints without having to
cancel and then reset them. By default, the RERUN command saves
the current state of all tracepoints (activated or deactivated).
You can activate and deactivate user-defined tracepoints or
predefined tracepoints or both. To check if a tracepoint is
activated, use the SHOW TRACE command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,DEACTIVATE) TRACE
4 Examples
1.DBG> ACTIVATE TRACE MAIN\LOOP+10
This command activates the user-defined tracepoint at the
location MAIN\LOOP+10.
2.DBG> ACTIVATE TRACE/ALL
This command activates all user-defined tracepoints.
3 WATCH
Activates a watchpoint that you have previously set and then
deactivated.
Format
ACTIVATE WATCH [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a watchpoint to be activated. With high-level
languages, this is typically the name of a variable. Do not
use the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify an address expression with /ALL.
4 Qualifiers
/ALL
Activates all watchpoints.
4 Description
Watchpoints are activated when you set them with the SET WATCH
command. Use the ACTIVATE WATCH command to activate one or more
watchpoints that you deactivated with DEACTIVATE WATCH.
Activating and deactivating watchpoints enables you to run and
rerun your program with or without watchpoints without having to
cancel and then reset them.
By default, the RERUN command saves the current state of all
static watchpoints (activated or deactivated). The state of
a particular nonstatic watchpoint might or might not be saved
depending on the scope of the variable being watched relative to
the main program unit (where execution restarts).
To check if a watchpoint is activated, use the SHOW WATCH
command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) WATCH
4 Examples
1.DBG> ACTIVATE WATCH SUB2\TOTAL
This command activates the watchpoint at variable TOTAL in
module SUB2.
2.DBG> ACTIVATE WATCH/ALL
This command activates all watchpoints you have set and
deactivated.
2 ANALYZE
3 /CRASH_DUMP
Opens a system dump for analysis by the System Dump Debugger
(kept debugger only).
Format
ANALYZE/CRASH_DUMP
4 Description
Invokes the OpenVMS Alpha System Dump Debugger (SDD) to analyze a
system dump.
SDD is similar in concept to the System Code Debugger (SCD).
While SCD allows connection to a running system, with control of
the system's execution and the examination and modification of
variables, SDD allows analysis of memory as recorded in a system
dump.
Use of SDD usually involves two systems, although all of the
required environment can be set up on a single system. The
description that follows assumes that two systems are being used:
o The build system, where the image that causes the system crash
has been built
o The test system, where the image is executed and the system
crash occurs
In common with SCD, the OpenVMS debugger user interface allows
you to specify variable names, routine names, and so on,
precisely as they appear in your source code. Also, SDD can
display the source code where the software was executing at the
time of the system crash.
SDD recognizes the syntax, data typing, operators, expressions,
scoping rules, and other constructs of a given language. If your
code or driver is written in more than one language, you can
change the debugging context from one language to another during
a debugging session.
To use SDD you must do the following:
o Build the system image or device driver that is causing the
system crash.
o Boot a system, including the system image or device driver,
and perform the necessary steps to cause the system crash.
o Reboot the system and save the dump file.
o Invoke SDD, which is integrated with the OpenVMS debugger.
For more information about using the SDD, including a sample SDD
session, see the OpenVMS Alpha System Analysis Tools Manual.
Related commands:
ANALYZE/PROCESS_DUMP
CONNECT %NODE
SDA
4 Example
DBG> ANALYZE/CRASH_DUMP
DBG>
Invokes SDD from within the kept debugger.
3 /PROCESS_DUMP
Opens a process dump for analysis with the System Code Debugger
(kept debugger only)
Format
ANALYZE/PROCESS_DUMP dumpfile
4 Parameters
dumpfile
The name of the process dump file to be analyzed. The file type
must be .DMP.
4 Qualifiers
/IMAGE_PATH
/IMAGE_PATH=directory-spec
Specifies the search path for the debugger to find the files that
contains the debugger symbol tables (DSTs). The files must be of
type .DSF or .EXE, with the same name as the image names in the
dumpfile. For example, if image name foo.exe is in the dump file,
then the debugger searches for foo.dsf or foo.exe.
4 Description
(Kept debugger only.) Opens a process dump for analysis with
the System Code Debugger (SCD). The qualifier /PROCESS_DUMP is
required and distinguishes this command from the one that invokes
the System Dump Debugger (SDD), ANALYZE/CRASH_DUMP.
The qualifier /IMAGE_PATH=directory-spec is optional, and
specifies the search path the debugger is to use to find the
debugger symbol table (DST) files. The debugger builds an image
list from the saved process image list. When you set an image
(the main image is automatically set), the debugger attempts to
open that image in order to find the DSTs.
If you include the /IMAGE_PATH=directory-spec qualifier, the
debugger searches for the .DST file in the specified directory.
The debugger first tries to translate directory-spec as the
logical name of a directory search list. If that fails, the
debugger interprets directory-spec as a directory specification,
and searches that directory for matching .DSF or .EXE files. A
.DSF file takes precedence over an .EXE file. The name of the
.DSF or .EXE file must match the image name.
If you do not include the /IMAGE_PATH=directory-spec qualifier,
the debugger looks for the DST file first in the directory
that contains the dump file. If that fails, the debugger next
searches directory SYS$SHARE and then directory SYS$MESSAGE. If
the debugger fails to find a DST file for the image, symbolic
information available to the debugger is limited to global and
universal symbol names.
The debugger checks for link date-time mismatches between the
dump file image and the DST file and issues a warning if one is
discovered.
The parameter dumpfile is the name of the process dump file to be
analyzed. Note that the process dump file type must be .DMP and
the DST file type must be either .DSF or .EXE.
For more information about using SCD, see the OpenVMS Alpha
System Analysis Tools Manual.
Related commands:
ANALYZE/CRASH_DUMP
CONNECT %NODE
SDA
4 Example
DBG> ANALYZE/PROCESS/IMAGE_DUMP=my_disk$:[my_dir] my_disk$:[my_
dir]wecrash.dmp
%SYSTEM-F-IMGDMP, dynamic image dump signal at PC=001C0FA0B280099C, PS=001C003C
break on unhandled exception preceding WECRASH\th_
run\%LINE 26412 in THREAD 8
26412: if (verify) {
DBG> SET RADIX HEXEXADECIMAL; EXAMINE PC
WECRASH\th_run\%PC: 0000000000030244
DBG>
2 ATTACH
Passes control of your terminal from the current process to
another process.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
ATTACH process-name
3 Parameters
process-name
Specifies the process to which your terminal is to be attached.
The process must already exist before you try to attach to it.
If the process name contains nonalphanumeric or space characters,
you must enclose it in quotation marks (").
3 Description
The ATTACH command enables you to go back and forth between
a debugging session and your command interpreter, or between
two debugging sessions. To do so, you must first use the SPAWN
command to create a subprocess. You can then attach to it
whenever you want. To return to your original process with
minimal system overhead, use another ATTACH command.
Related command:
SPAWN
3 Examples
1.DBG> SPAWN
$ ATTACH JONES
%DEBUG-I-RETURNED, control returned to process JONES
DBG> ATTACH JONES_1
$
In this example, the series of commands creates a subprocess
named
JONES_1 from the debugger (currently running in the process
JONES) and then attaches to that subprocess.
2.DBG> ATTACH "Alpha One"
$
This example illustrates using quotation marks to enclose a
process name that contains a space character.
2 CALL
Calls a routine that was linked with your program.
Format
CALL routine-name [(argument[, . . . ])]
3 Parameters
routine-name
Specifies the name or the memory address of the routine to be
called.
argument
Specifies an argument required by the routine. Arguments can be
passed by address, by descriptor, by reference, and by value, as
follows:
%ADDR (Default, except for C and C++.) Passes the argument by
address. The format is as follows:
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
composite variables (such as arrays, records, and access
types), the address is passed when you specify %ADDR,
but the called routine might 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. The format is as
follows:
CALL routine-name (%DESCR language-expression)
The debugger evaluates the language expression and
builds a 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. The format is as
follows:
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 (Default for C and C++.) Passes the argument by value.
The format is as follows:
CALL routine-name (%VAL language-expression)
The debugger evaluates the language expression and passes
the value directly to the called routine.
3 Qualifiers
/AST
/AST (default)
/NOAST
Controls whether the delivery of asynchronous system traps
(ASTs) is enabled or disabled during the execution of the called
routine. The /AST qualifier enables the delivery of ASTs in the
called routine. The /NOAST qualifier disables the delivery of
ASTs in the called routine. If you do not specify /AST or /NOAST
with the CALL command, the delivery of ASTs is enabled unless you
have previously entered the DISABLE AST command.
/SAVE_VECTOR_STATE
/SAVE_VECTOR_STATE
/NOSAVE_VECTOR_STATE (default)
Applies to VAX 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 was issued
The /SAVE_VECTOR_STATE qualifier specifies that after the called
routine has completed execution, the debugger restores the state
of the vector processor that exists before the CALL command is
issued. This ensures that, after the called routine has completed
execution:
o Any vector exception that was pending delivery before the CALL
command was issued 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 was issued
The /NOSAVE_VECTOR_STATE qualifier (which is the default)
specifies that the state of the vector processor that exists
before the CALL command is issued 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
general registers. The values of these registers are always saved
and restored when you execute a routine with the CALL command.
3 Description
The CALL command is one of the four debugger commands that
can be used to execute your program (the others are GO, STEP,
and EXIT). The CALL command enables you to execute a routine
independently of the normal execution of your program. The CALL
command executes a routine whether or not your program actually
includes a call to that routine, as long as the routine was
linked with your program.
When you enter a CALL command, the debugger takes the following
actions. For more information, see the qualifier descriptions.
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 register R0.
By 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 might 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 was executed.
7. Issues the prompt.
The debugger assumes that the called routine conforms to the
procedure calling standard (see the OpenVMS Calling Standard).
However, the debugger does not know about all the argument-
passing mechanisms for all supported languages. Therefore,
you might need to specify how to pass parameters, for example,
use CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete
information about how arguments are passed to routines, see your
language documentation.
When the current language is C or C++, the CALL command by
default now passes arguments by value rather than by reference.
In addition, you can now pass the following arguments without
using a passing mechanism lexical (such as %REF or %VAL):
o Routine references
o Quoted strings (treated as %REF strings)
o Structures, records, and objects
o Floating-point parameters by value in F_, D_, G_, S_, and T_
floating format by dereferencing a variable of that type.
If the routine contains parameters that are not read-only, the
values assigned to parameters may not be visible, and access
to values is unreliable. This is because the debugger adjusts
parameter values in an internal argument list, not the program
argument list. To examine changing values, consider using static
variables instead of parameters.
The CALL command converts all floating-point literals to F_
floating format. Passing a floating-point literal in a format
other than F_floating is not supported. (See the example below.)
A common debugging technique at an exception breakpoint
(resulting from a SET BREAK/EXCEPTION or STEP/EXCEPTION command)
is to call a dump routine with the CALL command. When you enter
the CALL command at an exception breakpoint, 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 enter the CALL command at a location other than an
exception breakpoint.
3 Description,_Continued...
When an exception breakpoint is triggered, execution is suspended
before any application-declared condition handler is invoked.
At an exception breakpoint, entering a GO or STEP command after
executing a routine with the CALL command causes the debugger to
resignal the exception (see the GO and STEP commands).
On Alpha processors, you cannot debug routines that are activated
before the routine activated by a CALL command. For example, your
program is stopped in routine MAIN, and you set a breakpoint in
routine SORT. You issue the debugger command CALL SORT. While
debugging routine SORT, you cannot debug routine MAIN. You must
first return from the call to routine SORT.
If you are debugging a multiprocess program, the CALL command is
executed in the context of the current process set. In addition,
when debugging a multiprocess program, the way in which execution
continues in your process depends on whether you entered a SET
MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By
default (SET MODE NOINTERRUPT), when one process stops, the
debugger takes no action with regard to the other processes.
Also by default (SET MODE WAIT), the debugger waits until
all processes in the current process set have stopped before
prompting for a new command.
Related commands:
GO
EXIT
SET PROCESS
SET MODE [NO]INTERRUPT
SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
STEP
SYNCHRONIZE VECTOR_MODE (VAX only)
3 Examples
1.DBG> CALL SUB1(X)
value returned is 19
DBG>
This command calls routine SUB1, with parameter X (by default,
the address of X is passed). In this case, the routine returns
the value 19.
2.DBG> CALL SUB(%REF 1)
value returned is 1
DBG>
This command 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
DBG>
This example calls Run-Time Library routine LIB$SHOW_VM
(in shareable image LIBRTL) to display memory statistics.
The SET MODULE command makes the universal symbols (routine
names) in LIBRTL visible in the main image. See also the SHOW
MODULE/SHARE command.
4.DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33)
This example passes floating-point parameters by value, to a
C subroutine with the function prototype void testsub (float,
float, float). The floating-point parameters are passed in F_
floating format.
2 CANCEL
3 ALL
Cancels all breakpoints, tracepoints, and watchpoints. Restores
the scope and type to their default values. Restores the line,
symbolic, and G_floating modes established with the SET MODE
command to their default values.
Format
CANCEL ALL
4 Qualifiers
/PREDEFINED
Cancels all predefined (but no user-defined) breakpoints and
tracepoints.
/USER
Cancels all user-defined (but no predefined) breakpoints,
tracepoints, and watchpoints. This is the default unless you
specify /PREDEFINED.
4 Description
The CANCEL ALL command does the following:
1. Cancels all user-defined eventpoints (those created with
the commands SET BREAK, SET TRACE, and SET WATCH). This is
equivalent to entering the commands CANCEL BREAK/ALL, CANCEL
TRACE/ALL, and CANCEL WATCH/ALL. Depending on the type of
program (for example Ada, multiprocess), certain predefined
breakpoints or tracepoints might be set automatically when
you start the debugger. To cancel all predefined but no user-
defined eventpoints, use CANCEL ALL/PREDEFINED. To cancel
all predefined and user-defined eventpoints, use CANCEL
ALL/PREDEFINED/USER.
2. Restores the scope search list to its default value
(0,1,2, . . . ,n). This is equivalent to entering the CANCEL
SCOPE command.
3. Restores the data type for memory locations that are
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
equivalent to entering the CANCEL TYPE/OVERRIDE and SET TYPE
LONGWORD commands.
4. Restores the line, symbolic, and G_floating modes established
with the SET MODE command to their default values. This is
equivalent to entering the following command:
DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT
The CANCEL ALL command does not affect the current language
setting or modules included in the run-time symbol table.
Related commands:
(CANCEL,DEACTIVATE) BREAK
CANCEL SCOPE
(CANCEL,DEACTIVATE) TRACE
CANCEL TYPE/OVERRIDE
(CANCEL,DEACTIVATE) WATCH
(SET,CANCEL) MODE
SET TYPE
4 Examples
1.DBG> CANCEL ALL
This command cancels all user-defined breakpoints and
tracepoints and all watchpoints, and restores scopes, types,
and some modes to their default values. In this example, there
are no predefined breakpoints or tracepoints.
2.DBG> CANCEL ALL
%DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled
This command cancels all user-defined breakpoints and
tracepoints and all watchpoints, and restores scopes, types,
and some modes to their default values. In this example, there
is a predefined breakpoint or tracepoint; this is not canceled
by default.
3.DBG> CANCEL ALL/PREDEFINED
This command cancels all predefined breakpoints and
tracepoints, and restores scopes, types, and some modes
to their default values. No user-defined breakpoints or
tracepoints are affected.
3 BREAK
Cancels a breakpoint.
Format
CANCEL BREAK [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a breakpoint to be canceled. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression when using any qualifiers except
/EVENT, /PREDEFINED, or /USER.
4 Qualifiers
/ACTIVATING
Cancels the effect of a previous SET BREAK/ACTIVATING command.
/ALL
By default, cancels all user-defined breakpoints. When used
with /PREDEFINED, cancels all predefined breakpoints but no
user-defined breakpoints. To cancel all breakpoints, use CANCEL
BREAK/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=event-name
Cancels the effect of a previous SET BREAK/EVENT=event-name
command. Specify the event name (and address expression, if
any) exactly as specified with the SET BREAK/EVENT command. To
identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Cancels the effect of a previous SET BREAK/EXCEPTION command.
/HANDLER
Cancels the effect of a previous SET BREAK/HANDLER 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. When used with /ALL, cancels all
predefined breakpoints.
/SYSEMULATE
(Alpha only) Cancels the effect of a previous SET
BREAK/SYSEMULATE command.
/TERMINATING
Cancels the effect of a previous SET BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Cancels the effect of a previous SET
BREAK/UNALIGNED_DATA command.
/USER
Cancels a specified user-defined breakpoint without affecting any
predefined breakpoints. This is the default unless you specify
/PREDEFINED. To cancel all user-defined breakpoints, use the /ALL
qualifier.
/VECTOR_INSTRUCTION
(VAX only) Cancels the effect of a previous SET BREAK/VECTOR_
INSTRUCTION command.
4 Description
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 ZQUIT multiprocess), are
established automatically when you start the debugger. Use the
SHOW BREAK command to identify all breakpoints that are currently
set. Any predefined breakpoints are identified as such.
User-defined and predefined breakpoints are set and canceled
independently. For example, a location or event can have both
a user-defined and a predefined breakpoint. Canceling the user-
defined breakpoint does not affect the predefined breakpoint, and
conversely.
To cancel only user-defined breakpoints, do not specify
/PREDEFINED with the CANCEL BREAK command (the default is /USER).
To cancel only predefined breakpoints, specify /PREDEFINED
but not /USER. To cancel both predefined and user-defined
breakpoints, specify both /PREDEFINED and /USER.
In general, the effect of the CANCEL BREAK command is symmetrical
with that of the SET BREAK command (even though the SET BREAK
command is used only with user-defined breakpoints). Thus, to
cancel a breakpoint that was established at a specific location,
specify that same location (address expression) with the CANCEL
BREAK command. To cancel breakpoints that were established
on a class of instructions or events, specify the class of
instructions or events with the corresponding qualifier (/LINE,
/BRANCH, /ACTIVATING, /EVENT=, and so on). For more information,
see the qualifier descriptions.
If you want the debugger to ignore a breakpoint without your
having to cancel it (for example, if you want to rerun the
program with and without breakpoints), use the DEACTIVATE BREAK
instead of the CANCEL BREAK command. Later, you can activate the
breakpoint (with ACTIVATE BREAK).
Related commands:
(ACTIVATE,DEACTIVATE) BREAK
CANCEL ALL
(SET,SHOW) BREAK
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL) TRACE
4 Examples
1.DBG> CANCEL BREAK MAIN\LOOP+10
This command cancels the user-defined breakpoint set at the
address expression MAIN\LOOP+10.
2.DBG> CANCEL BREAK/ALL
This command cancels all user-defined breakpoints.
3.DBG> CANCEL BREAK/ALL/USER/PREDEFINED
This command cancels all user-defined and predefined
breakpoints.
4.all> CANCEL BREAK/ACTIVATING
This command cancels a previous user-defined SET
BREAK/ACTIVATING command. As a result, the debugger does not
suspend execution when a new process is brought under debugger
control.
5.DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED
This command cancels the predefined breakpoint set on task
terminations due to unhandled exceptions. This breakpoint
is predefined for Ada programs and programs that call POSIX
Threads or Ada routines.
3 DISPLAY
Permanently deletes a screen display.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
CANCEL DISPLAY [display-name[, . . . ]]
4 Parameters
display-name
Specifies the name of a display to be canceled. Do not specify
the PROMPT display, which cannot be canceled. Do not use
the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify a display name with /ALL.
4 Qualifiers
/ALL
Cancels all displays, except the PROMPT display.
4 Description
When a display is canceled, its contents are permanently lost,
it is deleted from the display list, and all the memory that was
allocated to it is released.
You cannot cancel the PROMPT display.
Related commands:
(SHOW) DISPLAY
(SET,SHOW,CANCEL) WINDOW
4 Examples
1.DBG> CANCEL DISPLAY SRC2
This command deletes display SRC2.
2.DBG> CANCEL DISPLAY/ALL
This command deletes all displays, except the PROMPT display.
3 MODE
Restores the line, symbolic, and G_floating modes established by
the SET MODE command to their default values. Also restores the
default input/output radix.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
CANCEL MODE
4 Description
The effect of the CANCEL MODE command is equivalent to the
following commands:
DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT
DBG> CANCEL RADIX
The default radix for both data entry and display is decimal for
most languages.
On VAX processors, the exceptions are BLISS and MACRO-32, which
have a default radix of hexadecimal. On Alpha processors, the
exceptions are BLISS, MACRO-32, and MACRO-64, which have a
default radix of hexadecimal.
Related commands:
(SET,SHOW) MODE
(SET,SHOW,CANCEL) RADIX
4 Example
DBG> CANCEL MODE
This command restores the default radix mode and all default
mode values.
3 RADIX
Restores the default radix for the entry and display of integer
data.
Format
CANCEL RADIX
4 Qualifiers
/OVERRIDE
Cancels the override radix established by a previous SET
RADIX/OVERRIDE command. This sets the current override radix
to "none" and restores the output radix mode to the value
established with a previous SET RADIX or SET RADIX/OUTPUT
command. If you did not change the radix mode with a SET RADIX
or SET RADIX/OUTPUT command, the CANCEL RADIX/OVERRIDE command
restores the radix mode to its default value.
4 Description
The CANCEL RADIX command cancels the effect of any previous SET
RADIX and SET RADIX/OVERRIDE commands. It restores the input and
output radix to their default value. The default radix for both
data entry and display is decimal for most languages.
On VAX processors, the exceptions are BLISS and MACRO-32, which
have a default radix of hexadecimal. On Alpha processors, the
exceptions are BLISS, MACRO-32, and MACRO-64, which have a
default radix of hexadecimal.
The effect of the CANCEL RADIX/OVERRIDE command is more limited
and is explained in the description of the /OVERRIDE qualifier.
Related commands:
EVALUATE
(SET,SHOW) RADIX
4 Examples
1.DBG> CANCEL RADIX
This command restores the default input and output radix.
2.DBG> CANCEL RADIX/OVERRIDE
This command cancels any override radix you might have set with
the SET RADIX/OVERRIDE command.
3 SCOPE
Restores the default scope search list for symbol lookup.
Format
CANCEL SCOPE
4 Description
The CANCEL SCOPE command cancels the current scope search list
established by a previous SET SCOPE command and restores the
default scope search list, namely 0,1,2, . . . ,n, where n is the
number of calls in the call stack.
The default scope search list specifies that, for a symbol
without a path-name prefix, a symbol lookup such as EXAMINE X
first looks for X in the routine that is 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), then searches the global symbol
table (GST), if necessary.
Related commands:
(SET,SHOW) SCOPE
4 Example
DBG> CANCEL SCOPE
This command cancels the current scope.
3 SOURCE
Cancels a source directory search list, a source directory search
method, or both a list and method established by a previous SET
SOURCE command.
Format
CANCEL SOURCE
4 Qualifiers
/DISPLAY
Cancels the effect of a previous SET SOURCE/DISPLAY command,
which specifies the directory search list to be used by the
debugger when displaying source code. Canceling this command
means the debugger searches for a source file in the directory in
which it was compiled.
/EDIT
Cancels the effect of a previous SET SOURCE/EDIT command, which
specifies the directory search list to be used during execution
of the debugger's EDIT command. Canceling this command means the
debugger searches for a source file in the directory in which it
was compiled.
/EXACT
Cancels the effect of a previous SET SOURCE/EXACT command, which
specifies a directory search method. Canceling this command means
that the debugger no longer searches for the exact version of the
source file from compilation; it reverts to the default behavior
of searching for the latest version of the file.
/LATEST
Cancels the effect of a previous SET SOURCE/LATEST command, which
specifies a directory search method. In this case, the CANCEL
SOURCE/LATEST command directs the debugger to return to searching
for the exact version of the source file from compilation.
Because /LATEST is the default setting, this qualifier only makes
sense when used with other qualifiers, for example, /MODULE.
/MODULE
/MODULE=module-name
Cancels the effect of a previous SET SOURCE/MODULE=module-
name command in which the same module name and qualifiers were
specified. (The /MODULE qualifier allows you to specify a unique
directory search list, directory search method, or both, for
the named module.) You can append one or more of the qualifiers
listed above to the SET SOURCE/MODULE and CANCEL SOURCE/MODULE
commands.
If you issue a CANCEL SOURCE/MODULE command with additional
qualifiers, you cancel the effect of the specified qualifiers
on the module. If you issue an unqualified CANCEL SOURCE/MODULE
command, the debugger no longer differentiates the module from
any other module in your directories.
/ORIGINAL
(Applies to STDL programs only. Requires the installation of the
Correlation Facility (a separate layered product) and invocation
of the kept debugger.) Cancels the effect of a previous SET
SOURCE/ORIGINAL command. The SET SOURCE/ORIGINAL command is
required to debug STDL source files, and must be canceled when
you debug source files written in other languages.
4 Description
CANCEL SOURCE cancels the effect of a previous SET SOURCE
command. The nature of this cancellation depends on the
qualifiers activated in previous SET SOURCE commands. See the
CANCEL SOURCE examples to see how CANCEL SOURCE and SET SOURCE
interact.
When you issue a SET SOURCE command, be aware that one of the
two qualifiers -/LATEST or /EXACT-will always be active. These
qualifiers affect the debugger search method. The /LATEST
qualifier directs the debugger to search for the version last
created (the highest-numbered version in your directory). The
/EXACT qualifier directs the debugger to search for the version
last compiled (the version recorded in the debugger symbol table
created at compile time). For example, a SET SOURCE/LATEST
command might search for SORT.FOR;3 while a SET SOURCE/EXACT
command might search for SORT.FOR;1.
CANCEL SOURCE without the /DISPLAY or /EDIT qualifier cancels the
effect of both SET SOURCE/DISPLAY and SET SOURCE/EDIT, if both
were previously given.
The /DISPLAY qualifier is needed when the files to be displayed
are no longer in the compilation directory.
The /EDIT qualifier is needed when the files used for the display
of source code are different from the editable files. This is the
case with Ada programs. For Ada programs, the (SET,SHOW,CANCEL)
SOURCE commands affect the search of files used for source
display (the "copied" source files in Ada program libraries);
the (SET,SHOW,CANCEL) SOURCE/EDIT commands affect the search of
the source files that you edit when using the EDIT command.
For information specific to Ada programs, see the
Language_Support Ada help topic.
Related commands:
(SET,SHOW) SOURCE
4 Examples
1.DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD]
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
. . .
DBG> SHOW SOURCE
source directory search list for CTEST,
match the exact source file version:
[]
SYSTEM::DEVICE:[PROJD]
source directory list for all other modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
DBG> CANCEL SOURCE
DBG> SHOW SOURCE
source directory search list for CTEST,
match the exact source file version:
[]
SYSTEM::DEVICE:[PROJD]
all other source files will try to match
the latest source file version
In this example, the SET SOURCE command establishes a directory
search list and a search method (the default, latest version)
for source files other than CTEST. The CANCEL SOURCE command
cancels the directory search list but does not cancel the
search method.
2.DBG> SET SOURCE /EXACT
DBG> SHOW SOURCE
no directory search list in effect,
match the exact source file
DBG> SET SOURCE [JONES]
DBG> SHOW SOURCE
source directory list for all modules,
match the exact source file version:
[JONES]
DBG> CANCEL SOURCE /EXACT
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[JONES]
In this example, the SET SOURCE/EXACT command establishes a
search method (exact version) that remains in effect for the
SET SOURCE [JONES] command. The CANCEL SOURCE/EXACT command not
only cancels the SET SOURCE/EXACT command, but also affects the
SET SOURCE [JONES] command.
3 TRACE
Cancels a tracepoint.
Format
CANCEL TRACE [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a tracepoint to be canceled. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression when using any qualifiers except
/EVENT, /PREDEFINED, or /USER.
4 Qualifiers
/ACTIVATING
Cancels the effect of a previous SET TRACE/ACTIVATING command.
/ALL
By default, cancels all user-defined tracepoints. When used
with /PREDEFINED, it cancels all predefined tracepoints but
no user-defined tracepoints. To cancel all tracepoints, use
/ALL/USER/PREDEFINED.
/BRANCH
Cancels the effect of a previous SET TRACE/BRANCH command.
/CALL
Cancels the effect of a previous SET TRACE/CALL command.
/EVENT
/EVENT=event-name
Cancels the effect of a previous SET TRACE/EVENT=event-name
command. Specify the event name (and address expression, if
any) exactly as specified with the SET TRACE/EVENT command. To
identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
/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
Cancels a specified predefined tracepoint without affecting any
user-defined tracepoints. When used with /ALL, it cancels all
predefined tracepoints.
/TERMINATING
Cancels the effect of a previous SET TRACE/TERMINATING command.
/USER
Cancels a specified user-defined tracepoint without affecting any
predefined tracepoints. This is the default unless you specify
/PREDEFINED. To cancel all user-defined tracepoints, use /ALL.
/VECTOR_INSTRUCTION
(VAX only) Cancels the effect of a previous SET TRACE/VECTOR_
INSTRUCTION command.
4 Description
Tracepoints can be user defined or predefined. User-defined
tracepoints are explicitly set with the SET TRACE command.
Predefined tracepoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are established
automatically when you start the debugger. Use the SHOW TRACE
command to identify all tracepoints that are currently set. Any
predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled
independently. For example, a location or event can have both
a user-defined and a predefined tracepoint. Canceling the user-
defined tracepoint does not affect the predefined tracepoint, and
conversely.
To cancel only user-defined tracepoints, do not specify
/PREDEFINED with the CANCEL TRACE command (the default is /USER).
To cancel only predefined tracepoints, specify /PREDEFINED
but not /USER. To cancel both user-defined and predefined
tracepoints, use CANCEL TRACE/ALL/USER/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 that
was established at a specific location, specify that same
location (address expression) with CANCEL TRACE. To cancel
tracepoints that were established on a class of instructions
or events, specify the class of instructions or events with the
corresponding qualifier (/LINE, /BRANCH, /ACTIVATING, /EVENT=,
and so on). For more information, see the qualifier descriptions.
To cause the debugger to temporarily ignore a tracepoint, but
retain definition of the tracepoint, use the command DEACTIVATE
TRACE. You can later activate the tracepoint (with ACTIVATE
TRACE).
Related commands:
(ACTIVATE,DEACTIVATE,SET,SHOW) TRACE
CANCEL ALL
(SET,SHOW,CANCEL) BREAK
(SET,SHOW) EVENT_FACILITY
4 Examples
1.DBG> CANCEL TRACE MAIN\LOOP+10
This command cancels the user-defined tracepoint at the
location MAIN\LOOP+10.
2.DBG> CANCEL TRACE/ALL
This command cancels all user-defined tracepoints.
3.all> CANCEL TRACE/TERMINATING
This command cancels a previous SET TRACE/TERMINATING command.
As a result, a user-defined tracepoint is not triggered when a
process does an image exit.
4.DBG> CANCEL TRACE/EVENT=RUN %TASK 3
This command cancels the tracepoint that was set to trigger
when task 3 (task ID = 3) entered the RUN state.
3 TYPE
4 /OVERRIDE
Cancels the override type established by a previous SET
TYPE/OVERRIDE command.
Format
CANCEL TYPE/OVERRIDE
5 Description
The CANCEL TYPE/OVERRIDE command sets the current override type
to "none." As a result, a program location associated with a
compiler-generated type is interpreted according to that type.
Related commands:
DEPOSIT
EXAMINE
(SET,SHOW) EVENT_FACILITY
(SET,SHOW) TYPE/OVERRIDE
5 Example
DBG> CANCEL TYPE/OVERRIDE
This command cancels the effect of a previous SET TYPE/OVERRIDE
command.
3 WATCH
Cancels a watchpoint.
Format
CANCEL WATCH [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a watchpoint to be canceled. With high-level languages,
this is typically the name of a variable. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression with /ALL.
4 Qualifiers
/ALL
Cancels all watchpoints.
4 Description
The effect of the CANCEL WATCH command is symmetrical with the
effect of the SET WATCH command. To cancel a watchpoint that was
established at a specific location with the SET WATCH command,
specify that same location with CANCEL WATCH. Thus, to cancel
a watchpoint that was set on an entire aggregate, specify the
aggregate in the CANCEL WATCH command; to cancel a watchpoint
that was set on one element of an aggregate, specify that element
in the CANCEL WATCH command.
The CANCEL ALL command also cancels all watchpoints.
To cause the debugger to temporarily ignore a watchpoint, but
not delete the definition of the watchpoint, use the command
DEACTIVATE WATCH. You can later activate the watchpoint (with
ACTIVATE WATCH).
Related commands:
(ACTIVATE,DEACTIVATE,SET,SHOW) WATCH
CANCEL ALL
(SET,SHOW,CANCEL) BREAK
(SET,SHOW,CANCEL) TRACE
4 Examples
1.DBG> CANCEL WATCH SUB2\TOTAL
This command cancels the watchpoint at variable TOTAL in module
SUB2.
2.DBG> CANCEL WATCH/ALL
This command cancels all watchpoints you have set.
3 WINDOW
Permanently deletes a screen window definition.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
CANCEL WINDOW [window-name[, . . . ]]
4 Parameters
window-name
Specifies the name of a screen window definition to be canceled.
Do not use the asterisk (*) wildcard character. Instead, use
the /ALL qualifier. Do not specify a window definition name with
/ALL.
4 Qualifiers
/ALL
Cancels all predefined and user-defined window definitions.
4 Description
When a window definition is canceled, you can no longer use its
name in a DISPLAY command. The CANCEL WINDOW command does not
affect any displays.
Related commands:
(SHOW,CANCEL) DISPLAY
(SET,SHOW) WATCH
4 Example
DBG> CANCEL WINDOW MIDDLE
This command permanently deletes the screen window definition
MIDDLE.
2 CONNECT
(Kept debugger only.) Interrupts an image that is running without
debugger control in another process and brings that process under
debugger control. When used without a parameter, CONNECT brings
any spawned process that is waiting to connect to the debugger
under debugger control.
On Alpha systems, the debugger command CONNECT can also be used
to bring a target system running the Alpha operating system
under the control of the OpenVMS Alpha System-Code Debugger.
The OpenVMS Alpha System-Code Debugger is a kernel debugger that
you activate through the OpenVMS Debugger.
If you are using the CONNECT command to debug the Alpha operating
system, you must complete the instructions described in the
System Code Debugger chapter of the OpenVMS Alpha System Analysis
Tools Manual before you issue the command. (These instructions
include the creation of an Alpha device driver and the setup
commands activating the OpenVMS Alpha System-Code Debugger.) You
must also have started the OpenVMS Debugger with the DCL command
DEBUG/KEEP.
Format
CONNECT [process-spec]
CONNECT %NODE_NAME node-name
3 Parameters
process-spec
Specifies a process in which an image to be interrupted is
running. The process must be in the same OpenVMS job as the
process in which the debugger was started. Use any of the
following forms:
[%PROCESS_NAME] proc- The OpenVMS process name, if that
name name contains no space or lowercase
characters. The process name can include
the asterisk (*) wildcard character.
[%PROCESS_NAME] "proc- The OpenVMS process name, if that name
name" contains space or lowercase characters.
You can also use apostrophes (') instead
of quotation marks (").
%PROCESS_PID proc-id The OpenVMS process identifier (PID, a
hexadecimal number).
node-name
(Alpha only) When you are debugging the Alpha operating
system, specifies the node name of the machine to which you
are connecting (the target machine running the Alpha operating
system).
3 Qualifiers
/PASSWORD
/PASSWORD="password"
(Alpha only) When you are debugging the Alpha operating
system, specifies the password for the machine to which you
are connecting (the target machine running the Alpha operating
system). If a password has not been established for that machine,
this qualifier can be omitted.
/IMAGE_PATH
/IMAGE_PATH="image-path"
(Alpha only) When you are debugging the Alpha operating system,
specifies the image-path for the machine from which you are
connecting (the host machine running the debugger). The image-
path is a logical name that points to the location of system
images. The default logical name is DBGHK$IMAGE_PATH:.
3 Description
(Kept debugger only.) When you specify a process, the CONNECT
command enables you to interrupt an image that is running without
debugger control in that process and bring the process under
debugger control. The command is useful if, for example, you
run a debuggable image with the DCL command RUN/NODEBUG, or if
your program issues a LIB$SPAWN Run-Time Library call that does
not start the debugger. You cannot connect to a process created
through a $CREPRC system service call.
Depending on the version of the debugger you are running on your
system, you may be restricted to connection with processes you
created, or you may be able to connect to processes created by
any member of your user identification code (UIC) group. (In some
cases, you may have to set the SYSGEN SECURITY_POLICY parameter
to 8 before you create the process.) Restrictions on Process
Creation, by Debugger Version Number lists the restrictions that
apply to specific versions of the debugger.
Table 1-1 Restrictions on Process Creation, by Debugger Version
Number
Then you can
connect to
a process
started
If you are running... by... With the SYSGEN Parameter?
VAX Version 5.5-2, You No
earlier
Alpha Version 6.0,
earlier
VAX Version 6.0 You, Member Yes
of UIC Group
VAX Version 6.1, You, Member No
later of UIC Group
Alpha Version 6.1,
later
If debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG,
DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and
VMSDEBUGUIL) exist, they must translate to the same definitions
in both the debugger and the target process.
The image modules must have been compiled and linked with the
/DEBUG qualifier. The image cannot have been linked with the
/NOTRACEBACK qualifier.
When the process is brought under debugger control, execution of
the image is suspended at the point at which it was interrupted.
When you do not specify a process, the CONNECT command 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 equivalent
to that resulting from entering the SET TRACE/ACTIVATING command.
The process is then known to the debugger and can be identified
in a SHOW PROCESS display.
You cannot use the CONNECT command to connect to a subprocess
of a process running under debugger control. Use the SET PROCESS
command to connect to such a subprocess.
Using the CONNECT Command to Debug the Alpha Operating System
(Alpha only)
You can use the CONNECT command to debug Alpha operating
system code with the OpenVMS Alpha System-Code Debugger (SCD).
Typically, you issue this command from a timesharing (host) Alpha
machine (running SCD), and you connect to a standalone (target)
Alpha machine (running the Alpha operating system). Communication
between the two machines occurs over the Ethernet network.
NOTE
The port used for SCD on the target machine is not
configured at all, and cannot be used for any other
purpose, such as DECnet, LAT, user applications, and so on.
Therefore, to be able to use DECnet or to be in a cluster
while using SCD, you must have another Ethernet port for
that traffic.
In some cases, you may find that you need to use the alternative
Delta/XDelta Debugger to debug operating system code. These cases
include:
o When you have access to only one Alpha machine for debugging
o When you are debugging portions of code that generate Ethernet
traffic on the target system and have only one ethernet port.
Generally, however, the OpenVMS Alpha System-Code Debugger is
preferred for debugging Alpha operating system code. For complete
information on using this debugger, see the OpenVMS Alpha System
Analysis Tools Manual.
Related commands:
DISCONNECT
Ctrl/Y
(SET,SHOW,CANCEL) TRACE
3 Examples
1.DBG_1> CONNECT
This command brings under debugger control any processes that
are waiting to be connected to the debugger.
2.DBG_1> CONNECT JONES_3
This command interrupts the image running in process JONES_3
and brings the process under debugger control. Process JONES_
3 must be in the same UIC group as the process in which the
debugger was started. Also, the image must not have been linked
with the /NOTRACEBACK qualifier.
3.DBG> CONNECT %NODE_NAME SCDTST /PASSWORD="eager_beaver"
%DEBUG-I-NOLOCALS, image does not contain local symbols
DBG>
On Alpha systems, this CONNECT command brings the target system
running Alpha operating-system code under debugger control.
This example specifies that the Alpha target machine (running
the operating system) has a node name of SCDTST and a password
of eager_beaver. The Alpha host machine (running the debugger)
has the default DBGHK$IMAGE_PATH: image-path.
2 Ctrl
3 /C
When entered from within a debugging session, Ctrl/C aborts the
execution of a debugger command or interrupts program execution
without interrupting the debugging session.
NOTE
Do not use Ctrl/Y from within a debugging session.
Format
<Ctrl/C>
4 Description
Pressing Ctrl/C enables you to abort the execution of a debugger
command or to interrupt program execution without interrupting
the debugging session. This is useful when, for example, the
program is executing an infinite loop that does not have a
breakpoint, or 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.
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 Ctrl-key sequence. Note, however, that many
Ctrl-key sequences have predefined functions, and the SET ABORT_
KEY command enables you to override such definitions (see the
OpenVMS User's Manual). Some of the Ctrl-key characters not used
by the operating system are G, K, N, and P.
If your program does not have a Ctrl/C AST service routine
enabled and you assign the debugger's abort function to another
Ctrl-key sequence, then Ctrl/C behaves like Ctrl/Y-that is, it
interrupts the debugging session and returns you to DCL level.
Do not use Ctrl/Y from within a debugging session. Instead, use
either Ctrl/C or an equivalent Ctrl-key sequence established with
the SET ABORT_KEY command.
You can use the SPAWN and ATTACH commands to leave and return to
a debugging session without losing the debugging context.
Related commands:
ATTACH
Ctrl/Y
(SET,SHOW) ABORT_KEY
SPAWN
4 Example
DBG> GO
. . .
<Ctrl/C>
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
<Ctrl/C>
%DEBUG-W-ABORTED, command aborted by user request
DBG>
This example shows how to use Ctrl/C to interrupt program
execution and then to abort the execution of a debugger
command.
3 /W
Refreshes the screen in screen mode (like DISPLAY/REFRESH). See
the DISPLAY/REFRESH command.
Format
<Ctrl/W>
3 /Y
When entered from DCL level, Ctrl/Y interrupts an image that is
running without debugger control, enabling you then to start the
debugger with the DCL command DEBUG.
NOTES
Do not use Ctrl/Y from within a debugging session. Instead,
use Ctrl/C or an equivalent abort-key sequence established
with the SET ABORT_KEY command.
When you start the debugger with the Ctrl/Y-DEBUG sequence,
you cannot then use the debugger RUN or RERUN commands.
Format
<Ctrl/Y>
4 Description
Pressing Ctrl/Y at DCL level enables you to interrupt an image
that is running without debugger control, so that you can then
start the debugger with the DCL command DEBUG.
You can bring an image under debugger control only if, as a
minimum, that image was linked with the /TRACEBACK qualifier
(/TRACEBACK is the default for the LINK command).
When you press Ctrl/Y to interrupt the image's execution, control
is passed to DCL. If you then enter the DCL command DEBUG, the
interrupted image is brought under control of the debugger. The
debugger sets its language-dependent parameters to the source
language of the module in which execution was interrupted and
displays its prompt. You can then determine where execution was
suspended by entering a SHOW CALLS command.
The Ctrl/Y-DEBUG sequence is not supported in the kept debugger
configuration.
The Ctrl/Y-DEBUG sequence is not supported in the Compaq
DECwindows Motif for OpenVMS user interface to the debugger.
Instead, use the STOP button.
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) to that debugging session.
Related commands:
CONNECT
Ctrl/C
DEBUG (DCL command)
RUN (DCL command)
4 Examples
1.$ RUN/NODEBUG TEST_B
. . .
<Ctrl/Y>
Interrupt
$ DEBUG
Debugger Banner and Version Number
Language: ADA, Module: SWAP
DBG>
In this example, the RUN/NODEBUG command executes the image
TEST_B without debugger control. Execution is interrupted
with Ctrl/Y. The DEBUG command then causes the debugger to be
started. The debugger displays its banner, sets the language-
dependent parameters to the language (Ada, in this case) of the
module (SWAP) in which execution was interrupted, and displays
the prompt.
2.$ RUN/NODEBUG PROG2
. . .
<Ctrl/Y>
Interrupt
$ DEBUG
Debugger Banner and Version Number
Language: FORTRAN, Module: SUB4
predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 1
DBG>
In this example, the DEFINE/JOB command establishes a
multiprocess debugging configuration. The RUN/NODEBUG command
executes the image PROG2 without debugger control. The Ctrl/Y-
DEBUG sequence interrupts execution and starts the debugger.
The banner indicates that a new debugging session has been
started. The activation tracepoint indicates where execution
was interrupted when the debugger took control of the process.
3 /Z
Ends a debugging session (like EXIT). See the EXIT command.
Format
<Ctrl/Z>
2 DEACTIVATE
3 BREAK
Deactivates a breakpoint, which you can later activate.
Format
DEACTIVATE BREAK [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a breakpoint to be deactivated. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression when using any qualifiers except
/EVENT, /PREDEFINED, or /USER.
4 Qualifiers
/ACTIVATING
Deactivates a breakpoint established by a previous SET
BREAK/ACTIVATING command.
/ALL
By default, deactivates all user-defined breakpoints. When used
with /PREDEFINED, deactivates all predefined breakpoints but
no user-defined breakpoints. To deactivate all breakpoints, use
/ALL/USER/PREDEFINED.
/BRANCH
Deactivates a breakpoint established by a previous SET
BREAK/BRANCH command.
/CALL
Deactivates a breakpoint established by a previous SET BREAK/CALL
command.
/EVENT
/EVENT=event-name
Deactivates a breakpoint established by a previous SET
BREAK/EVENT=event-name command. Specify the event name (and
address expression, if any) exactly as specified with the SET
BREAK/EVENT command.
To identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Deactivates a breakpoint established by a previous SET
BREAK/EXCEPTION command.
/HANDLER
Deactivates a breakpoint established by a previous SET
BREAK/HANDLER command.
/INSTRUCTION
Deactivates a breakpoint established by a previous SET
BREAK/INSTRUCTION command.
/LINE
Deactivates a breakpoint established by a previous SET BREAK/LINE
command.
/PREDEFINED
Deactivates a specified predefined breakpoint without affecting
any user-defined breakpoints. When used with /ALL, deactivates
all predefined breakpoints.
/SYSEMULATE
(Alpha only) Deactivates a breakpoint established by a previous
SET BREAK/SYSEMULATE command.
/TERMINATING
Deactivates a breakpoint established by a previous SET
BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Deactivates a breakpoint established by a previous
SET BREAK/UNALIGNED_DATA command.
/USER
Deactivates a specified user-defined breakpoint. To deactivate
all user-defined breakpoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Deactivates a breakpoint established by a previous SET
BREAK/VECTOR_INSTRUCTION command.
4 Description
User-defined breakpoints are activated when you set them with
the SET BREAK command. Predefined breakpoints are activated by
default. Use the DEACTIVATE BREAK command to deactivate one or
more breakpoints.
If you deactivate a breakpoint, the debugger ignores the
breakpoint during program execution. To activate a deactivated
breakpoint, use the ACTIVATE BREAK command. You can activate and
deactivate user-defined and predefined breakpoints separately.
Activating and deactivating breakpoints enables you to run and
rerun your program with or without breakpoints without having to
cancel and then reset them. By default, the RERUN command saves
the current state of all breakpoints (activated or deactivated).
To check if a breakpoint is deactivated, use the SHOW BREAK
command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,ACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY
4 Examples
1.DBG> DEACTIVATE BREAK MAIN\LOOP+10
This command deactivates the user-defined breakpoint set at the
address expression MAIN\LOOP+10.
2.DBG> DEACTIVATE BREAK/ALL
This command deactivates all user-defined breakpoints.
3 TRACE
Deactivates a tracepoint, which you can later activate.
Format
DEACTIVATE TRACE [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a tracepoint to be deactivated. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an address expression when using any qualifiers except
/EVENT, /PREDEFINED, or /USER.
4 Qualifiers
/ACTIVATING
Deactivates a tracepoint established with a previous SET
TRACE/ACTIVATING command.
/ALL
By default, deactivates all user-defined tracepoints. When used
with /PREDEFINED, it deactivates all predefined tracepoints but
no user-defined tracepoints. To deactivate all tracepoints, use
/ALL/USER/PREDEFINED.
/BRANCH
Deactivates a tracepoint established with a previous SET
TRACE/BRANCH command.
/CALL
Deactivates a tracepoint established with a previous SET
TRACE/CALL command.
/EVENT
/EVENT=event-name
Deactivates a tracepoint established with a previous SET
TRACE/EVENT=event-name command. Specify the event name (and
address expression, if any) exactly as specified with the SET
TRACE/EVENT command.
To identify the current event facility and the associated event
names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Deactivates a tracepoint established with a previous SET
TRACE/EXCEPTION command.
/INSTRUCTION
Deactivates a tracepoint established with a previous SET
TRACE/INSTRUCTION command.
/LINE
Deactivates a tracepoint established with a previous SET
TRACE/LINE command.
/PREDEFINED
Deactivates a specified predefined tracepoint without affecting
any user-defined tracepoints. When used with /ALL, it deactivates
all predefined tracepoints.
/TERMINATING
Deactivates a tracepoint established with a previous SET
TRACE/TERMINATING command.
/USER
Deactivates a specified user-defined tracepoint without affecting
any predefined tracepoints. When used with /ALL, it deactivates
all user-defined tracepoints. The /USER qualifier is the default
unless you specify /PREDEFINED.
/VECTOR_INSTRUCTION
(VAX only) Deactivates a tracepoint established with a previous
SET TRACE/VECTOR_INSTRUCTION command.
4 Description
User-defined tracepoints are activated when you set them with
the SET TRACE command. Predefined tracepoints are activated by
default. Use the DEACTIVATE TRACE command to deactivate one or
more tracepoints.
If you deactivate a tracepoint, the debugger ignores the
tracepoint during program execution. To activate a deactivated
tracepoint, use the ACTIVATE TRACE command. You can activate and
deactivate user-defined and predefined tracepoints separately.
Activating and deactivating tracepoints enables you to run and
rerun your program with or without tracepoints without having to
cancel and then reset them. By default, the RERUN command saves
the current state of all tracepoints (activated or deactivated).
To check if a tracepoint is deactivated, use the SHOW TRACE
command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,ACTIVATE) TRACE
4 Examples
1.DBG> DEACTIVATE TRACE MAIN\LOOP+10
This command deactivates the user-defined tracepoint at the
location MAIN\LOOP+10.
2.DBG> DEACTIVATE TRACE/ALL
This command deactivates all user-defined tracepoints.
3 WATCH
Deactivates a watchpoint, which you can later activate.
Format
DEACTIVATE WATCH [address-expression[, . . . ]]
4 Parameters
address-expression
Specifies a watchpoint to be deactivated. With high-level
languages, this is typically the name of a variable. Do not
use the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify an address expression with /ALL.
4 Qualifiers
/ALL
Deactivates all watchpoints.
4 Description
Watchpoints are activated when you set them with the SET WATCH
command. Use the DEACTIVATE WATCH command to deactivate one or
more watchpoints.
If you deactivate a watchpoint, the debugger ignores the
watchpoint during program execution. To activate a deactivated
watchpoint, use the ACTIVATE WATCH command. Activating and
deactivating watchpoints enables you to run and rerun your
program with or without watchpoints without having to cancel
and then reset them.
By default, the RERUN command saves the current state of all
static watchpoints (activated or deactivated). The state of
a particular nonstatic watchpoint might or might not be saved
depending on the scope of the variable being watched relative to
the main program unit (where execution restarts).
To check if a watchpoint is deactivated, use the SHOW WATCH
command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,ACTIVATE) WATCH
4 Examples
1.DBG> DEACTIVATE WATCH SUB2\TOTAL
This command deactivates the watchpoint at variable TOTAL in
module SUB2.
2.DBG> DEACTIVATE WATCH/ALL
This command deactivates all watchpoints you have set.
2 DECLARE
Declares a formal parameter within a command procedure. This
enables you to pass an actual parameter to the procedure when
entering an execute procedure (@) command.
Format
DECLARE p-name:p-kind [,p-name:p-kind[, . . . ]]
3 Parameters
p-name
Specifies a formal parameter (a symbol) that is declared within
the command procedure.
Do not specify a null parameter (represented either by two
consecutive commas or by a comma at the end of the command).
p-kind
Specifies the parameter kind of a formal parameter. Valid
keywords are as follows:
ADDRESS Specifies that the actual parameter is interpreted
as an address expression. Same effect as
DEFINE/ADDRESS symbol-name = actual-parameter.
COMMAND Specifies that the actual parameter is
interpreted as a command. Same effect as
DEFINE/COMMAND symbol-name = actual-parameter.
VALUE Specifies that the actual parameter is interpreted as a
value expression in the current language. Same effect
as DEFINE/VALUE symbol-name = actual-parameter.
3 Description
The DECLARE command is valid only within a command procedure.
The DECLARE command binds one or more actual parameters,
specified on the command line following the execute procedure
(@) command, to formal parameters (symbols) declared within a
command procedure.
Each p-name:p-kind pair specified by a DECLARE command binds one
formal parameter to one actual parameter. Formal parameters are
bound to actual parameters in the order in which the debugger
processes the parameter declarations. If you specify several
formal parameters on a single DECLARE command, the leftmost
formal parameter is bound to the first actual parameter, the
next formal parameter is bound to the second, and so on. If you
use a DECLARE command in a loop, the formal parameter is bound
to the first actual parameter on the first iteration of the loop;
the same formal parameter is bound to the second actual parameter
on the next iteration, and so on.
Each parameter declaration acts like a DEFINE command: it
associates a formal parameter with an address expression, a
command, or a value expression in the current language, according
to the parameter kind specified. The formal parameters themselves
are consistent with those accepted by the DEFINE command and can
in fact be deleted from the symbol table with the DELETE command.
The %PARCNT built-in symbol, which can be used only within a
command procedure, enables you to pass a variable number of
parameters to a command procedure. The value of %PARCNT is the
number of actual parameters passed to the command procedure.
Related commands:
@ (Execute Procedure)
DEFINE
DELETE
3 Examples
1.! ***** Debugger Command Procedure EXAM_GO.COM *****
DECLARE L:ADDRESS, M:COMMAND
EXAMINE L; M
DBG> @EXAM_GO X "@DUMP"
In this example, the command procedure EXAM_GO.COM accepts two
parameters, an address expression (L) and a command string
(M). The address expression is then examined and the command
is executed.
At the debugger prompt, the @EXAM_GO X "@DUMP" command executes
EXAM_GO.COM, passing the address expression X and the command
string @DUMP.
2.! ***** Debugger Command Procedure VAR.DBG *****
SET OUTPUT VERIFY
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
DBG> @VAR.DBG 12,37,45
%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
12
37
45
%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG
DBG>
In this example, the command procedure VAR.DBG accepts a
variable number of parameters. That number is stored in the
built-in symbol %PARCNT.
At the debugger prompt, the @VAR.DBG command executes VAR.DBG,
passing the actual parameters 12, 37, and 45. Therefore,
%PARCNT has the value 3, and the FOR loop is repeated 3
times. The FOR loop causes the DECLARE command to bind each
of the three actual parameters (starting with 12) to a new
declaration of X. Each actual parameter is interpreted as a
value expression in the current language, and the EVALUATE X
command displays that value.
2 DEFINE
Assigns a symbolic name to an address expression, command, or
value.
Format
DEFINE symbol-name=parameter [,symbol-name=parameter[, . . . ]]
3 Parameters
symbol-name
Specifies a symbolic name to be assigned to an address, command,
or value. 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.
parameter
Depends on the qualifier specified.
3 Qualifiers
/ADDRESS
(Default) Specifies that the defined symbol is an abbreviation
for an address expression. In this case, parameter is an address
expression.
/COMMAND
Specifies that the defined symbol is treated as a new debugger
command. In this case, parameter is a quoted character string.
This qualifier provides, in simple cases, essentially the same
capability as the following DCL command:
$ symbol := string
To define complex commands, you might need to use command
procedures with formal parameters. For more information about
declaring parameters to command procedures, see the DECLARE
command.
/LOCAL
Specifies that the definition is valid only in the command
procedure in which it is defined. The defined symbol is not
visible at debugger command level. By default, a symbol defined
within a command procedure is visible outside that procedure.
/VALUE
Specifies that the defined symbol is an abbreviation for a value.
In this case, parameter is a language expression in the current
language.
3 Description
The DEFINE/ADDRESS command assigns a symbolic name to an
address expression in a program. You can define a symbol for a
nonsymbolic program location or for a symbolic program location
having a long path-name prefix. You can then refer to that
program location with the symbolic name. The /ADDRESS qualifier
is the default.
The DEFINE/COMMAND command enables you to define abbreviations
for debugger commands or even define new commands, either from
the debugger command level or from command procedures.
The DEFINE/VALUE command enables you to assign a symbolic name to
a value (or the result of evaluating a language expression).
The DEFINE/LOCAL command confines symbol definitions to command
procedures. By default, defined symbols are global (visible
outside the command procedure).
To enter several DEFINE commands with the same qualifier, first
use the SET DEFINE command to establish a new default qualifier
(for example, SET DEFINE COMMAND makes subsequent DEFINE commands
behave like DEFINE/COMMAND). You can override the current default
qualifier for a single DEFINE command by specifying another
qualifier.
In symbol translation, the debugger searches symbols you define
during the debugging session first. So if you define a symbol
that already exists in your program, the debugger translates the
symbol according to its defined definition, unless you specify a
path-name prefix.
If a symbol is redefined, the previous definition is canceled,
even if you used different qualifiers with the DEFINE command.
Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE
commands are available only when the image in whose context
they were created is the current image. If you use the SET IMAGE
command to establish a new current image, these definitions are
temporarily unavailable. However, definitions created with the
DEFINE/COMMAND and DEFINE/KEY commands are always available for
all images.
Use the SHOW SYMBOL/DEFINED command to determine the equivalence
value of a symbol.
Use the DELETE command to cancel a symbol definition.
Related commands:
DECLARE
DELETE
SET IMAGE
SHOW DEFINE
SHOW SYMBOL/DEFINED
3 Examples
1.DBG> DEFINE/VALUE COUNTER=0
DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1)
In this example, the DEFINE/VALUE command assigns a value of
0 to the symbol COUNTER. The SET TRACE command causes the
debugger to increment the value of the symbol COUNTER by 1
whenever address R is encountered. In other words, this example
counts the number of calls to R.
2.DBG> DEFINE/COMMAND BRE = "SET BREAK"
This command assigns the symbol BRE to the debugger command SET
BREAK.
3 /KEY
Assigns a string to a function key.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
DEFINE/KEY key-name "equivalence-string"
4 Parameters
key-name
Specifies a function key to be assigned a string. Valid key names
are as follows:
Key LK201
Name Keyboard VT100-type VT52-type
PF1 PF1 PF1 Blue
PF2 PF2 PF2 Red
PF3 PF3 PF3 Black
PF4 PF4 PF4
KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9
PERIOD Keypad Keypad
period (.) period (.)
COMMA Keypad comma Keypad comma
(,) (,)
E1 Find
E2 Insert Here
E3 Remove
E4 Select
E5 Prev Screen
E6 Next Screen
HELP Help
DO Do
F6-F20 F6-F20
On LK201 keyboards:
o You cannot define keys F1 to F5 or the arrow keys (E7 to E10).
o You can define keys F6 to F14 only if you have first entered
the DCL command SET TERMINAL/NOLINE_EDITING. In that case, the
line-editing functions of the left and right arrow keys (E8
and E9) are disabled.
equivalence-string
Specifies the string to be processed when you press the specified
key. Typically, this is one or more debugger commands. If the
string includes any space or nonalphanumeric characters (for
example, a semicolon separating two commands), enclose the string
in quotation marks (").
4 Qualifiers
/ECHO
/ECHO (default)
/NOECHO
Controls whether the command line is displayed after the key has
been pressed. Do not use /NOECHO with /NOTERMINATE.
/IF_STATE
/IF_STATE=(state-name[, . . . ])
/NOIF_STATE (default)
Specifies one or more states to which a key definition applies.
The /IF_STATE qualifier assigns the key definition to the
specified states. You can specify predefined states, such as
DEFAULT and GOLD, or user-defined states. A state name can be
any appropriate alphanumeric string. The /NOIF_STATE qualifier
assigns the key definition to the current state.
/LOCK_STATE
/LOCK_STATE
/NOLOCK_STATE (default)
Controls how long the state set by /SET_STATE remains in effect
after the specified key is pressed. The /LOCK_STATE qualifier
causes the state to remain in effect until it is changed
explicitly (for example, with a SET KEY/STATE command). The
/NOLOCK_STATE qualifier causes the state to remain in effect
only until the next terminator character is typed, or until the
next defined function key is pressed.
/LOG
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the key
definition has been successfully created. The /LOG qualifier
displays the message. The /NOLOG qualifier suppresses the
message.
/SET_STATE
/SET_STATE=state-name
/NOSET_STATE (default)
Controls whether pressing the key changes the current key state.
The /SET_STATE qualifier causes the current state to change to
the specified state when you press the key. The /NOSET_STATE
qualifier causes the current state to remain in effect.
/TERMINATE
/TERMINATE
/NOTERMINATE (default)
Controls whether the specified string is terminated (processed)
when the key is pressed. The /TERMINATE qualifier causes the
string to be terminated when the key is pressed. The /NOTERMINATE
qualifier enables you to press other keys before terminating the
string by pressing the Return key.
4 Description
Keypad mode must be enabled (SET MODE KEYPAD) before you can use
this command. Keypad mode is enabled by default.
The DEFINE/KEY command enables you to assign a string to a
function key, overriding any predefined function that was bound
to that key. When you then press the key, the debugger enters
the currently associated string into your command line. The
DEFINE/KEY command is like the DCL command DEFINE/KEY.
For a list of the predefined key functions, see the Keypad_
Definitions_CI online help topic.
On VT52- and VT100-series terminals, the function keys you can
use include all of the numeric keypad keys. Newer terminals and
workstations have the LK201 keyboard. On LK201 keyboards, the
function keys you can use include all of the numeric keypad keys,
the nonarrow keys of the editing keypad (Find, Insert Here, and
so on), and keys F6 to F20 at the top of the keyboard.
A key definition remains in effect until you redefine the key,
enter the DELETE/KEY command for that key, or exit the debugger.
You can include key definitions in a command procedure, such as
your debugger initialization file.
The /IF_STATE qualifier enables you to increase the number of
key definitions available on your terminal. The same key can be
assigned any number of definitions as long as each definition is
associated with a different state.
By default, the current key state is the DEFAULT state. The
current state can be changed with the SET KEY/STATE command,
or by pressing a key that causes a state change (a key that was
defined with DEFINE/KEY/LOCK_STATE/SET_STATE).
Related commands:
DELETE/KEY
(SET,SHOW) KEY
4 Examples
1.DBG> SET KEY/STATE=GOLD
%DEBUG-I-SETKEY, keypad state has been set to GOLD
DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX"
%DEBUG-I-DEFKEY, GOLD key KP9 has been defined
In this example, the SET KEY command establishes GOLD as
the current key state. The DEFINE/KEY command assigns the
SET RADIX/OVERRIDE HEX command to keypad key 9 (KP9) for the
current state (GOLD). The command is processed when you press
the key.
2.DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE "
%DEBUG-I-DEFKEY, BLUE key KP9 has been defined
This command assigns the unterminated command string "SET BREAK
%LINE" to keypad key 9 for the BLUE state. After pressing BLUE-
KP9, you can enter a line number and then press the Return key
to terminate and process the SET BREAK command.
3.DBG> SET KEY/STATE=DEFAULT
%DEBUG-I-SETKEY, keypad state has been set to DEFAULT
DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 ""
%DEBUG-I-DEFKEY, DEFAULT key F12 has been defined
In this example, the SET KEY command establishes DEFAULT as
the current state. The DEFINE/KEY command makes the F12 key
(on an LK201 keyboard) a state key. Pressing F12 while in
the DEFAULT state causes the current state to become RED. The
key definition is not terminated and has no other effect (a
null string is assigned to F12). After pressing F12, you can
enter "RED" commands by pressing keys that have definitions
associated with the RED state.
3 /PROCESS_SET
Assigns a symbolic name to a list of process specifications.
Format
DEFINE/PROCESS_SET process-set-name =process-spec[, . . . ]
4 Parameters
process-set-name
Specifies 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
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
If you do not specify a process, the symbolic name is created but
contains no process entries.
4 Description
The DEFINE/PROCESS_SET command assigns a symbol to a list of
process specifications. You can then use the symbol in any
command where a list of process specifications is allowed.
The DEFINE/PROCESS_SET command does not verify the existence of a
specified process. This enables you to specify processes that do
not yet exist.
To identify a symbol that was defined with the DEFINE/PROCESS_SET
command, use the SHOW SYMBOL/DEFINED command. To delete a symbol
that was defined with the DEFINE/PROCESS_SET command, use the
DELETE command.
Related commands:
DELETE
(SET,SHOW) DEFINE
SHOW SYMBOL/DEFINED
4 Examples
1.all> DEFINE/PROCESS_SET SERVERS=FILE_SERVER,NETWORK_SERVER
all> SHOW PROCESS SERVERS
Number Name State Current PC
* 1 FILE_SERVER step FS_PROG\%LINE 37
2 NETWORK_SERVER break NET_PROG\%LINE 24
all>
This DEFINE/PROCESS_SET command assigns the symbolic name
SERVERS to the process set consisting of FILE_SERVER and
NETWORK_SERVER. The SHOW PROCESS SERVERS command displays
information about the processes that make up the set SERVERS.
2.all> DEFINE/PROCESS_SET G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS
all> SHOW SYMBOL/DEFINED G1
defined G1
bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS"
was defined /process_set
all> DELETE G1
This DEFINE/PROCESS_SET command assigns the symbolic name G1 to
the process set consisting of process 1 and the visible process
(process 3). The SHOW SYMBOL/DEFINED G1 command identifies the
defined symbol G1. The DELETE G1 command deletes the symbol
from the DEFINE symbol table.
3.all> DEFINE/PROCESS_SET A = B,C,D
all> DEFINE/PROCESS_SET B = E,F,G
all> DEFINE/PROCESS_SET E = I,J,A
%DEBUG-E-NORECSYM, recursive PROCESS_SET symbol definition
encountered at or near "A"
This series of DEFINE/PROCESS_SET commands illustrate valid and
invalid uses of the command.
2 DELETE
Deletes a symbol definition that was established with the DEFINE
command.
Format
DELETE [symbol-name[, . . . ]]
3 Parameters
symbol-name
Specifies a symbol whose definition is to be deleted from the
DEFINE symbol table. Do not use the asterisk (*) wildcard
character. Instead, use the /ALL qualifier. Do not specify a
symbol name with /ALL. If you use the /LOCAL qualifier, the
symbol specified must have been previously defined with the
DEFINE/LOCAL command. If you do not specify /LOCAL, the symbol
specified must have been previously defined with the DEFINE
command without /LOCAL.
3 Qualifiers
/ALL
Deletes all global DEFINE definitions. Using /ALL/LOCAL deletes
all local DEFINE definitions associated with the current command
procedure (but not the global DEFINE definitions).
/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.
3 Description
The DELETE command deletes either a global DEFINE symbol or a
local DEFINE symbol. A global DEFINE symbol is defined with the
DEFINE command without the /LOCAL qualifier. A local DEFINE
symbol is defined in a debugger command procedure with the
DEFINE/LOCAL command, so that its definition is confined to that
command procedure.
Related commands:
DECLARE
DEFINE
SHOW DEFINE
SHOW SYMBOL/DEFINED
3 Examples
1.DBG> DEFINE X = INARR, Y = OUTARR
DBG> DELETE X,Y
In this example, the DEFINE command defines X and Y as global
symbols corresponding to INARR and OUTARR, respectively. The
DELETE command deletes these two symbol definitions from the
global symbol table.
2.DBG> DELETE/ALL/LOCAL
This command deletes all local symbol definitions from the
current command procedure.
3 /KEY
Deletes a key definition that was established with the DEFINE/KEY
command or, by default, by the debugger.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
DELETE/KEY [key-name]
4 Parameters
key-name
Specifies a key whose definition is to be deleted. Do not use
the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify a key name with /ALL. Valid key names
are as follows:
Key LK201
Name Keyboard VT100-type VT52-type
PF1 PF1 PF1 Blue
PF2 PF2 PF2 Red
PF3 PF3 PF3 Black
PF4 PF4 PF4
KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9
PERIOD Keypad Keypad
period (.) period (.)
COMMA Keypad comma Keypad comma
(,) (,)
ENTER Enter ENTER ENTER
E1 Find
E2 Insert Here
E3 Remove
E4 Select
E5 Prev Screen
E6 Next Screen
HELP Help
DO Do
F6-F20 F6-F20
4 Qualifiers
/ALL
Deletes all key definitions in the specified state. If you do
not specify a state, all key definitions in the current state are
deleted. To specify one or more states, use /STATE=state-name.
/LOG
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the
specified key definitions have been deleted. The /LOG qualifier
(which is the default) displays the message. The /NOLOG qualifier
suppresses the message.
/STATE
/STATE=(state-name [, . . . ])
/NOSTATE (default)
Selects one or more states for which a key definition is to be
deleted. The /STATE qualifier deletes key definitions for the
specified states. You can specify predefined key states, such as
DEFAULT and GOLD, or user-defined states. A state name can be any
appropriate alphanumeric string. The /NOSTATE qualifier deletes
the key definition for the current state only.
By default, the current key state is the DEFAULT state. The
current state can be changed with the SET KEY/STATE command,
or by pressing a key that causes a state change (a key that was
defined with DEFINE/KEY/LOCK_STATE/SET_STATE).
4 Description
The DELETE/KEY command is like the DCL command DELETE/KEY.
Keypad mode must be enabled (SET MODE KEYPAD) before you can use
this command. Keypad mode is enabled by default.
Related commands:
DEFINE/KEY
(SET,SHOW) KEY
4 Examples
1.DBG> DELETE/KEY KP4
%DEBUG-I-DELKEY, DEFAULT key KP4 has been deleted
This command deletes the key definition for KP4 in the state
last set by the SET KEY command (by default, this is the
DEFAULT state).
2.DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA
%DEBUG-I-DELKEY, BLUE key COMMA has been deleted
%DEBUG-I-DELKEY, RED key COMMA has been deleted
This command deletes the key definition for the COMMA key in
the BLUE and RED states.
2 DEPOSIT
Changes the value of a program variable. More generally, deposits
a new value at the location denoted by an address expression.
Format
DEPOSIT address-expression = language-expression
3 Parameters
address-expression
Specifies the location into which the value of the language
expression is to be deposited. With high-level languages, this
is typically the name of a variable and can include a path name
to specify the variable uniquely. More generally, an address
expression can also be a memory address or a register and can
be composed of numbers (offsets) and symbols, as well as one or
more operators, operands, or delimiters. For information about
the debugger symbols for the registers and about the operators
you can use in address expressions, see the Built_in_Symbols and
Address_Expressions help topics.
You cannot specify an entire aggregate variable (a composite data
structure such as an array or a record). To specify an individual
array element or a record component, follow the syntax of the
current language.
language-expression
Specifies the value to be deposited. You can specify any language
expression that is valid in the current language. For most
languages, the expression can include the names of simple
(noncomposite, single-valued) variables but not the names
of aggregate variables (such as arrays or records). If the
expression contains symbols with different compiler-generated
types, the debugger uses the rules of the current language to
evaluate the expression.
If the expression is an ASCII string or an assembly-language
instruction, you must enclose it in quotation marks (") or
apostrophes ('). If the string contains quotation marks or
apostrophes, use the other delimiter to enclose the string.
If the string has more characters (1-byte ASCII) than can fit
into the program location denoted by the address expression,
the debugger truncates the extra characters from the right. If
the string has fewer characters, the debugger pads the remaining
characters to the right of the string by inserting ASCII space
characters.
3 Qualifiers
/ASCIC
/ASCIC
/AC
Deposits a counted ASCII string into the specified location. You
must specify a quoted string on the right-hand side of the equal
sign. The deposited string is preceded by a 1-byte count field
that gives the length of the string.
/ASCID
/ASCID
/AD
Deposits an ASCII string into the address given by a string
descriptor that is at the specified location. You must specify
a quoted string on the right-hand side of the equal sign. The
specified location must contain a string descriptor. If the
string lengths do not match, the string is either truncated on
the right or padded with space characters on the right.
/ASCII
/ASCII:n
Deposits n bytes of an ASCII string into the specified location.
You must specify a quoted string on the right-hand side of the
equal sign. If its length is not n, the string is truncated or
padded with space characters on the right. If you omit n, the
actual length of the data item at the specified location is used.
/ASCIW
/ASCIW
/AW
Deposits a counted ASCII string into the specified location. You
must specify a quoted string on the right-hand side of the equal
sign. The deposited string is preceded by a 2-byte count field
that gives the length of the string.
/ASCIZ
/ASCIZ
/AZ
Deposits a zero-terminated ASCII string into the specified
location. You must specify a quoted string on the right-hand
side of the equal sign. The deposited string is terminated by a
zero byte that indicates the end of the string.
/BYTE
Deposits a 1-byte integer into the specified location.
/D_FLOAT
Converts the expression on the right-hand side of the equal sign
to the D_floating type (length 8 bytes) and deposits the result
into the specified location.
/DATE_TIME
Converts a string representing a date and time (for example,
21-DEC-1988 21:08:47.15) to the internal format for date and
time and deposits that value (length 8 bytes) into the specified
location. Specify an absolute date and time in the following
format:
[dd-mmm-yyyy[:]] [hh:mm:ss.cc]
/EXTENDED_FLOAT
/EXTENDED_FLOAT
/X_FLOAT
(Alpha only) Converts the expression on the right-hand side of
the equal sign to the IEEE X_floating type (length 16 bytes) and
deposits the result into the specified location.
/FLOAT
On VAX processors, converts the expression on the right-hand side
of the equal sign to the F_floating type (length 4 bytes) and
deposits the result into the specified location.
On Alpha processors, converts the expression on the right-hand
side of the equal sign to the IEEE T_floating type (double
precision, length 8 bytes) and deposits the result into the
specified location.
/F_FLOAT
(VAX only) Converts the expression on the right-hand side of the
equal sign to the F_floating type (length 4 bytes) and deposits
the result into the specified location.
/G_FLOAT
Converts the expression on the right-hand side of the equal sign
to the G_floating type (length 8 bytes) and deposits the result
into the specified location.
/H_FLOAT
(VAX only) Converts the expression on the right-hand side of the
equal sign to the H_floating type (length 16 bytes) and deposits
the result into the specified location.
/INSTRUCTION
(VAX only) Deposits an instruction into the specified location.
The expression on the right-hand side of the equal sign must be a
quoted string representing an assembly-language instruction.
/LONG_FLOAT
/LONG_FLOAT
/S_FLOAT
(Alpha only) Converts the expression on the right-hand side of
the equal sign to the IEEE S_floating type (single precision,
length 4 bytes) and deposits the result into the specified
location.
/LONG_LONG_FLOAT
/LONG_LONG_FLOAT
/T_FLOAT
(Alpha only) Converts the expression on the right-hand side of
the equal sign to the IEEE T_floating type (double precision,
length 8 bytes) and deposits the result into the specified
location.
/LONGWORD
Deposits a longword integer (length 4 bytes) into the specified
location.
/OCTAWORD
Deposits an octaword integer (length 16 bytes) into the specified
location.
/PACKED
/PACKED:n
Converts the expression on the right-hand side of the equal sign
to a packed decimal representation and deposits the resulting
value into the specified location. The value of n is the number
of decimal digits. Each digit occupies one nibble (4 bits).
/QUADWORD
Deposits a quadword integer (length 8 bytes) into the specified
location.
/S_FLOAT
/S_FLOAT
/LONG_FLOAT
(Alpha only) Converts the expression on the right-hand side of
the equal sign to the IEEE S_floating type (single precision,
length 4 bytes) and deposits the result into the specified
location.
/TASK
Applies to tasking (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.
/T_FLOAT
(Alpha only) Converts the expression on the right-hand side of
the equal sign to the IEEE T_floating type (double precision,
length 8 bytes) and deposits the result into the specified
location.
/TYPE
/TYPE=(name)
Converts the expression to be deposited to the type denoted by
name (which must be the name of a variable or data type declared
in the program), then deposits the resulting value into the
specified location. This enables you to specify a user-declared
type. You must use parentheses around the type expression.
/WCHAR_T
/WCHAR_T[:n]
Deposits up to n longwords (n characters) of a converted
multibyte file code sequence into the specified location. The
default is 1 longword. You must specify a string on the right-
hand side of the equal sign.
When converting the specified string, the debugger uses the
locale database of the process in which the debugger runs. The
default is C locale.
/WORD
Deposits a word integer (length 2 bytes) into the specified
location.
/X_FLOAT
(Alpha only) Converts the expression on the right-hand side of
the equal sign to the IEEE X_floating type (length 16 bytes) and
deposits the result into the specified location.
3 Description
You can use the DEPOSIT command to change the contents of any
memory location or register that is accessible in your program.
For high-level languages the command is used mostly to change the
value of a variable (an integer, real, string, array, record, and
so on).
The DEPOSIT command is like an assignment statement in most
programming languages. The value of the expression specified to
the right of the equal sign is assigned to the variable or other
location specified to the left of the equal sign. For Ada and
Pascal, you can use ":=" instead of "=" in the command syntax.
The debugger recognizes the compiler-generated types associated
with symbolic address expressions (symbolic names declared in
your program). Symbolic address expressions include the following
entities:
o Variable names. When specifying a variable with the DEPOSIT
command, use the same syntax that is used in the source code.
o Routine names, labels, and line numbers. On VAX systems, these
are associated with instructions. You can deposit instructions
using basically the same techniques as when depositing into
string variables. However, you must also use the /INSTRUCTION
qualifier or first enter a SET TYPE INSTRUCTION or SET
TYPE/OVERRIDE INSTRUCTION command.
In general, when you enter a DEPOSIT command, the debugger takes
the following actions:
o It evaluates the address expression specified to the left of
the equal sign, to yield a program location.
o If the program location has a symbolic name, the debugger
associates the location with the symbol's compiler-generated
type. If the location does not have a symbolic name (and,
therefore, no associated compiler-generated type) the debugger
associates the location with the type longword integer by
default. This means that, by default, you can deposit integer
values that do not exceed 4 bytes into these locations.
o It evaluates the language expression specified to the right of
the equal sign, in the syntax of the current language and in
the current radix, to yield a value. The current language is
the language last established with the SET LANGUAGE command.
By default, if you did not enter a SET LANGUAGE command, the
current language is the language of the module containing the
main program.
o It checks that the value and type of the language expression
is consistent with the type of the address expression. If
you try to deposit a value that is incompatible with the type
of the address expression, the debugger issues a diagnostic
message. If the value is compatible, the debugger deposits the
value into the location denoted by the address expression.
3 Description,_Continued...
The debugger might do type conversion during a deposit operation
if the language rules allow it. For example, a real value
specified to the right of the equal sign might be converted to
an integer value if it is being deposited into a location with
an integer type. In general, the debugger tries to follow the
assignment rules for the current language.
There are several ways of changing the type associated with a
program location so that you can deposit data of a different type
into that location:
o To change the default type for all locations that do not have
a symbolic name, you can specify a new type with the SET TYPE
command.
o To change the default type for all locations (both those that
do and do not have a symbolic name), you can specify a new
type with the SET TYPE/OVERRIDE command.
o To override the type currently associated with a particular
location for the duration of a single DEPOSIT command, you
can specify a new type by using a qualifier (/ASCII:n, /BYTE,
/TYPE=(name), and so on).
When debugging a C program, or a program in any case-specific
language, you cannot use the DEPOSIT/TYPE command if the type
specified is a mixed or lowercase name. For example, suppose the
program has a function like the following:
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"
The debugger can interpret and display integer data in any one
of four radixes: binary, decimal, hexadecimal, and octal. The
default radix for both data entry and display is decimal for most
languages.
On VAX processors, the exceptions are BLISS and MACRO-32, which
have a default radix of hexadecimal. On Alpha processors, the
exceptions are BLISS, MACRO-32, and MACRO-64, which have a
default radix of hexadecimal.
You can use the SET RADIX and SET RADIX/OVERRIDE commands to
change the default radix.
The DEPOSIT command sets the current entity built-in symbols
%CURLOC and period (.) to the location denoted by the address
expression specified. Logical predecessors (%PREVLOC or the
circumflex character (^)) and successors (%NEXTLOC) are based
on the value of the current entity.
Related commands:
CANCEL TYPE/OVERRIDE
EVALUATE
EXAMINE
MONITOR
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
3 Examples
1.DBG> DEPOSIT I = 7
This command deposits the value 7 into the integer variable I.
2.DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 24.80
This command deposits the value of the expression CURRENT_WIDTH
+ 24.80 into the real variable WIDTH.
3.DBG> DEPOSIT STATUS = FALSE
This command deposits the value FALSE into the Boolean variable
STATUS.
4.DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84"
This command deposits the string WG-7619.3-84 into the string
variable PART_NUMBER.
5.DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172
This command deposits the value 02172 into component ZIPCODE of
record EMPLOYEE.
6.DBG> DEPOSIT ARR(8) = 35
DBG> DEPOSIT ^ = 14
In this example, the first DEPOSIT command deposits the value
35 into element 8 of array ARR. As a result, element 8 becomes
the current entity. The second command deposits the value 14
into the logical predecessor of element 8, namely element 7.
7.DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = 0)
This command deposits the value 0 into elements 1 to 4 of array
ARR.
8.DBG> DEPOSIT COLOR = 3
%DEBUG-E-OPTNOTALLOW, operator "DEPOSIT" not allowed on
given data type
The debugger alerts you when you try to deposit data of the
wrong type into a variable (in this case, if you try to deposit
an integer value into an enumerated type variable). The E
(error) message severity indicates that the debugger does not
make the assignment.
9.DBG> DEPOSIT VOLUME = - 100
%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds
at or near '-'
The debugger alerts you when you try to deposit an out-of-
bounds value into a variable (in this case a negative value).
The I (informational) message severity indicates that the
debugger does make the assignment.
10DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555
This command deposits the expression 111222333444555 into
location BIGINT and converts it to an octaword integer.
11DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35
This command converts 1.11949*10**35 to an F_floating type
value and deposits it into location BIGFLT.
2 DISABLE
3 AST
Disables the delivery of asynchronous system traps (ASTs) in your
program.
Format
DISABLE AST
4 Description
The DISABLE AST command disables the delivery of ASTs in your
program and thereby prevents interrupts from occurring while the
program is running. If ASTs are delivered while the debugger is
running (processing commands, and so on), they are queued and are
delivered when control is returned to the program.
The ENABLE AST command reenables the delivery of ASTs, including
any pending ASTs (ASTs waiting to be delivered).
NOTE
Any call by your program to the $SETAST system service that
enables ASTs overrides a previous DISABLE AST command.
Related commands:
(ENABLE,SHOW) AST
4 Example
DBG> DISABLE AST
DBG> SHOW AST
ASTs are disabled
DBG>
The DISABLE AST command disables the delivery of ASTs in your
program, as confirmed by the SHOW AST command.
2 DISCONNECT
Releases a process from debugger control without terminating the
process (kept debugger only).
Format
DISCONNECT process-spec
3 Parameters
process-spec
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
3 Description
(Kept debugger only.) The DISCONNECT command releases a specified
process from debugger control without terminating the process.
This is useful if, for example, you have brought a running
program under debugger control with a CONNECT command and you now
want to release it without terminating the image. (In contrast,
when you specify a process with the EXIT or QUIT command, the
process is terminated.)
CAUTION
The debugger kernel runs in the same process as the image
being debugged. If you issue the DISCONNECT command for this
process, you release your process, but the kernel remains
activated.
This activation continues until the program image finishes
running.
If you install a new version of the debugger while one or
more disconnected but activated kernels inhabit user program
space, you can experience problems with debugger behavior if
you try to reconnect to one of those kernels.
Related commands:
EXIT
QUIT
CONNECT
3 Example
DBG> DISCONNECT JONES
This command releases process JONES from debugger control
without terminating the process.
2 DISPLAY
Creates a new screen display or modifies an existing display.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
DISPLAY display-name [AT window-spec] [display-kind] [, . . . ]
3 Parameters
display-name
Specifies 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 entities:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
o A display built-in symbol:
%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
Specifies the screen window at which the display is to be
positioned. You can specify any of the following entities:
o A predefined window. For example, RH1 (right top half).
o A window definition previously established 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 can be based on the built-in symbols %PAGE
and %WIDTH (for example, %WIDTH/4).
If you omit the window specification, the screen position depends
on whether you are specifying an existing display or a new
display:
o If you are specifying an existing display, the position of the
display is not changed.
o If you are specifying a new display, it is positioned at
window H1 or H2, alternating between H1 and H2 each time you
create another display.
display-kind
Specifies the display kind. Valid keywords are as follows:
DO Specifies an automatically updated output
(command[; . . . ]) display. The commands are executed 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, the commands must be separated by
semicolons.
INSTRUCTION Specifies an instruction display. If selected
as the current instruction display with the
SELECT/INSTRUCTION command, it displays the
output from subsequent EXAMINE/INSTRUCTION
commands.
INSTRUCTION (VAX only) Specifies an automatically updated
(command) instruction 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 displays 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 are specifying an existing display or a new
display:
o If you specify an existing display, the display kind is not
changed.
o If you specify a new display, an OUTPUT display is created.
3 Qualifiers
/CLEAR
Erases the entire contents of a specified display. Do not use
this qualifier with /GENERATE or when creating a new display.
/DYNAMIC
/DYNAMIC (default)
/NODYNAMIC
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 (/DYNAMIC), 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, it regenerates the contents of all
automatically generated displays. Do not use this qualifier with
/CLEAR or when creating a new display.
/HIDE
Places a specified display at the bottom of the display
pasteboard (same as /PUSH). 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
/MARK_CHANGE
/NOMARK_CHANGE (default)
Controls whether the lines that change in a DO display each time
it is automatically updated are marked. Not applicable to other
kinds of displays.
When you use /MARK_CHANGE, any lines in which some contents
have changed since the last time the display was updated are
highlighted in reverse video. This qualifier is particularly
useful when you want any variables in an automatically updated
display to be highlighted when they change.
The /NOMARK_CHANGE qualifier (default) specifies that any lines
that change in DO displays are not to be marked. This qualifier
cancels the effect of a previous /MARK_CHANGE on the specified
display.
/POP
/POP (default)
/NOPOP
Controls whether a specified display is placed at the top of the
display pasteboard, ahead of any other displays but behind the
PROMPT display. By default (/POP), the display is placed at the
top of the pasteboard and hides any other displays that share the
same region of the screen, except the PROMPT display.
The /NOPOP qualifier preserves the order of all displays on the
pasteboard (same as /NOPUSH).
/PROCESS
/PROCESS[=(process-spec)]
/NOPROCESS (default)
Used only when debugging multiprocess programs (kept debugger
only). Controls whether the specified display is process specific
(that is, whether 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 the PROMPT display.
The /PROCESS=(process-spec) qualifier causes the specified
display to be associated with the specified process. You must
include the parentheses. Use any of the following process-spec
forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
The /PROCESS qualifier causes the specified display to be
associated with the process that was the visible process when
the DISPLAY/PROCESS command was executed.
The /NOPROCESS qualifier (which is the default) causes the
specified display to be associated with the visible process,
which might change during program execution.
If you do not specify /PROCESS, the current process-specific
behavior (if any) of the specified display remains unchanged.
/PUSH
/PUSH
/NOPUSH
The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH
qualifier preserves the order of all displays on the pasteboard
(same as /NOPOP).
/REFRESH
Refreshes the terminal screen. Do not specify any command
parameters with this qualifier. You can also use Ctrl/W to
refresh the screen.
/REMOVE
Marks the display as being removed from the display pasteboard,
so it is not shown on the screen unless you explicitly request
it with another DISPLAY command. Although a removed display is
not visible on the screen, it still exists and its contents are
preserved. You cannot remove the PROMPT display.
/SIZE
/SIZE:n
Sets the maximum size of a display to n lines. If more than n
lines are written to the display, the oldest lines are lost as
the new lines are added. If you omit this qualifier, the maximum
size of the display is as follows:
o If you specify an existing display, the maximum size is
unchanged.
o If you are creating 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).
3 Description
You can use the DISPLAY command to create a display or to modify
an existing display.
To create a display, specify a name that is not already used as
a display name (the SHOW DISPLAY command identifies all existing
displays).
By default, the DISPLAY command places 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 a list of the key definitions associated with the DISPLAY
command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY
command to determine the current key definitions.
Related commands:
Ctrl/W
EXPAND
MOVE
SET PROMPT
(SET,SHOW) TERMINAL
(SET,SHOW,CANCEL) WINDOW
SELECT
(SHOW,CANCEL) DISPLAY
3 Examples
1.DBG> DISPLAY REG
This command shows the predefined register display, REG, at its
current window location.
2.DBG> DISPLAY/PUSH INST
This command pushes display INST to the bottom of the display
pasteboard, behind all other displays.
3.DBG> DISPLAY NEWDISP AT RT2
DBG> SELECT/INPUT NEWDISP
In this example, the DISPLAY command 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
In this example, the DISPLAY command creates a display named
DISP2 essentially at the right bottom half of the screen, above
the PROMPT display, which is located at S6. This is an output
display by default. The SELECT/OUTPUT command then selects
DISP2 as the current output display.
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)
This command creates a DO display named CALLS at window Q3.
Each time the debugger gains control from the program, the
SHOW CALLS command is executed and the output is displayed in
display CALLS, replacing any previous contents.
7.DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C)
This command creates a DO display named EXAM at window Q2.
The display shows the current values of variables A, B, and C
whenever the debugger prompts for input. Any changed values are
highlighted.
8.all> DISPLAY/PROCESS OUT_X AT S4
This command makes display OUT_X specific to the visible
process (process 3) and puts the display at window S4.
2 DUMP
Displays the contents of memory.
Format
DUMP address-expression1 [:address-expression2]
3 Parameters
address-expression1
Specifies the first memory location to be displayed.
address-expression2
Specifies the last memory location to be displayed (default is
address-expression1).
3 Qualifiers
/BINARY
Displays each examined entity as a binary integer.
/BYTE
Displays each examined entity as a byte integer (length 1 byte).
/DECIMAL
Displays each examined entity as a decimal integer.
/HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
/LONGWORD
/LONGWORD (default)
Displays each examined entity in the longword integer type
(length 4 bytes). This is the default type for program locations
that do not have a compiler-generated type.
/OCTAL
Displays each examined entity as an octal integer.
/QUADWORD
Displays each examined entity in the quadword integer type
(length 8 bytes).
/WORD
Displays each examined entity in the word integer type (length 2
bytes).
3 Description
The DUMP command displays the contents of memory, including
registers, variables, and arrays. The DUMP command formats its
output in a manner similar to the DCL command DUMP. The debugger
DUMP command makes no attempt to interpret the structure of
aggregates.
In general, when you enter a DUMP command, the debugger evaluates
address-expression1 to yield a program location. The debugger
then displays the entity stored at that location as follows:
o If the entity has a symbolic name, the debugger uses the size
of the entity to determine the address range to display.
o If the entity does not have a symbolic name (and, therefore,
no associated compiler-generated type) the debugger
displays address-expression1 through address-expression2 (if
specified).
In either case, the DUMP command displays the contents of these
locations as longword (by default) integer values in the current
radix.
The default radix for display is decimal for most languages.
On VAX processors, the exceptions are BLISS and MACRO-32, which
have a default radix of hexadecimal. On Alpha processors, the
exceptions are BLISS, MACRO-32, and MACRO-64, which have a
default radix of hexadecimal.
Use one of the four radix qualifiers (/BINARY, /DECIMAL,
/HEXADECIMAL, /OCTAL) to display data in another radix. You can
also use the SET RADIX and SET RADIX/OVERRIDE commands to change
the default radix.
Use one of the size qualifiers (/BYTE, /WORD, /LONGWORD,
/QUADWORD) to change the format of the display.
The DUMP command sets the current entity built-in symbols %CURLOC
and period (.) to the location denoted by the address expression
specified. Logical predecessors (%PREVLOC or the circumflex
character (^)) and successors (%NEXTLOC) are based on the value
of the current entity.
Related command:
EXAMINE
3 Examples
1.DBG> DUMP/QUAD R16:R25
0000000000000078 0000000000030038 8.......x....... %R16
000000202020786B 0000000000030041 A.......kx ... %R18
0000000000030140 0000000000007800 .x......@....... %R20
0000000000010038 0000000000000007 ........8....... %R22
0000000000000006 0000000000000000 ................ %R24
DBG>
This command displays general registers R16 through R25 in
quadword format and hexadecimal radix.
2.DBG> DUMP/BYTE/DECIMAL 30000:30040
0 0 0 0 0 3 0 -80 °....... 0000000000030000
0 0 0 0 0 3 1 64 @....... 0000000000030008
0 0 0 0 0 3 0 48 0....... 0000000000030010
0 0 0 0 0 3 0 56 8....... 0000000000030018
0 0 0 0 0 3 0 -64 À....... 0000000000030020
0 0 0 0 0 3 0 -80 °....... 0000000000030028
0 0 0 0 0 0 7 -50 Î....... 0000000000030030
101 101 119 32 116 120 101 110 next wee 0000000000030038
107 k 0000000000030040
DBG>
This command displays locations 30000 through 30040 in byte
format and decimal radix.
2 EDIT
Starts the editor established with the SET EDITOR command. If
you did not enter a SET EDITOR command, starts the DEC Language-
Sensitive Editor (LSEDIT), if that editor is installed on your
system.
Format
EDIT [[module-name\] line-number]
3 Parameters
module-name
Specifies the name of the module whose source file is to be
edited. If you specify a module name, you must also specify a
line number. If you omit the module name parameter, the source
file whose code appears in the current source display is chosen
for editing.
line-number
A positive integer that specifies the source line on which the
editor's cursor is initially placed. If you omit this parameter,
the cursor is initially positioned at the beginning of the source
line that is centered in the debugger's current source display,
or at the beginning of line 1 if the editor was set to /NOSTART_
POSITION (see the SET EDITOR command.)
3 Qualifiers
/EXIT
/EXIT
/NOEXIT (default)
Controls whether you end the debugging session prior to starting
the editor. If you specify /EXIT, the debugging session is
terminated and the editor is then started. If you specify
/NOEXIT, the editing session is started and you return to your
debugging session after terminating the editing session.
3 Description
If you have not specified an editor with the SET EDITOR command,
the EDIT command starts the DEC Language-Sensitive Editor
(LSEDIT) in a spawned subprocess (if LSEDIT is installed on your
system). The typical (default) way to use the EDIT command is
not to specify any parameters. In this case, the editing cursor
is initially positioned at the beginning of the line that is
centered in the currently selected debugger source display (the
current source display).
The SET EDITOR command provides options for starting different
editors, either in a subprocess or through a callable interface.
Related commands:
(SET,SHOW) EDITOR
(SET,SHOW,CANCEL) SOURCE
3 Examples
1.DBG> EDIT
This command spawns the DEC Language-Sensitive Editor (LSEDIT)
in a subprocess to edit the source file whose code appears in
the current source display. The editing cursor is positioned
at the beginning of the line that was centered in the source
display.
2.DBG> EDIT SWAP\12
This command spawns the DEC Language-Sensitive Editor (LSEDIT)
in a subprocess to edit the source file containing the module
SWAP. The editing cursor is positioned at the beginning of
source line 12.
3.DBG> SET EDITOR/CALLABLE_EDT
DBG> EDIT
In this example, the SET EDITOR/CALLABLE_EDT command
establishes that EDT is the default editor and is started
through its callable interface (rather than spawned in a
subprocess). The EDIT command starts EDT to edit the source
file whose code appears in the current source display. The
editing cursor is positioned at the beginning of source line 1,
because the default qualifier /NOSTART_POSITION applies to EDT.
2 ENABLE
3 AST
Enables the delivery of asynchronous system traps (ASTs) in your
program.
Format
ENABLE AST
4 Description
The ENABLE AST command enables the delivery of ASTs while your
program is running, including any pending ASTs (ASTs waiting
to be delivered). If ASTs are delivered while the debugger is
running (processing commands, and so on), they are queued and are
delivered when control is returned to the program. Delivery of
ASTs in your program is initially enabled by default.
NOTE
Any call by your program to the $SETAST system service that
disables ASTs overrides a previous ENABLE AST command.
Related commands:
(DISABLE,SHOW) AST
4 Example
DBG> ENABLE AST
DBG> SHOW AST
ASTs are enabled
DBG>
The ENABLE AST command enables the delivery of ASTs in your
program, as confirmed with the SHOW AST command.
2 EVALUATE
Displays the value of a language expression in the current
language (by default, the language of the module containing the
main program).
Format
EVALUATE language-expression[, . . . ]
3 Parameters
language-expression
Specifies any valid expression in the current language.
3 Qualifiers
/BINARY
Specifies that the result be displayed in binary radix.
/CONDITION_VALUE
Specifies that the expression be interpreted as a condition
value (the kind of condition value you would specify using the
condition-handling mechanism). The message text corresponding to
that condition value is then displayed. The specified value must
be an integer value.
/DECIMAL
Specifies that the result be displayed in decimal radix.
/HEXADECIMAL
Specifies that the result be displayed in hexadecimal radix.
/OCTAL
Specifies that the result be displayed in octal radix.
3 Description
The debugger interprets the expression specified in an EVALUATE
command as a language expression, evaluates it in the syntax of
the current language and in the current radix, and displays its
value as a literal (for example, an integer value) in the current
language.
The current language is the language last established with
the SET LANGUAGE command. If you did not enter a SET LANGUAGE
command, the current language is, by default, the language of the
module containing the main program.
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.
The debugger can interpret and display integer data in any one
of four radixes: binary, decimal, hexadecimal, and octal. The
current radix is the radix last established with the SET RADIX
command.
If you did not enter a SET RADIX command, the default radix for
both data entry and display is decimal for most languages. On VAX
processors, the exceptions are BLISS and MACRO-32, which have a
default radix of hexadecimal. On Alpha processors, the exceptions
are BLISS, MACRO-32, and MACRO-64, which have a default radix of
hexadecimal.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to
display integer data in another radix. These qualifiers do not
affect how the debugger interprets the data you specify; they
override the current output radix, but not the input radix.
The EVALUATE command sets the current value of built-in symbols
%CURVAL and backslash (\) to the value denoted by the specified
expression.
You cannot evaluate a language expression that includes a
function call. For example, if PRODUCT is a function that
multiplies two integers, you cannot use the command EVALUATE
PRODUCT(3,5). If your program assigns the returned value
of a function to a variable, you can examine the resulting
value of that variable. On Alpha processors, the command
EVALUATE procedure-name displays the procedure descriptor address
(not the code address) of a specified routine, entry point, or
Ada package.
For more information about debugger support for language-specific
operators and constructs, see the Language_Support Help topic.
Related commands:
EVALUATE/ADDRESS
MONITOR
(SET,SHOW) LANGUAGE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
3 Examples
1.DBG> EVALUATE 100.34 * (14.2 + 7.9)
2217.514
DBG>
This command uses the debugger as a calculator by multiplying
100.34 by (14.2 + 7.9).
2.DBG> EVALUATE/OCTAL X
00000001512
DBG>
This command evaluates the symbol X and displays the result in
octal radix.
3.DBG> EVALUATE TOTAL + CURR_AMOUNT
8247.20
DBG>
This command evaluates the sum of the values of two real
variables, TOTAL and CURR_AMOUNT.
4.DBG> DEPOSIT WILLING = TRUE
DBG> DEPOSIT ABLE = FALSE
DBG> EVALUATE WILLING AND ABLE
False
DBG>
In this example, the EVALUATE command evaluates the logical
AND of the current values of two Boolean variables, WILLING and
ABLE.
5.DBG> EVALUATE COLOR'FIRST
RED
DBG>
In this Ada example, this command evaluates the first element
of the enumeration type COLOR.
3 /ADDRESS
Evaluates an address expression and displays the result as a
memory address or a register name.
Format
EVALUATE/ADDRESS address-expression[, . . . ]
4 Parameters
address-expression
Specifies an address expression of any valid form (for example, a
routine name, variable name, label, line number, and so on).
4 Qualifiers
/BINARY
Displays the memory address in binary radix.
/DECIMAL
Displays the memory address in decimal radix.
/HEXADECIMAL
Displays the memory address in hexadecimal radix.
/OCTAL
Displays the memory address in octal radix.
4 Description
The EVALUATE/ADDRESS command enables you to determine the memory
address or register associated with an address expression.
The debugger can interpret and display integer data in any one
of four radixes: binary, decimal, hexadecimal, and octal. The
default radix for both data entry and display is decimal for
most languages. On VAX processors, the exceptions are BLISS and
MACRO-32, which have a default radix of hexadecimal. On Alpha
processors, the exceptions are BLISS, MACRO-32, and MACRO-64,
which have a default radix of hexadecimal.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to
display address values in another radix. These qualifiers do not
affect how the debugger interprets the data you specify; that is,
they override the current output radix, but not the input radix.
If the value of a variable is currently stored in a register
instead of memory, the EVALUATE/ADDRESS command identifies the
register. The radix qualifiers have no effect in that case.
The EVALUATE/ADDRESS command sets the current entity built-in
symbols %CURLOC and period (.) to the location denoted by the
address expression specified. Logical predecessors (%PREVLOC
or the circumflex character (^)) and successors (%NEXTLOC) are
based on the value of the current entity.
On Alpha processors, the command EVALUATE/ADDRESS procedure-name
displays the procedure descriptor address (not the code address)
of a specified routine, entry point, or Ada package.
Related commands:
EVALUATE
(SET,SHOW,CANCEL) RADIX
SHOW SYMBOL/ADDRESS
SYMBOLIZE
4 Examples
1.DBG> EVALUATE/ADDRESS MODNAME\%LINE 110
3942
DBG>
This command displays the memory address denoted by the address
expression MODNAME\%LINE 110.
2.DBG> EVALUATE/ADDRESS/HEX A,B,C
000004A4
000004AC
000004A0
DBG>
This command displays the memory addresses denoted by the
address expressions A, B, and C in hexadecimal radix.
3.DBG> EVALUATE/ADDRESS X
MOD3\%R1
DBG>
This command indicates that variable X is associated with
register R1. X is a nonstatic (register) variable.
2 EXAMINE
Displays the current value of a program variable. More
generally, displays the value of the entity denoted by an address
expression.
Format
EXAMINE [address-expression[:address-expression] [, . . . ]]
3 Parameters
address-expression
Specifies an entity to be examined. With high-level languages,
this is typically the name of a variable and can include a path
name to specify the variable uniquely. More generally, an address
expression can also be a memory address or a register and can
be composed of numbers (offsets) and symbols, as well as one or
more operators, operands, or delimiters. For information about
the debugger symbols for the registers and about the operators
you can use in address expressions, type Help Built_in_Symbols or
Help Address_Expressions.
If you specify the name of an aggregate variable (a composite
data structure such as an array or record structure) the debugger
displays the values of all elements. For an array, the display
shows the subscript (index) and value of each array element. For
a record, the display shows the name and value of each record
component.
To specify an individual array element, array slice, or record
component, follow the syntax of the current language.
If you specify a range of entities, the value of the address
expression that denotes the first entity in the range must
be less than the value of the address expression that denotes
the last entity in the range. The debugger displays the entity
specified by the first address expression, the logical successor
of that address expression, the next logical successor, and so
on, until it displays the entity specified by the last address
expression. You can specify a list of ranges by separating ranges
with a comma.
For information specific to vector registers and vector
instructions, see /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers.
3 Qualifiers
/ASCIC
/ASCIC
/AC
Interprets each examined entity as a counted ASCII string
preceded by a 1-byte count field that gives the length of the
string. The string is then displayed.
/ASCID
/ASCID
/AD
Interprets each examined entity as the address of a string
descriptor pointing to an ASCII string. The CLASS and DTYPE
fields of the descriptor are not checked, but the LENGTH and
POINTER fields provide the character length and address of the
ASCII string. The string is then displayed.
/ASCII
/ASCII:n
Interprets and displays each examined entity as an ASCII string
of length n bytes (n characters). If you omit n, the debugger
attempts to determine a length from the type of the address
expression.
/ASCIW
/ASCIW
/AW
Interprets each examined entity as a counted ASCII string
preceded by a 2-byte count field that gives the length of the
string. The string is then displayed.
/ASCIZ
/ASCIZ
/AZ
Interprets each examined entity as a zero-terminated ASCII
string. The ending zero byte indicates the end of the string.
The string is then displayed.
/BINARY
Displays each examined entity as a binary integer.
/BYTE
Displays each examined entity in the byte integer type (length 1
byte).
/CONDITION_VALUE
Interprets each examined entity as a condition-value return
status and displays the message associated with that return
status.
/D_FLOAT
Displays each examined entity in the D_floating type (length 8
bytes).
/DATE_TIME
Interprets each examined entity as a quadword integer (length 8
bytes) containing the internal representation of date and time.
Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc.
/DECIMAL
Displays each examined entity as a decimal integer.
/DEFAULT
Displays each examined entity in the default radix.
The minimum abbreviation is /DEFA.
/DEFINITIONS
/DEFINITIONS=n
(Alpha only) When the code is optimized, displays n definition
points for a split-lifetime variable. A definition point
is a location in the program where the variable could have
received its value. By default, up to five definition points are
displayed. If more than the given number of definitions (explicit
or default) are available, then the number of additional
definitions is reported as well. (For more information on split-
lifetime variables, see OpenVMS Debugger Manual.)
The minimum abbreviation is /DEFI.
/EXTENDED_FLOAT
/EXTENDED_FLOAT
/X_FLOAT
(Alpha only) Displays each examined entity in the IEEE X_floating
type (length 16 bytes).
/FLOAT
On VAX processors, same as /F_FLOAT. Displays each examined
entity in the F_floating type (length 4 bytes).
On Alpha processors, same as T_FLOAT. Displays each examined
entity in the IEEE T_floating type (double precision, length 8
bytes).
/F_FLOAT
(VAX only) Displays each examined entity in the F_floating type
(length 4 bytes).
/FPCR
(Alpha only) Displays each examined entity in FPCR (floating-
point control register) format.
/FMASK
/FMASK[=(mask-address-expression)]
Applies only to VAX vectorized programs. See the /TMASK
qualifier.
/G_FLOAT
Displays each examined entity in the G_floating type (length 8
bytes).
/H_FLOAT
(VAX only) Displays each examined entity in the H_floating type
(length 16 bytes).
/HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
/INSTRUCTION
Displays each examined entity as an assembly-language instruction
(variable length, depending on the number of instruction operands
and the kind of addressing modes used). See also the /OPERANDS
qualifier.
In screen mode, the output of an EXAMINE/INSTRUCTION command is
directed at the current instruction display, if any, not at an
output or DO display. The arrow in the instruction display points
to the examined instruction.
On Alpha processors, the command EXAMINE/INSTRUCTION procedure-
name displays the first instruction at the code address of a
specified routine, entry point, or Ada package.
/LINE
/LINE (default)
/NOLINE
Controls whether program locations are displayed in terms of line
numbers (%LINE x) or as routine-name + byte-offset. By default
(/LINE), the debugger symbolizes program locations in terms of
line numbers.
/LONG_FLOAT
/LONG_FLOAT
/S_FLOAT
(Alpha only) Displays each examined entity in the IEEE S_floating
type (single precision, length 4 bytes).
/LONG_LONG_FLOAT
/LONG_LONG_FLOAT
/T_FLOAT
(Alpha only) Displays each examined entity in the IEEE T_floating
type (double precision, length 8 bytes).
/LONGWORD
Displays each examined entity in the longword integer type
(length 4 bytes). This is the default type for program locations
that do not have a compiler-generated type.
/OCTAL
Displays each examined entity as an octal integer.
/OCTAWORD
Displays each examined entity in the octaword integer type
(length 16 bytes).
/OPERANDS
/OPERANDS[=keyword]
(VAX only) 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 enable you to 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 lets
you set a default level for the amount of operand information
displayed when examining instructions.
/PACKED
/PACKED:n
Interprets each examined entity as a packed decimal number. The
value of n is the number of decimal digits. Each digit occupies
one nibble (4 bits).
/PS
(Alpha only) Displays each examined entity in PS (processor
status register) format.
/PSL
(VAX only) Displays each examined entity in PSL (processor status
longword) format.
/PSW
(VAX only) Displays each examined entity in PSW (processor status
word) format. The /PSW qualifier is like /PSL except that only
the low-order word (2 bytes) is displayed.
/QUADWORD
Displays each examined entity in the quadword integer type
(length 8 bytes).
/S_FLOAT
(Alpha only) Displays each examined entity in the IEEE S_floating
type (single precision, length 4 bytes).
/SFPCR
(Alpha only) Displays each examined entity in SFPCR (software
floating-point control register) format.
/SOURCE
NOTE
This qualifier is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
Displays the source line corresponding to the location of each
examined entity. The examined entity must be associated with a
machine code instruction and, therefore, must be a line number, a
label, a routine name, or the memory address of an instruction.
The examined entity cannot be a variable name or any other
address expression that is associated with data.
In screen mode, the output of an EXAMINE/SOURCE command is
directed at the current source display, if any, not at an output
or DO display. The arrow in the source display points to the
source line associated with the last entity specified (or the
last one specified in a list of entities).
On Alpha processors, the command EXAMINE/SOURCE procedure-name
displays the source code at the code address of a specified
routine, entry point, or Ada package.
/SYMBOLIC
/SYMBOLIC (default)
/NOSYMBOLIC
Controls whether symbolization occurs. By default (/SYMBOLIC),
the debugger symbolizes all addresses, if possible; that is, it
converts numeric addresses into their symbolic representation.
If you specify /NOSYMBOLIC, the debugger suppresses symbolization
of entities you specify as absolute addresses. If you specify
entities as variable names, symbolization still occurs. The
/NOSYMBOLIC qualifier is useful if you are interested in
identifying numeric addresses rather than their symbolic names
(if symbolic names exist for those addresses). Using /NOSYMBOLIC
may speed up command processing because the debugger does not
need to convert numbers to names.
/TASK
Applies to tasking (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.
/T_FLOAT
(Alpha only) Displays each examined entity in the IEEE T_floating
type (double precision, length 8 bytes).
/TMASK
/TMASK[=(mask-address-expression)]
/FMASK[=(mask-address-expression)]
These qualifiers apply only to VAX vectorized programs. They
enable you to specify a mask in order 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
enable you to 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. That
is, the EXAMINE command is applied 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
/TYPE=(name)
Interprets and displays each examined entity according to the
type specified by name (which must be the name of a variable or
data type declared in the program). This enables you to specify
a user-declared type. You must use parentheses around the type
expression.
/VARIANT
/VARIANT=variant-selector address-expression
/VARIANT=(variant-selector,...) address-expression
Enables the debugger to display the correct item when it
encounters an anonymous variant.
In a C program, a union contains members, only one of which is
valid at any one time. When displaying a union, the debugger does
not know which member is currently valid.
In a PASCAL program, a record with a variant part contains
variants, only one of which is valid at any one time. When
displaying a record with an anonymous variant part, the debugger
does not know which variant is currently valid, and displays all
variants by default.
You can use the /VARIANT qualifier of the EXAMINE command to
select which member of a union (C) or anonymous variant (PASCAL)
to display.
/VMR
(VAX only) Applies only to VAX vectorized programs. Displays the
Vector Mask Register.
/WCHAR_T
/WCHAR_T[:n]
Interprets and displays each examined entity as a multibyte file
code sequence of length n longwords (n characters). The default
is 1 longword.
When converting the examined string, the debugger uses the locale
database of the process in which the debugger runs. The default
is C locale.
/WORD
Displays each examined entity in the word integer type (length 2
bytes).
/X_FLOAT
(Alpha only) Displays each examined entity in the IEEE X_floating
type (length 16 bytes).
3 Description
The EXAMINE command displays the entity at the location denoted
by an address expression. You can use the command to display the
contents of any memory location or register that is accessible
in your program. For high-level languages, the command is used
mostly to obtain the current value of a variable (an integer,
real, string, array, record, and so on).
If you are debugging optimized code on Alpha systems, the EXAMINE
command displays the definition points at which a split-lifetime
variable could have received its value. Split-lifetime variables
are discussed in OpenVMS Debugger Manual. By default, the
EXAMINE command displays up to five definition points. With the
/DEFINITIONS qualifier, you can specify the number of definition
points.
The debugger recognizes the compiler-generated types associated
with symbolic address expressions (symbolic names declared in
your program). Symbolic address expressions include the following
entities:
o Variable names. When specifying a variable with the EXAMINE
command, use the same syntax that is used in the source code.
o Routine names, labels, and line numbers. These are associated
with instructions. You can examine instructions using the same
techniques as when examining variables.
In general, when you enter an EXAMINE command, the debugger
evaluates the address expression specified to yield a program
location. The debugger then displays the value stored at that
location as follows:
o If the location has a symbolic name, the debugger formats the
value according to the compiler-generated type associated with
that symbol (that is, as a variable of a particular type or as
an instruction).
o If the location does not have a symbolic name (and, therefore,
no associated compiler-generated type) the debugger formats
the value in the type longword integer by default. This means
that, by default, the EXAMINE command displays the contents of
these locations as longword (4-byte) integer values.
For information specific to vector registers (VAX only) and
vector instructions (VAX only), see the /TMASK, /FMASK, /VMR,
and /OPERANDS qualifiers.
3 Description,_Continued...
There are several ways of changing the type associated with
a program location so that you can display the data at that
location in another data format:
o To change the default type for all locations that do not have
a symbolic name, you can specify a new type with the SET TYPE
command.
o To change the default type for all locations (both those that
do and do not have a symbolic name), you can specify a new
type with the SET TYPE/OVERRIDE command.
o To override the type currently associated with a particular
location for the duration of a single EXAMINE command, you can
specify a new type by using a type qualifier (/ASCII:n, /BYTE,
/TYPE=(name), and so on). Most qualifiers for the EXAMINE
command are type qualifiers.
The debugger can interpret and display integer data in any one of
four radixes: binary, decimal, hexadecimal, and octal.
The default radix for both data entry and display is decimal for
most languages. On VAX processors, the exceptions are BLISS and
MACRO-32, which have a default radix of hexadecimal. On Alpha
processors, the exceptions are BLISS, MACRO-32, and MACRO-64,
which have a default radix of hexadecimal.
The EXAMINE command has four radix qualifiers (/BINARY, /DECIMAL,
/HEXADECIMAL, /OCTAL) that enable you to display data in another
radix. You can also use the SET RADIX and SET RADIX/OVERRIDE
commands to change the default radix.
In addition to the type and radix qualifiers, the EXAMINE command
has qualifiers for other purposes:
o The /SOURCE qualifier enables you to identify the line of
source code corresponding to a line number, routine name,
label, or any other address expression that is associated with
an instruction rather than data.
o The /[NO]LINE and /[NO]SYMBOLIC qualifiers enable you to
control the symbolization of address expressions.
The EXAMINE command sets the current entity built-in symbols
%CURLOC and period (.) to the location denoted by the address
expression specified. Logical predecessors (%PREVLOC or the
circumflex character (^)) and successors (%NEXTLOC) are based
on the value of the current entity.
The /VARIANT qualifier enables the debugger to display the
correct item when it encounters an anonymous variant.
In a C program, a union contains members, only one of which is
valid at any one time. When displaying a union, the debugger does
not know which member is currently valid. In a PASCAL program,
a record with a variant part contains variants, only one of
which is valid at any one time. When displaying a record with an
anonymous variant part, the debugger does not know which variant
is currently valid, and displays all variants by default.
You can use the /VARIANT qualifier of the EXAMINE command to
select which member of a union (C program) or anonymous variant
(PASCAL program) to display. The format is as follows:
DBG> EXAMINE /VARIANT=variant-selector address-expression
DBG> EXAMINE /VARIANT=(variant-selector,...) address-expression
The variant selector variant-selector specifies a name, a
discriminant (PASCAL only), or a position; that is, one of the
following:
o NAME = name-string
o DISCRIMINANT = expression
o POSITION = expression
The /VARIANT qualifier takes a list of zero or more variant
selectors. /VARIANT without any variant selectors is the
default: the first variant of all anonymous variant lists will
be displayed.
Each variant selector specifies either the name, the
discriminant, or the position of the variant to be displayed.
The debugger uses the variant selector as follows:
1. If the debugger encounters an anonymous variable list while
displaying address-expression, the debugger uses the variant
selector to choose which variant to display.
2. Each time the debugger encounters an anonymous variant list,
it attempts to use the next variant selector to choose which
variant to display. If the variant selector matches one of the
variants of the variant list (union), the debugger displays
that variant.
3. The debugger walks the structure top-to-bottom, depth first,
so that children are encountered before siblings.
4. If the debugger encounters an anonymous variant list and does
not have a variant selector to match it with, the debugger
displays the first variant.
5. If the variant selector does not match any of the variants of
an anonymous variant list, the debugger displays a single line
to indicate that. This is similar to what the debugger does if
the discriminant value fails to match any of the variants in a
discriminated variant list. . For example:
[Variant Record omitted - null or illegal Tag Value: 3]
A name specifies a name string. A name matches a variant if that
variant contains a field with the name specified by name.
A discriminant specifies a language expression that must be
type compatible with the tag type of the variant part it is
meant to match. The discriminant expression matches a variant
if it evaluates to a value in the variant's case-label list.
Discriminants apply only to Pascal programs, because C and C++
unions do not have discriminants.
A positional-selector specifies a language expression, which
should evaluate to a integer between 1 and N, where N is the
number of variants in a variant list. A positional-selector that
evaluates to I specifies that the Ith variant is to be displayed.
You can use asterisk (*) as a wildcard, which matches all
variants of an anonymous variant list.
Each of these variant selectors can be used to match all
variants. In particular, each of the following variant selectors
indicates that all of the variants of the first anonymous variant
list are to be displayed.
/VAR=D=*
/VAR=N=*
/VAR=P=*
The variant selectors can themselves contain a list of selectors.
For example, the following commands all mean the same thing.
EXAMINE /VARIANT=(DIS=3,DIS=1,DIS=54) x
EXAMINE /VARIANT=(DIS=(3,1,54)) x
EXAMINE /VARIANT=DIS=(3,1,54) x
You can specify a a single discriminant or position value without
parentheses if the value is a simple decimal integer. To use
a general expression to specify the value, you enclose the
expression in parentheses. In the following list of commands,
the first four are legal while the last three are not.
EXAMINE /VARIANT=POS=3
EXAMINE /VARIANT=POS=(3) ! parentheses unnecessary
EXAMINE /VARIANT=(POS=(3)) ! parentheses unnecessary
EXAMINE /VARIANT=(POS=3) ! parentheses unnecessary
EXAMINE /VARIANT=(POS=foo) ! parentheses necessary
EXAMINE /VARIANT=POS=(foo) ! parentheses necessary
EXAMINE /VARIANT=(POS=3-1) ! parentheses necessary
Related Commands:
CANCEL TYPE/OVERRIDE
DEPOSIT
DUMP
EVALUATE
SET MODE [NO]OPERANDS
SET MODE [NO]SYMBOLIC
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
3 Examples
1.DBG> EXAMINE COUNT
SUB2\COUNT: 27
DBG>
This command displays the value of the integer variable COUNT
in module SUB2.
2.DBG> EXAMINE PART_NUMBER
INVENTORY\PART_NUMBER: "LP-3592.6-84"
DBG>
This command displays the value of the string variable PART_
NUMBER.
3.DBG> EXAMINE SUB1\ARR3
SUB1\ARR3
(1,1): 27.01000
(1,2): 31.01000
(1,3): 12.48000
(2,1): 15.08000
(2,2): 22.30000
(2,3): 18.73000
DBG>
This command displays the value of all elements in array ARR3
in module SUB1. ARR3 is a 2 by 3 element array of real numbers.
4.DBG> EXAMINE SUB1\ARR3(2,1:3)
SUB1\ARR3
(2,1): 15.08000
(2,2): 22.30000
(2,3): 18.73000
DBG>
This command displays the value of the elements in a slice of
array SUB1\ARR3. The slice includes "columns" 1 to 3 of "row"
2.
5.DBG> EXAMINE VALVES.INTAKE.STATUS
MONITOR\VALVES.INTAKE.STATUS: OFF
DBG>
This command displays the value of the nested record component
VALVES.INTAKE.STATUS in module MONITOR.
6.DBG> EXAMINE/SOURCE SWAP
module MAIN
47: procedure SWAP(X,Y: in out INTEGER) is
DBG>
This command displays the source line in which routine SWAP is
declared (the location of routine SWAP).
7.DBG> EXAMINE /VARIANT=(NAME=m,DIS=4,POS=1) x
This command specifies that, for the first anonymous variant
list encountered, display the variant part containing a field
named "m", for the second anonymous variant list, display
the part with the discriminant value 4, and, for the third
anonymous variant list, display the first variant part.
2 EXIT
Ends a debugging session, or terminates one or more processes of
a multiprocess program, allowing any application-declared exit
handlers to run. If used within a command procedure or DO clause
and no process is specified, it exits the command procedure or DO
clause at that point.
Format
EXIT [process-spec[, . . . ]]
3 Parameters
process-spec
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
You can also use the asterisk (*) wildcard character to specify
all processes.
3 Description
The EXIT command is one of the four debugger commands that can be
used to execute your program (the others are CALL, GO, and STEP).
Ending a Debugging Session:
To end a debugging session, enter the EXIT command at the
debugger prompt without specifying any parameters. This causes
orderly termination of the session: the program's application-
declared exit handlers (if any) are executed, the debugger exit
handler is executed (closing log files, restoring the screen and
keypad states, and so on), and control is returned to the command
interpreter. You cannot then continue to debug your program by
entering the DCL command DEBUG or CONTINUE (you must restart the
debugger).
Because EXIT runs any application-declared exit handlers, you can
set breakpoints in such exit handlers, and the breakpoints are
triggered upon typing EXIT. Thus, you can use EXIT to debug your
exit handlers.
To end a debugging session without running any application-
declared exit handlers, use the QUIT command instead of EXIT.
Using the EXIT Command in Command Procedures and DO Clauses:
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.
3 Description,_Continued...
Terminating Specified Processes:
If you are debugging a multiprocess program you can use the
EXIT command to terminate specified 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, enter the EXIT command,
specifying these processes as parameters. This causes orderly
termination of the images in these processes, executing any
application-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 command, the hold condition
is ignored.
When the specified processes begin to exit, any unspecified
process that is not on hold begins execution. After execution
is started, the way in which it continues depends on whether you
entered a SET MODE [NO]INTERRUPT command. 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 specified processes without running any application-
declared exit handlers or otherwise starting execution, use the
QUIT command instead of EXIT.
Related commands:
DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
QUIT
RERUN
RUN
SET ABORT_KEY
SET MODE [NO]INTERRUPT
SET PROCESS
3 Examples
1.DBG> EXIT
$
This command ends the debugging session and returns you to DCL
level.
2.all> EXIT %NEXT_PROCESS, JONES_3, %PROC 5
all>
This command causes orderly termination of three processes of
a multiprocess program: the process after the visible process
on the process list, process JONES_3, and process 5. Control
is returned to the debugger after the specified processes have
exited.
2 EXITLOOP
Exits one or more enclosing FOR, REPEAT, or WHILE loops.
Format
EXITLOOP [integer]
3 Parameters
integer
A decimal integer that specifies the number of nested loops to
exit from. The default is 1.
3 Description
Use the EXITLOOP command to exit one or more enclosing FOR,
REPEAT, or WHILE loops.
Related commands:
FOR
REPEAT
WHILE
3 Example
DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP)
The WHILE 1 command generates an endless loop that executes a
STEP command with each iteration. After each STEP, the value
of X is tested. If X is greater than 3, the EXITLOOP command
terminates the loop (Fortran example).
2 EXPAND
Expands or contracts the window associated with a screen display.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
EXPAND [display-name[, . . . ]]
3 Parameters
display-name
Specifies a display to be expanded or contracted. You can specify
any of the following entities:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
o A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you do not specify a display, the current scrolling display,
as established by the SELECT command, is chosen.
3 Qualifiers
/DOWN
/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 omit n, the
border is moved down by 1 line.
/LEFT
/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 omit n, the border is moved to the left by 1 line.
/RIGHT
/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 omit n, the border is moved to the right by 1 line.
/UP
/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 omit
n, the border is moved up by 1 line.
3 Description
You must specify at least one qualifier.
The EXPAND command moves one or more display-window borders
according to the qualifiers specified (/UP:[n], /DOWN:[n],
RIGHT:[n], /LEFT:[n]).
The EXPAND command does not affect the order of a display on
the display pasteboard. Depending on the relative order of
displays, the EXPAND command can 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 contracted to
the point where it disappears (at which point it is marked as
"removed"). It can then be expanded from that point. Contracting
a display to the point where it disappears causes it to lose any
attributes that were selected for it. The PROMPT display cannot
be contracted or expanded horizontally but can be contracted
vertically to a height of 2 lines.
A window border can be expanded only up to the edge of the
screen. The left and top window borders cannot be expanded beyond
the left and top edges of the display, respectively. 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 (to the
end of the source module or routine's instructions). A register
display cannot be expanded beyond its full size.
For a list of the key definitions associated with the EXPAND
command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY
command to determine the current key definitions.
Related commands:
DISPLAY
MOVE
SELECT/SCROLL
(SET,SHOW) TERMINAL
3 Examples
1.DBG> EXPAND/RIGHT:6
This command moves the right border of the current scrolling
display to the right by 6 columns.
2.DBG> EXPAND/UP/RIGHT:-12 OUT2
This command moves the top border of display OUT2 up by 1 line,
and the right border to the left by 12 columns.
3.DBG> EXPAND/DOWN:99 SRC
This command moves the bottom border of display SRC down to the
bottom edge of the screen.
2 EXTRACT
Saves the contents of screen displays in a file or creates a
debugger command procedure with all of the commands necessary to
re-create the current screen state later on.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
EXTRACT [display-name[, . . . ]] [file-spec]
3 Parameters
display-name
Specifies a display to be extracted. You can specify any of the
following entities:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
You can use the asterisk (*) wildcard character in a display
name. Do not specify a display name with the /ALL qualifier.
file-spec
Specifies the file to which the information is written. You can
specify a logical name.
If you specify /SCREEN_LAYOUT, the default specification for
the file is SYS$DISK:[]DBGSCREEN.COM. Otherwise, the default
specification is SYS$DISK:[]DEBUG.TXT.
3 Qualifiers
/ALL
Extracts all displays. Do not specify /SCREEN_LAYOUT with this
qualifier.
/APPEND
Appends the information at the end of the file, rather than
creating a new file. By default, a new file is created. Do not
specify /SCREEN_LAYOUT with this qualifier.
/SCREEN_LAYOUT
Writes a file that contains the debugger commands describing the
current state of the screen. This information includes the screen
height and width, message wrap setting, and the position, display
kind, and display attributes of every existing display. This file
can then be executed with the execute procedure (@) command to
reconstruct the screen at a later time. Do not specify /ALL with
this qualifier.
3 Description
When you use the EXTRACT command to save the contents of a
display into a file, only those lines that are currently stored
in the display's memory buffer (as determined by the /SIZE
qualifier on the DISPLAY command) are written to the file.
You cannot extract the PROMPT display into a file.
Related commands:
DISPLAY
SAVE
3 Examples
1.DBG> EXTRACT SRC
This command writes all the lines in display SRC into file
SYS$DISK:[]DEBUG.TXT.
2.DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE
This command appends all the lines in display OUT to the end of
file [JONES.WORK]MYFILE.TXT.
3.DBG> EXTRACT/SCREEN_LAYOUT
This command writes the debugger commands needed to reconstruct
the screen into file SYS$DISK:[]DBGSCREEN.COM.
2 FOR
Executes a sequence of commands while incrementing a variable a
specified number of times.
Format
FOR name=expression1 TO expression2 [BY expression3]
DO (command[; . . . ])
3 Parameters
name
Specifies the name of a count variable.
expression1
Specifies an integer or enumeration type value. The expression1
and expression2 parameters must be of the same type.
expression2
Specifies an integer or enumeration type value. The expression1
and expression2 parameters must be of the same type.
expression3
Specifies an integer.
command
Specifies a debugger command. If you specify more than one
command, you must separate the commands with semicolons. At each
execution, the debugger checks the syntax of any expressions in
the commands and then evaluates them.
3 Description
The behavior of the FOR command depends on the value of the
expression3 parameter, as detailed in the following table:
expression3Action of the FOR Command
Positive name parameter is incremented from the value of
expression1 by the value of expression3 until it is
greater than the value of expression2
Negative name is decremented from the value of expression1 by
the value of expression3 until it is less than the
value of expression2
0 The debugger returns an error message
Omitted The debugger assumes it to have the value +1
Related commands:
EXITLOOP
REPEAT
WHILE
3 Examples
1.DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(I))
This command examines an array backwards.
2.DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0)
This command initializes an array to zero.
2 GO
Starts or resumes program execution.
Format
GO [address-expression]
3 Parameters
address-expression
Specifies that program execution resume at the location denoted
by the address expression. If you do not specify an address
expression, execution resumes at the point of suspension or,
in the case of debugger startup, at the image transfer address.
3 Description
The GO command 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 be used to execute your program
(the others are CALL, EXIT, and STEP).
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 the GO %LINE 1 command. However, because the program has
executed, the contents of some variables might now be initialized
differently from when you first ran the program.
If an exception breakpoint is triggered (resulting from a SET
BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is
suspended before any application-declared condition handler is
invoked. If you then resume execution with the GO command, the
behavior is as follows:
o Entering a GO command to resume execution from the current
location causes the debugger to resignal the exception. This
enables you to observe which application-declared handler, if
any, next handles the exception.
o Entering a GO command to resume execution from a location
other than the current location inhibits the execution of any
application-declared handler for that exception.
If you are debugging a multiprocess program, the GO command is
executed in the context of the current process set. In addition,
when debugging a multiprocess program, the way in which execution
continues in your process depends on whether you entered a SET
MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By
default (SET MODE NOINTERRUPT), when one process stops, the
debugger takes no action with regard to the other processes.
Also by default (SET MODE WAIT), the debugger waits until all
process in the current process set have stopped before prompting
for a new command.
Related commands:
CALL
EXIT
RERUN
SET BREAK
SET MODE [NO]INTERRUPT
SET MODE [NO]WAIT
SET PROCESS
SET STEP
SET TRACE
SET WATCH
STEP
WAIT
3 Examples
1.DBG> GO
. . .
'Normal successful completion'
DBG>
This command starts program execution, which then completes
successfully.
2.DBG> SET BREAK RESTORE
DBG> GO ! start execution
. . .
break at routine INVENTORY\RESTORE
137: procedure RESTORE;
DBG> GO ! resume execution
. . .
In this example, 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
This command resumes program execution at line 42 of the module
in which execution is currently suspended.
2 HELP
Displays online help on debugger commands and selected topics.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger. Help on commands
is available from the Help menu in a DECwindows debugger
window.
Format
HELP topic [subtopic [ . . . ]]
3 Parameters
topic
Specifies the name of a debugger command or topic about which you
want help. You can specify the asterisk (*) wildcard character,
either singly or within a name.
subtopic
Specifies a subtopic, qualifier, or parameter about which you
want further information. You can specify the asterisk wildcard
(*), either singly or within a name.
3 Description
The debugger's online help facility provides the following
information about any debugger command, including a description
of the command, its format, explanations of any parameters
that can be specified with the command, and explanations of any
qualifiers that can be specified with the command.
To get information about a particular qualifier or parameter,
specify it as a subtopic. If you want information about all
qualifiers, specify "qualifier" as a subtopic. If you want
information about all parameters, specify "parameter" as
a subtopic. If you want information about all parameters,
qualifiers, and any other subtopics related to a command, specify
an asterisk (*) as a subtopic.
In addition to help on commands, you can get online help on
various topics such as screen features, keypad mode, and so on.
Topic keywords are listed along with the commands when you type
HELP.
For summary information about new features with this release of
the debugger, see help on New_Features.
For help on the predefined keypad-key functions, type Help
Keypad_Definitions_CI. Also, use the SHOW KEY command to
determine the current key definitions.
3 Example
DBG> HELP GO
This command displays help for the GO command.
2 IF
Executes a sequence of commands if a language expression (Boolean
expression) is evaluated as true.
Format
IF Boolean-expression THEN (command[; . . . ])
[ELSE (command[; . . . ])]
3 Parameters
Boolean-expression
Specifies a language expression that evaluates as a Boolean value
(true or false) in the currently set language.
command
Specifies a debugger command. If you specify more than one
command, you must separate the commands with semicolons (;).
3 Description
The IF command evaluates a Boolean expression. If the value is
true (as defined in the current language), the command list in
the THEN clause is executed. If the expression is false, the
command list in the ELSE clause (if any) is executed.
Related commands:
EXITLOOP
FOR
REPEAT
WHILE
3 Example
DBG> SET BREAK R DO (IF X .LT. 5 THEN (GO) ELSE (EXAMINE X))
This command causes the debugger to suspend program execution
at location R (a breakpoint) and then resume program execution
if the value of X is less than 5 (Fortran example). If the
value of X is 5 or more, its value is displayed.
2 MONITOR
Displays the current value of a program variable or language
expression in the monitor view of the Compaq DECwindows Motif for
OpenVMS user interface.
NOTE
Requires the Compaq DECwindows Motif for OpenVMS user
interface.
Format
MONITOR expression
3 Parameters
expression
Specifies an entity to be monitored. With high-level languages,
this is typically the name of a variable. Currently, MONITOR does
not handle composite expressions (language expressions containing
operators).
If you specify the name of an aggregate variable (a composite
data structure such as an array or record structure), the monitor
view lists "Aggregate" for the value of the variable. You can
then double-click on the variable name to get the values of all
the elements (see context-sensitive Help).
To specify an individual array element, array slice, or record
component, follow the syntax of the current language.
3 Qualifiers
/ASCIC
/ASCIC
/AC
Interprets each monitored entity as a counted ASCII string
preceded by a 1-byte count field that gives the length of the
string. The string is then displayed.
/ASCID
/ASCID
/AD
Interprets each monitored entity as the address of a string
descriptor pointing to an ASCII string. The CLASS and DTYPE
fields of the descriptor are not checked, but the LENGTH and
POINTER fields provide the character length and address of the
ASCII string. The string is then displayed.
/ASCII
/ASCII:n
Interprets and displays each monitored entity as an ASCII string
of length n bytes (n characters). If you omit n, the debugger
attempts to determine a length from the type of the address
expression.
/ASCIW
/ASCIW
/AW
Interprets each monitored entity as a counted ASCII string
preceded by a 2-byte count field that gives the length of the
string. The string is then displayed.
/ASCIZ
/ASCIZ
/AZ
Interprets each monitored entity as a zero-terminated ASCII
string. The ending zero byte indicates the end of the string.
The string is then displayed.
/BINARY
Displays each monitored entity as a binary integer.
/BYTE
Displays each monitored entity in the byte integer type (length 1
byte).
/D_FLOAT
(VAX only) Displays each monitored entity in the D_floating type
(length 8 bytes).
/DATE_TIME
Interprets each monitored entity as a quadword integer (length 8
bytes) containing the internal OpenVMS representation of date and
time. Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc.
/DECIMAL
Displays each monitored entity as a decimal integer.
/DEFAULT
Displays each monitored entity in the default radix.
/EXTENDED_FLOAT
(Alpha only) Displays each monitored entity in the IEEE X_
floating type (length 16 bytes).
/FLOAT
On VAX processors, displays each monitored entity in the F_
floating type (length 4 bytes).
On Alpha processors, displays each monitored entity in the IEEE
T_floating type (double precision, length 8 bytes).
/F_FLOAT
(VAX only) Displays each monitored entity in the F_floating type
(length 4 bytes).
/G_FLOAT
Displays each monitored entity in the G_floating type (length 8
bytes).
/H_FLOAT
(VAX only) Displays each monitored entity in the H_floating type
(length 16 bytes).
/HEXADECIMAL
Displays each monitored entity as a hexadecimal integer.
/INSTRUCTION
Displays each monitored entity as an assembly-language
instruction (variable length, depending on the number of
instruction operands and the kind of addressing modes used).
See also the /OPERANDS qualifier.
/INT
Same as /LONGWORD qualifier.
/LONG_FLOAT
(Alpha only) Displays each monitored entity in the IEEE S_
floating type (single precision, length 4 bytes).
/LONG_LONG_FLOAT
(Alpha only) Displays each monitored entity in the IEEE T_
floating type (double precision, length 8 bytes).
/LONGWORD
/LONGWORD
/INT
/LONG
Displays each monitored entity in the longword integer type
(length 4 bytes). This is the default type for program locations
that do not have a compiler-generated type.
/OCTAL
Displays each monitored entity as an octal integer.
/OCTAWORD
Displays each monitored entity in the octaword integer type
(length 16 bytes).
/QUADWORD
Displays each monitored entity in the quadword integer type
(length 8 bytes).
/REMOVE
Removes a monitored item or items with the address expression
specified from the Monitor View.
/SHORT
Same as /WORD qualfier.
/TASK
Applies to tasking (multithread) programs. Interprets each
monitored entity as a task (thread) object and displays the task
value (the name or task ID) of that task object. When monitoring
a task object, use /TASK only if the programming language does
not have built-in tasking services.
/WORD
/WORD
/SHORT
Displays each monitored entity in the word integer type (length 2
bytes).
3 Description
You can use the MONITOR command only with the debugger's Compaq
DECwindows Motif for OpenVMS user interface, because the output
of that command is directed at the monitor view. With the command
interface, you typically use the EVALUATE, EXAMINE or SET WATCH
command instead.
The MONITOR command does the following:
1. Displays the monitor view (if it is not already displayed by a
previous MONITOR command).
2. Puts the name of the specified variable or expression and its
current value in the monitor view.
The debugger updates the monitor view whenever the debugger
regains control from the program, regardless of whether the value
of the variable or location you are monitoring has changed. (By
contrast, a watchpoint halts execution when the value of the
watched variable changes.)
For more information about the monitor view and the MONITOR
command, see context-sensitive Help.
Related commands:
DEPOSIT
EVALUATE
EXAMINE
SET WATCH
3 Example
DBG> MONITOR COUNT
This command displays the name and current value of the
variable COUNT in the monitor view of the debugger's Compaq
DECwindows Motif for OpenVMS user interface. The value is
updated whenever the debugger regains control from the program.
2 MOVE
Moves a screen display vertically or horizontally across the
screen.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
MOVE [display-name[, . . . ]]
3 Parameters
display-name
Specifies a display to be moved. You can specify any of the
following entities:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
o A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you do not specify a display, the current scrolling display,
as established by the SELECT command, is chosen.
3 Qualifiers
/DOWN
/DOWN[:n]
Moves the display down by n lines (if n is positive) or up by
n lines (if n is negative). If you omit n, the display is moved
down by 1 line.
/LEFT
/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 omit n, the display
is moved to the left by 1 line.
/RIGHT
/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 omit n, the display is
moved to the right by 1 line.
/UP
/UP[:n]
Moves the display up by n lines (if n is positive) or down by n
lines (if n is negative). If you omit n, the display is moved up
by 1 line.
3 Description
You must specify at least one qualifier.
For each display specified, the MOVE command simply creates a
window of the same dimensions elsewhere on the screen and maps
the display to it, while maintaining the relative position of the
text within the window.
The MOVE command does not change the order of a display on the
display pasteboard. Depending on the relative order of displays,
the MOVE command can 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.
For a list of the keypad-key definitions associated with the MOVE
command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY
command to determine the current key definitions.
Related commands:
DISPLAY
EXPAND
SELECT/SCROLL
(SET,SHOW) TERMINAL
3 Examples
1.DBG> MOVE/LEFT
This command moves the current scrolling display to the left by
1 column.
2.DBG> MOVE/UP:3/RIGHT:5 NEW_OUT
This command moves display NEW_OUT up by 3 lines and to the
right by 5 columns.
2 PTHREAD
Passes a command to the POSIX Threads debugger for execution.
NOTE
This command is valid only when the event facility is
THREADS and the program is running POSIX Threads 3.13 or
later.
Format
PTHREAD command
3 Parameters
command
A POSIX Threads debugger command.
3 Description
Passes a command to the POSIX Threads debugger for execution.
The results appear in the command view. Once the POSIX Threads
debugger command has been completed, control is returned to the
OpenVMS debugger. You can get help on POSIX Threads debugger
commands by typing PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
Related commands:
o SET EVENT FACILITY
o SET TASK|THREAD
o SHOW EVENT FACILITY
o SHOW TASK|THREAD
3 Example
DBG_1> PTHREAD HELP
conditions [-afhwqrs] [-
N <n>] [id]...: list condition variables
exit: exit from DECthreads debugger
help [topic]: display help information
keys [-v] [-N <n>] [id]...: list keys
mutexes [-afhilqrs] [-N <n>] [id]...: list mutexes
quit: exit from DECthreads debugger
show [-csuv]: show stuff
squeue [-c <n>] [-fhq] [-t <t>] [a]: format queue
stacks [-fs] [sp]...: list stacks
system: show system information
threads [-1] [-N <n>] [-abcdfhklmnor] [-s <v>] [-
tz] [id]...: list threads
tset [-chna] [-s <v>] <id>: set state of thread
versions: display versions
write <st>: write a string
All keywords may be abbreviated: if the abbreviation is ambiguous,
the first match will be used. For more help, type 'help <topic>'.
DBG_1>
This command invokes the POSIX Threads debugger help file,
then returns control to the OpenVMS debugger. To get specific
help on a POSIX Threads debugger Help topic, type PTHREAD HELP
topic.
2 QUIT
Ends a debugging session, or terminates one or more processes of
a multiprocess program (similar to EXIT), but without allowing
any application-declared exit handlers to run. If used within a
command procedure or DO clause and no process is specified, it
exits the command procedure or DO clause at that point.
Format
QUIT [process-spec[, . . . ]]
3 Parameters
process-spec
(Kept debugger only.) Specifies a process currently under
debugger control. Use any of the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
You can also use the asterisk (*) wildcard character to specify
all processes.
3 Description
The QUIT command is simlar to the EXIT command, except that QUIT
does not cause your program to execute and, therefore, does not
execute any application-declared exit handlers in your program.
Ending a Debugging Session:
To end a debugging session, enter the QUIT command at the
debugger prompt without specifying any parameters. This causes
orderly termination of the session: the debugger exit handler
is executed (closing log files, restoring the screen and keypad
states, and so on), and control is returned to DCL level. You
cannot then continue to debug your program by entering the DCL
command DEBUG or CONTINUE (you must restart the debugger).
Using the QUIT Command in Command Procedures and DO Clauses:
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 Specified Processes:
If you are debugging a multiprocess program, you can use the
QUIT command to terminate specified 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 application-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, the QUIT command does not cause
any process to start execution.
Related commands:
DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
EXIT
RERUN
RUN
SET ABORT_KEY
SET PROCESS
3 Examples
1.DBG> QUIT
$
This command ends the debugging session and returns you to DCL
level.
2.all> QUIT %NEXT_PROCESS, JONES_3, %PROC 5
all>
This command causes orderly termination of three processes of
a multiprocess program: the process after the visible process
on the process list, process JONES_3, and process 5. Control
is returned to the debugger after the specified processes have
exited.
2 REBOOT
(Alpha only) When debugging Alpha operating system code with
the OpenVMS Alpha System-Code Debugger, reboots the target
machine running the Alpha operating system code and executes
(or reexecutes) your system program.
The REBOOT command, in other words, is similar to the RUN or
RERUN commands when you are within the OpenVMS Alpha System-Code
Debugger environment. (The OpenVMS Alpha System-Code Debugger
is a kernel debugger that is activated through the OpenVMS
Debugger.)
Before you issue this command, you must have completed the
instructions described in the Writing OpenVMS Alpha Device
Drivers in C manual. These instructions include the creation of
an Alpha device driver, the setup commands activating the OpenVMS
Alpha System-Code Debugger, and the CONNECT command that allows
you to debug.
You must also have started the OpenVMS Debugger with the
DEBUG/KEEP command.
Format
REBOOT
3 Description
For complete information on using the OpenVMS Alpha System-
Code Debugger, see the Writing OpenVMS Alpha Device Drivers in
C manual.
Related commands:
CONNECT
DISCONNECT
3 Example
DBG> REBOOT
This command reboots the target machine where you will be
debugging the OpenVMS Alpha operating system and reruns your
program.
2 REPEAT
Executes a sequence of commands a specified number of times.
Format
REPEAT language-expression DO (command[; . . . ])
3 Parameters
language-expression
Denotes any expression in the currently set language that
evaluates to a positive integer.
command
Specifies a debugger command. If you specify more than one
command, you must separate the commands with semicolons (;). At
each execution, the debugger checks the syntax of any expressions
in the commands and then evaluates them.
3 Description
The REPEAT command is a simple form of the FOR command. The
REPEAT command executes a sequence of commands repetitively a
specified number of times, without providing the options for
establishing count parameters that the FOR command does.
Related commands:
EXITLOOP
FOR
WHILE
3 Example
DBG> REPEAT 10 DO (EXAMINE Y; STEP)
This command line sets up a loop that issues a sequence of two
commands (EXAMINE Y, then STEP) 10 times.
2 RERUN
Reruns the program currently under debugger control.
NOTE
Requires that you started your debugging session with the
DCL command DEBUG/KEEP and then executed the debugger RUN
command. If you began your session with the DCL command RUN
filespec instead, you cannot use the debugger RERUN command.
Format
RERUN
3 Qualifiers
/ARGUMENTS
/ARGUMENTS="arg-list"
Specifies a list of arguments. If you specify a quoted string,
you might have to add quotation marks because the debugger strips
them when parsing the string. If you do not specify arguments,
any arguments that were specified previously when running or
rerunning that program are applied, by default.
/HEAP_ANALYZER
(Applies only to workstation users.) Invokes the Heap Analyzer, a
debugger feature that helps you understand how memory is used
by your application. For more information on using the Heap
Analyzer, see the OpenVMS Debugger Manual.
/SAVE
/SAVE (default)
/NOSAVE
Controls whether to save the current state (activated or
deactivated) of all breakpoints, tracepoints, and static
watchpoints for the next run of the program. The /SAVE qualifier
specifies that their state is saved, and /NOSAVE specifies that
their state is not saved. /SAVE may or may not save the state of
a particular nonstatic watchpoint depending on the scope of the
variable being watched relative to the main program unit (where
execution restarts).
3 Description
If you invoked the debugger with the DCL command DEBUG/KEEP and
subsequently used the debugger RUN command to begin debugging
your program, you can then use the RERUN command to rerun the
program currently under debugger control.
The RERUN command terminates the image you were debugging and
then restarts that image under debugger control. Execution is
paused at the start of the main program unit, as if you had used
the debugger RUN command or the DCL command RUN/DEBUG.
The RERUN command uses the same version of the image that is
currently under debugger control. To debug a different version
of that program (or a different program) from the same debugging
session, use the RUN command.
Related commands:
RUN (debugger command)
RUN (DCL command)
(ACTIVATE,DEACTIVATE) BREAK
(ACTIVATE,DEACTIVATE) TRACE
(ACTIVATE,DEACTIVATE) WATCH
3 Examples
1.DBG> RERUN
This command reruns the current program. By default, the
debugger saves the current state of all breakpoints,
tracepoints, and static watchpoints (activated or deactivated).
2.DBG> RERUN/NOSAVE
This command reruns the current program without saving the
current state of breakpoints, tracepoints, and watchpoints-in
effect, the same as using the RUN command and specifying the
image name.
3.DBG> RERUN/ARGUMENTS="fee fii foo fum"
This command reruns the current program with new arguments.
2 RUN
Runs a program under debugger control.
NOTE
Requires that you started your debugging session with the
DCL command DEBUG/KEEP. If you began your session with
the DCL command RUN filespec instead, you cannot use the
debugger RUN command.
Format
RUN [program-image]
3 Parameters
program-image
Specifies the executable image of the program to be debugged.
Do not specify an image if you use the /COMMAND=cmd-symbol
qualifier.
3 Qualifiers
/ARGUMENTS
/ARGUMENTS="arg-list"
Specifies a list of arguments. If you specify a quoted string,
you might have to add quotation marks because the debugger strips
quotes when parsing the string.
/COMMAND
/COMMAND="cmd-symbol"
Specifies a DCL foreign command for running the program.
Do not use this qualifier if you specify a program-image
parameter.
Do not specify a DCL command or any other command definition that
was created with the SET COMMAND command.
/HEAP_ANALYZER
(Applies only to workstation users.) Invokes the Heap Analyzer, a
debugger feature that helps you understand how memory is used
by your application. For more information on using the Heap
Analyzer, see the OpenVMS Debugger Manual.
/NEW
Runs a new program under debugger control without terminating any
programs already running.
3 Description
If you invoked the debugger with the DCL command DEBUG/KEEP, you
can use the debugger RUN command at any time during a debugging
session to start a program under debugger control. If you are in
the midst of debugging a program when you issue the RUN command,
that program will first be terminated unless you use the /NEW
qualifier.
To run the same program again (that is, the same version of the
program that is currently under debugger control), use the RERUN
command. RERUN enables you to save the current state (activated
or deactivated) of any breakpoints, tracepoints, and static
watchpoints.
Note the following restrictions about the debugger RUN command:
o You can use the RUN command only if you started the debugger
with the DCL command DEBUG/KEEP.
o You cannot use the RUN command to connect the debugger to a
running program. See the description of Ctrl/Y.
o You cannot run a program under debugger control over a DECnet
link. Both the image to be debugged and the debugger must
reside on the same node.
Related commands:
RERUN
RUN (DCL command)
Ctrl/Y-DEBUG (DCL command)
DEBUG (DCL command)
3 Examples
1.DBG> RUN EIGHTQUEENS
Language: C, Module: EIGHTQUEENS
This command brings the program EIGHTQUEENS under debugger
control.
2.$ RUNPROG == "$ DISK3:[SMITH]MYPROG.EXE"
$ DEBUG/KEEP
. . .
DBG> RUN/COMMAND="RUNPROG"/ARGUMENTS="X Y Z"
The first line of this example creates a command symbol RUNPROG
(at DCL level) to run an image named MYPROG.EXE. The second
line starts the debugger. The debugger RUN command then brings
the image MYPROG.EXE under debugger control. The /COMMAND
qualifier specifies the command symbol previously created (in
this case RUNPROG), and the /ARGUMENTS qualifier passes the
arguments X Y Z to the image.
3.DBG> RUN/ARGUMENTS="X Y Z" MYPROG
This command brings the program MYPROG.EXE under debugger
control and passes the arguments X Y Z.
2 SAVE
Preserves the contents of an existing screen display in a new
display.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SAVE old-display AS new-display [, . . . ]
3 Parameters
old-display
Specifies the display whose contents are saved. You can specify
any of the following entities:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
o A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
new-display
Specifies the name of the new display to be created. This new
display then receives the contents of the old-disp display.
3 Description
The SAVE command enables you to save a snapshot copy of an
existing display in a new display for later reference. The new
display is created with the same text contents as the existing
display. In general, the new display is given all the attributes
or characteristics of the old display except that it is removed
from the screen and is never automatically updated. You can later
recall the saved display to the terminal screen with the DISPLAY
command.
When you use the SAVE command, only those lines that are
currently stored in the display's memory buffer (as determined
by the /SIZE qualifier on the DISPLAY command) are stored in
the saved display. However, in the case of a saved source or
instruction display, you can also see any other source lines
associated with that module or any other instructions associated
with that routine (by scrolling the saved display).
You cannot save the PROMPT display.
Related commands:
DISPLAY
EXITLOOP
3 Example
DBG> SAVE REG AS OLDREG
This command saves the contents of the display named REG into
the newly created display named OLDREG.
2 SCROLL
Scrolls a screen display to make other parts of the text visible
through the display window.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SCROLL [display-name]
3 Parameters
display-name
Specifies a display to be scrolled. You can specify any of the
following entities:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
o A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you do not specify a display, the current scrolling display,
as established by the SELECT command, is chosen.
3 Qualifiers
/BOTTOM
Scrolls down to the bottom of the display's text.
/DOWN
/DOWN:[n]
Scrolls down over the display's text by n lines to reveal text
further down in the display. If you omit n, the display is
scrolled by approximately 3/4 of its window height.
/LEFT
/LEFT:[n]
Scrolls left over the display's text by n columns to reveal text
beyond the left window border. You cannot scroll past column 1.
If you omit n, the display is scrolled left by 8 columns.
/RIGHT
/RIGHT[:n]
Scrolls right over the display's text by n columns to reveal text
beyond the right window border. You cannot scroll past column
255. If you omit n, the display is scrolled right by 8 columns.
/TOP
Scrolls up to the top of the display's text.
/UP
/UP[:n]
Scrolls up over the display's text by n lines to reveal text
further up in the display. If you omit n, the display is scrolled
by approximately 3/4 of its window height.
3 Description
The SCROLL command moves a display up, down, right, or left
relative to its window so that various parts of the display text
can be made visible through the window.
Use the SELECT/SCROLL command to select the target display for
the SCROLL command (the current scrolling display).
For a list of the key definitions associated with the SCROLL
command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY
command to determine the current key definitions.
Related command: SELECT.
3 Examples
1.DBG> SCROLL/LEFT
This command scrolls the current scrolling display to the left
by 8 columns.
2.DBG> SCROLL/UP:4 ALPHA
This command scrolls display ALPHA 4 lines up.
2 SEARCH
Searches the source code for a specified string and displays
source lines that contain an occurrence of the string.
Format
SEARCH [range] [string]
3 Parameters
range
Specifies a program region to be searched. Use any of the
following formats:
mod-name Searches the specified module from line 0 to
the end of the module.
mod-name\line-num Searches the specified module from the
specified line number to the end of the
module.
mod-name\line- Searches the specified module from the line
num:line-num number specified on the left of the colon to
the line number specified on the right.
line-num Uses the current scope to find a module and
searches that module from the specified line
number to the end of the module. The current
scope is established by a previous SET SCOPE
command, or the PC scope if you did not enter
a SET SCOPE command. If you specify a scope
search list with the SET SCOPE command, the
debugger searches only the module associated
with the first named scope.
line-num:line-num Uses the current scope to find a module and
searches that module from the line number
specified on the left of the colon to the
line number specified on the right. The
current scope is established by a previous
SET SCOPE command, or the PC scope if you
did not enter a SET SCOPE command. If you
specify a scope search list with the SET
SCOPE command, the debugger searches only the
module associated with the first named scope.
null (no entry) Searches the same module as that from which
a source line was most recently displayed
(as a result of a TYPE, EXAMINE/SOURCE,
or SEARCH command, for example), beginning
at the first line following the line most
recently displayed and continuing to the end
of the module.
string
Specifies the source code characters for which to search. If you
do not specify a string, the string specified in the last SEARCH
command, if any, is used.
You must enclose the string in quotation marks (") or
apostrophes (') under the following conditions:
o The string has any leading or ending space or tab characters
o The string contains an embedded semicolon
o The range parameter is null
If the string is enclosed in quotation marks, use two consecutive
quotation marks ("") to indicate an enclosed quotation mark.
If the string is enclosed in apostrophes, use two consecutive
apostrophes ('') to indicate an enclosed apostrophe.
3 Qualifiers
/ALL
Specifies that the debugger search for all occurrences of the
string in the specified range and display every line containing
an occurrence of the string.
/IDENTIFIER
Specifies that the debugger search for an occurrence of the
string in the specified range but display the string only if
it is not bounded on either side by a character that can be part
of an identifier in the current language.
/NEXT
(Default) Specifies that the debugger search for the next
occurrence of the string in the specified range and display only
the line containing this occurrence.
/STRING
(Default) Specifies that the debugger search for and display the
string as specified, and not interpret the context surrounding an
occurrence of the string, as it does in the case of /IDENTIFIER.
3 Description
The SEARCH command displays the lines of source code that contain
an occurrence of a specified string.
If you specify a module name with the SEARCH command, that module
must be set. To determine whether a particular module is set,
use the SHOW MODULE command, then use the SET MODULE command, if
necessary.
Qualifiers for the SEARCH command determine whether the debugger:
(1) searches for all occurrences (/ALL) of the string or only
the next occurrence (/NEXT); and (2) displays any occurrence
of the string (/STRING) or only those occurrences in which the
string is not bounded on either side by a character that can be
part of an identifier in the current language (/IDENTIFIER).
If you plan to enter several SEARCH commands with the same
qualifier, you can first use the SET SEARCH command to establish
a new default qualifier (for example, SET SEARCH ALL makes the
SEARCH command behave like SEARCH/ALL). Then you do not have to
use that qualifier with the SEARCH command. You can override the
current default qualifiers for the duration of a single SEARCH
command by specifying other qualifiers.
Related commands:
(SET,SHOW) LANGUAGE
(SET,SHOW) MODULE
(SET,SHOW) SCOPE
(SET,SHOW) SEARCH
3 Examples
1.DBG> SEARCH/STRING/ALL 40:50 D
module COBOLTEST
40: 02 D2N COMP-2 VALUE -234560000000.
41: 02 D COMP-2 VALUE 222222.33.
42: 02 DN COMP-2 VALUE -222222.333333.
47: 02 DR0 COMP-2 VALUE 0.1.
48: 02 DR5 COMP-2 VALUE 0.000001.
49: 02 DR10 COMP-2 VALUE 0.00000000001.
50: 02 DR15 COMP-2 VALUE 0.0000000000000001.
DBG>
This command searches for all occurrences of the letter D in
lines 40 to 50 of the module COBOLTEST, the module that is in
the current scope.
2.DBG> SEARCH/IDENTIFIER/ALL 40:50 D
module COBOLTEST
41: 02 D COMP-2 VALUE 222222.33.
DBG>
This command searches for all occurrences of the letter D in
lines 40 to 50 of the module COBOLTEST. The debugger displays
the only line where the letter D (the search string) is not
bounded on either side by a character that can be part of an
identifier in the current language.
3.DBG> SEARCH/NEXT 40:50 D
module COBOLTEST
40: 02 D2N COMP-2 VALUE -234560000000.
DBG>
This command searches for the next occurrence of the letter D
in lines 40 to 50 of the module COBOLTEST.
4.DBG> SEARCH/NEXT
module COBOLTEST
41: 02 D COMP-2 VALUE 222222.33.
DBG>
This command searches for the next occurrence of the letter D.
The debugger assumes D to be the search string because D was
the last one entered and no other search string was specified.
5.DBG> SEARCH 43 D
module COBOLTEST
47: 02 DR0 COMP-2 VALUE 0.1.
DBG>
This command searches for the next occurrence (by default) of
the letter D, starting with line 43.
2 SDA
Invokes the System Dump Analyzer (SDA) from within the OpenVMS
debugger without terminating a debugger session.
Format
SDA [sda-command]
3 Parameters
sda-command
One SDA command to be executed before returning control to the
OpenVMS debugger.
3 Description
The SDA command allows you to use the System Dump Analyzer (SDA)
within the debugger for the following tasks:
o
o System code debugging with the System Code Debugger (SCD)
(Alpha only)
o System dump analysis with the System Dump Debugger (SDD)
(Alpha only)
o Process dump analysis with the System Dump Analyzer (SDA)
(Alpha only)
This gives you access to all SDA commands within the debugging
session. When you exit SDA, you return to the same debugging
session. Note that you do not have access to debugger commands
within the SDA session.
NOTE
The SDA command is not available when debugging user-mode
programs.
Related commands
ANALYZE/CRASH_DUMP
ANALYZE/PROCESS_DUMP
CONNECT %NODE
3 Example
DBG> SDA
OpenVMS (TM) Alpha process dump analyzer
SDA> ..
.
.
SDA> EXIT
DBG>
This example opens an SDA session within the OpenVMS debugger,
performs some analysis, closes the SDA session and returns
control to the debugger.
DBG> SDA SHOW PROCESS
.
.
DBG>
This example show the execution of a single SDA command from
within the debugger, followed by a return of control to the
debugger.
2 SELECT
Selects a screen display as the current error, input,
instruction, output, program, prompt, scrolling, or source
display.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SELECT [display-name]
3 Parameters
display-name
Specifies the display to be selected. You can specify any one
of the following, with the restrictions noted in the qualifier
descriptions:
o A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG
o A display previously created with the DISPLAY command
o A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you omit this parameter and do not specify a qualifier, you
"unselect" the current scrolling display (no display then has the
scrolling attribute). If you omit this parameter but specify a
qualifier (/INPUT, /SOURCE, and so on), you unselect the current
display with that attribute (see the qualifier descriptions).
3 Qualifiers
/ERROR
Selects the specified display as the current error display. This
causes all debugger diagnostic messages to go to that display.
The display specified must be either an output display or the
PROMPT display. If you do not specify a display, this qualifier
selects the PROMPT display current error display. By default, the
PROMPT display has the error attribute.
/INPUT
Selects the specified display as the current input display. This
causes that display to echo debugger input (which appears in the
PROMPT display). The display specified must be an output display.
If you do not specify a display, the current input display
is unselected and debugger input is not echoed to any display
(debugger input appears only in the PROMPT display). By default,
no display has the input attribute.
/INSTRUCTION
Selects the specified display as the current instruction display.
This causes the output of all EXAMINE/INSTRUCTION commands to
go to that display. The display specified must be an instruction
display.
If you do not specify a display, the current instruction display
is unselected and no display has the instruction attribute.
By default, for all languages except MACRO-32, no display has the
instruction attribute. If the language is set to MACRO-32, the
INST display has the instruction attribute by default.
/OUTPUT
Selects the specified display as the current output display. This
causes debugger output that is not already directed to another
display to go to that display. The display specified must be
either an output display or the PROMPT display.
If you do not specify a display, the PROMPT display is selected
as the current output display. By default, the OUT display has
the output attribute.
/PROGRAM
Selects the specified display as the current program display.
This causes the debugger to try to force program input and
output to that display. Currently, only the PROMPT display can
be specified.
If you do not specify a display, the current program display is
unselected and program input and output are no longer forced to
the specified display.
By default, the PROMPT display has the program attribute, except
on workstations, where the program attribute is unselected.
/PROMPT
Selects the specified display as the current prompt display.
This is where the debugger prompts for input. Currently, only the
PROMPT display can be specified. Moreover, you cannot unselect
the PROMPT display (the PROMPT display always has the prompt
attribute).
/SCROLL
(Default) Selects the specified display as the current scrolling
display. This is the default display for the SCROLL, MOVE,
and EXPAND commands. Although any display can have the scroll
attribute, you can use only the MOVE and EXPAND commands (not the
SCROLL command) with the PROMPT display.
If you do not specify a display, the current scrolling display is
unselected and no display has the scroll attribute.
By default, for all languages except MACRO-32, the SRC display
has the scroll attribute. If the language is set to MACRO-32, the
INST display has the scroll attribute by default.
/SOURCE
Selects the specified display as the current source display. This
causes the output of all TYPE and EXAMINE/SOURCE commands to go
to that display. The display specified must be a source display.
If you do not specify a display, the current source display is
unselected and no display has the source attribute.
By default, for all languages except MACRO-32, the SRC display
has the source attribute. If the language is set to MACRO-32, no
display has the source attribute by default.
3 Description
Attributes are used to select the current scrolling display
and to direct various types of debugger output to particular
displays. This gives you the option of mixing or isolating
different types of information, such as debugger input, output,
diagnostic messages, and so on in scrollable displays.
Use the SELECT command with one or more qualifiers (/ERROR,
/SOURCE, and so on) to assign one or more corresponding
attributes to a display. By default, if you do not specify a
qualifier, /SCROLL is assumed.
If you use the SELECT command without specifying a display name,
the attribute assignment indicated by the qualifier is canceled
(unselected). To reassign display attributes, you must use
another SELECT command. For more information, see the individual
qualifier.
For a list of the key definitions associated with the SELECT
command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY
command to determine the current key definitions.
Related commands:
DISPLAY
EXPAND
MOVE
SCROLL
SHOW SELECT
3 Examples
1.DBG> SELECT/SOURCE/SCROLL SRC2
This command selects display SRC2 as the current source and
scrolling display.
2.DBG> SELECT/INPUT/ERROR OUT
This command selects display OUT as the current input and
error display. This causes debugger input, debugger output
(assuming OUT is the current output display), and debugger
diagnostic messages to be logged in the OUT display in the
correct sequence.
3.DBG> SELECT/SOURCE
This command unselects (deletes the source attribute from)
the currently selected source display. The output of a TYPE
or EXAMINE/SOURCE command then goes to the currently selected
output display.
2 SET
3 ABORT_KEY
Assigns the debugger's abort function to another Ctrl-key
sequence. By default, Ctrl/C does the abort function.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SET ABORT_KEY = CTRL_character
4 Parameters
character
Specifies the key you press while holding down the Ctrl key. You
can specify any alphabetic character.
4 Description
By default, the Ctrl/C sequence, when entered within a debugging
session, aborts the execution of a debugger command and
interrupts program execution. The SET ABORT_KEY command enables
you to assign the abort function to another Ctrl-key sequence.
This might be necessary if your program has a Ctrl/C AST service
routine enabled.
Many Ctrl-key sequences have predefined functions, and the SET
ABORT_KEY command enables you to override such definitions (see
the OpenVMS User's Manual). Some of the Ctrl-key characters not
used by the operating system are G, K, N, and P.
The SHOW ABORT_KEY command identifies the Ctrl-key sequence
currently in effect for the abort function.
Do not use Ctrl/Y from within a debugging session. Instead, use
either Ctrl/C or an equivalent Ctrl-key sequence established with
the SET ABORT_KEY command.
Related commands:
Ctrl/C
Ctrl/Y
SHOW ABORT_KEY
4 Example
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> GO
. . .
<Ctrl/C>
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
<Ctrl/C>
%DEBUG-W-ABORTED, command aborted by user request
DBG> SET ABORT_KEY = CTRL_P
DBG> GO
. . .
<Ctrl/P>
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
<Ctrl/P>
%DEBUG-W-ABORTED, command aborted by user request
DBG>
This example shows the following:
o Use of Ctrl/C for the abort function (default).
o Use of the SET ABORT_KEY command to reassign the abort
function to Ctrl/P.
3 ATSIGN
Establishes the default file specification that the debugger uses
when searching for command procedures.
Format
SET ATSIGN file-spec
4 Parameters
file-spec
Specifies any part of a file specification (for example, a
directory name or a file type) that the debugger is to use
by default when searching for a command procedure. If you do
not supply a full file specification, the debugger assumes
SYS$DISK:[]DEBUG.COM as the default file specification for any
missing field.
You can specify a logical name that translates to a search list.
In this case, the debugger processes the file specifications
in the order they appear in the search list until the command
procedure is found.
4 Description
When you invoke a debugger command procedure with the execute
procedure (@) command, the debugger assumes, by default, that the
command procedure file specification is SYS$DISK:[]DEBUG.COM. The
SET ATSIGN command enables you to override this default.
Related commands:
@ (Execute Procedure)
SHOW ATSIGN
4 Example
DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> @TEST
In this example, when you use the @TEST command, the debugger
looks for the file TEST.DBG in USER:[JONES.DEBUG].
3 BREAK
Establishes a breakpoint at the location denoted by an address
expression, at instructions of a particular class, or at the
occurrence of specified events.
Format
SET BREAK [address-expression[, . . . ]]
[WHEN(conditional-expression)]
[DO(command[; . . . ])]
4 Parameters
address-expression
Specifies an address expression (a program location) at which
a breakpoint is to be set. With high-level languages, this
is typically a line number, a routine name, or a label, and
can include a path name to specify the entity uniquely. More
generally, an address expression can also be a memory address or
a register and can be composed of numbers (offsets) and symbols,
as well as one or more operators, operands, or delimiters. For
information about the operators that you can use in address
expressions, see the Address_Expressions help topic.
Do not specify the asterisk (*) wildcard character. Do not
specify an address expression with any of the following
qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/HANDLER
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/INTO
/[NO]JSB (VAX only)
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/SYSEMULATE (Alpha only)
/TERMINATING
/UNALIGNED_DATA (Alpha only)
/VECTOR_INSTRUCTION (VAX only)
The /MODIFY and /RETURN qualifiers are used with specific kinds
of address expressions.
If you specify a memory address or an address expression whose
value is not a symbolic location, check (with the EXAMINE
command) that an instruction actually begins at the byte of
memory so indicated. If an instruction does not begin at this
byte, a run-time error can occur when an instruction including
that byte is executed. When you set a breakpoint by specifying
an address expression whose value is not a symbolic location, the
debugger does not verify that the location specified marks the
beginning of an instruction.
On VAX systems, CALLS and CALLG routines start with an entry
mask.
conditional-expression
Specifies a conditional expression in the currently set
language that is to be evaluated whenever execution reaches the
breakpoint. (The debugger checks the syntax of the expressions in
the WHEN clause when execution reaches the breakpoint, not when
the breakpoint is set.) If the expression is true, the debugger
reports that a breakpoint has been triggered. If an action (DO
clause) is associated with the breakpoint, it will occur at this
time. If the expression is false, a report is not issued, the
commands specified by the DO clause (if one was specified) are
not executed, and program execution is continued.
command
Specifies a debugger command to be executed as part of the DO
clause when break action is taken. The debugger checks the syntax
of the commands in a DO clause when it executes the DO clause,
not when the breakpoint is set.
4 Qualifiers
/ACTIVATING
Causes the debugger to break when a new process comes under
debugger control. The debugger prompt is displayed when the first
process comes under debugger control. This enables you to enter
debugger commands before the program has started execution. See
also the /TERMINATING qualifier.
/AFTER
/AFTER:n
Specifies that break action not be taken until the nth time the
designated breakpoint is encountered (n is a decimal integer).
Thereafter, the breakpoint occurs every time it is encountered
provided that conditions in the WHEN clause (if specified) are
true. The SET BREAK/AFTER:1 command has the same effect as SET
BREAK.
/BRANCH
Causes the debugger to break on every branch instruction
encountered during program execution. See also the /INTO and
/OVER qualifiers.
/CALL
Causes the debugger to break on every call instruction
encountered during program execution, including the RET
instruction. See also the /INTO and /OVER qualifiers.
/EVENT
/EVENT=event-name
Causes the debugger to break on the specified event (if that
event is defined and detected by the current event facility).
If you specify an address expression with /EVENT, causes the
debugger to break whenever the specified event occurs for that
address expression. You cannot specify an address expression with
certain event names.
Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX Threads services. Use the SHOW EVENT_
FACILITY command to identify the current event facility and the
associated event names.
/EXCEPTION
Causes the debugger to break whenever an exception is signaled.
The break action occurs before any application-declared exception
handlers are invoked.
As a result of a SET BREAK/EXCEPTION command, whenever your
program generates an exception, the debugger suspends program
execution, reports the exception, and displays its prompt. When
you resume execution from an exception breakpoint, the behavior
is as follows:
o If you enter a GO command without an address-expression
parameter, the exception is resignaled, thus allowing any
application-declared exception handler to execute.
o If you enter a GO command with an address-expression
parameter, program execution continues at the specified
location, thus inhibiting the execution of any application-
declared exception handler.
o On VAX, if you enter a STEP command, the debugger steps into
any application-declared exception handler. If there is no
application-declared handler for that exception, the debugger
resignals the exception.
On Alpha, you must explicitly set a breakpoint in the
exception handler before entering a STEP or a GO command to
get the debugger to suspend execution within the handler.
o If you enter a CALL command, the routine specified is
executed.
On Alpha processors, an exception might not be delivered (to
the program or debugger) immediately after the execution of the
instruction that caused the exception. Therefore, the debugger
might suspend execution on an instruction beyond the one that
actually caused the exception.
/HANDLER
Causes the debugger to scan the call stack and attempt to set
a breakpoint on every established frame-based handler whenever
the program being debugged has an exception. The debugger does
not discriminate between standard RTL handlers and user-defined
handlers.
On Alpha systems, many RTLs establish a jacket RTL handler on a
frame where the user program has defined its own handler. This
RTL jacket does some setup and argument manipulation before
actually calling the handler defined by the user. When processing
the exception, the debugger sets the breakpoint on the jacket RTL
jacket handler, because that is the address on the call stack. If
the debugger suspends program execution at a jacket RTL handler,
you can usually reach the user-defined handler by entering a
STEP/CALL command followed by a STEP/INTO command. Some cases
might require that you enter additional sequences of STEP/CALL
and STEP/INTO commands. See the OpenVMS Calling Standard for more
information on frame-based handlers.
If the jacket RTL handler is part of an installed shared image
such as ALPHA LIBOTS, the debugger cannot set a breakpoint on it.
In this case, activate the RTL as a private image by defining the
RTL as a logical name. For example:
$DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;
Note that the trailing semicolon (;) is required.
/INSTRUCTION
/INSTRUCTION
/INSTRUCTION[=(opcode[, . . . ])]
When you do not specify an opcode, causes the debugger to break
on every instruction encountered during program execution.
On VAX processors only, you can optionally specify one or more
opcodes. This causes the debugger to break on every instruction
with an opcode that is on the list.
If you specify a vector instruction (VAX only), do not include
an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION,
/MODIFY, /0, or /1) with the instruction mnemonic.
See also the /INTO and /OVER qualifiers.
/INTO
(Default) Applies only to breakpoints set with the following
qualifiers (that is, when an address expression is not explicitly
specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
When used with those qualifiers, /INTO causes the debugger to
break at the specified points within called routines (as well as
within the routine in which execution is currently suspended).
The /INTO qualifier is the default and is the opposite of /OVER.
When using /INTO, you can further qualify the break action with
/[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM.
/JSB
/JSB
/NOJSB
(VAX only) Qualifies /INTO. Use with /INTO and one of the
following qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ])
/LINE
/VECTOR_INSTRUCTION
The /JSB qualifier is the default for all languages except DIBOL.
It lets the debugger break within routines that are called by the
JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default)
specifies that breakpoints not be set within routines called
by JSB instructions. In DIBOL, application-declared routines
are called by the CALL instruction and DIBOL Run-Time Library
routines are called by the JSB instruction.
/LINE
Causes the debugger to break on the beginning of each source
line encountered during program execution. See also the /INTO and
/OVER qualifiers.
/MODIFY
Causes the debugger to break on every instruction that writes to
and modifies the value of the location indicated by the address
expression. The address expression is typically a variable name.
The SET BREAK/MODIFY command acts exactly like a SET WATCH
command and operates under the same restrictions.
If you specify an absolute address for the address expression,
the debugger might not be able to associate the address with
a particular data object. In this case, the debugger uses a
default length of 4 bytes. You can change this length, however,
by setting the type to either WORD (SET TYPE WORD, which changes
the default length to 2 bytes) or BYTE (SET TYPE BYTE, which
changes the default length to 1 byte). SET TYPE LONGWORD restores
the default length of 4 bytes.
/OVER
Applies only to breakpoints set with the following qualifiers
(that is, when an address expression is not explicitly
specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
When used with those qualifiers, /OVER causes the debugger to
break at the specified points only within the routine in which
execution is currently suspended (not within called routines).
The /OVER qualifier is the opposite of /INTO (which is the
default).
/RETURN
Causes the debugger to break on the return instruction of the
routine associated with the specified address expression (which
can be a routine name, line number, and so on). Breaking on the
return instruction enables you to inspect the local environment
(for example, obtain the values of local variables) while
the routine is still active. Note that the view of a local
environment may differ depending on your architecture.
On VAX processors, this qualifier can only be applied to routines
called with a CALLS or CALLG instruction; it cannot be used with
JSB routines. On Alpha processors, this qualifier can be applied
to any routine.
The address-expression parameter is an instruction address within
a routine. It can simply be a routine name, in which case it
specifies the routine start address. However, you can also
specify another location in a routine, so you can see only those
returns that are taken after a certain code path is followed.
A SET BREAK/RETURN command cancels a previous SET BREAK if you
specify the same address expression.
/SHARE
/SHARE (default)
/NOSHARE
Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
The /SHARE qualifier permits the debugger to break within
shareable image routines as well as other routines. The /NOSHARE
qualifier specifies that breakpoints not be set within shareable
images.
/SILENT
/SILENT
/NOSILENT (default)
Controls whether the "break . . . " message and the source line
for the current location are displayed at the breakpoint. The
/NOSILENT qualifier specifies that the message is displayed. The
/SILENT qualifier specifies that the message and the source line
are not displayed. The /SILENT qualifier overrides /SOURCE. See
also the SET STEP [NO]SOURCE command.
/SOURCE
/SOURCE (default)
/NOSOURCE
Controls whether the source line for the current location is
displayed at the breakpoint. The /SOURCE qualifier specifies that
the source line is displayed. The /NOSOURCE qualifier specifies
that no source line is displayed. The /SILENT qualifier overrides
/SOURCE. See also the SET STEP [NO]SOURCE command.
/SYSEMULATE
/SYSEMULATE[=mask]
(Alpha only) Stops program execution and returns control to the
debugger after the operating system emulates an instruction.
The optional argument mask is an unsigned quadword with bits
set to specify which emulated instruction groups shall cause
breakpoints. The only emulated instruction group currently
defined consists of the BYTE and WORD instructions. Select this
instruction group by setting bit 0 of mask to 1.
If mask is not specified or if mask = FFFFFFFFFFFFFFFF, the
debugger stops program execution when the operating system
emulates any instruction.
/SYSTEM
/SYSTEM (default)
/NOSYSTEM
Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
The /SYSTEM qualifier permits the debugger to break within system
routines (P1 space) as well as other routines. The /NOSYSTEM
qualifier specifies that breakpoints not be set within system
routines.
/TEMPORARY
Causes the breakpoint to disappear after it is triggered (the
breakpoint does not remain permanently set).
/TERMINATING
Causes the debugger to break when a process does an image exit.
The debugger gains control and displays its prompt when the
last image of a one-process or multiprocess program exits. A
process is terminated when the image has executed the $EXIT
system service and all of its exit handlers have executed. See
also the /ACTIVATING qualifier.
/UNALIGNED_DATA
(Alpha only) Causes the debugger to break directly after any
instruction that accesses unaligned data (for example, after a
load word instruction that accesses data that is not on a word
boundary).
/VECTOR_INSTRUCTION
(VAX only) Causes the debugger to break on every vector
instruction encountered during program execution. See also the
/INTO and /OVER qualifiers.
4 Description
When a breakpoint is triggered, the debugger takes the following
actions:
1. Suspends program execution at the breakpoint location.
2. If you specified /AFTER when you set the breakpoint, checks
the AFTER count. If the specified number of counts has not
been reached, execution resumes and the debugger does not do
the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the breakpoint. If the value of the
expression is false, execution resumes and the debugger does
not do the remaining steps.
4. Reports that execution has reached the breakpoint location by
issuing a "break . . . " message, unless you specified /SILENT.
5. Displays the line of source code at which execution is
suspended, unless you specified /NOSOURCE or /SILENT when
you set the breakpoint or unless you previously entered SET
STEP NOSOURCE.
6. Executes the commands in a DO clause, if you specified one
when you set the breakpoint. If the DO clause contains a GO
command, execution continues and the debugger does not perform
the next step.
7. Issues the prompt.
You set a breakpoint at a particular location in your program
by specifying an address expression with the SET BREAK command.
You set a breakpoint on consecutive source lines, classes of
instructions, or events by specifying a qualifier with the SET
BREAK command. Generally, you must specify either an address
expression or a qualifier, but not both. Exceptions are /EVENT
and /RETURN.
The /LINE qualifier sets a breakpoint on each line of source
code.
The following qualifiers set breakpoints on classes of
instructions. Using these qualifiers with /LINE causes the
debugger to trace every instruction of your program as it
executes and thus significantly slows down execution:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/RETURN
/VECTOR_INSTRUCTION (VAX only)
The following qualifiers set breakpoints on classes of events:
/ACTIVATING
/EVENT=event-name
/EXCEPTION
/SYSEMULATE (Alpha only)
/TERMINATING
/UNALIGNED_DATA (Alpha only)
The following qualifiers affect what happens at a routine call:
/INTO
/[NO]JSB (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM
4 Description,_Continued...
The following qualifiers affect what output is displayed when a
breakpoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of
breakpoints:
/AFTER:n
/TEMPORARY
Use the /MODIFY qualifier to monitor changes at program locations
(typically changes in the values of variables).
If you set a breakpoint at a location currently used as
a tracepoint, the tracepoint is canceled in favor of the
breakpoint, and vice versa.
On OpenVMS Alpha systems, the SET BREAK/UNALIGNED_DATA command
calls the $START_ALIGN_FAULT_REPORT system service routine. Do
not issue this command if the program you are debugging includes
a call to the same $START_ALIGN_FAULT_REPORT routine. If you
issue the command before the program call, the program call
fails. If the program call occurs before you issue the command,
unaligned breaks are not set.
Breakpoints can be user defined or predefined. User-defined
breakpoints are set explicitly with the SET BREAK command.
Predefined breakpoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are established
automatically when you start the debugger. Use the SHOW BREAK
command to identify all breakpoints that are currently set. Any
predefined breakpoints are identified as such.
User-defined and predefined breakpoints are set and canceled
independently. For example, a location or event can have both
a user-defined and a predefined breakpoint. Canceling the user-
defined breakpoint does not affect the predefined breakpoint, and
conversely.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) BREAK
CANCEL ALL
GO
(SET,SHOW) EVENT_FACILITY
SET STEP [NO]SOURCE
SET TRACE
SET WATCH
STEP
4 Examples
1.DBG> SET BREAK SWAP\%LINE 12
This command causes the debugger to break on line 12 of module
SWAP.
2.DBG> SET BREAK/AFTER:3 SUB2
This command causes the debugger to break on the third and
subsequent times that SUB2 (a routine) is executed.
3.DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAM D; STEP; EXAM Y; GO)
This command causes the debugger to break at location LOOP1. At
the breakpoint, the following commands are issued, in the order
given: (1) EXAMINE D, (2) STEP, (3) EXAMINE Y, and (4) GO.
The /NOSOURCE qualifier suppresses the display of source code
at the breakpoint.
4.DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y)
This command causes the debugger to break on routine ROUT3 when
X is greater than 4. At the breakpoint, the EXAMINE Y command
is issued. The syntax of the conditional expression in the WHEN
clause is language-dependent.
5.DBG> SET BREAK/TEMPORARY 1440
DBG> SHOW BREAK
breakpoint at 1440 [temporary]
DBG>
This command sets a temporary breakpoint at memory address
1440. After that breakpoint is triggered, it disappears.
6.DBG> SET BREAK/LINE
This command causes the debugger to break on the beginning of
every source line encountered during program execution.
7.DBG> SET BREAK/LINE WHEN (X .NE. 0)
DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 0)
These two commands cause the debugger to break when X is not
equal to 0. The first command tests for the condition at the
beginning of every source line encountered during execution.
The second command tests for the condition at each instruction.
The syntax of the conditional expression in the WHEN clause is
language-dependent.
8.DBG> SET BREAK/RETURN ROUT4
This command causes the debugger to break whenever the return
instruction of routine ROUT4 is about to be executed.
9.DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS)
This command causes the debugger to break whenever an exception
is signaled. At the breakpoint, the SET MODULE/CALLS and SHOW
CALLS commands are issued.
10all> SET BREAK/ACTIVATING
This command causes the debugger to break whenever a process of
a multiprocess program is brought under debugger control.
3 DEFINE
Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_
GROUP, or /VALUE) for the DEFINE command.
Format
SET DEFINE define-default
4 Parameters
define-default
Specifies the default to be established for the DEFINE command.
Valid keywords (which correspond to DEFINE command qualifiers)
are as follows:
ADDRESS Subsequent DEFINE commands are treated as
DEFINE/ADDRESS. This is the default.
COMMAND Subsequent DEFINE commands are treated as
DEFINE/COMMAND.
PROCESS_SET Subsequent DEFINE commands are treated as
DEFINE/PROCESS_SET.
VALUE Subsequent DEFINE commands are treated as
DEFINE/VALUE.
4 Description
The SET DEFINE command establishes a default qualifier for
subsequent DEFINE commands. The parameters that you specify in
the SET DEFINE command have the same names as the qualifiers for
the DEFINE command. The qualifiers determine whether the DEFINE
command binds a symbol to an address, a command string, a list of
processes, or a value.
You can override the current DEFINE default for the duration of
a single DEFINE command by specifying another qualifier. Use the
SHOW DEFINE command to identify the current DEFINE defaults.
Related commands:
DEFINE
DEFINE/PROCESS_SET
DELETE
SHOW DEFINE
SHOW SYMBOL/DEFINED
4 Example
DBG> SET DEFINE VALUE
The SET DEFINE VALUE command specifies that subsequent DEFINE
commands are treated as DEFINE/VALUE.
3 EDITOR
Establishes the editor that is started by the EDIT command.
Format
SET EDITOR [command-line]
4 Parameters
command-line
Specifies a command line to start a particular editor on your
system when you use the EDIT command.
You need not specify a command line if you use /CALLABLE_EDT,
/CALLABLE_LSEDIT, or /CALLABLE_TPU. If you do not use one of
these qualifiers, the editor specified in the SET EDITOR command
line is spawned to a subprocess when you enter the EDIT command.
You can specify a command line with /CALLABLE_LSEDIT or
/CALLABLE_TPU but not with /CALLABLE_EDT.
4 Qualifiers
/CALLABLE_EDT
Specifies that the callable version of the EDT editor is started
when you use the EDIT command. Do not specify a command line with
this qualifier (a command line of "EDT" is used).
/CALLABLE_LSEDIT
(VAX only) Specifies that the callable version of the DEC
Language-Sensitive Editor (LSEDIT) is started when you use the
EDIT command. If you also specify a command line, it is passed
to callable LSEDIT. If you do not specify a command line, the
default command line is LSEDIT.
/CALLABLE_TPU
Specifies that the callable version of the DEC Text Processing
Utility (DECTPU) is started when you use the EDIT command. If you
also specify a command line, it is passed to callable DECTPU. If
you do not specify a command line, the default command line is
TPU.
/START_POSITION
/START_POSITION
/NOSTART_POSITION (default)
Controls whether the /START_POSITION qualifier is appended
to the specified or default command line when you enter the
EDIT command. Currently, only DECTPU and the DEC Language-
Sensitive Editor (specified as TPU or /CALLABLE_TPU, and LSEDIT
or /CALLABLE_LSEDIT, respectively) support this qualifier.
The /START_POSITION qualifier affects the initial position of
the editor's cursor. By default (/NOSTART_POSITION), the editor's
cursor is placed at the beginning of source line 1, regardless
of which line is centered in the debugger's source display or
whether you specify a line number in the EDIT command. If you
specify /START_POSITION, the cursor is placed either on the
line whose number you specify in the EDIT command, or (if you
do not specify a line number) on the line that is centered in the
current source display.
4 Description
The SET EDITOR command enables you to specify any editor that is
installed on your system. In general, the command line specified
as parameter to the SET EDITOR command is spawned and executed in
a subprocess.
On VAX processors, if you use EDT, LSEDIT, or DECTPU, you can
start these editors in a more efficient way. You can specify
/CALLABLE_EDT, /CALLABLE_LSEDIT, or /CALLABLE_TPU, which causes
the callable versions of EDT, LSEDIT, and DECTPU, respectively,
to be invoked by the EDIT command. In the case of LSEDIT and
DECTPU, you can also specify a command line that is executed by
the callable editor.
On Alpha processors, you can use /CALLABLE_EDT or /CALLABLE_TPU,
but not /CALLABLE_LSEDIT.
Related commands:
EDIT
(SET,SHOW,CANCEL) SOURCE
SHOW DEFINE
4 Examples
1.DBG> SET EDITOR '@MAIL$EDIT ""'
This command causes the EDIT command to spawn the command line
'@MAIL$EDIT ""', which starts the same editor as you use in
MAIL.
2.DBG> SET EDITOR/CALLABLE_TPU
This command causes the EDIT command to start callable DECTPU
with the default command line of TPU.
3.DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION
This command causes the EDIT command to start callable DECTPU
with the command line TPU/SECTION=MYSECINI.TPU$SECTION.
4.DBG> SET EDITOR/CALLABLE_EDT/START_POSITION
This command causes the EDIT command to start callable EDT
with the default command line of EDT. Also the /START_POSITION
qualifier is appended to the command line, so that the editing
session starts on the source line that is centered in the
debugger's current source display.
3 EVENT_FACILITY
Establishes the current event facility.
Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX Threads services.
Format
SET EVENT_FACILITY facility-name
4 Parameters
facility-name
Specifies an event facility. Valid facility-name keywords are as
follows:
ADA If the event facility is set to ADA, the (SET,CANCEL)
BREAK and (SET,CANCEL) TRACE commands recognize Ada-
specific events as well as generic, low-level task
events. (Ada events consist of task and exception
events.)
You can set the event facility to ADA only if the main
program is written in Ada or if the program calls an
Ada routine.
THREADS If the event facility is set to THREADS, the
(SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands
recognize POSIX Threads-specific as well as generic,
low-level task events. All POSIX Threads events are
task (thread) events.
You can set the event facility to THREADS only if
the shareable image CMA$RTL is currently part of the
program's process (if that image is listed in a SHOW
IMAGE display).
SCAN (VAX only) If the event facility is set to SCAN, the
(SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands
recognize SCAN (pattern-matching) events.
You can set the event facility to SCAN only if the main
program is written in SCAN or if the program calls a
SCAN routine.
4 Description
The current event facility (ADA, THREADS, or SCAN) defines the
eventpoints that you can set with the SET BREAK/EVENT and SET
TRACE/EVENT commands.
When started with a program that is linked with an event
facility, the debugger automatically sets the facility in a
manner appropriate for the type of program. For example, if the
main program is written in Ada or SCAN, the event facility is set
to ADA or SCAN, respectively.
The SET EVENT_FACILITY command enables you to change the event
facility and thereby change your debugging context. This is
useful if you have a multilanguage program and want to debug
a routine that is associated with an event facility but that
facility is not currently set.
On VAX processors, you cannot use both Ada and POSIX Threads
tasking services in the same program. This implies that you can
change the event facility only from ADA to SCAN or from POSIX
Threads to SCAN, or conversely.
Use the SHOW EVENT_FACILITY command to identify the event
names associated with the current event facility. These are the
keywords that you can specify with the (SET,CANCEL) BREAK/EVENT
and (SET,CANCEL) TRACE/EVENT commands.
Related commands:
(SET,CANCEL) BREAK/EVENT
(SET,CANCEL) TRACE/EVENT
SHOW BREAK
SHOW EVENT_FACILITY
SHOW IMAGE
SHOW TASK
SHOW TRACE
4 Example
DBG> SET EVENT_FACILITY THREADS
This command establishes THREADS (POSIX Threads) as the current
event facility.
3 IMAGE
Loads symbol information for one or more shareable images and
establishes the current image.
Format
SET IMAGE [image-name[, . . . ]]
4 Parameters
image-name
Specifies a shareable image to be set. Do not use the asterisk
(*) wildcard character. Instead, use the /ALL qualifier. Do not
specify an image name with /ALL.
4 Qualifiers
/ALL
Specifies that all shareable images are set.
4 Description
The SET IMAGE command builds data structures for one or more
specified images but does not set any modules within the images
specified.
The current image is the current debugging context: you have
access to symbols in the current image. If you specify only one
image with the SET IMAGE command, that image becomes the current
image. If you specify a list of images, the last one in the list
becomes the current image. If you specify /ALL, the current image
is unchanged.
Before an image can be set with the SET IMAGE command, it must
have been linked with the /DEBUG or /TRACEBACK qualifier on the
DCL command LINK. If an image was linked /NOTRACEBACK, no symbol
information is available for that image and you cannot specify it
with the SET IMAGE command.
Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE
commands are available only when the image in whose context they
were created is the current image. When you use the SET IMAGE
command to establish a new current image, these definitions are
temporarily unavailable. However, definitions created with the
DEFINE/COMMAND and DEFINE/KEY commands are available for all
images.
Related commands:
SET MODE [NO]DYNAMIC
(SET,SHOW,CANCEL) MODULE
(SHOW,CANCEL) IMAGE
4 Example
DBG> SET IMAGE SHARE1
DBG> SET MODULE SUBR
DBG> SET BREAK SUBR
This sequence of commands shows how to set a breakpoint on
routine SUBR in module SUBR of shareable image SHARE1. The SET
IMAGE command sets the debugging context to SHARE1. The SET
MODULE command loads the symbol records of module SUBR into
the run-time symbol table (RST). The SET BREAK command sets a
breakpoint on routine SUBR.
3 KEY
Establishes the current key state.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SET KEY
4 Qualifiers
/LOG
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the key
state has been set. The /LOG qualifier displays the message. The
/NOLOG qualifier suppresses the message.
/STATE
/STATE[=state-name]
/NOSTATE (default)
Specifies a key state to be established as the current state.
You can specify a predefined key state, such as GOLD, or
a user-defined state. A state name can be any appropriate
alphanumeric string. The /NOSTATE qualifier leaves the current
state unchanged.
4 Description
Keypad mode must be enabled (SET MODE KEYPAD) before you can use
this command. Keypad mode is enabled by default.
By default, the current key state is the DEFAULT state. When
you define function keys, you can use the DEFINE/KEY /IF_STATE
command to assign a specific state name to the key definition.
If that state is not set when you press the key, the definition
is not processed. The SET KEY/STATE command enables you to change
the current state to the appropriate state.
You can also change the current state by pressing a key
that causes a state change (a key that was defined with
DEFINE/KEY/LOCK_STATE/SET_STATE).
Related commands:
DELETE/KEY
DEFINE/KEY
SHOW KEY
4 Example
DBG> SET KEY/STATE=PROG3
This command changes the key state to the PROG3 state. You
can now use the key definitions that are associated with this
state.
3 LANGUAGE
Establishes the current language.
Format
SET LANGUAGE language-name
4 Parameters
language-name
Specifies a language.
On VAX processors, valid keywords are:
ADA BASIC BLISS C
C_PLUS_PLUS COBOL DIBOL FORTRAN
MACRO PASCAL PLI RPG
SCAN UNKNOWN
On Alpha processors, valid keywords are:
ADA AMACRO BASIC BLISS
C C_PLUS_PLUS COBOL FORTRAN
MACRO MACRO64 PASCAL PLI
UNKNOWN
4 Description
When you start the debugger, the current language is set to that
in which the module containing the main program is written. This
is usually the module containing the image transfer address. To
debug a module written in a different source language from that
of the main program, you can change the language with the SET
LANGUAGE command.
The current language setting determines how the debugger parses
and interprets the names, operators, and expressions you specify
in debugger commands, including things like the typing of
variables, array and record syntax, the default radix for the
entry and display of integer data, case sensitivity, and so on.
The language setting also determines how the debugger formats and
displays data associated with your program.
The default radix for both data entry and display is decimal for
most languages. On VAX processors, the exceptions are BLISS and
MACRO-32, which have a default radix of hexadecimal. On Alpha
processors, the exceptions are BLISS, MACRO-32, and MACRO-64,
which have a default radix of hexadecimal.
The default type for program locations that do not have a
compiler-generated type is longword integer. This is appropriate
for debugging 32-bit applications. It might be advisable to
change the default type to quadword for debugging applications
that use the 64-bit address space. Use the SET TYPE QUADWORD
command.
Use the SET LANGUAGE UNKNOWN command when debugging a program
written in an unsupported language. To maximize the usability
of the debugger with unsupported languages, SET LANGUAGE UNKNOWN
causes the debugger to accept a large set of data formats and
operators, including some that might be specific to only a few
supported languages.
Note that SET LANGUAGE UNKNOWN can be an easy, quick workaround
for language-related problems because it uses the "loosest" set
of rules.
For information about debugger support for language-specific
operators and constructs, see the Language_Support help topic.
Related commands:
EVALUATE
EXAMINE
DEPOSIT
SET MODE
SET RADIX
SET TYPE
SHOW LANGUAGE
4 Examples
1.DBG> SET LANGUAGE COBOL
This command establishes COBOL as the current language.
2.DBG> SET LANGUAGE PASCAL
This command establishes Pascal as the current language.
4 /DYNAMIC
Toggles the state of automatic language setting.
Format
SET LANGUAGE/DYNAMIC
5 Description
When you start the debugger, the current language is set to that
in which the module containing the main program is written. This
is usually the module containing the image transfer address. By
default, when the scope of the program being executed changes to
a module written in a different language, the debugger changes
the current language to that of the module.
You can prevent the debugger from automatically changing the
current language with the SET LANGUAGE/NODYNAMIC command.
Related commands:
SET LANGUAGE
SHOW LANGUAGE
5 Examples
1.DBG> SET LANGUAGE/NODYNAMIC
This command prevents the debugger from changing the current
language until you enter a SET LANGUAGE or SET LANGUAGE/DYNAMIC
command.
3 LOG
Specifies a log file to which the debugger writes after a SET
OUTPUT LOG command has been entered.
Format
SET LOG file-spec
4 Parameters
file-spec
Denotes the file specification of the log file. If you do
not supply a full file specification, the debugger assumes
SYS$DISK:[]DEBUG.LOG as the default file specification for any
missing field.
If you specify a version number and that version of the file
already exists, the debugger writes to the file specified,
appending the log of the debugging session onto the end of that
file.
4 Description
The SET LOG command determines only the name of a log file; it
does not cause the debugger to create or write to the specified
file. The SET OUTPUT LOG command accomplishes that.
If you entered a SET OUTPUT LOG command but no SET LOG command,
the debugger writes to the file SYS$DISK:[]DEBUG.LOG by default.
If the debugger is writing to a log file and you specify another
log file with the SET LOG command, the debugger closes the former
file and begins writing to the file specified in the SET LOG
command.
Related commands:
SET OUTPUT LOG
SET OUTPUT SCREEN_LOG
SHOW LOG
4 Examples
1.DBG> SET LOG CALC
DBG> SET OUTPUT LOG
In this example, the SET LOG command specifies the debugger
log file to be SYS$DISK:[]CALC.LOG. The SET OUTPUT LOG command
causes user input and debugger output to be logged to that
file.
2.DBG> SET LOG [CODEPROJ]FEB29.TMP
DBG> SET OUTPUT LOG
In this example, the SET LOG command specifies the debugger
log file to be [CODEPROJ]FEB29.TMP. The SET OUTPUT LOG command
causes user input and debugger output to be logged to that
file.
3 MARGINS
Specifies the leftmost and rightmost source-line character
position at which to begin and end display of a source line.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SET MARGINS rm
lm:rm
lm:
:rm
4 Parameters
lm
The source-line character position at which to begin display of
the line of source code (the left margin).
rm
The source-line character position at which to end display of the
line of source code (the right margin).
4 Description
The SET MARGINS command affects only the display of source lines.
It does not affect the display of other debugger output, as from
an EXAMINE command.
The SET MARGINS command is useful for controlling the display
of source code when, for example, the code is deeply indented
or long lines wrap at the right margin. In such cases, you can
set the left margin to eliminate indented space in the source
display, and you can decrease the right margin setting (from its
default value of 255) to truncate lines and prevent them from
wrapping.
The SET MARGINS command is useful mostly in line (noscreen) mode.
In line mode, the SET MARGINS command affects the display of
source lines resulting from a TYPE, EXAMINE/SOURCE, SEARCH, or
STEP command, or when a breakpoint, tracepoint, or watchpoint is
triggered.
In screen mode, the SET MARGINS command has no effect on
the display of source lines in a source display, such as the
predefined display SRC. Therefore it does not affect the output
of a TYPE or EXAMINE/SOURCE command, since that output is
directed at a source display. The SET MARGINS command affects
only the display of any source code that might appear in an
output or DO display (for example, after a STEP command has
been executed). However, such source-code display is normally
suppressed if you enable screen mode by pressing PF1-PF3, because
that sequence issues the SET STEP NOSOURCE command as well as SET
MODE SCREEN to eliminate redundant source display.
By default, the debugger displays a source line starting at
character position 1 of the source line. This is actually
character position 9 on your terminal screen. The first eight
character positions on the screen are reserved for the line
number and cannot be manipulated by the SET MARGINS command.
If you specify a single number, the debugger sets the left margin
to 1 and the right margin to the number specified.
If you specify two numbers, separated with a colon, the debugger
sets the left margin to the number on the left of the colon and
the right margin to the number on the right.
If you specify a single number followed by a colon, the debugger
sets the left margin to that number and leaves the right margin
unchanged.
If you specify a colon followed by a single number, the debugger
sets the right margin to that number and leaves the left margin
unchanged.
Related commands:
SET STEP [NO]SOURCE
SHOW MARGINS
4 Examples
1.DBG> SHOW MARGINS
left margin: 1 , right margin: 255
DBG> TYPE 14
module FORARRAY
14: DIMENSION IARRAY(4:5,5), VECTOR(10), I3D(3,3,4)
DBG>
This example displays the default margin settings for a line of
source code (1 and 255).
2.DBG> SET MARGINS 39
DBG> SHOW MARGINS
left margin: 1 , right margin: 39
DBG> TYPE 14
module FORARRAY
14: DIMENSION IARRAY(4:5,5), VECTOR
DBG>
This example shows how the display of a line of source code
changes when you change the right margin setting from 255 to
39.
3.DBG> SET MARGINS 10:45
DBG> SHOW MARGINS
left margin: 10 , right margin: 45
DBG> TYPE 14
module FORARRAY
14: IMENSION IARRAY(4:5,5), VECTOR(10),
DBG>
This example shows the display of the same line of source code
after both margins are changed.
4.DBG> SET MARGINS :100
DBG> SHOW MARGINS
left margin: 10 , right margin: 100
DBG>
This example shows how to change the right margin setting while
retaining the previous left margin setting.
5.DBG> SET MARGINS 5:
DBG> SHOW MARGINS
left margin: 5 , right margin: 100
DBG>
This example shows how to change the left margin setting while
retaining the previous right margin setting.
3 MODE
Enables or disables a debugger mode.
Format
SET MODE mode[, . . . ]
4 Parameters
DYNAMIC
(Default) Enables dynamic mode. When dynamic mode is enabled,
the debugger sets modules and images automatically during program
execution so that you typically do not have to enter the SET
MODULE or SET IMAGE command. Specifically, whenever the debugger
interrupts execution (whenever the debugger prompt is displayed),
the debugger automatically sets the module and image that contain
the routine in which execution is currently suspended. If the
module or image is already set, dynamic mode has no effect
on that module or image. The debugger issues an informational
message when its sets a module or image automatically.
NODYNAMIC
Disables dynamic mode. Because additional memory is allocated
when a module or image is set, you might want to disable dynamic
mode if performance becomes a problem (you can also free up
memory by canceling modules and images with the CANCEL MODULE
and CANCEL IMAGE commands). When dynamic mode is disabled, you
must set modules and images explicitly with the SET MODULE and
SET IMAGE commands.
G_FLOAT
Specifies that the debugger interpret double-precision floating-
point constants entered in expressions as G_FLOAT (does not
affect the interpretation of variables declared in your program).
NOG_FLOAT
(Default) Specifies that the debugger interpret double-precision
floating-point constants entered in expressions as D_FLOAT (does
not affect the interpretation of variables declared in your
program).
INTERRUPT
Useful when debugging a multiprocess program. Specifies that,
when program execution is suspended in any process, the debugger
interrupts execution in all other processes that were executing
images and prompts for input.
NOINTERRUPT
(Default) Useful when debugging a multiprocess program. Specifies
that, when program execution is suspended in any process, the
debugger take no action with regard to other process.
KEYPAD
NOTE
This parameter is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
(Default) Enables keypad mode. When keypad mode is enabled,
you can use the keys on the numeric keypad to perform certain
predefined functions. Several debugger commands, especially
useful in screen mode, are bound to the keypad keys. (See the
Keypad_Definitions_CI help topic; also, use the SHOW KEY command
to determine the current key definitions.) You can also redefine
the key functions with the DEFINE/KEY command.
NOKEYPAD
NOTE
This parameter is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
Disables keypad mode. When keypad mode is disabled, the keys on
the numeric keypad do not have predefined functions, nor can you
assign debugger functions to those keys with DEFINE/KEY commands.
LINE
(Default) Specifies that the debugger display program locations
in terms of line numbers, if possible.
NOLINE
Specifies that the debugger display program locations as routine-
name + byte-offset rather than in terms of line numbers.
OPERANDS[=keyword]
Specifies that the EXAMINE command, when used to examine
an instruction, display the address and contents of the
instruction's operands in addition to the instruction and
its operands. The level of information displayed about any
nonregister operands depends on whether you use the keyword BRIEF
or FULL. The default is OPERANDS=BRIEF.
NOOPERANDS
(Default) Specifies that the EXAMINE command, when used to
examine an instruction, display only the instruction and its
operands.
SCREEN
NOTE
This parameter is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
Enables screen mode. When screen mode is enabled, you can divide
the terminal screen into rectangular regions, so different data
can be displayed in different regions. Screen mode enables you to
view more information more conveniently than the default, line-
oriented, noscreen mode. You can use the predefined displays, or
you can define your own.
NOSCREEN
NOTE
This parameter is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
(Default) Disables screen mode.
SCROLL
NOTE
This parameter is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
Enables scroll mode. When scroll mode is enabled, a screen-mode
output or DO display is updated by scrolling the output line by
line, as it is generated. SET MODE SCROLL is the default.
NOSCROLL
NOTE
This parameter is not available in the Compaq DECwindows
Motif for OpenVMS user interface to the debugger.
Disables scroll mode. When scroll mode is disabled, a screen-mode
output or DO display is updated only once per command, instead
of line by line as it is generated. Disabling scroll mode reduces
the amount of screen updating that takes place and can be useful
with slow terminals.
SEPARATE
(Applies only to workstations running VWS.) Specifies that a
separate window be created for debugger input and output. This
feature is useful when debugging screen-oriented programs,
because it moves all debugger displays out of the window that
contains the program's input and output. The separate window is
created with a height of 24 lines and a width of 80 columns wide,
emulating a VT-series terminal screen.
NOSEPARATE
(Applies only to workstations running VWS. Default.) Specifies
that no separate window be created for debugger input and output.
SYMBOLIC
(Default) Enables symbolic mode. When symbolic mode is
enabled, the debugger displays the locations denoted by address
expressions symbolically (if possible) and displays instruction
operands symbolically (if possible). EXAMINE/NOSYMBOLIC can be
used to override SET MODE SYMBOLIC for the duration of an EXAMINE
command.
NOSYMBOLIC
Disables symbolic mode. When symbolic mode is disabled, the
debugger does not attempt to symbolize numeric addresses (it
does not cause the debugger to convert numbers to names). This is
useful if you are interested in identifying numeric addresses
rather than their symbolic names (if symbolic names exist
for those addresses). When symbolic mode is disabled, command
processing might speed up somewhat, because the debugger does not
need to convert numbers to names. EXAMINE/SYMBOLIC can be used
to override SET MODE NOSYMBOLIC for the duration of an EXAMINE
command.
WAIT
(Default) Enables wait mode. In wait mode the debugger waits
until all processes under its control have stopped before
prompting for a new command.
NOWAIT
Disable wait mode. In nowait mode, the debugger immediately
prompts for new commands even if some or all processes are still
running.
4 Description
For details about the SET MODE command, see the parameter
descriptions. The default values of these modes are the same
for all languages.
Related commands:
EVALUATE
EXAMINE
DEFINE/KEY
DEPOSIT
DISPLAY
(SET,SHOW,CANCEL) IMAGE
(SET,SHOW,CANCEL) MODULE
SET PROMPT
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
(SHOW,CANCEL) MODE
SYMBOLIZE
4 Example
DBG> SET MODE SCREEN
This command puts the debugger in screen mode.
3 MODULE
Loads the symbol records of a module in the current image into
the run-time symbol table (RST) of that image.
NOTE
The current image is either the main image (by default) or
the image established as the current image by a previous SET
IMAGE command.
Format
SET MODULE [module-name[, . . . ]]
4 Parameters
module-name
Specifies a module of the current image whose symbol records
are loaded into the RST. Do not use the asterisk (*) wildcard
character. Instead, use the /ALL qualifier. Do not specify a
module name with /ALL or /CALLS.
4 Qualifiers
/ALL
Specifies that the symbol records of all modules in the current
image be loaded into the RST.
/CALLS
Sets all the modules that currently have routines on the call
stack. If a module is already set, /CALLS has no effect on that
module.
/RELATED
/RELATED (default)
/NORELATED
(Applies to Ada programs.) Controls whether the debugger loads
into the RST the symbol records of a module that is related to a
specified module through a with-clause or subunit relationship.
Once loaded, you can reference names declared in related modules
within debugger commands exactly as you reference them within the
Ada source code.
4 Description
Symbol records must be present in the RST if the debugger is to
recognize and properly interpret the symbols declared in your
program. The process by which the symbol records of a module are
loaded into the RST is called setting a module.
At debugger startup, the debugger sets the module containing
the transfer address (the main program). By default, dynamic
mode is enabled (SET MODE DYNAMIC). Therefore, the debugger sets
modules (and images) automatically as the program executes so
that you can reference symbols as you need them. Specifically,
whenever execution is suspended, the debugger sets the module
and image containing the routine in which execution is suspended.
In the case of Ada programs, as a module is set dynamically, its
related modules are also set automatically, by default, to make
the appropriate symbols accessible (visible).
Dynamic mode makes accessible most of the symbols you might need
to reference. If you need to reference a symbol in a module that
is not already set, proceed as follows:
o If the module is in the current image, use the SET MODULE
command to set the module where the symbol is defined.
o If the module is in another image, use the SET IMAGE command
to make that image the current image, then use the SET MODULE
command to set the module where the symbol is defined.
If dynamic mode is disabled (SET MODE NODYNAMIC), only the module
containing the transfer address is set automatically. You must
set any other modules explicitly.
If you use the SET IMAGE command to establish a new current
image, all modules previously set remain set. However, only the
symbols in the set modules of the current image are accessible.
Symbols in the set modules of other images are temporarily
inaccessible.
When dynamic mode is enabled, memory is allocated automatically
to accommodate the increasing size of the RST. If dynamic mode
is disabled, the debugger automatically allocates more memory as
needed when you set a module or an image. Whether dynamic mode
is enabled or disabled, if performance becomes a problem as more
modules are set, use the CANCEL MODULE command to reduce the
number of set modules.
If a parameter in a SET SCOPE command designates a program
location in a module that is not already set, the SET SCOPE
command sets that module.
For information specific to Ada programs, type Help
Language_Support Ada.
Related commands:
(SET,SHOW,CANCEL) IMAGE
SET MODE [NO]DYNAMIC
(SHOW,CANCEL) MODULE
4 Examples
1.DBG> SET MODULE SUB1
This command sets module SUB1 (loads the symbol records of
module SUB1 into the RST).
2.DBG> SET IMAGE SHARE3
DBG> SET MODULE MATH
DBG> SET BREAK %LINE 31
In this example, the SET IMAGE command makes shareable image
SHARE3 the current image. The SET MODULE command sets module
MATH in image SHARE3. The SET BREAK command sets a breakpoint
on line 31 of module MATH.
3.DBG> SHOW MODULE/SHARE
module name symbols language size
FOO yes MACRO 432
MAIN no FORTRAN 280
. . .
SHARE$DEBUG no Image 0
SHARE$LIBRTL no Image 0
SHARE$MTHRTL no Image 0
SHARE$SHARE1 no Image 0
SHARE$SHARE2 no Image 0
total modules: 17. bytes allocated: 162280.
DBG> SET MODULE SHARE$SHARE2
DBG> SHOW SYMBOL * IN SHARE$SHARE2
In this example, the SHOW MODULE/SHARE command identifies all
modules in the current image and all shareable images (the
names of the shareable images are prefixed with SHARE$).
The SET MODULE SHARE$SHARE2 command sets the shareable image
module SHARE$SHARE2. The SHOW SYMBOL command identifies any
universal symbols defined in the shareable image SHARE2. For
more information, see the SHOW MODULE/SHARE command.
3 OUTPUT
Enables or disables a debugger output option.
Format
SET OUTPUT output-option[, . . . ]
4 Parameters
output-option
Specifies an output option to be enabled or disabled. Valid
keywords are as follows:
LOG Specifies that debugger input and output be recorded
in a log file. If you specify the log file by
the SET LOG command, the debugger writes to that
file; otherwise, by default the debugger writes to
SYS$DISK[]:DEBUG.LOG.
NOLOG (Default) Specifies that debugger input and output
not be recorded in a log file.
SCREEN_LOG Specifies that, while in screen mode, the screen
contents be recorded in a log file as the screen is
updated. To log the screen contents, you must also
specify SET OUTPUT LOG. See the description of the
LOG option regarding specifying the log file.
NOSCREEN_ (Default) Specifies that the screen contents, while
LOG in screen mode, not be recorded in a log file.
TERMINAL
NOTE
This parameter is not available in the
Compaq DECwindows Motif for OpenVMS user
interface to the debugger.
(Default) Specifies that debugger output be
displayed at the terminal.
NOTERMINAL
NOTE
This parameter is not available in the
Compaq DECwindows Motif for OpenVMS user
interface to the debugger.
Specifies that debugger output, except diagnostic
messages, not be displayed at the terminal.
VERIFY Specifies that the debugger echo, on the current
output device, each input command string that it is
executing from a command procedure or DO clause. The
current output device is by default SYS$OUTPUT (your
terminal) but can be redefined with the logical name
DBG$OUTPUT.
NOVERIFY (Default) Specifies that the debugger not display
each input command string that it is executing from
a command procedure or DO clause.
4 Description
Debugger output options control the way in which debugger
responses to commands are displayed and recorded. For details
about the SET OUTPUT command, see the parameter descriptions.
Related commands:
@ (Execute Procedure)
(SET,SHOW) ATSIGN
(SET,SHOW) LOG
SET MODE SCREEN
SHOW OUTPUT
4 Example
DBG> SET OUTPUT VERIFY,LOG,NOTERMINAL
This command specifies that the debugger take the following
actions:
o Output each command string that it is executing from a
command procedure or DO clause (VERIFY)
o Record debugger output and user input in a log file (LOG)
o Not display output at the terminal, except diagnostic
messages (NOTERMINAL)
3 PROCESS
Establishes the visible process or enables/disables dynamic
process setting.
Used only when debugging multiprocess programs (kept debugger
only).
Format
SET PROCESS [process-spec[, . . . ]]
4 Parameters
process-spec
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
You can also use the asterisk (*) wildcard character to specify
process set all.
Do not specify a process with the /[NO]DYNAMIC qualifier.
4 Qualifiers
/DYNAMIC
/DYNAMIC (default)
/NODYNAMIC
Controls whether dynamic process setting is enabled or disabled.
When dynamic process setting is enabled (/DYNAMIC), whenever the
debugger suspends execution and displays its prompt, the process
in which execution is suspended automatically becomes the visible
process. When dynamic process setting is disabled (/NODYNAMIC),
the visible process remains unchanged until you specify another
process with the SET PROCESS/VISIBLE command.
/VISIBLE
Makes the specified process the visible process. This switches
your debugging context to the specified process, so that symbol
lookups and the setting of breakpoints, and so on, are done
in the context of that process. When using /VISIBLE, you must
specify one process.
4 Description
The SET PROCESS command establishes the visible process, defines
the current process set, or defines the visible process.
By default, commands are executed in the context of the visible
process (the process that is your current debugging context).
Symbol lookups, the setting of breakpoints, and so on, are done
in the context of the visible process.
Dynamic process setting is enabled by default and is controlled
with /[NO]DYNAMIC. When dynamic process setting is enabled,
whenever the debugger suspends program execution and displays
its prompt, the process in which execution is suspended becomes
the visible process automatically.
Related commands:
CALL
EXIT
GO
QUIT
SHOW PROCESS
STEP
4 Example
all> SET PROCESS TEST_Y
all> SHOW PROCESS
Number Name State Current PC
* 2 TEST_Y break PROG\%LINE 71
all>
The SET PROCESS TEST_Y command makes process TEST_Y the visible
process. The SHOW PROCESS command displays information about
the visible process by default.
3 PROMPT
Changes the debugger prompt string to your personal preference.
Format
SET PROMPT [prompt-parameter]
4 Parameters
prompt-parameter
Specifies the new prompt string. If the string contains spaces,
semicolons (;), or lowercase characters, you must enclose it in
quotation marks (") or apostrophes ('). If you do not specify a
string, the current prompt string remains unchanged.
By default, the prompt string is DBG> when debugging a single
process program.
By default, when debuggging a multiprocess program, the prompt
string is the name of the current process set followed by a right
angle bracket (>). You should not use the SET PROMPT command when
debugging multiprocess programs.
4 Qualifiers
/POP
/POP
/NOPOP (default)
(Applies only to workstations running VWS.) The /POP qualifier
causes the debugger window to pop over other windows and become
attached to the keyboard when the debugger prompts for input. The
/NOPOP qualifier disables this behavior (the debugger window is
not popped over other windows and is not attached to the keyboard
automatically when the debugger prompts for input).
4 Description
The SET PROMPT command enables you to tailor the debugger prompt
string to your individual preference.
If you are debugging a multiprocess program, you should not use
the SET PROMPT command.
If you are using the debugger at a workstation, /[NO]POP enables
you to control whether the debugger window is popped over other
windows whenever the debugger prompts for input.
Related commands:
(SET,SHOW) PROCESS
4 Examples
1.DBG> SET PROMPT "$ "
$ SET PROMPT "d b g : "
d b g : SET PROMPT "DBG> "
DBG>
In this example, the successive SET PROMPT commands change the
debugger prompt from "DBG>" to "$", to "d b g :", then back to
"DBG>".
3 RADIX
Establishes the radix for the entry and display of integer data.
When used with /OVERRIDE, it causes all data to be displayed as
integer data of the specified radix.
Format
SET RADIX radix
4 Parameters
radix
Specifies the radix to be established. Valid keywords are as
follows:
BINARY Sets the radix to binary.
DECIMAL Sets the radix to decimal. This is the default for
all languages except BLISS, MACRO-32, and MACRO-64
(Alpha only).
DEFAULT Sets the radix to the language default.
OCTAL Sets the radix to octal.
HEXADECIMAL Sets the default radix to hexadecimal. This is the
default for BLISS, MACRO-32, and MACRO-64 (Alpha
only).
4 Qualifiers
/INPUT
Sets only the input radix (the radix for entering integer data)
to the specified radix.
/OUTPUT
Sets only the output radix (the radix for displaying integer
data) to the specified radix.
/OVERRIDE
Causes all data to be displayed as integer data of the specified
radix.
4 Description
The current radix setting influences how the debugger interprets
and displays integer data in the following contexts:
o Integer data that you specify in address expressions or
language expressions.
o Integer data that is displayed by the EXAMINE and EVALUATE
commands.
The default radix for both data entry and display is decimal for
most languages. On VAX processors, the exceptions are BLISS and
MACRO-32, which have a default radix of hexadecimal. On Alpha
processors, the exceptions are BLISS, MACRO-32, and MACRO-64,
which have a default radix of hexadecimal.
The SET RADIX command enables you to specify a new radix
for data entry or display (the input radix and output radix,
respectively).
If you do not specify a qualifier, the SET RADIX command
changes both the input and output radix. If you specify /INPUT
or /OUTPUT, the command changes the input or output radix,
respectively.
Using SET RADIX/OVERRIDE changes only the output radix but causes
all data (not just data that has an integer type) to be displayed
as integer data of the specified radix.
Except when used with /OVERRIDE, the SET RADIX command does not
affect the interpretation or display of noninteger values (such
as real or enumeration type values).
The EVALUATE, EXAMINE, and DEPOSIT commands have radix
qualifiers (/BINARY, /HEXADECIMAL, and so on) which enable you to
override, for the duration of that command, any radix previously
established with SET RADIX or SET RADIX/OVERRIDE.
You can also use the built-in symbols %BIN, %DEC, %HEX, and %OCT
in address expressions and language expressions to specify that
an integer literal should be interpreted in binary, decimal,
hexadecimal, or octal radix.
Related commands:
DEPOSIT
EVALUATE
EXAMINE
(SET,SHOW,CANCEL) MODE
(SHOW,CANCEL) RADIX
4 Examples
1.DBG> SET RADIX HEX
This command sets the radix to hexadecimal. This means that,
by default, integer data is interpreted and displayed in
hexadecimal radix.
2.DBG> SET RADIX/INPUT OCT
This command sets the radix for input to octal. This means
that, by default, integer data that is entered is interpreted
in octal radix.
3.DBG> SET RADIX/OUTPUT BIN
This command sets the radix for output to binary. This means
that, by default, integer data is displayed in binary radix.
4.DBG> SET RADIX/OVERRIDE DECIMAL
This command sets the override radix to decimal. This means
that, by default, all data (not just data that has an integer
type) is displayed as decimal integer data.
3 SCOPE
Establishes how the debugger looks up symbols (variable names,
routine names, line numbers, and so on) when a path-name prefix
is not specified.
Format
SET SCOPE location[, . . . ]
4 Parameters
location
Denotes a program region (scope) to be used for the
interpretation of symbols that you specify without a path-name
prefix. A location can be any of the following, unless you
specify /CURRENT or /MODULE.
path-name Specifies the scope denoted by the path-name
prefix prefix. A path-name prefix consists of the
names of one or more nesting program elements
(module, routine, block, and so on), with each
name separated by a backslash character (\).
When a path-name prefix consists of more than
one name, list a nesting element to the left of
the backslash and a nested element to the right of
the backslash. A common path-name prefix format is
module\routine\block\.
If you specify only a module name and that name is
the same as the name of a routine, use /MODULE;
otherwise, the debugger assumes that you are
specifying the routine.
n Specifies the scope denoted by the routine which
is n levels down the call stack (n is a decimal
integer). A scope specified by an integer changes
dynamically as the program executes. The value 0
denotes the routine that is currently executing,
the value 1 denotes the caller of that routine,
and so on down the call stack. The default scope
search list is 0,1,2, . . . ,n, where n is the
number of calls in the call stack.
\ Specifies the global scope-that is, the set of
(backslash) all program locations in which a global symbol is
known. The definition of a global symbol and the
way it is declared depends on the language.
When you specify more than one location parameter, you establish
a scope search list. If the debugger cannot interpret the symbol
using the first parameter, it uses the next parameter, and
continues using parameters in order of their specification until
it successfully interprets the symbol or until it exhausts the
parameters specified.
4 Qualifiers
/CURRENT
Establishes a scope search list that is like the default search
list (0,1,2, . . . ,n), numeric scope specified as the command
parameter. Scope 0 is the PC scope, and n is the number of calls
in the call stack.
When using SET SCOPE/CURRENT, note the following conventions and
behavior:
o The default scope search list must be in effect when the
command is entered. To restore the default scope search list,
enter the CANCEL SCOPE command.
o The command parameter specified must be one (and only one)
decimal integer from 0 to n.
o In screen mode, the command updates the predefined source,
instruction, and register displays SRC, INST, and REG,
respectively, to show the routine on the call stack in which
symbol searches are to start.
o The default scope search list is restored when program
execution is resumed.
/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.
4 Description
By default, the debugger looks up a symbol specified without a
path-name prefix according to the scope search list 0,1,2, . . .
,n, where n is the number of calls in the call stack. This
scope search list is based on the current PC value and changes
dynamically as the program executes. The default scope search
list specifies that a symbol lookup such as EXAMINE X first looks
for X in the routine that is currently executing (scope 0, also
known as the PC scope); if no X is visible there, the debugger
looks in the caller of that routine (scope 1), and so on down the
call stack; if X is not found in scope n, the debugger searches
the rest of the run-time symbol table (RST)-that is, all set
modules and the global symbol table (GST), if necessary.
In most cases, this default scope search list enables you
to resolve ambiguities in a predictable, natural way that is
consistent with language rules. But if you cannot access a symbol
that is defined multiple times, use either of the following
techniques:
o Specify the symbol with a path-name prefix. The path-name
prefix consists of any nesting program units (for example,
module\routine\block) that are necessary to specify the symbol
uniquely. For example:
DBG> EXAMINE MOD4\ROUT3\X
DBG> TYPE MOD4\27
o Establish a new default scope (or a scope search list) for
symbol lookup by using the SET SCOPE command. You can then
specify the symbol without using a path-name prefix. For
example:
DBG> SET SCOPE MOD4\ROUT3
DBG> EXAMINE X
DBG> TYPE 27
4 Description,_Continued...
The SET SCOPE command is useful in those cases where otherwise
you would need to use a path name repeatedly to specify symbols.
To restore the default scope search list, use the CANCEL SCOPE
command.
When the default scope search list is in effect, you can use the
SET SCOPE/CURRENT command to specify that symbol searches start
at a numeric scope other than scope 0, relative to the call stack
(for example, scope 2).
When you use the SET SCOPE command, the debugger searches only
the program locations you specify explicitly, unless you specify
/CURRENT. Also, the scope or scope search list established with a
SET SCOPE command remains in effect until you restore the default
scope search list or enter another SET SCOPE command. However, if
you specify /CURRENT, the default scope search list is restored
whenever program execution is resumed.
The SET SCOPE command updates a screen-mode source or instruction
display only if you specify /CURRENT.
If a name you specify in a SET SCOPE command is the name of
both a module and a routine, the debugger sets the scope to the
routine. In such cases, use the SET SCOPE/MODULE command if you
want to set the scope to the module.
If you specify a module name in a SET SCOPE command, the debugger
sets that module if it is not already set. However, if you want
only to set a module, use the SET MODULE command rather than the
SET SCOPE command, to avoid the possibility of disturbing the
current scope search list.
For information specific to Ada programs, type Help Language_
Support Ada.
Related commands:
CANCEL ALL
SEARCH
SET MODULE
(SHOW,CANCEL) SCOPE
SHOW SYMBOL
SYMBOLIZE
TYPE
4 Examples
1.DBG> EXAMINE Y
%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique
DBG> SHOW SYMBOL Y
data CHECK_IN\Y
data INVENTORY\COUNT\Y
DBG> SET SCOPE INVENTORY\COUNT
DBG> EXAMINE Y
INVENTORY\COUNT\Y: 347.15
DBG>
In this example, the first EXAMINE Y command indicates that
symbol Y is defined multiple times and cannot be resolved from
the current scope search list. The SHOW SYMBOL command displays
the different declarations of symbol Y. The SET SCOPE command
directs the debugger to look for symbols without path-name
prefixes in routine COUNT of module INVENTORY. The subsequent
EXAMINE command can now interpret Y unambiguously.
3 SEARCH
Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or
/STRING) for the SEARCH command.
Format
SET SEARCH search-default[, . . . ]
4 Parameters
search-default
Specifies a default to be established for the SEARCH command.
Valid keywords (which correspond to SEARCH command qualifiers)
are as follows:
ALL Subsequent SEARCH commands are treated as SEARCH/ALL,
rather than SEARCH/NEXT.
IDENTIFIER Subsequent SEARCH commands are treated as
SEARCH/IDENTIFIER, rather than SEARCH/STRING.
NEXT (Default) Subsequent SEARCH commands are treated as
SEARCH/NEXT, rather than SEARCH/ALL.
STRING (Default) Subsequent SEARCH commands are treated as
SEARCH/STRING, rather than SEARCH/IDENTIFIER.
4 Description
The SET SEARCH command establishes default qualifiers for
subsequent SEARCH commands. The parameters that you specify with
SET SEARCH have the same names as the qualifiers for the SEARCH
command. The qualifiers determine whether the SEARCH command:
(1) searches for all occurrences of a string (ALL) or only the
next occurrence (NEXT); and (2) displays any occurrence of the
string (STRING) or only those occurrences in which the string is
not bounded on either side by a character that can be part of an
identifier in the current language (IDENTIFIER).
You can override the current SEARCH default for the duration of
a single SEARCH command by specifying other qualifiers. Use the
SHOW SEARCH command to identify the current SEARCH defaults.
Related commands:
SEARCH
(SET,SHOW) LANGUAGE
SHOW SEARCH
4 Example
DBG> SHOW SEARCH
search settings: search for next occurrence, as a string
DBG> SET SEARCH IDENTIFIER
DBG> SHOW SEARCH
search settings: search for next occurrence, as an identifier
DBG> SET SEARCH ALL
DBG> SHOW SEARCH
search settings: search for all occurrences, as an identifier
DBG>
In this example, the SET SEARCH IDENTIFIER command directs
the debugger to search for an occurrence of the string in
the specified range but display the string only if it is not
bounded on either side by a character that can be part of an
identifier in the current language.
The SET SEARCH ALL command directs the debugger to search for
(and display) all occurrences of the string in the specified
range.
3 SOURCE
Specifies a directory search list, a directory search method, or
both a list and a method for source files.
Format
SET SOURCE directory-spec[, . . . ]
4 Parameters
directory-spec
Specifies any part of an OpenVMS file specification (typically
a device/directory) that the debugger is to use by default
when searching for a source file. For any part of a full file
specification that you do not supply, the debugger uses the file
specification stored in the module's symbol record (that is, the
file specification that the source file had at compile time).
If you specify more than one directory in a single SET SOURCE
command, you create a source directory search list (you can
also specify a search list logical name that is defined at your
process level). In this case, the debugger locates the source
file by searching the first directory specified, then the second,
and so on, until it either locates the source file or exhausts
the list of directories.
4 Qualifiers
/DISPLAY
Specifies the directory search list used when the debugger
displays source code. The default display search directory is
the compilation directory.
/EDIT
Specifies the directory search list used during execution of the
debugger's EDIT command. The default edit search directory is the
compilation directory.
/EXACT
/EXACT (default)
Specifies the directory search method used. In this case, the
debugger searches for the exact version of the source file, as
indicated in the debugger symbol table.
/LATEST
Specifies the directory search method used. In this case, the
debugger searches for the latest version of the source file, that
is, the highest-numbered version in your directory.
/MODULE
/MODULE=module-name
Specifies the directory search list used only for the designated
module. You can append one or more of the qualifiers listed above
to the SET SOURCE/MODULE command.
/ORIGINAL
(Applies to STDL programs only. Requires installation of the
Correlation Facility (a separate layered product) and invocation
of the kept debugger.) Specifies that the debugger display the
original STDL source file, rather than the intermediate files
produced during STDL compilation.
4 Description
By default, the debugger expects a source file to be in the same
directory it was in at compile time. If a source file has been
moved to a different directory since compile time, use the SET
SOURCE command to specify a directory search list and search
method to locate the file.
Specifying the Directory Search List
On OpenVMS Version 6.1 and later, a complete OpenVMS file
specification has the following format:
node::device:[directory]file-name.file-type;version-number
This format reflects the DECnet node name functionality used
in the default version of DECnet shipped with the OpenVMS
operating system. For more information, see the DECnet for
OpenVMS Networking Manual.
On OpenVMS systems running Version 6.1 or later and DECnet-
Plus for OpenVMS, a complete file specification can include
expanded node designations, called full names. Full names are
hierarchically structured DECnet-Plus for OpenVMS node names that
can be stored in a DECdns naming service. Full names can be a
maximum of 255 bytes long, in the following format:
namespace:.directory ... .directory.node-name
In this syntax statement, namespace identifies the global naming
service, directory ... .directory defines the hierarchical
directory path within the naming service, and node-name is the
specific object defining the DECnet node.
For information on full names and suggestions for setting up a
system of names, see the OpenVMS System Manager's Manual. For
information on DECnet-Plus for OpenVMS, see the DECnet-Plus for
OpenVMS Introduction and User's Guide.
If the full file specification of a source file exceeds 255
characters, the debugger cannot locate the file. You can work
around this problem by first defining a logical name "X" (at DCL
level) to expand to your long file specification, and then using
the SET SOURCE X command.
A SET SOURCE command with neither the /DISPLAY nor the /EDIT
qualifier changes both the display and edit search directories.
When compiling a program with the /DEBUG qualifier, if you use
a rooted-directory logical name to specify the location of the
source file, make sure that it is a concealed rooted-directory
logical name. If it is not concealed and you move the source file
to another directory after compilation, you cannot then use the
debugger SET SOURCE command to specify the new location of the
source file.
To create a concealed rooted-directory logical name, use the DCL
command DEFINE with the /TRANSLATION_ATTR=CONCEALED qualifier.
4 Description,_Continued...
Specifying the Directory Search Method
When you issue a SET SOURCE command, be aware that one of the
two qualifiers -/LATEST or /EXACT-will always be active. These
qualifiers affect the debugger search method. The /LATEST
qualifier directs the debugger to search for the version last
created (the highest-numbered version in your directory). The
/EXACT qualifier directs the debugger to search for the version
last compiled (the version recorded in the debugger symbol table
created at compile time). For example, a SET SOURCE/LATEST
command might search for SORT.FOR;3 while a SET SOURCE/EXACT
command might search for SORT.FOR;1.
If the debugger locates this version using the directory search
list, it checks that the creation or revision date and time,
file size, record format, and file organization are the same as
the original compile-time source file. If these characteristics
match, the debugger concludes that the original source file has
been located in its new directory.
If the debugger cannot locate this version using the directory
search list, it identifies the file that has the closest revision
date and time (if such a file exists in that directory) and
issues a NOTORIGSRC message ("original version of source file
not found") when first displaying the source code.
Specifying the /EDIT Qualifier
The /EDIT qualifier is needed when the files used for the display
of source code are different from the files to be edited by
using the EDIT command. This is the case with Ada programs. For
Ada programs, the (SET, SHOW, CANCEL) SOURCE commands affect
the search of files used for source display (the "copied"
source files in Ada program libraries); the (SET,SHOW,CANCEL)
SOURCE/EDIT commands affect the search of the source files you
edit when using the EDIT command. If you use /MODULE with /EDIT,
the effect of /EDIT is further qualified by /MODULE.
For information specific to Ada programs, see the
Language_Support Ada help topic.
Specifying the /ORIGINAL Qualifier
Before you can use the /ORIGINAL qualifier in a SET SOURCE
command, the Correlation Facility (a separate layered product)
must be installed on your system. Refer to Correlation Facility
documentation for information on creating a correlation library
before debugging.
Then, invoke the kept debugger and issue the SET SOURCE/ORIGINAL
command as follows:
$ DEBUG/KEEP
DBG> SET SOURCE/ORIGINAL
DBG> RUN filename.EXE
After issuing these commands, you can debug STDL source code in
the same way you debug any other supported language program.
Related commands:
(SHOW,CANCEL) SOURCE
4 Examples
1.DBG> SHOW SOURCE
no directory search list in effect
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
In this example, the SET SOURCE command specifies that the
debugger should search directories [PROJA], [PROJB], and
[PETER.PROJC], in that order, for the latest version of source
files.
2.DBG> SET SOURCE /EXACT
DBG> SHOW SOURCE
no directory search list in effect,
match the exact source file
DBG> SET SOURCE [JONES]
DBG> SHOW SOURCE
source directory list for all modules,
match the exact source file version:
[JONES]
DBG> CANCEL SOURCE /EXACT
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[JONES]
In this example, the SET SOURCE/EXACT command establishes a
search method (exact version) that remains in effect for the
SET SOURCE [JONES] command. The CANCEL SOURCE/EXACT command not
only cancels SET SOURCE/EXACT command, but also affects the SET
SOURCE [JONES] command.
3 STEP
Establishes default qualifiers (/LINE, /INTO, and so on) for the
STEP command.
Format
SET STEP step-default[, . . . ]
4 Parameters
BRANCH
Subsequent STEP commands are treated as STEP/BRANCH (step to the
next branch instruction).
CALL
Subsequent STEP commands are treated as STEP/CALL (step to the
next call instruction).
EXCEPTION
Subsequent STEP commands are treated as STEP/EXCEPTION (step to
the next exception).
INSTRUCTION
Subsequent STEP commands are treated as STEP/INSTRUCTION (step to
the next instruction).
On VAX processors, you can also specify one or more instructions
(opcode[, . . . ]). The debugger then steps to the next
instruction in the specified list.
On VAX processors, if you specify a vector instruction, do not
include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_
INSTRUCTION, /MODIFY, /0, or /1)) with the instruction mnemonic.
INTO
Subsequent STEP commands are treated as STEP/INTO (step into
called routines) rather than STEP/OVER (step over called
routines). When INTO is in effect, you can qualify the types
of routines to step into by using the [NO]JSB, [NO]SHARE,
and [NO]SYSTEM parameters, or by using the STEP/[NO]JSB,
STEP/[NO]SHARE, and STEP/[NO]SYSTEM command/qualifier
combinations (the latter three take effect only for the immediate
STEP command).
JSB
(VAX only) If INTO is in effect, subsequent STEP commands are
treated as STEP/INTO/JSB (step into routines called by a JSB
instruction as well as those called by a CALL instruction). This
is the default for all languages except DIBOL.
NOJSB
(VAX only; Default.) If INTO is in effect, subsequent STEP
commands are treated as STEP/INTO/NOJSB (step over routines
called by a JSB instruction, but step into routines called by
a CALL instruction). This is the default for DIBOL.
LINE
(Default) Subsequent STEP commands are treated as STEP/LINE (step
to the next line).
OVER
(Default) Subsequent STEP commands are treated as STEP/OVER (step
over all called routines) rather than STEP/INTO (step into called
routines).
RETURN
Subsequent STEP commands are treated as STEP/RETURN (step to the
return instruction of the routine that is currently executing-
that is, up to the point just prior to transferring control back
to the calling routine).
SEMANTIC_EVENT
(Alpha only) Subsequent STEP commands are treated as
STEP/SEMANTIC_EVENT (step to the next semantic event).
SHARE
(Default) If INTO is in effect, subsequent STEP commands
are treated as STEP/INTO/SHARE (step into called routines in
shareable images as well as into other called routines).
NOSHARE
If INTO is in effect, subsequent STEP commands are treated as
STEP/INTO/NOSHARE (step over called routines in shareable images,
but step into other routines).
SILENT
Subsequent STEP commands are treated as STEP/SILENT (after a
step, do not display the "stepped to . . . " message or the source
line for the current location).
NOSILENT
(Default) Subsequent STEP commands are treated as STEP/NOSILENT
(after a step, display the "stepped to . . . " message).
SOURCE
(Default) Subsequent STEP commands are treated as STEP/SOURCE
(after a step, display the source line for the current location).
Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands
are treated as SET BREAK/SOURCE, SET TRACE/SOURCE, and SET
WATCH/SOURCE, respectively (at a breakpoint, tracepoint, or
watchpoint, display the source line for the current location).
NOSOURCE
Subsequent STEP commands are treated as STEP/NOSOURCE (after a
step, do not display the source line for the current location).
Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands
are treated as SET BREAK/NOSOURCE, SET TRACE/NOSOURCE, and
SET WATCH/NOSOURCE, respectively (at a breakpoint, tracepoint,
or watchpoint, do not display the source line for the current
location).
SYSTEM
(Default) If INTO is in effect, subsequent STEP commands are
treated as STEP/INTO/SYSTEM (step into called routines in system
space (P1 space) as well as into other called routines).
NOSYSTEM
If INTO is in effect, subsequent STEP commands are treated as
STEP/INTO/NOSYSTEM (step over called routines in system space,
but step into other routines).
VECTOR_INSTRUCTION
(VAX only) On VAX processors, subsequent STEP commands are
treated as STEP/VECTOR_INSTRUCTION (step to the next vector
instruction).
4 Description
The SET STEP command establishes default qualifiers for
subsequent STEP commands. The parameters that you specify in
the SET STEP command have the same names as the qualifiers for
the STEP command. The following parameters affect where the STEP
command suspends execution after a step:
BRANCH
CALL
EXCEPTION
INSTRUCTION
INSTRUCTION=(opcode[, . . . ]) (VAX only)
LINE
RETURN
SEMANTIC_EVENT (Alpha only)
VECTOR_INSTRUCTION (VAX only)
The following parameters affect what output is seen when a STEP
command is executed:
[NO]SILENT
[NO]SOURCE
The following parameters affect what happens at a routine call:
INTO
[NO]JSB (VAX only)
OVER
[NO]SHARE
[NO]SYSTEM
You can override the current STEP defaults for the duration of a
single STEP command by specifying other qualifiers. Use the SHOW
STEP command to identify the current STEP defaults.
Enabling screen mode by pressing PF1-PF3 enters the SET STEP
NOSOURCE command as well as the SET MODE SCREEN command.
Therefore, any display of source code in output and DO displays
that would result from a STEP command or from a breakpoint,
tracepoint, or watchpoint being triggered is suppressed, to
eliminate redundancy with the source display.
On VAX systems, the STEP/OVER command may sometimes result in
stepping into, not over, Fortran Run-Time Library routines. For
more information, see the OpenVMS Debugger Manual.
Related commands:
SHOW STEP
STEP
4 Examples
1.DBG> SET STEP INSTRUCTION,NOSOURCE
This command causes the debugger to execute the program to the
next instruction when a STEP command is entered, and not to
display lines of source code with each STEP command.
2.DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE
This command causes the debugger to execute the program to
the next line when a STEP command is entered, and to step into
called routines in user space only. The debugger steps over
routines in system space and in shareable images.
3 TASK
Changes characteristics of one or more tasks of a tasking program
(also called a multithread program).
NOTE
SET TASK and SET THREAD are synonymous commands. They
perform identically.
Format
SET TASK [task-spec[, . . . ]]
4 Parameters
task-spec
Specifies a task value. Use any of the following forms:
o When the event facility is THREADS:
- A task (thread) ID number as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW
TASK display.
o When the event facility is ADA:
- A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
- A task ID (for example, %TASK 2), as indicated in a SHOW
TASK display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or
EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_ The task previous to the visible task in the
TASK debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are
the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard character. Instead, use the
/ALL qualifier. Do not specify a task with /ALL or /TIME_SLICE.
If you do not specify a task or /ALL with /ABORT, /[NO]HOLD,
/PRIORITY, or /RESTORE, the visible task is selected.
4 Qualifiers
/ABORT
Marks the specified tasks for termination. Termination occurs
at the next allowable point after a specified task resumes
execution.
For Compaq Ada tasks, the effect is identical to executing an Ada
abort statement for the tasks specified and causes these tasks
to be marked as abnormal. Any dependent tasks are also marked for
termination.
For POSIX Threads threads, use the following command:
PTHREAD tset -c thread-number
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/ACTIVE
Makes the specified task the active task, which is the task that
runs when a STEP, GO, CALL, or EXIT command executes. This causes
a task switch to the new active task and makes that task the
visible task. The specified task must be in either the RUNNING or
READY state. When using /ACTIVE, you must specify one task.
The SET TASK/ACTIVE command is supported for Compaq Ada on VAX
only. For POSIX Threads programs or Compaq Ada on Alpha programs,
use one of the following alternatives:
o For query-type actions, use the SET TASK/VISIBLE command.
o To gain control of execution, use a strategic placement of
breakpoints.
o Use the PTHREAD tset -a thread-number command.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/ALL
Applies the SET TASK command to all tasks.
/HOLD
/HOLD
/NOHOLD (default)
When the event
facility is THREADS, use the PTHREAD tset -h thread-number or
the PTHREAD tset -n thread-number command.
Controls whether a specified task is put on hold. The /HOLD
qualifier puts a specified task on hold.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED
to the READY state.
A task already in the RUNNING state (the active task) can
continue to execute as long as it remains in the RUNNING state,
even though it is put on hold. If the task leaves the RUNNING
state for any reason (including expiration of a time slice, if
time slicing is enabled), it will not return to the RUNNING state
until released from the hold condition.
You can override the hold condition and force a task into the
RUNNING state with the SET TASK/ACTIVE command even if the task
is on hold.
The /NOHOLD qualifier releases a specified task from hold.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/PRIORITY
/PRIORITY=n
When the event facility is THREADS, use the PTHREAD
tset -s thread-number command.
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example, while
executing an Ada rendezvous or POSIX Threads synchronization
event. This qualifier does not affect a task's scheduling policy.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/RESTORE
(Compaq Ada on VAX only) Restores the priority of a specified
task to the priority it had when it was created. Does not affect
the scheduling priority of the task.
/TIME_SLICE
/TIME_SLICE=t
Supported for Compaq Ada on VAX only. 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 /TIME_SLICE=0.0. /TIME_SLICE is valid only when the
event facility is ADA.
/VISIBLE
Makes the specified task the visible task, which is the task
whose call stack and register set are the current context for
looking up symbols, register values, routine calls, breakpoints,
and so on. Commands such as EXAMINE are directed at the visible
task. The /VISIBLE qualifier does not affect the active task.
When using /VISIBLE, you must specify one task.
4 Description
The SET TASK command enables you to establish the visible task
and the active task, control the execution of tasks, and cause
task state transitions, directly or indirectly.
To determine the current state of a task, use the SHOW TASK
command. The possible states are RUNNING, READY, SUSPENDED, and
TERMINATED.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
SET BREAK/EVENT
SET TRACE/EVENT
(SET, SHOW) EVENT_FACILITY
SHOW TASK|THREAD
4 Examples
1.DBG> SET TASK/ACTIVE %TASK 3
(Event facility = ADA) This command makes task 3 (task ID = 3)
the active task.
2.DBG> PTHREAD tset -a 3
(Event facility = THREADS) This command makes task 3 (task ID =
3) the active task.
3.DBG> SET TASK %NEXT_TASK
This command makes the next task in the debugger's task list
the visible task. (The /VISIBLE qualifier is a default for the
SET TASK command.)
4.DBG> SET TASK/HOLD/ALL
DBG> SET TASK/ACTIVE %TASK 1
DBG> GO
. . .
DBG> SET TASK/ACTIVE %TASK 3
DBG> STEP
. . .
In this example, the SET TASK/HOLD/ALL command freezes
the state of all tasks except the active task. Then, SET
TASK/ACTIVE is used selectively (along with the GO and STEP
commands) to observe the behavior of one or more specified
tasks in isolation.
3 TERMINAL
Sets the terminal-screen height or width that the debugger uses
when it formats screen and other output.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SET TERMINAL
4 Qualifiers
/PAGE
/PAGE:n
Specifies that the terminal screen height should be set to n
lines. You can use any value from 18 to 100.
/WIDTH
/WIDTH:n
Specifies that the terminal screen width should be set to n
columns. You can use any value from 20 to 255. For a VT100-,
VT200-, or VT300 series terminal, n is typically either 80 or
132.
/WRAP
Tells the debugger to wrap output text in predefined display
OUT at the column specified by the /WIDTH qualifier. If you do
not specify /WIDTH in the current command, /WRAP defaults to the
%WIDTH setting.
4 Description
The SET TERMINAL command enables you to define the portion of
the screen that the debugger has available for formatting screen
output.
This command is useful with VT100-, VT200-, or VT300-series
terminals, where you can set the screen width to typically 80 or
132 columns. It is also useful with workstations, where you can
modify the size of the terminal-emulator window that the debugger
uses.
You must specify at least one qualifier. You can specify all. The
/PAGE and /WIDTH qualifiers each require a value.
When you enter the SET TERMINAL command, all display window
definitions are automatically adjusted to reflect the new screen
dimensions. For example, RH1 changes dimensions proportionally to
remain in the top right half of the screen.
Similarly, all "dynamic" display windows are automatically
adjusted to maintain their relative proportions. Note that
all display windows are dynamic unless referenced with the
DISPLAY/NODYNAMIC command. In that case, the display window
retains its current dimensions after subsequent SET TERMINAL
commands. However, you can use the DISPLAY command to reconfigure
the display window (you can also use keypad-key combinations,
such as BLUE-MINUS, to enter predefined DISPLAY commands).
Related commands:
DISPLAY/[NO]DYNAMIC
EXPAND
(SET,SHOW,CANCEL) WINDOW
SHOW TERMINAL
4 Example
DBG> SET TERMINAL/WIDTH:132
This command specifies that the terminal screen width be set to
132 columns.
3 THREAD
Changes characteristics of one or more tasks of a tasking program
(also called a multithread program).
NOTE
SET TASK and SET THREAD are synonymous commands. They
perform identically.
Format
SET TASK [task-spec[, . . . ]]
4 Parameters
task-spec
Specifies a task value. Use any of the following forms:
o When the event facility is THREADS:
- A task (thread) ID number as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW
TASK display.
o When the event facility is ADA:
- A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
- A task ID (for example, %TASK 2), as indicated in a SHOW
TASK display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or
EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_ The task previous to the visible task in the
TASK debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are
the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard character. Instead, use the
/ALL qualifier. Do not specify a task with /ALL or /TIME_SLICE.
If you do not specify a task or /ALL with /ABORT, /[NO]HOLD,
/PRIORITY, or /RESTORE, the visible task is selected.
4 Qualifiers
/ABORT
Marks the specified tasks for termination. Termination occurs
at the next allowable point after a specified task resumes
execution.
For Compaq Ada tasks, the effect is identical to executing an Ada
abort statement for the tasks specified and causes these tasks
to be marked as abnormal. Any dependent tasks are also marked for
termination.
For POSIX Threads threads, use the following command:
PTHREAD tset -c thread-number
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/ACTIVE
Makes the specified task the active task, which is the task that
runs when a STEP, GO, CALL, or EXIT command executes. This causes
a task switch to the new active task and makes that task the
visible task. The specified task must be in either the RUNNING or
READY state. When using /ACTIVE, you must specify one task.
The SET TASK/ACTIVE command is supported for Compaq Ada on VAX
only. For POSIX Threads programs or Compaq Ada on Alpha programs,
use one of the following alternatives:
o For query-type actions, use the SET TASK/VISIBLE command.
o To gain control of execution, use a strategic placement of
breakpoints.
o Use the PTHREAD tset -a thread-number command.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/ALL
Applies the SET TASK command to all tasks.
/HOLD
/HOLD
/NOHOLD (default)
When the event
facility is THREADS, use the PTHREAD tset -h thread-number or
the PTHREAD tset -n thread-number command.
Controls whether a specified task is put on hold. The /HOLD
qualifier puts a specified task on hold.
Putting a task on hold prevents a task from entering the RUNNING
state. A task put on hold is allowed to make other state
transitions; in particular, it can change from the SUSPENDED
to the READY state.
A task already in the RUNNING state (the active task) can
continue to execute as long as it remains in the RUNNING state,
even though it is put on hold. If the task leaves the RUNNING
state for any reason (including expiration of a time slice, if
time slicing is enabled), it will not return to the RUNNING state
until released from the hold condition.
You can override the hold condition and force a task into the
RUNNING state with the SET TASK/ACTIVE command even if the task
is on hold.
The /NOHOLD qualifier releases a specified task from hold.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/PRIORITY
/PRIORITY=n
When the event facility is THREADS, use the PTHREAD
tset -s thread-number command.
Sets the priority of a specified task to n, where n is a decimal
integer from 0 to 15. This does not prevent the priority from
later changing in the course of execution, for example, while
executing an Ada rendezvous or POSIX Threads synchronization
event. This qualifier does not affect a task's scheduling policy.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/RESTORE
(Compaq Ada on VAX only) Restores the priority of a specified
task to the priority it had when it was created. Does not affect
the scheduling priority of the task.
/TIME_SLICE
/TIME_SLICE=t
Supported for Compaq Ada on VAX only. 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 /TIME_SLICE=0.0. /TIME_SLICE is valid only when the
event facility is ADA.
/VISIBLE
Makes the specified task the visible task, which is the task
whose call stack and register set are the current context for
looking up symbols, register values, routine calls, breakpoints,
and so on. Commands such as EXAMINE are directed at the visible
task. The /VISIBLE qualifier does not affect the active task.
When using /VISIBLE, you must specify one task.
4 Description
The SET TASK command enables you to establish the visible task
and the active task, control the execution of tasks, and cause
task state transitions, directly or indirectly.
To determine the current state of a task, use the SHOW TASK
command. The possible states are RUNNING, READY, SUSPENDED, and
TERMINATED.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
SET BREAK/EVENT
SET TRACE/EVENT
(SET, SHOW) EVENT_FACILITY
SHOW TASK|THREAD
4 Examples
1.DBG> SET TASK/ACTIVE %TASK 3
(Event facility = ADA) This command makes task 3 (task ID = 3)
the active task.
2.DBG> PTHREAD tset -a 3
(Event facility = THREADS) This command makes task 3 (task ID =
3) the active task.
3.DBG> SET TASK %NEXT_TASK
This command makes the next task in the debugger's task list
the visible task. (The /VISIBLE qualifier is a default for the
SET TASK command.)
4.DBG> SET TASK/HOLD/ALL
DBG> SET TASK/ACTIVE %TASK 1
DBG> GO
. . .
DBG> SET TASK/ACTIVE %TASK 3
DBG> STEP
. . .
In this example, the SET TASK/HOLD/ALL command freezes
the state of all tasks except the active task. Then, SET
TASK/ACTIVE is used selectively (along with the GO and STEP
commands) to observe the behavior of one or more specified
tasks in isolation.
3 TRACE
Establishes a tracepoint at the location denoted by an address
expression, at instructions of a particular class, or at the
occurrence of specified events.
Format
SET TRACE [address-expression[, . . . ]]
[WHEN(conditional-expression)]
[DO(command[; . . . ])]
4 Parameters
address-expression
Specifies an address expression (a program location) at which
a tracepoint is to be set. With high-level languages, this
is typically a line number, a routine name, or a label, and
can include a path name to specify the entity uniquely. More
generally, an address expression can also be a memory address or
a register and can be composed of numbers (offsets) and symbols,
as well as one or more operators, operands, or delimiters. For
information about the operators that you can use in address
expressions, type Help Address_Expressions.
Do not specify the asterisk (*) wildcard character. Do not
specify an address expression with the following qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/INTO
/[NO]JSB (VAX only)
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/TERMINATING
/VECTOR_INSTRUCTION (VAX only)
The /MODIFY and /RETURN qualifiers are used with specific kinds
of address expressions.
If you specify a memory address or an address expression whose
value is not a symbolic location, check (with the EXAMINE
command) that an instruction actually begins at the byte of
memory so indicated. If an instruction does not begin at this
byte, a run-time error can occur when an instruction including
that byte is executed. When you set a 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.
On VAX processors, CALLS and CALLG routines start with an entry
mask.
conditional-expression
Specifies a conditional expression in the currently set
language that is to be evaluated whenever execution reaches the
tracepoint. (The debugger checks the syntax of the expressions in
the WHEN clause when execution reaches the tracepoint, not when
the tracepoint is set.) If the expression is true, the debugger
reports that a tracepoint has been triggered. If an action (DO
clause) is associated with the tracepoint, it will occur at this
time. If the expression is false, a report is not issued, the
commands specified by the DO clause (if one was specified) are
not executed, and program execution is continued.
command
Specifies a debugger command to be executed as part of the DO
clause when trace action is taken. The debugger checks the syntax
of the commands in a DO clause when it executes the DO clause,
not when the tracepoint is set.
4 Qualifiers
/ACTIVATING
Causes the debugger to trace when a new process comes under
debugger control. See also the /TERMINATING qualifier.
/AFTER
/AFTER:n
Specifies that trace action not be taken until the nth time the
designated tracepoint is encountered (n is a decimal integer).
Thereafter, the tracepoint occurs every time it is encountered
provided that conditions in the WHEN clause (if specified) are
true. The SET TRACE/AFTER:1 command has the same effect as SET
TRACE.
/BRANCH
Causes the debugger to trace every branch instruction encountered
during program execution. See also the /INTO and /OVER
qualifiers.
/CALL
Causes the debugger to trace every call instruction encountered
during program execution, including the return instruction. See
also the /INTO and /OVER qualifiers.
/EVENT
/EVENT=event-name
Causes the debugger to trace the specified event (if that event
is defined and detected by the current event facility). If you
specify an address expression with /EVENT, causes the debugger
to trace whenever the specified event occurs for that address
expression. You cannot specify an address expression with certain
event names.
Event facilities are available for programs that call Ada or
SCAN routines or that use POSIX Threads services. To identify the
current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
/EXCEPTION
Causes the debugger to trace every exception that is signaled.
The trace action occurs before any application-declared exception
handlers are invoked.
As a result of a SET TRACE/EXCEPTION command, whenever your
program generates an exception, the debugger reports the
exception and resignals the exception, thus allowing any
application-declared exception handler to execute.
/INSTRUCTION
/INSTRUCTION
/INSTRUCTION[=(opcode[, . . . ])] (VAX only)
When you do not specify an opcode, causes the debugger to trace
every instruction encountered during program execution.
(VAX only) If you specify one or more opcodes, causes the
debugger to trace every instruction whose opcode is in the list.
If you specify a vector instruction, do not include an
instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION,
/MODIFY, /0, or /1) with the instruction mnemonic.
See also the /INTO and /OVER qualifiers.
/INTO
(Default) Applies only to tracepoints set with the following
qualifiers (that is, when an address expression is not explicitly
specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
When used with those qualifiers, /INTO causes the debugger to
trace the specified points within called routines (as well as
within the routine in which execution is currently suspended).
The /INTO qualifier is the default and is the opposite of /OVER.
When using /INTO, you can further qualify the trace action with
the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB
/JSB
/NOJSB
(VAX only) Qualifies /INTO. Use with /INTO and one of the
following qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ])
/LINE
/VECTOR_INSTRUCTION
The /JSB qualifier is the default for all languages except DIBOL.
It lets the debugger set tracepoints within routines that are
called by the JSB or CALL instruction. The /NOJSB qualifier (the
DIBOL default) specifies that tracepoints not be set within
routines called by JSB instructions. In DIBOL, application-
declared routines are called by the CALL instruction and DIBOL
Run-Time Library routines are called by the JSB instruction.
/LINE
Causes the debugger to trace the beginning of each source line
encountered during program execution. See also the /INTO and
/OVER qualifiers.
/MODIFY
Causes the debugger to trace when an instruction writes to and
changes the value of a location indicated by a specified address
expression. The address expression is typically a variable name.
The SET TRACE/MODIFY X command is equivalent to SET WATCH X
DO(GO). The SET TRACE/MODIFY command operates under the same
restrictions as SET WATCH.
If you specify an absolute address for the address expression,
the debugger might not be able to associate the address with
a particular data object. In this case, the debugger uses a
default length of 4 bytes. You can change this length, however,
by setting the type to either WORD (SET TYPE WORD, which changes
the default length to 2 bytes) or BYTE (SET TYPE BYTE, which
changes the default length to 1 byte). The SET TYPE LONGWORD
command restores the default length of 4 bytes.
/OVER
Applies only to tracepoints set with the following qualifiers
(that is, when an address expression is not explicitly
specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
When used with those qualifiers, /OVER causes the debugger to
trace the specified points only within the routine in which
execution is currently suspended (not within called routines).
The /OVER qualifier is the opposite of /INTO (which is the
default).
/RETURN
Causes the debugger to break on the return instruction of the
routine associated with the specified address expression (which
can be a routine name, line number, and so on). Breaking on the
return instruction enables you to inspect the local environment
(for example, obtain the values of local variables) while
the routine is still active. Note that the view of a local
environment may differ depending on your architecture. On VAX
processors, this qualifier can only be applied to routines called
with a CALLS or CALLG instruction; it cannot be used with JSB
routines. On Alpha processors, this qualifier can be applied to
any routine.
The address-expression parameter is an instruction address within
a routine. It can simply be a routine name, in which case it
specifies the routine start address. However, you can also
specify another location in a routine, so you can see only those
returns that are taken after a certain code path is followed.
A SET TRACE/RETURN command cancels a previous SET TRACE if you
specify the same address expression.
/SHARE
/SHARE (default)
/NOSHARE
Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
The /SHARE qualifier permits the debugger to set tracepoints
within shareable image routines as well as other routines. The
/NOSHARE qualifier specifies that tracepoints not be set within
shareable images.
/SILENT
/SILENT
/NOSILENT (default)
Controls whether the "trace . . . " message and the source line
for the current location are displayed at the tracepoint. The
/NOSILENT qualifier specifies that the message is displayed. The
/SILENT qualifier specifies that the message and source line are
not displayed. The /SILENT qualifier overrides /SOURCE.
/SOURCE
/SOURCE
/NOSOURCE (default)
Controls whether the source line for the current location is
displayed at the tracepoint. The /SOURCE qualifier specifies that
the source line is displayed. The /NOSOURCE qualifier specifies
that the source line is not displayed. The /SILENT qualifier
overrides /SOURCE. See also the SET STEP [NO]SOURCE command.
/SYSTEM
/SYSTEM (default)
/NOSYSTEM
Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)
The /SYSTEM qualifier permits the debugger to set tracepoints
within system routines (P1 space) as well as other routines. The
/NOSYSTEM qualifier specifies that tracepoints not be set within
system routines.
/TEMPORARY
Causes the tracepoint to disappear after it is triggered (the
tracepoint does not remain permanently set).
/TERMINATING
(Default) Causes the debugger to trace when a process does an
image exit. The debugger gains control and displays its prompt
when the last image of a one-process or multiprocess program
exits. See also the /ACTIVATING qualifier.
/VECTOR_INSTRUCTION
(VAX only) Causes the debugger to trace every vector instruction
encountered during execution. See also the /INTO and /OVER
qualifiers.
4 Description
When a tracepoint is triggered, the debugger takes the following
actions:
1. Suspends program execution at the tracepoint location.
2. If you specified /AFTER when you set the tracepoint, checks
the AFTER count. If the specified number of counts has not
been reached, execution is resumed and the debugger does not
perform the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the tracepoint. If the value of the
expression is false, execution is resumed and the debugger
does not perform the remaining steps.
4. Reports that execution has reached the tracepoint location by
issuing a "trace . . . " message, unless you specified /SILENT.
5. Displays the line of source code corresponding to the
tracepoint, unless you specified /NOSOURCE or /SILENT when
you set the tracepoint or entered a previous SET STEP NOSOURCE
command.
6. Executes the commands in a DO clause, if you specified one
when you set the tracepoint.
7. Resumes execution.
You set a tracepoint at a particular location in your program
by specifying an address expression with the SET TRACE command.
You set a tracepoint on consecutive source lines, classes of
instructions, or events by specifying a qualifier with the SET
TRACE command. Generally, you must specify either an address
expression or a qualifier, but not both. Exceptions are /EVENT
and /RETURN.
The /LINE qualifier sets a tracepoint on each line of source
code.
The following qualifiers set tracepoints on classes of
instructions. Using these qualifiers and /LINE causes the
debugger to trace every instruction of your program as it
executes and thus significantly slows down execution.
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/RETURN
/SYSEMULATE (Alpha only)
/VECTOR_INSTRUCTION (VAX only)
The following qualifiers set tracepoints on classes of events:
/ACTIVATING
/EVENT=event-name
/EXCEPTION
/TERMINATING
4 Description_(Continued...)
The following qualifiers affect what happens at a routine call:
/INTO
/[NO]JSB (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM
The following qualifiers affect what output is displayed when a
tracepoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of
tracepoints:
/AFTER:n
/TEMPORARY
Use the /MODIFY qualifier to monitor changes at program locations
(typically changes in the values of variables).
If you set a tracepoint at a location currently used as
a breakpoint, the breakpoint is canceled in favor of the
tracepoint, and conversely.
Tracepoints can be user defined or predefined. User-defined
tracepoints are set explicitly with the SET TRACE command.
Predefined tracepoints, which depend on the type of program you
are debugging (for example, Ada or multiprocess), are established
automatically when you start the debugger. Use the SHOW TRACE
command to identify all tracepoints that are currently set. Any
predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled
independently. For example, a location or event can have both
a user-defined and a predefined tracepoint. Canceling the user-
defined tracepoint does not affect the predefined tracepoint, and
conversely.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) TRACE
CANCEL ALL
GO
SET BREAK
(SET,SHOW) EVENT_FACILITY
SET STEP [NO]SOURCE
SET WATCH
4 Examples
1.DBG> SET TRACE SUB3
This command causes the debugger to trace the beginning of
routine SUB3 when that routine is executed.
2.DBG> SET TRACE/BRANCH/CALL
This command causes the debugger to trace every BRANCH
instruction and every CALL instruction encountered during
program execution.
3.DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM
This command causes the debugger to trace the beginning of
every source line, including lines in called routines (/INTO)
but not in shareable image routines (/NOSHARE) or system
routines (/NOSYSTEM).
4.DBG> SET TRACE/NOSOURCE TEST5\%LINE 14 WHEN (X .NE. 2) DO (EXAMINE Y)
This command causes the debugger to trace line 14 of module
TEST5 when X is not equal to 2. At the tracepoint, the EXAMINE
Y command is issued. The /NOSOURCE qualifier suppresses the
display of source code at the tracepoint. The syntax of
the conditional expression in the WHEN clause is language-
dependent.
5.DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0)
This command causes the debugger to trace when X is not equal
to 0. The condition is tested at each instruction encountered
during execution. The syntax of the conditional expression in
the WHEN clause is language-dependent.
6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
This command causes the debugger to trace the beginning of
routine SUB2 during execution. At the tracepoint, the DO
clause sets a watchpoint on variable K. The /SILENT qualifier
suppresses the "trace . . . " message and the display of source
code at the tracepoint. This example shows a convenient way
of setting a watchpoint on a nonstatic (stack or register)
variable. A nonstatic variable is defined only when its
defining routine (SUB2, in this case) is active (on the call
stack).
7.DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X)
This command causes the debugger to trace the return
instruction of routine ROUT4 (that is, just before execution
returns to the calling routine). At the tracepoint, the DO
clause issues the EXAMINE X command. This example shows a
convenient way of obtaining the value of a nonstatic variable
just before execution leaves that variable's defining routine.
8.DBG> SET TRACE/EVENT=TERMINATED
This command causes the debugger to trace the point at which
any task makes a transition to the TERMINATED state.
3 TYPE
Establishes the default type to be associated with program
locations that do not have a symbolic name (and, therefore, do
not have an associated compiler-generated type). When used with
/OVERRIDE, it establishes the default type to be associated with
all locations, overriding any compiler-generated types.
Format
SET TYPE type-keyword
4 Parameters
ASCIC
Sets the default type to counted ASCII string with a 1-byte count
field that precedes the string and gives its length. AC is also
accepted as a keyword.
ASCID
Sets the default type to ASCII string descriptor. The CLASS and
DTYPE fields of the descriptor are not checked, but the LENGTH
and POINTER fields provide the character length and address
of the ASCII string. The string is then displayed. AD is also
accepted as a keyword.
ASCII:n
Sets the default type to ASCII character string (length n bytes).
The length indicates both the number of bytes of memory to be
examined and the number of ASCII characters to be displayed. If
you do not specify a value for n, the debugger uses the default
value of 4 bytes. The value n is interpreted in decimal radix.
ASCIW
Sets the default type to counted ASCII string with a 2-byte count
field that precedes the string and gives its length. This data
type occurs in PASCAL and PL/I. AW is also accepted as a keyword.
ASCIZ
Sets the default type to zero-terminated ASCII string. The ending
zero byte indicates the end of the string. AZ is also accepted as
a keyword.
BYTE
Sets the default type to byte integer (length 1 byte).
D_FLOAT
Sets the default type to D_floating (length 8 bytes).
DATE_TIME
Sets the default type to date and time. This is a quadword
integer (length 8 bytes) containing the internal representation
of date and time. Values are displayed in the format dd-mmm-yyyy
hh:mm:ss.cc. Specify an absolute date and time as follows:
[dd-mmm-yyyy[:]] [hh:mm:ss.cc]
EXTENDED_FLOAT
(Alpha only) Sets the default type to IEEE X_floating (length 16
bytes).
FLOAT
On VAX systems, sets the default type to F_floating (length 4
bytes).
On Alpha systems, sets the default type to IEEE T_floating
(double precision, length 8 bytes).
G_FLOAT
Sets the default type to G_floating (length 8 bytes).
H_FLOAT
(VAX only) Sets the default type to H_floating (length 16 bytes).
INSTRUCTION
Sets the default type to instruction (variable length, depending
on the number of instruction operands and the kind of addressing
modes used).
LONG_FLOAT
(Alpha only) Sets the default type to IEEE S_Floating type
(single precision, length 4 bytes).
LONG_LONG_FLOAT
(Alpha only) Sets the default type to IEEE T_Floating type
(double precision, length 8 bytes).
LONGWORD
Sets the default type to longword integer (length 4 bytes). This
is the default type for program locations that do not have a
symbolic name (do not have a compiler-generated type).
OCTAWORD
Sets the default type to octaword integer (length 16 bytes).
PACKED:n
Sets the default type to packed decimal. The value of n is the
number of decimal digits. Each digit occupies one nibble (4
bits).
QUADWORD
Sets the default type to quadword integer (length 8 bytes).
TYPE=expression
Sets the default type to the type denoted by expression (the name
of a variable or data type declared in the program). This enables
you to specify an application-declared type.
S_FLOAT
(Alpha only) Sets the default type to IEEE S_Floating type
(single precision, length 4 bytes).
T_FLOAT
On Alpha systems, sets the default type to IEEE T_Floating type
(double precision, length 8 bytes).
X_FLOAT
On Alpha systems, sets the default type to IEEE X_floating type
(length 16 bytes).
WORD
Sets the default type to word integer (length 2 bytes).
4 Qualifiers
/OVERRIDE
Associates the type specified with all program locations, whether
or not they have a symbolic name (whether or not they have an
associated compiler-generated type).
4 Description
When you use EXAMINE, DEPOSIT, or EVALUATE commands, the default
types associated with address expressions affect how the debugger
interprets and displays program entities.
The debugger recognizes the compiler-generated types associated
with symbolic address expressions (symbolic names declared in
your program), and it interprets and displays the contents of
these locations accordingly. For program locations that do not
have a symbolic name and, therefore, no associated compiler-
generated type, the default type in all languages is longword
integer, which is appropriate for debugging 32-bit applications.
On Alpha systems, when debugging applications that use the 64-bit
address space, you should use the SET TYPE QUADWORD command.
The SET TYPE command enables you to change the default type
associated with locations that do not have a symbolic name.
The SET TYPE/OVERRIDE command enables you to set a default type
for all program locations, both those that do and do not have a
symbolic name.
The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII,
/BYTE, /G_FLOAT, and so on) which enable you to override, for the
duration of a single command, the type previously associated with
any program location.
Related commands:
CANCEL TYPE/OVERRIDE
DEPOSIT
EXAMINE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW,CANCEL) MODE
SHOW TYPE
4 Examples
1.DBG> SET TYPE ASCII:8
This command establishes an 8-byte ASCII character string as
the default type associated with untyped program locations.
2.DBG> SET TYPE/OVERRIDE LONGWORD
This command establishes longword integer as the default type
associated with both untyped program locations and program
locations that have compiler-generated types.
3.DBG> SET TYPE D_FLOAT
This command establishes D_Floating as the default type
associated with untyped program locations.
4.DBG> SET TYPE TYPE=(S_ARRAY)
This command establishes the type of the variable S_ARRAY as
the default type associated with untyped program locations.
3 VECTOR_MODE
Enables or disables a debugger vector mode option.
Applies only to VAX vectorized programs.
Format
SET VECTOR_MODE vector-mode-option
4 Parameters
vector-mode-option
Specifies the vector mode option. Valid keywords are as follows:
SYNCHRONIZED Specifies that the debugger force automatic
synchronization between the scalar and vector
processors whenever a vector instruction is
executed. Specifically, the debugger issues a
SYNC instruction after every vector instruction
and, in addition, an MSYNC instruction after
any vector instruction that accesses memory.
This forces the completion of all activities
associated with the vector instruction that is
being synchronized:
o Any exception that was caused by a vector
instruction is delivered before the next
scalar instruction is executed. 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 before the next scalar
instruction is executed.
The SET VECTOR_MODE SYNCHRONIZED command does
not issue an immediate SYNC or MSYNC instruction
at the time it is issued. To force immediate
synchronization, use the SYNCHRONIZE VECTOR_MODE
command.
NOSYNCHRONIZED (Default) Specifies that the debugger not force
synchronization between the scalar and vector
processors except for internal debugger purposes.
As a result, any synchronization is controlled
entirely by the program, and the program runs as
if it were not under debugger control.
4 Description
Vector mode options control the way in which the debugger
interacts with the vector processor. For details about the SET
VECTOR_MODE command, see the parameter descriptions.
Related commands:
(SHOW,SYNCHRONIZE) VECTOR_MODE
4 Examples
1.DBG> SET VECTOR_MODE SYNCHRONIZED
This command causes the debugger to force synchronization
between the scalar and vector processors after each vector
instruction is executed.
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
DBG>
The comments that follow refer to the callouts in the previous
example:
1 The SET VECTOR_MODE SYNCHRONIZED command causes the debugger
to force automatic synchronization between the scalar and
vector processors whenever a vector instruction is executed.
2 This STEP command suspends program execution on line 99,
just before a VVDIVD instruction is executed. Assume that,
in this example, the instruction will trigger a floating-
point divide-by-zero exception.
3 This STEP command executes the VVDIVD instruction, which
triggers the exception. The vector exception is delivered
immediately because the debugger is being operated in
synchronized vector mode.
3 WATCH
Establishes a watchpoint at the location denoted by an address
expression.
Format
SET WATCH address-expression[, . . . ]
[WHEN(conditional-expression)]
[DO(command[; . . . ])]
4 Parameters
address-expression
Specifies an address expression (a program location) at which
a watchpoint is to be set. With high-level languages, this is
typically the name of a program variable and can include a path
name to uniquely specify the variable. More generally, an address
expression can also be a memory address or a register and can
be composed of numbers (offsets) and symbols, as well as one or
more operators, operands, or delimiters. For information about
the operators that you can use in address expressions, see the
Address_Expressions online help topic.
Do not specify the asterisk (*) wildcard character.
conditional-expression
Specifies a conditional expression in the currently set language;
the expression is to be evaluated whenever execution reaches the
watchpoint. (The debugger checks the syntax of the expressions in
the WHEN clause when execution reaches the watchpoint, not when
the watchpoint is set.) If the expression is true, the debugger
reports that a watchpoint has been triggered. If an action (DO
clause) is associated with the watchpoint, it will occur at this
time. If the expression is false, a report is not issued, the
commands specified by the DO clause (if one was specified) are
not executed, and program execution is continued.
command
Specifies a debugger command to be executed as part of the DO
clause when watch action is taken. The debugger checks the syntax
of the commands in a DO clause when it executes the DO clause,
not when the watchpoint is set.
4 Qualifiers
/AFTER
/AFTER:n
Specifies that watch action not be taken until the nth time the
designated watchpoint is encountered (n is a decimal integer).
Thereafter, the watchpoint occurs every time it is encountered
provided that conditions in the WHEN clause are true. The SET
WATCH/AFTER:1 command has the same effect as SET WATCH.
/INTO
Specifies that the debugger is to monitor a nonstatic variable
by tracing instructions not only within the defining routine, but
also within a routine that is called from the defining routine
(and any other such nested calls). The SET WATCH/INTO command
enables you to monitor nonstatic variables within called routines
more precisely than SET WATCH/OVER; but the speed of execution
within called routines is faster with SET WATCH/OVER.
/OVER
Specifies that the debugger is to monitor a nonstatic variable
by tracing instructions only within the defining routine, not
within a routine that is called by the defining routine. As a
result, the debugger executes a called routine at normal speed
and resumes tracing instructions only when execution returns
to the defining routine. The SET WATCH/OVER command provides
faster execution than SET WATCH/INTO; but if a called routine
modifies the watched variable, execution is interrupted only upon
returning to the defining routine. When you set watchpoints on
nonstatic variables, SET WATCH/OVER is the default.
/SILENT
/SILENT
/NOSILENT (default)
Controls whether the "watch . . . " message and the source line
for the current location are displayed at the watchpoint. The
/NOSILENT qualifier specifies that the message is displayed. The
/SILENT qualifier specifies that the message and source line are
not displayed. The /SILENT qualifier overrides /SOURCE.
/SOURCE
/SOURCE (default)
/NOSOURCE
Controls whether the source line for the current location is
displayed at the watchpoint. The /SOURCE qualifier specifies that
the source line is displayed. The /NOSOURCE qualifier specifies
that the source line is not displayed. The /SILENT qualifier
overrides /SOURCE. See also the SET STEP [NO]SOURCE command.
/STATIC
/STATIC
/NOSTATIC
Enables you to override the debugger's default determination of
whether a specified variable (watchpoint location) is static or
nonstatic. The /STATIC qualifier specifies that the debugger
should treat the variable as a static variable, even though
it might be allocated in P1 space. This causes the debugger
to monitor the location by using the faster write-protection
method rather than by tracing every instruction. The /NOSTATIC
qualifier specifies that the debugger should treat the variable
as a nonstatic variable, even though it might be allocated in P0
space, and causes the debugger to monitor the location by tracing
every instruction. Be careful when using these qualifiers.
/TEMPORARY
Causes the watchpoint to disappear after it is triggered (the
watchpoint does not remain permanently set).
4 Description
When an instruction causes the modification of a watchpoint
location, the debugger takes the following actions:
1. Suspends program execution after that instruction has
completed execution.
2. If you specified /AFTER when you set the watchpoint, checks
the AFTER count. If the specified number of counts has not
been reached, execution continues and the debugger does not
perform the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified
one when you set the watchpoint. If the value of the
expression is false, execution continues and the debugger
does not perform the remaining steps.
4. Reports that execution has reached the watchpoint location
("watch of . . . ") unless you specified /SILENT.
5. Reports the old (unmodified) value at the watchpoint location.
6. Reports the new (modified) value at the watchpoint location.
7. Displays the line of source code at which execution is
suspended, unless you specified /NOSOURCE or /SILENT when
you set the watchpoint or entered a previous SET STEP NOSOURCE
command.
8. Executes the commands in a DO clause, if you specified one
when you set the watchpoint. If the DO clause contains a GO
command, execution continues and the debugger does not perform
the next step.
9. Issues the prompt.
For high-level language programs, the address expressions you
specify with the SET WATCH command are typically variable names.
If you specify an absolute memory address that is associated
with a compiler-generated type, the debugger symbolizes the
address and uses the length in bytes associated with that type
to determine the length in bytes of the watchpoint location. If
you specify an absolute memory address that the debugger cannot
associate with a compiler-generated type, the debugger watches 4
bytes of memory, by default, beginning at the byte identified by
the address expression. You can change this length, however, by
setting the type to either WORD (SET TYPE WORD, which changes the
default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes
the default length to 1 byte). SET TYPE LONGWORD restores the
default length of 4 bytes.
You can set watchpoints on aggregates (that is, entire arrays
or records). A watchpoint set on an array or record triggers
if any element of the array or record changes. Thus, you do not
need to set watchpoints on individual array elements or record
components. Note, however, that you cannot set an aggregate
watchpoint on a variant record.
You can also set a watchpoint on a record component, on an
individual array element, or on an array slice (a range of array
elements). A watchpoint set on an array slice triggers if any
element within that slice changes. When setting the watchpoint,
follow the syntax of the current language.
4 Description,_Continued...
The following qualifiers affect what output is seen when a
watchpoint is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of
watchpoints:
/AFTER:n
/TEMPORARY
The following qualifiers apply only to nonstatic variables:
/INTO
/OVER
The following qualifier overrides the debugger's determination of
whether a variable is static or nonstatic:
/[NO]STATIC
NOTE
On VAX systems, watchpoints set on variables whose addresses
are in global sections do not work. Attempting to set a
watchpoint on a location in a global section results in a
%DEBUG-E-BADWATCH message.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) WATCH
MONITOR
SET BREAK
SET STEP [NO]SOURCE
SET TRACE
4 Static_and_Nonstatic_Watchpoints
Static and Nonstatic Watchpoints
The technique for setting a watchpoint depends on whether the
variable is static or nonstatic.
A static variable is associated with the same memory address
throughout execution of the program. You can always set a
watchpoint on a static variable throughout execution.
A nonstatic variable is allocated on the call stack or in a
register and has a value only when its defining routine is active
(on the call stack). Therefore, you can set a watchpoint on a
nonstatic variable only when execution is currently suspended
within the scope of the defining routine (including any routine
called by the defining routine). The watchpoint is canceled when
execution returns from the defining routine. With a nonstatic
variable, the debugger traces every instruction to detect any
changes in the value of a watched variable or location.
Another distinction between static and nonstatic watchpoints
is speed of execution. To watch a static variable, the debugger
write-protects the page containing the variable. If your program
attempts to write to that page, an access violation occurs and
the debugger handles the exception, determining whether the
watched variable was modified. Except when writing to that page,
the program executes at normal speed.
To watch a nonstatic variable, the debugger traces every
instruction in the variable's defining routine and checks the
value of the variable after each instruction has been executed.
Since this significantly slows execution, the debugger issues a
message when you set a nonstatic watchpoint.
As explained in the next paragraphs, /[NO]STATIC, /INTO, and
/OVER enable you to exercise some control over speed of execution
and other factors when watching variables.
The debugger determines whether a variable is static or nonstatic
by checking how it is allocated. Typically, a static variable is
in P0 space (0 to 3FFFFFFF, hexadecimal); a nonstatic variable is
in P1 space (40000000 to 7FFFFFFF) or in a register. The debugger
issues a warning if you try to set a watchpoint on a variable
that is allocated in P1 space or in a register when execution is
not currently suspended within the scope of the defining routine.
The /[NO]STATIC qualifiers enable you to override this default
behavior. For example, if you have allocated nonstack storage
in P1 space, use /STATIC when setting a watchpoint on a variable
that is allocated in that storage area. This enables the debugger
to use the faster write-protection method of watching the
location instead of tracing every instruction. Conversely, if,
for example, you have allocated your own call stack in P0 space,
use /NOSTATIC when setting a watchpoint on a variable that is
allocated on that call stack. This enables the debugger to treat
the watchpoint as a nonstatic watchpoint.
You can also control the execution speed for nonstatic
watchpoints in called routines by using /INTO and /OVER.
On both Alpha and VAX processors, both static and nonstatic
watchpoints are available. With static watchpoints, the debugger
write-protects the page of memory in which the watched variable
is stored. Static watchpoints, therefore, would interfere with
the system service itself if not for the debugger's use of system
service interception (SSI).
If a static watchpoint is in effect then, through system service
interception, the debugger deactivates the static watchpoint,
asynchronous traps (ASTs), and thread switching, just before the
system service call. The debugger reactivates them just after
the system service call completes, putting the watchpoint, AST
enabling, and thread switching back to their original state
and, finally, checking for any watchpoint hits. This behavior
is designed to allow the system service to run as it normally
would (that is, without write-protected pages) and to prevent
the AST code or a different thread from potentially changing the
watchpointed location while the watchpoint is deactivated. Be
aware of this behavior if, for example, your application tests to
see if ASTs are enabled.
An active static watchpoint can cause a system service to fail,
likely with an ACCVIO status, if the system service is not
supported by the system service interception (SSI) vehicle
(DBGSSISHR on OpenVMS VAX systems and SYS$SSISHR on OpenVMS Alpha
systems). Any system service that is not in SYS$PUBLIC_VECTORS is
unsupported by SSI, including User Written System Services (UWSS)
and any loadable system services, such as $MOUNT.
When a static watchpoint is active, the debugger write-protects
the page containing the variable to be watched. A system service
call not supported by SSI can fail if it tries to write to that
page of user memory.
To avoid this failure, do either of the following:
o Deactivate the static watchpoint before the service call.
When the call completes, check the watchpoint manually and
reactivate it.
o Use nonstatic watchpoints. Note that nonstatic watchpoints can
slow execution.
If a watched location changes during a system service routine,
you will be notified, as usual, that the watchpoint occurred.
Note that, on rare occasions, stack may show one or more debugger
frames on top of the frame or frames for your program. To work
around this problem, enter one or more STEP/RETURN commands to
get back to your program.
System service interception is on by default, but on Alpha
processors only, you can disable interception prior to a
debugging session by issuing the following command:
$ DEFINE SSI$AUTO_ACTIVATE OFF
To reenable system service interception, issue one of the
following commands:
$ DEFINE SSI$AUTO_ACTIVATE ON
$ DEASSIGN SSI$AUTO_ACTIVATE
4 Global_Section_Watchpoints
On Alpha processors, you can set watchpoints on variables or
arbitrary program locations in global sections. A global section
is a region of memory that is shared among all processes of a
multiprocess program. A watchpoint that is set on a location in
a global section (a global section watchpoint) triggers when any
process modifies the contents of that location.
You set a global section watchpoint just as you would set a
watchpoint on a static variable. However, because of the way the
debugger monitors global section watchpoints, note the following
point. When setting watchpoints on arrays or records, performance
is improved if you specify individual elements rather than the
entire structure with the SET WATCH command.
If you set a watchpoint on a location that is not yet mapped to
a global section, the watchpoint is treated as a conventional
static watchpoint. When the location is subsequently mapped
to a global section, the watchpoint is automatically treated
as a global section watchpoint and an informational message is
issued. The watchpoint is then visible from each process of the
multiprocess program.
4 Examples
1.DBG> SET WATCH MAXCOUNT
This command establishes a watchpoint on the variable MAXCOUNT.
2.DBG> SET WATCH ARR
DBG> GO
. . .
watch of SUBR\ARR at SUBR\%LINE 12+8
old value:
(1): 7
(2): 12
(3): 3
new value:
(1): 7
(2): 12
(3): 28
break at SUBR\%LINE 14
DBG>
In this example, the SET WATCH command sets a watchpoint on
the three-element integer array, ARR. Execution is then resumed
with the GO command. The watchpoint triggers whenever any array
element changes. In this case, the third element changed.
3.DBG> SET WATCH ARR(3)
This command sets a watchpoint on element 3 of array ARR
(Fortran array syntax). The watchpoint triggers whenever
element 3 changes.
4.DBG> SET WATCH P_ARR[3:5]
This command sets a watchpoint on the array slice consisting
of elements 3 to 5 of array P_ARR (Pascal array syntax). The
watchpoint triggers whenever any of these elements change.
5.DBG> SET WATCH P_ARR[3]:P_ARR[5]
This command sets a separate watchpoint on each of elements
3 to 5 of array P_ARR (Pascal array syntax). Each watchpoint
triggers whenever its target element changes.
6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
In this example, variable K is a nonstatic variable and is
defined only when its defining routine, SUB2, is active (on
the call stack). The SET TRACE command sets a tracepoint on
SUB2. When the tracepoint is triggered during execution, the DO
clause sets a watchpoint on K. The watchpoint is then canceled
when execution returns from routine SUB2. The /SILENT qualifier
suppresses the "trace . . . " message and the display of source
code at the tracepoint.
3 WINDOW
Creates a screen window definition.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SET WINDOW window-name
AT (start-line,line-count
[,start-column,column-count])
4 Parameters
window-name
Specifies the name of the window you are defining. If a window
definition with that name already exists, it is canceled in favor
of the new definition.
start-line
Specifies the starting line number of the window. This line
displays the window title, or header line. The top line of the
screen is line 1.
line-count
Specifies the number of text lines in the window, not counting
the header line. The value must be at least 1. The sum of start-
line and line-count must not exceed the current screen height.
start-column
Specifies the starting column number of the window. This is the
column at which the first character of the window is displayed.
The leftmost column of the screen is column 1.
column-count
Specifies the number of characters per line in the window. The
value must be at least 1. The sum of start-column and column-
count must not exceed the current screen width.
4 Description
A screen window is a rectangular region on the terminal screen
through which you can view a display. The SET WINDOW command
establishes a window definition by associating a window name
with a screen region. You specify the screen region in terms of a
starting line and height (line count) and, optionally, a starting
column and width (column count). If you do not specify the
starting column and column count, the starting column defaults
to column 1 and the column count defaults to the current screen
width.
You can specify a window region in terms of expressions that use
the built-in symbols %PAGE and %WIDTH.
You can use the names of any windows you have defined with the
SET WINDOW command in a DISPLAY command to position displays on
the screen.
Window definitions are dynamic-that is, window dimensions expand
and contract proportionally when a SET TERMINAL command changes
the screen width or height.
Related commands:
DISPLAY
(SHOW,CANCEL) DISPLAY
(SET,SHOW) TERMINAL
(SHOW,CANCEL) WINDOW
4 Examples
1.DBG> SET WINDOW ONELINE AT (1,1)
This command defines a window named ONELINE at the top of the
screen. The window is one line deep and, by default, spans the
width of the screen.
2.DBG> SET WINDOW MIDDLE AT (9,4,30,20)
This command defines a window named MIDDLE at the middle of the
screen. The window is 4 lines deep starting at line 9, and 20
columns wide starting at column 30.
3.DBG> SET WINDOW FLEX AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
This command defines a window named FLEX that occupies a region
around the middle of the screen and is defined in terms of the
current screen height (%PAGE) and width (%WIDTH).
2 SHOW
3 ABORT_KEY
Identifies the Ctrl-key sequence currently defined to abort
the execution of a debugger command or to interrupt program
execution.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW ABORT_KEY
4 Description
By default, the Ctrl/C sequence, when entered within a debugging
session, aborts the execution of a debugger command and
interrupts program execution. The SET ABORT_KEY command enables
you to assign the abort function to another Ctrl-key sequence.
The SHOW ABORT_KEY command identifies the Ctrl-key sequence
currently in effect for the abort function.
Related commands:
Ctrl/C
SET ABORT_KEY
4 Example
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
DBG>
In this example, the first SHOW ABORT_KEY command identifies
the default abort command key sequence, Ctrl/C. The SET ABORT_
KEY = CTRL_P command assigns the abort-command function to
Ctrl/P, as confirmed by the second SHOW ABORT_KEY command.
3 AST
Indicates whether delivery of asynchronous system traps (ASTs) is
enabled or disabled.
Format
SHOW AST
4 Description
The SHOW AST command indicates whether delivery of ASTs is
enabled or disabled. The command does not identify an AST whose
delivery is pending. The delivery of ASTs is enabled by default
and with the ENABLE AST command. The delivery of ASTs is disabled
with the DISABLE AST command.
Related commands:
(ENABLE,DISABLE) AST
4 Example
DBG> SHOW AST
ASTs are enabled
DBG> DISABLE AST
DBG> SHOW AST
ASTs are disabled
DBG>
The SHOW AST command indicates whether the delivery of ASTs is
enabled.
3 ATSIGN
Identifies the default file specification established with
the last SET ATSIGN command. The debugger uses this file
specification when processing the execute procedure (@) command.
Format
SHOW ATSIGN
4 Description
Related commands:
@ (Execute Procedure)
SET ATSIGN
4 Examples
1.DBG> SHOW ATSIGN
No indirect command file default in effect, using DEBUG.COM
DBG>
This example shows that if you did not use the SET ATSIGN
command, the debugger assumes command procedures have the
default file specification SYS$DISK:[]DEBUG.COM.
2.DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> SHOW ATSIGN
Indirect command file default is USER:[JONES.DEBUG].DBG
DBG>
In this example, the SHOW ATSIGN command indicates the default
file specification for command procedures, as previously
established with the SET ATSIGN command.
3 BREAK
Displays information about breakpoints.
Format
SHOW BREAK
4 Qualifiers
/PREDEFINED
Displays information about predefined breakpoints.
/USER
Displays information about user-defined breakpoints.
4 Description
The SHOW BREAK command displays information about breakpoints
that are currently set, including any options such as WHEN or DO
clauses, /AFTER counts, and so on, and whether the breakpoints
are deactivated.
By default, SHOW BREAK displays information about both user-
defined and predefined breakpoints (if any). This is equivalent
to entering the SHOW BREAK/USER/PREDEFINED command. User-defined
breakpoints are set with the SET BREAK command. Predefined
breakpoints are set automatically when you start the debugger,
and they depend on the type of program you are debugging.
If you established a breakpoint using SET BREAK/AFTER:n, the SHOW
BREAK command displays the current value of the decimal integer
n, that is, the originally specified integer value minus 1 for
each time the breakpoint location was reached. (The debugger
decrements n each time the breakpoint location is reached until
the value of n is 0, at which time the debugger takes break
action.)
On Alpha systems, the SHOW BREAK command does not display
individual instructions when the break is on a particular class
of instruction (as with SET BREAK/CALL or SET BREAK/RETURN).
Related commands:
(ACTIVATE,CANCEL,DEACTIVATE,SET) BREAK
4 Examples
1.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
DBG>
The SHOW BREAK command identifies all breakpoints that are
currently set. This example indicates user-defined breakpoints
that are triggered whenever execution reaches SUB1\LOOP,
MAIN\MAIN, and SUB2\SUB2, respectively.
2.DBG> SHOW BREAK/PREDEFINED
predefined breakpoint on Ada event "DEPENDENTS_EXCEPTION"
for any value
predefined breakpoint on Ada event "EXCEPTION_TERMINATED"
for any value
DBG>
This command identifies the predefined breakpoints that are
currently set. The example shows two predefined breakpoints,
which are associated with Ada tasking exception events. These
breakpoints are set automatically by the debugger for all Ada
programs and for any mixed language program that is linked with
an Ada module.
3 CALLS
Identifies the currently active routine calls.
Format
SHOW CALLS [integer]
4 Parameters
integer
A decimal integer that specifies the number of routine calls to
be identified. If you omit the parameter, the debugger identifies
all routine calls for which it has information.
4 Qualifiers
/IMAGE
Displays the image name for each active call on the call stack.
4 Description
The SHOW CALLS command shows a traceback that lists the sequence
of active routine calls that lead to the routine in which
execution is currently suspended. Any recursive routine calls
are shown in the display, so you can use the SHOW CALLS command
to examine the chain of recursion.
SHOW CALLS displays one line of information for each call frame
on the call stack, starting with the most recent call. The top
line identifies the currently executing routine, the next line
identifies its caller, the following line identifies the caller
of the caller, and so on.
Even if your program contains no routine calls, the SHOW CALLS
command displays an active call. The reason for this is that
your program has a stack frame built for it when it is first
activated. Thus, if the SHOW CALLS display shows no active calls,
either your program has terminated or the call stack has been
corrupted.
On VAX processors, the sequence of routine calls corresponds to
the sequence of call frames on the call stack. Whenever a call is
made to a routine as your program executes, the operating system
creates a separate call frame on the call stack. Each call frame
stores information about the calling routine, for example, the PC
value that enables the SHOW CALLS command to symbolize module and
routine information.
On Alpha processors, a routine invocation can result in a stack
frame procedure (with a call frame on the stack), a register
frame procedure (with a call frame stored in the register set),
or a null frame procedure (without a call frame). SHOW CALLS
provides one line of information on all three: stack frame
procedures, register frame procedures, and null frame procedures.
(See the Alpha example below.)
4 Description,_Continued...
The following information is provided for each line of the SHOW
CALLS display:
o The name of the enclosing module. An asterisk (*) to the left
of a module name indicates that the module is set.
o The name of the calling routine, provided the module is set
(the first line shows the currently executing routine).
o The line number where the call was made in that routine,
provided the module is set (the first line shows the line
number at which execution is suspended).
o The value of the PC in the calling routine at the time
that control was transferred to the called routine. On VAX
processors, the PC value is shown as a memory address relative
to the nearest preceding symbol value (for example, a routine)
and also as an absolute address. On Alpha processors, the
PC is shown as a memory address relative to the first code
address in the module and also as an absolute address.
When you specify the /IMAGE qualifier, the debugger first does
a SET IMAGE command for each image that has debug information
(that is, it was linked using the /DEBUG or /TRACEBACK
qualifier). The debugger then displays the image name for
each active call on the calls stack. The output display has
been expanded and displays the image name in the first column.
The debugger suppresses the share$image_name module name,
because that information is provided by the /IMAGE qualifier.
The SET IMAGE command lasts only for the duration of the SHOW
CALLS/IMAGE command. The debugger restores the set image state
when the SHOW CALLS/IMAGE command is complete.
Related commands:
SHOW SCOPE
SHOW STACK
4 Examples
1.DBG> SHOW CALLS
module name routine name line rel PC abs PC
SUB2 SUB2 00000002 0000085A
*SUB1 SUB1 5 00000014 00000854
*MAIN MAIN 10 0000002C 0000082C
DBG>
This command displays information about the sequence of
currently active procedure calls on a VAX system.
2.DBG> SHOW CALLS
module name routine name line rel PC abs PC
*MAIN FFFF 31 00000000000002B8 00000000000203C4
-the above appears to be a null frame
in the same scope as the frame below
*MAIN MAIN 13 00000000000000A8 00000000000200A8
0000000000000000 FFFFFFFF8255A1F8
This example has been reformatted for Help, and may appear
slightly different from the actual output display. This example
is on an Alpha system. Note that sections of routine prologues
and epilogues appear to the debugger to be null frames. The
portion of the prologue before the change in the frame pointer
(FP) and the portion of the epilogue after restoration of the
FP each look like a null frame, and are reported accordingly.
3 DEFINE
Identifies the default (/ADDRESS, /COMMAND, /PROCESS_GROUP, or
/VALUE) currently in effect for the DEFINE command.
Format
SHOW DEFINE
4 Description
The default qualifier for the DEFINE command is the one last
established with the SET DEFINE command. If you did not enter a
SET DEFINE command, the default qualifier is /ADDRESS.
To identify a symbol defined with the DEFINE command, use the
SHOW SYMBOL/DEFINED command.
Related commands:
DEFINE
DEFINE/PROCESS_SET
DELETE
SET DEFINE
SHOW SYMBOL/DEFINED
4 Example
DBG> SHOW DEFINE
Current setting is: DEFINE/ADDRESS
DBG>
This command indicates that the DEFINE command is set for
definition by address.
3 DISPLAY
Identifies one or more existing screen displays.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW DISPLAY [display-name[, . . . ]]
4 Parameters
display-name
Specifies the name of a display. If you do not specify a name,
or if you specify the asterisk (*) wildcard character by itself,
all display definitions are listed. You can use the wildcard
within a display name. Do not specify a display name with the
/ALL qualifier.
4 Qualifiers
/ALL
Lists all display definitions.
4 Description
The SHOW DISPLAY command lists all displays according to their
order in the display list. The most hidden display is listed
first, and the display that is on top of the display pasteboard
is listed last.
For each display, the SHOW DISPLAY command lists its name,
maximum size, screen window, and display kind (including any
debug command list). It also identifies whether the display is
removed from the pasteboard or is dynamic (a dynamic display
automatically adjusts its window dimensions if the screen size is
changed with the SET TERMINAL command).
Related commands:
DISPLAY
EXTRACT/SCREEN_LAYOUT
(CANCEL) DISPLAY
(SET,CANCEL,SHOW) WINDOW
SHOW SELECT
4 Example
DBG> SHOW DISPLAY
display SRC at H1, size = 64, dynamic
kind = SOURCE (EXAMINE/SOURCE .%SOURCE_SCOPE\%PC)
display INST at H1, size = 64, removed, dynamic
kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\%PC)
display REG at RH1, size = 64, removed, dynamic, kind = REGISTER
display OUT at S45, size = 100, dynamic, kind = OUTPUT
display EXSUM at Q3, size = 64, dynamic, kind = DO (EXAMINE SUM)
display PROMPT at S6, size = 64, dynamic, kind = PROGRAM
DBG>
The SHOW DISPLAY command lists all displays currently defined.
In this example, they include the five predefined displays
(SRC, INST, REG, OUT, and PROMPT), and the user-defined DO
display EXSUM. Displays INST and REG are removed from the
display pasteboard: the DISPLAY command must be used to display
them on the screen.
3 EDITOR
Indicates the action taken by the EDIT command, as established by
the SET EDITOR command.
Format
SHOW EDITOR
4 Description
Related commands:
EDIT
SET EDITOR
4 Examples
1.DBG> SHOW EDITOR
The editor is SPAWNed, with command line
"EDT/START_POSITION=(n,1)"
DBG>
In this example, the EDIT command spawns the EDT editor in
a subprocess. The /START_POSITION qualifier appended to the
command line indicates that the editing cursor is initially
positioned at the beginning of the line that is centered in the
debugger's current source display.
2.DBG> SET EDITOR/CALLABLE_TPU
DBG> SHOW EDITOR
The editor is CALLABLE_TPU, with command line "TPU"
DBG>
In this example, the SHOW EDITOR command indicates that the
EDIT command invokes the callable version of the DEC Text
Processing Utility (DECTPU). The editing cursor is initially
positioned at the beginning of source line 1.
3 EVENT_FACILITY
Identifies the current event facility and the associated event
names.
Event facilities are available for programs that call Ada
routines or that use POSIX Threads services. On VAX processors,
event facilities are also available for programs that call SCAN
routines.
Format
SHOW EVENT_FACILITY
4 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,CANCEL) BREAK/EVENT
SET EVENT_FACILITY
(SET,CANCEL) TRACE/EVENT
SHOW BREAK
SHOW TASK
SHOW TRACE
4 Example
DBG> SHOW EVENT_FACILITY
event facility is THREADS
. . .
This command identifies the current event facility to be
THREADS (POSIX Threads) and lists the associated event names
that can be used with SET BREAK/EVENT or SET TRACE/EVENT
commands.
3 EXIT_HANDLERS
Identifies the exit handlers that have been declared in your
program.
Format
SHOW EXIT_HANDLERS
4 Description
The exit handler routines are displayed in the order that they
are called (that is, 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.
4 Example
DBG> SHOW EXIT_HANDLERS
exit handler at STACKS\CLEANUP
DBG>
This command identifies the exit handler routine CLEANUP, which
is declared in module STACKS.
3 IMAGE
Displays information about one or more images that are part of
your running program.
Format
SHOW IMAGE [image-name]
4 Parameters
image-name
Specifies the name of an image to be included in the display. If
you do not specify a name, or if you specify the asterisk (*)
wildcard character by itself, all images are listed. You can use
the wildcard within an image name.
4 Description
The SHOW IMAGE command displays the following information:
o Name of the image
o Start and end addresses of the image
o Whether the image has been set with the SET IMAGE command
(loaded into the run-time symbol table, RST)
o Current image that is your debugging context (marked with an
asterisk (*))
o Total number of images selected in the display
o Number of bytes allocated for the RST and other internal
structures
SHOW IMAGE does not display all of the memory ranges of an image
installed using the /RESIDENT qualifier. Instead, this command
displays only the process data region.
Related commands:
(SET,CANCEL) IMAGE
(SET,SHOW,CANCEL) MODULE
4 Example
DBG> SHOW IMAGE SHARE*
image name set base address end address
*SHARE yes 00000200 00000FFF
SHARE1 no 00001000 000017FF
SHARE2 yes 00018C00 000191FF
SHARE3 no 00019200 000195FF
SHARE4 no 00019600 0001B7FF
total images: 5 bytes allocated: 33032
DBG>
This SHOW IMAGE command identifies all of the images whose
names start with SHARE and which are associated with the
program. Images SHARE and SHARE2 are set. The asterisk (*)
identifies SHARE as the current image.
3 KEY
Displays the debugger predefined key definitions and those
created by the DEFINE/KEY command.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW KEY [key-name]
4 Parameters
key-name
Specifies a function key whose definition is displayed. Do not
use the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify a key name with /ALL or /DIRECTORY.
Valid key names are as follows:
Key LK201
Name Keyboard VT100-type VT52-type
PF1 PF1 PF1 Blue
PF2 PF2 PF2 Red
PF3 PF3 PF3 Black
PF4 PF4 PF4
KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9
PERIOD Keypad Keypad
period (.) period (.)
COMMA Keypad comma Keypad comma
(,) (,)
ENTER Enter ENTER ENTER
E1 Find
E2 Insert Here
E3 Remove
E4 Select
E5 Prev Screen
E6 Next Screen
HELP Help
DO Do
F6-F20 F6-F20
4 Qualifiers
/ALL
Displays all key definitions for the current state, by default,
or for the states specified with /STATE.
/BRIEF
Displays only the key definitions (by default, all qualifiers
associated with a key definition are also shown, including any
specified state).
/DIRECTORY
Displays the names of all the states for which keys have been
defined. Do not specify other qualifiers with this qualifier.
/STATE
/STATE=(state-name [, . . . ])
/NOSTATE (default)
Selects one or more states for which a key definition is
displayed. The /STATE qualifier displays key definitions for the
specified states. You can specify predefined key states, such as
DEFAULT and GOLD, or user-defined states. A state name can be any
appropriate alphanumeric string. The /NOSTATE qualifier displays
key definitions for the current state only.
4 Description
Keypad mode must be enabled (SET MODE KEYPAD) before you can use
this command. Keypad mode is enabled by default.
By default, the current key state is the DEFAULT state. You can
change the current state by using the SET KEY/STATE command or
by pressing a key that causes a state change (that is, a key that
was defined with DEFINE/KEY/LOCK_STATE or /SET_STATE).
Related commands:
DEFINE/KEY
DELETE/KEY
SET KEY
4 Examples
1.DBG> SHOW KEY/ALL
This command displays all the key definitions for the current
state.
2.DBG> SHOW KEY/STATE=BLUE KP8
GOLD keypad definitions:
KP8 = "Scroll/Top" (noecho,terminate,nolock)
DBG>
This command displays the definition for keypad key 8 in the
BLUE state.
3.DBG> SHOW KEY/BRIEF KP8
DEFAULT keypad definitions:
KP8 = "Scroll/Up"
DBG>
This command displays the definition for keypad key 8 in the
current state.
4.DBG> SHOW KEY/DIRECTORY
MOVE_GOLD
MOVE_BLUE
MOVE
GOLD
EXPAND_GOLD
EXPAND_BLUE
EXPAND
DEFAULT
CONTRACT_GOLD
CONTRACT_BLUE
CONTRACT
BLUE
DBG>
This command displays the names of the states for which keys
have been defined.
3 LANGUAGE
Identifies the current language.
Format
SHOW LANGUAGE
4 Description
The current language is the language last established with
the SET LANGUAGE command. If you did not enter a SET LANGUAGE
command, the current language is, by default, the language of the
module containing the main program.
Related command:
SET LANGUAGE
4 Example
DBG> SHOW LANGUAGE
language: BASIC
DBG>
This command displays the name of the current language as
BASIC.
3 LOG
Indicates whether the debugger is writing to a log file and
identifies the current log file.
Format
SHOW LOG
4 Description
The current log file is the log file last established by a SET
LOG command. By default, if you did not enter a SET LOG command,
the current log file is the file SYS$DISK:[]DEBUG.LOG.
Related commands:
SET LOG
SET OUTPUT [NO]LOG
SET OUTPUT [NO]SCREEN_LOG
4 Examples
1.DBG> SHOW LOG
not logging to DEBUG.LOG
DBG>
This command displays the name of the current log file as
DEBUG.LOG (the default log file) and reports that the debugger
is not writing to it.
2.DBG> SET LOG PROG4
DBG> SET OUTPUT LOG
DBG> SHOW LOG
logging to USER$:[JONES.WORK]PROG4.LOG
DBG>
In this example, the SET LOG command establishes that the
current log file is PROG4.LOG (in the current default
directory). The SET OUTPUT LOG command causes the debugger
to log debugger input and output into that file. The SHOW LOG
command confirms that the debugger is writing to the log file
PROG4.COM in your current default directory.
3 MARGINS
Identifies the current source-line margin settings for displaying
source code.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW MARGINS
4 Description
The current margin settings are the margin settings last
established with the SET MARGINS command. By default, if you
did not enter a SET MARGINS command, the left margin is set to 1
and the right margin is set to 255.
Related command:
SET MARGINS
4 Examples
1.DBG> SHOW MARGINS
left margin: 1 , right margin: 255
DBG>
This command displays the default margin settings of 1 and 255.
2.DBG> SET MARGINS 50
DBG> SHOW MARGINS
left margin: 1 , right margin: 50
DBG>
This command displays the default left margin setting of 1 and
the modified right margin setting of 50.
3.DBG> SET MARGINS 10:60
DBG> SHOW MARGINS
left margin: 10 , right margin: 60
DBG>
This command displays both margin settings modified to 10 and
60.
3 MODE
Identifies the current debugger modes (screen or no screen,
keypad or nokeypad, and so on) and the current radix.
Format
SHOW MODE
4 Description
The current debugger modes are the modes last established with
the SET MODE command. By default, if you did not enter a SET MODE
command, the current modes are the following:
DYNAMIC
NOG_FLOAT (D_float)
INTERRUPT
KEYPAD
LINE
NOSCREEN
SCROLL
NOSEPARATE
SYMBOLIC
Related commands:
(SET,CANCEL) MODE
(SET,SHOW,CANCEL) RADIX
4 Example
DBG> SHOW MODE
modes: symbolic, line, d_float, screen, scroll, keypad,
dynamic, interrupt, no separate window
input radix :decimal
output radix:decimal
DBG>
The SHOW MODE command displays the current modes and current
input and output radix.
3 MODULE
Displays information about the modules in the current image.
Format
SHOW MODULE [module-name]
4 Parameters
module-name
Specifies the name of a module to be included in the display. If
you do not specify a name, or if you specify the asterisk (*)
wildcard character by itself, all modules are listed. You can
use a wildcard within a module name. Shareable image modules are
selected only if you specify /SHARE.
4 Qualifiers
/RELATED
/RELATED
/NORELATED (default)
(Applies to Ada programs.) Controls whether the debugger
includes, in the SHOW MODULE display, any module that is
related to a specified module through a with-clause or subunit
relationship.
The SHOW MODULE/RELATED command displays related modules as
well as those specified. The display identifies the exact
relationship. By default (/NORELATED), no related modules are
selected for display (only the modules specified are selected).
/SHARE
/SHARE
/NOSHARE (default)
Controls whether the debugger includes, in the SHOW MODULE
display, any shareable images that have been linked with your
program. By default (/NOSHARE) no shareable image modules are
selected for display.
The debugger creates dummy modules for each shareable image in
your program. The names of these shareable "image modules" have
the prefix SHARE$. The SHOW MODULE/SHARE command identifies these
shareable image modules, as well as the modules in the current
image.
Setting a shareable image module loads the universal symbols
for that image into the run-time symbol table so that you can
reference these symbols from the current image. However, you
cannot reference other (local or global) symbols in that image
from the current image. This feature overlaps the effect of the
newer SET IMAGE and SHOW IMAGE commands.
4 Description
The SHOW MODULE command displays the following information about
one or more modules selected for display:
o Name of the module
o Programming language in which the module is coded, unless all
modules are coded in the same language
o Whether the module has been set with the SET MODULE command.
That is, whether the symbol records of the module have been
loaded into the debugger's run-time symbol table (RST)
o Space (in bytes) required in the RST for symbol records in
that module
o Total number of modules selected in the display
o Number of bytes allocated for the RST and other internal
structures (the amount of heap space in use in the main
debugger's process)
NOTE
The current image is either the main image (by default) or
the image established as the current image by a previous SET
IMAGE command.
For information specific to Ada programs, type Help
Language_Support Ada.
Related commands:
(SET,SHOW,CANCEL) IMAGE
SET MODE [NO]DYNAMIC
(SET,CANCEL) MODULE
(SET,SHOW,CANCEL) SCOPE
SHOW SYMBOL
4 Examples
1.DBG> SHOW MODULE
module name symbols size
TEST yes 432
SCREEN_IO no 280
total PASCAL modules: 2. bytes allocated: 2740.
DBG>
In this example, the SHOW MODULE command, without a parameter,
displays information about all of the modules in the current
image, which is the main image by default. This example shows
the display format when all modules have the same source
language. The symbols column shows that module TEST has been
set, but module SCREEN_IO has not.
2.DBG> SHOW MODULE FOO,MAIN,SUB*
module name symbols language size
FOO yes MACRO 432
MAIN no FORTRAN 280
SUB1 no FORTRAN 164
SUB2 no FORTRAN 204
total modules: 4. bytes allocated: 60720.
DBG>
In this example, the SHOW MODULE command displays information
about the modules FOO and MAIN, and all modules having the
prefix SUB. This example shows the display format when the
modules do not have the same source language.
3.DBG> SHOW MODULE/SHARE
module name symbols language size
FOO yes MACRO 432
MAIN no FORTRAN 280
. . .
SHARE$DEBUG no Image 0
SHARE$LIBRTL no Image 0
SHARE$MTHRTL no Image 0
SHARE$SHARE1 no Image 0
SHARE$SHARE2 no Image 0
total modules: 17. bytes allocated: 162280.
DBG> SET MODULE SHARE$SHARE2
DBG> SHOW SYMBOL * IN SHARE$SHARE2
In this example, the SHOW MODULE/SHARE command identifies all
of the modules in the current image and all of the shareable
images (the names of the shareable images are prefixed with
SHARE$. The SET MODULE SHARE$SHARE2 command sets the shareable
image module SHARE$SHARE2. The SHOW SYMBOL command identifies
any universal symbols defined in the shareable image SHARE2.
3 OUTPUT
Identifies the current output options.
Format
SHOW OUTPUT
4 Description
The current output options are the options last established with
the SET OUTPUT command. By default, if you did not enter a SET
OUTPUT command, the output options are: NOLOG, NOSCREEN_LOG,
TERMINAL, NOVERIFY.
Related commands:
SET LOG
SET MODE SCREEN
SET OUTPUT
4 Example
DBG> SHOW OUTPUT
noverify, terminal, screen_log,
logging to USER$:[JONES.WORK]DEBUG.LOG;9
DBG>
This command shows the following current output options:
o Debugger commands read from debugger command procedures are
not echoed on the terminal.
o Debugger output is being displayed on the terminal.
o The debugging session is being logged to the log file
USER$:[JONES.WORK]DEBUG.LOG;9.
o The screen contents are logged as they are updated in screen
mode.
3 PROCESS
Displays information about processes that are currently under
debugger control.
Format
SHOW PROCESS [process-spec[, . . . ]]
4 Parameters
process-spec
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
You can also use the asterisk (*) wildcard character or the /ALL
qualifier to specify all processes. Do not specify a process with
/ALL or /DYNAMIC. If you do not specify a process or /ALL with
/BRIEF, /FULL, or /[NO]HOLD, the visible process is selected.
4 Qualifiers
/ALL
Selects all processes known to the debugger for display.
/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.
/FULL
Displays maximum information for each process selected for
display.
/VISIBLE
(Default). Selects the visible process for display.
4 Description
The SHOW PROCESS command displays information about specified
processes and any images running in those processes.
The SHOW PROCESS/FULL command also displays information about the
availability and use of the vector processor. This information
is useful if you are debugging a program that uses vector
instructions.
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 it is terminated through 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 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. The visible process
is marked with an asterisk (*) in the leftmost column.
o The process name.
o The current debugging state for that process.
o The location (symbolized, if possible) at which execution of
the image is suspended in that process.
The SHOW PROCESS/FULL command gives additional information about
processes (see the examples).
Related commands:
CONNECT
Ctrl/C
DEFINE/PROCESS_SET
EXIT
QUIT
SET PROCESS
4 Examples
1.all> SHOW PROCESS
Number Name State Current PC
* 2 _WTA3: break SCREEN\%LINE 47
all>
By default, the SHOW PROCESS command displays one line of
information about the visible process (which is identified
with an asterisk (*) in the leftmost column). The process has
the process name _WTA3:. It is the second process brought under
debugger control (process number 2). It is on hold, and the
image's execution is suspended at a breakpoint at line 47 of
module SCREEN.
2.all> SHOW PROCESS TEST_3
Number Name State Current PC
7 TEST_3 watch of TEST_3\ROUT4\COUNT
TEST_3\%LINE 54
all>
This SHOW PROCESS command displays one line of information
about process TEST_3. The image is suspended at a watchpoint of
variable COUNT.
3.all> SHOW PROCESS/DYNAMIC
Dynamic process setting is enabled
all>
This command indicates that dynamic process setting is enabled.
3 RADIX
Identifies the current radix for the entry and display of integer
data or, if you specify /OVERRIDE, the current override radix.
Format
SHOW RADIX
4 Qualifiers
/OVERRIDE
Identifies the current override radix.
4 Description
The debugger can interpret and display integer data in any one
of four radixes: binary, decimal, hexadecimal, and octal. The
current radix for the entry and display of integer data is the
radix last established with the SET RADIX command.
If you did not enter a SET RADIX command, the default radix for
both data entry and display is decimal for most languages. On VAX
processors, the exceptions are BLISS and MACRO-32, which have a
default radix of hexadecimal. On Alpha processors, the exceptions
are BLISS, MACRO-32, and MACRO-64, which have a default radix of
hexadecimal.
The current override radix for the display of all data is the
override radix last established with the SET RADIX/OVERRIDE
command. If you did not enter a SET RADIX/OVERRIDE command, the
override radix is "none".
Related commands:
DEPOSIT
EVALUATE
EXAMINE
(SET,CANCEL) RADIX
4 Examples
1.DBG> SHOW RADIX
input radix: decimal
output radix: decimal
DBG>
This command identifies the input radix and output radix as
decimal.
2.DBG> SET RADIX/OVERRIDE HEX
DBG> SHOW RADIX/OVERRIDE
output override radix: hexadecimal
DBG>
In this example, the SET RADIX/OVERRIDE command sets the
override radix to hexadecimal and the SHOW RADIX/OVERRIDE
command indicates the override radix. This means that commands
such as EXAMINE display all data as hexadecimal integer data.
3 SCOPE
Identifies the current scope search list for symbol lookup.
Format
SHOW SCOPE
4 Description
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.
The current scope search list is the scope search list last
established with the SET SCOPE command. By default, if you did
not enter a SET SCOPE command, the current scope search list is
0,1,2, . . . ,n.
The default scope search list specifies that, for a symbol
without a path-name prefix, a symbol lookup such as EXAMINE X
first looks for X in the routine that is 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.
If you used a decimal integer in the SET SCOPE command to
represent a routine in the call stack, the SHOW SCOPE command
displays the name of the routine represented by the integer, if
possible.
Related commands:
(SET,CANCEL) SCOPE
4 Examples
1.DBG> CANCEL SCOPE
DBG> SHOW SCOPE
scope:
* 0 [ = EIGHTQUEENS\TRYCOL\REMOVEQUEEN ],
1 [ = EIGHTQUEENS\TRYCOL ],
2 [ = EIGHTQUEENS\TRYCOL 1 ],
3 [ = EIGHTQUEENS\TRYCOL 2 ],
4 [ = EIGHTQUEENS\TRYCOL 3 ],
5 [ = EIGHTQUEENS\TRYCOL 4 ],
6 [ = EIGHTQUEENS ]
DBG> SET SCOPE/CURRENT 2
DBG> SHOW SCOPE
scope:
0 [ = EIGHTQUEENS\TRYCOL\REMOVEQUEEN ],
1 [ = EIGHTQUEENS\TRYCOL ],
* 2 [ = EIGHTQUEENS\TRYCOL 1 ],
3 [ = EIGHTQUEENS\TRYCOL 2 ],
4 [ = EIGHTQUEENS\TRYCOL 3 ],
5 [ = EIGHTQUEENS\TRYCOL 4 ],
6 [ = EIGHTQUEENS ]
DBG>
The CANCEL SCOPE command restores the default scope search
list, which is displayed by the (first) SHOW SCOPE command. In
this example, execution is suspended at routine REMOVEQUEEN,
after several recursive calls to routine TRYCOL. The asterisk
(*) indicates that the scope search list starts with scope 0,
the scope of the routine in which execution is suspended.
The SET SCOPE/CURRENT command resets the start of the scope
search list to scope 2. Scope 2 is the scope of the caller of
the routine in which execution is suspended. The asterisk in
the output of the (second) SHOW SCOPE command indicates that
the scope search list now starts with scope 2.
2.DBG> SET SCOPE 0,STACKS\R2,SCREEN_IO,\
DBG> SHOW SCOPE
scope:
0, [= TEST ],
STACKS\R2,
SCREEN_IO,
\
DBG>
In this example, the SET SCOPE command directs 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, which is in module TEST). 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_IO, and then finally in the global
symbol table (denoted by the global scope (\)). The SHOW SCOPE
command identifies the current scope search list for symbol
lookup. No asterisk is shown in the SHOW SCOPE display unless
the default scope search list is in effect or you have entered
a SET SCOPE/CURRENT command.
3 SEARCH
Identifies the default qualifiers (/ALL or /NEXT, /IDENTIFIER or
/STRING) currently in effect for the SEARCH command.
Format
SHOW SEARCH
4 Description
The default qualifiers for the SEARCH command are the default
qualifiers last established with the SET SEARCH command. If you
did not enter a SET SEARCH command, the default qualifiers are
/NEXT and /STRING.
Related commands:
SEARCH
(SET,SHOW) LANGUAGE
SET SEARCH
4 Example
DBG> SHOW SEARCH
search settings: search for next occurrence, as a string
DBG> SET SEARCH IDENT
DBG> SHOW SEARCH
search settings: search for next occurrence, as an identifier
DBG> SET SEARCH ALL
DBG> SHOW SEARCH
search settings: search for all occurrences, as an identifier
DBG>
In this example, the first SHOW SEARCH command displays the
default settings for the SET SEARCH command. By default, the
debugger searches for and displays the next occurrence of the
string.
The second SHOW SEARCH command indicates that the debugger
searches for the next occurrence of the string, but displays
the string only if it is not bounded on either side by a
character that can be part of an identifier in the current
language.
The third SHOW SEARCH command indicates that the debugger
searches for all occurrences of the string, but displays
the strings only if they are not bounded on either side by a
character that can be part of an identifier in the current
language.
3 SELECT
Identifies the displays currently selected for each of the
display attributes: error, input, instruction, output, program,
prompt, scroll, and source.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW SELECT
4 Description
The display attributes have the following properties:
o A display that has the error attribute displays debugger
diagnostic messages.
o A display that has the input attribute echoes your debugger
input.
o A display that has the instruction attribute displays the
decoded instruction stream of the routine being debugged.
The display is updated when you enter an EXAMINE/INSTRUCTION
command.
o A display that has the output attribute displays any debugger
output that is not directed to another display.
o A display that has the program attribute displays program
input and output. Currently only the PROMPT display can have
the program attribute.
o A display that has the prompt attribute is where the debugger
prompts for input. Currently, only the PROMPT display can have
the PROMPT attribute.
o A display that has the scroll attribute is the default display
for the SCROLL, MOVE, and EXPAND commands.
o A display that has the source attribute displays the source
code of the module being debugged, if available. The display
is updated when you enter a TYPE or EXAMINE/SOURCE command.
Related commands:
SELECT
SHOW DISPLAY
4 Example
DBG> SHOW SELECT
display selections:
scroll = SRC
input = none
output = OUT
error = PROMPT
source = SRC
instruction = none
program = PROMPT
prompt = PROMPT
DBG>
The SHOW SELECT command identifies the displays currently
selected for each of the display attributes. These selections
are the defaults for languages.
3 SOURCE
Identifies the source directory search lists and search methods
currently in effect.
Format
SHOW SOURCE
4 Qualifiers
/DISPLAY
Identifies the search list used when the debugger displays source
code.
/EDIT
Identifies the search list to be used during execution of the
debugger's EDIT command.
4 Description
The SET SOURCE/MODULE=module-name command establishes a source
directory search list for a particular module. The SET SOURCE
command establishes a source directory search list for all
modules not explicitly mentioned in a SET SOURCE/MODULE=module-
name command. When you have used those commands, SHOW SOURCE
identifies the source directory search list associated with each
search category.
If a source directory search list has not been established by
using the SET SOURCE or SET SOURCE/MODULE=module-name command,
the SHOW SOURCE command indicates that no directory search list
is currently in effect. In this case, the debugger expects each
source file to be in the same directory that it was in at compile
time (the debugger also checks that the version number and the
creation date and time of a source file match the information in
the debugger's symbol table).
The /EDIT qualifier is needed when the files used for the display
of source code are different from the files to be edited by using
the EDIT command. This is the case with Ada programs. For Ada
programs, the SHOW SOURCE command identifies the search list of
files used for source display (the copied source files in Ada
program libraries); the SHOW SOURCE/EDIT command identifies the
search list for the source files you edit when using the EDIT
command.
For information specific to Ada programs, see the
Language_Support Ada help topic.
Related commands:
(SET,CANCEL) SOURCE
4 Examples
1.DBG> SHOW SOURCE
no directory search list in effect,
match the latest source file version
DBG> SET SOURCE [PROJA],[PROJB],DISK:[PETER.PROJC]
DBG> SHOW SOURCE
source directory search list for all modules,
match the latest source file version:
[PROJA]
[PROJB]
DISK:[PETER.PROJC]
DBG>
In this example, the SET SOURCE command directs the debugger to
search the directories [PROJA],[PROJB], and DISK:[PETER.PROJC].
By default, the debugger searches for the latest version of
source files.
2.DBG> SET SOURCE/MODULE=CTEST/EXACT [], DISK$2:[PROJD]
DBG> SHOW SOURCE
source directory search list for CTEST,
match the exact source file version:
[]
DISK$2:[PROJD]
source directory search list for all other modules,
match the latest source file version:
[PROJA]
[PROJB]
DISK:[PETER.PROJC]
DBG>
In this example, the SET SOURCE command directs the debugger
to search the current default directory ([]) and directory
DISK$2:[PROJD] for source files to use with the module CTEST.
The /EXACT qualifier specifies that the search will locate
the exact version of the CTEST source files found in the debug
symbol table.
3 STACK
Displays information on the currently active routine calls.
Format
SHOW STACK [integer]
4 Parameters
integer
Specifies the number of frames to display. If you omit the
parameter, the debugger displays information about all call
frames.
4 Description
For each call frame, the SHOW STACK command displays information
such as the condition handler, saved register values, and the
argument list, if any. The latter is the list of arguments passed
to the subroutine with that call. In some cases the argument list
can contain the addresses of actual arguments. In such cases, use
the EXAMINE address-expression command to display the values of
these arguments.
On VAX processors, each routine invocation results in a call
frame on the call stack.
On Alpha processors, a routine invocation can result in a stack
frame procedure (with a call frame on the stack), a register
frame procedure (with a call frame stored in the register set),
or a null frame procedure (without a call frame). SHOW STACK
provides information on all three: stack frame procedures,
register frame procedures, and null frame procedures. (See
Example 2 below.)
Related command:
SHOW CALLS
4 Examples
1.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
DBG>
In this example for VAX systems, the SHOW STACK command
displays information about all call stack frames at the current
PC location.
3 STEP
Identifies the default qualifiers (/INTO, /INSTRUCTION, /NOSILENT
and so on) currently in effect for the STEP command.
Format
SHOW STEP
4 Description
The default qualifiers for the STEP command are the default
qualifiers last established by the SET STEP command. If you did
not enter a SET STEP command, the default qualifiers are /LINE,
/OVER, /NOSILENT, and /SOURCE.
Enabling screen mode by pressing PF1-PF3 enters the SET STEP
NOSOURCE command as well as the SET MODE SCREEN command (to
eliminate redundant source display in output and DO displays).
In that case, the default qualifiers are /LINE, /OVER, /NOSILENT,
and /NOSOURCE.
Related commands:
STEP
SET STEP
4 Example
DBG> SET STEP INTO,NOSYSTEM,NOSHARE,INSTRUCTION,NOSOURCE
DBG> SHOW STEP
step type: nosystem, noshare, nosource, nosilent, into routine calls,
by instruction
DBG>
In this example, the SHOW STEP command indicates that the
debugger take the following actions:
o Steps into called routines, but not those in system space or
in shareable images
o Steps by instruction
o Does not display lines of source code while stepping
3 SYMBOL
Displays information about the symbols in the debugger's run-time
symbol table (RST) for the current image.
NOTE
The current image is either the main image (by default) or
the image established as the current image by a previous SET
IMAGE command.
Format
SHOW SYMBOL symbol-name[, . . . ] [IN scope[, . . . ]]
4 Parameters
symbol-name
Specifies a 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. Compound names such as RECORD.FIELD
or ARRAY[1,2] are not valid. If you specify the asterisk (*)
wildcard character by itself, all symbols are listed. You can use
the wildcard within a symbol name.
scope
Specifies 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 this parameter, all set modules and the
global symbol table (GST) for the current image are searched
for symbols that match the name specified by the symbol-name
parameter.
4 Qualifiers
/ADDRESS
Displays 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."
On Alpha processors, the command SHOW SYMBOL/ADDRESS procedure-
name displays both the code address and procedure descriptor
address of a specified routine, entry point, or Ada package.
/DEFINED
Displays symbols you have defined with the DEFINE command (symbol
definitions that are in the DEFINE symbol table).
/DIRECT
Displays only those symbols that are declared directly in the
scope parameter. Symbols declared in lexical entities nested
within the scope specified by the scope parameters are not shown.
/FULL
Displays all information associated with the /ADDRESS, /TYPE, and
/USE_CLAUSE qualifiers.
For C++ modules, if symbol-name is a class, SHOW SYMBOL/FULL also
displays information about the class.
/LOCAL
Displays symbols that are defined with the DEFINE/LOCAL command
(symbol definitions that are in the DEFINE symbol table).
/TYPE
Displays data type information for each selected symbol.
/USE_CLAUSE
(Applies to Ada programs.) 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.
4 Description
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.
If you do not specify a qualifier, the SHOW SYMBOL command lists
all of the 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, 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.
For information specific to Ada programs, type Help
Language_Support Ada.
Related commands:
DEFINE
DELETE
SET MODE [NO]LINE
SET MODE [NO]SYMBOLIC
SHOW DEFINE
SYMBOLIZE
4 Examples
1.DBG> SHOW SYMBOL I
data FORARRAY\I
DBG>
This command 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
DBG>
This command shows that symbol INTARRAY1 is defined in module
FORARRAY and has a memory address of 0009DE8B.
3.DBG> SHOW SYMBOL *PL*
This command lists all the symbols whose names contain the
string "PL".
4.DBG> SHOW SYMBOL/TYPE COLOR
data SCALARS\MAIN\COLOR
enumeration type (primary, 3 elements), size: 4 bytes
This command shows that the variable COLOR is an enumeration
type.
5.DBG> SHOW SYMBOL/TYPE/ADDRESS *
This command displays all information about all symbols.
6.DBG> SHOW SYMBOL * IN MOD3\COUNTER
routine MOD3\COUNTER
data MOD3\COUNTER\X
data MOD3\COUNTER\Y
DBG>
This command lists all the symbols that are defined in the
scope denoted by the path name MOD3\COUNTER.
7.DBG> DEFINE/COMMAND SB=SET BREAK
DBG> SHOW SYMBOL/DEFINED SB
defined SB
bound to: SET BREAK
was defined /command
DBG>
In this example, the DEFINE/COMMAND command defines SB as
a symbol for the SET BREAK command. The SHOW SYMBOL/DEFINED
command displays that definition.
3 TASK
Displays information about the tasks of a multithread program
(also called a tasking program).
NOTE
SET TASK and SET THREAD are synonymous commands. They
perform identically.
Format
SHOW THREAD [task-spec[, . . . ]]
4 Parameters
task-spec
Specifies a task value. Use any of the following forms:
o When the event facility is THREADS:
- A task (thread) name as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW
THREAD display.
o When the event facility is ADA:
- A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
- A task ID (for example, 2), as indicated in a SHOW THREAD
display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or
EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_ The task previous to the visible task in the
TASK debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are
the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard character. Instead, use the
/ALL qualifier. Do not specify a task with /ALL, /STATISTICS, or
/TIME_SLICE.
4 Qualifiers
/ALL
Selects all existing tasks for display-namely, tasks that have
been created and (in the case of Ada tasks) whose master has not
yet terminated.
/CALLS
/CALLS[=n]
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
When the event facility is THREADS, use the
PTHREAD thread -f thread-number
command.
Displays additional information for each task selected for
display. The additional information is provided if you use /FULL
by itself or with /CALLS or /STATISTICS.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/HOLD
/HOLD
/NOHOLD (default)
When the event facility is THREADS, use the PTHREAD tset -n
thread-number command.
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.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/IMAGE
Displays the image name for each active call on the call stack.
Valid only with the /CALLS qualifier.
/PRIORITY
/PRIORITY=(n[, . . . ])
When the event facility is THREADS, use the PTHREAD tset -s
thread-number command.
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.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/STATE
/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.
/STATISTICS
(Compaq Ada on VAX only) 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.
/TIME_SLICE
(VAX only) 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, that was specified in the program.
If no time-slice value was previously established, the value is
0.0-that is, time slicing is disabled.
/TIME_SLICE is valid only when the event facility is ADA.
4 Description
A task can first appear in a SHOW THREAD display as soon as it
is created. A task can no longer appear in a SHOW THREAD display
if it is terminated or (in the case of an Ada tasking program)
if its master is terminated. By default, the SHOW THREAD command
displays one line of information for each task selected.
When you specify the /IMAGE qualifier, the debugger first does a
SET IMAGE command for each image that has debug information (that
is, it was linked using the /DEBUG or /TRACEBACK qualifier). The
debugger then displays the image name for each active call on the
calls stack. The output display has been expanded and displays
the image name in the first column.
The debugger suppresses the share$image_name module name, because
that information is provided by the /IMAGE qualifier.
The SET IMAGE command lasts only for the duration of the SHOW
THREAD/CALLS/IMAGE command. The debugger restores the set image
state when the SHOW THREAD/CALLS/IMAGE command is complete.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
(SET, SHOW) EVENT_FACILITY
SET TASK|THREAD
4 Examples
1.DBG> SHOW EVENT_FACILITY
event facility is ADA
. . .
DBG> SHOW TASK/ALL
task id pri hold state substate task object
* %TASK 1 7 RUN 122624
%TASK 2 7 HOLD SUSP Accept H4.MONITOR
%TASK 3 6 READY Entry call H4.CHECK_IN
DBG>
In this example, the SHOW EVENT_FACILITY command identifies
ADA as the current event facility. The SHOW TASK/ALL command
provides basic information about all the tasks that were
created through Ada services and currently exist. One line
is devoted to each task. The active task is marked with an
asterisk (*). In this example, it is also the active task (the
task that is in the RUN state).
2.DBG> SHOW TASK %ACTIVE_TASK,3,MONITOR
This command selects the active task, 3, and task MONITOR for
display.
3.DBG> SHOW TASK/PRIORITY=6
This command selects all tasks with priority 6 for display.
4.DBG> SHOW TASK/STATE=(RUN,SUSP)
This command selects all tasks that are either running or
suspended for display.
5.DBG> SHOW TASK/STATE=SUSP/NOHOLD
This command selects all tasks that are both suspended and not
on hold for display.
6.DBG> SHOW TASK/STATE=(RUN,SUSP)/PRIO=7 %VISIBLE_TASK, 3
This command selects for display those tasks among the visible
task and %TASK 3 that are in either the RUNNING or SUSPENDED
state and have priority 7.
3 TERMINAL
Identifies the current terminal screen height (page) and width
being used to format output.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW TERMINAL
4 Description
The current terminal screen height and width are the height and
width last established by the SET TERMINAL command. By default,
if you did not enter a SET TERMINAL command, the current height
and width are the height and width known to the terminal driver,
as displayed by the DCL command SHOW TERMINAL (usually 24 lines
and 80 columns for VT-series terminals).
Related commands:
SET TERMINAL
SHOW DISPLAY
SHOW WINDOW
4 Example
DBG> SHOW TERMINAL
terminal width: 80
page: 24
wrap: 80
DBG>
This command displays the current terminal screen width and
height (page) as 80 columns and 24 lines, and the message wrap
setting at column 80.
3 THREAD
Displays information about the tasks of a multithread program
(also called a tasking program).
NOTE
SET TASK and SET THREAD are synonymous commands. They
perform identically.
Format
SHOW THREAD [task-spec[, . . . ]]
4 Parameters
task-spec
Specifies a task value. Use any of the following forms:
o When the event facility is THREADS:
- A task (thread) name as declared in the program, or a
language expression that yields a task ID number.
- A task ID number (for example, 2), as indicated in a SHOW
THREAD display.
o When the event facility is ADA:
- A task (thread) name as declared in the program, or a
language expression that yields a task value. You can use a
path name.
- A task ID (for example, 2), as indicated in a SHOW THREAD
display.
o One of the following task built-in symbols:
%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or
EXIT command executes.
%CALLER_TASK (Applies only to Ada programs.) When an accept
statement executes, the task that called the
entry associated with the accept statement.
%NEXT_TASK The task after the visible task in the
debugger's task list. The ordering of tasks
is arbitrary but consistent within a single
run of a program.
%PREVIOUS_ The task previous to the visible task in the
TASK debugger's task list.
%VISIBLE_TASK The task whose call stack and register set are
the current context for looking up symbols,
register values, routine calls, breakpoints,
and so on.
Do not use the asterisk (*) wildcard character. Instead, use the
/ALL qualifier. Do not specify a task with /ALL, /STATISTICS, or
/TIME_SLICE.
4 Qualifiers
/ALL
Selects all existing tasks for display-namely, tasks that have
been created and (in the case of Ada tasks) whose master has not
yet terminated.
/CALLS
/CALLS[=n]
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
When the event facility is THREADS, use the command.
Displays additional information for each task selected for
display. The additional information is provided if you use /FULL
by itself or with /CALLS or /STATISTICS.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/HOLD
/HOLD
/NOHOLD (default)
When the event facility is THREADS, use the PTHREAD tset -n
thread-number command.
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.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/IMAGE
Displays the image name for each active call on the call stack.
Valid only with the /CALLS qualifier.
/PRIORITY
/PRIORITY=(n[, . . . ])
When the event facility is THREADS, use the PTHREAD tset -s
thread-number command.
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.
You can get help on POSIX Threads debugger commands by typing
PTHREAD HELP.
See the Guide to POSIX Threads Library for more information about
using the POSIX Threads debugger.
/STATE
/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.
/STATISTICS
(Compaq Ada on VAX only) 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.
/TIME_SLICE
(VAX only) 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, that was specified in the program.
If no time-slice value was previously established, the value is
0.0-that is, time slicing is disabled.
/TIME_SLICE is valid only when the event facility is ADA.
4 Description
A task can first appear in a SHOW THREAD display as soon as it
is created. A task can no longer appear in a SHOW THREAD display
if it is terminated or (in the case of an Ada tasking program)
if its master is terminated. By default, the SHOW THREAD command
displays one line of information for each task selected.
When you specify the /IMAGE qualifier, the debugger first does a
SET IMAGE command for each image that has debug information (that
is, it was linked using the /DEBUG or /TRACEBACK qualifier). The
debugger then displays the image name for each active call on the
calls stack. The output display has been expanded and displays
the image name in the first column.
The debugger suppresses the share$image_name module name, because
that information is provided by the /IMAGE qualifier.
The SET IMAGE command lasts only for the duration of the SHOW
THREAD/CALLS/IMAGE command. The debugger restores the set image
state when the SHOW THREAD/CALLS/IMAGE command is complete.
Related commands:
DEPOSIT/TASK
EXAMINE/TASK
(SET, SHOW) EVENT_FACILITY
SET TASK|THREAD
4 Examples
1.DBG> SHOW EVENT_FACILITY
event facility is ADA
. . .
DBG> SHOW TASK/ALL
task id pri hold state substate task object
* %TASK 1 7 RUN 122624
%TASK 2 7 HOLD SUSP Accept H4.MONITOR
%TASK 3 6 READY Entry call H4.CHECK_IN
DBG>
In this example, the SHOW EVENT_FACILITY command identifies
ADA as the current event facility. The SHOW TASK/ALL command
provides basic information about all the tasks that were
created through Ada services and currently exist. One line
is devoted to each task. The active task is marked with an
asterisk (*). In this example, it is also the active task (the
task that is in the RUN state).
2.DBG> SHOW TASK %ACTIVE_TASK,3,MONITOR
This command selects the active task, 3, and task MONITOR for
display.
3.DBG> SHOW TASK/PRIORITY=6
This command selects all tasks with priority 6 for display.
4.DBG> SHOW TASK/STATE=(RUN,SUSP)
This command selects all tasks that are either running or
suspended for display.
5.DBG> SHOW TASK/STATE=SUSP/NOHOLD
This command selects all tasks that are both suspended and not
on hold for display.
6.DBG> SHOW TASK/STATE=(RUN,SUSP)/PRIO=7 %VISIBLE_TASK, 3
This command selects for display those tasks among the visible
task and %TASK 3 that are in either the RUNNING or SUSPENDED
state and have priority 7.
3 TRACE
Displays information about tracepoints.
Format
SHOW TRACE
4 Qualifiers
/PREDEFINED
Displays information about predefined tracepoints.
/USER
Displays information about user-defined tracepoints.
4 Description
The SHOW TRACE command displays information about tracepoints
that are currently set, including any options such as WHEN or DO
clauses, /AFTER counts, and so on, and whether the tracepoints
are deactivated.
By default, SHOW TRACE displays information about both user-
defined and predefined tracepoints (if any). This is equivalent
to entering the SHOW TRACE/USER/PREDEFINED command. User-defined
tracepoints are set with the SET TRACE command. Predefined
tracepoints are set automatically when you start the debugger,
and they depend on the type of program you are debugging.
If you established a tracepoint using SET TRACE/AFTER:n, the SHOW
TRACE command displays the current value of the decimal integer
n, that is, the originally specified integer value minus 1 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 0, at which time the debugger takes trace
action.)
On Alpha systems, the SHOW TRACE command does not display
individual instructions when the trace is on a particular class
of instruction (as with SET TRACE/CALL or SET TRACE/RETURN).
Related commands:
(ACTIVATE, DEACTIVATE, SET, CANCEL) TRACE
4 Examples
1.DBG> SHOW TRACE
tracepoint at routine CALC\MULT
tracepoint on calls:
RET RSB BSBB JSB BSBW CALLG CALLS
DBG>
In this VAX example, the SHOW TRACE command 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.
2.all> SHOW TRACE/PREDEFINED
predefined tracepoint on program activation
DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_ AT H1 SOURCE
(EXAM/SOURCE .%SOURCE_SCOPE\%PC);
SET DISP/DYN/REM/SIZE:64/PROC INST_ AT H1 INST
(EXAM/INSTRUCTION .0\%PC))
predefined tracepoint on program termination
all>
This command 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. 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 does an image
exit.
3 TYPE
Identifies the current type for program locations that do not
have a compiler-generated type or, if you specify /OVERRIDE, the
current override type.
Format
SHOW TYPE
4 Qualifiers
/OVERRIDE
Identifies the current override type.
4 Description
The current type for program locations that do not have a
compiler-generated type is the type last established by the SET
TYPE command. If you did not enter a SET TYPE command, the type
for those locations is longword integer.
The current override type for all program locations is the
override type last established by the SET TYPE/OVERRIDE command.
If you did not enter a SET TYPE/OVERRIDE command, the override
type is "none".
Related commands:
CANCEL TYPE/OVERRIDE
DEPOSIT
EXAMINE
(SET,SHOW,CANCEL) MODE
(SET,SHOW,CANCEL) RADIX
SET TYPE
4 Examples
1.DBG> SET TYPE QUADWORD
DBG> SHOW TYPE
type: quadword integer
DBG>
In this example, you set the type to quadword for locations
that do not have a compiler-generated type. The SHOW TYPE
command displays the current default type for those locations
as quadword integer. This means that the debugger interprets
and displays entities at those locations as quadword integers
unless you specify otherwise (for example with a type qualifier
on the EXAMINE command).
2.DBG> SHOW TYPE/OVERRIDE
type/override: none
DBG>
This command indicates that no override type has been defined.
3 VECTOR_MODE
Identifies the current vector mode (synchronized or
nonsynchronized).
Applies to VAX vectorized programs.
Format
SHOW VECTOR_MODE
4 Description
The current vector mode is the mode established with the SET
VECTOR_MODE command. If you did not enter a SET VECTOR_MODE
command, the default vector mode is NONSYNCHRONIZED.
Related commands:
SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
SYNCHRONIZE VECTOR_MODE (VAX only)
4 Example
DBG> SHOW VECTOR_MODE
Vector mode is nonsynchronized
DBG> SET VECTOR_MODE SYNCHRONIZED
DBG> SHOW VECTOR_MODE
Vector mode is synchronized
DBG>
The SHOW VECTOR_MODE command indicates the effect of the SET
VECTOR_MODE command.
3 WATCH
Displays information about watchpoints.
Format
SHOW WATCH
4 Description
The SHOW WATCH command displays information about watchpoints
that are currently set, including any options such as WHEN or DO
clauses, /AFTER counts, and so on, and whether the watchpoints
are deactivated.
If you established a watchpoint using SET WATCH/AFTER:n, the SHOW
WATCH command displays the current value of the decimal integer
n, that is, the originally specified integer value minus 1 for
each time the watchpoint location was reached. (The debugger
decrements n each time the watchpoint location is reached until
the value of n is 0, at which time the debugger takes watch
action.)
Related commands:
(ACTIVATE,CANCEL,DEACTIVATE,SET) WATCH
4 Example
DBG> SHOW WATCH
watchpoint of MAIN\X
watchpoint of SUB2\TABLE+20
DBG>
This command displays two watchpoints: one at the variable
X (defined in module MAIN), and the other at the location
SUB2\TABLE+20 (20 bytes beyond the address denoted by the
address expression TABLE).
3 WINDOW
Identifies the name and screen position of predefined and
user-defined screen-mode windows.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SHOW WINDOW [window-name[, . . . ]]
4 Parameters
windowname
Specifies the name of a screen window definition. If you do not
specify a name, or if you specify the asterisk (*) wildcard
character by itself, all window definitions are listed. You can
use the wildcard within a window name. Do not specify a window
definition name with the /ALL qualifier.
4 Qualifiers
/ALL
Lists all window definitions.
4 Description
Related commands:
(SHOW,CANCEL) DISPLAY
(SET,SHOW) TERMINAL
(SET,CANCEL) WINDOW
SHOW SELECT
4 Example
DBG> SHOW WINDOW LH*,RH*
window LH1 at (1,11,1,40)
window LH12 at (1,23,1,40)
window LH2 at (13,11,1,40)
window RH1 at (1,11,42,39)
window RH12 at (1,23,42,39)
window RH2 at (13,11,42,39)
DBG>
This command displays the name and screen position of all
screen window definitions whose names start with LH or RH.
2 SPAWN
Creates a subprocess, enabling you to execute DCL commands
without terminating a debugging session or losing your debugging
context.
NOTE
This command is not available in the Compaq DECwindows Motif
for OpenVMS user interface to the debugger.
Format
SPAWN [DCL-command]
3 Parameters
DCL-command
Specifies a DCL command which is then executed in a subprocess.
Control is returned to the debugging session when the DCL command
terminates.
If you do not specify a DCL command, a subprocess is created
and you can then enter DCL commands. Either logging out of the
spawned process or attaching to the parent process (with the DCL
command ATTACH) returns you to your debugging session.
If the DCL command contains a semicolon, you must enclose the
command in quotation marks ("). Otherwise the semicolon is
interpreted as a debugger command separator. To include a
quotation mark in the string, enter two consecutive quotation
marks ("").
3 Qualifiers
/INPUT
/INPUT=file-spec
Specifies an input DCL command procedure containing one or more
DCL commands to be executed by the spawned subprocess. The
default file type is .COM. If you specify a DCL command string
with the SPAWN command and an input file with /INPUT, the command
string is processed before the input file. After processing
of the input file is complete, the subprocess is terminated.
Do not use the asterisk (*) wildcard character in the file
specification.
/OUTPUT
/OUTPUT=file-spec
Writes the output from the SPAWN operation to the specified
file. The default file type is .LOG. Do not use the asterisk
(*) wildcard character in the file specification.
/WAIT
/WAIT (default)
/NOWAIT
Controls whether the debugging session (the parent process) is
suspended while the subprocess is running. The /WAIT qualifier
(default) suspends the debugging session until the subprocess
is terminated. You cannot enter debugger commands until control
returns to the parent process.
The /NOWAIT qualifier executes the subprocess in parallel with
the debugging session. You can enter debugger commands while the
subprocess is running. If you use /NOWAIT, you should specify
a DCL command with the SPAWN command; the DCL command is then
executed in the subprocess. A message indicates when the spawned
subprocess completes.
The kept debugger (that is, the debugger invoked with the DCL
command DEBUG/KEEP) shares I/O channels with the parent process
when it is run by a SPAWN/NOWAIT command. Therefore, in the
Compaq DECwindows Motif for OpenVMS user interface, you must
press the Return key twice on the DECterm from which the debugger
was run after the debugger version number has appeared in the
command view.
Optionally, you can execute the kept debugger in the following
manner:
$ DEFINE DBG$INPUT NL:
$ SPAWN/NOWAIT RUN DEBUG/KEEP
3 Description
The SPAWN command acts exactly like the DCL command SPAWN. You
can edit files, compile programs, read mail, and so on without
ending your debugging session or losing your current debugging
context.
In addition, you can spawn a DCL command SPAWN. DCL processes the
second SPAWN command, including any qualifier specified with that
command.
Related command:
ATTACH
3 Examples
1.DBG> SPAWN
$
This example shows that the SPAWN command, without a parameter,
creates a subprocess at DCL level. You can now enter DCL
commands. Log out to return to the debugger prompt.
2.DBG> SPAWN/NOWAIT/INPUT=READ_NOTES/OUTPUT=0428NOTES
This command creates a subprocess that is executed in parallel
with the debugging session. This subprocess executes the DCL
command procedure READ_NOTES.COM. The output from the spawned
operation is written to the file 0428NOTES.LOG.
3.DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM
This command creates a subprocess that is executed in parallel
with the debugging session. This subprocess creates another
subprocess to execute the DCL command procedure MYCOM.COM. The
output from that operation is written to the file MYCOM.LOG.
2 STEP
Executes the program up to the next line, instruction, or other
specified location.
Format
STEP [integer]
3 Parameters
integer
A decimal integer that specifies the number of step units
(lines, instructions, and so on) to be executed. If you omit
the parameter, the debugger executes one step unit.
3 Qualifiers
/BRANCH
Executes the program to the next branch instruction. STEP/BRANCH
has the same effect as SET BREAK/TEMPORARY/BRANCH;GO.
/CALL
Executes the program to the next call or return instruction.
STEP/CALL has the same effect as SET BREAK/TEMPORARY/CALL;GO.
/EXCEPTION
Executes the program to the next exception, if
any. STEP/EXCEPTION has the same effect as SET
BREAK/TEMPORARY/EXCEPTION;GO. If no exception occurs,
STEP/EXCEPTION has the same effect as GO.
/INSTRUCTION
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ])
When you do not specify an opcode, executes the program to the
next instruction. STEP/INSTRUCTION has the same effect as SET
BREAK/TEMPORARY/INSTRUCTION;GO.
On VAX processors, you can specify one or more opcodes; the
debugger executes the program to the next instruction whose
opcode is in the list. The following commands are equivalent:
DBG> STEP/INSTRUCTION=(opcode[, . . . ])
DBG> SET BREAK/TEMPORARY/INSTRUCTION=(opcode[, . . . ]);GO
On VAX processors, you can specify vector instructions; do not
include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_
INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic.
/INTO
If execution is currently suspended at a routine call, STEP/INTO
executes the program up to the beginning of that routine (steps
into that routine). Otherwise, STEP/INTO has the same effect as
STEP without a qualifier. The /INTO qualifier is the opposite of
/OVER (the default behavior).
NOTE
On Alpha processors, when execution is stopped at an
exception break, STEP/INTO does not transfer control to a
user exception handler. Stop execution within the handler by
setting a breakpoint in the handler.
The STEP/INTO behavior can be changed by also using the /[NO]JSB,
/[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB
/JSB
/NOJSB
(VAX only) Qualifies a previous SET STEP INTO command or a
current STEP/INTO command.
If execution is currently suspended at a routine call and the
routine is called by a JSB instruction, STEP/INTO/NOJSB has the
same effect as STEP/OVER. Otherwise, STEP/INTO/NOJSB has the same
effect as STEP/INTO.
Use STEP/INTO/JSB to override a previous SET STEP NOJSB command.
STEP/INTO/JSB enables STEP/INTO to step into routines called
by a JSB instruction, as well as into routines called by a CALL
instruction.
The /JSB qualifier is the default for all languages except
DIBOL. The /NOJSB qualifier is the default for DIBOL. In DIBOL,
application-declared routines are called by the CALL instruction
and DIBOL Run-Time Library routines are called by the JSB
instruction.
/LINE
Executes the program to the next line of source code. However,
the debugger skips over any source lines that do not result
in executable code when compiled (for example, comment lines).
STEP/LINE has the same effect as SET BREAK/TEMPORARY/LINE;GO.
This is the default behavior for all languages.
/OVER
If execution is currently suspended at a routine call, STEP/OVER
executes the routine up to and including the routine's return
instruction (steps over that routine). The /OVER qualifier is the
default behavior and is the opposite of /INTO.
NOTE
On Alpha processors, when execution is suspended at a source
line that contains a loop with a routine call, STEP/OVER
steps into the called routine. To step to the next program
statement, set a temporary breakpoint at the statement and
enter GO.
/RETURN
Executes the routine in which execution is currently suspended up
to its return instruction (that is, up to the point just prior to
transferring control back to the calling routine). This enables
you to inspect the local environment (for example, obtain the
values of local variables) before the return instruction deletes
the routine's call frame from the call stack. STEP/RETURN has the
same effect as SET BREAK/TEMPORARY/RETURN;GO.
STEP/RETURN n executes the program up n levels of the call stack.
/SEMANTIC_EVENT
(Alpha only) Executes the program to the next semantic event.
STEP/SEMANTIC_EVENT simplifies debugging optimized code. (See the
Description section.)
/SHARE
/SHARE (default)
/NOSHARE
Qualifies a previous SET STEP INTO command or a current STEP/INTO
command.
If execution is currently suspended at a call to a shareable
image routine, STEP/INTO/NOSHARE has the same effect as
STEP/OVER. Otherwise, STEP/INTO/NOSHARE has the same effect as
STEP/INTO.
Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE
command. STEP/INTO/SHARE enables STEP/INTO to step into shareable
image routines, as well as into other kinds of routines.
/SILENT
/SILENT
/NOSILENT (default)
Controls whether the "stepped to . . . " message and the source
line for the current location are displayed after the STEP has
completed. The /NOSILENT qualifier specifies that the message is
displayed. The /SILENT qualifier specifies that the message and
source line are not displayed. The /SILENT qualifier overrides
/SOURCE.
/SOURCE
/SOURCE (default)
/NOSOURCE
Controls whether the source line for the current location is
displayed after the STEP has completed. The /SOURCE qualifier
specifies that the source line is displayed. The /NOSOURCE
qualifier specifies that the source line is not displayed.
The /SILENT qualifier overrides /SOURCE. See also the SET STEP
[NO]SOURCE command.
/SYSTEM
/SYSTEM (default)
/NOSYSTEM
Qualifies a previous SET STEP INTO command or a current STEP/INTO
command.
If execution is currently suspended at a call to a system
routine (in P1 space), STEP/INTO/NOSYSTEM has the same effect
as STEP/OVER. Otherwise, STEP/INTO/NOSYSTEM has the same effect
as STEP/INTO.
Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM
command. STEP/INTO/SYSTEM enables STEP/INTO to step into system
routines, as well as into other kinds of routines.
/VECTOR_INSTRUCTION
(VAX only) Executes the program to the next vector
instruction. STEP/VECTOR_INSTRUCTION has the same effect as SET
BREAK/TEMPORARY/VECTOR_INSTRUCTION;GO.
3 Description
The STEP command is one of the four debugger commands that can be
used to execute your program (the others are CALL, EXIT, and GO).
The behavior of the STEP command depends on the following
factors:
o The default STEP mode previously established with a SET STEP
command, if any
o The qualifier specified with the STEP command, if any
o The number of step units specified as the parameter to the
STEP command, if any
If no SET STEP command was previously entered, the debugger
takes the following default actions when you enter a STEP command
without specifying a qualifier or parameter:
1. Executes a line of source code (the default is STEP/LINE).
2. Reports that execution has completed by issuing a "stepped
to . . . " message (the default is STEP/NOSILENT).
3. Displays the line of source code at which execution is
suspended (the default is STEP/SOURCE).
4. Issues the prompt.
The following qualifiers affect the location to which you step:
/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INSTRUCTION=(opcode[, . . . ]) (VAX only)
/LINE
/RETURN
/SEMANTIC_EVENT (Alpha only)
/VECTOR_INSTRUCTION (VAX only)
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 (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM
If you plan to enter several STEP commands with the same
qualifiers, you can first use the SET STEP command to establish
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. Use the SHOW
STEP command to identify the current STEP defaults.
3 Description,_Continued...
If an exception breakpoint is triggered (resulting from a SET
BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is
suspended before any application-declared condition handler is
started. If you then resume execution with the STEP command, the
debugger resignals the exception and the program executes to the
beginning of (steps into) the condition handler, if any.
On Alpha systems, if your program has been compiled with the
/OPTIMIZE qualifier, semantic stepping mode is available, with
the STEP/SEMANTIC_EVENT and SET STEP SEMANTIC_EVENT commands.
When you are debugging optimized code, the apparent source
program location tends to bounce back and forth, with the same
line appearing repeatedly. In semantic stepping mode, the program
executes to the next point in the program where a significant
effect (semantic event) occurs.
A semantic event is one of the following:
o Data event - An assignment to a user variable
o Control event - A control flow decision, with a conditional or
unconditional transfer of control, other than a call
o Call event - A call (to a routine that is not stepped over) or
a return from a call
Not every assignment, transfer of control, or call is a semantic
event. The major exceptions are as follows:
o When two instructions are required to assign to a complex or
X_floating value, only the first instruction is treated as a
semantic event.
o When there are multiple branches that are part of a single
higher-level construct, such as a decision tree of branches
that implement a case or select construct, then only the first
is treated as a semantic event.
o When a call is made to a routine that is a compiler-specific
helper routine, such as a call to OTS$MOVE, which handles
certain kinds of string or storage copy operations, the call
is not considered a semantic event. Control will not stop at
the call.
To step into such a routine, you must do either of the
following:
- Set a breakpoint at the routine entry point.
- Use a series of STEP/INSTRUCTION commands to reach the call
of interest and then use STEP/INSTRUCTION/INTO to enter the
called routine.
o When there is more than one potential semantic event in a
row with the same line number, only the first is treated as a
semantic event.
The STEP/SEMANTIC_EVENT command causes a breakpoint to be set at
the next semantic event. Execution proceeds to that next event.
Parts of any number of different lines and statements may be
executed along the way, without interfering with progress. When
the semantic event is reached (that is, when the instruction
associated with that event is reached but not yet executed),
execution is suspended (similar to reaching the next line when
STEP/LINE is used).
If you are debugging a multiprocess program, the STEP command is
executed in the context of the current process set. In addition,
when debugging a multiprocess program, the way in which execution
continues in your process depends on whether you entered a SET
MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By
default (SET MODE NOINTERRUPT), when one process stops, the
debugger takes no action with regard to the other processes.
Also by default (SET MODE WAIT), the debugger waits until all
process in the current process set have stopped before prompting
for a new command.
On VAX systems, the STEP/OVER command results in stepping
into, not over, Fortran Run-Time Library routines. For more
information, see the OpenVMS Debugger Manual.
Related commands:
CALL
EXIT
GO
SET BREAK/EXCEPTION
SET MODE [NO]INTERRUPT
SET PROCESS
(SET,SHOW) STEP
3 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')
DBG>
In this example, the SHOW STEP command identifies the default
qualifiers currently in effect for the STEP command. In this
case, the STEP command, 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);
DBG>
This command 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;
DBG>
In this example, execution is paused at a call to routine
SWAP, and the STEP/INTO command executes the program up to
the beginning of the called routine. The STEP command executes
the next line of source code. The STEP/RETURN command executes
the rest of routine SWAP up to its RET instruction (that is,
up to the point just prior to transferring control back to the
calling routine).
2 STOP
Interrupts all specified processes that are running.
Format
STOP [process-spec[, . . . ]
3 Parameters
process-spec
This parameter specifies the process set to be stopped. The
default is the current process set. Use any of the following
forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name" spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
You can also use the asterisk (*) wildcard character to specify
all processes.
3 Description
The STOP command interrupts the specified processes. You can use
the STOP command in nowait mode to stop processes that are still
running.
3 Examples
1.all> SHOW PROCESS
Number Name State Current PC
1 DBGK$$2727282C break SERVER\main\%LINE 18834
2 USER1_2 running not available
* 3 USER1_3 running not available
all> CLIENTS> STOP
all> show process
Number Name State Current PC
1 DBGK$$2727282C break SERVER\main\%LINE 18834
2 USER1_2 interrupted 0FFFFFFFF800F7A20
* 3 USER1_3 interrupted 0FFFFFFFF800F7A20
all>
This command sequence first shows all processes, then stops the
processes in process set clients. The last SHOW PROCESS command
shows the new process states.
2 SYMBOLIZE
Converts a memory address to a symbolic representation, if
possible.
Format
SYMBOLIZE address-expression[, . . . ]
3 Parameters
address-expression
Specifies an address expression to be symbolized. Do not use the
asterisk (*) wildcard character.
3 Description
If the address is a static address, it is symbolized as the
nearest preceding symbol name, plus an offset. If the address
is also a code address and a line number can be found that covers
the address, the line number is included in the symbolization.
If the address is a register address, the debugger displays all
symbols in all set modules that are bound to that register. The
full path name of each such symbol is displayed. The register
name itself ("%R5", for example) is also displayed.
If the address is a call stack location in the call frame of a
routine in a set module, the debugger searches for all symbols
in that routine whose addresses are relative to the frame pointer
(FP) or the stack pointer (SP). The closest preceding symbol name
plus an offset is displayed as the symbolization of the address.
A symbol whose address specification is too complex is ignored.
On Alpha processors, the commands
SYMBOLIZE procedure-code-address and
SYMBOLIZE procedure-descriptor-address both display the path
name of the routine, entry point, or Ada package specified by
these addresses.
If the debugger cannot symbolize the address, a message is
displayed.
Related commands:
EVALUATE/ADDRESS
SET MODE [NO]LINE
SET MODE [NO]SYMBOLIC
(SET,SHOW,CANCEL) MODULE
SHOW SYMBOL
3 Examples
1.DBG> SYMBOLIZE %R5
address PROG\%R5:
PROG\X
DBG>
This example shows that the local variable X in routine PROG is
located in register R5.
2.DBG> SYMBOLIZE %HEX 27C9E3
address 0027C9E3:
MOD5\X
DBG>
This command directs the debugger to treat the integer literal
27C9E3 as a hexadecimal value and convert that address to a
symbolic representation, if possible. The address converts to
the symbol X in module MOD5.
2 SYNCHRONIZE
3 VECTOR_MODE
Forces immediate synchronization between the scalar and vector
processors.
Applies to VAX vectorized programs.
Format
SYNCHRONIZE VECTOR_MODE
4 Description
The SYNCHRONIZE VECTOR_MODE command forces immediate
synchronization between the scalar and vector processors by
issuing SYNC and MSYNC instructions. The effect is as follows:
o Any exception that was caused by a vector instruction and
was still pending delivery is immediately delivered. 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 at which execution is suspended.
By default, the debugger does not force synchronization between
the scalar and vector processors during program execution (SET
VECTOR_MODE NOSYNCHRONIZED). To force such synchronization, use
the SET VECTOR_MODE SYNCHRONIZED command.
Related commands:
SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
SHOW VECTOR_MODE (VAX only)
4 Examples
1.DBG> SYNCHRONIZE VECTOR_MODE
%DEBUG-I-SYNCREPCOM, Synchronize reporting complete
This command 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)
DBG>
The comments that follow refer to the callouts in the previous
example:
1 This STEP command suspends program execution on line 99,
just before a VVDIVD instruction is executed. Assume that,
in this example, 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.
2 TYPE
Displays lines of source code.
Format
TYPE [[module-name\]line-number[:line-number]
[,[module-name\]line-number[:line-number][, . . . ]]]
3 Parameters
module-name
Specifies the module that contains the source lines to be
displayed. If you specify a module name along with the line
numbers, use standard pathname notation: insert a backslash (\)
between the module name and the line numbers.
If you do not specify a module name, the debugger uses the
current scope (as established by a previous SET SCOPE command,
or the PC scope if you did not enter a SET SCOPE command) to find
source lines for display. If you specify a scope search list with
the SET SCOPE command, the debugger searches for source lines
only in the module associated with the first named scope.
line-number
Specifies a compiler-generated line number (a number used to
label a source language statement or statements).
If you specify a single line number, the debugger displays the
source code corresponding to that line number.
If you specify a list of line numbers, separating each with a
comma, the debugger displays the source code corresponding to
each of the line numbers.
If you specify a range of line numbers, separating the beginning
and ending line numbers in the range with a colon (:), the
debugger displays the source code corresponding to that range
of line numbers.
You can display all the source lines of a module by specifying
a range of line numbers starting from 1 and ending at a number
equal to or greater than the largest line number in the module.
After displaying a single line of source code, you can display
the next line of that module by entering a TYPE command without
a line number (that is, by entering TYPE and then pressing the
Return key). You can then display the next line and successive
lines by repeating this sequence, in effect, reading through your
source program one line at a time.
3 Description
The TYPE command displays the lines of source code that
correspond to the specified line numbers. The line numbers used
by the debugger to identify lines of source code are generated by
the compiler. They appear in a compiler-generated listing and in
a screen-mode source display.
If you specify a module name with the TYPE command, the module
must be set. Use the SHOW MODULE command to determine whether
a particular module is set. Then use the SET MODULE command, if
necessary.
In screen mode, the output of a TYPE command is directed at the
current source display, not at an output or DO display. The
source display shows the lines specified and any surrounding
lines that fit in the display window.
Related commands:
EXAMINE/SOURCE
SET (BREAK,TRACE,WATCH)/[NO]SOURCE
SET MODE [NO]SCREEN
(SET,SHOW,CANCEL) SCOPE
SET STEP [NO]SOURCE
STEP/[NO]SOURCE
3 Examples
1.DBG> TYPE 160
module COBOLTEST
160: START-IT-PARA.
DBG> TYPE
module COBOLTEST
161: MOVE SC1 TO ES0.
DBG>
In this example, the first TYPE command displays line 160,
using the current scope to locate the module containing
that line number. The second TYPE command, entered without
specifying a line number, displays the next line in that
module.
2.DBG> TYPE 160:163
module COBOLTEST
160: START-IT-PARA.
161: MOVE SC1 TO ES0.
162: DISPLAY ES0.
163: MOVE SC1 TO ES1.
DBG>
This command displays lines 160 to 163, using the current scope
to locate the module.
3.DBG> TYPE SCREEN_IO\7,22:24
This command displays line 7 and lines 22 to 24 in module
SCREEN_IO.
2 WAIT
Causes the debugger to wait until the target processes have
stopped before prompting for the next command.
Format
WAIT
3 Description
When debugging multiprocess programs, the WAIT command causes
the debugger to complete executing all process specified by the
previous command before displaying a prompt to accept and execute
another command.
Related commands:
STOP
SET MODE [NO]INTERRUPT
SET MODE [NO]WAIT
3 Example
all> 2,3> GO;WAIT
processes 2,3
break at CLIENT\main\%LINE 18814
18814: status = sys$qiow (EFN$C_ENF, mbxchan,
IO$_READVBLKIO$M_WRITERCHECK, myiosb)
process 1
break at SERVER\main\%LINE 18834
18834: if ((myiosb.iosb$w_status ==
SS$_NOREADER) && (pos_status != -1))
all>
This command sequence executes the target processes (in this
case, 2 and 3), and the debugger waits until both processes
reach breakpoints before prompting for the next command.
2 WHILE
Executes a sequence of commands while the language expression
(Boolean expression) you have specified evaluates as true.
Format
WHILE Boolean-expression DO (command[; . . . ])
3 Parameters
Boolean-expression
Specifies a language expression that evaluates as a Boolean value
(true or false) in the currently set language.
command
Specifies a debugger command. If you specify more than one
command, separate the commands with semicolons (;). At each
execution, the debugger checks the syntax of any expressions in
the commands and then evaluates them.
3 Description
The WHILE command evaluates a Boolean expression in the current
language. If the value is true, the command list in the DO clause
is executed. The command then repeats the sequence, reevaluating
the Boolean expression and executing the command list until the
expression is evaluated as false.
If the Boolean expression is false, the WHILE command terminates.
Related commands:
EXITLOOP
FOR
REPEAT
3 Example
DBG> WHILE (X .EQ. 0) DO (STEP/SILENT)
This command directs the debugger to keep stepping through the
program until X no longer equals 0 (Fortran example).