This chapter provides guidance and reference information that will help you use Palm OS® Simulator.
- "Installing Palm OS Simulator"
- "Starting Palm OS Simulator"
- "Specifying Command Line Arguments"
- "Using the Initialization File"
- "Loading ROM Images"
- "Running Palm OS Simulator"
- "Using Communication Functions"
- "Using External Debug Tools with Palm OS Simulator"
- "Using Gremlins"
- "Using the Host Control API"
Installing Palm OS Simulator
Palm OS Simulator consists of the following:
The ROM file is specific to Palm OS Simulator; the ROM file is not the same as ROM files used with Palm OS Emulator. ARM-based PRCs and 68K-based PRCs are embedded in this ROM file. However, ARM-based PRCs don't really contain code; rather, they reference external DLL files. As a result, there will be at least one DLL per ARM-based application or shared library.
The DLLs required by the ROM file can be in the same directory as the executable file PalmSim.EXE
, or in the subfolder for the locale-specific ROM file (such as enUS
or jpJP
).
To use tracing functions with Palm OS Simulator, you need to have the files PalmTrace.DLL
and Reporter.EXE
in a directory included in the PATH
environment variable.
Starting Palm OS Simulator
To start Palm OS Simulator, run PalmSim.EXE
. The first time you start Palm OS Simulator, you are asked to select a ROM file.
You can also start Palm OS Simulator by dragging and dropping a Simulator ROM file onto the PalmSim.EXE
icon. (Note again that the Simulator ROM file is not the same as the ROM files used for Palm OS Emulator. You should not drop an Emulator ROM file on the PalmSim.EXE
icon.)
When Palm OS Simulator starts, the main window is displayed, as shown in Figure 2.1.
Figure 2.1 Palm OS Simulator's Main Window

