Document revision date: 19 July 1999

On VAX systems, writing the DOSD has the following requirements:

• The system must be connected directly to, and must boot from, CI controllers.
• The dump device must physically connect to the same two HSx CI controllers as the boot device.
• The dump device directory structure must resemble the current system disk structure. The [SYSn.SYSEXE]SYSDUMP.DMP file will reside there, with the same boot time system root.
  Use AUTOGEN to create this file. In the MODPARAMS.DAT file, the following symbol prompts AUTOGEN to create the file:

  DUMPFILE_DEVICE = $nnn$ddcuuuu

  
  You can list only one device.

• The volume label can be up to 12 characters long. The ASCII string DOSD_DUMP must be part of this volume label. For example, valid volume labels are DOSD_DUMP, DOSD_DUMP_12, 12_DOSD_DUMP. The label is read and retained in a memory boot data structure.
• The dump device cannot be part of a volume set. Compaq strongly recommends that the dump device also not be part of a shadow set.
• The dump device cannot be MSCP unit zero (0); only units 1 to 4095 (1---FFF) are supported.
  You can designate the dump device as follows:
  • On VAX 7000 configurations, by using bits 16 through 27 of the DUMPSTYLE system parameter.
  • On configurations other than the VAX 7000, by using bits 16 through 27 of register 3 (R3). You can use this portion of the register to specify the dump device.
  
  The OpenVMS System Management Utilities Reference Manual and online help contain details about the DUMPSTYLE system parameter.

The System Dump Analyzer utility (SDA) lets you interpret the contents of the system dump file to investigate the probable causes of the crash. For information about analyzing a crash dump, refer to the OpenVMS VAX System Dump Analyzer Utility Manual or the OpenVMS Alpha System Dump Analyzer Utility Manual.

If your system fails, make a copy of the system dump file written at the time of the failure and contact your Compaq support representative. For information about copying the system dump file, see Section 15.11.

15.8 Using SDA CLUE Commands to Analyze Crash Dump Files (Alpha Only)

SDA CLUE (Crash Log Utility Extractor) commands automate the analysis of crash dumps and maintain a history of all fatal bugchecks on a standalone system or cluster. You can use SDA CLUE commands in conjunction with SDA to collect and decode additional dump file information not readily accessible through standard SDA. You can also use SDA CLUE with Dump Off System Disk (DOSD) to analyze a system dump file that resides on a disk other than the system disk.

15.8.1 Understanding CLUE (Alpha Only)

On Alpha systems, SDA is automatically invoked by default when you reboot the system after a system failure. To better facilitate crash dump analysis, SDA CLUE commands automatically capture and archive summary dump file information in a CLUE listing file.

A startup command procedure initiates commands that:

• Invoke SDA
• Issue an SDA CLUE HISTORY command
• Create a listing file called CLUE$nodename_ddmmyy_hhmm.LIS

The CLUE HISTORY command adds a one-line summary entry to a history file and saves the following output from SDA CLUE commands in the listing file:

• Crash dump summary information
• System configuration
• Stack decoder
• Page and swap files
• Memory management statistics
• Process DCL recall buffer
• Active XQP processes
• XQP cache header

The contents of this CLUE list file can help you analyze a system failure.

If these files accumulate more space than the threshold allows (default 5000 blocks), the oldest files are deleted until the threshold limit is reached. This can also be customized using the CLUE$MAX_BLOCK logical name.

To inhibit the running of CLUE at system startup, define the logical CLUE$INHIBIT in the SYLOGICALS.COM file as /SYS TRUE.

It is important to remember that CLUE$nodename_ddmmyy_hhmm.LIS contains only an overview of the crash dump and does not always contain enough information to determine the cause of the crash. If you must do an in-depth analysis of the system crash, Compaq recommends that you always use the SDA COPY command to save the dump file.

15.8.2 Displaying Data Using SDA CLUE Commands (Alpha Only)

Invoke CLUE commands at the SDA prompt as follows:

SDA> CLUE CONFIG

CLUE commands provide summary information of a crash dump captured from a dump file. When debugging a crash dump interactively, you can use SDA CLUE commands to collect and decode some additional information from a dump file, which is not easily accessible through standard SDA. For example, CLUE can quickly provide detailed XQP summaries.

