This chapter provides guidance and reference information that will help you use Palm OS® Cobalt Simulator.
- "Installing Palm OS Cobalt Simulator"
- "Starting Palm OS Cobalt Simulator"
- "Specifying Command Line Arguments"
- "Using the Initialization File"
- "Loading ROM Images"
- "Running Palm OS Cobalt Simulator"
- "Using Communication Functions"
- "Using External Debug Tools with Palm OS Cobalt Simulator"
Installing Palm OS Cobalt Simulator
Palm OS Cobalt Simulator consists of the following:
The ROM file is specific to Palm OS Cobalt 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 is at least one DLL per ARM-based application or shared library.
The DLLs required by the ROM file can be in any directory specified by the PALMSOURCE_SIM_PATH
environment variable. The DLLs can also 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 jaJP
).
To use Palm OS Reporter's tracing functions with Palm OS Cobalt Simulator, you need to have the file PalmTrace.DLL
in a directory specified by the PATH
environment variable. For more information on Palm OS Reporter, see Chapter 4, "Using Palm OS Reporter,".
Starting Palm OS Cobalt Simulator
To start Palm OS Cobalt Simulator, run PalmSim.EXE
. The first time you start Palm OS Cobalt Simulator, you are asked to select a ROM file.
You can also start Palm OS Cobalt 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 Cobalt Simulator starts, the main window is displayed, as shown in Figure 2.1.
Figure 2.1 Palm OS Cobalt Simulator's main window

