HP OpenVMS System Analysis Tools Manual

Previous Contents Index

2.6 SDA Command Format

The following sections describe the format of SDA commands and the expressions you can use with SDA commands.

SDA uses a command format similar to that used by the DCL interpreter. Issue commands in the following format:

command-name[/qualifier...] [parameter][/qualifier...] [!comment]

The command-name is an SDA command. Each command tells the utility to perform a function. Commands can consist of one or more words, and can be abbreviated to the number of characters that make the command unique. For example, SH stands for SHOW.

The parameter is the target of the command. For example, SHOW PROCESS RUSKIN tells SDA to display the context of the process RUSKIN. The command EXAMINE 80104CD0;40 displays the contents of 40 bytes of memory, beginning with location 80104CD0.

When you supply part of a file specification as a parameter, SDA assumes default values for the omitted portions of the specification. The default device is SYS$DISK, the device specified in your most recent SET DEFAULT command. The default directory is the directory specified in the most recent SET DEFAULT command. See the HP OpenVMS DCL Dictionary for a description of the DCL command SET DEFAULT.

The qualifier modifies the action of an SDA command. A qualifier is always preceded by a slash (/). Several qualifiers can follow a single parameter or command name, but each must be preceded by a slash. Qualifiers can be abbreviated to the shortest string of characters that uniquely identifies the qualifier.

The comment consists of text that describes the command; this comment is not actually part of the command. Comments are useful for documenting SDA command procedures. When executing a command, SDA ignores the exclamation point and all characters that follow it on the same line.

2.6.1 Using Expressions and Operators

You can use expressions as parameters for some SDA commands, such as SEARCH and EXAMINE. To create expressions, use any of the following elements:

Numerals are one possible component of an expression. The following sections describe the use of the other components. Radix Operators

Radix operators determine which numeric base SDA uses to evaluate expressions. You can use one of the three radix operators to specify the radix of the numeric expression that follows the operator:

The default radix is hexadecimal. SDA displays hexadecimal numbers with leading zeros and decimal numbers with leading spaces. Arithmetic and Logical Operators

There are two types of arithmetic and logical operators:

In evaluating expressions containing binary operators, SDA performs logical AND, OR, and XOR operations, and multiplication, division, and arithmetic shifting before addition and subtraction. Note that the SDA arithmetic operators perform integer arithmetic on 64-bit operands.

Table 2-3 SDA Unary Operators
Operator Action
# Performs a logical NOT of the expression.
+ Makes the value of the expression positive.
-- Makes the value of the expression negative.
@ Evaluates the following expression as an address, then uses the contents of that address as its value.
^Q Specifies that the size of the field to be used as an address is a quadword when used with the unary operator @ 1.
^L Specifies that the size of the field to be used as an address is a longword when used with the unary operator @ 1.
^W Specifies that the size of the field to be used as an address is a word when used with the unary operator @ 1.
^B Specifies that the size of the field to be used as an address is a byte when used with the unary operator @ 1.
^P Specifies a physical address when used with the unary operator @ 1.
^V Specifies a virtual address when used with the unary operator @ 1.
G Adds FFFFFFFF 80000000 16 to the value of the expression 2.
H Adds 7FFE0000 16 to the value of the expression 3.
I Fills the leading digits of the following hexadecimal number with hex value of F. For example:
SDA> eval i80000000

Hex = FFFFFFFF.80000000 Decimal = -2147483648 G

1The command SET FETCH can be used to change the default FETCH size and/or access method. See the SET FETCH command description in Chapter 4 for more details and examples.
2The unary operator G corresponds to the first virtual address in S0 system space. For example, the expression GD40 can be used to represent the address FFFFFFFF 80000D4016.
3The unary operator H corresponds to a convenient base address in P1 space (7FFE000016). You can therefore refer to an address such as 7FFE2A6416 as H2A64.

Table 2-4 SDA Binary Operators
Operator Action
+ Addition
-- Subtraction
* Multiplication
& Logical AND
| Logical OR
\ Logical XOR
/ Division 1
@ Arithmetic shifting
"." Catenates two 32-bit values into a 64-bit value. For example:
SDA> eval fe.50000

