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

3    Running Palm OS Emulator

Using Palm OS® Emulator

Palm OS Developer Suite

This chapter describes how to use emulation sessions and how to customize the emulation sessions.

Starting Palm OS Emulator ^TOP^

Run Palm OS Emulator just like you would any other program. When Palm OS Emulator starts up, it displays an image of a handheld, as shown in Figure 1.1.

Command Line Options ^TOP^

If you are running Palm OS Emulator on a Windows-based desktop computer or on a Unix system, you can supply the session parameters as command-line parameters. For example:

Emulator -psf C:\Data\Session1.psf

Table 3.1 shows the options that you can specify on the Windows command line. You can also change most of these options by starting a new session with the New menu, as described in "Configuring a New Session".

Note that the command line option specifications are not case sensitive.

Table 3.1 Palm OS Emulator Command Line
Options 

Option syntax

Parameter values

Description

-d <key>=<value>

A preference file property and its associated value, as specified in the preference file.

Changes preferences that are stored in the preferences file.

This option is a synonym for the -preference option. For more information, see "Preferences Files".

-horde <num>

A Gremlin number

The number of the Gremlin to run after the session is created or loaded.

Note that this is equivalent to supplying the same Gremlin number for the horde_first and horde_last options.

-horde_first <num>

A Gremlin number

The first Gremlin to run in a horde.

-horde_last <num>

A Gremlin number

The last Gremlin to run in a horde.

-horde_apps <app name list>

A comma-separated list of applications.

The list of applications to which the Gremlin horde is allowed to switch. The default is no restrictions.

To specify a list of excluded applications, use a hyphen character before a list of application names. Example: "-Prefs,HotSync"

-horde_save_dir <path>

A path name

The name of the directory in which to save session and log files.

The default log location is the directory in which the Palm OS Emulator application is stored.

-horde_save_freq <num>

An event count

The Gremlin snapshot frequency.

The default value is to not save snapshots.

-horde_depth_max <num>

An event count

The maximum number of Gremlin events to generate for each Gremlin.

The default value is no upper limit.

-horde_depth_ switch <num>

An event count

The number of Gremlin events to generate before switching to another Gremlin in the horde.

The default is to use the same value as specified for the horde_depth_max option.

-horde_quit_ when_done

None

Emulator will exit after completing the Gremlin horde.

-pref <key>=<value>

-preference <key>=<value>

A preference file property and its associated value, as specified in the preference file.

This option changes preferences that are stored in the preferences file. For more information, see "Preferences Files".

-psf <fileName>

Any valid PSF file name

The emulator session file to load upon start-up. You can also load a session file with the Open menu.

-rom <fileName>

Any valid ROM file name

The name of the ROM file to use.

-ram <size>

or

-ramsize <size>

One of the following kilobyte size values:
128K
256K
512K
1024K
2048K
4096K
8192K
16,384K

The amount of RAM to emulate during the session.

-device <type>

One of the following handheld type values:
Pilot, Pilot1000, Pilot5000, PalmPilot, PalmPilotPersonal, PalmPilotProfessional, PalmIII, PalmIIIc, PalmIIIe, PalmIIIx, PalmV, PalmVx, PalmVII, PalmVIIEZ, PalmVIIx, PalmM100, m100, PalmM105, m105, PalmM125, m125, PalmM130, m130, PalmM500, m500, PalmM505, m505, PalmM515, m515, PalmI705, i705, Symbol1500, Symbol1700, Symbol1740, TRGpro, HandEra330, Visor, VisorPlatinum, VisorPrism, VisorEdge

The handheld type to emulate during the session.

  • Pilot1000 and Pilot5000 are synonyms for Pilot.
  • PalmPilotPersonal and PalmPilotProfessional are synonyms for PalmPilot.
  • The following handhelds are not supported: Palm IIIxe, Palm IIIse, Symbol handhelds other than those listed, Handspring handhelds other than those listed, all Acer handhelds, all Sony handhelds, all Samsung handhelds, all Kyocera handhelds, and all Qualcomm handhelds.

-load_apps <file name list>

A list of valid file names, separated by commas

A list of PRC files or other files to load into the session after starting up.

-log_save_dir <path>

A path name

