Document revision date: 19 July 1999

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:

• %NAME---Used to construct identifiers.
• %PARCNT---Used in command procedures to count parameters passed.
• %DECWINDOWS---Used in debugger command procedures or initialization files to determine whether the debugger's command interface or DECwindows Motif interface was displayed.
• %BIN, %DEC, %HEX, %OCT---Used to control the input radix.
• Period (.), Return key, circumflex (^), backslash (\), %CURLOC, %NEXTLOC, %PREVLOC, %CURVAL---Used to specify consecutive program locations and the current value of an entity.
• Plus sign (+), minus sign (-), multiplication sign (*), division sign (/), at sign (@), period (.), bit field operator (<p,s,e>), %LABEL, %LINE, backslash (\) -Used as operators in address expressions.
• %ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_NUMBER, %EXC_SEVERITY---Used to obtain information about exceptions.
• %CURRENT_SCOPE_ENTRY, %NEXT_SCOPE_ENTRY, %PREVIOUS_SCOPE_ENTRY---Used to specify the current, next, and previous scope relative to the call stack.
• On VAX processors, %R0 to %R11, %AP, %FP, %SP, %PC, %PSL---Used to specify the VAX general registers.
• %V0 to %V15, %VCR, %VLR, and %VMR---Used to specify the VAX vector registers and vector control registers.
• On Alpha processors, %R0 to %R28, %FP, %SP, %R31, %PC, %PS---Used to specify the Alpha general registers.
• %F0 to %F30, %F31---Used to specify the Alpha floating-point registers.
• %ADDR, %DESCR, %REF, %VAL---Used to specify the argument-passing mechanism for the CALL command. See the CALL command description in the command dictionary.
• %PROCESS_NAME, %PROCESS_PID, %PROCESS_NUMBER, %NEXT_PROCESS, %PREVIOUS_PROCESS, %VISIBLE_PROCESS---Used to specify processes in multiprocess programs. See Section 15.3.2.
• %ACTIVE_TASK, %CALLER_TASK, %NEXT_TASK, %PREVIOUS_TASK, %TASK, %VISIBLE_TASK---Used to specify tasks or threads in tasking or multithread programs. See Section 17.3.4.
• %PAGE, %WIDTH---Used to specify the current screen height and width. See Section 7.11.1.
• %SOURCE_SCOPE, %INST_SCOPE---Used to specify the scope for source and instruction display in screen mode. See Section 7.4.1 and Section 7.4.4, respectively.
• %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE---Used in screen mode to specify displays in the display list. See Section 7.11.2.

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.

Table B-1 Debugger Symbols for VAX Registers (VAX Only)

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.

Table B-2 Debugger Symbols for Alpha Registers (Alpha Only)

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:

• You cannot deposit a value into registers R31 or F31. They are permanently assigned the value 0.
• There are no vector registers.
• The debugger does not provide a screen-mode register display.

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'

B.3.3 Counting Parameters Passed to Command Procedures

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)

B.3.4 Determining the Debugger Interface (Command or DECwindows Motif)

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))

B.3.5 Controlling the Input Radix

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

B.3.6 Specifying Program Locations and the Current Value of an Entity

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.

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 (@) Period (.)	Unary operators. In an address expression, the 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 <p,s,e>	Unary operator. You can apply bit field 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 sign (*)	Binary operator. Multiplies the preceding operand by the succeeding operand.
Division sign (/)	Binary operator. Divides the preceding operand by the succeeding operand.

The following examples show the use of built-in symbols and operators in address expressions.

%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

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

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

Contents-of Operator

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).

	privacy and legal statement
4538PRO_065.HTML