Rogue Wave banner
Previous fileTop of DocumentContentsIndexNext file

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

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

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:

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:

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

A description of each program line follows:

//1This 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 -DRW_USER_TRACE_LEVEL=8 flag.
//2This 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).
//3This 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.
//4This 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.
//5This 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.
//6This 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.
//7This 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.
//8This macro generates an INFO event for this function. The macro name does not contain the word OBJECT, because this is not a member function.

Previous fileTop of DocumentContentsIndexNext file

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.