The name of the directory in which to save the standard log file.

The default log location is the directory in which the Palm OS Emulator application is stored.

-minimize <pevFileName>

The name of a Palm OS event file (PEV).

The Palm OS event file contains an event set you want to minimize. When you invoke Emulator with this command line option, Emulator goes though the event minimization process, writes the output files, and exits. See "Minimizing Gremlin Events" for more information.

-quit_on_exit

None

If the -run_app option was specified, this option indicates that Palm OS Emulator should quit after that application terminates.

-run_app <app name>

Application name

The name of an application to run in the session after starting up. You must specify the name of the application, not the name of the application's file.

-silkscreen <type>

or

-skin <type>

The name of a skin. The skin names are defined by the handheld-specific SKIN files. For most handhelds, these skin names are available:

Generic
Standard-English
Standard-Japanese

The skin types to emulate during the session. For more information about skins, see "Changing Emulator's Appearance".

Palm OS Emulator Start Up ^TOP^

The most common scenario for starting Palm OS Emulator is without any command line parameters. In this case, Emulator restarts with saved information from the previous session.

When Palm OS Emulator starts execution, it determines its configuration by sequencing through the following rules:

  1. If the Caps Lock key is on, the Startup dialog box is always displayed. The Startup dialog box is shown in Figure 3.1.

Figure 3.1  Palm OS Emulator Startup Dialog Box


NOTE: The dialog box shown in Figure 3.1 is displayed when you are running Palm OS Emulator on a Windows-based computer.

If you are using a Macintosh computer, the new session dialog box shown in Figure 2.2 is displayed.

If you are using a Unix system, the new session dialog box shown in Figure 2.3 is displayed.
  1. If you are using Windows or Unix with command line options specified:
    • If the Caps Lock key is not on, Palm OS Emulator scans the command line for options. If an error is encountered on the command line, Palm OS Emulator displays an error message and then presents the Startup dialog box.
    • If a session (PSF) file was specified on the command line, Palm OS Emulator attempts to load the file. If the file cannot be loaded, Palm OS Emulator displays an error message and then presents the Startup dialog box.
    • If any other options are specified on the command line, Palm OS Emulator attempts to start a new session with those values. If any of the four values is missing, Palm OS Emulator displays the session configuration dialog box, as shown in Figure 3.2.

      If any of the command line options are not valid, or if the user cancels the dialog box, Palm OS Emulator displays an error message and then presents the Startup dialog box.

Figure 3.2  New Session Dialog Box

  1. If no command line options are specified, Palm OS Emulator attempts to reopen the session file from the most recent session, if one was saved. If the file cannot be opened, Palm OS Emulator displays an error message, and then presents the Startup dialog box.
  2. Palm OS Emulator attempts to create a new session based on the setting most recently specified by the user. If an error occurs, Palm OS Emulator displays an error message, and then presents the Startup dialog box.

NOTE: When it starts up, Palm OS Emulator looks for the most recently saved PSF file:
- On Windows and Unix, Emulator uses the full path name of that file.
- On Macintosh, Emulator uses aliases to locate the file.

If Emulator cannot find that file, it looks for the file name in the directory in which the Palm OS Emulator executable is located.

Using Emulation Sessions ^TOP^

Palm OS Emulator uses the concept of an emulation session, which is a testing or debugging session for a combination of the following items:

  • the handheld type to emulate
  • the amount of RAM to emulate
  • the ROM file to use for the emulation

You can start new emulation sessions during a single run of Palm OS Emulator. You can also save the current state of a session and restore it in a later session. This session describes these features of Palm OS Emulator.

Configuring a New Session ^TOP^

You can start a new session in Palm OS Emulator by choosing New from the Palm OS Emulator menu. If you are already running an emulation session, Palm OS Emulator will optionally ask if you want to save the session in a Palm OS Emulator session (PSF) file before starting the new session. You set this option in your preferences.

Figure 3.3 shows the New Session dialog box, which Palm OS Emulator displays when you choose New from the menu.

Figure 3.3  Configuring a New Session

