Updated: 11 December 1998

OpenVMS VAX System Dump Analyzer Utility Manual

SYS$SYSTEM:SYSDUMP.DMP (SYS$SPECIFIC:[SYSEXE]SYSDUMP.DMP) is furnished as an empty file in the software distribution kit. To successfully store a crash dump, you must make SYS$SYSTEM:SYSDUMP.DMP large enough to hold all the information to be written when the system fails. If this is not possible, you can have dumps written into the system paging file, SYS$SYSTEM:PAGEFILE.SYS. You can enlarge or adjust the size of either of these files by using the CREATE command of the System Generation utility (SYSGEN), as described in the OpenVMS System Management Utilities Reference Manual.

Using SYSDUMP.DMP

To calculate the correct size for SYS$SYSTEM:SYSDUMP.DMP, use the following formula:

size-in-blocks(SYS$SYSTEM:SYSDUMP.DMP) = size-in-pages(physical-memory) + (number-of-error-log-buffers * blocks-per-buffer) + 1

You can use the DCL command SHOW MEMORY to determine the total size of physical memory on your system. In addition, you must account for any MA780 multiport memory installed on your system. The number of error log buffers in any given system varies, depending on the setting of the ERRORLOGBUFFERS system parameter. (See the OpenVMS System Management Utilities Reference Manual for additional information about this parameter.)

Using PAGEFILE.SYS

If SYS$SYSTEM:SYSDUMP.DMP does not exist, the operating system writes the dump of physical memory into SYS$SYSTEM:PAGEFILE.SYS, the system's paging file, overwriting the contents of that file. If the SAVEDUMP system parameter is set, the dump file is retained in PAGEFILE.SYS when the system is booted. If it is clear, the entire paging file is used for paging, and any dump written to the paging file is lost.²

It is not recommended to use a selective dump (DUMPSTYLE=1) style with PAGEFILE.SYS. If the PAGEFILE is used for a selective dump, and if the PAGEFILE is not large enough to contain all the logical memory blocks, the dump fills the entire pagefile and the system may hang on reboot. When selective dumping is setup, all available space will be used to write out the logical memory blocks. If the pagefile is large enough to contain all of physical memory, there is no reason to use selective dumping and a full memory dump (DUMPSTYLE=0) should be used.

To calculate the minimum size for SYS$SYSTEM:PAGEFILE.SYS, use the following formula:

size-in-blocks(SYS$SYSTEM:PAGEFILE.SYS) = size-in-pages(physical-memory) + (number-of-error-log-buffers * blocks-per-buffer) + 1 + 1000

Freeing Space in PAGEFILE.SYS

If you use SYS$SYSTEM:PAGEFILE.SYS to hold system crash dumps, you must later free the space occupied by the dump so that the pager can use it. Usually, you include SDA commands in the site-specific startup command procedure (SYS$MANAGER:SYSTARTUP_VMS.COM) to free this space; if you do not, your system might hang during the startup procedure.

