DataBlade API Programmer's Manual

DataBlade API Programmer's Manual
Chapter 10: Tracing

Home Contents Index Master Index New Book

Putting Traces into Code

To insert trace messages into code, use the DPRINTF macro or the tprintf() function. The simpler way is DPRINTF, which directly marks a tracepoint in the code. The tprintf() function works together with the tf() function to allow computation to determine whether a tracepoint is active.

The DPRINTF macro

The syntax for DPRINTF is as follows:

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

Syntax elements have the following values:


trace_class	is either a class name or the class ID integer value expressed as a character string.
threshold	is a non-negative integer setting the statement threshold for execution.
format	is a printf-style output format.
arg	is an expression to be evaluated for output. It corresponds to a print formatting directive in the format argument.

To determine the value of a class ID, query the classid column of the systraceclasses system catalog table.

As an example, consider four levels of tracing: none, light, medium, and heavy. One way to define four levels is to define a trace level of 0 as no tracing, levels 1 to 10 as light, levels 11 to 20 as medium, and any value above 20 as heavy.

For light tracing, insert the following line in the code:

DPRINTF("funcEntry", 1,
	("Entering doTheJob: the main function"));

For medium tracing, insert the following:

DPRINTF("funcEntry", 11,
	("Entering doAbigPiece: a top level help function"));

For heavy tracing, insert the following:

DPRINTF("funcEntry", 21,
	("Entering doAlittlePiece: an often-called helper"));

The following example uses the trace class name ("show_piece"):

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

The following example uses the trace class ID:

mi_integer
doAlittlePiece(mi_string *inparam)
	{
	DPRINTF("42", 21,
			("Entering doAlittlePiece with inparam =%s",
			inparam));
	}

Trace Blocks

In some cases, you might need to perform some computing before you decide whether to output certain trace data. To accomplish this computing, use the tf() and tprintf() functions to insert a trace block that outputs a result in a trace message. The tf() function serves as a threshold check or guard that protects a block of code. This function returns a Boolean result; it is TRUE if the current class level is greater than or equal to the threshold.

The syntax of the guard function is as follows:

tf(trace_class, threshold)

For a trace output statement without the guard inputs, use tprintf(). Its syntax is as follows:

tprintf(format [,arg]...)

These two new constructs might be combined with conventional C structures. The following example is typical:

if(tf ("chck_consist", 950))
	{
		x = fastScan(aList, y);
		consFactor = checkRconsit(x, bList);
		tprintf("...in doWork: x = %f and consFactor = %f",
			x, consFactor);
	}

DataBlade API Programmer's ManualChapter 10: Tracing Home Contents Index Master Index New Book

Putting Traces into Code

The DPRINTF macro

Trace Blocks

DataBlade API Programmer's Manual
Chapter 10: Tracing

Home Contents Index Master Index New Book