QTRC Trace Tips

Performance

When a QTRC Trace API is called, the trace conditions for the specified component are always checked. When tracing is not active for the specified component, and the QTRC Trace APIs are called multiple times, there may be a noticeable performance impact. To avoid the performance impact the QtrcGetActiveLevel() API can be used, and the results saved into a variable for later uses. Assume an application program does the following:

    const char *myComp = "MYCOMP";
    unsigned int myCompActLvl;
    QtrcGetActiveLevel(myComp, &myCompActLvl);

The application can use the myCompActLvl variable to quickly check if the component's active trace level is in effect, just prior to calling any of the QTRC Trace APIs that write trace data.

Condition to Check	API Coded Trace Level
`if (myCompActLvl >= QTRC_LEVEL_ERROR)`	QTRC_LEVEL_ERROR
`if (myCompActLvl >= QTRC_LEVEL_INFO)`	QTRC_LEVEL_INFO
`if (myCompActLvl >= QTRC_LEVEL_VERBOSE)`	QTRC_LEVEL_VERBOSE

It is important that the if-condition checks for greater than or equal to the trace level. This is done to keep the same semantics of how the QTRC Trace APIs check the component's active trace level against the coded trace level parameter. The variable should be periodically updated, using the QtrcGetActiveLevel() API, to ensure a current view of the component's active trace level. For example, the variable should be updated in the following conditions:

Upon entry to a program or major function.
After coming out of a wait.
After calling a long-running program or function.
After each iteration of a major loop cycle.

A simplified check of the variable could be used instead, for those cases where the performance impact is less critical, when any type of tracing (ERROR, INFO, or VERBOSE trace) is active:

    if (myCompActLvl != QTRC_LEVEL_NONE)

In some cases, the performance impact of tracing, whether tracing is active or not, is of no concern. This is most often the case for ERROR-level trace points, since error conditions should not normally occur within the application. Namely, the ERROR-level trace points would normally not be reached. In those cases, the QTRC Trace API that writes trace data can be called directly, without using the QtrcGetActiveLevel() API and checking the variable as described above.

Character Data Processing

The QTRC Trace APIs do not convert character data as it is being processed. Hence, it is important to understand and follow certain guidelines, when using character data on various parameters of the QTRC Trace APIs:

Character data should be limited to the invariant character set.
Character data should not contain control characters such as newline, line feed, or carriage return.
Component names should not contain lowercase a through z. Application component names should contain an abbreviated company name along with the application name. Component names starting with an asterisk (*) are reserved for the operating system. Component names starting with Q are reserved for IBM^® licensed programs.
Subcomponent names should not contain lowercase a through z.
Mixed-byte strings that contain DBCS characters should not be used for a Component name or a Subcomponent name.
The format string used by QtrcWriteTextPrintF(), QtrcWriteTextPPrintF(), and QtrcWriteTextVPrintF() APIs is assumed to be in the CCSID of the job.
When an application is given character data that originates from outside the application, the preferred method for tracing that character data is through the QtrcWriteHexDumpF() API.

[ Back to top | QTRC Trace APIs | APIs by category ]