You need to make the following choices in this dialog box:

  • Select the ROM file on your desktop computer that you want to use for the session. You can click on the arrow and select Other... to navigate to the file. For more information about ROM files, see "Loading ROM Images".
  • Select the Palm Powered handheld that you want to emulate in the session. Only those handhelds that apply to the selected ROM will be shown in the list. The list may include the following choices:

- Pilot

- PalmPilot

- Palm III

- Palm IIIc

- Palm IIIe

- Palm IIIx

- Palm V

- Palm Vx

- Palm VII

- Palm VII (EZ)

- Palm VIIx

- Palm m100

- Palm m105

- Palm m125

- Palm m130

- Palm m100

- Palm m105

- Palm m125

- Palm m500

- Palm m505

- Palm m515

- Palm i705

- Symbol 1500

- Symbol 1700

- Symbol1740

- TRGpro

- HandEra 330

- Visor

- Visor Platinum

- Visor Prism

- Visor Edge

  • Select the skin that you want displayed on the emulation screen.

    Note that the skin is simply a graphic; it does not change the ROM or the handheld being emulated. The skin simply changes the appearance of the Emulator window.

    The skin choices available are dependent on the handheld selection. When you select a handheld, Emulator reads through the available SKIN files for the skin names that support the selected handheld.

    Alternative skins, such as the Japanese skin, are only available for certain handheld types. The Generic choice is always available, even when alternatives are not available. For additional information, see the section "Changing Emulator's Appearance".

  • Select the amount of memory that you want emulated. Note that Emulator filters out the sizes that are invalid for the handheld you have chosen to emulate. Depending on the handheld you are emulating, you can choose from the following RAM sizes:
    • 128 KB
    • 256 KB
    • 512 KB
    • 1024 KB
    • 2048 KB
    • 4096 KB
    • 8192 KB
    • 16,384 KB

      Note that 1 MB (1024 KB) is most often the right amount of RAM to emulate. Using 1 MB of RAM tells you if your application will work properly across the majority of hardware handhelds available.

After you click OK, Palm OS Emulator begins an emulation session.

The Difference between the New Menu Item and the Open Menu Item ^TOP^

Both New and Open can be used to initiate an emulator session. However, the Open menu item is used to open an existing session file (PSF file) that has been saved from a previous emulator session. The Open menu item does not allow you to change the ROM file or handheld being emulated.

Dragging and Dropping Files ^TOP^

You can drag and drop the following file type categories onto the Palm OS Emulator LCD screen:

  • PRC, PDB, and PQA files
  • ROM files
  • PSF files

When dragging and dropping files, observe the following rules:

  • You can drag and drop only one ROM file at a time.
  • You can drag and drop only one PSF file at a time.
  • You can drag and drop any number of PRC, PDB, and PQA files.

NOTE: Drag and drop is not currently supported for the Unix version of Palm OS Emulator.

Saving and Restoring Session State ^TOP^

You can save the current state of a Palm OS Emulator session to a session file for subsequent restoration. Palm OS Emulator saves a session to a session file. The Emulator uses Save and Save As in the standard manner, with one addition: you can automate what happens when closing a session by changing the Save options.

Saving the Screen ^TOP^

You can save the current screen to a bitmap file by selecting the Save Screen menu item, which saves the contents of the emulated Palm Powered handheld screen.

Figure 3.4  A Palm OS Emulator Screen Shot

Palm OS Emulator saves screen images on Windows-based systems as BMP bitmap images, saves screen images on MacOS-based systems as SimpleText image files, and saves screen images on Unix-based systems as PPM files.

Changing Emulator's Appearance ^TOP^

You can change the appearance of Palm OS Emulator by choosing Settings>Skins. This displays the Skins dialog box, which is shown in Figure 3.5.

Figure 3.5  Changing Palm OS Emulator Appearance

The Skins dialog box lists the skins that are available for the handheld that is being emulated.

Emulator comes with a built-in Generic skin, which is sufficient for testing your application. Note that the skin is simply a graphic. Selecting a skin changes the appearance of the Emulator window, but it does not change the ROM or the handheld being emulated.

You can download additional skins from:

http://www.palmos.com/dev/tools/emulator/

For more information about using skin files, see "Using Emulator Skin Files".

Other Options on the Skins Dialog Box ^TOP^

