 |
OpenVMS VAX System Dump Analyzer Utility Manual
OpenVMS VAX System Dump Analyzer Utility Manual
Order Number:
AA--PV6TD--TE
April 2001
This manual explains how to use the System Dump Analyzer (SDA) to
investigate system failures and examine a running system.
Revision/Update Information:
This manual supersedes the VMS System Dump Analyzer Utility Manual, Version 6.0
Software Version:
OpenVMS VAX Version 7.3
Compaq Computer Corporation Houston, Texas
© 2001 Compaq Computer Corporation
Compaq, AlphaServer, VAX, VMS, and the Compaq logo Registered in U.S.
Patent and Trademark Office.
OpenVMS, Alpha, and DECdirect are trademarks of Compaq Information
Technologies Group, L.P. in the United States and other countries.
UNIX and X/Open are trademarks of The Open Group in the United States
and other countries.
All other product names mentioned herein may be the trademarks of their
respective companies.
Confidential computer software. Valid license from Compaq required for
possession, use, or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
Compaq shall not be liable for technical or editorial errors or
omissions contained herein. The information in this document is
provided "as is" without warranty of any kind and is subject to change
without notice. The warranties for Compaq products are set forth in the
express limited warranty statements accompanying such products. Nothing
herein should be construed as constituting an additional warranty.
ZK4556
The Compaq OpenVMS documentation set is available on CD-ROM.
Preface
Intended Audience
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.
Document Structure
The OpenVMS VAX System Dump Analyzer Utility Manual contains the following sections:
| Section |
Description of Contents |
|
SDA Description
|
Includes the following information:
- An introduction to the functions of the System Dump Analyzer (SDA)
- A description of SDA features
- A discussion of key concepts of SDA
- An illustration of the use of SDA
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:
- Function
- Format
- Parameters
This section also provides examples of situations in which specific
commands are useful.
|
Related Documents
Additional information is available in the following documents:
- OpenVMS System Manager's Manual, Volume 1: Essentials
- OpenVMS System Manager's Manual, Volume 2: Tuning, Monitoring, and Complex Systems
- OpenVMS System Management Utilities Reference Manual
- Guide to Creating OpenVMS Modular Procedures
- OpenVMS Performance Management
- OpenVMS VAX Device Support Manual1
- OpenVMS DCL Dictionary
- OpenVMS System Services Reference Manual
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 about Compaq OpenVMS products and
services, access the Compaq website at the following location:
http://www.openvms.compaq.com/
|
Note
1 This manual has been archived but is
available on the OpenVMS Documentation CD-ROM.
|
Reader's Comments
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
|
Internet
|
openvmsdoc@compaq.com
|
|
Mail
|
Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
|
How To Order Additional Documentation
Use the following World Wide Web address to order additional
documentation:
http://www.openvms.compaq.com/
|
If you need help deciding which documentation best meets your needs,
call 800-282-6672.
Conventions
The following conventions are 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
|
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
button.
|
|
[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.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
|
|
...
|
A horizontal ellipsis in examples indicates one of the following
possibilities:
- Additional optional arguments in a statement have been omitted.
- The preceding item or items can be repeated one or more times.
- Additional parameters, values, or other information can be entered.
|
.
.
.
|
A vertical ellipsis indicates 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 you must
enclose choices in parentheses if you choose more than one.
|
|
[ ]
|
In command format descriptions, brackets indicate optional choices. You
can choose one or more items or no items. Do not type the brackets on
the command line. However, you must include the brackets in the syntax
for OpenVMS directory specifications and for a substring specification
in an assignment statement.
|
|
|
|
In command format descriptions, vertical bars separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
|
|
{ }
|
In command format descriptions, braces indicate required choices; you
must choose at least one of the items listed. Do not type the braces on
the command line.
|
|
bold text
|
This typeface represents the introduction of a new term. It also
represents the name of an argument, an attribute, or a reason.
|
|
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
dd represents the predefined code for the device type).
|
|
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 text
|
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.
|
SDA Description
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, Compaq 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.
Table SDA-1 Selecting and Displaying Information 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.
Table SDA-2 Displaying Information 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.
Table SDA-3 Examining, Evaluating, and Validating 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.
Table SDA-5 describes the operations you can perform to manage the SDA
utility and the SDA symbol table.
Table SDA-5 Managing 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.
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
Compaq a Software Performance Report (SPR) and a copy of the system
dump file written at the time of the failure.
1 System Management and SDA
The system manager must perform the following operations in regard to
the system dump file:
- Ensure that the system writes a dump file whenever the system fails.
- Ensure that the dump file is large enough to contain all the
information to be saved.
- Ensure that the dump file is saved for analysis.
The following sections describe these tasks.
1.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. 1 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.
1.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.2
Do not 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
|
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, Volume 1: Essentials and OpenVMS System Manager's Manual, Volume 2: 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.
Note
The ANALYZE/CRASH_DUMP/RELEASE command does not allow you to analyze
the dump before deleting it.
|
Note
1 The DUMPBUG parameter is set by
default. To examine or change its value, consult the OpenVMS System Management Utilities Reference Manual.
2 The SAVEDUMP parameter is clear by
default. To examine or change its value, consult the OpenVMS System Management Utilities Reference Manual.
|
|