Hex = 000000FE00050000 Decimal = 1090922020864

1In division, SDA truncates the quotient to an integer, if necessary, and does not retain a remainder. Precedence Operators

SDA uses parentheses as precedence operators. Expressions enclosed in parentheses are evaluated first. SDA evaluates nested parenthetical expressions from the innermost to the outermost pairs of parentheses. SDA Symbols

An SDA symbol can represent several value types. It can represent a constant, a data address, a procedure or function descriptor address, or a routine address. Constants are usually offsets of a particular field in a data structure; however, they can also represent constant values such as the BUG$_xxx symbols.

Symbols are composed of up to 31 letters and numbers, and can include the dollar sign ($) and underscore (_) characters. When you invoke SDA, it reads in the global symbols from the symbols table section of SYS$BASE_IMAGE.EXE, and from REQSYSDEF.STB, a required subset of the symbols in the file SYSDEF.STB. You can add other symbols to SDA's symbol table by using the DEFINE and READ commands.

All address symbols identify memory locations. SDA generally does not distinguish among different types of address symbols. However, for a symbol identified as the name of a procedure descriptor, SDA takes an additional step of creating an associated symbol to name the code entry point address of the procedure. It forms the code entry point symbol name by appending _C to the name of the procedure descriptor.

Also, SDA substitutes the code entry point symbol name for the procedure descriptor symbol when you enter the following command:

SDA> EXAMINE/INSTRUCTION procedure-descriptor

For example, enter the following command:


SDA displays the following information:

SCH$QAST_C:     SUBQ    SP,#X40,SP 

Now enter the EXAMINE command but do not specify the /INSTRUCTION qualifier, as follows:


SDA displays the following information:

SCH$QAST:  0000002C.00003009   ".0..,..." 

This display shows the contents of the first two longwords of the procedure descriptor.

Note that there are no routine address symbols on Alpha systems, except for those in MACRO-64 assembly language modules. Therefore, SDA creates a routine address symbol for every procedure descriptor it has in its symbol table. The new symbol name is the same as for the procedure descriptor except that it has an _C appended to the end of the name.

Sources for SDA Symbols

SDA obtains its information from the following:

SDA also defines symbols to access registers and to access common data structures.

The only images with symbols are shareable images and executive images. These images contain only universal symbols, such as constants and addresses.

The image symbol table files are produced by the linker with the /SYMBOLS qualifier. These files normally contain only universal symbols, as do the executable images. However, if the SYMBOL_TABLE=GLOBALS linker option is specified, the .STB file also contains all global symbols defined in the image. See the HP OpenVMS Linker Utility Manual for more information.

Object files can contain global constant values. An object file used with SDA typically contains symbol definitions for data structure fields. Such an object file can be generated by compiling a MACRO-32 source module that invokes specific macros. The macros, which are typically defined in SYS$LIBRARY:LIB.MLB or STARLET.MLB, define symbols that correspond to data structure field offsets. The macro $UCBDEF, for example, defines offsets for fields within a unit control block (UCB). OpenVMS Alpha and Integrity servers provide several such object modules in SDA$READ_DIR, as listed in Table 2-5. For compatibility with OpenVMS VAX, the modules' file types have been renamed to .STB.

Table 2-5 Modules Containing SDA Global Symbols and Data Structures
File Contents
DCLDEF.STB Symbols for the DCL interpreter
DECDTMDEF.STB Symbols for transaction processing
GLXDEF.STB Symbols for OpenVMS Galaxy data structures
IMGDEF.STB Symbols for the image activator
IODEF.STB I/O database structure symbols
NETDEF.STB Symbols for DECnet data structures
REQSYSDEF.STB Required symbols for SDA
RMSDEF.STB Symbols that define RMS internal and user data structures and RMS$_ xxx completion codes
SCSDEF.STB Symbols that define data structures for system communications services
SYSDEF.STB Symbols that define system data structures, including the I/O database
TCPIP$NET_GLOBALS.STB 1 Data structure definitions for TCP/IP internet driver, execlet, and ACP data structures
TCPIP$NFS_GLOBALS.STB 1 Data structure definitions for TCP/IP NFS server
TCPIP$PROXY_GLOBALS.STB 1 Data structure definitions for TCP/IP proxy execlet
TCPIP$PWIP_GLOBALS.STB 1 Data structure definitions for TCP/IP PWIP driver, and ACP data structures
TCPIP$TN_GLOBALS.STB 1 Data structure definitions for TCP/IP TELNET/RLOGIN server driver data structures

