Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

39    Trace Manager

System Management

Exploring Palm OS®

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 ^TOP^

TM Macro ^TOP^

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

Returns nothing.

Comments

Rather than calling the Trace Manager functions directly, you can use this macro instead.

To call...

Use...

TmOutputT()

TM(T (errorClass,"format",...) )

TmOutputTL()

TM(TL (errorClass,"format",...) )

TmOutputB()

TM(B (errorClass,addr,count) )

TmOutputVT()

TM(VT (errorClass,"format",va_list) )

TmOutputVTL()

TM(VTL(errorClass,"format",va_list) )

See Also

TraceOutput()

TmOutputB Function ^TOP^

Purpose

Output a buffer of data, in hex dump format, to the external trace reporting tool.

Declared In

TraceMgr.h

Prototype

void TmOutputB (
   status_t traceModule,
   const void *aBuffer,
   long aBufferLen
)

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 use appErrorClass.
aBuffer
Pointer to a buffer of raw data to be output.
aBufferLen
The number of bytes of data in the buffer.

Returns

Returns nothing.

See Also

TmOutputT(), TmOutputTL(), TmOutputVT(), TmOutputVTL()

TmOutputT Function ^TOP^

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 use appErrorClass.
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

Returns nothing.

Comments

The format string has the following form:

% flags width type

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 

Flag

Description

-

Left-justified output. By default, output is right-justified.

+

Always display the sign symbol. By default, only a leading minus sign is displayed.

space

Display a space when the value is positive, rather than a '+' symbol.

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 

Flag

Description

%

Display the '%' character.

s

Display a null-terminated string value.

c

Display a character value.

ld

Display an int32_t value.

lu

Display a uint32_t value.

lx or lX

Display a uint32_t value in hexadecimal.

hd

Display an int16_t value.

hu

Display a uint16_t value.

hx or hX

Display a uint16_t value in hexadecimal.

See Also

TmOutputB(), TmOutputTL(), TmOutputVT(), TmOutputVTL()

TmOutputTL Function ^TOP^

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 use appErrorClass.
aFormatString
A format string, as used in standard C-library calls such as printf(). See the Comments section under TmOutputT() for more detail.
...
The list of variables to be formatted for output.

Returns

Returns nothing.

See Also

TmOutputB(), TmOutputVT(), TmOutputVTL()

TmOutputVT Function ^TOP^

Purpose

Output a formatted text string to the external trace reporting tool.

Declared In

TraceMgr.h

Prototype

void TmOutputVT (
   status_t traceModule,
   const char *aFormatString,
   va_list arglist
)

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 use appErrorClass.
aFormatString
A format string, as used in standard C-library calls such as printf(). See the Comments section under TmOutputT() 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

Returns nothing.

See Also

TmOutputB(), TmOutputTL(), TmOutputVTL()

TmOutputVTL Function ^TOP^

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_t traceModule,
   const char *aFormatString,
   va_list arglist
)

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 use appErrorClass.
aFormatString
A format string, as used in standard C-library calls such as printf(). See the Comments section under TmOutputT() 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

Returns nothing.

See Also

TmOutputB(), TmOutputT(), TmOutputTL()

TraceDefine Macro ^TOP^

Purpose

Constructs a custom error class value.

Declared In

TraceMgr.h

Prototype

#define TraceDefine (
   x,
    y
)

Parameters

x
The error class "base" value.
y
The offset from the "base" value.

Returns

This macro evaluates to the sum of the two supplied values.

Comments

Use this macro to construct custom error class values.

TraceOutput Macro ^TOP^

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

Returns nothing.

Comments

Rather than calling the Trace Manager functions directly, you can use this macro instead.

To call...

Use...

TmOutputT()

TraceOutput(T (errorClass,"format",...) )

TmOutputTL()

TraceOutput(TL (errorClass,"format",...) )

TmOutputB()

TraceOutput(B (errorClass,addr,count) )

TmOutputVT()

TraceOutput(VT (errorClass,"format",va_list) )

TmOutputVTL()

TraceOutput(VTL(errorClass,"format",va_list) )

See Also

TM()