HP OpenVMS System Analysis Tools Manual


Previous Contents Index


Chapter 4
SDA Commands

This chapter describes the SDA commands that you can use to analyze a system dump or a running system. SDA extension commands, such as CLUE and FLT are described in separate chapters.


@(Execute Command)

Causes SDA to execute SDA commands contained in a file. Use this command to execute a set of frequently used SDA commands.

Format

@filespec


Parameter

filespec

Name of a file that contains the SDA commands to be executed. The default file type is .COM.

Example


SDA>  @USUAL
      

The execute (@) command executes the following commands, as contained in a file named USUAL.COM:


SET OUTPUT LASTCRASH.LIS 
SHOW CRASH 
SHOW PROCESS 
SHOW STACK 
SHOW SUMMARY 

This command procedure first makes the file LASTCRASH.LIS the destination for output generated by subsequent SDA commands. Next, the command procedure sends information to the file about the system failure and its context, including a description of the process executing at the time of the failure, the contents of the stack on which the failure occurred, and a list of the processes active on the system.

An EXIT command within a command procedure terminates the procedure at that point, as would an end-of-file.

Command procedures cannot be nested.


ATTACH

Switches control of your terminal from your current process to another process in your job (for example, one created with the SDA SPAWN command).

Format

ATTACH [/PARENT] process-name


Parameter

process-name

Name of the process to which you want to transfer control.

Qualifier

/PARENT

Transfers control of the terminal to the parent process of the current process. When you specify this qualifier, you cannot specify the process-name parameter.

Examples

#1

SDA>  ATTACH/PARENT
      

This ATTACH command attaches the terminal to the parent process of the current process.

#2

SDA>  ATTACH DUMPER
      

This ATTACH command attaches the terminal to a process named DUMPER in the same job as the current process.


COLLECT

Collect file identification to file name translation data on both OpenVMS Alpha and OpenVMS for Integrity servers, and process unwind data only on OpenVMS for Integrity servers.

Format

COLLECT [qualifiers]


Parameters

None


Qualifiers

/LOG

Displays information on the progress of the COLLECT command, for example, the name of the process being scanned, or (on Integrity servers) the name of an image whose unwind data is being collected.

/SAVE [= file name]

Writes collection data to a separate file. By default, a file of type .COLLECT with the same name as the dump file will be created in the same directory as the dump file.

/UNDO

Removes all the file or unwind data from an earlier COLLECT command from SDA's memory. COLLECT/UNDO does not affect the file or unwind data already appended to the dump file being analyzed, or already written to a separate collection file.

Description

When a dump is being analyzed, it is useful to have data available that cannot be written to the dump file at the time of the system crash. This data includes the full file specification associated with a file identification. On OpenVMS for Integrity servers, it also includes the unwind data for images activated in processes.

If the dump is being analyzed on the system where it was originally written, this data can be collected for use in the current SDA session using the COLLECT command. If the dump is being copied for analysis elsewhere, the COPY/COLLECT command may be used to collect the data and append it to the copy being written. If the COPY/COLLECT command is used after a COLLECT command, the data already collected is appended to the dump copy.

For all file or unwind data to be collected successfully, all disks that were mounted at the time of the system crash should be remounted and accessible to the process running SDA.

If the COPY and the COLLECT cannot be done as a single step, a COLLECT/SAVE command writes the collection to a separate file that can be used later with the dump file. A later COPY will combine the two files.


Example


SDA> COLLECT
%SDA-W-DISKNOACC, no access to _$30$DKB100: for file and/or unwind data 
%SDA-W-FILENOACC, no access to _$30$DKB0:(7709,1,0) for unwind data 
-SYSTEM-W-NOSUCHFILE, no such file 
      

In this example, the disk $30$DKB100, which was mounted at the time the system crashed, is not available when file and/or unwind data is being collected. In addition, unwind data cannot be collected for the image with file identification (7709,1,0) on _$30$DKB0: since it no longer exists.


COPY

Copies the contents of the dump file to another file.

Format

COPY [/qualifier...] output-filespec


Parameter

output-filespec

Name of the device, directory, and file to which SDA copies the dump file. The default file specification is:
SYS$DISK:[default-dir]filename.DMP

