Trace Function

Programmers use tracing to obtain low-level information about how an application runs, with the information often used for debugging purposes to understand why a program does not execute as expected. CSPro offers limited tracing functionality for two objectives: logging user-generated information and tracking executed statements. Tracing messages can be displayed in a window or saved to a file.

Activating and Disabling Tracing

// turns on tracing and outputs messages to a window
trace(on);

// turns on tracing and appends messages to "filename"
trace(on,"filename");

// turns on tracing, clears any contents in the file, and writes messages to "filename"
trace(on,"filename",clear);

// turns off tracing, closing all open trace windows or files
trace(off);

It is possible, by calling the trace function twice, to send messages to both a window and a file. If the filename does not contain a directory, the file will be placed in the application folder. On mobile devices, it is only possible to trace to a file and any trace statements output to a window will be ignored.

Logging User-Generated Information

To send a message to the trace log, simply pass a string to the trace function using any message formatting options (like used by the errmsg function).

if distance > 100 then
trace("distance (%d) > 100!",distance);
endif;

Tracking Executed Statements

Occasionally a programmer wants to observe how logic statements are executed, particularly when the logic behaves in a manner inconsistent with the programmer's expectations. The trace window or file can display each line of logic as it is executed. Because in some applications this may be a very large number of statements, the programmer must specify what elements of the logic should be outputted:

// logic statements after this point will be outputted
set trace;

// same as above
set trace(on);

// logic statements after this point will not be outputted
set trace(off);

The set trace statement indicates to CSPro that logic statements should or should not be outputted but the statements will only be outputted if tracing is activated, thus the trace function and set trace statements must be used together.

Example

trace("There is no trace window open so this message is discarded");

// opens the trace file and clears previous contents
trace(on,"trace.txt",clear);

trace("This message appears in the file");

trace("Complex strings can be outputted using errmsg-style formatting; e.g., e = %0.3f",exp(1));

// closes the trace file
trace(off);

// opens the trace file and now messages will be appended to the end of the file
trace(on,"trace.txt");

set trace;

numeric value = 10;

if value > 10 then
errmsg("A");
elseif value < 10 then
errmsg("B");
else
errmsg("C");
endif;

errmsg("This statement will appear on the trace window");

set trace(off);

errmsg("This statement will not appear on the trace window");

Trace Output

As the following trace results show, the output for conditional statements (e.g., if) and loops (e.g., do) is limited. Trace results show the line numbers to the left of the executed statements.

Trace started at 02/03/11 20:28:35

TRACE   This message appears in the file
TRACE   Complex strings can be outputted using errmsg-style formatting; e.g., e = 2.718

Trace stopped at 02/03/11 20:28:35
Trace started at 02/03/11 20:28:35

31   :  numeric value = 10;
33   :  if value > 10 then
38   :  errmsg("C");
41   :  errmsg("This statement will appear on the trace window");
43   :  set trace(off);

Trace stopped at 02/03/11 20:28:35