TRACE Version 1.0

Copyright (c) 1989 Richard W. Prescott
All Rights Reserved



Files in this package:

TRACE.DOC - This file
TRACE.PAS - TRACE Version 1.0 (Pascal/Assembly Source)
TRACE.TPU - TRACE Version 1.0 (Compiled w Turbo Version 5.0)
TRACE.TP4 - TRACE Version 1.0 (Compiled w Turbo Version 4.0)
DEMOTRC.PAS - Main demonstration using TRACE
NESTTRC.PAS - Demonstration using a nested Trace routine



The following topics are discussed in this file:

1. Overview
2. Using TRACE
3. Disclaimer
4. Terms and Conditions
5. TP&Asm/TP&Asm-M




1. Overview


This package provides a powerful "trap on condition" debugging
capability for use with Turbo Pascal Versions 4.0 and 5.0. Using
TRACE, you can designate any standard Pascal procedure which is
either 1) global, or 2) local to the current procedure, to be
executed between every two program instructions. This means that
you can trap any condition which can be described using Pascal
statements (as well as Inline and TP&Asm assembly statements),
including:

o One or more Pascal variables or absolute memory locations
changed

o One or more Pascal variables or absolute memory locations
equal to specified value(s)

o Value of Pascal variable between two other Pascal variables
or within specified range

o CPU register equal to specified value

(etc)

You can designate precisely where within your program to activate
and deactivate the trace, and different parts of your program can
have different Trace routines. When the specified condition is
detected, you can specify exactly what action should be taken, again
using any action which you can describe using Pascal statements,
including:

o Write a specified list of variables to the screen and continue
tracing

o Write a specified list of variables to a file and continue
tracing

o Write the current Cs:Ip and register values to the screen or
a file and continue tracing

o Release control to the IDE or an external debugger, and use
the features of the debugger to inspect variables and/or step
further through the program

o Display message and wait for response (Readln/ReadKey). Based
on response, reset certain variables and/or continue tracing,
switch to the IDE or an external debugger, or halt execution

(etc)


TRACE can be used from within the Version 4.0 or 5.0 Integrated
Development Environment (IDE), or within a program which is
compiled to disk and is run from DOS or any standard external
debugger.

In a typical application, a program which is not operating properly
exhibits a certian unexpected behavior, say for example the value
of the variable NeverZero somehow becomes zero and eventually causes
a Run-Time divide error. Using the following simple trace routine,
you can easily find the statement that is causing the problem:

PROCEDURE CheckForZero;
BEGIN
IF NeverZero = 0 THEN TRelease; {- Release to Debugger -}
TReturn; {- Else return from Trace -}
END; {PROCEDURE CheckForZero}

If you are using the Version 5.0 IDE, you will be dropped into the
IDE debugger at the first Pascal line following the line where
NeverZero was set to zero. You can now examine other variables
and/or use F7/F8 etc to trace further. If you are using an external
debugger such as DEBUG, D86, or Turbo Debugger, you will be dropped
into the external debugger at the first assembly statement following
the statement which set NeverZero to zero.

Note that any program which is compiled with TRACE can also be run
directly from DOS, in which case TRelease will simply deactivate the
current Trace. This would normally be useful only if your Trace
routine writes values to the screen or a file.




2. Using TRACE


To use this package, simply place "TRACE" in the uses clause of
the program or unit you are debugging, construct an appropriate
Trace routine, and specify where the Trace routine will be active
using TraceOn and TraceOff. These steps are described at greater
length below. For examples of working trace routines, please see
the files DEMOTRC.PAS and NESTTRC.PAS.

If you find this package useful you may wish to move it into your
TURBO.TPL file. Please see your reference manual for instructions
on using the utility program TPUMOVER.


Constructing a Trace Routine

The Trace Routine should be a Procedure which takes 0 parameters
and which IN ALL CASES exits with a call to the (assembly) inline
directive TReturn or to the procedure TRelease. The body of the
procedure should check for a user-defined condition and exit via
TReturn until that condition is detected. The routine should then
take a user-defined action and exit with TReturn (to continue the
Trace), TRelease (to transfer control to the Version 5.0 IDE or an
external debugger), or Halt (to terminate the program).

Thus:

PROCEDURE TraceProc;
BEGIN
IF <..user-defined condition..>
THEN BEGIN
<..user-defined trace action..>
END;
TReturn; {- IN ALL CASES exit via TReturn or TRelease -}
END; {PROCEDURE TraceProc}