Specifying Command Line Arguments
You can supply the session parameters for Palm OS Simulator as command line options. For example:
Table 2.1 shows the options that you can specify with the command line version of Palm OS Simulator.
NOTE: The command line option are not case sensitive, but the values specified for the options might be (for example, the 4-character application creator ID for the
-appcreator
option).
Table 2.1 Command Line Options
romname - The name of the ROM file. If you do not specify a value for this option when you first start Simulator, Simulator will open a dialog box asking for you to specify a ROM file. If you do not specify a value for this option on subsequent uses of Simulator, Simulator will load the ROM file name from the initialization file. |
|
size - An integer value indicating the amount of RAM to emulate during the session, specified in kilobytes. The default is 8192. For more information, see "Memory>RAM Size." |
|
size - An integer value indicating the amount of dynamic heap to emulate during the session, specified in kilobytes. The default is 512. For more information, see "Memory>Dynamic Heap Size." |
|
Activate or deactivate sound output. The default is For more information, see "Enable Sound." |
|
Activate or deactivates write protection for the storage memory. The default is For more information, see "Memory>Storage Is Write-Protected." |
|
ssfname - The name of the storage snapshot file (SSF), indicating the saved storage snapshot that you want Simulator to load at startup or upon hard reset. For more information, see "Storage Menu". |
|
xxxx - A four-character Creator ID indicating the application to start. For more information, see Chapter 2, "Using AppCreator to Start an Application,". |
|
Screen bit depth. The default is 8. For more information, see "Display>Allowed Screen Depths." |
|
Magnification level. The default is 2. For more information, see "Display>Magnification." |
|
Indicates whether the Simulator window should stay in front of other windows on the desktop. The default is For more information, see "Display>Always on Top." |
|
integer - Specifies Simulator's horizontal distance from the left of the screen when the window is opened. The default is 0. |
|
integer - Specifies Simulator's vertical distance from the top of the screen when the window is opened. The default is 0. |
|
COMx - The communications port used to talk to the cradle. For more information, see "Communication>Communication Ports." |
|
type - The type of port used for communication with the cradle. The default is For more information, see "Communication>Communication Ports." |
|
COMx - The communications port used for infrared. For more information, see "Communication>Communication Ports." |
|
type - The type of port used for infrared communication. For more information, see "Communication>Communication Ports." |
|
host - The name of the host used for the 68K debugger. port - The port used for the 68K debugger. For more information, see "Communication>Communication Ports." |
|
type - The type of port used for the 68K debugger. The default is For more information, see "Communication>Communication Ports." |
|
COMx - Additional communications ports. For more information, see "Communication>Communication Ports." |
|
Indicates whether the changes in the host machine should be indicated in the battery state of the handheld (for example, when you want to have the battery state of a laptop computer mapped to the Palm OS Simulator display). The default is For more information, see "Battery." |
|
Indicates whether you want to redirect NetLib calls to the host machine's TCP/IP stack. The default is For more information, see "Communication>Redirect NetLib Calls to Host TCP/IP." |
|
mask - A number representing the screen depths you want to allow. The default is a mask representing all possible depths. For more information, see "Display>Allowed Screen Depths." |
|
Indicates whether PACE should do extended checks of applications' use of system memory. The default is For more information, see "Memory>PACE Extended Checks." |
|
Indicates whether the installed applications have access to the LCD screen buffer. The default is For more information, see "Display>Allow Direct Screen Access." |
|
Sets the density of the display screen. The default is For more information, see "Display>Resolution." |
|
Sets the width of the display screen. The default is For more information, see "Display>Resolution." |
|
Sets the height of the display screen. The default is For more information, see "Display>Resolution." |
|
Indicates whether the display screen has a dynamic input area. The default is For more information, see "Display>Resolution." |
Using the Initialization File
The command line arguments can be set in the Simulator initialization file, palmsim.ini
. Any options specified on the command line will override the initialization file settings.
When you exit Simulator, the session's values are written to palmsim.ini
for the next time you start Simulator.
NOTE: The initialization file options use an equals sign (=) to separate the option from the value, rather than the colon character (:) used in the command line version. Also, boolean values in the initialization file are indicated using 0 and 1 rather than
off
and on
.
Listing 2.1 Sample palmsim.ini File
[Settings] ROM=C:\Palm OS Simulator\Release\enUS\NTFull_enUS.rom RAM=8192 DYN=1024 Sound=0 StorageProtection=0 Zoom=2 BitDepth=8 DebugThroughTCP=1 AlwaysOnTop=0 UseHostBatteryInfo=1 WindowOriginX=681 WindowOriginY=8 RedirectNetLibCalls=0 AllowedScreenDepths=32907 LastSilkScreen= AppCreator= CradlePort= CradlePortType=Standard RS-232 InfraredPort= InfraredPortType= 68KDebuggerPort=localhost:2000 68KDebuggerPortType=TCP/IP AdditionalPorts= TraceTarget=tcp:localhost:25998 GremlinsFromValue=0 GremlinsToValue=0 GremlinsSwitchAfter=0 GremlinsSwitchAfterValue=0 GremlinsStopAfter=0 GremlinsStopAfterValue=0 GremlinsSelectedApps= GremlinsFirstApp= GremlinsAllowScreenUpdates=1 GremlinsWindowOriginX=0 GremlinsWindowOriginY=0 LogErrorMessages=0 DirectScreenAccess=0 ExtendedMemoryChecks=1 LastStorageSnapshot=storage snapshot.ssf StorageSnapshotFile=mysnapshot.ssf ScreenDensity=108 ScreenWidth=240 ScreenHeight=240 HasSilkScreen=0
Loading ROM Images
When you first run Palm OS Simulator, you can specify the ROM image filename using the -rom
command line option. If you do not specify a value for this option, Simulator will open a dialog box asking for you to specify a ROM file.
When you restart Simulator, it will assume you want to use the ROM file that you specified when you first started Simulator.
To run Simulator with a different ROM file, you can do one of the following:
- Change the
ROM
option value in thepalmsim.ini
file. - Specify a new value using the
-rom
command line option. - Hold down the Shift key when you start Simulator. Then, Simulator will open a dialog box asking for you to specify a ROM file.
- Drag and drop a ROM file onto the
PalmSim.EXE
icon.
Running Palm OS Simulator
This section provides an overview how to use Palm OS Simulator.
Palm OS Simulator Display
The Palm OS Simulator display looks very much like a real Palm Powered handheld device. You can use your mouse to perform actions that you perform with the stylus on handheld devices, and you can use the menus to access Palm OS Simulator functions.
Displaying Menu Items
Right-click (use mouse button 2) on the Palm OS Simulator screen display to access the menu items. The Palm OS Simulator menu displays, as shown in Figure 2.2.
Figure 2.2 The Palm OS Simulator Menu

