Sometimes a developer will want to see a trap dump of your system to properly diagnose a problem. This page contains some general information about how to produce a trap dump when a developer requests one. The developer may also provide specific instructions in addition to what is presented here. 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 1 GiB of memory, use one of the methods below to limit the amount of usable system memory. Please do not submit a trap dump larger than 2GB unless the developer has specifically said it was okay. 1GB or smaller is preferred. The larger the memory size the larger the dump file and the longer it will take to upload it and the more time and resources it takes for the developer..
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. Please do not submit a trap dump larger than 2GB unless the developer has specifically said it was okay. The larger the memory size the larger the dump file and the longer it will take to upload it.
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 on ArcaOS systems
This section applies to to all ArcaOS systems v5.0.5 or later that use the new Arca Noae OS2DUMP module. If your system is older than v5.0.5 you should update first anyway.
The trap dump facility writes the dump files to a dedicated FAT or FAT32 formatted volume. This dump volume must be formatted FAT or FAT32 and must have the volume name SADUMP. The volume must be at least as large as the available system memory to be dumped. Note that FAT volumes are limited to 2GB. Please do not submit a trap dump larger than 2GB unless the developer has specifically said it was okay.
The dump volume may be on any fixed disk accessible by the system’s AHCI disk controller or by the BIOS. For ArcaOS 5.0.7 and later, the dump volume may be on the RAM disk. Dump files cannot be written to removable media such as USB flash drives.
WARNING – OS2DUMP effectively formats the volume and overwrites any existing volume content. Don’t store anything you don’t want to lose on the dump volume.
Dump volume on hard disk
For a dump volume on the hard disk, use MiniLVM (recommended), LVM, or DFSee to create a volume for the file system. For normal dump files within the recommended guideline of less than 2GB, a 2047 MB FAT formatted partition is recommended.
Format the volume with
format X: /fs:FAT /v:SADUMP
format X: /fs:FAT32 /v:SADUMP
where X: is the drive letter you assigned to the volume. A FAT formatted volume is recommended.
Dump volume on RAM disk
For a dump volume on a RAM disk go to System Setup -> RAM Disk and create a RAM disk large enough to hold the dump file. Be sure to check “Preserve contents after warm reboot”, and choose FAT or FAT32 for “Format partitions using”. Then edit \OS2LDR.CFG and add the line
RAMDISKLABEL = SADUMP
You must reboot for the changes to take effect. You should check to make sure that files created on the RAM disk persist after a reboot. This works on most systems, however in rare cases on some systems the contents of the RAM disk cannot be preserved across a reboot.
Preparing the Dump Volume on Non-ArcaOS systems
This section applies to non-ArcaOS systems (eCS, Warp4, etc.) that use the old IBM OS2DUMP module.
The trap dump facility writes the dump files to a dedicated FAT formatted volume. This dump volume must be FAT formatted with the volume name SADUMP. The volume must be at least as large as the available system memory.
The standard IBM 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. Please do not submit a trap dump larger than 2GB unless the developer has specifically said it was okay.
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 file.
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-F10-F10 or Ctrl-Alt-NumLock-NumLock from the keyboard. 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. On some systems, and in some situations, you may need to plug in a PS/2 keyboard for this to work.
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. Always provide a testlog log file from the system that was taken in the exact configuration as the system dump. Normally you will attach the testlog log file to your ticket at the same time you upload your dump file. If in doubt when to capture a matching testlog log file, do it immediately after rebooting after the trap. More information on how to create a testlog log file is here.