(c)PocitoWare
{ Paul Prachyl [71121,2444] }
{ Robert Oberwetter [76367,1205] }
{ This code is released into the Public Domain by the Authors. }

TraceIt


This Arc file contains a series of programs and a pascal unit that when
used in conjunction with Turbo Pascal Version 4, will allow a user to
trace the execution of a pascal program at the procedure level.

This arc file contains the following files:

TraceIt.Doc - This file
TraceUnt.pas - A self contained unit housing the TraceIt Procedure.
FileView.pas - A memory resident turbo3 program that can be used to
view TraceIt.Dat
TraceVw.pas - Include file refrenced by FileView.pas
FileView.com - Compiled version of FileView.pas
Gtrace.exe - Utility program that will insert TraceIt calls.
GunTrace.exe - Utility program that will remove TraceIt calls.


Description

TraceUnt contains a procedure called TraceIt. When called from a pascal
program, TraceIt will write a string value passed to it to a trace file.
That trace file can then be viewed, with FileView, to determine program flow.

Gtrace is a utility program that will read a pascal source file and
automatically insert TraceIt procedure calls at the begining of each
procedure found in the pascal file. These TraceIt procedure calls
will be built with a parameter containing the name of the current
procedure block. Traceit does this by first renaming your pascal
program to .old, reading it and creating a new .pas file.

Gtrace is comment sensative and "unit structure" sensative. It
won't insert traceit calls in comment blocks and it only
inserts traceit calls in the implementation portion of units.
Gtrace will also insert a reference to TraceUnt in the USES statement.

FileView is a memory resident utility that can be used to "view" the
trace file that TraceIt has created. FileView is heavily based on the
excellent routines found in Stay42.arc by Lane Ferris. Once installed,
FileView will allow you to "view" what TraceIt is writing. You may
end the viewing by reaching the end of your trace.dat file or by
pressing escape. TraceIt may be de-installed by pressing Ctrl-F9.



How TraceIt Works:

First, TraceIt looks for an enviroment statement in the form of

TRACEIT=d:\dir\traceit.dat,# where
d:\dir\traceit.dat - is the fully qualified name of
the Trace file that TraceIt will
write to.
# - is the number of iterations TraceIt
will make between open(s) and close(s)
of the Trace file.
if # is 0, TraceIt will open the Trace
file at the initial TraceIt call and
it will be the programmers responsability
to place a call to "CloseTraceIt" to close
the Trace file.
TRACEIT=NO - will cause TraceIt to stop tracing.

If no TRACEIT= statement is found, a default statement of
TRACEIT=C:\TRACEIT.DAT,1 is used.

When TraceIt is first called it will open an empty Trace file. After that
TraceIt will write out the data passed to it until the iteration counter
is reached. At that point TraceIt will close the Trace file. Subsequent calls
will cause TraceIt to open the trace file with the Append option.



What to do:

1. Using the SET command place a TRACEIT environment statement
in the DOS environment.
Ex. SET TRACEIT=C:\TPAS\TRACEIT.DAT,5

2. Run FileView, it will become memory resident and can be executed
by pressing Alt-F9 and de-activated by pressing Ctrl-F9.

3. Run Gtrace, passing it a fully qualified (with path) Pascal file.
This will add TraceIt call statements.

4. Edit your pascal program and add a call to "CloseTraceIt" at the
logical end of your program.

5. Compile your pascal program using Turbo Pascal 4.0.

6. Execute your program.

7. At any time press Alt-F9 to invoke FileView. FileView will display
the contents of the Trace file.

8. After testing has completed use GunTrace to remove TraceIt calls.

9. Edit your pascal program and remove the references to CloseTraceIt and
TraceUnt.


Restrictions and other stuff.

1. When FileView is installed the environment is copied into it's PSP.
Therefore, if you change the TRACEIT environment statement after installing
FileView, it won't be reflected to FileView. DeInstalling FileView and
reinstalling it will pickup the new TRACEIT environment statement.
Remember, the iteration portion of the TRACEIT statement is used only by
the TreacIt procedure and not by FileView. Only the Trace file is important
to FileView.
2. If your Trace file is currently open by TraceIt and you execute FileView,
you will not see what Dos is currently buffering. Using a low iteration
counter, such as 1, can remedy this problem.
3. Gtrace and Guntrace prefix all calls to TraceIt and TraceUnt with {G!},
ex. {G!}TraceIt('ProcedureName');
DON'T remove the {G!} comments if you want to use GunTrace to remove
TraceIt calls.
4. Gtrace requires that the procedure heading for all procedures be on
the same line as the word "procedure".
ex. Procedure First; - is acceptable.
Procedure
First; - is not.
5. GunTrace doesn't remove the reference to the TraceUnt or the call to
CloseTraceIt. This way Gtrace and GunTrace can be used repeatedly on
the same program without the need to add the call to CloseTraceIt each
time.

Use Agreement:
TraceIt is released into the public domain by the authors. TraceIt is
released 'as-is'. The authors disclaim all implicit and explicit
warranties including merchantability and fitness for a particular purpose.
TraceIt is released free of charge and may be distributed in any manner
desired so long as the distributor receives no compensation for it.
Comments, suggestions, money, table dances or whatever should be directed
to the authors listed at the top of this document. If you are interested in
the source code for GTrace or GUntrace, contact the authors.

Credits, Acknowledgements :

Lane Ferris [70357,2716] - Stay42.arc - Turbo3 memory resident code
Jim LeMay [76011,217] - Qwik40.arc - Qwrite utilities
Window30.arc - Window mgmt utilities
David Bennett [74635,6171] - Env.Pas - Dos Environment access code