HP OpenVMS Systems Documentation

Loads the global symbols contained in the specified file into the SDA symbol table.

Format

READ {/EXECUTIVE [directory spec]
| /FORCE filespec [/RELOCATE =expression | /SYMVA=expression]
| /IMAGE filespec
| filespec}
[ /[NO]LOG]

Parameters

directory-spec

Name of the directory containing the loadable images of the executive. This parameter defaults to SDA$READ_DIR, which is a search list of SYS$LOADABLE_IMAGES, SYS$LIBRARY, and SYS$SYSTEM.

filespec

Name of the device, directory, and file from which you want to read global symbols. The filespec defaults to SYS$DISK:[default-dir]filename.type, where SYS$DISK and [default-dir] represent the disk and directory specified in your last DCL command SET DEFAULT. If no type has been given in filespec, SDA first tries .STB and then .EXE.

If no device or directory is given in the file specification, and the file specification is not found in SYS$DISK:[default_dir], then SDA attempts to open the file SDA$READ_DIR:filename.type. If no type has been given in filespec, SDA first tries .STB and then .EXE.

If the file name is the same as that of an execlet or image, but the symbols in the file are not those of the execlet or image, then you must use the /FORCE qualifier, and optionally /RELOCATE and /SYMVA qualifiers, to tell SDA how to interpret the symbols in the file.

The READ command accepts quoted filenames for access to images on ODS-5 disks with lowercase or compound characters in their names.

Qualifiers

/EXECUTIVE directory-spec

Reads into the SDA symbol table all global symbols and global entry points defined within all loadable images that make up the executive. For all the execlets in the system, SDA reads the .STB or .EXE files in the requested directory.

/FORCE filespec

Forces SDA to read the symbols file, regardless of what other information or qualifiers are specified. If you do not specify the /FORCE qualifier, SDA may not read the symbols file if the specified filespec matches the image name in either the executive loaded images or the current processes activated image list, and one of the following conditions is true:

• The image has a symbols vector (is a shareable image), and a symbols vector was not specified with the /SYMVA or /IMAGE qualifier.
• The image is sliced, and slicing information was not provided with the /IMAGE qualifier.
• The shareable or executive image is not loaded at the same address it was linked at, and the relocation information was not provided with either the /IMAGE or /RELOCATE qualifier.

The use of /FORCE [/SYMVA=addr][/RELOCATE=addr] filespec is a variant of the /IMAGE qualifier and avoids fixing up the symbols to match an image of the same name.

/IMAGE filespec

Searches the executive loaded image list and the current process activated image list for the image specified by filespec. If the image is found, the symbols are read in using the image symbol vector (if there is one) and either slicing or relocation information.

This is the preferred way to read in the .STB files produced by the linker. These .STB files contain all universal symbols, unless SYMBOL_TABLE=GLOBAL is in the linker options file, in which case the .STB file contains all universal and global symbols.

/LOG

/NOLOG (D)

The /LOG qualifier causes SDA to output the %SDA-I-READSYM message for each symbol table file it reads. By default, these messages are suppressed. You can specify /LOG and /NOLOG with any other combination of parameters and qualifiers.

/RELOCATE=expression

Changes the relative addresses of the symbols to absolute addresses by adding the value of expression to the value of each symbol in the symbol table file to be read. This qualifier changes those addresses to absolute addresses in the address space into which the dump is mapped.

The relocation only applies to symbols with the relocate flag set. All universal symbols must be found in the symbol vector for the image. All constants are read in without any relocation.

If the image is sliced (image sections are placed in memory at different relative offsets than how the image is linked), then the /RELOCATE qualifier does not work. SDA compares the file name used as a parameter to the READ command against all the image names in the executive loaded image list and the current processes activated image list. If a match is found, and that image contains a symbol vector, an error results. At this point you can either use the /FORCE qualifier or the /IMAGE qualifier to override the error.

/SYMVA=expression