For more information about the Palm OS Simulator menu items, see "Menu Reference Summary."
Entering Data
Palm OS Simulator supports . You can draw using a mouse.
Palm OS Simulator also supports keyboard input. When a field is active, you can use the keyboard to enter text. You can also use keyboard equivalents for hardware buttons and other functions. For more information, see "Keyboard Equivalents Reference."
Installing Applications
To install Palm OS applications, you can either use the Install menu item or drag and drop files onto Simulator.
Using the Install Menu Item
Use Install>Database to open the Install Database dialog box. You can install a single PRC, PDB, or PQA file, or you can use Shift-click to select multiple databases for installation. You will receive a warning message if Palm OS Simulator cannot use a PRC, PDB, or PQA file.
Using Drag and Drop
Drag and drop PRC, PDB, and PQA files onto the Palm OS Simulator main window. You will receive a warning message if Palm OS Simulator cannot use a PRC, PDB, or PQA file.
Using AutoRun, AutoLoad, and AutoRunAndQuit
Simulator also supports the AutoRun, AutoLoad and AutoRunAndQuit features that are available with Palm OS Emulator.
- Create a subdirectory of the Simulator directory called
AutoRun
. - Place the PRC, PDB, and PQA files that you want to automatically run in the
AutoRun
directory. - When you start Simulator, Simulator will automatically load the PRC, PDB, and PQA files.
To use AutoLoad or AutoRunAndQuit, follow the steps listed above using AutoLoad
or AutoRunAndQuit
as the directory name rather than AutoRun
.
Using AppCreator to Start an Application
To have Simulator switch to a specific application at startup, you can either set the AppCreator
value to the application's creator ID in the palmsim.ini
file, or you can specify the -AppCreator
command line argument. See "Specifying Command Line Arguments" for more information about command line arguments.
Starting Simulator with a Storage Snapshot File
To have Simulator load a specific storage snapshot file at startup or upon hard reset, you can either:
- Set the
storagesnapshotfile
value in thepalmsim.ini
file - Specify the
-StorageSnapshotFile
command line argument.
Note that the storage image size specified by the storage snapshot file must match the current storage size setting.
See "Specifying Command Line Arguments" for more information about command line arguments. For more information about storage snapshot files, see "Storage Menu".
Using Communication Functions
Palm OS Simulator supports the following communication functions.
Performing a HotSync Operation
You can perform a HotSync® operation through serial connection, through IrDA, and through TCP.
HotSync Operation with Two Serial Ports
- Connect the serial ports with a NULL serial cable.
- Set the properties for the HotSync application to perform a local HotSync operation with one of the serial ports.
- Using the Simulator menu Settings > Communications > Communication ports, set the cradle's port to Standard RS232 bound to the other serial communication port.
HotSync Operation with One Serial Port
- Select the Simulator menu Settings>Communications> Redirect NetLib calls to TCP/IP in order to redirect the NetLib calls to the host machine's TCP/IP stack.
- Using the Simulator menu Settings>Communications> Communication ports, set the cradle's port to TCP/IP bound to localhost:9.
- In the HotSync settings for the host computer, enable Network Hotsync.
- In the HotSync application in the simulation session, set the following settings:
- Tap Modem.
- Select Options>Modem Sync Prefs and tap Network. Tap OK to save the changes.
- Select Options>LANSync Preferences and tap LANSync. Tap OK to save the changes.
- Select Options>Primary PC Setup and enter
127.0.0.1
as the Primary PC Address. Tap OK to save the changes. - Select Options>Connection Setup and select Cradle/Cradle. Tap Done to save the changes.
- Tap Select Service to set your service preferences, and then tap Done.
Using External Debug Tools with Palm OS Simulator
Palm OS Simulator can be used with a 68K debugger to examine the state of the 68K emulated applications.
Palm OS Simulator is a debug target, just as an actual device or Palm OS Emulator. You can use Palm Debugger, Metrowerks CodeWarrior Debugger, or any other debugger you are used to using with Palm OS Emulator.
For example, you can use Palm OS Simulator with Metrowerks CodeWarrior by following these steps:
- In Palm OS Simulator, select Settings>Communication> Redirect NetLib Calls to Host TCP/IP, as shown in Figure 2.3, in order to redirect the NetLib calls to the host machine's TCP/IP stack.
Figure 2.3 Redirect NetLib Calls to Host TCP/IP

- Also in Palm OS Simulator, select Settings> Communication>Communication ports to bind the 68K debugger transport to
localhost:2000
, as shown in Figure 2.4.
Figure 2.4 Setting the 68K Debugger Transport Values

- In CodeWarrior, select Edit>Preferences to display the IDE Preferences dialog box, shown in Figure 2.5.
Figure 2.5 IDE Preferences Dialog Box

- Click PalmDebugger Settings in the IDE Preference Panels tree to display the PalmDebugger Settings panel.
- Set the Target selection to be Palm OS Emulator.
- Click Choose next to the Location entry field.
- Use the Choose File dialog box to select the
PalmSim.exe
executable. - Select the setting Use TCP/IP connection to emulator.
Figure 2.6 Setting the CodeWarrior IDE Preferences

- Click Apply or OK to set your new values so that Palm OS Simulator will be used to run your application rather than Palm OS Emulator.
Using Gremlins
Palm OS Simulator's Gremlins testing is similar to the Gremlins testing provided by Palm OS Emulator.
To use Gremlins, use the Gremlins menu item to display the Gremlins dialog box, as shown in Figure 2.7. In this dialog box, you specify the characteristics of the Gremlins you want to use to test your application.
Figure 2.7 Gremlins Dialog Box

Applications and Panels
Use this multiple selection list to select the set of applications and OS panels that the Gremlins are to run. You can select a single application or panel, a group of applications and panels, or all applications and panels.
First Application
Use this drop-down list to select the first application the Gremlins are to run.
Random Seed
Use the From entry field to set the seed for the Gremlin pseudo-random number generator.
Events
Use the Stop after entry field to set the maximum number of events for each Gremlin. Simulator stops running each Gremlin after it posts this many events, or after it terminates with an error.
Control
This area allows you to start, step, and stop Gremlin testing. It also allows you to monitor Gremlin testing as it is happening.
Using the Host Control API
A subset of the host control API, as recognized by Palm OS Emulator, is supported in Palm OS Simulator:
- Standard C Library wrapper selectors
- Remote Procedure Call (RPC)
- External tracing tool support and all selectors required by
HostFS.prc
.
To determine whether a specific host control function is supported, use the HostIsSelectorImplemented
function.
For more information about the host control API, see Using Palm OS Emulator.