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.
This wiki describes how to get a trap dump from an installed system. This means that you can get a trap dump from your system if it is fully installed and configured. Trap dumps on uninstalled systems generated from install media are not supported. Do not attempt to get a trap dump when booted from the install medium. Trap dumps are difficult and complex to achieve on uninstalled systems, are not needed, and are rarely if ever useful. If the developer working a ticket determines that a trap dump would be useful, then that developer will instruct the reporter on getting the dump file in that particular environment. Capturing a trap dump on an uninstalled system from the install media is beyond the scope of normal operations and beyond the scope of this wiki.
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..
On this page
Limiting RAM on ArcaOS Systems
For ArcaOS systems, open a command window and type:
memlimit
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
For non-ArcaOS systems (eCS, Warp4, etc.) install either the 512MiB loader (recommended), or the 2GiB Loader. Do not use these RAM limiting loaders on ArcaOS systems or the trap dump facility may not work.
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. In most cases dump files cannot be written to NVME devices.
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 to create a volume and assign a drive letter for the file system. If not using FAT32, a 2047 MB FAT formatted partition is recommended. For ArcaOS systems v5.1.0 and later, the dump volume may be on a GPT disk.
Format the volume with
format X: /fs:FAT /v:SADUMP
or
format X: /fs:FAT32 /v:SADUMP
where X: is the drive letter you assigned to the volume.
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
So the end result will be 3 lines describing the RAM disk and should look something like this:
RAMDISK = FAT32 PERSIST O: RAMDISKNAME = SADUMP 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), or LVM to create a volume for the file system. Verify that the partition size is no more than 2047MiB. LVM rounds 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
dir X:\
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
TRAPDUMP=R0,x:
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.
The dump facility will reboot the system automatically after the trap file has been written. In rare cases the system may not reboot automatically. If you think the system is stuck, simply reset or power cycle the system to reboot. If the dump target is a RAM disk, the reset or power cycle must be quick enough to preserve the contents of the RAM disk.
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.
This entry last updated: by