Informs SDA whether the absolute symbol vector address is for a shareable image (SYS$PUBLIC_VECTORS.EXE) or base system image (SYS$BASE_IMAGE.EXE). All symbols found in the file with the universal flag are found by referencing the symbol vector (that is, the symbol value is a symbol vector offset).

Description

The READ command symbolically identifies locations in memory and the definitions used by SDA for which the default files (SDA$READ_DIR:SYS$BASE_IMAGE.EXE and SDA$READ_DIR:REQSYSDEF.STB) provide no definition. In other words, the required global symbols are located in modules and symbol tables that have been compiled and/or linked separately from the executive. SDA extracts no local symbols from the files.

The file specified in the READ command can be the output of a compiler or assembler (for example, an .OBJ file).

Note The READ command can read both OpenVMS Alpha and OpenVMS Integrity servers format files. Do not use READ to read files that contain symbols specific to another architecture, as this might change the behavior of other SDA commands for the current architecture.

Most often the file is provided in SYS$LOADABLE_IMAGES. Many SDA applications, for instance, need to load the definitions of system data structures by issuing a READ command specifying SYSDEF.STB. Others require the definitions of specific global entry points within the executive image.

The files in SYS$LOADABLE_IMAGES define global locations within executive images, including those listed in Table 4-2. The actual list of executive images used varies, depending on platform type, devices, and the settings of several system parameters.

Table 4-2 Modules Defining Global Locations Within Executive Images

File	Contents
ACME.EXE	$ACM system service
CNX$DEBUG.EXE	Connection Manager trace routines
DDIF$RMS_EXTENSION.EXE	Support for Digital Document Interchange Format (DDIF) file operations
ERRORLOG.STB	Error-logging routines and system services
EXCEPTION.STB 1	Bugcheck and exception-handling routines and those system services that declare condition and exit handlers
EXEC_INIT.STB	Initialization code
F11BXQP.STB	File system support
FC$GLOGALS.STB	Fibrechannel symbols
IMAGE_MANAGEMENT.STB	Image activator and the related system services
IO_ROUTINES.STB 1	$QIO system service, related system services (for example, $CANCEL and $ASSIGN), and supporting routines
LAT$RATING.EXE	CPU load-balancing routines for LAT
LCK$DEBUG.EXE	Lock manager trace routines
LMF$GROUP_TABLE.EXE 4	Data structures for licensed product groups
LOCKING.STB	Lock management routines and system services
LOGICAL_NAMES.STB	Logical name routines and system services
MESSAGE_ROUTINES.STB	System message routines and system services (including $SNDJBC and $GETTIM)
MSCP.EXE	Disk MSCP server
MULTIPATH.STB 1	Fibrechannel multipath support routines
NET$CSMACD.EXE	CSMA/CD LAN management module
NET$FDDI.EXE	FDDI LAN management module
NT_EXTENSION.EXE	NT extensions for persona system services
PROCESS_MANAGEMENT.STB 1	Scheduler, report system event, and supporting routines and system services
RECOVERY_UNIT_SERVICES.STB	Recovery unit system services
RMS.EXE	Global symbols and entry points for RMS
SECURITY.STB 1	Security management routines and system services
SHELL xxK.STB	Process shell
SPL$DEBUG.EXE	Spinlock trace routines
SSPI.EXE	Security Support Provider Interface
SYS$ xxDRIVER.EXE	Run-time device drivers
SYS$ACPI.EXE 5	Advanced Configuration and Power Interface routines
SYS$ATMWORKS351.EXE	PCI-ATM driver
SYS$CLUSTER.EXE	OpenVMS Cluster support routines
SYS$CPU_ROUTINES_ xxxx.EXE 4	Processor-specific data and initialization routines
SYS$EW1000A.EXE	Gigabit Ethernet driver
SYS$EW5700.EXE 5	Gigabit Ethernet driver
SYS$GALAXY.STB	OpenVMS Galaxy support routines
SYS$HWP nnnn.EXE 5	PCI support routines
SYS$IPC_SERVICES.EXE	Interprocess communication for DECdtm and Batch/Print
SYS$IPI nnnn.EXE 5	PCI support routines
SYS$LAN.EXE	Common LAN routines
SYS$LAN_ATM.EXE	LAN routines for ATM
SYS$LAN_ATM4.EXE	LAN routines for ATM (ForeThought)
SYS$LAN_CSMACD.EXE	LAN routines for CSMA/CD
SYS$LAN_FDDI.EXE	LAN routines for FDDI
SYS$LAN_TR.EXE	LAN routines for Token Ring
SYS$MME_SERVICES.STB	Media Management Extensions
SYS$NETWORK_SERVICES.EXE	DECnet support
SYS$NTA.STB	NT affinity routines and services
SYS$ xxxx_SUPPORT.EXE 5	Processor-specific data and initialization routines
SYS$PUBLIC_VECTORS.EXE 2	System service vector base image
SYS$SCS.EXE	System Communication Services
SYS$TRANSACTION_SERVICES.EXE	DECdtm services
SYS$UTC_SERVICES.EXE	Universal Coordinated Time services
SYS$VCC.STB 1, 4	Virtual I/O cache
SYS$VM.STB	System pager and swapper, along with their supporting routines, and management system services
SYS$XFCACHE.STB 1	Extented File Cache
SYSDEVICE.STB	Mailbox driver and null driver
SYSGETSYI.STB	Get System Information system service ($GETSYI)
SYSLDR_DYN.STB	Dynamic executive image loader
SYSLICENSE.STB	Licensing system service ($LICENSE)
SYSTEM_DEBUG.EXE	XDelta and SCD routines
SYSTEM_PRIMITIVES.STB 1	Miscellaneous basic system routines, including those that allocate system memory, maintain system time, create fork processes, and control mutex acquisition
SYSTEM_SYNCHRONIZATION.STB 1	Routines that enforce synchronization
TCPIP$BGDRIVER.STB 3	TCP/IP internet driver
TCPIP$INETACP.STB 3	TCP/IP internet ACP
TCPIP$INETDRIVER.STB 3	TCP/IP internet driver
TCPIP$INTERNET_SERVICES.STB 3	TCP/IP internet execlet
TCPIP$NFS_SERVICES.STB 3	Symbols for the TCP/IP NFS server
TCPIP$PROXY_SERVICES.STB 3	Symbols for the TCP/IP proxy execlet
TCPIP$PWIPACP.STB 3	TCP/IP PWIP ACP
TCPIP$PWIPDRIVER.STB 3	TCP/IP PWIP driver
TCPIP$TNDRIVER.STB 3	TCP/IP TELNET/RLOGIN server driver
TMSCP.EXE	Tape MSCP server
VMS_EXTENSION.EXE	VMS extensions for persona system services

