HP OpenVMS Debugger Manual

Contents

Index

Appendix B
Built-In Symbols and Logical Names

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 HP DECwindows Motif for OpenVMS. Specifies the debugger interface (HP DECwindows Motif for OpenVMS 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.8.3 for information about using DBG$DECW$DISPLAY to override the debugger's default interface in the HP DECwindows Motif for OpenVMS environment.

DBG$IMAGE_DSF_PATH (Alpha and I64 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 as 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 HP DECwindows Motif for OpenVMS user 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 HP DECwindows Motif for OpenVMS user interface (see DBG$DECW$DISPLAY). You can use DBG$OUTPUT if you are displaying the debugger's command interface in a DECterm window.

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.

Logical Name	Description
DBG$DECW$DISPLAY	Applies only to workstations running HP DECwindows Motif for OpenVMS. Specifies the debugger interface (HP DECwindows Motif for OpenVMS 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.8.3 for information about using DBG$DECW$DISPLAY to override the debugger's default interface in the HP DECwindows Motif for OpenVMS environment.
DBG$IMAGE_DSF_PATH	(Alpha and I64 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 as 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 HP DECwindows Motif for OpenVMS user 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 HP DECwindows Motif for OpenVMS user interface (see DBG$DECW$DISPLAY). You can use DBG$OUTPUT if you are displaying the debugger's command interface in a DECterm window.
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 HP DECwindows Motif for OpenVMS user 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.
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.
On I64 processors,
- %R0 to %R127, %GP, %SP, %TP, %AP, %OUT0 to %OUT7 --- Used to specify the I64 general registers.
- %F0 to %F127 --- Used to specify the I64 floating-point registers.
- P0 to %P63, %PR --- Used to specify the I64 predicate registers.
- %B0 to %B7, %RP --- Used to specify the I64 branch registers.
- %AR0 to %AR7. %AR17 to %AR19, %AR32, %AR36, %AR40, %AR64 to %AR66, %KR0 to %KR7, %RSC, %BSP, %RNAT, %CCV, %UNAT, %FPSR, %PFS, %LC, %EC, %CSD, and %SSD --- Used to specify the I64 application registers.
- %CR0 to %CR2, %CR8, %CR16, %CR17, %CR19 to %CR25, %CR64, %CR66, %CR68 to %CR74, %CR80, %CR81, %DCR, %ITM, %IVA, %PTA, %PSR, %IPSR, %ISR, %IIP, %IFA, %ITIR, %IIPA, %IFS, %IIM, %IHA, %LID, %TPR, %IRR0 to %IRR3, %ITV, %PMV, %CMCV, and %IRR0 to %IRR3 --- Used to specify the I64 control registers.
- %SR0, %IH, %PREV_BSP, %PC, %IP, %RETURN_PC, %CFM, %NEXT_PFS, %PSP, %CHTCTX_ADDR, %OSSD, %HANDLER_FV, %LSDA, and %UM --- Used to specify the I64 special 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.16.1.
%ACTIVE_TASK, %CALLER_TASK, %NEXT_TASK, %PREVIOUS_TASK, %TASK, %VISIBLE_TASK---Used to specify tasks or threads in tasking or multithread programs. See Section 16.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.

B.3.1 Specifying Registers

The debugger built-in symbol for a VAX, Alpha, or I64 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 General Registers (VAX Only)
Symbol Description

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

**Table B-1 Debugger Symbols for VAX General Registers (VAX Only)**
Symbol	Description
%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)

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.

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

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

The debugger does not provide a screen-mode register display.

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.

See Section 4.4 and Section 4.4.2 for more information about the Alpha general registers.

Table B-3 identifies the I64 register symbols.

TABLE_ROW>(%BSP (%AR17)\ Backing Store Pointer )
Table B-3 Debugger Symbols for I64 Registers (I64 Only)
Symbol Description

I64 Application Registers

%KR0...%KR7 Kernel registers 0...7

%RSC (%AR16) Register Stack Configuration

%BSPSTORE (%AR18) Backing Store Pointer for Memory Stores

%RNAT (%AR19) RSE NaT Collection

%CCV ($AR32) Compare and Exchange Compare Value

%UNAT (%AR36) User NaT Collection

%FPSR (%AR40) Floating-point Status

%PFS (%AR64) Previous Function State

%LC (%AR65) Loop Count

%EC (%AR66) Epilog Count

%CSD Code Segment

%SSD Stack Segment

Control Registers

%DCR (%CR0) Default Control

%ITM (%CR1) Interval Timer Match (only visible for SCD)

%IVA (%CR2) Interruption Vector Address (only visible for SCD)

%PTA (%CR8) Page Table Address (only visible for SCD)

%PSR (%CR9, %ISPR) Interruption Processor Status

%ISR (%CR17) Interruption Status

%IIP (%CR19) Interruption Instruction Pointer

%IFA (%CR20) Interruption Faulting Address

%ITIR (%CR21) Interruption TLB Insertion

%IIPA (%CR22) Interruption Instruction Previous

%IFS (%CR23) Interruption Function State

%IIM (%CR24) Interruption Immediate

%IHA (%CR25) Interruption Hash Address

%LID (%CR64) Local Interrupt ID (only visible for SCD)

%TPR (%CR66) Task Priority (only visible for SCD)

%IRR0...%IRR3 (%CR68...%CR71) External Interrupt Request 0...3 (only visible for SCD)

%ITV (%CR72) Interval Timer (only visible for SCD)

%PMV (%CR73) Performance Monitoring (only visible for SCD)

%CMCV (%CR74) Corrected Machine Check Vector (only visible for SCD)

%IRR0 and %IRR1 (%CR80 and %CR81) Local Redirection 0:1 (only visible for SCD)

Special Registers

%IH (%SR0) Invocation Handle

%PREV_BSP Previous Backing Store Pointer

%PC (%IP) Program Counter (Instruction Pointer | slot number)

%RETURN_PC Return Program Counter

%CFM Current Frame Marker

%NEXT_PFS Next Prefious Frame State

%PSP Previous Stack Pointer

%CHFCTX_ADDR Condition Handling Facility Context Address

%OSSD Operating System Specific Data

%HANDLER_FV Handler Function Value

%LSDA Language Specific Data Area

%UM User Mask

Predicate Registers

%PR (%PRED) Predicate Collection Register---Collection of %P0...%P63

%P0...%P63 Predicate (single-bit)Registers 0...63

Branch Registers

%RP (%B0) Return Pointer

%B1...%B7 Branch Registers 1...7

General Integer Registers

%R0 General Integer Register 0

%GP (%R1) Global Data Pointer

%R2...%R11 General Integer Registers 2...11

%SP (%R12) Stack Pointer

%TP (%R13) Thread Pointer

%R14...%R24 General Integer Registers 14...24

%AP (%R25) Argument Information

%R26...%R127 General Integer Registers 26...127

Output Registers

%OUT0...%OUT7 Output Registers, runtime aliases (i.e., If the frame has allocated output registers, then %OUT0 maps to the first allocated output registers, for example, %R38, etc.)

General Registers

%GRNAT0 and %GRNAT1 General Register Not A Thing (NAT) collection registers 64 bits each, for example, %GRNAT0<3,1,0> is the NAT bit for %R3.

Floating Point Registers

%F0...%F127 Floating Poing Registers 0...127

**Table B-3 Debugger Symbols for I64 Registers (I64 Only)**
Symbol	Description
I64 Application Registers
%KR0...%KR7	Kernel registers 0...7
%RSC (%AR16)	Register Stack Configuration
%BSPSTORE (%AR18)	Backing Store Pointer for Memory Stores
%RNAT (%AR19)	RSE NaT Collection
%CCV ($AR32)	Compare and Exchange Compare Value
%UNAT (%AR36)	User NaT Collection
%FPSR (%AR40)	Floating-point Status
%PFS (%AR64)	Previous Function State
%LC (%AR65)	Loop Count
%EC (%AR66)	Epilog Count
%CSD	Code Segment
%SSD	Stack Segment
Control Registers
%DCR (%CR0)	Default Control
%ITM (%CR1)	Interval Timer Match (only visible for SCD)
%IVA (%CR2)	Interruption Vector Address (only visible for SCD)
%PTA (%CR8)	Page Table Address (only visible for SCD)
%PSR (%CR9, %ISPR)	Interruption Processor Status
%ISR (%CR17)	Interruption Status
%IIP (%CR19)	Interruption Instruction Pointer
%IFA (%CR20)	Interruption Faulting Address
%ITIR (%CR21)	Interruption TLB Insertion
%IIPA (%CR22)	Interruption Instruction Previous
%IFS (%CR23)	Interruption Function State
%IIM (%CR24)	Interruption Immediate
%IHA (%CR25)	Interruption Hash Address
%LID (%CR64)	Local Interrupt ID (only visible for SCD)
%TPR (%CR66)	Task Priority (only visible for SCD)
%IRR0...%IRR3 (%CR68...%CR71)	External Interrupt Request 0...3 (only visible for SCD)
%ITV (%CR72)	Interval Timer (only visible for SCD)
%PMV (%CR73)	Performance Monitoring (only visible for SCD)
%CMCV (%CR74)	Corrected Machine Check Vector (only visible for SCD)
%IRR0 and %IRR1 (%CR80 and %CR81)	Local Redirection 0:1 (only visible for SCD)
Special Registers
%IH (%SR0)	Invocation Handle
%PREV_BSP	Previous Backing Store Pointer
%PC (%IP)	Program Counter (Instruction Pointer \| slot number)
%RETURN_PC	Return Program Counter
%CFM	Current Frame Marker
%NEXT_PFS	Next Prefious Frame State
%PSP	Previous Stack Pointer
%CHFCTX_ADDR	Condition Handling Facility Context Address
%OSSD	Operating System Specific Data
%HANDLER_FV	Handler Function Value
%LSDA	Language Specific Data Area
%UM	User Mask
Predicate Registers
%PR (%PRED)	Predicate Collection Register---Collection of %P0...%P63
%P0...%P63	Predicate (single-bit)Registers 0...63
Branch Registers
%RP (%B0)	Return Pointer
%B1...%B7	Branch Registers 1...7
General Integer Registers
%R0	General Integer Register 0
%GP (%R1)	Global Data Pointer
%R2...%R11	General Integer Registers 2...11
%SP (%R12)	Stack Pointer
%TP (%R13)	Thread Pointer
%R14...%R24	General Integer Registers 14...24
%AP (%R25)	Argument Information
%R26...%R127	General Integer Registers 26...127
Output Registers
%OUT0...%OUT7	Output Registers, runtime aliases (i.e., If the frame has allocated output registers, then %OUT0 maps to the first allocated output registers, for example, %R38, etc.)
General Registers
%GRNAT0 and %GRNAT1	General Register Not A Thing (NAT) collection registers 64 bits each, for example, %GRNAT0<3,1,0> is the NAT bit for %R3.
Floating Point Registers
%F0...%F127	Floating Poing Registers 0...127

See Section 4.4 and reference (I64_reg_status_sec) for more information about the I64 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 HP DECwindows Motif for OpenVMS)

The %DECWINDOWS built-in symbol enables you to determine whether the debugger's HP DECwindows Motif for OpenVMS or command interface was displayed. When the HP DECwindows Motif for OpenVMS user 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))