TRACE statement

Purpose

Capture a representation of the precise flow of execution in a module.

Syntax

TRACE NEW fname$

TRACE ON

TRACE PRINT string_expr

TRACE OFF

TRACE CLOSE

Remarks

The TRACE statement is used to generate a trace file detailing program flow as execution passes through Labels, plus entry and exit of all Subs and Functions, along with details of passed parameters, etc.  All trace details are written to a named disk file fname$.

TRACE also logs PowerBASIC run-time errors as they occur, to assist with locating program errors.  TRACE can be dynamically started and stopped with the TRACE ON and TRACE OFF statements to enable the programmer to check specific portions of a program without generating volumes of irrelevant trace data.

The five general forms of the TRACE statement are described as follow:

TRACE NEW fname$

TRACE NEW causes a standard sequential trace file (of the specified file name fname$) to be created, deleting any previous file of the same name.

TRACE ON

When a subsequent TRACE ON is then executed, PowerBASIC begins to write pertinent trace information to the trace file.  It will contain a chronological list of every call to an internal Sub/Function, the associated parameter values, and the point at which it was exited.  Further, it will list a label name each time that program execution flows through the label position.

In a test or debugging situation, TRACE, CALLSTK, and CALLSTK$ allow you to easily answer that age-old programming question, "How did I get here?".  TRACE details the entry and exit of every Sub or Function in your program, while CALLSTK simply lists the stack frames that exist above the current level.  TRACE is particularly valuable in pinpointing the area of a program where a fatal machine crash occurs.

TRACE PRINT string_expr

TRACE PRINT writes the value of string_expr to the trace file.  It can be used to record the value of important variables or other information of importance.

TRACE OFF

TRACE OFF temporarily stops output to the trace file.  The trace can be subsequently restarted with another TRACE ON statement.  An implied TRACE OFF is performed when you exit the Sub or Function in which the current TRACE ON was executed.

TRACE CLOSE

TRACE CLOSE permanently detaches the trace file from the stream of trace data.

The TRACE statement can easily create a huge trace file, so caution must be exercised.  Use TRACE ON at the lowest Sub or Function level possible, to keep the output size within reason.

If PBMAIN contains TRACE NEW and TRACE ON statements, and subsequently calls SUB AAA(x&), which in turn calls SUB BBB(y&,a$), which then calls SUB CCC(z&), which encounters a run-time error 5, the trace file might look something like this:

Trace Begins...

 AAA(3)

  BBB(4,string data)

   CCC(5)

   TRACE PRINT printed this user data from CCC()

   ERROR 151 was generated in this thread

   CCC Exit

  BBB Exit

 AAA Exit

Numeric parameters are displayed in decimal, while pointer and array parameters display a decimal representation of the offset of the target value.

Restrictions

TRACE can be invaluable during debugging, but it generates substantial additional code that should be avoided in the final release version of an application.  If the source code contains #TOOLS  OFF, all TRACE statements which remain in the program are ignored by the compiler, and the parameters and expressions are excluded from the compiled program.

To conserve memory requirements in the code, long labels are truncated to 13 characters; however, Sub and Function names are not truncated.

The TRACE statement is "Thread-Aware", displaying only Sub, Function, or Label details from the thread in which it was executed.  You can execute TRACE multiple times, or even in multiple concurrent threads.  However, you must use caution to ensure that each thread uses a unique name for its own trace file.

See also

#TOOLS, CALLSTK, CALLSTK$, CALLSTKCOUNT, FUNCNAME$, PROFILE

Example

#TOOLS ON

FUNCTION PBMAIN

  TRACE NEW "tracelog.txt"

  TRACE ON

  x& = 3

  CALL AAA(x&)

  TRACE OFF

  TRACE CLOSE

END FUNCTION

SUB AAA(x&)

  INCR x&

  CALL BBB(x&,"string data")

  ' More code

END SUB

SUB BBB(y&,a$)

  INCR y&

  CALL CCC(y&)

END SUB

SUB CCC(z&)

  TRACE PRINT "TRACE PRINT printed this " + _

    "user data from " + FUNCNAME$ + "()"

  ERROR 151 ' Trigger a run-time error

END SUB