SDA can also read symbols from an image .EXE or .STB produced by the linker. The STB and EXE files only contain universal symbols. The STB file, however, can be forced to have global symbols for the image if you use the SYMBOL_TABLE=GLOBAL option in the linker options file.

A number of ready-built symbol table files ship with OpenVMS. They can be found in the directory SYS$LOADABLE_IMAGES, and all have names of the form xyzDEF.STB. Of these files, SDA automatically reads REQSYSDEF.STB on activation. You can add the symbols in the other files to SDA's symbol table using the READ command. Table 2-5 lists the files that OpenVMS provides in SYS$LOADABLE_IMAGES that define data structure offsets.

The following MACRO program, GLOBALS.MAR, shows how to obtain symbols in addition to those in SYS$BASE_IMAGE.EXE, other executive images listed in Table 4-2, and the symbol table files that are listed in Table 2-5:

.TITLE GLOBALS 
; n.b. on following lines GLOBAL must be capitalized 
$PHDDEF GLOBAL          ; Process header definitions 
$DDBDEF GLOBAL          ; Device data block 
$UCBDEF GLOBAL          ; Unit control block 
$VCBDEF GLOBAL          ; Volume control block 
$ACBDEF GLOBAL          ; AST control block 
$IRPDEF GLOBAL          ; I/O request packet 
; more can be inserted here 
.END 

Use the following command to generate an object module file containing the globals defined in the program:

