Trace information in the C codebase

This section describes trace and logging in the C codebase. It shows you how to enable WebSphere MQ Everyplace trace on PocketPC and PocketPC2002 devices and emulators.

Information on trace and logging is organised under the following headings:

Trace architecture

In WebSphere MQ Everyplace, trace is configured globally. This means that trace is enabled for the device, and when enabled, all C WebSphere MQ Everyplace applications generate trace.

You can configure the location where you want trace files to be written. Each application generates a unique file in the form MQEnnnnn.trc, where "nnnnn" is the process identifier of the application. WebSphere MQ Everyplace trace files are written in a binary format to minimise their size. You can either send these binary trace files directly to an IBM Service Representative to decode them or, alternatively, use the MQenativeTraceFormatter.exe utility provided with WebSphere MQ Everyplace. This utility runs on Windows, but does not run on PocketPC. It takes the trace file as an argument and prints the decoded output to standard out. The output can be captured in a file by running a command, such as:

MQenativeTraceFormatter.exe AMQ12345.trc > AMQ12345.txt

This will decode the file AMQ12345.trc and place the output in a file called AMQ12345.txt.

Configuring trace in the C codebase

Trace is controlled on the PocketPC via entries in the "Windows Registry". These trace values are under the
HKEY_LOCAL_MACHINE\SOFTWARE\IBM\MQe\CurrentVersion\Trace key. You can set the values in a number of ways:

For information on the mqeTrace_setOptions function, see the C Programming Reference on the product CD. If you set the value manually or use a .Reg file, all values should be of type REG_SZ. WebSphere MQ Everyplace supports the following values:

Table 1. Trace values supported in WebSphere MQ Everyplace

Value Name Supported values Description
Enable Yes or no Turns trace on and off.
Location Full path Directory where trace files are written to. The location string must be a valid file path, for example mqetrace.
Timestamp Yes or no Determine if timestamp information is added to each tracepoint. Set to "no" to reduce file size and increase speed.
Parameters Yes or no Determine if parameter information is added to each tracepoint. Set to "no" to reduce file size and increase speed.
WrapLength Value Advanced value, described in the following list under Wraplength.
SubtractMethodFilter Value Advanced value, described in the following list under AddMethodFilter and SubtractMethodFilter.
AddMethodFilter Value Advanced value, describted in the following list under AddMethodFilter and SubtractMethodFilter.

In Table 1, the following conditions apply:

WrapLength
This is the maximum size, in bytes, that an individual trace file will reach. Once this value is reached, the trace file begins to wrap using a "circular buffer" algorithm. However, this takes a considerable amount of time, and may significantly slow down execution speed once the file starts wrapping. Therefore, leave this value at -1, except in circumstances where disk space is at a premium.
Note:
This is the maximum length of a single trace file. If an application is run multiple times, or multiple applications are run, then each generated trace file reaches this size.

AddMethodFilter and SubtractMethodFilter
These values allow sophisticated control over exactly what trace points are produced. Incorrect use can seriously limit the effectiveness and understandability of the trace files. You should leave these fields blank, unless an IBM service representative instructs you otherwise. If you do send trace files to IBM, you must include details of what both of these fields are set to.


© IBM Corporation 2002. All Rights Reserved