PDGuide - Capturing and Saving Failure-Related Information through Dumps
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
This chapter describes FFST dumps, process dumps, and system dumps. This chapter also instructs you how to set up for and enable system dumps. This chapter instructs you on how to use the Presentation Manager Dump Facility (PMDF) dump formatter to display and analyze FFST (First Failure Support Technology) dumps, process dump, and system dump information.
The FFST dump portion of this chapter assumes that you are familiar with the information and terms that are described in Guide to Instrumenting Your Code.
What Is A Dump?
A dump is a file created by the system at the time of a failure that contains a collection of system data. The collected data is analyzed by software service personnel to determine the cause of a software problem. There are three types of dumps possible for OS/2 Warp Version 4.
- FFST dump
- The system generates a FFST dump when the FFSTProbe function requests certain user and process data. The dump collects the application-oriented and program-specific information that you specify. Guide to Instrumenting Your Code covers the FFSTProbe function, the FFST dump function, and code instrumentation for this type of activity. This chapter contains information about formatting and displaying the contents of the FFST dump.
- Process dump
- A process dump contains limited information about a single process that was running at the time of the failure. The system dump contains greater detail about all processes that were running when the failure occurred. The process dump can be formatted using the PM Dump Facility dump formatter described in this chapter.
- System dump
- A system dump covers system-wide activities. When a system dump occurs, the system automatically stops and stores the contents of main memory. After the data is stored, the system automatically reboots and any operating data that is not in main memory is lost. In other words, when the operating system software encounters a serious problem, the system triggers a system dump. The dump contains the important failure-related information held in the system main memory. The system records this information in a system dump file. You use the information to debug and solve system problems. This chapter discusses the system dump file later.
Where Are Dumps Stored?
FFST dumps are stored stored in the directory specified in the FFST setup. If you do not specify where to store FFST dumps, the system will store the FFST dump file in the default directory of <boot-drive>\OS2\SYSTEM\RAS. The FFST dump file will have the extension of DMP.
Process dumps can be stored only in the root directory of the drive specified in the DUMPPROCESS statement in the CONFIG.SYS file (see Setting Up for a Process Dump). The file name will be PDUMP.nnn where nnn is a number that is incremented each time a process dump is generated.
System dumps are stored either in a dedicated FAT hard disk partition on your system or on a diskette. For details on setting up the dump partition refer to #Setting Up for a System Dump for more information.
System dumps taken to a hard disk partition may be used directly by the PM Dump Facility dump formatter.
Any system dump stored on diskettes is compressed and needs to be decompressed to produce a single dump file. This may be done directly from PMDF by selecting the Decompress Dump option of the File pull-down. PMDF offers the additional facility of decompressing diskette dumps directly from diskette images (see #PM Dump Facility Dump Formatter File Option).
System Dump
A System dump requires that the following steps are performed in order:
- You set up for a system dump by adding statements to the CONFIG.SYS file and adding instrumentation to your code
- The system performs the dump
- You use the PM Dump Facility dump formatter to format and display dump information in a way that you can analyze it.
Setting Up for a System Dump
You must prepare your system to store system dumps before the dump occurs. You add the TRAPDUMP statement described below to the CONFIG.SYS file on your system. The TRAPDUMP statement enables your system to store dump data.
The TRAPDUMP statement controls the system dump facility of OS/2. It will enable initiation of a system dump the instant a trap (error) occurs. The TRAPDUMP statement tells the system where to store the dump information: either on formatted diskettes or on your system's disk storage. Dumping to diskette is the default. A dump is stored on disk storage if the second parameter is used shown as X: in the TRAPDUMP statement example below.
The disk storage device on your system must have a file allocation table (FAT) partition with the volume label of SADUMP. TRAPDUMP accesses this partition when the dump information is stored. You specify the partition with second parameter in the TRAPDUMP statement.
Note: Do not specify a partition that contains vital data. When a dump is written to the partition, it overwrites any data that is in the partition.
To enable system dumps to be performed you need to add the following statement to the CONFIG.SYS file on your system:
TRAPDUMP= OFF | ON | R0, X:
- OFF
- Specifies that the stand-alone dump process will not initiate automatically when an unrecoverable trap occurs. This is the default option. It does not prohibit the use of the Ctrl-Alt-Numlock-Numlock key sequence, Ctrl-Alt-F10-F10 key sequence, or the use of DosForceSystemDump in your code to force a system dump to be performed.
- ON
- Specifies that the stand-alone dump process will be automatically initiated whenever an unrecoverable trap occurs.
- R0
- Specifies that only ring zero traps will automatically initiate the system dump process.
- X
- : specifies the hard-disk FAT partition to which OS2DUMP will write a stand-alone dump. The partition letter must have the colon suffix.
- Note
- The partition may be specified with either ON or OFF. When specified with OFF it will allow a stand-alone dump initiated by Ctrl-Alt-Numlock-Numlock or Ctrl-Alt-F10-F10 to be written to the dump partition.
- The only removable media you can use for dump storage is diskettes.
- Only hard disk logical drives and primary partitions may be specified.
- The system will erase all data on the dump media (disk partition or diskettes) before writing the dump. Do not specify a disk partition or use diskettes that contain vital data.
- When dumping to disk storage, the system is automatically re-booted on completion of the dump if there is a REIPL=ON statement in the CONFIG.SYS file. If the dump was stored on diskettes, the system will not be re-booted automatically.
You can add the REIPL statement to CONFIG.SYS to allow the system to re-boot (re-IPL) following an error.
The syntax of the statement is as follows:
REIPL=ON | OFF
The statement has the following parameters:
- ON
- This specifies the system it to be automatically re-booted following an error.
- OFF
- This specifies that the system is not to be automatically re-booted following an error. The system will remain hung until manually restarted.
Starting a System Dump
You start, or trigger, system dumps in several different ways:
- Using the keyboard sequence (Ctrl-Alt-F10-F10 or Ctrl-Alt-Numlock-Numlock)
- Calling the DosForceSystemDump API
- Selecting the Enable System Dump choice on the Probe Control Table and allowing the FFSTProbe API to generate the dump
If TRAPDUMP=ON statement is in the CONFIG.SYS file and a trap occurs, a system dump will automatically be generated.
DosForceSystemDump Function
For more information about the DosForceSystemDump function, refer to the OS/2 Warp Version 4 CP Reference in the Toolkit.
FFSTProbe Function
The FFSTProbe method of triggering is done by selecting the Enable System Dump option on the FFST Probe Control Table Entry Summary - Add window shown on page Probe Control Table (PCT) Entry Add or Change Summary Window. When your code calls FFSTProbe for a Probe ID that you specified on FFST Probe Control Table Entry Summary - Add window a system dump starts immediately. The FFSTProbe function calls the DosForceSystemDump function to perform the dump.
Process Dump
A process dump file contains very basic unformatted system and user storage data related to the process that encountered the error and does not contain any data pertaining to main memory.
A process dump requires that the following steps are performed in order:
- You set up for a process dump by adding statements to the CONFIG.SYS file and adding instrumentation to your code
- The system performs the dump
- You use the PM Dump Facility dump formatter to format and display dump information in a way that you can analyze it.
Setting Up for a Process Dump
The DUMPPROCESS statement in the CONFIG.SYS file on your system allows you to activate the process dump facility. When a process dump file is created the file name takes the form of PDUMP.nnn where nnn is an index that is incremented each time a new process dump is created.
The syntax of the DUMPPROCESS statement in the CONFIG.SYS file is defined below.
DUMPPROCESS=x
- x
- This parameter specifies the drive letter (excluding the colon) on system where the process dump data file is stored. The file takes the name PDUMP.nnn and resides in the root directory of the drive specified.
Starting a Process Dump
A process dump is generated and written to a dump file when one of the following conditions occur:
- When your code calls the DosDumpProcess function
- When the DUMPPROCESS=x statement is in CONFIG.SYS and a process (application) encounters an error (trap)
- When FFSTProbe is called with a request for a process dump to be generated
FFST Dump
A FFST dump contains information about the processes that were running when the dump was generated along with any user information you requested to be collected.
Setting Up for a FFST Dump
The setup for FFST dumps is done by using the dumpUserData and probe_flags parameters of the FFSTProbe function.
Refer to Problem Determination APIs for information on using the parameters.
Starting a FFST Dump
When the FFSTProbe function is called and the dumpUserData and probe_flags parameters have been specified, a FFST dump is generated and stored.
Refer to Problem Determination APIs for information on using the parameters.
Using the PM Dump Facility Dump Formatter
You use the PM Dump Facility dump formatter to display system dump, process dump, or FFST dump information. The system dump contains data about all system activities. The process dump contains data about a single process. The FFST dump contains the captured information your code requested in the call to FFSTProbe.
Starting the PM Dump Facility Dump Formatter
The PM Dump Facility dump formatter can be accessed by using one of the following:
- By clicking on the PM Dump Facility in the Problem Determination Tools folder. You then click on the File action-bar item, select the Open menu choice, and select the dump file you want to format.
- From the SYSLOG Details window by selecting the Tools menu-bar option (see Displaying Error Log Entry Data).
- By dragging a dump file and dropping it onto the PM Dump Facility icon.
- When you drop multiple copies of the dump files to the PM Dump Facility icon, the dump formatter opens one window for each copy of the dump.
- By selecting Dumps from the Actions menu-bar option on the FFST setup window.
When you start the PM Dump Facility dump formatter without an initial dump file, a window appears with four action-bar choices: File, Edit, Options, and Help.. Use the File option to select the dump file you want to view. When you open the file, the Analyze option appears.
Selecting a Dump to Analyze
You use the File option to open a system dump file.
PM Dump Facility Dump Formatter File Option
The File pull-down menu offers the following options:
- Open Dump File
- This option prompts you for the dump file name to be analyzed. You can also open a dump file by dragging it and dropping it onto the client window of the PM Dump Facility dump formatter. When you drop multiple copies of a dump onto the client window, the system opens only the first copy.
- When you analyze a system dump or process dump, a command line will be shown at the bottom of the PM Dump Facility dump formatter display. You can use the formatter commands as a fast way to find specific data. Refer to the PMDF document in the Troubleshooting folder for a list of system dump and process dump commands.
- When the dump file is first opened, only limited data will appear. Use the Analyze option to access the remaining dump data.
- Log Output
- This option prompts you to start or stop logging output to a file. Log data may be appended to an existing log file.
- Save Output
- This option allows you to save all output displayed in the PMDF scrollable window.
- Decompress Dump File
- Select this option to decompress a new dump.
- Note: For diskette dumps the DUMPDATA.nnn files may be copied for a directory on the hard drive and decompressed from there.
- PMDF has the ability to decompress diskette images created by OS2IMAGE without re-creating the original diskettes. To use this facility each of the image file must be named image.nnn where nnn is a numeric sequence number that corresponds to the disk number.
- Connect
- Connect allows PMDF to be used as a terminal emulator to drive a Kernel Debugger session.
- Disconnect
- Disconnect terminated the communications session with the Kernel Debugger.
The Log Output... option displays a window that allows the logging of formatted dump data to a file. When you turn on logging, the system records all dump information formatted during this session in the log file you specified. The system also displays the formatted dump information at the same time. The system stores the data from the time that you started logging until you close the PM Dump Facility dump formatter. You also stop logging by using the Log Output... Stop push-button. If you open another dump file, logging continues.
When you select the Save Output... option, the system displays a standard OS/2 Save As... window. Specify the file name for the saved data. The system will save all formatted dump output that was generated since the file was opened or since the last clear screen was done. The system saves this "snap-shot" of dump data only when requested using this option. The system does not save the data simultaneously like it does with the Log Output... option.
PM Dump Facility Dump Formatter Edit Option
The Edit pull-down menu offers the following options:
- Search String
- Locates text within the scrollable window.
- Undo
- Reverse the previous Edit Cut action.
- Copy
- Copy marked text to the clip board.
- Cut
- Move marked text to the clip board.
- Clear Screen
- Clears the scrollable window of all text.
PM Dump Facility Dump Formatter Options Option
The Options pull-down menu offers the following options:
- Font Settings
- This allows font selection for displayed output.
- Function Keys
- This provides a menu to predefine function keys as strings of dump formatter command strings. Commands may be separated by a semi-colon.
- Terminal Settings
- Allows the communications parameters to be specified for when the Connect option of the File pull-down is selected.
- Save Settings
- This will save the current options in the PMDF.INI file for use next time PMDF is started.
PM Dump Facility Dump Formatter Analyze Option
The Analyze pull-down menu options are different for each type of dump. These options change when you select a different type of dump to format.
The system dump options are:
- System
- Process
- Threads
- Synopses
The process dump options are:
- Registers
- Task Control Blocks
- Local Descriptors
- Virtual Machine Control Blocks
- Memory Objects
- Module Table
- Process Synopsis
The FFST dump options are:
- Process Environment Data
- Process Status Data
- Format Trace Buffer
- Format Process Dump
- User Data
- Error Log Data
If the dump you selected does not contain data for a particular option, you will not be able to select the option.
Analyzing a System Dump
After you select a system dump for formatting, the Analyze pull-down menu for system dumps offers four selections. Each selection displays its own menu selection. The menu selections are: System, Process, Threads, and Synopsis.. Note that this option is shown only after you open a system dump file.
It is important to note that the output from the Analyze option needs to interpreted with care. Some options are precise since they follow control block chains. The Physical Device Driver Chain and Kernel Heap are examples of control block chains. Other options depend on correct symbols being loaded. Options that display stacks are more speculative in what they display.
The following System Dump Analyze selections are available:
- System
- The System menu display the following options:
- Physical Device Driver
- Virtual Device Driver
- Interrupt Stack
- Program List
- Window Info
- Open files
- Heap Info
- Memory
- Trace
- Process
- The Process menu display the following options:
- Process Info
- Thread Chain
- Module Table
- Local Descriptors
- Memory Objects
- Threads
- The Threads menus dumps stacks related to a given thread. The following menu is displayed:
- Ring 3 / Stack Trace
- Ring 2 / Stack Trace
- Ring 0 / Stack Trace
- Call Gate
- Synopsis
- This offers a miscellaneous collection of options, the most important of which is the Trap Screen display. The following menu is displayed:
- System Synopsis
- Process Synopsis
- Trap Screen Info
- Semaphore Analysis
- Desktop State
When you analyze a system dump, a command line will be shown at the bottom of the PM Dump Facility dump formatter display. You can use the formatter commands as a fast way to find specific data. Refer to the PMDF document in the Troubleshooting folder for a list of system dump commands.
Analyzing a Process Dump
The PM Dump Facility dump formatter is started when a process dump file is opened by using the Open option of the File pull-down menu. The date and time of the dump are displayed. If the dump was created because of a trap then the trap number is displayed otherwise the trap number is shown as ffffffff. The current thread slot and register are shown last.
Process Dump Analyze Option
The Analyze pull-down menu for a process dump differs from the standard PMDF Analyze facility. The following choices are provided:
- Registers
- Task Control Blocks
- Local Descriptors
- Virtual Machine Control Blocks
- Memory Objects
- Module Table
- Process Synopsis
When you analyze a process dump, a command line will be shown at the bottom of the PM Dump Facility dump formatter display. You can use the formatter commands as a fast way to find specific data. Refer to the PMDF document in the Troubleshooting folder for a list of process dump commands.
For information on taking and controlling process dumps, refer to the DUMPPROCESS command in the Command Reference and the DosDumpProcess function in the OS/2 Warp Version 4 CP Reference. Both references can be found in the Toolkit.
Analyzing a FFST Dump
FFST dumps contain information about the processes that were running when the dump was generated along with any user information you requested to be collected.
FFST Dump Analyze Option
The Analyze options for formatting FFST dumps are:
- Process environment data
- Process status data
- Format trace buffer
- Format process dump
- User data
- Error log data
Process Environment Data
When you select the Process Environment Data choice, the PM Dump Facility dump formatter retrieves and displays the environment variables. The system displays the variables that were set at the time the system stored FFST dump. You will not be able to select this option if there is no process environment data in the dump file.
Process Status Data
Select the Process Status Data choice to have the PM Dump Facility dump formatter retrieve and display the system process information. The system records all processes that were running on the system when storing the dump. You will not be able to select this option if there is no process status data in the dump file.
Format Trace Buffer
Selecting this option causes the PM Dump Facility dump formatter to start the trace formatter with the full path and name of the trace data file. The PM Dump Facility dump formatter then writes the following message in the window:
Format trace buffer in x:\xxxxxxxx.xxx
The x:\xxxxxxxx.xxx indicates the path name of the trace file. Then the PM Dump Facility dump formatter starts the trace formatter to format the trace data. The trace data file is a separate file and is not part of the FFST dump file. You will not be able to select this option if the system did not capture trace information when your code called FFSTProbe.
If the system cannot find the path name of the trace data file, use the File menu-bar choice of the trace formatter to specify the file name and path name of the trace data file to format.
You can use the PM Dump Facility dump formatter to access the trace formatter. If you close the dump formatter window while the trace formatter window is open, the trace formatter window also closes.
You can find more information on trace and the trace formatter in Analyzing Performance and Debugging Problems Using Trace.
Format Process Dump
Selecting this option causes the PM Dump Facility dump formatter to start another formatter session with the full path and name of the process dump file. This is similar to the way that the trace formatter is accessed.
The PM Dump Facility dump formatter then writes the following message in the window:
Formatting process dump file x:\xxxxxxxx.xxx
The x:\xxxxxxxx.xxx indicates the path name of the dump file.
If the system cannot find the process dump data file, a File not found error message will be displayed. Use Open option of the File pull-down menu to specify the file name and path name of the dump file to format.
If you close the PM Dump Facility FFST dump formatting window while the process dump window is open, the process dump window also closes.
User Data
When you open the dump and there is at least one area of user data in the dump, the User Data option is available from the Analyze pull-down menu. You will not be able to select this option if the FFST dump contains no user data.
When you select this option, the PM Dump Facility dump formatter reads the data and displays the data areas one by one. The system displays the data with a label for each data area; for example, Data Area xxx (xxx is from 1 to 30).
Error Log Data
When you select the Error Log Data choice, the PM Dump Facility dump formatter reads the error data from the dump file. The dump formatter then displays the error log entry in the same format as the SYSLOG Details record. There is always Error Log data in an FFST dump. The system always allows you to select this option.
You can find more information on error logs in Viewing and Analyzing Error Log Entries.
Other PM Dump Facility Dump Formatter Features
The PM Dump Facility dump formatter has a command interface where you can use your own REXX programs to assist in formatting the dump data.
The PM Dump Facility dump formatter also allows you to use the standard CUA mouse selection and highlighting to select items from the formatted dump.
The PM Dump Facility Mouse Options
Standard CUA mouse selection and highlighting are supported in the PM Dump Facility dump formatter. Use the mouse options to drag and drop marked items onto the command line of the system dump or process dump window.
A double-click with mouse button 1 will highlight a blank delimited string.
A double-click with mouse button 2 will display a pop-up menu of items to use for processing highlighted dump data.
These selections provide the same function as some of the dump formatter commands. They are intended to provide a easy way to perform the same function as the command without having to enter the command on the command line.
Note: There is no validation done between the data that is highlighted and the menu option you select. You must ensure that the correct data is highlighted for the menu option you select.
Listed below are the mouse option selections available system and process dumps:
- List Near
- UnAssemble
- Selector Info
- Unwind Stack
- Thunk Address
- Display Memory
- Bytes
- Words
- Dwords
- ASCII
- Structures
- ExEntry_s
- memstat_s
- ptda_s
- tcb_s
- vmah_s
- _WND
- _MQ
- KSEMSHR
- KSEMMTX
- KSEMEVT
- RamSemStruc
- SysSemTblStruc
- Unlisted
- Chains
- ExEntry_s
- ~ptda_s
- ~tcb_s
- ~vmah_s
- _~MQ
- _~WND
- ~Unlisted
Summary
Set up and triggering for FFST dumps are different than set up and triggering for system dumps.
The system creates FFST dumps when the FFSTProbe function requests user data, process environment data, or process status data. Running a FFSTProbe always causes an entry to be made in the system-error log. A FFST dump does not shut the system down.
A process dump contains limited information about a single process that was running at the time of the failure.
The system creates system dumps when encountering a serious problem or error. When the system creates a system dump, the contents of main memory is stored in the system dump file and the system shuts down.
Use the PM Dump Facility dump formatter to format, display, and analyze FFST dumps, process dumps, and system dumps.