Specifying Command Line Arguments
You can supply the session parameters for Palm OS Cobalt Simulator as command line options. For example:
PalmSim.EXE
-rom:Simulator_Full_EFIGS_Release.rom
Table 2.1 shows the options that you can specify with the command line version of Palm OS Cobalt Simulator.
NOTE: The command line options are not case sensitive, but the values specified for the options might be (for example, the four-character application creator ID for the
-appcreator
option).
Table 2.1 Command line options
host - The name of the host used for the 68K debugger. port - The port used for the 68K debugger. For more information, see "Communication Ports." |
|
type - The type of port used for the 68K debugger. The default is For more information, see "Communication Ports." |
|
portList - A list of additional communications ports, enclosed in parentheses and separated by commas. portName - A unique name for a port. portType - [Standard RS-232 | Modem | IR through RS-232 | IR through JetEye | TCP/IP] portInfo - The port information, either host:port or COMx. Example: Note: The quotation marks are required if the parameter string contains spaces. For more information, see "Communication Ports." |
|
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." |
|
xxxx - A four-character Creator ID indicating the application to start. For more information, see Chapter 2, "Using AppCreator to Start an Application,". |
|
filename - The PRC or PDB file that you want Palm OS Cobalt Simulator to automatically load. filelist - A list of PRC and PDB files that you want Palm OS Cobalt Simulator to automatically load, each item in the list separated by semicolons. If a filename includes spaces, the filename must be enclosed in quotation marks. directory - The directory containing the PRC and PDB files that you want Palm OS Cobalt Simulator to automatically load. For more information on using AutoLoad, see "Using AutoRun, AutoLoad, and AutoRunAndQuit." |
|
filename - The PRC or PDB file that you want Palm OS Cobalt Simulator to automatically run. directory - The directory containing the PRC and PDB files that you want Palm OS Cobalt Simulator to automatically run. For more information on using AutoRunAndQuit, see "Using AutoRun, AutoLoad, and AutoRunAndQuit." |
|
filename - The PRC or PDB file that you want Palm OS Cobalt Simulator to automatically run. directory - The directory containing the PRC and PDB files that you want Palm OS Cobalt Simulator to automatically run. For more information on using AutoRun, see "Using AutoRun, AutoLoad, and AutoRunAndQuit." |
|
Sets the color depth for the display setting. The default is For more information, see "Display > Resolution." |
|
COMx - The communications port used to talk to the cradle port. For more information, see "Communication Ports." |
|
directories - A list of directories, separated by semicolons (;), that specify where you want Palm OS Cobalt Simulator to look to find DLLs. This command line option is similar to the If you use both the environment variable and the command line option, Palm OS Cobalt Simulator looks in the paths specified by the environment variable first. |
|
COMx - The communications port used for infrared. For more information, see "Communication Ports." |
|
type - The type of port used for infrared communication. For more information, see "Communication Ports." |
|
llCC - A language/country descriptor identifying the language you want Palm OS Cobalt Simulator to use. When you use this command line option, Palm OS Cobalt Simulator skips the language selection application for a ROM that supports multiple languages. |
|
size - An integer value indicating the amount of RAM to emulate during the session, specified in kilobytes. The size has to be the exact number of bytes. For example, to specify 16 MB, use the value 165536. For more information, see "Memory." |
|
Indicates whether you want to redirect Socket API calls to the host machine's TCP/IP stack. The default is For more information, see "Networking > Standard Palm OS TCP/IP." |
|
romname - The name of the ROM file. If you do not specify a value for this option when you first start Simulator, Simulator opens 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 loads the ROM file name from the initialization file. |
|
Indicates whether Simulator should output sound. The default is For more information, see "Enable Sound." |
|
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". |
|
machine - The identifier of the machine to which you want traces redirected. For example: file - The file to which you want traces redirected. For example: stderr - Redirects trace output to standard error.For more information, see "Traces." |
|
Indicates whether Palm OS Cobalt Simulator can use the host ethernet adapter. The default is For more information, see "Networking > Standard Palm OS TCP/IP." |
|
integer - Specifies Simulator's horizontal distance from the left of the screen when the window is opened. The default is |
|
integer - Specifies Simulator's vertical distance from the top of the screen when the window is opened. The default is |
|
Magnification level. The default is For more information, see "Display > Magnification." |
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. (Command line options are described in Table 2.1.)
When you exit Simulator, the session's values are written to palmsim.ini
; these values are loaded from the initialization file the next time you start Simulator.
To reset the values to the original defaults, simply delete the palmsim.ini
file.
Listing 2.1 Sample palmsim.ini File
[Settings] ROM=C:\SDK\ROM\Simulator_Full_EFIGS_Release.rom Sound=1 AlwaysOnTop=0 Fullscreen=0 Zoom=1 Renderer=0 BitDepth=16 RedirectSocketLibCalls=0 UseHostTCP=0 CradlePort= CradlePortType=Standard RS-232 UseHostBatteryInfo=1 BatteryPluggedIn=1 BatteryPercent=75 BatteryKind=2 DockStatus=0 UseSkin=0 RAM=32768 LastSilkScreen= InfraredPort=localhost:6417 InfraredPortType=TCP/IP 68KDebuggerPort=localhost:2000 68KDebuggerPortType=TCP/IP VirtualPhonePort=localhost:6416 VirtualPhonePortType=TCP/IP AdditionalPorts= LastStorageSnapshot=C:\SDK\Simulator\Release\storage snapshot.ssf ScreenDensity=144 ScreenWidth=320 ScreenHeight=480 ScreenOrientation=0 ScreenRotations=14 HasSilkScreen=0 TraceTarget=tcp:localhost:25998 ConsoleVisible=0 EventsVisible=0 ThreadsVisible=0 HeapsVisible=0 EventsFilter= AutoStartReporter=0 UseHostEthernetAdapter=1 WindowOriginX=0 Window0Right=326 WindowOriginY=0 Window0Bottom=505
The options that you can also set on the command line are described in Table 2.1.
NOTE: The initialization file options use an equal 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
.
Loading ROM Images
When you first run Palm OS Cobalt 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 opens a dialog box asking for you to specify a ROM file.
When you restart Simulator, it assumes 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 opens a dialog box asking for you to specify a ROM file.
- Drag and drop a ROM file onto the
PalmSim.EXE
icon.
NOTE: If you are running the Release version of Palm OS Cobalt Simulator, you must use a Release version ROM file. If you are running the Debug version of Palm OS Cobalt Simulator, you must use a Debug version ROM file.
Running Palm OS Cobalt Simulator
This section provides an overview how to use Palm OS Cobalt Simulator.
Palm OS Cobalt Simulator Display
The Palm OS Cobalt 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 Cobalt Simulator functions.
Displaying Menu Items
Right-click (use mouse button 2) on the Palm OS Cobalt Simulator screen display to access the menu items. The Palm OS Cobalt Simulator menu displays, as shown in Figure 2.2.
Figure 2.2 The Palm OS Cobalt Simulator menu