$MACRO GLOBALS+SYS$LIBRARY:LIB/LIBRARY /OBJECT=GLOBALS.STB

Examples

SDA>  READ SDA$READ_DIR:SYSDEF.STB/LOG
%SDA-I-READSYM, 10010 symbols read from SYS$COMMON:[SYSEXE]SYSDEF.STB;1
      

The READ command causes SDA to add all the global symbols in SDA$READ_DIR:SYSDEF.STB to the SDA symbol table. Such symbols are useful when you are formatting an I/O data structure, such as a unit control block or an I/O request packet.

SDA> SHOW STACK
Process stacks (on CPU 00)
--------------------------
Current operating stack (KERNEL):
                                 
        00000000.7FF95CD0  FFFFFFFF.80430CE0  SCH$STATE_TO_COM+00040
        00000000.7FF95CD8  00000000.00000000
        00000000.7FF95CE0  FFFFFFFF.81E9CB04  LNM$SEARCH_ONE_C+000E4
        00000000.7FF95CE8  FFFFFFFF.8007A988  PROCESS_MANAGEMENT_NPRO+0E988
   SP =>00000000.7FF95CF0  00000000.00000000
        00000000.7FF95CF8  00000000.006080C1
        00000000.7FF95D00  FFFFFFFF.80501FDC
        00000000.7FF95D08  FFFFFFFF.81A5B720
   .
   .
   .
 
SDA>  READ/IMAGE SYS$LOADABLE_IMAGES:PROCESS_MANAGEMENT/LOG
%SDA-I-READSYM, 767 symbols read from SYS$COMMON:[SYS$LDR]PROCESS_MANAGEMENT.STB;1
SDA>  SHOW STACK
Process stacks (on CPU 00)
--------------------------
Current operating stack (KERNEL):
                                 
        00000000.7FF95CD0  FFFFFFFF.80430CE0  SCH$FIND_NEXT_PROC
        00000000.7FF95CD8  00000000.00000000
        00000000.7FF95CE0  FFFFFFFF.81E9CB04  LNM$SEARCH_ONE_C+000E4
        00000000.7FF95CE8  FFFFFFFF.8007A988  SCH$INTERRUPT+00068
   SP =>00000000.7FF95CF0  00000000.00000000
        00000000.7FF95CF8  00000000.006080C1
        00000000.7FF95D00  FFFFFFFF.80501FDC
        00000000.7FF95D08  FFFFFFFF.81A5B720
   .
   .
   .
 
      

The initial SHOW STACK command contains an address that SDA resolves into an offset from the PROCESS_MANAGEMENT executive image. The READ command loads the corresponding symbols into the SDA symbol table such that the reissue of the SHOW STACK command subsequently identifies the same location as an offset within a specific process management routine.

Repeats execution of the last command issued. On terminal devices, the KP0 key performs the same function as the REPEAT command with no parameter or qualifier.

Format

REPEAT [count | /UNTIL=condition]

Parameter

count

Number of times the previous command is to be repeated. The default is a single repeat.

Qualifier

/UNTIL=condition

Defines a condition that terminates the REPEAT command. By default, there is no terminating condition.

Description

The REPEAT command is useful for stepping through a linked list of data structures, or for examining a sequence of memory locations. When used with ANALYZE/SYSTEM, it allows the changing state of a system location or data structure to be monitored.

You can also use the REPEAT command to provide a convenient method of either displaying a series of data structures in a linked list or examining a sequence of locations. For example:

FORMAT @IOC$GL_DEVLIST ! Start at first DDB in system FORMAT @. ! Skip to next entry in list <KP0> ! Repeat FORMAT @. command . . .

Examples

SDA> SPAWN CREATE SDATEMP.COM
SEARCH  0:3FFFFFFF   12345678
SET PROCESS/NEXT
^Z
SDA>  SET PROCESS NULL
SDA>  @SDATEMP
SDA>  REPEAT/UNTIL = BADPROC 
 
      

This example demonstrates how to search the address space of each process in a system or dump a given pattern.