1Available only if TCP/IP has been installed.

Table 2-6 lists symbols that SDA defines automatically on initialization.

Table 2-6 SDA Symbols Defined on Initialization
ASN Address space number
AST Both the asynchronous system trap status and enable registers: AST<3:0> = AST enable; AST<7:4> = AST status
BR0 through BR7 Branch registers (Integrity servers only)
CYCLE_COUNTER Process cycle counter
ESP Executive stack pointer
EBSP Executive register stack pointer (Integrity servers only)
FEN Floating-point enable
FP Frame pointer (R29)
FP0 through FP31 Floating-point registers (Alpha only)
FP0 through FP127 Floating point registers (Integrity servers only)
FPCR Floating-point control register (Alpha only)
FPSR Floating-point status register (Integrity servers only)
GP Global pointer (R1) (Integrity servers only)
G FFFFFFFF.80000000 16, the base address of system space
H 00000000.7FFE0000 16, a base address in P1 space
I FFFFFFFF.FFFFFFFF 16, also fills the leading digits of a hexadecimal number with the value of F
KSP Kernel stack pointer
KBSP Kernel register stack pointer (Integrity servers only)
PAL_RSVD PAL reserved area in process HWPCB
PC Program counter
PCC Process cycle counter
PS Processor status
PTBR Page table base register
R0 through R31 Integer registers (Alpha only)
R0 through R127 Integer registers (Integrity servers only)
SCC System cycle counter
SP Current stack pointer of a process
SSP Supervisor stack pointer
SBSP Supervisor register stack pointer (Integrity servers only)
SYSPTBR Page table base register for system space
USP User stack pointer
UBSP User register stack pointer (Integrity servers only)
VIRBND Virtual Address Boundary for RADs (Alpha only)

After a SET CPU command is issued (for analyzing a crash dump only), the symbols defined in Table 2-7 are set for that CPU.

Table 2-7 SDA Symbols Defined by SET CPU Command
CPUDB Address of CPU database
IPL Interrupt priority level register
MCES Machine check error summary register
PCBB Process context block base register
PRBR Processor base register (CPU database address)
RAD Address of RAD database
SCBB System control block base register
SISR Software interrupt status register
VPTB Virtual Page Table Base register

After a SET PROCESS command is issued, the symbols listed in Table 2-8 are defined for that process.

Table 2-8 SDA Symbols Defined by SET PROCESS Command
ARB Address of access rights block
FRED Address of floating-point register and execution data block
JIB Address of job information block
KTB Address of the kernel thread block
ORB Address of object rights block
PCB Address of process control block
PHD Address of process header
PSB Address of persona security block

Other SDA commands, such as SHOW DEVICE and SHOW CLUSTER, predefine additional symbols.

Symbols can include lowercase letters. Commands that manipulate symbols (such as DEFINE, SHOW SYMBOL, UNDEFINE) require these symbols to be enclosed within quotation marks ("symbol" ).

SDA Symbol Initialization

On initialization, SDA reads the universal symbols defined by SYS$BASE_IMAGE.EXE. For every procedure descriptor address symbol found, a routine address symbol is created (with _C appended to the symbol name).

SDA then reads the object file REQSYSDEF.STB. This file contains data structure definitions that are required for SDA to run correctly. It uses these symbols to access some of the data structures in the crash dump file or on the running system.

Finally, SDA initializes the process registers defined in Table 2-8 and executes a SET CPU command, defining the symbols as well.

