Updated: 11 December 1998 |
OpenVMS Debugger Manual
Previous | Contents | Index |
This appendix identifies all the debugger built-in symbols and logical
names.
B.1 SS$_DEBUG Condition
SS$_DEBUG (defined in SYS$LIBRARY:STARLET.OLB) is a condition you can signal from your program to start the debugger. Signaling SS$_DEBUG from your program is equivalent to pressing Ctrl/Y followed by the DCL command DEBUG at that point.
You can pass commands to the debugger at the time you signal it with
SS$_DEBUG. The commands you want the debugger to execute should be
specified as you would enter them at the DBG> prompt. Multiple
commands should be separated by semicolons. The commands should be
passed by reference as an ASCIC string. See your language documentation
for details on constructing an ASCIC string.
For example, to start the debugger and enter a SHOW CALLS command at a given point in your program, you can insert the following code in your program (BLISS example):
LIB$SIGNAL(SS$_DEBUG, 1, UPLIT BYTE(%ASCIC 'SHOW CALLS')); |
You can obtain the definition of SS$_DEBUG at compile time from the
appropriate STARLET or SYSDEF file for your language (for example,
STARLET.L32 for BLISS or FORSYSDEF.TLB for Fortran). You can also
obtain the definition of SS$_DEBUG at link time in
SYS$LIBRARY:STARLET.OLB (this method is less desirable).
B.2 Logical Names
The following table identifies debugger-specific logical names:
Logical Name |
Description |
---|---|
DBG$DECW$DISPLAY |
Applies only to workstations running DECwindows Motif. Specifies the
debugger interface (DECwindows Motif or command) or the display device.
Default: DBG$DECW$DISPLAY is either undefined or has the same
definition as the applicationwide logical name DECW$DISPLAY.
See Section 9.7.3 for information about using DBG$DECW$DISPLAY to override the debugger's default interface in the DECwindows Motif environment. |
DBG$IMAGE_DSF_PATH | (Alpha only) Specifies the directory that contains the .DSF (debug symbol table) files of the image being debugged. The file name of each .DSF file must be the same at the file name of the image being debugged. See Section 5.1.5 for more information about creating .DSF files. |
DBG$INIT | Specifies your debugger initialization file. Default: no debugger initialization file. DBG$INIT accepts a full or partial file specification as well as a search list. See Section 13.2 for information about debugger initialization files. |
DBG$INPUT |
Specifies the debugger input device. Default: SYS$INPUT. See
Section 14.2 for information about using DBG$INPUT and DBG$OUTPUT to
debug screen-oriented programs at two terminals.
DBG$INPUT is ignored in the DECwindows Motif interface (see DBG$DECW$DISPLAY). You can use DBG$INPUT if you are displaying the debugger's command interface in a DECterm window. |
DBG$OUTPUT |
Specifies the debugger output device. Default: SYS$OUTPUT. See
Section 14.2 for information about using DBG$INPUT and DBG$OUTPUT to
debug screen-oriented programs at two terminals.
DBG$OUTPUT is ignored in the DECwindows Motif interface (see DBG$DECW$DISPLAY). You can use DBG$OUTPUT if you are displaying the debugger's command interface in a DECterm window. |
DBG$PROCESS | Specifies the debugging configuration (default or multiprocess). Default: DBG$PROCESS is undefined. See Section 15.3.1 for information about using DBG$PROCESS to specify the debugging configuration. |
SSI$AUTO_ACTIVATE |
(Alpha only) Specifies whether system service interception (SSI) is
enabled. If you are having trouble with your watchpoints, disable SSI
with the DCL command
$DEFINE SSI$AUTO_ACTIVATE OFF See SET WATCH for more information about the interaction between static watchpoints, ASTs, and system service interception. |
Use the DCL command DEFINE or ASSIGN to assign values to these logical names. For example, the following command specifies the location of the debugger initialization file:
$ DEFINE DBG$INIT DISK$:[JONES.COMFILES]DEBUGINIT.COM |
Note the following points about the logical name DBG$INPUT. If you plan to debug a program that takes its input from a file (for example, PROG_IN.DAT) and your debugger input from the terminal, establish the following definitions before starting the debugger:
$ DEFINE SYS$INPUT PROG_IN.DAT $ 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 tries to
get its input from the file PROG_IN.DAT.
B.3 Built-In Symbols
The debugger's built-in symbols provide options for specifying program entities and values.
Most of the debugger built-in symbols have a percent sign (%) prefix.
The following symbols are described in this appendix:
The debugger built-in symbol for a VAX or Alpha register is the register name preceded by the percent sign (%). When specifying a register symbol, you can omit the percent sign (%) prefix if your program has not declared a symbol with the same name. Table B-1 identifies the VAX register symbols.
Symbol | Description |
---|---|
VAX General Registers | |
%R0...%R11 | General-purpose registers (R0...R11) |
%AP (%R12) | Argument pointer (AP) |
%FP (%R13) | Frame pointer (FP) |
%SP (%R14) | Stack pointer (SP) |
%PC (%R15) | Program counter (PC) |
%PSL | Processor status longword (PSL) |
VAX Vector Registers and Vector Control Registers | |
%V0...%V15 | Vector registers V0...V15 |
%VCR | Vector count register |
%VLR | Vector length register |
%VMR | Vector mask register |
You can examine the contents of all the registers. You can deposit values into all the registers except for SP. Use caution when depositing values into FP.
See Section 4.4 and Section 4.4.1 for more information about the VAX general registers. See Chapter 16 for more information about the VAX vector registers.
Table B-2 identifies the Alpha register symbols.
Symbol | Description |
---|---|
Alpha Integer Registers | |
%R0...%R28 | Registers R0...R28 |
%FP (%R29) | Stack frame base register (FP) |
%SP (%R30) | Stack pointer (SP) |
%R31 | ReadAsZero/Sink (RZ) |
%PC | Program counter (PC) |
%PS | Processor status register (PS). The built-in symbols %PSL and %PSW are disabled for Alpha processors. |
Alpha Floating-Point Registers | |
%F0...%F30 | Registers F0...F30 |
%F31 | ReadAsZero/Sink |
On Alpha processors:
See Section 4.4 and Section 4.4.2 for more information about the
Alpha general registers.
B.3.2 Constructing Identifiers
The %NAME built-in symbol enables you to construct identifiers that are not ordinarily legal in the current language. The syntax is as follows:
%NAME 'character-string' |
In the following example, the variable with the name '12' is examined:
DBG> EXAMINE %NAME '12' |
In the following example, the compiler-generated label P.AAA is examined:
DBG> EXAMINE %NAME 'P.AAA' |
You can use the %PARCNT built-in symbol within a command procedure that accepts a variable number of actual parameters (%PARCNT is defined only within a debugger command procedure).
%PARCNT specifies the number of actual parameters passed to the current command procedure. In the following example, command procedure ABC.COM is invoked and three parameters are passed:
DBG> @ABC 111,222,333 |
Within ABC.COM, %PARCNT now has the value 3. %PARCNT is then used as a loop counter to obtain the value of each parameter passed to ABC.COM:
DBG> FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) |
The %DECWINDOWS built-in symbol enables you to determine whether the debugger's DECwindows Motif or command interface was displayed. When the DECwindows Motif interface is being used, the value of %DECWINDOWS is 1 (TRUE). When the command interface is being used, the value of %DECWINDOWS 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)) |
The built-in symbols %BIN, %DEC, %HEX, and %OCT can be used in address expressions and language expressions to specify that an integer literal that follows (or all integer literals in a parenthesized expression that follows) should be interpreted in binary, decimal, hexadecimal, or octal radix, respectively. Use these radix built-in symbols only with integer literals. For example:
DBG> EVALUATE/DEC %HEX 10 16 DBG> EVALUATE/DEC %HEX (10 + 10) 32 DBG> EVALUATE/DEC %BIN 10 2 DBG> EVALUATE/DEC %OCT (10 + 10) 16 DBG> EVALUATE/HEX %DEC 10 0A DBG> SET RADIX DECIMAL DBG> EVALUATE %HEX 20 + 33 ! Treat 20 as hexadecimal, 33 as decimal 65 ! Resulting value is decimal DBG> EVALUATE %HEX (20+33) ! Treat both 20 and 33 as hexadecimal 83 DBG> EVALUATE %HEX (20+ %OCT 10 +33) ! Treat 20 and 33 as 91 ! hexadecimal and 10 as octal DBG> SYMBOLIZE %HEX 27C9E3 ! Symbolize a hexadecimal address DBG> DEPOSIT/INST %HEX 5432 = 'MOVL ^O%DEC 222, R1' DBG> ! Treat address 5432 as hexadecimal, and operand 222 as decimal |
The following built-in symbols enable you to specify program locations and the current value of an entity:
Symbol | Description |
---|---|
%CURLOC
. (period) |
Current logical entity---the program location last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command. |
%NEXTLOC
Return key |
Logical successor of the current entity---the program location that logically follows the location last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command. Because the Return key is a command terminator, it can be used only where a command terminator is appropriate (for example, immediately after EXAMINE, but not immediately after DEPOSIT or EVALUATE/ADDRESS). |
%PREVLOC
^ (circumflex) |
Logical predecessor of current entity---the program location that logically precedes the location last referenced by an EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command. |
%CURVAL
\ (backslash) |
Value last displayed by an EVALUATE or EXAMINE command, or deposited by a DEPOSIT command. These two symbols are not affected by an EVALUATE/ADDRESS command. |
In the following example, the variable WIDTH is examined; the value 12 is then deposited into the current location (WIDTH); this is verified by examining the current location:
DBG> EXAMINE WIDTH MOD\WIDTH: 7 DBG> DEPOSIT . = 12 DBG> EXAMINE . MOD\WIDTH: 12 DBG> EXAMINE %CURLOC MOD\WIDTH: 12 DBG> |
In the next example, the next and previous locations in an array are examined:
DBG> EXAMINE PRIMES(4) MOD\PRIMES(4): 7 DBG> EXAMINE %NEXTLOC MOD\PRIMES(5): 11 DBG> EXAMINE [Return] ! Examine next location MOD\PRIMES(6): 13 DBG> EXAMINE %PREVLOC MOD\PRIMES(5): 11 DBG> EXAMINE ^ MOD\PRIMES(4): 7 DBG> |
Note that using the Return key to signify the logical successor does
not apply to all contexts. For example, you cannot press the Return key
after typing the command DEPOSIT to indicate the next location, but you
can always use the symbol %NEXTLOC for that purpose.
B.3.7 Using Symbols and Operators in Address Expressions
The following list describes the symbols and operators that you can use in address expressions. A unary operator has one operand. A binary operator has two operands.
The following examples show the use of built-in symbols and operators in address expressions.
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 |
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 |
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):
The debugger operators are listed in decreasing order of precedence as follows:
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 |
The following examples show the use of the contents-of operator. In the first 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, the value of the pointer variable PTR is 7FF00000 hexadecimal, the address of an entity that you want to examine. 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 following figure). 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).
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). |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4538PRO_065.HTML
|