SDA> SPAWN CREATE SDATEMP2.COM
FORMAT CPUDB
SET CPU /NEXT
^Z
SDA>  READ SYSDEF
SDA>  SET CPU /FIRST
SDA>  @SDATEMP2
SDA>  REPEAT/UNTIL = BADCPU
      

This example demonstrates how to format the CPU database for every CPU in a dump.

SDA> SHOW CALL_FRAME
Call Frame Information 
---------------------- 
        Stack Frame Procedure Descriptor 
Flags:  Base Register = FP, Jacket, Native 
        Procedure Entry: FFFFFFFF.80080CE0           MMG$RETRANGE_C+00180 
        Return address on stack = FFFFFFFF.8004CF30  EXCEPTION_NPRO+00F30 
 
Registers saved on stack 
------------------------ 
7FF95E80 FFFFFFFF.FFFFFFFD  Saved R2 
7FF95E88 FFFFFFFF.8042DBC0  Saved R3      EXCEPTION_NPRW+03DC0 
7FF95E90 FFFFFFFF.80537240  Saved R4 
7FF95E98 00000000.00000000  Saved R5 
7FF95EA0 FFFFFFFF.80030960  Saved R6      MMG$IMGRESET_C+00200 
7FF95EA8 00000000.7FF95EC0  Saved R7 
7FF95EB0 FFFFFFFF.80420E68  Saved R13     MMG$ULKGBLWSL E 
7FF95EB8 00000000.7FF95F70  Saved R29 
. 
. 
. 
SDA> SHOW CALL_FRAME/NEXT_FRAME 
 
Call Frame Information 
---------------------- 
        Stack Frame Procedure Descriptor 
Flags:  Base Register = FP, Jacket, Native 
        Procedure Entry: FFFFFFFF.80F018D0              IMAGE_MANAGEMENT_PRO+078D0 
        Return address on stack = FFFFFFFF.8004CF30     EXCEPTION_NPRO+00F30 
 
Registers saved on stack 
------------------------ 
7FF95F90 FFFFFFFF.FFFFFFFB  Saved R2 
7FF95F98 FFFFFFFF.8042DBC0  Saved R3      EXCEPTION_ NPRW+03DC0 
7FF95FA0 00000000.00000000  Saved R5 
7FF95FA8 00000000.7FF95FC0  Saved R7 
7FF95FB0 FFFFFFFF.80EF8D20  Saved R13     ERL$DEVINF O+00C20 
7FF95FB8 00000000.7FFA0450  Saved R29 
. 
. 
. 
SDA> REPEAT 
Call Frame Information 
---------------------- 
        Stack Frame Procedure Descriptor 
Flags:  Base Register = FP, Jacket, Native 
        Procedure Entry: FFFFFFFF.80F016A0              IMAGE_MANAGEMENT_PRO+076A0 
        Return address on stack = 00000000.7FF2451C 
 
Registers saved on stack 
------------------------ 
7FFA0470 00000000.7FEEA890  Saved R13 
7FFA0478 00000000.7FFA0480  Saved R29 
. 
. 
. 
      

The first SHOW CALL_FRAME displays the call frame indicated by the current FP value. Because the /NEXT_FRAME qualifier to the instruction displays the call frame indicated by the saved frame in the current call frame, you can use the REPEAT command to repeat the SHOW CALL_FRAME/NEXT_FRAME command and follow a chain of call frames.

Scans a range of memory locations for all occurrences of a specified value or string.

Format

SEARCH [/qualifier] range [=] {expression | string}

Parameters

range

Location in memory to be searched. A location can be represented by any valid SDA expression. To search a range of locations, use the following syntax:

m:n	Range of locations to be searched, from m to n
m;n	Range of locations to be searched, starting at m and continuing for n bytes

You must use either an equals sign or a blank to separate range from expression or string.

expression

Value for which SDA is to search. SDA evaluates the expression and searches the specified range of memory for the resulting value. For a description of SDA expressions, see Section 2.6.1.

string