In addition to selecting a skin, use the Skins dialog box to change these appearance options:

  • Select Double scale to display the emulated handheld in double size; deselect it to display the emulated handheld in actual size.
  • Select White background to display the emulated handheld LCD background color in white on your monitor. If you are emulating a handheld that has a green LCD, deselect White background to display the emulated LCD background color in green.
  • Select Dim skin when inactive to cause the Emulator window to be dimmed when another window is the active window. This can be useful in combination with the Stay on top option.
  • Select Stay on top to cause the Emulator window to stay on top of other windows even when Emulator is not the active window. This can be useful when you need to switch to other windows, such as a debugger window.

NOTE: The Stay on top option is supported only on Windows.

Modifying the Runtime Environment ^TOP^

This section describes how you can modify the Palm OS Emulator runtime environment, including changing the properties and installing applications in the emulator session.

Palm OS Emulator Properties ^TOP^

Use the Properties dialog box to modify characteristics of your Palm OS Emulator sessions. To display this dialog box, choose Properties on Windows or Preferences on Macintosh or Unix. The Properties dialog box is shown in Figure 3.6.

Figure 3.6  Changing Palm OS Emulator Properties

Table 3.2 describes the options available in the properties dialog box.

Table 3.2 Palm OS Emulator properties 

Option

Description

Serial port

Specifies which serial port Palm OS Emulator uses to emulate serial communications on the handheld.

IR port

Specifies which port Palm OS Emulator uses to emulate infrared communications on the handheld.


NOTE: This function is not currently supported.

Mystery

Reserved for future use. Not used for current handhelds.

Redirect Netlib calls to host TCP/IP

Redirects Netlib calls in emulated software to TCP/IP calls on the desktop computer.

Enable sounds

Specifies whether Palm OS Emulator should enable emulation of handheld sounds.

Closing / Quitting

Selects what action Palm OS Emulator takes when you close a session or quit the program.

HotSync user name

Selects the user account name for synchronizing from Palm OS Emulator with the desktop computer HotSync® application.

Preferences Files ^TOP^

Your properties are stored in a preferences file on your computer. Each property is stored as a text string that you can view with a text editor. Emulator first looks for the preferences file in the folder containing the Emulator executable. Otherwise, the location of your preferences file depends on the type of computer that you are using, as shown in Table 3.3.

Table 3.3 Palm OS Emulator Preference File Locations 

Platform

File name

File location

Macintosh

Palm OS Emulator Prefs

In the Preferences folder.

Windows

Palm OS Emulator.ini

In the Windows System directory.

Unix

.poserrc

In your home directory.

Installing Applications ^TOP^

Palm OS Emulator provides the following ways to install applications into an Emulator session:

  • Drag and drop an application (PRC), database (PDB), or Palm Query Application (PQA) file directly onto the Emulator window. See "Dragging and Dropping Files" for more information.
  • Use the Install menu item from the Emulator pop-up menu. See "Using the Install Menu" for more information.
  • Use the autoload facility to create a directory of applications that are automatically installed into the Emulator session. See "Using the Autoload Facility" for more information.

Using the Install Menu ^TOP^

Use Install to load applications or databases directly into the current Palm OS Emulator session.

  • For Windows and Unix, right-click on the Palm OS Emulator screen display and choose Install Application/Database
  • On a Macintosh system, select Install Application/Database from the File menu

Install displays an open file dialog box in which you can choose the applications (PRC), databases (PDB), or Palm Query Application (PQA) files that you want installed.

Palm OS Emulator immediately loads the selected files into emulated RAM. If Palm OS Emulator finds another application or database with the same creator ID, that application or database is deleted before the new version is loaded.


IMPORTANT: If you install an application while the Palm OS Launcher is running, the Launcher does not update its data structures, and thus does not reflect the fact that a database has been added or modified. Use Install while an application is running in the emulated session. A simple method to use is to switch to the Calculator application when using the Install menu item.

Using the Autoload Facility ^TOP^

Palm OS Emulator provides an autoload facility, which allows you to specify installable files that should be automatically installed into the emulation session when you start Emulator. Here's how you can use the autoload facility:

  • Create a directory named autoload in the same directory as the Emulator executable file.
  • Place the files in the autoload directory that you want to have automatically installed. You can place application files (PRC), database files (PDB), and Palm Query Application (PQA) files in the autoload directory.