SYS$DISK and [default-dir] represent the disk and directory specified in your last DCL command SET DEFAULT. You must specify a file name.


Qualifiers

/COLLECT

/NOCOLLECT

Causes SDA to collect (or not collect) file identification or unwind data from the current system and append it to the copy being created. For more details, see the Description section.

/COMPRESS

Causes SDA to compress dump data as it is writing a copy. If the dump being analyzed is already compressed, then SDA does a direct COPY, and issues an informational message indicating that it is ignoring the /COMPRESS qualifier.

/CONFIRM

Causes SDA to prompt for which processes to copy when performing a Partial Dump Copy. This qualifier can only be used when /PARTIAL=PROCESS=option is specified. For each possible process in the set, SDA prompts as follows, where the default response is No and only a single character response is needed otherwise:


Copy process "process-name"? (Y/[N]/A/Q): 

Where the response:


YES   Includes the process in the copy. 
NO    Excludes the process from the copy. 
ALL   Includes the process and all remaining processes in the copy. 
QUIT  Excludes the process and all remaining processes from the copy. 

/DECOMPRESS

Causes SDA to decompress dump data as it is writing a copy. If the dump being analyzed is already decompressed, then SDA does a direct COPY, and issues an informational message indicating that it is ignoring the /DECOMPRESS qualifier.

/LOG

Displays information about the progress of the COPY command, for example, the name of the process being copied in a selective dump, or, in the case of COPY/COLLECT on Integrity servers, the name of an image whose unwind data is being appended to the dump copy.

/PARTIAL=(section,...)

Causes SDA to copy only the specified sections of the dump. The /PARTIAL qualifier can only be used with a selective system dump (compressed or uncompressed). It is not available for full system dumps or for process dumps. Also, the /PARTIAL qualifier cannot be combined with /COMPRESS, /DECOMPRESS, or /[NO]COLLECT. Such a copy must be performed as two separate COPY commands, and requires exiting from SDA and then re-invoking SDA on the intermediate copy.

See Section 2.2.3 for a description of Partial Dump Copies. For an explanation of key processes and key global pages, and the organization of a selective system dump, see the HP OpenVMS System Manager's Manual, Volume 2: Tuning, Monitoring, and Complex Systems.

Multiple sections must be separated by commas. If only one section is given, the parentheses may be omitted. Possible sections are as follows:

Table 4-1 Dump Sections
PT System Page Table Space
S0S1 32-bit System Space
S2 64-bit System Space
REPLICATED_SYS Replicated System Space (only applies to Alpha systems with RADs enabled)
PROCESS=option Process Space for one or more processes. Options are:
ALL All processes. This is the default.
KEY All key processes.
OTHER All other (not key) processes.
NAME=(list) Specific named processes (see note below)
GLOBAL=option Global Pages. Options are:
ALL All global pages mapped by processes. This is the default.
KEY All global pages mapped by key processes.
OTHER All other (not key) global pages mapped by processes.
KEY Equivalent to:
PT, S0S1, S2, REPLICATED_SYS, PROCESS = KEY, GLOBAL = KEY
OTHER Equivalent to:
PROCESS = OTHER, GLOBAL = OTHER
SYSTEM Equivalent to:
PT, S0S1, S2, REPLICATED_SYS

Note

If /PARTIAL=PROCESS=NAME=(list) is specified:
  • Multiple process names must be separated by commas. If only one process name is given, the parentheses may be omitted.
  • Process names can include "%" and "*" wildcards.
  • The comparison of the given name to actual process names in the dump is performed case-blind, and trailing spaces and tabs are ignored.
  • Process names can include characters, such as "," and "/". You can enclose the process name in quotes to include some of these special characters in the name you specify, or you can use the "%" wildcard instead of characters.

Description

Each time the system fails, the contents of memory and the hardware context of the current process (as directed by the DUMPSTYLE parameter) are copied into the file SYS$SYSTEM:SYSDUMP.DMP (or the page file), overwriting its contents. If you do not save this crash dump elsewhere, it will be overwritten the next time that the system fails.

