Sometimes a developer will want to see a trap dump of your system to properly diagnose a problem. A trap dump is also called a system dump and both terms refer to the same thing.
Preparing the System
Trap dumps contain an image of all the memory in use. In order to make the trap dump more manageable and usable, limiting the amount of usable system memory may be necessary.
If your system has more than 2 GiB of memory, use one of the methods below to limit the amount of usable system memory.
Limiting RAM on ArcaOS Systems
For ArcaOS systems, open a command window and type:
Check the “Limit available memory to” check box and type the desired amount of memory the entry field. 512MB is recommended. If 512 MiB of system memory is too small for your application, you can increase this number up to 2047. However, 512 is the recommended size for debugging.
Click OK and reboot your system.
To undo the memory limiting feature, simply run the memlimit command again and uncheck the “Limit available memory to” checkbox.
Limiting RAM on Non-ArcaOS Systems
These loaders limit the detected physical memory to a hardcoded value. This limits the amount of physical memory that OS/2 will use and generally allows a usable system dump to be written to a 2GiB FAT formatted volume. The system must contain more physical memory than the RAM limiting loader will claim exists. For example, using the OS2LDR_2GB on a system with only 1GiB of physical memory will not work.
One loader limits the detected physical memory to 2GiB. The other limits the memory to 512MiB. The 512MiB version has the benefit of producing a smaller system dump. However, if your application mix requires more than 512MiB of physical RAM to perform well, use the 2GiB version. These RAM limiting loaders only work with SMP kernels.
To install one of these RAM limiting loaders follow these steps. If the OS2LDR file is hidden, unhide it. Example:
attrib -h -s -r OS2LDR
- Download one of the above loaders to the root of your boot disk
- On your boot disk, copy OS2LDR to OS2LDR.save. Example:
copy OS2LDR OS2LDR.save
- Copy the downloaded loader to OS2LDR. Example:
copy OS2LDR_512MB OS2LDR
To uninstall one of these RAM limiting loaders
- Copy OS2LDR.save to OS2LDR. Example:
copy OS2LDR.save OS2LDR
Preparing the Dump Volume
The trap dump facility writes the dump files to a dedicated FAT formatted volume. The code that writes the dump file is located in OS2DUMP on your boot volume. The kernel contains code that passes control to OS2DUMP when a dump is requested.
This dump volume must be a FAT formatted with the volume name SADUMP. The volume must be at least as large as the available system memory.
The standard OS2DUMP is limited by the 2GiB FAT volume limit. If your system has more than 2GiB of RAM, using one of the RAM limiting methods described above is recommended. This will reduce the size of the dump file so that it fits using the standard OS2DUMP, and it will make the dump file more manageable for uploading, etc.
Alternatively, you can install and configure the DUMPFS IFS. However, using this method will create dump files that are larger and more difficult to manage, and is not recommended.
The dump volume must be visible to the BIOS. This usually means it must be on the first or second drive and must be below the 1024 cylinder boundary unless the BIOS support the Int13 extensions.
In a mixed IDE/SCSI system, the driver for the boot volume must load first. This applies even when booting from IDE and when the SCSI drive contains no bootable
devices. Otherwise, OS2DUMP will hang.
The dump partition must be located on a disk with standard logical geometry. OS2DUMP assumes there are 63 sectors/track. This means that OS2DUMP will not be able to find the dump volume on disks larger than 512GiB that use non-standard 127 or 255 sectors/track geometry. So, if your disk is larger than 512GiB, or it uses something other than 63 sectors/track, you will not be able to create system dumps on that disk.
WARNING – OS2DUMP effectively formats the volume and overwrites any existing volume content. Don’t store anything you don’t want to lose on the volume.
Use MiniLVM (recommended), LVM, or DFSee to create a volume for the file system. Verify that the partition size is no more than 2047MiB. LVM and DFSsee round requests up to the next cylinder boundary and OS2DUMP can not handle partitions larger than 2047MiB.
On some systems with less than 2GiB of RAM, it appears that a maximum size partition is required.
Format the volume with
format X: /fs:FAT /v:SADUMP
where X: is the drive letter you assigned to the volume.
Test the volume with the command
The volume name should display as SADUMP. Since the volume is empty, the shell may display a sys0002 error message.
Enabling the Trap Dump Facility
To enable trap dumps, add the following line to config.sys
where x is the volume where the dumps will be stored.
After editing CONFIG.SYS, reboot to active the feature.
To turn off the Trap Dump Facility, REM out the TRAPDUMP statement in
config.sys and reboot.
Recording Trap Dumps
With the above configuration, this is usually automatic. The trap dump file
will be created as the traps occur and will be written to the volume you
chose. Any existing data on volume will be erased including any prior dump
Those using non-US keyboards might have trouble responding to the dump prompt
with the Y key. If so, use F1 instead.
If you are trying to capture a trap dump file for a hang condition, press
Ctrl-Alt-NumLock-NumLock from the keyboard. On some keyboards, you may need
to use Ctrl-Alt-F10-F10. This means, for example, press and hold the Ctrl key and the Alt key at the same time, and while still holding Ctrl key and the Alt key, then press the F10 key twice.
Before actually trying to use the dump facility, you should test your setup and the ability of your system to correctly generate a dump file by manually forcing a dump. Use the Ctl-Alt-NumLock-Numlock or Ctrl-Alt-F10-F10 procedure as described above. Then verify that the dump file is created and can be read by the dump formatter.
Sending the Trap Dump to the Developer
Please see: How to Upload a Dump File.
This document is excerpted from Steven Levine’s document TrapDump.ref