The Trace Manager allows you to output a buffer of data, in hex, or a string to the external trace reporting tool.
The contents of this chapter are organized as follows:
Trace Manager Functions and Macros
The header file TraceMgr.h
declares the API that this chapter describes.
For more information on debugging Palm OS applications, see Chapter 13, "Debugging Strategies."
Trace Manager Functions and Macros
TM Macro
Purpose
Provides a shorthand method for calling the Trace Manager functions. This macro is identical to TraceOutput()
.
Declared In
TraceMgr.h
Prototype
#define TM (
X
)
Parameters
-
→ X
- The portion of the function name following
TraceOutput
that indicates the type of the value being output.
Returns
Comments
Rather than calling the Trace Manager functions directly, you can use this macro instead.
See Also
TmOutputB Function
Purpose
Output a buffer of data, in hex dump format, to the external trace reporting tool.
Declared In
TraceMgr.h
Prototype
void TmOutputB ( status_ttraceModule
, const void*aBuffer
, longaBufferLen
)
Parameters
-
→ traceModule
- The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors
.h
. Applications should useappErrorClass
. -
→ aBuffer
- Pointer to a buffer of raw data to be output.
-
→ aBufferLen
- The number of bytes of data in the buffer.
Returns
See Also
TmOutputT()
, TmOutputTL()
, TmOutputVT()
, TmOutputVTL()
TmOutputT Function
Purpose
Output a formatted text string to the external trace reporting tool.
Declared In
TraceMgr.h
Prototype
void TmOutputT (
status_t traceModule
,
const char *aFormatString,
...
)
Parameters
-
→ traceModule
- The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors
.h
. Applications should useappErrorClass
. -
→ aFormatString
- A format string, as used in standard C-library calls such as
printf()
. See the Comments section, below, for more detail. -
→ ...
- The list of variables to be formatted for output.
Returns
Comments
The format string has the following form:
Table 39.1 shows the flag types that you can use in the format specification for the tracing output functions.
Table 39.1 Trace function format specification flags
Table 39.2 shows the output types that you can use in the format specification for the tracing output functions.
Table 39.2 Trace function format specification types
See Also
TmOutputB()
, TmOutputTL()
, TmOutputVT()
, TmOutputVTL()
TmOutputTL Function
Purpose
Output a formatted text string, followed by a newline, to the external trace reporting tool. This function performs the same operation as TmOutputT()
but adds the newline character.
Declared In
TraceMgr.h
Prototype
void TmOutputTL (
status_t traceModule
,
const char *aFormatString,
...
)
Parameters
-
→ traceModule
- The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors
.h
. Applications should useappErrorClass
. -
→ aFormatString
- A format string, as used in standard C-library calls such as
printf()
. See the Comments section underTmOutputT()
for more detail. -
→ ...
- The list of variables to be formatted for output.
Returns
See Also
TmOutputB()
, TmOutputVT()
, TmOutputVTL()
TmOutputVT Function
Purpose
Output a formatted text string to the external trace reporting tool.
Declared In
TraceMgr.h
Prototype
void TmOutputVT ( status_ttraceModule
, const char*aFormatString
, va_listarglist
)
Parameters
-
→ traceModule
- The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors
.h
. Applications should useappErrorClass
. -
→ aFormatString
- A format string, as used in standard C-library calls such as
printf()
. See the Comments section underTmOutputT()
for more detail. -
→ arglist
- A structure containing the variable argument list. This is the same kind of variable argument list used for standard C-library functions such as
vprintf()
.
Returns
See Also
TmOutputB()
, TmOutputTL()
, TmOutputVTL()
TmOutputVTL Function
Purpose
Output a formatted text string, followed by a newline, to the external trace reporting tool. This function performs the same operation as TmOutputVT()
but adds the newline character.
Declared In
TraceMgr.h
Prototype
void TmOutputVTL ( status_ttraceModule
, const char*aFormatString
, va_listarglist
)
Parameters
-
→ traceModule
- The ID of the Palm OS subsystem from which this output originates. You can use this with the external tracing tool to filter traces according to their origin. The ID must match one of the error classes defined in CmnErrors
.h
. Applications should useappErrorClass
. -
→ aFormatString
- A format string, as used in standard C-library calls such as
printf()
. See the Comments section underTmOutputT()
for more detail. -
→ arglist
- A structure containing the variable argument list. This is the same kind of variable argument list used for standard C-library functions such as
vprintf()
.
Returns
See Also
TmOutputB()
, TmOutputT()
, TmOutputTL()
TraceDefine Macro
Purpose
Constructs a custom error class value.
Declared In
TraceMgr.h
Prototype
#define TraceDefine (x
,y
)
Parameters
Returns
This macro evaluates to the sum of the two supplied values.
Comments
Use this macro to construct custom error class values.
TraceOutput Macro
Purpose
Provides a shorthand method for calling the Trace Manager functions. This macro is identical to TM()
.
Declared In
TraceMgr.h
Prototype
#define TraceOutput (
X
)
Parameters
-
→ X
- The portion of the function name following
TraceOutput
that indicates the type of the value being output.
Returns
Comments
Rather than calling the Trace Manager functions directly, you can use this macro instead.