The COPY command allows you to preserve a crash dump by copying its contents to another file. It is generally useful to invoke SDA during system initialization to execute the COPY command. This ensures that a copy of the dump file is made only after the system has failed. The preferred method for doing this, using the logical name CLUE$SITE_PROC, is described in Section 2.2.4.

The COPY command does not affect the contents of the file containing the dump being analyzed.

If you are using the page file (SYS$SYSTEM:PAGEFILE.SYS) as the dump file instead of SYSDUMP.DMP, successful completion of the COPY command will automatically cause the blocks of the page file containing the dump to be released, thus making them available for paging. Even if the copy operation succeeds, the release operation requires that your process have change-mode-to-kernel (CMKRNL) privilege. When the dump pages have been released from the page file, the dump information in these pages will be lost and SDA will immediately exit. You must perform subsequent analysis upon the copy of the dump created by the COPY command.

If you press Ctrl/T while using the COPY command, the system displays how much of the file has been copied.

When a dump is being analyzed, it is useful to have data available that cannot be written to the dump file at the time of the system crash. This data includes the full file specification associated with a file identification, and, on OpenVMS Integrity servers, the unwind data for images activated in processes.

If the dump is being analyzed on the system where it was originally written, this data can be collected for use in the current SDA session using the COLLECT command. If the dump is being copied for analysis elsewhere, the COPY/COLLECT command can be used to collect the data and append it to the copy being written. If the COPY/COLLECT command is used after a COLLECT command, the data already collected is appended to the dump copy.

By default, a copy of the original dump, as written at the time of the system crash, includes collection. You can use COPY/NOCOLLECT to override this default. Conversely, a copy of a dump previously copied by SDA without collection (COPY/NOCOLLECT) does not include collection. You can use COPY/COLLECT to override this setting.

When you copy a dump that already contains an appended collection, the copy will always include that collection.

For all file and unwind data to be collected successfully, all disks that were mounted at the time of the system crash should be remounted and be accessible to the process running SDA. If SDA is invoked early in the startup procedure to save the contents of the dump (for example, using CLUE$SITE_PROC as described in Section 2.2.4), but disks are not mounted until a batch job is run, you should use the COPY/NOCOLLECT command in the CLUE$SITE_PROC command procedure. Once all disks are mounted, you can use a COPY/COLLECT command to save file or unwind data.

If the COPY and the COLLECT procedures cannot be done as a single step, you can execute a COLLECT/SAVE command to write the collection to a separate file that can be used later in conjunction with the dump file. A later COPY operation can combine the two files.


Example


SDA>  COPY SYS$CRASH:SAVEDUMP
      

The COPY command copies the dump file into the file SYS$CRASH:SAVEDUMP.DMP.


DEFINE

Assigns a value to a symbol.

Format

DEFINE [/qualifier...] symbol-name [=] expression


Parameters

symbol-name

Name, containing from 1 to 31 alphanumeric characters, that identifies the symbol. Symbols that include lowercase letters must be enclosed in quotation marks ("symbol" ). See Section 2.6.1.4 for a description of SDA symbol syntax and a list of default symbols.

expression

Definition of the symbol's value. See Section 2.6.1 for a discussion of the components of SDA expressions.

Qualifier

/FD

/PD

Defines a symbol as a function descriptor (FD) or procedure descriptor (PD). It also defines the routine address symbol corresponding to the defined symbol (the routine address symbol has the same name as the defined symbol, only with _C appended to the symbol name). See Section 2.6.1.4 for more information about symbols. /FD and /PD are completely interchangeable. SDA interprets them based on the architecture of the system or dump being analyzed.

Description

The DEFINE command causes SDA to evaluate an expression and then assign its value to a symbol. Both the DEFINE and EVALUATE commands perform computations to evaluate expressions. DEFINE adds symbols to the SDA symbol table but does not display the results of the computation. EVALUATE displays the result of the computation but does not add symbols to the SDA symbol table.

Examples

#1

SDA>  DEFINE BEGIN = 80058E00
SDA>  DEFINE END = 80058E60
SDA>  EXAMINE BEGIN:END
 
 
      

In this example, DEFINE defines two addresses, called BEGIN and END. These symbols serve as reference points in memory, defining a range of memory locations for the EXAMINE command to inspect.