Character sequence for which SDA is to search. If all characters in the sequence are printable characters, the string is enclosed in quotes, for example,
"My_String". If the character sequence contains nonprintable characters, it must be specified as a comma-separated list composed of quoted strings and hexadecimal numbers; for example, ("My_String",0C00,"More") would specify a search for "My_String<NUL><FF>More". Each hexadecimal number can be no more than 8 digits (4 bytes) in length. Nonprintable sequences of more than 4 bytes must be split into multiple hexadecimal numbers. The maximum length of a search string is 127 bytes. Note that the quote character itself cannot be included in a quoted string and must be specified as a hexadecimal number.

Qualifiers

/IGNORE_CASE

Specifies that searches for strings are not to be case-specific. (By default, searches look for an exact match.) This qualifier is ignored for value searches.

/LENGTH={QUADWORD | LONGWORD | WORD | BYTE}

Specifies the size of the expression value that the SEARCH command uses for matching. If you do not specify the /LENGTH qualifier, the SEARCH command uses a longword length by default. This qualifier is ignored for string searches.

/MASK=n

Allows the SEARCH command finer qranularity in its matches. It compares only the given bits of a byte, word, longword, or quadword. To compare bits when matching, you set the bits in the mask; to ignore bits when matching, you clear the bits in the mask. This qualifier is ignored for string searches.

/PHYSICAL

Specifies that the addresses used to define the range of locations to be searched are physical addresses.

/STEPS = {QUADWORD | LONGWORD | WORD | BYTE | value}

Specifies the step factor of the search through the specified memory range. After the SEARCH command has performed the comparison between the value of expression or the given string and memory location, it adds the specified step factor to the address of the memory location. The resulting location is the next location to undergo the comparison. If you do not specify the /STEPS qualifier, the SEARCH command uses a step factor of a longword for value searches, and a step factor of a byte for string searches.

Description

SEARCH displays each location as each value or string is found. If you press Ctrl/T while using the SEARCH command, the system displays how far the search has progressed. The progress display is always output to the terminal even if a SET OUTPUT <file> command has previously been entered.

Examples

SDA> SEARCH GB81F0;500 B41B0000
Searching from FFFFFFFF.800B81F0 to FFFFFFFF.800B86EF in LONGWORD steps for B41B0000... 
Match at FFFFFFFF.800B86E4    B41B0000
      

This SEARCH command finds the value B41B0000 in the longword at FFFFFFFF.800B86E4.

SDA> SEARCH 80000000;200/STEPS=BYTE 82
Searching from FFFFFFFF.80000000 to FFFFFFFF.800001FF in BYTE steps for 00000082... 
Match at FFFFFFFF.8000012C    00000082
      

This SEARCH command finds the value 00000082 in the longword at FFFFFFFF.8000012C.

SDA> SEARCH/LENGTH=WORD 80000000;100 10
Match at FFFFFFFF.80000030    0010 
Match at FFFFFFFF.80000040    0010 
Match at FFFFFFFF.80000090    0010 
Match at FFFFFFFF.800000A0    0010 
Match at FFFFFFFF.800000C0    0010 
5 matches found
      

This SEARCH command finds the value 0010 in the words at FFFFFFFF.80000030, FFFFFFFF.80000040, FFFFFFFF.80000090, FFFFFFFF.800000A0, FFFFFFFF.800000C0.

SDA> SEARCH/MASK=FF000000 80000000;40 20000000
Searching from FFFFFFFF.80000000 to FFFFFFFF.8000003F in LONGWORD steps for 20000000... 
(Using search mask of FF000000) 
Match at FFFFFFFF.80000000    201F0104 
Match at FFFFFFFF.80000010    201F0001 
2 matches found
      

This SEARCH command finds the value 20 in the upper byte of the longwords at FFFFFFFF.80000000 and FFFFFFFF.80000010, regardless of the contents of the lower 3 bytes.

This example combines quoted strings and hexadecimal values to form a character sequence to be used in a search. Note the order in which the bytes within each hexadecimal number are inserted into the search sequence: the least significant byte of the hexadecimal number is the first byte added to the search sequence.