When Emulator starts, it will automatically install all of the files that it finds in the Autoload directory.


NOTE: On Windows and Unix, the -load_apps command line option causes Emulator to ignore the Autoload directory. The files listed with the -load_apps command line option are automatically installed rather than the files in the Autoload directory.

Using the Autorun Facility ^TOP^

Similar to using the Autoload facility, you can automatically load and run applications by creating an autorun directory. Place the applications you want automatically run in the autorun directory.

To have applications automatically run and quit, you create a directory with the name autorunandquit.

Using Serial Communication ^TOP^

Palm OS Emulator supports emulation of the Palm Powered handheld serial port connection. It does so by mapping Palm OS serial port operations to a communications port on the desktop computer. To select which port the Emulator uses, use Properties (on Macintosh and Unix computers, this is Preferences), as described in "Palm OS Emulator Properties".

When emulated software accesses the processor serial port hardware registers, Palm OS Emulator performs the appropriate actions on the specified serial port on the desktop computer. This means that serial read and write operations work as follows:

  • when outgoing data is written to the UART's tx register, the Emulator redirects that data to the desktop computer's serial port.
  • when the emulated software attempts to read data from the UART's rx register, the Emulator reads data from the desktop computer's serial port and places the data into that register.

Using the HotSync Application ^TOP^

You can perform a HotSync operation from your emulated session in one of two ways:

Performing a Network Hotsync Operation with Palm OS Emulator on Windows ^TOP^

You do not need to be connected to a network to perform a Network HotSync operation with Palm OS Emulator. This method can be used with Emulator and a single Windows computer. However, other configurations are possible.

In general, you need these two:

  • a Windows computer running HotSync Manager
  • a computer running Emulator that can access the computer running HotSync Manager.

The computer running Emulator can be the same Windows computer that is running HotSync Manager, or it can be a second computer (either Windows, Macintosh, or Unix). If you are using a single Windows computer, you don't need to be connected to a network. However, if you are using a second computer, you will need the actual IP address of the Windows computer running HotSync Manager for step 4 below.

Here is the complete process for performing a Network HotSync operation:

  1. Ensure that you have the Network HotSync application on your emulated handheld:
    • If you are emulating a handheld that did not come with Network HotSync pre-installed (for example, a Palm III or Palm m100 handheld), you must first download and install the Network HotSync application on the emulated handheld. You can get the Network HotSync files from:

      http://www.palm.com/support/downloads/netsync.html

    • If you are emulating a handheld running Palm OS version 3.1 or later, then you may already have the Network HotSync application installed on the emulated handheld.
  2. Configure the HotSync settings on your Windows computer:
    • Right-click (use mouse button two) on the HotSync icon in the system tray.
    • In the pop-up menu, select Network to enable Network HotSync. (A checkmark will appear next to the Network menu item if it is already enabled.)
  3. Configure Palm OS Emulator to Redirect NetLib Calls to TCP/IP:
    • Right-click (use mouse button two) on Emulator.
    • In the pop-up menu, select Settings>Properties...
    • In the Properties dialog box, click the Redirect NetLib Calls to TCP/IP checkbox. Click OK to save the changed properties.
  4. Configure the HotSync settings on the emulated handheld:
    • From the handheld's application launcher, tap the HotSync application to open it.
    • Tap Menu to display the HotSync application's menu.
    • Select Options>Modem Sync Prefs...
    • In the Modem Sync Preferences dialog box, tap the Network button. Tap the OK button to save the changed preferences.
    • Tap Menu to display the HotSync application's menu again.
    • Select Options>LANSync Prefs...
    • In the LANSync Preferences dialog box, tap the LANSync button. Tap the OK button to save the changed preferences.
    • Tap Menu to display the HotSync application's menu again.
    • Select Options>Primary PC Setup...
    • In the Primary PC Setup dialog box, enter the Primary PC Address (the middle entry field):

      - If you are running Emulator and HotSync manager on the same Windows computer, enter 127.0.0.1

      - If you are running Emulator on a second computer, then enter the actual IP address of the Windows computer running the Network HotSync operation.

      Tap the OK button to save the changed preferences.

    • In the HotSync application, tap Modem. Next, tap the Select Service button under the Modem Sync icon.
    • In the Preferences dialog box, tap the Tap to enter phone field. In the Phone Setup dialog box, enter 00 in the Phone # entry field. Then tap the OK button. Then tap the Done button.
    • To start the HotSync operation, tap the HotSync icon in the center of the HotSync dialog box.