#2

SDA>  DEFINE NEXT = @PC
SDA>  EXAMINE/INSTRUCTION NEXT
NEXT:   HALT
      

The symbol NEXT defines the address contained in the program counter, so that the symbol can be used in an EXAMINE/INSTRUCTION command.

#3

SDA>  DEFINE VEC SCH$GL_PCBVEC
SDA>  EXAMINE VEC
SCH$GL_PCBVEC:  00000000.8060F2CC   "Ìò`....."
SDA> 
      

After the value of global symbol SCH$GL_PCBVEC has been assigned to the symbol VEC, the symbol VEC is used to examine the memory location or value represented by the global symbol.

#4

SDA>  DEFINE/PD VEC SCH$QAST
SDA>  EXAMINE VEC
SCH$QAST:  0000002C.00003008   ".0..,..."
SDA>  EXAMINE VEC_C
SCH$QAST_C:  B75E0008.43C8153E   ">.ÈC..^·"
SDA> 
 
      

In this example, the DEFINE/PD command defines not only the symbol VEC, but also the corresponding routine address symbol (VEC_C).


DEFINE/KEY

Associates an SDA command with a terminal key.

Once you have associated a command with a key, you can just press the defined key, followed by the Return key to issue the command. If you specify the /TERMINATE qualifier when you define the key, you do not have to press the Return key to issue the command.


Format

DEFINE/KEY [/qualifier...] key-name command


Parameters

key-name

Name of the key to be defined. You can define the following keys under SDA:
Key Name Key Designation
PF1 LK201, VT100
PF2 LK201, VT100
PF3 LK201, VT100
PF4 LK201, VT100
KP0...KP9 Keypad 0--9
PERIOD Keypad period
COMMA Keypad comma
MINUS Keypad minus
ENTER Keypad ENTER
UP Up arrow
DOWN Down arrow
LEFT Left arrow
RIGHT Right arrow
E1 LK201 Find
E2 LK201 Insert Here
E3 LK201 Remove
E4 LK201 Select
E5 LK201 Prev Screen
E6 LK201 Next Screen
HELP LK201 Help
DO LK201 Do
F7...F20 LK201 Function keys

command

SDA command to define a key. You must enclose the command in quotation marks (" ").

Qualifiers

/IF_STATE=state_list

/NOIF_STATE

Specifies a list of one or more states, one of which must be in effect for the key definition to work. The /NOIF_STATE qualifier has the same meaning as /IF_STATE=current_state. The state name is an alphanumeric string. States are established with the /SET_STATE qualifier. If you specify only one state name, you can omit the parentheses. By including several state names, you can define a key to have the same function in all the specified states.

/LOCK_STATE

/NOLOCK_STATE

Specifies that the state set by the /SET_STATE qualifier remains in effect until explicitly changed. By default, the /SET_STATE qualifier is in effect only for the next definable key you press or the next read-terminating character that you type. You can specify this qualifier only with the /SET_STATE qualifier.

The default is /NOLOCK_STATE.

/SET_STATE=state-name

/NOSET_STATE

Causes the key being defined to create a key state change instead of or in addition to issuing an SDA command. When you use the /SET_STATE qualifier, you supply the name of a key state to be used with the /IF_STATE qualifier in other key definitions.

For example, you can define the PF1 key as the GOLD key and use the /IF_STATE=GOLD qualifier to allow two definitions for the other keys, one in the GOLD state and one in the non-GOLD state. For more information on using the /IF_STATE qualifier, see the DEFINE/KEY command in the HP OpenVMS DCL Dictionary or online help.

The default is /NOSET_STATE.

/TERMINATE

/NOTERMINATE

Causes the key definition to include termination of the command, which causes SDA to execute the command when the defined key is pressed. Therefore, you do not have to press the Return key after you press the defined key if you specify the /TERMINATE qualifier.

Description

The DEFINE/KEY command causes an SDA command to be associated with the specified key, in accordance with any of the specified qualifiers described previously.

If the symbol or key is already defined, SDA replaces the old definition with the new one. Symbols and keys remain defined until you exit from SDA.


Examples

#1

