The Palm Reporter is a trace utility that can be used together with the Palm OS Emulator (POSE). Applications that run inside POSE can send information in real-time to the Reporter. This information can help to pinpoint problems that would be hard to troubleshoot executing code step by step or setting breakpoints. To observe traces, simply run your application and the Reporter at the same time.
The Palm Reporter has a number of features that make it useful:
The Palm Reporter package includes the following files:
File |
Description |
Reporter.exe (Windows) |
Main Palm Reporter program. |
PalmTrace.dll (Windows) |
POSE add-on that relay traces to the Reporter. |
Reporter guide.html |
Palm Reporter documentation (this file). |
Reporter protocol.html |
Description of the protocol recognized by the Reporter. |
TraceTest.prc |
Small binary sending a few traces. |
filters.def (Windows) |
Filters customization file, provided as a sample. |
The Palm Reporter requires Windows 9x, Windows NT or 2000 to run.
The Reporter may be started from any folder, and does not need to be stored in the same folder as POSE. This is not true for PalmTrace.dll, which should be located in the same directory as POSE. POSE will not be able to send traces to the Reporter if it can't find and load PalmTrace.dll, and it will fail silently if this happens.
Traces are generated from a PRC using special system calls that are recognized by POSE but ignored by actual devices. These calls are listed in hostcontrol.h, which is part of the Palm OS SDK. This file is also shipped with POSE, which is updated more frequently than the SDK. Only the Win32 version of POSE can handle traces at this time however. The system calls pertinent to tracing are:
void HostTraceInit(void) |
Initiate a connection to the "tracing port" (by default that's the Reporter) |
void HostTraceOutputT(UInt16 mod, const char* fmt, ...) |
Output a string to the Reporter (printf-like) |
void HostTraceOutputTL(UInt16 mod, const char* fmt, ...) |
Same as HostTraceOutputT with an additional line break |
void HostTraceOutputB(UInt16 mod, const void* buff, Int32 len) |
Send binary data to the Reporter |
void HostTraceOutputVT(UInt16 mod, const char* fmt, va_list vargs) |
vprintf-like variant of HostTraceOutputT |
void HostTraceOutputVTL(UInt16 mod, const char* fmt, va_list vargs) |
vprintf-like variant of HostTraceOutputTL |
void HostTraceClose(void) |
Close the current connection |
All HostTraceOutput functions take an error class identifier as their first parameter. This parameter allows filtering out traces according to their origin. Recognized error classes are listed in SystemMgr.h. For example, applications should specify appErrorClass.
The format string is as follows: % flags width type
Supported flags are:
- |
Left justified display (default is right justified) |
+ |
Always displays the sign symbol (default is to display it for negative values only) |
space |
Displays a space (when the value is positive) instead of a '+' symbol |
# |
Alternate form specifier |
width should be a strictly positive number
Supported types are:
% |
Display the % character |
s |
Display a 0 terminated string |
c |
Display a character |
ld |
Display a Int32 |
lu |
Display a UInt32 |
lX or lx |
Display a UInt32 in hexadecimal |
hd |
Display a Int16 |
hu |
Display a UInt16 |
hX or hx |
Display a Int16 (or UInt16) in hexadecimal |
Unsupported types are:
o |
Display an unsigned int in octal |
e |
Display a double |
E |
Display a double |
f |
Display a double |
F |
Display a double |
g |
Display a double |
G |
Display a double |
p |
Display a pointer to void |
l |
Display a long |
n |
Display a pointer to integer |
d |
Display an int (type size not guaranteed) |
i |
Display an int (type size not guaranteed) |
u |
Display an unsigned int (type size not guaranteed) |
X or x |
Display an int (or unsigned int) in hexadecimal (type size not guaranteed) |
After launching the Palm Reporter, you should see an empty window. This window will serve as a container for other windows into which traces will be displayed. A new trace window is created for each HostTraceInit ... HostTraceClose sequence. HostTraceOutput calls will send information into the current trace window. They will fail if there is no active trace window, which can happen if the Reporter was not running when HostTraceInit was called. A reset in POSE will close any pending connection - i.e. call HostTraceClose for you if you had called HostTraceInit before.
The Reporter is able to filter the types of traces that it displays. You may control filters either globally or just for the current window by using the appropriate options under the View menu or by clicking on the appropriate icons. By enabling or disabling filters, you may choose to view traces sent by the corresponding modules. Global settings are saved when the Reporter exits.
You can also modify the filter map that the Reporter uses internally. Take a look to the filters.def file for additional information.
|
Save the content of the Reporter window to a file |
|
Print the content of the Reporter window |
|
Select all of the text in the Reporter window |
|
Copy the selected text into the Windows clipboard |
|
Clear the Reporter window |
|
Draw a horizontal line across the Reporter window |
|
Search the Reporter window for specified text |
|
Search for the next occurrence of specified text |
|
Search for the preceding occurrence of specified text |
|
Set "on top" mode - keep the Reporter 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 |
|
Sets font for all new windows |
You might encounter a few error messages related to traces. Here are their descriptions:
Error message |
Problem |
Possible solution |
An error occurred while trying to listen for traces |
Default reception port in use |
Check that no other instance of the Reporter is running |
An error occurred while initializing ObjectSet |
Framework initialization failed |
Contact us |
An error occured while ObjectSet was initializing TCP/IP |
TCP/IP related failure |
Check that TCP/IP networking is correctly set up |
Cannot load filters description |
Reporter executable was altered |
Contact us |
Unable to start a reader thread |
Could not create receiver thread |
Free up system ressources |
Unable to start a format thread |
Could not create displayer thread |
Free up system ressources |
If the PalmTrace.dll doesn't appear in the folder where you decompressed the Reporter's archive:
If nothing appears where you would expect traces, check that:
The Reporter requires some OLE related DLLs as well as Winsock2. The following system updates may be necessary on Windows 95 (not 98, NT or 2000):
void f(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();
}
There is Tracing Options dialog in POSE that controls the location where POSE sends traces. The default output is set to none, so traces are simply discarded unless otherwise specified. This dialog box enables sending traces to a remote computer, which can be useful for remote troubleshooting.
One packet (message) is emitted for each trace. See Reporter Protocol.html for details. The Reporter expects connections on localhost:25998.
Incoming data is stored in a circular list of buffers. Only the last few thousands traces are kept. If traces have been discarded, it will be signaled by a [...] at the top of the trace window.
Only the last 100 trace windows are displayed. The oldest windows are closed first.