This chapter describes Palm OS Reporter, which you can use to do trace analysis of your Palm OS® applications. The following topics are covered in this chapter:
- "About Palm OS Reporter" - An introduction to Palm OS Reporter concepts
- "Installing Palm OS Reporter" - How to download and install the Palm OS Reporter package
- "Adding Trace Calls to Your Application" - How to add Trace Manager calls to your ARM application or Host Control trace calls to your 68K application.
- "Displaying Trace Information in Palm OS Reporter" - How to open a Palm OS Reporter session to view the trace information
- "Troubleshooting Palm OS Reporter" - How to make sure Palm OS Reporter is running correctly
About Palm OS Reporter
Palm OS Reporter is a trace utility that can be used with Palm OS Cobalt Simulator. As an application runs on Palm OS Cobalt Simulator, it can send information in real time to Reporter. This information can help pinpoint problems that might be hard to identify when executing code step-by-step or when specifying breakpoints. To view the realtime traces, simply start Reporter before you run Palm OS Cobalt Simulator.
Palm OS Reporter Features
Palm OS Reporter has a number of features that make it useful:
- High throughput of trace output, allowing for realtime traces
- Trace output filtering, searching, saving, printing, and copying
- Display of Trace output through a TCP/IP connection
Installing Palm OS Reporter
Palm OS Reporter is a component of the Palm OS Cobalt developer tools package. When you install the developer tools package, you install Palm OS Reporter.
To check for product fixes or other between-release updates, check
http://www.palmos.com/dev/tools
Palm OS Reporter Package Files
The Palm OS Reporter package includes the following files:
Table 4.1 Files included in the Palm OS Reporter package
Palm OS Reporter requires either Palm OS Cobalt Simulator or Palm OS Emulator. When you installed Palm OS Reporter, the installer placed the PalmTrace
library (PalmTrace.dll
) in the same folder as the Palm OS Cobalt Simulator executable. Palm OS Cobalt Simulator is not able to send trace information to Reporter if it cannot find and load the PalmTrace
library.
The Palm OS Reporter executable can be located in any folder on your system; it does not need to be in the same folder as Palm OS Cobalt Simulator.
Adding Trace Calls to Your Application
Traces are generated by system calls that are recognized by Palm OS Cobalt Simulator but ignored by actual handheld devices.
Tracing ARM-Based Applications
For ARM-based applications recompiled to run on Windows for Palm OS Cobalt Simulator, you use the system calls listed in TraceMgr.h
, which is part of the Palm OS SDK. For more information about the Trace Manager API, see the book Exploring Palm OS: System Management.
The Trace Manager system calls pertinent to tracing are listed in the following table:
Trace Manager Functions in a Code Sample
void function(void) { unsigned char theBuffer[256]; unsigned long theUInt32 = 0xFEDC1234; unsigned short theUInt16 = 0xFE12; int i; TmOutputTL(appErrorClass, "This is an Int32:"); TmOutputTL(appErrorClass, " unsigned (lu) [4275835444]=[%lu]", theUInt32); TmOutputTL(appErrorClass, " signed (ld) [-19131852]=[%ld]", theUInt32); TmOutputTL(appErrorClass, " hexa (lx) [fedc1234]=[%lx]", theUInt32); TmOutputTL(appErrorClass, "This is an Int16:"); TmOutputTL(appErrorClass, " unsigned (hu) [65042]=[%hu]", theUInt16); TmOutputTL(appErrorClass, " signed (hd) [-494]=[%hd]", theUInt16); TmOutputTL(appErrorClass, " hexa (hX) [FE12]=[%hX]", theUInt16); TmOutputTL(appErrorClass, "This is a string (s) [Hello world]=[%s]", "Hello world"); TmOutputTL(appErrorClass, "This is a char (c) [A]=[%c]", 'A'); TmOutputTL(appErrorClass, "This is a buffer:"); for (i = 0 ; i < 256 ; i++) theBuffer[i] = (unsigned char) i; TmOutputB(appErrorClass, theBuffer, 256); }
Tracing 68K-Based Applications
For 68K-based applications, you use the system calls listed in hostcontrol.h
, which is part of the Palm OS SDK. For more information about the Host Control API, see the book Exploring Palm OS: System Management.
The Host Control system calls pertinent to tracing are listed in the following table:
All HostTraceOutput
functions take an error class identifier as their first parameter. This parameter allows filtering of traces according to their origin. Recognized error classes are listed in SystemMgr.h
. For example, applications should specify the error class appErrorClass
.
Host Control Functions in a Code Sample
void function(void) { unsigned char theBuffer[256]; unsigned long theUInt32 = 0xFEDC1234; unsigned short theUInt16 = 0xFE12; int i; HostTraceInit(); HostTraceOutputTL(appErrorClass, "This is an Int32:"); HostTraceOutputTL(appErrorClass, " unsigned (lu) [4275835444]=[%lu]", theUInt32); HostTraceOutputTL(appErrorClass, " signed (ld) [-19131852]=[%ld]", theUInt32); HostTraceOutputTL(appErrorClass, " hexa (lx) [fedc1234]=[%lx]", theUInt32); HostTraceOutputTL(appErrorClass, "This is an Int16:"); HostTraceOutputTL(appErrorClass, " unsigned (hu) [65042]=[%hu]", theUInt16); HostTraceOutputTL(appErrorClass, " signed (hd) [-494]=[%hd]", theUInt16); HostTraceOutputTL(appErrorClass, " hexa (hX) [FE12]=[%hX]", theUInt16); HostTraceOutputTL(appErrorClass, "This is a string (s) [Hello world]=[%s]", "Hello world"); HostTraceOutputTL(appErrorClass, "This is a char (c) [A]=[%c]", 'A'); HostTraceOutputTL(appErrorClass, "This is a buffer:"); for (i = 0 ; i < 256 ; i++) theBuffer[i] = (unsigned char) i; HostTraceOutputB(appErrorClass, theBuffer, 256); HostTraceClose(); }
Specifying Trace Strings
Trace strings use the following format:
% <flags> <width> <type>
-
<flags>
-
-
- Left-justify display (Default is right justify).
-
+
- Always display the sign character (Default is to display the sign character for negative values only).
-
space
- Display a space (when a value is positive) rather than displaying a "+" sign.
-
#
- Alternate form specifier.
-
<width>
- Must be a positive number.
-
<type>
-
%
- Display a "%" character
-
s
- Display a null-terminated string
-
c
- Display a character
-
ld
- Display an Int32 value
-
lu
- Display a UInt32 value
-
lX or lx
- Display an Int32 or UInt32 value in hexadecimal
-
hd
- Display an Int16 value
-
hu
- Display a UInt16 value
-
hX or hx
- Display an Int16 or UInt16 value in hexadecimal
NOTE: The following types are not supported for
<type>
: o, e, E, f, F, g, G, p, l, n, d, i, u, X, or x.
Displaying Trace Information in Palm OS Reporter
To view trace information in Palm OS Reporter, you need to do the following:
- Add trace calls to your application and build your application.
- Start a Palm OS Reporter session.
- Start a Palm OS Cobalt Simulator session.
- Redirect the Simulator's Socket API calls to the host machine's TCP/IP stack. Select the Simulator menu Settings > Networking > Winsock-Based SocketLib Replacement.
- Install your trace-enabled application in the Simulator session.
- Run your trace-enabled application in the Simulator session.
Starting a Palm OS Reporter Session
To start a Palm OS Reporter session, run the Reporter.exe
file. After starting Palm OS Reporter, you should see an empty window. This window serves as a container for other windows which display the trace information.
Testing ARM-Based Applications with Palm OS Reporter
Each TmOutput
call sends information into the current trace window. The TmOutput
call is ignored if there is no active trace window.
Testing 68K-Based Applications with Palm OS Reporter
A new trace window is created for each HostTraceInit
to HostTraceClose
sequence in your trace-enabled application.
Each HostTraceOutput
call sends information into the current trace window. The HostTraceOutput
call fails if there is no active trace window, which can happen if Reporter is not running when the HostTraceInit
function is called.
Also, a reset in Simulator closes any pending connection. That is, Simulator calls the HostTraceClose
function for your application if you used HostTraceInit
to open a trace connection.
Figure 4.1 shows a Palm OS Reporter session window.
Figure 4.1 Palm OS Reporter session window

Filtering Information in a Palm OS Reporter Session
You can control the type of trace information Palm OS Reporter displays. You control this information by setting filters. Filters can be set either globally, by using the Global filters... menu, or for the current window, by using the Active view filters... menu. By enabling or disabling the filters, you can choose to view traces sent by corresponding modules in your application. Global filter settings are saved when you exit the Palm OS Reporter session.
Using the Palm OS Reporter Toolbar
Palm OS Reporter provides a toolbar with the following functions:
Troubleshooting Palm OS Reporter
Table 4.2 How to solve possible Palm OS Reporter problems
The |
Check to see if your system is configured to "Hide system files." |
Table 4.3 Palm OS Reporter error messages