You can also use CLUE commands interactively on a running system to help identify performance problems.

You can use all CLUE commands when analyzing crash dumps; the only CLUE commands that are not allowed when analyzing a running system are CLUE CRASH, CLUE ERRLOG, CLUE HISTORY, and CLUE STACK.

Refer to OpenVMS Alpha System Dump Analyzer Utility Manual for more information about using SDA CLUE commands.

15.8.3 Using SDA CLUE with Dump Off System Disk (Alpha Only)

Dump off system disk (DOSD) allows you to write the system dump file to a device other than the system disk. For SDA CLUE to be able to correctly find the dump file to be analyzed after a system crash, you need to perform the following steps:

1. Modify the command procedure SYS$MANAGER:SYLOGICALS.COM to add the system logical name CLUE$DOSD_DEVICE to point to the device where the dump file resides. You need to supply only the physical or logical device name without a file specification.
2. Modify the command procedure SYS$MANAGER:SYLOGICALS.COM to mount systemwide the device where the dump file resides. Otherwise, SDA CLUE cannot access and analyze the dump file.

In the following example, the dump file is placed on device $3$DUA25, with the label DMP$DEV. You need to add the following commands to SYS$MANAGER:SYLOGICALS.COM:

$mount/system/noassist $3$dua25: dmp$dev dmp$dev $define/system clue$dosd_device dmp$dev

15.9 Using CLUE to Obtain Historical Information About Crash Dumps (VAX Only)

On VAX systems, the Crash Log Utility Extractor (CLUE) displays the contents of a crash history file. By examining the contents of the crash history file, you can understand and resolve the issues responsible for failures (crashes), and you might also obtain other useful data.

15.9.1 Understanding CLUE (VAX Only)

The crash history file, which is created and updated by CLUE, contains key parameters from crash dump files. Unlike crash dumps, which are overwritten with each system failure and are therefore typically available only for the most recent failure, the crash history file is a permanent record of system failures.

After a system fails and physical memory is copied to the crash dump file, CLUE automatically appends the relevant parameters to the file CLUE$OUTPUT:CLUE$HISTORY.DATA when the system is restarted. The remainder of this section describes how you can use CLUE to display the data it has collected; reference information about CLUE is available in the OpenVMS System Management Utilities Reference Manual.

To display data using CLUE, you must first define the following symbol:

$ CLUE :== $CLUE

After defining the symbol, you can use CLUE to display information by entering the following command:

$ CLUE/DISPLAY CLUE_DISPLAY>

At the CLUE_DISPLAY> prompt, you can issue commands to perform the following actions:

• Use the DIRECTORY command to list failures that have occurred since a specified date, failures of a particular type, failures that contain a specified module, and failures that have a specified offset.
  For example, you can list all the failures in the history file using the DIRECTORY command, as follows:

  CLUE_DISPLAY> DIRECTORY

• Use the SHOW command to generate information similar to that obtained from certain commands in the System Dump Analyzer utility (SDA).
  For example, if you wanted complete information about the crash listed as crash number 7, the following SHOW command would provide the information:

  CLUE_DISPLAY> SHOW ALL 7

• Use the EXTRACT command to write the data from an entry to a file.
  For example, the following command writes the data from entry number 7 in the crash history file to a file named 15MAYCRASH.TXT:

  CLUE_DISPLAY> EXTRACT 7/OUTPUT=15MAYCRASH.TXT

For more information about CLUE commands, refer to the OpenVMS System Management Utilities Reference Manual.

15.10 Saving the Contents of the System Dump File After a System Failure

If the system fails, it overwrites the contents of the system crash dump file and the previous contents are lost. For this reason, ensure that your system automatically analyzes and copies the contents of the system dump file each time the system reboots.

On Alpha systems, SDA is invoked by default during startup, and a CLUE list file is created. Generated by a set sequence of commands, the CLUE list file contains only an overview of the crash and might not provide enough information to determine the cause of the crash. Compaq, therefore, recommends that you always copy the system dump file.

Refer to the OpenVMS Alpha System Dump Analyzer Utility Manual for information about modifying your site-specific command procedure to execute additional commands such as SDA COPY upon startup after a system failure.

