DebugTrace

Controls and customizes the WIL debugging trace logs.

Syntax:

DebugTrace ( request-code [ ,parm1 [, parm2 ]] )

Parameters:

(i) request-code: numeric code indicating desired action (see below)

(s/i) parm1 [optional] depends on requestcode

(s/i) parm2 [optional] depends on requestcode

Returns:

(i) DebugTrace mode state: 0 = Off 1 = Statement by statement Tracing enabled.

Note: DebugTrace will create a file showing each line executed and the return value of the line. It will consume considerable processing time and is generally reserved for particularly hard-to-debug problems.

DebugTrace will append to the end of the file you specify. You may want to delete the file, if it already exists.

To debug into a 'Called' WinBatch script, User Defined Function or User Defined Subroutine, make sure to add the corresponding debug command, to the 'called script', User Defined Function or User Defined Subroutine.

IntControl (71, p1, p2, 0, 0) can be used to dump WIL and extender function tables to the debug log file.

Request codes:

Note: For requests which take a file name, if "filename" is "*DEBUGDATA*" then debug output will be written to the system debugger using the OutputDebugString Windows API (see WIL DebugData function).

Request codes fall into one of three categories.

Modes	These control the DebugTrace line by line logging.
Mode Option Flags	These control the log file names, formatting, and content.
Immediate Action Codes	These cause additional data to be immediately written to the Debug Trace log file.

Modes:

Request code	Meaning	Parm1	Parm2
-1	Returns previous trace mode
0 (@OFF)	Stops statement by statement debug tracing.
1 (@ON)	Starts or Resumes statement by statement debug tracing.	Optional filename to set or change the current debug trace log file. If no previous debug trace file has been specified, then a filename is required. Output filename may be specified by a previous @ON, 10, 100, or 101 requestcode.
10	Same as 1 (@ON) with the addition that if the output file exists, one attempt will be made to delete the file before continuing.
22	Allow DebugTrace continuation (inherit the debug mode from the caller). By default, when the code enters a UDF, UDS or Call'ed script file, statement by statement debugging is suppressed until the script returns. Adding DebugTrace(22) to a UDF, UDS, or called script will resume statement by statement debugging IF it was active on entry.

Mode Option Flags:

Request code	Meaning	Parm1	Parm2
100	Specify output file name for subsequent debug trace logging.	Required filename parameter
101	Same as 100 with the addition that if the output file exists, one attempt will be made to delete the file before continuing.
102	Dump WIL variable table to the debug trace log file when a terminal error occurs. ( Replaces option 2 in version 2006A and older)	0 - Do NOT dump variable table to debug trade log file. (default) 1 - Dump WIL variable table to the debug trace log file if a terminal error occurs.
103	Dump internal debug data for each keyword lookup.	0 - Do NOT dump debug data for keyword lookups. (default) 1 - Dump debug data for keyword lookups.
104	Suppress statement timestamp information.	0 - Include statement timing information (default). 1 - Suppress statement timing information. note: This option is useful when creating multiple debug trace log files that you plan to compare with one another using a file-compare type program. As statement timing will vary slightly, this option allows statement timing information to be skipped to avoid non-relevant differences in the generated log files.

Immediate Action Codes:

Note: DebugTrace(@OFF) does not suppress the execution of these codes.

In the case of where a code would output information to the debug trace log file, if the file is defined, then an attempt will be made to write data to it.

Request code	Meaning	Parm1	Parm2
200	Reset. Turns off statement by statement tracing, and resets all the Mode Option Flags to the default values	Optionally set new debug trace file name. If there is no optional parm parameter, or it is set to a null string, the output filename parameter will be cleared.
203	Write a string to the debug trace log file.	Specifies a string to be written to the debug trace log file.
204	Write a string, surrounded by "$" signs to the debug trace log file.	Specifies a string to be written to the debug trace log file.
205	Dump WIL and loaded extender function tables to the debug trace log file.
206	Dump WIL variable table to the debug trace log file. Includes values for simple variable types. Note: Only the first part of long strings will be dumped. Complex variable types (Arrays, Binary Buffers, etc) will not have variables dumped.
207	Dump stack info to the debug trace log file.
208	Dump machine information block.
277	Dump formatted internal debugging information to the debug trace log file. Much of the same information as provided by IntControl 77 is available.	Missing or "" - Display select internal information Numeric value - Displays more detailed information regarding a specific IntControl 77 request.

Example:

DT_OFF = 0
DT_ON = 1
DT_ON_DEL = 10
DT_RESUME = 22
DT_FILENAME = 100
DT_FILENAME_DEL = 101
DT_VARS_ON_ERR = 102
DT_KEY_LOOKUP = 103
DT_TIMING = 104
DT_RESET = 200
DT_LOG = 202
DT_LOG_MARK = 205
DT_VARTABLE = 206
DT_STACK = 207
DT_HEADERS = 208
DT_DEBUGINFO = 277
#DefineFunction MyUDF()


   DT_RESUME = 22
   DebugTrace( DT_RESUME )
   ccc = 1
   ccc = 2
   ccc = 3
   ccc = 5
   Return
#EndFunction
a = 1
; start debug tracing.
; if the output file exists, one attempt will be made to
; delete the file before continuing.
DebugTrace( DT_ON_DEL , "DTT_TEST.TXT" )
aa = 1
aa1 = 1
aa2 = 2
aa3 = 3
aa4 = 4
zz = MyUDF ()
bb1 = 1
; Display select internal information
DebugTrace( DT_DEBUGINFO )
; tab-delimited list of application function table entries
DebugTrace( DT_DEBUGINFO , 101 )
bb2 = 2

DebugTrace

Syntax:

Parameters:

Returns:

Example:

See Also: