Question:

I've got an application that traps in DOSCALL1.DLL. The programmer says he can't duplicate the failure. Is there a way I can get him more information?

Answer:

A Process Dump is one way to get more information about what the application was attempting to do at the time of the trap. This may allow you better understand why the applicaiton trapped. It will definitely provide data the programmer can use.

Configuring the Process Dump Facility

By default, the Process Dump Facility is turned off when OS/2 boots. The Dump Facility can be turned on from config.sys or from the command line.

• To enable process dumps from config.sys, edit config.sys and add the following line:

    DUMPPROCESS=x
  

  where x is the drive where the dump files are to be written. The files will be written to the root of this drive. Save the config.sys changes and reboot.

• To enable process dumps from the command line, issue the command:

    PROCDUMP ON /L:pathname
  

  where pathname is the directory where the dump files are to be written. The Dump Facility will be enabled until it is turned off or until the next reboot.

For best results, pick an HPFS or JFS drive with the most free space. Depending on how an application uses memory, the dump files can be very large.

If the application traps intermittently, you will probably want to use the config.sys method. If the application trap is easy to force, the command line method is probably the simpler choice.

Once the Dump Facility is enabled, a process dump will be recorded whenever an application traps. If the application hangs rather than traps, you can force a process dump with the command:

  PROCDUMP FORCE /PROC:processname

The default Process Dump settings generate a relatively small dump file, but might not include sufficient detail for analysis. The Process Dump Facility supports a variety of configuration settings so this can be controlled as needed. For example, to include application's private memory area in the dump, issue the command:

  PDUMPUSR PRIVATE,UPDATE

Recording the Process Dump

The dump files will be written to the selected location as the traps occur. Once you have the dump file you want written to disk, you will probably want to turn off the Dump Facility to avoid filling up the disk.

• To turn off the Dump Facility from config.sys, REM out the DUMPPROCESS line and reboot.
• To turn off the Dump Facility from the command line, type:

    PROCDUMP OFF
  

Preparing to Use the PM Dump Formatter

The PM Dump Formatter (PMDF) provides a set of tools for analyzing Process and System Dump files. PMDF itself is version independent. It is configured by version specific control files. These include a helper application (df_ret.exe or df_deb.exe) and symbol files (.sym). The helper application knows how to locate the internal data structures for a particular kernel version. The .sym files map binary addresses within an executable to symbolic labels. Given a typical Dump Facility installation, the helper and .sym files are stored in a subdirectory of \os2\pdpsi\pmdf on the boot drive and pointed to by the index file \os2\pdpsi\pmdf\pmdfvers.lst.

If you installed the Dump Facility when you installed Warp, you might already have the files needed to examine the dump. By default, they will be installed to \os2\pdpsi\pmdf\merlin. Unfortunately, FixPak installs do not always update this directory correctly. If you don't have the files you need, the following example shows how to determine which files you need, where to to get them, and how to install them so that PMDF can use them.

The example assumes:

  MCP Fixpack 2
  Kernel version 14.091
  Boot drive f:

IBM supplies a variety of debug support files, including those needed to configure the PMDF at the IBM Debug Support FTP Site. These include the debug symbols zip files which is what we want now.

Download c002mdmp.zip. This contains the debug symbols for MCP FP2 and kernel version 14.091. The files for other FP levels are named similarly. They will be named xxxxydmp.zip where xxxx is the FP id code and y is the kernel type. Warp4 Debug Symbol files omit the kernel type code. For example, m015dmp.zip contains the symbols for Warp4 FP15.

Create the subdirectory:

  f:\os2\pdpsi\pmdf\warp14.091

  unzip -j c002mdmp -d f:\os2\pdpsi\pmdf\warp14.091

The Debug Symbols zip files are structured for use with either the Kernel Debugger or PMDF. The Kernel Debugger requires that the .sym files be in the same directory as the associated executable, so the zip files contain subdirectory information. PMDF requires that the files to be in a subdirectory named in pmdfvers.lst.

There is a reason for the differing requirements. The Kernel Debugger runs on the Machine Under Test (MUT). The only set of symbols the Kernel Debugger needs, or can use, are the one's for the installed kernel revision. PMDF often runs on a system other than the MUT which generated the dump. Using pmdfvers.lst to locate the correct symbols for the dump file allows PMDF to be used to analyze dumps from different system running different kernel and FP versions. Pmdfvers.lst will have a line defining where to find the symbols for each system configuration to be analyzed.

Add the following control line to pmdfvers.lst:

  warp14.091:14.091:OS/2 MCP FP2

If you have a testcase kernel installed, copy any .sym files that came with the kernel to the PMDF symbols subdirectory. Don't forget to use the testcase kernel buildlevel in the pmdfvers.lst control line.

If the application came with .sym files copy them into tye symbols subdirectory.

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

  MAPSYM mapfile

Analyzing the Process Dump

This is a bare bones introduction. Start the PM Dump Formatter. There should be a Program Object titled "PM Dump Facility" 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 base FixPak to apply any PMDF updates that might exist.

From the File menu, open the dump file. If you have installed the matching sym files and have configured pmdfvers.lst correctly, PMDF will find them. Otherwise, PMDF will prompt you to select a symbol set. Cancel the dialog; quit PMDF and correct the problem.

PMDF will allow you to tell it to use any set of debug symbols. It is up to to get to select the correct set. The result of using the wrong set can vary from nothing to hanging PMDF.

To gather data:

• From the Analyze menu, select Synopsis -> Trap Screen.
• From Analyze menu, select Thread -> Call Gate
• From Analyze menu, select Thread -> Ring 3 Stack Trace.
• From Analyze menu, select Process -> Open Files
• From Analyze menu, select Process -> Module Table.
• From PMDF command line at the bottom of the window, enter the commands:

    r
    ln
    u eip-20 eip
    k
    dw bp
  

  Press the Enter key after each command.
• From the File menu, select Save Output and save the window contents to a file.

If the application trapped in a Call Gate, this will often give a clue as to why the application got in trouble. The Call Gate name will indicate what OS/2 service the application requested.

The Ring 3 Stack Trace is useful because it can identify what the application was doing when the trap occurred. The symbolic names of listed in the Stack Trace often give a good clue what the application was trying to do.

Sometimes the Open File list will give similar hints.

It is unlikely that you will understand a lot of what you are seeing, unless you are very familiar with OS/2. However, the information you can now provide the programmer should make the cause for the trap much easier to locate.

E-mailing Process Dumps

If you need to E-mail a process dump, zip it up first. This will save a lot of transmit time.

Additional Resources

If you want to know more about the gory details of Process Dumps, there are lots of additional resources out there.

• The OS/2 Warp Command Reference is somewhat limited. To see what's there, open it and search for:

    process dump
  

  or type:

    view cmdref dumpprocess
  

  from the command line.

• The text file \os2\system\ras\procdump.doc contains complete documentation of the procdump and pdumpusr command options.

• The OS/2 Debugging Handbook (sg244640.inf) contains good tutorials on both PMDF and general problem determination. This document is included in the Warp Toolkit which is available from many sources, including the MCP CD's.

Copyright 2002 the Southern California OS/2 User Group. ALL RIGHTS RESERVED.

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.