For more information about the Palm OS Cobalt Simulator menu items, see "Menu Reference Summary."
Entering Data
Palm OS Cobalt Simulator supports handwriting recognition. You can draw characters using a mouse.
Palm OS Cobalt 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.
NOTE: Palm OS applications written for Palm OS 4 or earlier (68K applications) run in Palm OS Cobalt Simulator without any changes.
However, if you are installing a Palm OS application that uses ARM-native code, you must recompile the ARM-native code into a Windows DLL.
Palm OS Cobalt Simulator recognizes a call to an ARM-native subroutine as a call into a DLL. A fully ARM-native application must also be built as a PRC that calls a Windows DLL in order for Palm OS Cobalt Simulator to use it.
Place the DLL either in the Palm OS Cobalt Simulator directory or in a directory specified by using the
-dllpath
command line option.
Using the Install Menu Item
Use Install > Database to open the Install Database dialog box. You can install a single PRC or PDB file, or you can use Shift-click to select multiple databases for installation. You will receive a warning message if Palm OS Cobalt Simulator cannot use a PRC or PDB file.
Using Drag and Drop
Drag and drop PRC and PDB files onto the Palm OS Cobalt Simulator main window. You will receive a warning message if Palm OS Cobalt Simulator cannot use a PRC or PDB file.
Using AutoRun, AutoLoad, and AutoRunAndQuit
Palm OS Cobalt Simulator also supports the AutoRun, AutoLoad and AutoRunAndQuit features that make it easier to test you applications.
You can use these features either by using the command line options (-autorun
, -autoload
, -autorunandquit
) or by creating special directories.
For information about the command line options, see Table 2.1.
To use an AutoRun directory:
- Create a subdirectory of the Simulator directory called
AutoRun
. - Place the PRC and PDB files that you want to automatically run in the
AutoRun
directory. - When you start Simulator, Simulator automatically loads the PRC and PDB files.
NOTE: If you include more than one PRC file in the
AutoRun
directory, Simulator loads all of the PRC files, but runs only the last PRC file loaded (the last PRC filename when sorted alphabetically).
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 Cobalt Simulator supports the following communication functions:
Testing Infrared Communication (Beaming)
You can beam data between two Palm OS Cobalt Simulator sessions to test infrared communication in your applications.
- Select Communication Ports to open the Communication Ports dialog box.
- Select Infrared from the listed ports, and click Edit.
- Set the Transport Type to
TCP/IP
, and set the Bound to value tolocalhost:6417
, as shown in Figure 2.3.
Figure 2.3 Setting communication ports to test beaming

Performing a HotSync Operation
You can perform a HotSync® operation through serial connection, through IrDA, and through TCP/IP.
NOTE: To perform a HotSync operation, you may want to first select Settings > HotSync Name to enter a user name.
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 > Communication Ports, set the Cradle port to Standard RS232 bound to the other serial communication port.
Using External Debug Tools with Palm OS Cobalt Simulator
Palm OS Cobalt Simulator can be used with a 68K debugger, to examine the state of the 68K emulated applications. Palm OS Cobalt Simulator can also be used with a Windows debugger, to examine the state of ARM-native code that has been recompiled to run as a PRC calling a DLL.
Using Palm OS Cobalt Simulator with 68K Debuggers
Palm OS Cobalt 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 use to debug 68K-native applications.