Performing a HotSync Operation with a Null Modem Cable ^TOP^

You can perform a HotSync operation by connecting the serial port that the HotSync application uses to communicate with the handheld to another serial port that Palm OS Emulator uses. You connect these ports together with a null modem cable, such as a LapLink cable.

For example, if your HotSync application uses the COM1 port, follow these steps:

  1. Select Properties (Preferences on a Macintosh or Unix) and specify the COM2 port for Palm OS Emulator.
  2. Connect COM1 and COM2 together with a null modem cable.
  3. Select HotSync from the Palm OS Emulator menu.

The HotSync application synchronizes with Palm OS Emulator just as it does with an actual hardware handheld.


TIP: The desktop HotSync application is CPU-intensive, which is not generally an issue; however, when you are using the HotSync application with Palm OS Emulator, the two programs are sharing the same CPU, which can dramatically slow the synchronization down.

A handy trick to deal with this problem is to click on the Palm OS Emulator window after the HotSync process starts. This brings the Emulator back into the foreground and allows it to use more CPU time, which improves the speed of the overall process.

If your desktop computer has two ports and you use a serial mouse on one of them, you can temporarily disable the mouse, perform a synchronization, and re-enable the mouse. Follow these steps:

  1. Disable your mouse.
  2. Restart Windows.
  3. Connect the serial ports together with a null modem cable.
  4. Start Palm OS Emulator.
  5. Press Shift-F10 to display the menu, then H to begin the HotSync operation.
  6. After the HotSync operation completes, re-enable your mouse.
  7. Restart Windows again.

TIP: When you first perform a HotSync operation with Palm OS Emulator, the HotSync application asks you to select a user name. It is a good idea to create a new user account, with a different name, for use with the Emulator.

Emulating Expansion Memory ^TOP^

Palm OS 4.0 includes the Expansion Manager, which manages plug-in memory cards, and the Virtual File System manager, which supports the management of files on memory cards.

Palm OS Emulator can emulate these cards, which the Expansion Manager will recognize and mount in the same way it would mount an actual hardware expansion card. The Virtual File System Manager will then read from and write to the host operating system using the mount information associated with the emulated card. The host operating manipulation is performed using the many file-related host control functions available. (See "Host Control API Reference" for more information on the host control API.)

PalmSource provides an implementation of a file system, called HostFS, that works in conjunction with Emulator's Host Control API to mount a local directory on the desktop as a volume or card. You can download the HostFS application from the Palm OS Emulator web page.


NOTE: Because Expansion Manager was added in Palm OS 4.0, the HostFS.prc application needs to be installed in an Emulator session running a ROM file for Palm OS 4.0 or later. (See "Using ROM Images" for more information on using ROM images with Emulator.)

Once you have installed HostFS.prc in an Emulator session running at least a Palm OS 4.0 ROM, you are ready to emulate expansion memory. To specify mount information for card emulation, use the HostFS Options dialog box shown in Figure 3.7.

Figure 3.7  Palm OS Emulator HostFS Options Dialog Box

The HostFS Options dialog box supports the mounting of up to eight emulated cards. For each card, you can specify a directory in the host file system that will serve as the root for the card as managed by the Virtual File System Manager. You can also specify whether a particular card is actually mounted.

You can change the HostFS options settings while an emulation session is running. Changes regarding whether a card is mounted or not take place immediately; the Palm OS is notified that the card has been added or removed. Changes regarding the root path take effect only when the card is mounted.

Emulating a Handheld Reset ^TOP^

Palm OS Emulator can perform any of the standard handheld reset functions. To perform a reset, select Reset... to open the Reset dialog box, as shown in Figure 3.8.

Figure 3.8  Reset Dialog Box

This dialog box is also available when you click Reset in an error message dialog box (see Figure 6.1 for an example of an error message dialog box).