SDA>  DEFINE/KEY PF1 "SHOW STACK"
SDA>  [PF1] SHOW STACK [RETURN]
Process stacks (on CPU 00)
-------------------------
Current operating stack (KERNEL):
   .
   .
   .
 
      

The DEFINE/KEY command defines PF1 as the SHOW STACK command. When you press the PF1 key, SDA displays the command and waits for you to press the Return key.

#2

SDA>  DEFINE/KEY/TERMINATE PF1 "SHOW STACK"
SDA>  [PF1] SHOW STACK
Process stacks (on CPU 00)
-------------------------
Current operating stack (KERNEL):
      00000000.7FF95D00  00000000.0000000B  
      00000000.7FF95D08  FFFFFFFF.804395C8  MMG$TBI_DATA_64+000B8
      00000000.7FF95D10  00000000.00000000  
      00000000.7FF95D18  0000FE00.00007E04  
SP => 00000000.7FF95D20  00000000.00000800  IRP$M_EXTEND
      00000000.7FF95D28  00000001.000002F7  UCB$B_PI_FKB+0000B
      00000000.7FF95D30  FFFFFFFF.804395C8  MMG$TBI_DATA_64+000B8
      00000000.7FF95D38  00000002.00000000  
   .
   .
   .
      

The DEFINE/KEY command defines PF1 as the SDA SHOW STACK command. The /TERMINATE qualifier causes SDA to execute the SHOW STACK command without waiting for you to press the Return key.

#3

SDA>  DEFINE/KEY/SET_STATE="GREEN" PF1 ""
SDA>  DEFINE/KEY/TERMINATE/IF_STATE=GREEN PF3 "SHOW STACK"
SDA>  [PF1] [PF3] SHOW STACK
Process stacks (on CPU 00)
-------------------------
Current operating stack (KERNEL):
   .
   .
   .
      

The first DEFINE/KEY command defines PF1 as a key that sets a command state GREEN. The trailing pair of quotation marks is required syntax, indicating that no command is to be executed when this key is pressed.

The second DEFINE command defines PF3 as the SHOW STACK command, but using the /IF_STATE qualifier makes the definition valid only when the command state is GREEN. Thus, you must press PF1 before pressing PF3 to issue the SHOW STACK command. The /TERMINATE qualifier causes the command to execute as soon as you press the PF3 key.


DUMP

Displays the contents of a range of memory formatted as a comma-separated variable (CSV) list, suitable for inclusion in a spreadsheet.

Format

DUMP range
[/BYTE | /WORD | /LONGWORD (default) | /QUADWORD]
[/DECIMAL | /HEXADECIMAL (default)]
[/FORWARD (default) | /REVERSE]
[/RECORD_SIZE=size ] (default = 512)
[/INDEX_ARRAY [= {LONGWORD (default) | QUADWORD} ] ]
[/INITIAL_POSITION = {ADDRESS=address | RECORD=number } ]
[/COUNT = {ALL | records } ] (default = all records)
[/PHYSICAL]
[/BYTE | /WORD |/NOSUPPRESS]


Parameter

range

The range of locations to be displayed. The range is specified in one of the following formats:
m:n Range from address m to address n inclusive
m;n Range from address m for n bytes

The length of the range must be an exact multiple of the data item size --- or of the index array size if /INDEX_ARRAY is specified.


Qualifiers

/BYTE

Outputs each data item as a byte.

/COUNT = [ {ALL | records} ]

Gives the number of records to be displayed. The default is to display all records.

/DECIMAL

Outputs data as decimal values.

/FORWARD

Causes SDA to display the records in the history buffer in ascending address order. This is the default.

/HEXADECIMAL

Outputs data as hexadecimal values. This is the default.

/INDEX_ARRAY [= {LONGWORD (default) | QUADWORD} ]

Indicates to SDA that the range of addresses given is a vector of pointers to the records to be displayed. The vector can be a list of longwords (default) or quadwords. The size of the range must be an exact number of longwords or quadwords as appropriate.

/INITIAL_POSITION = {ADDRESS=address | RECORD=number}

Indicates to SDA which record is to be displayed first. The default is the lowest addressed record if /FORWARD is used, and the highest addressed record if /REVERSE is used. The initial position may be given as a record number within the range, or the address at which the record is located.

