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

4    Using Palm OS Reporter

Palm OS® Cobalt Simulator Guide

Palm OS Cobalt Version 6.1

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

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

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

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

The Palm OS Reporter package includes the following files:

Table 4.1  Files included in the Palm OS Reporter package 

File

Description

Reporter.exe

Main Palm OS Reporter program file

PalmTrace.dll

Palm OS Cobalt Simulator add-on that relays traces to Palm OS Reporter

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

Traces are generated by system calls that are recognized by Palm OS Cobalt Simulator but ignored by actual handheld devices.

Tracing ARM-Based Applications ^TOP^

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:

System Call Format

Function Description

void TmOutputT(status_t mod, const char* fmt, ...)

Output a string to Reporter (printf format).

void TmOutputTL(status_t mod, const char* fmt, ...)

Output a string to Reporter (printf format) with an additional line break.

void TmOutputB(status_t mod, const void* buff, long len)

Send binary data to Reporter.

void TmOutputVT(status_t mod, const char* fmt, va_list vargs)

Output a string to Reporter (vprintf format).

void TmOutputVTL(status_t mod, const char* fmt, va_list vargs)

Output a string to Reporter (vprintf format) with an additional line break.

Trace Manager Functions in a Code Sample ^TOP^


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

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:

System Call Format

Function Description

void HostTraceInit(void)

Initiate a connection to Reporter

void HostTraceOutputT(UInt16
mod, const char* fmt, ...)

Output a string to Reporter (printf format)

void HostTraceOutputTL(UInt16
mod, const char* fmt, ...)

Output a string to Reporter (printf format) with an additional line break

void HostTraceOutputB(UInt16
mod, const char* buff, UInt32 len)

Send binary data to Reporter

void HostTraceOutputVT(UInt16
mod, const char* fmt, va_list vargs)

Output a string to Reporter (vprintf format)

void HostTraceOutputVTL(UInt16
mod, const char* fmt, va_list vargs)

Output a string to Reporter (vprintf format) with an additional line break

void HostTraceClose(void)

Close the connection to Reporter

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

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

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

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

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

Palm OS Reporter provides a toolbar with the following functions:

Toolbar Icon

Function

Save the contents of the Reporter window to a file

Print the contents of the Reporter window

Select all of the text in the Reporter window

Copy the selected text into the system clipboard

Clear the contents of the Reporter window

Draw a horizontal line across the Reporter window

Search the Reporter window for specified text

Search the Reporter window for the next occurrence of specified text

Search the Reporter window for the previous occurrence of specified text

Set "on top" mode to keep the Reporter window always visible on the screen

Set filters for the current window only

Set font for the current window only

Set filters for all new windows

Set font for all new windows

Troubleshooting Palm OS Reporter ^TOP^

Table 4.2  How to solve possible Palm OS Reporter problems 

Symptom

Solution

The PalmTrace library (PalmTrace.dll) doesn't appear in the folder where you decompressed the Reporter's archive.

Check to see if your system is configured to "Hide system files."

Nothing appears in the Palm OS Reporter session window.

Make sure that:

  • The PalmTrace library (PalmTrace.dll) is in the same folder as the Palm OS Cobalt Simulator executable.
  • Your application code is calling HostTraceInit, if the application is a 68K-application.
  • Your filters are set correctly, and traces are emitted with the right modules.

Table 4.3  Palm OS Reporter error messages  

Error Message

Problem

Possible Solution

An error occurred while trying to listen for traces.

Default reception port is already in use.

Check that no other instance of the Reporter is running.

An error occurred while ObjectSet was initializing TCP/IP.

TCP/IP related failure.

Check that TCP/IP networking is correctly set up.

Unable to start a reader thread.

Reporter could not create receiver thread.

Free up system resources.

Unable to start a format thread.

Reporter could not create displayer thread.

Free up system resources.