Category : Pascal Source Code
Archive   : STKDMP.ZIP
Filename : STAKDUMP.DOC

STAKDUMP - Error handler with Stack Trace for Turbo Pascal 4.0
------------------------------------------------------------------------------
Kim Kokkonen
TurboPower Software
11/27/87
Version 1.0
Released to the public domain


Overview
------------------------------------------------------------------------------
When Turbo Pascal encounters a runtime error, it normally reports the error
number and the location of the error, and then halts execution. This is a
useful feature that allows you to track down errors quickly.

Knowing the location of the error is sometimes not enough. Suppose for
example that you have some small routines that are called from many places
within a program. If a runtime error occurs within one of those routines, you
probably won't have any idea why the error really occurred, since the small
routine could have been called from anywhere.

The STAKDUMP unit solves this problem by reporting not only the address of the
actual error, but also the addresses of all calls made in reaching the error.
The Turbo Graphix Toolbox for Turbo 3 has a similar routine but it isn't
adequate for Turbo 4, which mixes near and far calls as required by the unit
structure of the program.


Using STAKDUMP
------------------------------------------------------------------------------
STAKDUMP is a small unit that exports no identifiers at all. You use it by
inserting it as the first unit in the USES statement of your program. STAKDUMP
uses about 700 bytes of code space.

STAKDUMP automatically installs itself as a Turbo exit handler. When the
program terminates, the exit handler gains control. If a runtime error has
occurred, STAKDUMP writes the error number and the error address, followed by
any stacked return addresses. It writes to the standard output device after
first resetting it so that the results will appear on the console screen.

STAKDUMP reports addresses in the relative segment format used by the
compiler. The base code segment of the program is 0 in this format. You can
use any of the addresses with the TPC.EXE /F "find error" option to relate
back to the source code. Alternatively you can find the addresses in a MAP
file produced by the TPMAP utility.

STAKDUMP has one major limitation: it will work only when your program is run
as a standalone EXE file. Within the user-interface compiler TURBO.EXE, or
when run using the TPC /R option, the program's code is loaded in a different
manner and at different relative addresses than when it is an EXE file.
STAKDUMP senses these situations and simply passes control to the normal Turbo
error handler. Similarly, you can't use TURBO.EXE's "find error" command to
find errors reported when running the EXE file. You must use the TPC /F option
to find the source locations.


How STAKDUMP Works
------------------------------------------------------------------------------
STAKDUMP traces the BP chain on the stack. While within any routine in Turbo
Pascal, the word at SS:[BP] contains the calling routine's BP value. (While
within the main block, SS:[BP] contains the initial value of the stack
pointer. This value is used to terminate the trace.) The word at SS:[BP+2]
contains the return offset of the current call. If the call was FAR, the word
at SS:[BP+4] contains the return segment of the current call. Otherwise,
SS:[BP+4] contains an undefined value, perhaps a parameter.

The tricky part of STAKDUMP lies in determining whether each call was NEAR or
FAR. It does so by doing a partial disassembly of the code. For each error
address, STAKDUMP scans forward in the object code until it finds a RET
instruction. Based on the type of the return instruction, STAKDUMP can tell
whether the current call was NEAR or FAR, and thus whether SS:[BP+4] has a new
code segment or not.

STAKDUMP must assume the presence of a chain of stack frame pointers. Code
generated by the Turbo compiler always maintains this chain by inserting the
instruction sequence

PUSH BP
MOV BP,SP

at the beginning of every procedure and function. If an external assembly
language routine does not set up a stack frame in this way and is active at
the time a runtime error occurs, STAKDUMP will not be able to follow the stack
chain and will either produce garbage or halt with an error of its own.

The disassembly technique places further restrictions that apply only to
external assembly language routines. First, the disassembler cannot deal with
data placed within the code stream. Second, the disassembler assumes that the
return instruction for any routine is at the end of the routine.

STAKDUMP is written primarily in assembly language to save code space.
STAKDUMP.ASM will assemble with MASM 4.0, MASM 5.0 or A86.