The Trace procedure may freely reference any Pascal identifiers
which are known at the point where the Trace is activated. If the
Trace procedure references ANY identifier which is not global,
however, then it MUST be placed immediately preceding the BEGIN
block in which it is activated. Thus, in the following:

PROCEDURE GlobalProc;
Var Local1 ...
PROCEDURE NestedProc;
Var Local2 ...
PROCEDURE MoreNested; BEGIN .. END;
PROCEDURE NeedToTrace;
Var Local3 ...
Position
PROCEDURE TraceProc; BEGIN .. END; <--- Trace Procedure
BEGIN {PROCEDURE NeedToTrace} Here
:
TraceOn(@TraceProc);
:
END; {PROCEDURE NeedToTrace}

TraceProc must be positioned as indicated, local to the procedure
in which the Trace is activated. It can then make reference to
any of the local variables shown above. If the Trace procedure
references only global identifiers, then its placement is not
crucial, except that it must reside in the same module (program
or unit) as the block in which it is activated.


Activating the Trace

Tracing is activated by a call to TraceOn, as follows:

TraceOn(@TraceProc);

where TraceProc is the name of the Pascal Trace procedure, and
"@" is the "address of" operator. As noted above, the Trace
procedure must reside in the same module as the block in which it
is activated, and must contain at least one TReturn call before the
standard procedure exit code. If an invalid Trace procedure is
detected, a Run-Time Error will be generated at the invalid TraceOn
call.

There can be at most one Trace active at any one time. Attempting
to activate a second simultaneous Trace will also cause a Run-Time
Error.


Deactivating the Trace

Tracing can be deactivated either from within the subject code or
from within the Trace procedure itself by calling the procedure
TraceOff, which takes no parameters:

TraceOff;

Every trace procedure must be deactivated by the end of the block
(procedure or function) in which it is activated, except that a
global Trace routine which is activated in the main program block
does not need to be deactivated. Normal or abnormal (Run-Time
Error) program termination automatically terminates the Trace and
restores the Interrupt 01 vector.

Tracing can also be deactivated by transferring control to the IDE
or an external debugger using the procedure TRelease, which takes
no parameters:

TRelease;

The debugger will assume control within the subject code (not the
Trace routine) at the next Pascal line (for the Version 5.0 IDE
debugger) or the next assembly statement (for all other debuggers)
to be executed.

TRelease should only be called from within an active Trace routine.
Attempting to call TRelease in any other situation will generate a
Run-Time Error.

Finally, if the IDE or an external debugger takes control as a
result of a conditional break it will reinstall its own Interrupt
01 handler, which effectively terminates the trace. It follows
that although you can effectively use both conditional breaks and
Trace routines in the same program, you can not automatically
restart from a conditional break with Trace active. You can if
you wish insert a TraceOff and another TraceOn following the
conditional breakpoint to resume tracing after the break.


Run-Time Error messages

This package includes an interesting feature in that it attempts
to determine if it is being used correctly. If an invalid Trace
procedure or an attempt to "nest" TraceOn calls is detected, the
TRACE unit will display a description of the error and wait for you
to press a key. After you press any key, a Run-Time error message
will display the Segment:Offset of the invalid TraceOn call. If
you were executing from the Version 5.0 IDE, the invalid call will
be highlighted and the cursor will be positioned automatically at
the beginning of the line containing it. (If you were executing
from DOS, the Version 4.0 IDE or an external debugger, you can
load the program into the IDE and use the Find Error option as
described in your reference manual). Note that unlike the Version
5.0 RunError statement, this system can detect an error from within
a {$D-} Unit, and it signals the Run-Time error address of the
invalid procedure CALL rather than the address (within the Unit)
where the error was detected. The error displayed for an invalid
TraceOn or TRelease call is always number 204, "Invalid Pointer
Operation".

While it is hoped that this precaution will help to keep you from
"shooting yourself in the foot" with this package, please note that
it is impossible to prevent all possible user errors. In particular,
the TRACE unit cannot detect invalid TReturn calls. TReturn should
only be used within a valid Trace procedure, and attempting to use
it in any other situation will almost certainly cause a program or
system crash.




3. DISCLAIMER OF WARRANTY


This software and accompanying documentation are provided "as is"
and without warranties as to performance or merchantability.