/LONGWORD

Outputs each data item as a longword. This is the default.

/NOSUPPRESS

Indicates that SDA should not suppress leading zeroes when displaying data in hexadecimal format.

/PHYSICAL

Indicates to SDA that all addresses (range and/or start position) are physical addresses. By default, virtual addresses are assumed.

/QUADWORD

Outputs each data item as a quadword.

/RECORD_SIZE=size

Indicates the size of each record within the history buffer, the default being 512 bytes. This size must exactly divide into the total size of the address range to be displayed, unless you specify /INDEX_ARRAY. If no record size is given, and the length of the range is not more than 512 bytes, a single record is output containing the range specified, with no record number field. The length of the range must be an exact multiple of the data item size --- or of the index array size if /INDEX_ARRAY is specified.

/REVERSE

Causes SDA to display the records in the history buffer in descending address order.

/WORD

Outputs each data item as a word.

Description

The DUMP command displays the contents of a range of memory formatted as a comma-separated variable (CSV) list, suitable for inclusion in a spreadsheet. It is intended for use with a history buffer containing records of information of which the most recently written entry is in the middle of the memory range.

Note

See SET OUTPUT/NOHEADER for related information.

Examples

#1

SDA> DUMP dump g;200/initial_position=record=5/record_size=20/reverse
05,A77B0010,A79B0008,6B9C4001,47FF041F,A03E0000,47DF041C,201F0016,083
04,A03E0000,47DF041C,201F0058,083,A77B0010,A79B0008,6B9C4001,47FF041F
03,A03E0000,47DF041C,201F0075,083,A03E0000,47DF041C,201F001B,083
02,A77B0010,A79B0008,6B9C4001,47FF041F,A03E0000,47DF041C,201F0074,083
01,43E05120,083,6BFA8001,47FF041F,A77B0010,A79B0008,6B9C4001,47FF041F
0,201F0104,6BFA8001,47FF041F,47FF041F,201F0001,6BFA8001,47FF041F,47FF041F
0F,A03E0000,47DF041C,201F0065,083,A03E0000,47DF041C,201F0006,083
0E,A03E0000,47DF041C,201F001C,083,A03E0000,47DF041C,201F001A,083
0D,A03E0000,47DF041C,201F0077,083,A03E0000,47DF041C,201F0057,083
0C,A03E0000,47DF041C,201F002B,083,A03E0000,47DF041C,201F003A,083
0B,A03E0000,47DF041C,201F007D,083,A77B0010,A79B0008,6B9C4001,47FF041F
0A,A03E0000,47DF041C,201F005A,083,A03E0000,47DF041C,201F0078,083
09,A03E0000,47DF041C,201F0002,082,A03E0000,47DF041C,201F0037,083
08,A03E0000,47DF041C,201F0035,083,A03E0000,47DF041C,201F007A,083
07,A03E0000,47DF041C,201F0019,083,A03E0000,47DF041C,201F0034,083
06,A77B0010,A79B0008,6B9C4001,47FF041F,A03E0000,47DF041C,201F0018,083
      

This example shows the dump of an area of memory treated as 16 records of 32 bytes each, beginning at record 5, and dumped in reverse order. Note the record number in the first field, and that the dump wraps to the end of the memory area after the first record has been output.

#2

SDA> EXAMINE SMP$GL_CPU_DATA;80
00000000 00000000 8FE26000 8FE14000 00000000 00000000 8FE02000 811FE000  ...
00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000  ...
00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000  ...
00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000  ...
SDA> DUMP SMP$GL_CPU_DATA;80/index_array/record_size=20/count=5
0,810C17C0,8EC7C180,026A09C0,02,0,FFFFFFFF,0,0
01,810C17C0,8EC7C400,026A09C0,02,0,FFFFFFFF,0,01
04,810C17C0,8EC7CB80,026A09C0,02,0,FFFFFFFF,0,04
      

This example shows the contents of the CPU database vector, then dumps the first 32 bytes of each CPU database entry. Only the first five entries in the array are requested, and those containing zero are ignored.


Previous Next Contents Index