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

2    Using Palm OS Cobalt Simulator

Palm OS® Cobalt Simulator Guide

Palm OS Cobalt Version 6.1

This chapter provides guidance and reference information that will help you use Palm OS® Cobalt Simulator.

Installing Palm OS Cobalt Simulator ^TOP^

Palm OS Cobalt Simulator consists of the following:

  • The executable file: PalmSim.EXE
  • A ROM file
  • The DLLs required by the ROM file

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

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

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  

Option Syntax

Parameter Values

-68kdebuggerport: [host:port|None]

host - The name of the host used for the 68K debugger.

port - The port used for the 68K debugger.

Example:

-68KDebuggerPort: localhost:2000

For more information, see "Communication Ports."

-68kdebuggerporttype:type

type - The type of port used for the 68K debugger. The default is TCP/IP.

For more information, see "Communication Ports."

-additionalPorts: portList

portList - A list of additional communications ports, enclosed in parentheses and separated by commas.

Each port definition consists of a name, a port type, and the port information:

(portName,portType,portInfo)

where:

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:
-AdditionalPorts: "(FirstPort,Standard RS-232,COM3),(SecondPort,TCP/IP,LOCALHOST:1000)"

Note: The quotation marks are required if the parameter string contains spaces.

For more information, see "Communication Ports."

-alwaysontop:[on|off]

Indicates whether the Simulator window should stay in front of other windows on the desktop. The default is off.

For more information, see "Display > Always on Top."

-appcreator:xxxx

xxxx - A four-character Creator ID indicating the application to start.

For more information, see Chapter 2, "Using AppCreator to Start an Application,".

-autoload:[ filename | filelist | directory ]

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.

For example:

-autoload:"C:\Sample\My Sample.prc";"C:\Sample\My Data.pdb";C:\Program.prc

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."

-autorunandquit: [ filename | directory ]

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."

-autorun: [ filename | directory ]

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."

-bitdepth: [4|8|16|24|32]

Sets the color depth for the display setting. The default is 16.

For more information, see "Display > Resolution."

-cradleport:COMx

COMx - The communications port used to talk to the cradle port.

For more information, see "Communication Ports."

-dllpath:directories

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 PALMSOURCE_SIM_PATH environment variable (described in "Installing Applications").

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.

-infraredport:[COMx|None]

COMx - The communications port used for infrared.

For more information, see "Communication Ports."

-infraredporttype:type

type - The type of port used for infrared communication.

For more information, see "Communication Ports."

-preferredLocale:llCC

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.

-ram:size

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."

-redirectsocketlibcalls:
[on|
off]

Indicates whether you want to redirect Socket API calls to the host machine's TCP/IP stack. The default is off.

For more information, see "Networking > Standard Palm OS TCP/IP."

-rom:romname

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.

-sound:[on|off]

Indicates whether Simulator should output sound. The default is on.

For more information, see "Enable Sound."

-storagesnapshotfile:ssfname

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".

-tracetarget:[ machine |file | stderr ]

machine - The identifier of the machine to which you want traces redirected. For example:

-tracetarget: tcp:localhost:25998

file - The file to which you want traces redirected. For example:

-tracetarget:file:myfile.txt

stderr - Redirects trace output to standard error.For more information, see "Traces."

-usehostethernetadapter: [on|off]

Indicates whether Palm OS Cobalt Simulator can use the host ethernet adapter. The default is on. However, the ethernet driver does not load if you have not installed the WinPcap library.

For more information, see "Networking > Standard Palm OS TCP/IP."

-windoworiginx:integer

integer - Specifies Simulator's horizontal distance from the left of the screen when the window is opened. The default is 0.

-windoworiginy:integer

integer - Specifies Simulator's vertical distance from the top of the screen when the window is opened. The default is 0.

-zoom:[1|2|3|4]

Magnification level. The default is 1.

For more information, see "Display > Magnification."

Using the Initialization File ^TOP^

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

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 the palmsim.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 ^TOP^

This section provides an overview how to use Palm OS Cobalt Simulator.

Palm OS Cobalt Simulator Display ^TOP^

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

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

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

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

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

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

To have Simulator load a specific storage snapshot file at startup or upon hard reset, you can either:

  • Set the storagesnapshotfile value in the palmsim.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 ^TOP^

Palm OS Cobalt Simulator supports the following communication functions:

Testing Infrared Communication (Beaming) ^TOP^

You can beam data between two Palm OS Cobalt Simulator sessions to test infrared communication in your applications.

  1. Select Communication Ports to open the Communication Ports dialog box.
  2. Select Infrared from the listed ports, and click Edit.
  3. Set the Transport Type to TCP/IP, and set the Bound to value to localhost:6417, as shown in Figure 2.3.

Figure 2.3  Setting communication ports to test beaming

Performing a HotSync Operation ^TOP^

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

  1. Connect the serial ports with a NULL serial cable.
  2. Set the properties for the HotSync application to perform a local HotSync operation with one of the serial ports.
  3. 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 ^TOP^

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

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.