The DPRINTF macro

The syntax for DPRINTF is as follows:

DPRINTF(trace_class, threshold, (format [, arg]...));

These syntax elements have the following values:

trace_class

Either a trace-class name or the trace-class identifier (an integer value) expressed as a character string.

threshold

A non-negative integer that sets the tracepoint threshold for execution.

format

A printf-style output format that formats the trace message and can include print formatting directives.

arg

An expression to be evaluated for output. It provides the value for a print formatting directive in the format argument.

The following example uses DPRINTF to insert a tracepoint of the funcEntry trace_class (which Creating the funcEntry trace class defines) after the doAbigPiece() function executes:

result = doAbigPiece(x, "x location");
DPRINTF("funcEntry", 50,
   ("After calling doAbigPiece with x = %d and %s \
      result = %f", x, "x location", result));

To determine the value of a trace-class identifier, you can query the systraceclasses system catalog table for the classid column. The following SELECT statement obtains the trace-class identifier for the funcEntry trace class:

SELECT classid FROM informix.systraceclasses
WHERE name = 'funcEntry';

If the trace-class identifier for the funcEntry trace class is 42, the following DPRINTF call performs the same task as the preceding DPRINTF call:

result = doAbigPiece(x, "x location");
DPRINTF("42", 50,
   ("After calling doAbigPiece with x = %d and %s \
      result = %f", x, "x location", result));

The simplest tracing scheme is to have only two trace levels:

• Trace level = 0

  No tracing occurs.

• Trace level > 0

  Any tracepoint with a threshold greater than zero (0) prints. All others do not.

A more complex scheme can have four states: no tracing, light tracing, medium tracing, and heavy tracing. As an example, suppose you want to define the following trace levels for the funcEntry trace class.

Tracing level	Threshold values	Sample DPRINTF call
None	0	None
Light	1 to 10	DPRINTF("funcEntry", 1, ("Entering doTheJob: the main function"));
Medium	11 to 20	DPRINTF("funcEntry", 11, ("Entering doAbigPiece: a top-level \help function"));
Heavy	>= 20	DPRINTF("funcEntry", 21, ("Entering doAlittlePiece: an often-called \helper"));