On VAX systems, modify the site-specific startup command procedure SYSTARTUP_VMS.COM so that it invokes the System Dump Analyzer utility (SDA) when the system is booted.

Be aware of the following facts:

• When invoked from the site-specific startup procedure in the STARTUP process, SDA executes the specified commands only if the system is booting immediately after a system failure. If the system is rebooting after it was shut down with SHUTDOWN.COM or OPCCRASH.EXE, SDA exits without executing the commands.
• Use the DCL command COPY to copy the dump file; however, the SDA command COPY is preferable 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 it releases those pages occupied by the dump to the pager. For more information, see Section 15.12.
• Because a system dump file can contain privileged information, protect copies of dump files from world read access. For more information about file protection, refer to the OpenVMS Guide to System Security.
• System dump files have the NOBACKUP attribute, so the Backup utility (BACKUP) does not copy them unless you use the qualifier /IGNORE=NOBACKUP when invoking BACKUP. When you use the SDA command COPY to copy the system dump file to another file, the operating system does not automatically set the new file to NOBACKUP. If you want to set the NOBACKUP attribute on the copy, use the SET FILE command with the /NOBACKUP qualifier as described in the OpenVMS DCL Dictionary.

Example

The SDA command COPY in the following example saves the contents of the file SYS$SYSTEM:SYSDUMP.DMP and performs some analysis of the file:

$ ! $ ! Print dump listing if system just failed $ ! $ ANALYZE/CRASH_DUMP SYS$SYSTEM:SYSDUMP.DMP COPY SYS$SYSTEM:SAVEDUMP.DMP ! Save system dump file SET OUTPUT DISK1:SYSDUMP.LIS ! Create listing file READ/EXECUTIVE ! Read in symbols for kernel SHOW CRASH ! Display crash information SHOW STACK ! Show current stack SHOW SUMMARY ! List all active processes SHOW PROCESS/PCB/PHD/REG ! Display current process EXIT $ SET FILE/NOBACKUP SYS$SYSTEM:SAVEDUMP.DMP

15.11 Copying System Dump Files to Tape or Disk

If your system fails, make a copy of the contents of the system dump file and contact your Compaq support representative. You can use the Backup utility (BACKUP) to create save sets containing system dump files on magnetic tape or disk. However, when using BACKUP to copy system dump files, you must specify the /IGNORE=(NOBACKUP,INTERLOCK) qualifier for the following reasons:

• By default, the system dump file has the NOBACKUP attribute, so it is not copied unless you specify /IGNORE=NOBACKUP.
• The system keeps an open channel to the system dump file, so the file is not copied unless you specify /IGNORE=INTERLOCK.

Compaq recommends that you use the following procedure to copy your system dump file:

1. Use the SDA command COPY to make a copy of the system dump file.
2. Use BACKUP to save that copy on tape or disk.

This procedure avoids issues with BACKUP qualifiers and reduces the amount of data written to tape or disk because the SDA command COPY copies only blocks in the system dump file that are actually used.

15.12 Freeing Dump Information from the Page File

If you use SYS$SYSTEM:PAGEFILE.SYS to store a system crash dump, you must later free the space occupied by the system dump for use by the pager. If you do not, your system might hang because of insufficient paging space.

Section 15.1 explains when you might use the page file to store a system crash dump.

15.12.1 Freeing Dump Information on VAX and Alpha Systems

This section contains instructions for freeing dump information from the page file on VAX and Alpha systems.

How to Perform This Task on VAX Systems

On VAX systems, perform the following steps:

1. Invoke the System Dump Analyzer utility (SDA), specifying PAGEFILE.SYS as the target:

   $ ANALYZE/CRASH_DUMP SYS$SYSTEM:PAGEFILE.SYS

2. Enter the SDA command COPY in the following format to copy the dump from SYS$SYSTEM:PAGEFILE.SYS to another file:

   COPY dump_filespec

   
   For example, to copy the system dump file off the system disk to a file called SAVEDUMP.DMP on DISK$USER5, enter the following command:

   SDA> COPY DISK$USER5:[DUMPS]SAVEDUMP.DMP

3. Enter the EXIT command to exit SDA.
4. Include the SDA commands entered in steps 1 and 2 in the site-specific startup command procedure SYSTARTUP_VMS.COM to free page space each time the system reboots.

Alternatively, to free the pages in the page file that are taken up by the dump without having to copy the dump elsewhere, enter the ANALYZE/CRASH_DUMP/RELEASE command. This command immediately releases the pages to be used for system paging, effectively deleting the dump. Note that this command does not allow you to analyze the dump before deleting it.

Example

The following commands, added to the SYSTARTUP_VMS.COM command procedure, copy the contents of the page file to a file named SAVEDUMP.DMP:

$ ANALYZE/CRASH_DUMP SYS$SYSTEM:PAGEFILE.SYS COPY DISK$USER5:[DUMPS]SAVEDUMP.DMP EXIT $ SET FILE/NOBACKUP SYS$SYSTEM:SAVEDUMP.DMP

How to Perform This Task on Alpha Systems

On Alpha systems, as described in the OpenVMS Alpha System Dump Analyzer Utility Manual, SDA is automatically invoked by default when the system is rebooted after a system failure.

To automatically save the system dump file, perform the following steps:

1. Create a SYS$$MANAGER:SAVEDUMP.COM file; for example:

   ! ! SDA command file, to be executed as part of the system ! bootstrap from within CLUE. Commands in this file can ! be used to save the dump file after a system bugcheck, and ! to execute any additional SDA command. ! READ/EXEC ! Read in the executive images' symbol tables COPY SAVEDUMP.DMP ! Copy and save system dump file SHOW STACK ! Display the stack !

2. To point to your site-specific file, add a line such as the following one to the file SYS$MANAGER:SYLOGICALS.COM:

   $ DEFINE/SYSTEM CLUE$SITE_PROC SYS$MANAGER:SAVEDUMP.COM

   
   In this example, the site-specific file is named SAVEDUMP.COM.

If the logical CLUE$INHIBIT has been defined, and SDA has not been automatically invoked during system startup, the pages in the page file that are taken up by the dump can be released using the ANALYZE/CRASH_DUMP/RELEASE command. This command immediately releases the pages to be used for system paging, effectively deleting the dump. Note that this command does not allow you to analyze the dump before deleting it.

For a discussion of logical names used by CLUE, refer to OpenVMS Alpha System Dump Analyzer Utility Manual.

15.12.2 Usage Notes for Freeing Information on VAX and Alpha Systems

Because a system dump file can contain privileged information, protect copies of dump files from world read access.

To prevent the system from backing up the complete contents of the file, assign the NOBACKUP attribute to the file with the DCL command SET FILE/NOBACKUP.

Although you can also use the DCL command COPY to copy a dump file, Compaq recommends that you use the SDA command COPY because SDA COPY performs the following actions:

• Copies only the blocks that the dump actually occupies.
• Is the only way to release for paging the pages that the dump occupies in the system's page file.

The system automatically installs the primary page and swap files located in SYS$SYSTEM. However, other page and swap files are not automatically installed. For this reason, if you create secondary page and swap files, you must also install them with the System Generation utility (SYSGEN). Note that SYSGEN INSTALL commands perform a different function than Install utility (INSTALL) commands.

15.13.1 Installing Interactively

1. Invoke SYSGEN by entering the following command:

   $ RUN SYS$SYSTEM:SYSGEN

2. Enter the SYSGEN command INSTALL as follows:
   For page files, use the following format:

   INSTALL file-spec/PAGEFILE

   
   For example:

   SYSGEN> INSTALL DUA2:[PAGE_SWAP]PAGEFILE_1.SYS/PAGEFILE

   
   For swap files, use the following format:

   INSTALL file-spec/SWAPFILE

   
   For example:

   SYSGEN> INSTALL DUA2:[PAGE_SWAP]SWAPFILE_1.SYS/SWAPFILE

3. To make sure the files are installed each time the system boots, edit SYS$MANAGER:SYPAGSWPFILES.COM to add the commands you entered in step 2. For more information, see Section 15.13.2.

Example

The following example installs page and swap files interactively:

$ RUN SYS$SYSTEM:SYSGEN SYSGEN> INSTALL DUA2:[PAGE_SWAP]PAGEFILE_1.SYS/PAGEFILE SYSGEN> INSTALL DUA2:[PAGE_SWAP]SWAPFILE_1.SYS/SWAPFILE

	privacy and legal statement
6017PRO_071.HTML