![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
Revision/Update Information: This manual supersedes the VMS System Dump Analyzer Utility Manual, Version 6.0.
Software Version: OpenVMS VAX Version 7.1
Digital Equipment Corporation Maynard, Massachusetts
Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.
Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.
© Digital Equipment Corporation 1996. All rights reserved.
The following are trademarks of Digital Equipment Corporation: Bookreader, DECdtm, DECnet, DECUS, DECwindows, Digital, IAS, MASSBUS, OpenVMS, OpenVMS Cluster TMSCP, VAX, VAX DOCUMENT, VAXcluster, VMS, VMScluster, and the DIGITAL logo.
The following is a third-party trademark:
Adobe is a registered trademark of Adobe Systems Incorporated.
All other trademarks and registered trademarks are the property of their respective holders.
ZK4556
The OpenVMS documentation set is available on CD-ROM.
The OpenVMS VAX System Dump Analyzer Utility Manual is primarily intended for the system programmer who must investigate the causes of system failures and debug kernel-mode code, such as a device driver. This programmer should have some knowledge of OpenVMS data structures to properly interpret the results of System Dump Analyzer (SDA) commands.
This manual also includes information required by the system manager in order to maintain the system resources necessary to capture and store system crash dumps. Those who need to determine the cause of a hung process or improve system performance can refer to this manual for instructions for using SDA to analyze a running system.
The OpenVMS VAX System Dump Analyzer Utility Manual contains the following sections:
| Section | Description of Contents |
|---|---|
| SDA Description |
Includes the following information:
This section also includes instructions for maintaining the optimal environment for the analysis of system failures and notes the requirements for processes invoking SDA. |
| SDA Usage Summary | Summarizes how to use SDA, including invoking SDA, exiting from SDA, and recording the output of an SDA session. It also describes required privileges. |
| SDA Qualifiers | Describes ANALYZE command qualifiers that govern the behavior of SDA: /CRASH_DUMP, /RELEASE, /SYMBOL, and /SYSTEM. |
| SDA Commands |
Describes each SDA command; descriptions include the following
information about each command:
This section also provides examples of situations in which specific commands are useful. |
For additional information, refer to the following documents:
Investigators of VMScluster failures will find the discussion in OpenVMS Cluster Systems and the discussion of the Show Cluster utility in the OpenVMS System Management Utilities Reference Manual helpful in understanding the output of several SDA commands.
For additional information on the Open Systems Software Group (OSSG) products and services, access the Digital OpenVMS World Wide Web site. Use the following URL:
http://www.openvms.digital.com
Digital welcomes your comments on this manual.
Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
| Internet | openvmsdoc@zko.mts.dec.com |
| Fax | 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08 |
|
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd. Nashua, NH 03062-2698 |
Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).
The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonym ous with OpenVMS Alpha or Alpha.
VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.
In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.
The following conventions are also used in this manual:
| Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. |
|
PF1
x or
GOLD x |
A sequence such as PF1
x or GOLD
x indicates that you must first press and release the key
labeled PF1 or GOLD and then press and release another key or a
pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands. |
| [Return] | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) |
| ... |
Horizontal ellipsis points in examples indicate one of the following
possibilities:
|
|
.
. . |
Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed. |
| ( ) | In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. |
| [ ] | In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.) |
| [|] | In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or all of the options. |
| { } | In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed. |
| {|} | In command format descriptions, vertical bars separating items inside braces indicate that you choose one item from among those listed. |
| text style |
This text style represents the introduction of a new term or the name
of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual. |
| italic text | Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters). |
| UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
| Monospace type |
Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example. |
| - | A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line. |
| numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated. |
When a fatal error causes the system to fail, the operating system copies the contents of memory to a system dump file; the system also records the hardware context of each processor in the system.
The System Dump Analyzer (SDA) provides a means of interpreting the contents of the system dump file, thus enabling you to examine the status of each processor at the time of the failure and to investigate the probable causes of the crash.
To examine the system dump file, you invoke SDA by using the DCL command ANALYZE/CRASH_DUMP. You can also invoke SDA to analyze a running system, using the DCL command ANALYZE/SYSTEM. Most SDA commands generate useful output in this mode of operation.
Caution
Although the analysis of a running system might be instructive, be aware that system context, process context, and a processor's hardware context remain fluid during any given display. In a multiprocessing environment, a process running SDA might be rescheduled to a different processor frequently during analysis. Therefore, Digital recommends that you not examine the hardware context of processors in a running system.
Following are brief explanations of SDA qualifiers. Details about these qualifiers are in the SDA Qualifiers section.
| Qualifier | Description |
|---|---|
| /CRASH_DUMP | Invokes SDA to analyze a specified dump file |
| /RELEASE | Invokes SDA to release those blocks that are occupied by a crash dump in a specified system paging file |
| /SYMBOL | Specifies a system symbol table for SDA to use in place of the system symbol table it uses by default (SYS$SYSTEM:SYS.STB) |
| /SYSTEM | Invokes SDA to analyze a running system |
The following tables show the SDA commands that you can use to perform operations within the SDA utility. These commands are in groups of related information. Details about SDA commands are in the SDA Commands section.
Table SDA-1 describes information that you can select and display about processes.
| Operation | SDA Command |
|---|---|
| Display the condition of the operating system and the hardware context of each processor in the system at the time of a crash | SHOW CRASH |
| Display a summary of all processes on the system | SHOW SUMMARY |
| Select a process to become the SDA current process | SET PROCESS |
| Examine the memory of any process | SHOW PROCESS |
| Select a specific processor in a multiprocessing system as the subject of analysis | SET CPU |
| Display information about the state of a processor at the time of the system failure | SHOW CPU |
| Display multiprocessor synchronization information | SHOW SPINLOCKS |
| Display the contents of a specific process stack or the interrupt stack of a specific processor | SHOW STACK |
| Display the layout of the loadable executive images | SHOW EXECUTIVE |
Table SDA-2 describes information that you can display about data structures.
| Operation | SDA Command |
|---|---|
| Display memory management data structures |
SHOW POOL,
SHOW PFN_DATA, SHOW PAGE_TABLE |
| Display device status, as reflected in system data structures | SHOW DEVICE |
| Display OpenVMS RMS data structures of a process | SHOW PROCESS/RMS |
| Display lock management data structures |
SHOW RESOURCE,
SHOW LOCK |
| Display information contained in various local area network (LAN) data structures | SHOW LAN |
| Display VAXcluster management data structures |
SHOW CLUSTER,
SHOW CONNECTIONS, SHOW RSPID, SHOW PORTS |
Table SDA-3 describes SDA commands that you can use to examine, evaluate, and validate information.
| Operation | SDA Command |
|---|---|
| Evaluate an expression in hexadecimal and decimal, interpreting its value as a symbol, a condition value, a page table entry (PTE), or a processor status longword (PSL) | EVALUATE |
| Examine the contents of memory locations, optionally interpreting them as MACRO instructions, a PTE, or a PSL | EXAMINE |
| Validate the integrity of the links in a queue | VALIDATE QUEUE |
Table SDA-4 describes the SDA commands that you can use to search for, format, and copy information.
| Operation | SDA Command |
|---|---|
| Search memory for a given value | SEARCH |
| Format system data structures | FORMAT |
| Format a call frame from a stack location | SHOW CALL_FRAME |
| Copy the system dump file | COPY |
Table SDA-5 describes the operations you can perform to manage the SDA utility and the SDA symbol table.
| Operation | SDA Command |
|---|---|
| Define keys to invoke SDA commands | DEFINE/KEY |
| Switch control of your terminal from your current process to another process in your job | ATTACH |
| Direct (or echo) the output of an SDA session to a file or device |
SET OUTPUT or
SET LOG |
| Repeat execution of the last command issued | REPEAT |
| Create a subprocess of the process currently running SDA | SPAWN |
| Change the options shown by the SHOW PROCESS/RMS command | SET RMS |
| Define symbols to represent values or locations in memory and add them to the SDA symbol table | DEFINE |
| Read a set of global symbols into the SDA symbol table | READ |
| Display the hexadecimal value of a symbol and, if the value is equal to an address location, the contents of that location | SHOW SYMBOL |
| Exit from the SDA display or from the SDA utility | EXIT |
Table SDA-6 describes the commands that you can use to display information produced by DECdtm.
| Operation | SDA Command |
|---|---|
| Display information about all transactions on the node or about a specified transaction | SHOW TRANSACTIONS |
| Display information about transaction logs currently open for the node | SHOW LOGS |
Although SDA provides a great deal of information, it does not analyze
all the control blocks and data contained in memory. For this reason,
in the event of system failure it is extremely important that you send
Digital Equipment Corporation a Software Performance Report (SPR) and a
copy of the system dump file written at the time of the failure.
2 System Management and SDA
The system manager must perform the following operations in regard to the system dump file:
The following sections describe these tasks.
2.1 Understanding the System Dump File
The operating system attempts to write information into the system dump file only if the system parameter DUMPBUG is set. ¹ If DUMPBUG is set and the operating system fails, the system writes the contents of the error log buffers, processor registers, and physical memory into the system dump file, overwriting its previous contents.
If the system dump file is too small, it cannot contain all of memory
when a system failure occurs. For most systems, this means that the
system's page table (SPT) is not included in the dump. SDA cannot
analyze a dump unless the entire SPT is included in the dump.
2.1.1 Choosing Between SYSDUMP.DMP and PAGEFILE.SYS Files
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 slective 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
Caution
This formula calculates only the minimum size requirement for saving a dump in the system's primary page file. For most systems, the page file must be larger than this to avoid hanging the system. (See the OpenVMS System Manager's Manual: Essentials and OpenVMS System Manager's Manual: Tuning, Monitoring, and Complex Systems for more information.)
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
Note
The ANALYZE/CRASH_DUMP/RELEASE command does not allow you to analyze the dump before deleting it.
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.
| 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. |
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
4556P.HTM OSSG Documentation 22-NOV-1996 14:13:01.70
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.