6.3 Using Trace

These are the basic steps required to generate trace output:

Put set declaration macros in your code to make the functions traceable. (See Section 6.4, "Using Set Declaration Macros.")
Put trace event macros in your code to generate trace output. (See Section 6.5, "Using Event Generation Macros.")
Create at least one trace event client to process the trace output. (See Section 6.7, "Using Trace Clients.")
Choose a combination of compile time and runtime options for controlling the severity levels of the events reported. (See Section 6.10, "Controlling Trace Output.")
Define environment variables to turn sets on or off at runtime. (See Section 6.4.4, "Setting Environment Variables for Event Sets.")

Example 52 illustrates the steps required to generate trace output in a global function. The following code is taken from examples\thr0200osfam\trace\helloTrace.cpp.

Example 52 -- Generating trace output

#define RW_USER_TRACE_LEVEL 8                             //1

#include <rw/trace/trace.h>                               //2

  // Create a trace client that logs messages to cerr
  RWTraceOstreamClient myTraceClient(cerr);               //3

int main()
{
  // Declare the function as traceable and use
  // the environment variable named "main" to control
  // trace event generation from this function
  RW_USER_TRACEABLE_FUNCTION("main");                     //4
 
  // Connect the client to the singleton manager
  myTraceClient.connectToManager();                       //5

  // Generate some trace events
  RW_USER_TRACE_DEBUG("This is a debug message");         //6
  RW_USER_TRACE_INFO("This is an informational message"); //7

  return 0;
}

A description of each program line follows:

//1	Set the trace level to maximum (8). This ensures that all trace events are compiled into the executable. If you define the trace level in the program, as shown here, this macro must be set before including `trace.h`. This macro could also be set on the command line when the program is compiled, using the `-D`RW_USER_TRACE_LEVEL=8 flag.
//2	Include the trace umbrella header.
//3	Create a client that logs messages to `cerr`. The function is declared global, so that all events from `main()` are processed before the client's destruction.
//4	This is a set declaration macro. It declares the function as traceable and assigns it the name `main`, which is used as the environment variable name to toggle the generation of trace events in this function. This macro also generates the function ENTRY and EXIT events.
//5	Connect the client to the trace manager.
//6	This is an event generation macro. It generates a DEBUG trace event.
//7	This is also an event generation macro. It generates an INFO trace event.

To see output, set the main or rw_user environment variable to ON. rw_user works because the main() function is declared on line //3 to be a member of the predefined rw_user package set. The program produces this output:

ENTRY|helloTrace.cpp:10|main> Entry
DEBUG|helloTrace.cpp:19|main> This is a debug message
INFO|helloTrace.cpp:20|main> This is an informational message
EXIT|helloTrace.cpp:25|main> Exit