Mr. Know-It-All has the answers to even the really tough questions.
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?
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:
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:
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:
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:
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.
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.
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:
to hold the helper application and the .sym files.
Unzip the contents of c002mdmp.zip into this subdirectory with:
unzip -j c002mdmp -d f:\os2\pdpsi\pmdf\warp14.091
The -j tells unzip to ignore the directory information in the zip file and is required.
If you don't use the -j option or its equivalent, PMDF will not be able to find the symbols.
The Debug Symbols zip files are structured for use with either the Kernel Debugger
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
This tells PMDF that the symbols for the 14.091 kernel are in the warp14.091 subdirectory.
There are 3 parameters, separated by colons.
The first this the PMDF symbols directory name which must be a subdirectory of \os2\pdpsi\pmdf.
The second is the kernel buildlevel.
The third is a comment.
When PMDF loads a dump file, it extracts the kernel revision the dump data and uses it to locate
the symbols subdirectory.
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:
If you don't have either .map or .sym files, the programmer should be able to supply them.
If not, it will be a bit more difficult to analyze the dump file, but PMDF will still work and may still provide some useful hints.
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:
The Trap Screen display will not show much more than the popuplog will, but it will confirm that the dump file is really for the same trap.
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.
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:
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.
Curious or in doubt, you can ask
OS/2 is his specialty and sharing solutions is his passion
Mr. Know-It-All lives in Southern California.
The Southern California OS/2 User Group
P.O. Box 26904
Santa Ana, CA 92799-6904, USA
Copyright 2002 the Southern California OS/2 User Group. ALL RIGHTS
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.