6.5 Using Event Generation Macros

Event generation macros are used to actually generate the trace events in your code. You can use as many event generation macros as you want in any function that has been declared traceable. The event generation macros come in two varieties, one for member functions and the other for global, static member, and friend functions.

Each macro corresponds to a trace severity level. See Section 6.1.3 for an explanation of trace severity levels.

NOTE: No ENTRY/EXIT macros are provided, because these trace events are generated by the function declaration macros.

The macros take a msg parameter, which is a string containing the message to be logged. See Section 6.5.3 for information on how to include variables in the output message.

6.5.1 Macros for Global Functions

RW_USER_TRACE_FATAL("msg")

RW_USER_TRACE_ERROR("msg")

RW_USER_TRACE_WARNING("msg")

RW_USER_TRACE_INFO("msg")

RW_USER_TRACE_TEST("msg")

RW_USER_TRACE_DEBUG("msg")

These macros are normally used in global, static member, and friend functions, which don't require an object for invocation. The macros can be used in member functions, but the trace message will not include the address of the current object.

6.5.2 Macros for Member Functions

RW_USER_TRACE_OBJECT_FATAL("msg")

RW_USER_TRACE_OBJECT_ERROR("msg")

RW_USER_TRACE_OBJECT_WARNING("msg")

RW_USER_TRACE_OBJECT_INFO("msg")

RW_USER_TRACE_OBJECT_TEST("msg")

RW_USER_TRACE_OBJECT_DEBUG("msg")

These macros with the word OBJECT in their names are used in member functions. The trace message includes the address of the object that the member function is called on. Using these macros in non-member functions results in compile errors.

6.5.3 Including Variables in Trace Messages

The Execution Tracing package provides a helper macro to allow the use of streaming syntax in trace messages. The RW_STREAM_TO_STRING(stream) macro allows the concatenation of strings and variables, much like the insertion operator for an ostream works. Here's an example:

RW_STREAM_TO_STRING( "The number of cups is " << numCups << "." );

Assuming numCups is in scope and has the value 5, the macro expands to the string "The number of cups is 5." This macro is normally used as the parameter to the event generation macros:

RW_USER_TRACE_INFO( RW_STREAM_TO_STRING( "The number of cups is" 
                                           << numCups << "." ) );

6.5.4 Trace Macros Example

Example 53 uses the set declaration macros with the event generation macros in a typical class. A more comprehensive example can be found in examples\thr0200osfam\trace\example1.cpp.

Example 53 -- Declaring trace event sets

// File: CoffeeRobot.h

#define RW_USER_TRACE_LEVEL 8                                   //1
#include <rw/trace/trace.h>

RW_USER_DECLARE_TRACEABLE_CLASS(CoffeeRobot)                    //2

Class CoffeeRobot
{
   CoffeeRobot() {
       RW_USER_TRACEABLE_INLINE_MEMBER("CoffeeRobot_ctor",CoffeeRobot);//3
   }

   void makeCoffee(int cups);
};


// File: CoffeeRobot.cpp

#include "CoffeeRobot.h"

RW_USER_DEFINE_TRACEABLE_CLASS(CoffeeRobot)                     //4

void
CoffeeRobot::makeCoffee(int cups)
{
  RW_USER_TRACEABLE_MEMBER("CoffeeRobot_makeCoffee", 
                            CoffeeRobot)                        //5

  RW_USER_TRACE_OBJECT_DEBUG( 
        RW_STREAM_TO_STRING("Number of cups = " << cups ) );    //6
  
. . . 
}

void globalHelper( void )
{
  RW_USER_TRACEABLE_FUNCTION( "globalHelper" );                 //7
  
  RW_USER_TRACE_INFO("I'm here to help");                       //8
}

A description of each program line follows:

//1	This line sets the maximum trace level to compile into the code. To compile in all the trace macros, the level is set to the maximum 8 (Entry/Exit). You could also define the trace level on the command line for your compiler, using the `-D`RW_USER_TRACE_LEVEL=8 flag.
//2	This macro declares the class *CoffeeRobot* as traceable. The declaration enables you to set an environment variable `CoffeeRobot` to ON or OFF to toggle tracing for this class at runtime. Remember to use the appropriate `DEFINE` macro in the implementation file (see Section 6.4.2).
//3	This macro declares the constructor as traceable and a member of the *CoffeeRobot* class (for tracing purposes). The declaration enables you to set an environment variable `CoffeeRobot_ctor` to ON or OFF to toggle tracing for this function at runtime. This macro automatically generates ENTRY and EXIT events when this function is called. Note the use of the `INLINE` version of the macro, because this constructor is defined inline.
//4	This macro matches the `DECLARE` macro in line `//2`. This `DEFINE` macro must appear in an implementation file exactly once for each class declared as traceable. If this macro is not used, the linker reports that some symbols are undefined.
//5	This macro declares the member function `makeCoffee()` as traceable and as a member of the *CoffeeRobot* class (for tracing purposes). The macro also enables you to set an environment variable `CoffeeRobot_makeCoffee` to ON or OFF to toggle tracing for this function at runtime. The macro automatically generates ENTRY and EXIT events when this function is called.
//6	This macro generates a DEBUG event for this member function. Because it is a member function, the `OBJECT` version of the macro is used. This macro uses the `RW_STREAM_TO_STRING` macro to include the value of the parameter in the trace message.
//7	This macro declares the function as traceable and enables you to set an environment variable named `globalHelper` to ON or OFF to toggle tracing for this function at runtime. ENTRY and EXIT events are generated automatically when this function is called. Note the macro used for this global function.
//8	This macro generates an INFO event for this function. The macro name does not contain the word `OBJECT`, because this is not a member function.