PDumpCtl

PDumpCtl v0.18 User Guide 2023-06-08 SHL PDumpCtl is a wrapper for the OS/2 Process Dump Facility. It makes it easy to configure the the Dump Facility for the typical situations. This package includes two versions of the tool. PDumpCtl.cmd is written in REXX. PDumpCtl4.cmd is written for 4OS2. PDumpCtl4.cmd is no longer maintained and is deprecated. However, it may be useful if REXX support is not available on the system where you need to capture a process dump file. PDumpCtl4 supports most, but not all, of the options supported by PDumpCtl. Note: v0.18 (this version) of PDumpCtl makes significant changes to the Shared and Extended dump styles. In most cases, the Shared style can now be used instead of the Extended style. The dump file will be smaller while still containing the shared memory data needed to analyze traps in DLLs. == Installation == Install the script to any convenient directory. Installing to a directory in the PATH is recommended. A dump directory is required. If a directory name is specified on the command line, it will be used. Otherwise, PDumpCtl will use the DUMPPROCESS directory from config.sys, if it is valid. Otherwise, PDumpCtl tries to locate a usable dump directory as follows. PDumpCtl assumes the directory is named Dumps and looks for this directory in the root of all local volumes and in the %TMP% directory. If PDumpCtl can not locate a dump directory or the dump directory specified on the command line does not exist, PDumpCtl will complain and quit. Be sure to place the dump directory on a volume with sufficient free space. Depending of the options selected, dump files can be anywhere from 1MB to size of physical RAM and they are not automatically deleted or overwritten. A typical firefox process dump will be in the 100MB to 200MB range because both private and shared data will be required to analyze the failure. PROCDUMP.EXE and PDUMPUSR.EXE must be installed. They are typically installed to \OS2\SYSTEM on your boot volume. If they were not installed when ArcaOS/eCS/OS2 was installed, copy them from the installation CD. For ArcaOS and eComStation, copy PROCDUMP.EXE and PDUMPUSR.EXE from the \OS2IMAGE\FI\SYSMGT\OS2\SYSTEM directory on the install media to \OS2\SYSTEM on the boot volume. Copy PROCDUMP.DOC from the OS2IMAGE\FI\SYSMGT\OS2\SYSTEM\RAS directory on on the install media to \OS2\SYSTEM\RAS on the boot volume. If you are using PDumpCtl4.cmd, you need to have 4OS2 installed on the system, but it does not need to be the default shell. == Usage == To see the available options, use PDumpCtl -? which will display pdumpctl 0.18 2023-06-08 Control Process Dump Facility in batch or interactive mode. Usage: pdumpctl [-h] [-i] [-p] [-v] [-?] [commands...] [procname|pid] [dirname] -h -? Display this message -i Run interactive (default is batch mode) -p Enable Proliant mode, disables sysvm to prevent system traps -v Display version number and quit pid Select PID to dump, default radix is hex Prefix with 0x for hex or 0t for decimal if ambiguous procname Select process to dump Quote if process name looks like a number dirname Set Dump directory, quote if name looks like a number Defaults to ?:\Dumps or %TMP\Dumps commands Batch mode commands a Reset to All - set to dump all physical memory d Force dump - requires PID or process name f Full - add private/instance code and data to current settings i Instance - add instance data to current settings n Reset to Normal - set to summ sem sysldr sysfs sysvm syssem o Turn off dump facility r Reset to Default - set to system default settings s Shared - add private/instance/shared code and data to current v View dump settings x Extended - add private/shared code/data mvdm sysio syspg to current The force dump command requires that at least one PID or process name be specified. Other commands do not require this. The command line can include a combination of - zero or more command line switches - zero or more batch mode commands - zero or more pid numbers - zero or more process names - a directory name Command line switches must appear first. The other command line arguments can be entered in any order. PDumpCtl will try to figure out what you mean. PDumpCtl assumes you want what you request. For example, if a command line argument names a valid directory, it will be interpreted as the dump directory name even if it could also be interpreted as a process name. For example, if you want to run PDumpCtl for the pmmail process and you invoke PDumpCtl as PDumpCtl -i pmmail and pmmail also happens to be a subdirectory of the current directory, PDumpCtl will select the pmmail subdirectory as the dump directory. If this is not what you want, run PDumpCtl from some other directory or name the dump directory you want PDumpCtl to use. For example: PDumpCtl -i \Dumps pmmail What the Process Dump Facility calls the process name is really the internal module name. In most cases, the process name is the same as executable name. If not, be sure to provide the module name and not the executable name. Batch mode commands must be entered in the order you want them executed. PDumpCtl operates in two modes - batch or interactive. In batch mode, PDumpCtl processes the batch mode commands on the command line and exits. In interactive mode, PDumpCtl processes any batch mode commands on the command line and then prompts the user for additional commands. When PDumpCtl starts, it does not change the Dump Facility settings unless requested. This means that if the Dump Facility is not enabled when you start PDumpCtl, you must issue one of the commands from that enables the Dump Facility otherwise any attempt to capture a dump file will fail. The same is true when PDumpCtl exits. The current Dump Facility settings are retained. This is useful when you need to wait for a trap to occur. If this is not what you want, issue a command that turns off the Dump Facility before PDumpCtl exits. As noted above, commands are processed in the order given. This is true in both batch and interactive mode. This means if the current Dump Facility settings are not what you need, you must adjust the settings before attempting to capture a dump file. If also means that if the dump facility is not currently enabled, you need to enable the dump facility before you can capture a dump file. There are two groups of commands that affect the Dump Facility settings. The Reset group enables the dump facility, clears any existing settings and sets the Dump Facility to a known state. The Add group adds settings to the current state. If you issue an Add group command when the Dump Facility is not enabled, PDumpCtl will set the dump state to Normal before processing the Add group command. If you attempt to capture a dump file when the Dump Facility is not enabled PDumpCtl will complain. PDumpCtl defines a number of Dump Styles. A Dump Style is a collection of Process Dump facility settings that have been shown to be broadly useful. See the "Choosing a Dump Style" section which discusses the available Dump Styles in more detail. See the Examples section for typical PDumpCtl command lines. In interactive mode, PDumpCtl prompts for commands with D)ump N)orm. I)nst. F)ull S)hare X)tend. A)ll R)eset O)ff V)iew H)elp Q)uit ? h where the available commands are D - Force dump using current settings N - Reset to Normal - set to summ,sem,sysldr,sysfs,sysvm,syssem I - Instance - add instance data to current settings F - Full - add private code and data to current settings S - Shared - add private/instance/shared code and data to current X - Extended - add private/shared code/data mdvm sysio and syspg to current A - Reset to All - set to dump all physical memory R - Reset to Default - set to system default settings O - Turn off dump facility V - View current settings H - Display this screen Q - Quit ? - Display this screen ! - Shell The commands available in interactive mode are a superset of the batch mode commands. The commands available in both modes function the same in either mode. Recall that when PDumpCtl exits, the current Dump Facility settings are retained. If this is not what you want, use the O command to turn off the Dump Facility before quitting PDumpCtl. As discussed above, the same is true when PDumpCtl starts. PDumpCtl does not change the Dump Facility settings unless requested. If the current settings are not what you need, you must change the settings before capturing the dump file. The View command displays the current settings as defined by the Process Dump Facility. PDumpCtl.cmd contains short explanations of these settings. \OS2\SYSTEM\RAS\PROCDUMP.DOC contains full explanations of these settings. If you are using PDumpCtl4.cmd, usage is the same. If 4OS2 is not your default shell, start PDumpCtl4.cmd with the command 4OS2 /c PDumpCtl4 If 4OS2 or PDumpCtl4.cmd are not in the PATH, you will need to supply full path names. Once you have a dump file, you can view it with the Process Dump Facility (pmdf). If you need help getting started with pmdf, see http://www.warpcave.com/os2diags/ProcDumpRef.txt == Choosing a Dump Style == PDumpCtl defines the following Process Dump styles Default Normal Instance Full Shared Extended All The styles differ in how much data is captured. The Default style produces the smallest dump file and the All style produces the largest. The Default style selects the process dump settings defined by the kernel or by the PDUMPUSR command in config.sys. Unless overridden by a PDUMPUSR command in config.sys, this style is equivalent to PDUMPUSR SUMM,MVDM,SEM,SYSFS which typically result in a dump file of 1MB or so. This style is not recommended because it omits data often required to effectively analyze application failures. The Normal dump style is equivalent to PDUMPUSR SUMM,SEM,SYSLDR,SYSFS,SYSVM,SYSSEM which typically results in a dump file of 3MB or so. This is the recommended dump style for simple application traps. It should be used, unless it is already known that additional data will be needed to effectively analyze the failure. The dump file is relatively small, but includes the system wide data that is almost always needed to analyze application failures. This is a good choice if you want to capture a dump file for all process exceptions. The dump files are small enough not to fill up the disk volume too quickly, but contains enough data to do useful analysis for a wide variety of process failures. The Instance dump style is equivalent to PDUMPUSR SUMM,INSTANCE,SEM,SYSLDR,SYSFS,SYSVM,SYSSEM which is the Normal style with INSTANCE data added. This typically results in a dump file of 3MB plus the size of the process's instance data. This style is a good choice if the Normal style does not include all the private data you need to analyze, but the stack traces are good enough that you don't need to have all the executable code and data included in the dump file. The Full dump style is usually equivalent to PDUMPUSR SUMM,PRIVATE,INSTANCE,SEM,SYSLDR,SYSFS,SYSVM,SYSSEM which is the Normal style with PRIVATE and INSTANCE data added. These settings can result in a relatively large dump file because the dump file will include all of the process's private code and data. Depending on the application the dump file can be 100MB or larger. This dump style is useful when the private executable code and data needs to be be analyzed and the Instance style does not include enough to the application code and data. The Shared dump style is usually equivalent to PDUMPUSR SUMM,PRIVATE,SHARED,INSTANCE,SEM,SYSLDR,SYSFS,SYSVM,SYSSEM which is the Full style with SHARED code and data added. These settings can generate a significantly larger dump file than the Full style because the dump file will also include all of the process's shared code and data. Depending on the application the dump files can be 100MB or larger. This dump style is required when the content of the code and data in shared memory needs to be analyzed and and the Full style does not include enough to the needed code and data. This occurs most often when the exception occurs in a DLL. The Extended dump style is usually equivalent to PDUMPUSR SUMM,PRIVATE,SHARED,INSTANCE,MVDM,SEM,SYSLDR,SYSFS,SYSVM, SYSSEM,SYSIO,SYSPG which is the Shared style with MVDM SYSPG and SYSPG data added. These settings will generate a larger dump file than the Shared style because the dump file will inlcude page tables and system IO tables. This specialized dump style is required when the content of the page tables needs to be analyzed. The All dump style is equivalent to PDUMPUSR PADDR(ALL) This is effectively the same a writing a system dump, but the system is not rebooted after the dump file is written. The dump file will be large since all physical memory will be written to the dump file. This specialize dump style is rarely used. In rare cases, attempting to capture a Full or Extended dump results in sufficient paging activity to hang the Process Dump Facility. The solution is to capture an All style dump which does not require any paging. If you are not sure which dump style you should use, ask a developer for guidance. == Examples == To capture of process dump for a running httpd process that has hung: PDumpCtl n s d o httpd This command line resets the Dump facility to the Normal style, updates the settings to the Shared style, forces a dump of the httpd process, turns off the Dump Facility and exits. To capture a process dump for firefox.exe when it traps: PDumpCtl n s firefox This command line resets the Dump facility to the Normal style, updates the settings to the Shared style and exits. After the dump file has been captured, you would typically do: PDumpCtl r o which resets the Dump Facility to the Default style and and turns off the Dump Facility. This will avoid capturing dump files that you don't need. To run PDumpCtl in interactive mode: PDumpCtl -i which starts PDumpCtl in interactive mode and prompts for commands. Any changes to the Process Dump Facility settings will apply to all processes. To run PDumpCtl in interactive mode for the firefox process: PDumpCtl -i firefox which starts PDumpCtl in interactive mode, selects the firefox process and prompts for commands. Any changes to the Process Dump settings will apply only to firefox process. == Proliant Servers == On some Proliant servers, some dump styles will cause the Process Dump Facility to hang or trap because these dump styles normally add SYSVM to the dump options. To avoid this, use the -p option when starting PDumpCtl. == Known Issues == None, as of today. Good luck, Steven