This package is provided without any express or implied warranties
whatsoever. Because of the diversity of conditions and hardware
under which this package may be used, no warranty of fitness for a
particular purpose is offered. The user is advised to test the
package thoroughly before relying on it. THE USER MUST ASSUME THE
ENTIRE RISK OF USING THE PACKAGE.




4. Terms and Conditions


TRACE Version 1.0 is copyrighted as indicated above. You may
however share this package and/or upload it to bulletin boards
as long as no fee is charged. User's groups and PD/shareware
distributors may charge a nominal fee, not to exceed $8, provided
it is accurately represented as payment for their services, not
payment for the software. In any case, the original unmodified
files must all be present.

There is no user fee requested for use of this package. If you
like it, send me a message about it. Please report problems or
suggestions to me at the address listed in section 5, or to my
CompUServe mailbox [76656,2476].

If you REALLY like it, consider registering TP&Asm (described in
the following section). While it might be possible to convert this
package into standard inline and external statements, it would not
have been developed without TP&Asm. By removing the restrictions
on when and where you can use assembly language, TP&Asm makes it
easy to design truly innovative Pascal & assembly applications.
(Admittedly, TRACE is an unusual application that uses techniques
you may not need in your programs. But TP&Asm will simplify the
design of ALL your assembly projects, whether unusual or routine).




5. TP&Asm/TP&Asm-M


TP&Asm is a small assembler which runs Turbo 4.0/5.0 (Integrated
Environment or TPC) as a subprocess and permits you to place
assembly language statements directly into your Pascal source code
in blocks beginning with the keywords "Assemble" and/or "Internal".

TP&Asm provides the convenience and flexibility of having "live"
assembly language in your programs which can be modified and
immediately recompiled with no need to exit and reassemble. You
have complete freedom to place assembly language anywhere in your
program, freely mix Pascal and assembly blocks, freely transfer
between Pascal and assembly blocks via Call/Jump/Loop/Goto to any
Pascal or assembly label, make direct Call, Jmp and Offset
references to Pascal Proc/Functions, and make simplified Pascal
style references to your Pascal and assembly variables and
parameters. Units compiled with TP&Asm can be distributed and
Used independent of TP&Asm.

The resulting ASSEMBLY Development Environment is identical to your
PASCAL Development Environment. It provides fast assembly with no
additional disk access, and reports assembly syntax errors on the
standard Turbo error line with cursor placed on the error. It
accepts the standard syntax of both MASM and A86, but also provides
certain enhancements such as the placement of named data in the
Code Segment.

With Turbo Version 5.0, you can trace your assembly code line by
line in the IDE. Using the record variable CPU defined in the unit
ASMWATCH (included), you can Watch, Evaluate, and Modify the CPU
registers and flags during the trace.

TP&Asm Version 2.0 can be purchased from me at the address given
below for $49 plus $3 P&H.

A shareable Memory Mode version called TP&Asm-M is also available.
The distinction between TP&Asm and TP&Asm-M is that TP&Asm-M is
intended for developing and debugging assembly language in the IDE,
but not for final compilation. You can compile to Memory (with the
standard Turbo style interactive syntax error detection) and Trace
your assembly code in the IDE with full capability to Watch,
Evaluate, and Modify the CPU registers and Flags - then convert to
INLINE or EXTERNAL after the code is fully developed. TP&Asm-M's
INTERNAL statement and its support of the standard syntax of MASM,
A86, and INLINE.COM simplifies this conversion.

The TP&Asm-M distribution disk can be ordered from me for $5 plus
$3 P&H, with the $5 being credited toward subsequent registration
of TP&Asm or TP&Asm-M. It can also be downloaded from the IBMPRO
or BPROGA forums on CompUServe. Look for the archives TP-ASM and
TPA2-R ( May be ".ARC" or ".ZIP" ). Registration for TP&Asm-M is
$19.


To order TP&Asm, please send a check or money order payable to:

Richard W. Prescott
724 Sauk Ridge Trail
Madison, WI 53705

Please include the following information:

1. Full Version number of the Turbo Pascal compiler you now use.

2. Your registration number for that compiler.

3. If you obtained TP&Asm-M from a bulletin board:
3a. Area code and phone number of that bulletin board
3b. Full Version number of the TP&Asm-M version you have
3c. Directory Date of the README file





TRACE.TPU was compiled and assembled using TP&Asm Version 2.0
running Turbo Pascal Version 5.0.
TRACE.TP4 was compiled and assembled using TP&Asm Version 2.0
running Turbo Pascal Version 4.0.