Q.  Dear Mr. Know-It-All,

Every now and then I get a kernel trap and a black screen full of numbers. I've reported the numbers and have been told that my trap is not a known failure and that if I want to trouble shoot the trap any further, I need to record a trap dump. I know I can record the dump on diskettes, but that sure seems like a lot of diskettes. How do I write the dump to hard disk?

A.  To write the dump to hard disk you need a FAT formatted partition within the first 1024 cylinders of a bootable disk drive. The following sections describe how to setup and record the dumps and gives some hints for analyzing the dump. Often just knowing where the code is failing is a good start on finding a way to avoid a trap.

1. Setup.

To enable trap dumps, add the following line to CONFIG.SYS:

WARNING - the dump will erase the drive, so either back up the drive first or use a scratch drive. The partition must be at least as large as the installed memory. Reboot to activate the feature. For more information, type:

Recent Fix Paks have added a command, pdumpsys, that can control the level of detail included in the dump. For more information, see:

2. Recording Trap Dumps.

This is automatic. The trap dump files will be created as the traps occur and will be written to the drive you chose. Any existing data on the drive will be erased including any prior dump file. Most often the trap will occur at the same cs:eip repeatedly. If not, you may need to save the trap dump files to a temporary directory to allow you to analyze the common factors.

To turn off the feature, just REM out the line(s) in CONFIG.SYS and reboot.

3. Preparing to Use the PM Dump Facility.

The PM Dump Facility (PMDF) uses .sym files to translate binary addresses to symbolic labels. These files are Fix Pak specific and application version specific. Assuming a standard install of the Dump Facility, the .sym files are stored in a subdirectory of \os2\pdpsi\pmdf on your boot drive and pointed to by the index file \os2\pdpsi\pmdf\pmdfvers.lst.

Depending on what components you installed when you installed Warp on the box where the trap occurred, you might already have the files needed to examine the dump installed in \os2\pdpsi\pmdf\merlin. If not, the following example explains how to get the files and install them so that the Dump Facility can find them.

The example that follows assumes:

• Fixpack 11
• Kernel version 9.035
• Boot drive f:

Replace the values in the example with values that match your system. Add pathname prefixes as needed based on where you have the files stored.

1. Go to ftp.software.ibm.com/ps/products/os2/fixes/debug and download m011dmp.zip. This is the symbols zip file for FP11 and kernel version 9.035.

2. Create the subdirectory "f:\os2\pdpsi\pmdf\warp4.11"

3. Unzip the contents of m011dmp.zip into this subdirectory with: unzip -j m011pmd.zip -d f:\os2\pdpsi\pmdf\warp4.11 This will put all the files in m011pmd.zip into a single directory. This is important. If you don't use the -j option or its equivalent, the Dump Facility will not be able to find the symbols.

   The zip files are structured for use with either the Kernel Debugger or the Dump Facility. The Kernel Debugger requires that the .sym files be in the same directory as the associated executable. The zip files contain subdirectory information so that the files will be placed in the correct directory when unzipped. The Dump Facility has different requirements. For the Dump Facility, the .sym and df*.exe files must be in a subdirectory named in pmdfvers.lst.

   The Kernel Debugger runs on the Machine Under Test (MUT). The only set of symbols it needs, or can use, are the ones for the installed kernel revision. The Dump Facility often runs on a system other than the MUT which generated the dump. Using pmdfvers.lst to locate the correct symbols for the dump allows the Dump Facility to be used to analyze dumps even when the systems have different kernel revisions installed. Pmdfvers.lst will have a line defining where to find the symbols for each specific kernel revision to be analyzed.

4. Add the following line to pmdfvers.lst: warp4.11:9.035:OS/2 Warp 4 FP11 This will allow the Dump Facility to find the symbols in the warp4.11 subdirectory.

5. If your application came with .sym files, copy them into this directory.

6. If your application came with .map files, use the mapsym utility to create the .sym files. Mapsym is available with most compilers.

   If you don't have either .map or .sym files, it will be a bit more difficult to analyze the dump file, but the Dump Facility will still work.

4. Analyzing Trap Dumps.

This is the bare bones. Start the PM Dump Facility. It should be in the Problem Determination Tools folder. If you didn't install it, you will need to run Selective Install to do so and reapply the last Warp 4 Fix Pak you installed (i.e., FP14 or whatever).

From the File menu, open the dump file. If you have installed the matching .sym files, the Dump Facility will find them. Otherwise, it will prompt you for a location. If you don't have symbols, just click OK.

• From Analyze menu, select Synopsis -> Trap Screen Info.
• From Analyze menu, select Synopsis -> Process Synopsis.
• From Analyze menu, select Synopsis -> System Synopsis.
• From Analyze menu, select Thread -> Ring 0 Stack Trace.
• From Analyze menu, select Thread -> Ring 2 Stack Trace.
• From Analyze menu, select Thread -> Ring 3 Stack Trace.
• From Analyze menu, select Thread -> Call Gate.
• From Analyze menu, select Process -> Open Files
• From Analyze menu, select Process -> Module Table.
• From the Dump Facility command line at the bottom of the window, enter these commands (press the Enter key after each command): u eip-20 eip r k dw bp
• From the File menu, select Save Output and save the window contents to a file.

If you don't understand what you are seeing, you will have to find someone to help you interpret the results. Your helper will want to review the saved output. Save the dump file until analysis is complete. Your helper may need it.

5. E-mailing Trap Dumps.

In general, don't. Trap Dumps are large and most ISP's will bounce an e-mail of this size. FTP is a better solution. Even so, it's a good idea to zip up the trap dump. This can reduce the file size and transmit time significantly.

SCOUG, Warp Expo West, and Warpfest are trademarks of the Southern California OS/2 User Group. OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks remain the property of their respective owners.