A common method of freeing space is to copy the dump from SYS$SYSTEM:PAGEFILE.SYS to another file, using the SDA COPY command. (Although you can also use the DCL COPY command to copy a dump file, only the SDA COPY command frees the pages occupied by the dump from the system's paging file.)

Occasionally, you might want to free the pages in the paging file that are taken up by the dump without having to copy the dump elsewhere. When you issue the ANALYZE/CRASH_DUMP/RELEASE command, SDA immediately releases the pages to be used for system paging, effectively deleting the dump. to examine

In certain system configurations, it might be impossible to preserve the entire contents of memory in a disk file. For instance, a large memory system or a system with small disk capacity might not be able to supply enough disk space for a full memory dump. In normal circumstances, if the system dump file cannot accommodate all of memory, SDA cannot analyze the dump.

To preserve those portions of memory that contain information most useful in determining the causes of system failures, a system manager sets the static system parameter DUMPSTYLE to 1. When the DUMPSTYLE parameter is set, AUTOGEN attempts to create a dump file large enough to contain ample information for SDA to analyze a failure. When the DUMPSTYLE parameter is clear (the default), AUTOGEN attempts to create a dump file large enough to contain all of physical memory.

A comparison of full and subset style dump files appears in Table SDA-7.

Table SDA-7 Comparison of Full and Subset Dump Files

	Full	Subset
Available Information	Complete contents of physical memory in use, stored in order of increasing physical address (for instance, system and global page tables are stored last).	System page table, global page table, system space memory, and process and control regions (plus global pages) for all saved processes.
Unavailable Information	Contents of paged-out memory at the time of the crash.	Contents of paged-out memory at the time of the crash, process and control regions of unsaved processes, and memory not mapped by a page table (such as the free and modified lists).
SDA Command Limitations	None.	The following commands are not useful for unsaved processes: SHOW PROCESS/CHANNELS, SHOW PROCESS/RMS, SHOW STACK, and SHOW SUMMARY/IMAGE.

1.2 Saving System Dumps

Every time the operating system writes information to the system dump file, it writes over whatever was previously stored in the file. For this reason, as system manager, you need to save the contents of the file after a system failure has occurred.

Using the SDA COPY Command

You can use the SDA COPY command or the DCL COPY command in your site-specific startup procedure. Digital recommends using the SDA COPY command because it marks the dump file as copied. This is particularly important if the dump was written into the paging file, SYS$SYSTEM:PAGEFILE.SYS, because the SDA COPY command releases to the pager the pages that were occupied by the dump.

Using /IGNORE=NOBACKUP

Because system dump files are set to NOBACKUP, the Backup utility (BACKUP) does not copy dump files to tape unless you use the qualifier /IGNORE=NOBACKUP when invoking BACKUP. When you use the SDA COPY command to copy the system dump file to another file, the new file is not set to NOBACKUP.

As included in the distribution kit, SYS$SYSTEM:SYSDUMP.DMP is protected against world access. Because a dump file can contain privileged information, Digital recommends that you continue to protect dump files from universal read access.

1.3 Invoking SDA in the Site-Specific Startup Command Procedure

Because a listing of the SDA output is an important source of information in determining the cause of a system failure, it is a good idea to have SDA produce such a listing after every failure. The system manager can ensure the creation of a listing by modifying the site-specific startup command procedure SYS$MANAGER:SYSTARTUP_VMS.COM so that it invokes SDA when the system is booted.

When invoked in the site-specific startup procedure, SDA executes the specified commands only if the system is booting immediately after a system failure. SDA examines a flag in the dump file's header that indicates whether it has already processed the file. If the flag is set, SDA merely exits. If the flag is clear, SDA executes the specified commands and sets the flag. This flag is clear when the operating system initially writes a crash dump, except for those resulting from an operator-requested shutdown (for instance, SYS$SYSTEM:SHUTDOWN.COM).

Using SYSDUMP.DMP

The following example shows typical commands that you might add to your site-specific startup command procedure to produce an SDA listing after each failure.

$ ! $ ! Print dump listing if system just failed $ ! $ ANALYZE/CRASH_DUMP SYS$SYSTEM:SYSDUMP.DMP COPY SYS$SYSTEM:SAVEDUMP.DMP ! Save dump file SET OUTPUT DISK1:SYSDUMP.LIS ! Create listing file READ/EXEC ! Read symbols into the SDA symbol table SHOW CRASH ! Display crash information SHOW STACK ! Show current stack SHOW SUMMARY ! List all active processes SHOW PROCESS/PCB/PHD/REG ! Display current process SHOW SYMBOL/ALL ! Print system symbol table EXIT $ PRINT DISK1:SYSDUMP.LIS

The COPY command in the preceding example saves the contents of the file SYS$SYSTEM:SYSDUMP.DMP. If your system's startup command file does not save a copy of the contents of this file, this crash dump information is lost in the next system failure, when the system saves the information about the new failure, overwriting the contents of SYS$SYSTEM:SYSDUMP.DMP.

Using PAGEFILE.SYS

If you are using the SYS$SYSTEM:PAGEFILE.SYS as the crash dump file, you must include SDA commands in SYS$MANAGER:SYSTARTUP_VMS.COM that free the space occupied by the dump so that the pager can use it. For instance:

$ ANALYZE/CRASH_DUMP SYS$SYSTEM:PAGEFILE.SYS . . . COPY dump_filespec EXIT

2 Analyzing a System Dump

SDA performs certain tasks prior to bringing a dump into memory, presenting its initial displays, and accepting command input. This section describes those tasks, which include the following:

• Verifying that the process invoking it has privileges to read the dump file
• Using RMS to read in pages upon request
• Reading the system symbol tables (SYS$SYSTEM:SYS.STB and SYS$SYSTEM:REQSYSDEF.STB)
• Executing the commands in the SDA initialization file

For detailed information about the investigation of a system failure, see Section 8.

Requirements

To be able to analyze a dump file, your process must have the following:

• Read access to the file that contains the dump and to copies of the following symbol tables, which SDA reads by default:
  • SYS$SYSTEM:SYS.STB (the system symbol table)
  • SYS$SYSTEM:REQSYSDEF.STB (the required subset of the symbols in the file SYSDEF.STB)
• A system UIC or SYSPRV privilege for a process to read the dump file.
  As included in the distribution kit, SYS$SYSTEM:SYSDUMP.DMP, SYS$SYSTEM:SYS.STB, and SYS$SYSTEM:REQSYSDEF.STB are protected against world access.
• Sufficient virtual address space for SDA to access the entire dump and any required symbol tables.
  To ensure that SDA has the correct amount of virtual address space, a value of 16,000 of the system parameter VIRTUALPAGECNT should be sufficient to analyze any dump, unless there is an exceptionally large number of symbols. You might need to increase the size if your particular installation places heavy demands on the virtual address space of the process.

If your process satisfies these conditions, you can issue the DCL command ANALYZE/CRASH_DUMP to invoke SDA. If you do not specify the name of a dump file in the command, SDA prompts you for the name of the file, as follows:

$ ANALYZE/CRASH_DUMP _Dump File:

The default file specification is as follows:

disk:[default-dir]SYSDUMP.DMP

disk and [default-dir] represent the disk and directory specified in your last SET DEFAULT command.

2.2 Mapping the Contents of the Dump File

SDA first attempts to map the contents of physical memory as stored in the specified dump file. To do this, it must first locate the system page table (SPT) among its contents. The SPT contains one entry for each page of system virtual address space.

The SPT appears at the largest physical addresses in a typical configuration. As a result, if a dump file is too small, the SPT cannot be written to it in the event of system failure.

If SDA cannot find the SPT in the dump file, it displays either of the following messages:

%SDA-E-SPTNOTFND, system page table not found in dump file

%SDA-E-SHORTDUMP, the dump only contains m out of n pages of physical memory

If SDA displays either of these error messages, you cannot analyze the crash dump, but must take steps to ensure that any subsequent dump can be preserved. To do this, you must increase the size of the dump file, as indicated in Section 1.1, or adjust the system DUMPSTYLE parameter, as discussed in Section 1.1.2.

Under certain conditions, the system might not save some memory locations in the system dump file. For instance, during halt/restart bugchecks, the system does not preserve the contents of general registers. If such a bugcheck occurs, SDA indicates in the SHOW CRASH display that the contents of the registers were destroyed. Additionally, if a bugcheck occurs during system initialization, the contents of the register display might be unreliable. The symptom of such a bugcheck is a SHOW SUMMARY display that shows no processes or only the swapper process.

Also, if you use an SDA command to access a virtual address that has no corresponding physical address, SDA displays the following error message:

%SDA-E-NOTINPHYS, 'location' not in physical memory

When you analyze a subset dump file, if you use an SDA command to access a virtual address that has a corresponding physical address but was not saved in the dump file, SDA displays the following error message:

%SDA-E-MEMNOTSVD, memory not saved in the dump file

2.3 Building the SDA Symbol Table

After locating and reading the system dump file, SDA attempts to read the system symbol table file into the SDA symbol table. This file, named SYS$SYSTEM:SYS.STB by default, contains most of the global symbols used by the operating system. SDA also reads into its symbol table a subset of SYS$SYSTEM:SYSDEF.STB, called SYS$SYSTEM:REQSYSDEF.STB, that it requires to identify locations in memory.

If SDA cannot find the system symbol table file, or if it is given a file that is not a system symbol table in the /SYMBOL qualifier to the ANALYZE command, it halts with a fatal error.

When SDA finishes building its symbol table, it displays a message identifying itself and the immediate cause of the crash. In the following example, the cause of the crash was an illegal exception occurring at an IPL above IPL$_ASTDEL or while using the interrupt stack.

Dump taken on 28-Jan-1993 18:10:09.79 INVEXCEPTN, Exception while above ASTDEL or on interrupt stack

2.4 Executing the SDA Initialization File (SDA$INIT)

After displaying the crash summary, SDA executes the commands in the SDA initialization file, if you have established one. SDA refers to its initialization file by using the logical name SDA$INIT. If SDA cannot find the file defined as SDA$INIT, it searches for the file SYS$LOGIN:SDA.INIT.

The initialization file can contain SDA commands that read symbols into SDA's symbol table, define keys, establish a log of SDA commands and output, or perform other tasks. For instance, you might want to use an SDA initialization file to augment SDA's symbol table with definitions helpful in locating system code.

If you issue the following command, SDA includes those symbols that define many of the system's data structures, including those in the I/O database:

READ SYS$SYSTEM:SYSDEF.STB

You might also find it very helpful to define those symbols that identify the modules in the images that make up the executive. You can do this by issuing the following command:

READ/EXECUTIVE SYS$LOADABLE_IMAGES

After SDA executes the commands in the initialization file, it displays its prompt, as follows:

SDA>

The SDA> prompt indicates that you can use SDA interactively and enter SDA commands.

An SDA initialization file can invoke a command procedure with the @ command. However, such command procedures cannot themselves invoke a command procedure (that is, you cannot have nested command procedures).

3 Analyzing a Running System

Occasionally, an internal problem hinders system performance but does not cause a system failure. By allowing you to examine the running system, SDA provides the means to search for the solution to the problem without disturbing the operating system. For example, you can use SDA to examine the stack and memory of a process that is stalled in a scheduler state, such as a miscellaneous wait (MWAIT) or a suspended (SUSP) state (see the Guide to OpenVMS Performance Management).

If your process has change-mode-to-kernel (CMKRNL) privilege, you can invoke SDA to examine the system. Use the following DCL command:

$ ANALYZE/SYSTEM

SDA then does the following:

1. Attempts to load the system symbol table (SYS$SYSTEM:SYS.STB) and symbol table SYS$SYSTEM:REQSYSDEF.STB.
2. Executes the contents of any existing SDA initialization file, as it does when invoked to analyze a crash dump (see Sections 2.3 and 2.4, respectively).
3. Displays its identification message and prompt, as follows:

   OpenVMS System analyzer SDA>

The SDA> prompt indicates that you can use SDA interactively and enter SDA commands. When analyzing a running system, SDA sets its process context to that of the process running SDA.

If you are undertaking an analysis of a running system, take the following considerations into account:

• When used in this mode, SDA does not map the entire system but instead retrieves only the information it needs to process each individual command. To update any given display, you must reissue the previous command.

  Caution When using SDA to analyze a running system, use caution in interpreting its displays. Because system states change frequently, it is possible that the information SDA displays might be inconsistent with the actual, volatile state of the system at any given moment.

• Certain SDA commands are illegal in this mode, such as SHOW CPU and SET CPU. If you use these commands, SDA displays the following error message:

  %SDA-E-CMDNOTVLD, command not valid on the running system

• The SHOW CRASH command, although valid, does not display the contents of any of the processor's set of hardware registers. Also, the "Time of system crash" information refers to the time you entered the ANALYZE/SYSTEM command.

When invoked to analyze either a crash dump or a running system, SDA establishes a default context from which it interprets certain commands.

When the subject of analysis is a uniprocessor system, SDA's context is solely process context. That is, SDA can interpret its process-specific commands in the context of either the process current on the uniprocessor or some other process in some other scheduling state.

When you initially invoke SDA to analyze a crash dump, its process context defaults to that of the process that was current at the time of the crash. When you invoke SDA to analyze a running system, its process context defaults to that of the current process; that is, the one executing SDA.

You can change SDA's process context by issuing any of the following commands:

• SET PROCESS/INDEX=nn
• SET PROCESS name
• SHOW PROCESS/INDEX=nn

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4556PRO_001.HTML