Collecting Documentation

If the problem can be reliably reproduced in a development environment, do it. This is the fastest way to get the problem fixed. When you cannot, try to get a good set of starting documentation.

It is possible to acquire and install a replacement for the OS/2 kernel which is the same as the one being replaced, except that it has debugging facilities and a debug interface to a serial port, COM2. If you install the wrong debug kernel, no one can predict the results. If you install the correct version, you will need to have a terminal emulation program (or ASCII terminal) to access the debug interface. The capabilities of this debug tool are essentially unlimited, and there is no protection from accidental entry errors. Its use is not a trivial task, nor one to be lightly undertaken.

It is often possible to collect enough information about a problem to diagnose its cause by creating customized trace entries specifically for that particular problem. For this to work well, the problem must be reproducable, and the trace buffer must be captured while the data gathered is still present.

Most people who have worked in a technical support role will agree that often the largest obstacle to solving a problem is collecting enough useful information about it. We will briefly discuss how to get enough useful data that problem solving can start in most cases. Be aware that frequently there will be some additional useful information, which can be gathered when the need for it is discovered, and that what is outlined here is not a complete list, by any means.

It is important to collect as complete a set of volatile data as possible from a single failure. If it is not gathered, it will be lost, perhaps requiring another occurrance of the problem in order to get needed information.

It is generally possible to use either an interactive debugger or a dump to diagnose either traps or hangs in an application.

For application problems, particularly traps, a good set of documentation includes the following:

• A statement of what sequence of events leads to the problem

• The trap screen, if a trap is involved

• A storage dump, with system trace data

• All the executable modules involved in the failure

• Optional application documentation, including:

  • all source files

  • map files, produced by the linker

  • lst and .cod or .asm files, produced by the compiler

  The storage dump is the only thing which is volatile. The rest can be collected whenever the need is discovered. To collect the first item, perform the following steps:

  Note: THIS WILL DRASTICALLY CHANGE OS/2 BEHAVIOUR WHEN A TRAP OCCURS. OS/2 WILL not CONTROL THE FAILURE, BUT WILL INSTANTLY AND IRREVOKABLY STOP THE SYSTEM, AND INITIATE A STORAGE DUMP. THERE WILL BE NO SHUTDOWN OF THE WORKPLACE SHELL, DATABASES, FILE SYSTEMS, (or lazy-write buffers,) OR ANYTHING ELSE. IT CAN BE AS DISRUPTIVE AS A POWER FAILURE. IT IS POSSIBLE TO LOSE FILES, OR PARTS OF FILES, but unlikely.

  Prior to WARP: execute the command CREATEDD A: This will prepare a diskette for taking a dump. The diskette will work only once. This is not required for WARP, nor for later levels of 2.11. A quick way to discover if it is required is to read the prompt which asks for the diskette at the beginning of the process. If CREATEDD is required, the prompt asks for the diskette prepared by CREATEDD, otherwise it asks for a formatted diskette.

  Preparation:

  • Save the current CONFIG.SYS

  • Edit CONFIG.SYS

    a.

    If the line is not already present, add a line which reads TRAPDUMP=ON
    b.
    add a line which reads TRACEBUF=63 to enable the system trace
    c.
    add a line which reads TRACE=ON to turn on the system trace
    d.
    optionally, add a line which reads TRACE=OFF,4,6,7
    e.
    optionally, turn LAZYWRITE off, so data goes directly to disk.
    3.
    Locate some formatted diskettes to use for a storage dump.
    Estimate about 2 Megabytes of RAM per diskette; usually one diskette more than that number is needed. For very large systems, estimate 1.5 meg per diskette. The dump process WILL NOT format.

    • Reboot the system so that the changes take effect.

    • Restore the original CONFIG.SYS, so you do not have to reboot an extra time to put things back to normal, after collecting the dump.

    Acquiring the storage dump:

    • Cause the application to trap, that is, reproduce the problem.

    • Insert the CREATEDD diskette, if created, otherwise insert the first formatted diskette.

    • If you can read the screen, follow directions every time you hear one or more beeps.

    • If you cannot read the screen, you can still successfully get a dump, by listening for a beep. Insert the next diskette every time you hear a single short beep. When the dump is almost complete, there will be a very distinctively different series of beeps. At this point, reinsert the first diskette.

    • Very soon after the first diskette is reinserted, the dump will complete. Remove the diskette.

    • OS/2 will reboot automatically in most cases. Expect autocheck to run on HPFS drives during the boot.

    • Run CHKDSK on the drives as soon as convenient.

    ---

    [Back: List of Necessary Skills]
    [Next: Hardware Architecture]