The DPRINTF macro

The DPRINTF macro directly marks a tracepoint in the code. It formats a trace message and specifies the threshold for the tracepoint.

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 DataBlade API also provides the GL_DPRINTF macro for formatting internationalized trace messages. For more information, see the HCL Informix® GLS User's Guide.

The following example uses DPRINTF to insert a tracepoint of the funcEntry trace_class (which Figure 1 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));

The trace message consists of the literal text, the print formatting directives, and the expressions for the print formatting directives.

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 tracepoint threshold determines which tracepoints generate output, based on the current trace levels of the trace class. If a tracepoint threshold is not greater than the current trace level, the database server writes the associated trace message to the trace-output file.

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"));

The maximum number of trace levels is the largest non-negative integer representable on the platform.