Edit

Share via

How are Trace-If expressions used?

  • Article

To help you understand how Trace-If expressions are used, we provide an example of such expressions that demonstrates the usage and syntax of "begin_wpp config" statements. This example refers to a function TRACE_RETURN, which logs an event if the expression FAILED(HR) is true.

If FAILED(HR) is true, assume that there is a source file that has status ULONG and an event will be logged by calling TRACE_RETURN(Status).

//MACRO: TRACE_RETURN
//
//begin_wpp config
//USEPREFIX (TRACE_RETURN, "%!STDPREFIX!");
//FUNC TRACE_RETURN{LEVEL=ERROR}(EXP);
//USESUFFIX (TRACE_RETURN, "Function Return=%!HRESULT!",EXP);
//end_wpp

#define WPP_LEVEL_EXP_PRE(LEVEL, HR) {if (FAILED(HR)) {
#define WPP_LEVEL_EXP_POST(LEVEL, HR) ;}}
#define WPP_LEVEL_EXP_ENABLED(LEVEL, HR) WPP_LEVEL_ENABLED(LEVEL)
#define WPP_LEVEL_EXP_LOGGER(LEVEL, HR) WPP_LEVEL_LOGGER(ERROR)

In the previous example, notice that, TRACE_RETURN is defined between the begin_wpp config and end_wpp lines. This definition is then followed by the PRE / POST macro and the ENABLED and LOGGER definitions.

The begin_wpp config and end_wpp delimiters define a configuration block that is parsed by the preprocessor. The file that contains the configuration block definition must be scanned by WPP. This file is specified with the -scan:file.extension parameter.

Note For information about -scan and other RUN_WPP options, see WPP Preprocessor.

The following list provides more information about each statement in the example configuration block:

USEPREFIX
Defines a prefix format string to be used when the event is logged. In the example, STDPREFIX is used. For values available with STDPREFIX, see How do I change the prefix output on every trace line?

USESUFFIX
Defines a suffix format string to be used when the event is logged.

FUNC
Defines the name and signature of the trace function. In the example, the function takes one parameter and no format string.

For another example of Trace-If expressions, see the How do I include a trace statement in a C/C++ macro? section.