Use of SDA Symbols

There are two major uses of the address type symbols. First, the EXAMINE command employs them to find the value of a known symbol. For example, EXAMINE CTL$GL_PCB finds the PCB for the current process. Then, certain SDA commands (such as EXAMINE, SHOW STACK, and FORMAT) use them to symbolize addresses when generating output.

When the code for one of these commands needs a symbol for an address, it calls the SDA symbolize routine. The symbolize routine tries to find the symbol in the symbol table whose address is closest to, but not greater than the requested address. This means, for any given address, the routine may return a symbol of the form symbol_name+offset. If, however, the offset is greater than 0FFF16, it fails to find a symbol for the address.

As a last resort, the symbolize routine checks to see if this address falls within a known memory range. Currently, the only known memory ranges are those used by the OpenVMS executive images and those used by active images in a process. SDA searches through the executive loaded image list (LDRIMG data structure) and activated image list (IMCB data structures) to see if the address falls within any of the image sections. If SDA does find a match, it returns one of the following types of symbols:


The offset is the same as the image offset as defined in the map file.

The constants in the SDA symbol table are usually used to display a data structure with the FORMAT command. For example, the PHD offsets are defined in SYSDEF.STB; you can display all the fields of the PHD by entering the following commands:

SDA> FORMAT/TYPE=PHD phd_address 

Symbols and Address Resolution

In OpenVMS, executive and user images are loaded into dynamically assigned address space. To help you associate a particular virtual address with the image whose code has been loaded at that address, SDA provides several features:

The OpenVMS executive consists of two base images, SYS$BASE_IMAGE.EXE and SYS$PUBLIC_VECTORS.EXE, and a number of other separately loadable images. Some of these images are loaded on all systems, while others support features unique to particular system configurations. Executive images are mapped into system space during system initialization.

By default, a typical executive image is not mapped at contiguous virtual addresses. Instead, its nonpageable image sections are loaded into a reserved set of pages with other executive images' nonpageable sections. The pageable sections of a typical executive image are mapped contiguously into a different part of system space. An image mapped in this manner is said to be sliced. A particular system may have system parameters defined that disable executive image slicing altogether.

Each executive image is described by a data structure called a loadable image data block (LDRIMG). The LDRIMG specifies whether the image has been sliced. If the image is sliced, the LDRIMG indicates the beginning of each image section and the size of each section. All the LDRIMGs are linked together in a list that SDA scans to determine what images have been loaded and into what addresses they have been mapped. The SHOW EXECUTIVE command displays a list of all images that are included in the OpenVMS executive.

Each executive image is a shareable image whose universal symbols are defined in the SYS$BASE_IMAGE.EXE symbol vector. On initialization, SDA reads this symbol vector and adds its universal symbols to the SDA symbol table.

Executive image .STB files define additional symbols within an executive image that are not defined as universal symbols and thus are not in the SYS$BASE_IMAGE.EXE symbol vector (see Sources for SDA Symbols in this section). You can enter a READ/EXECUTIVE command to read symbols defined in all executive image .STB files into the SDA symbol table, or a READ/IMAGE filespec command to read the .STB for a specified image only.

To obtain a display of all images mapped within a process, execute a SHOW PROCESS/IMAGE command. See the description of the SHOW PROCESS command for additional information about displaying the hardware and software context of a process.

You can also identify the image name and offset that correspond to a specified address with the MAP command. With the information obtained from the MAP command, you can then examine the image map to locate the source module and program section offset corresponding to an address.

2.6.2 SDA Display Mode

Some SDA commands produce more output than will fit on one screen. In this situation, SDA enters display mode, and outputs the screen overflow prompt at the bottom of the screen:

Press RETURN for more. 

If the RETURN key is pressed, SDA will continue the output of the command it was processing. If an EXIT command is entered, SDA will leave display mode, abort the command it was processing and output a regular SDA prompt. If any other command is entered, SDA will leave display mode, abort the command it was processing, and begin processing the new command.

SDA will leave display mode once a continued command completes.

Previous Next Contents Index