This chapter describes what you need to do to get Palm OS® Emulator installed and ready to use on your desktop machine.
- "Prerequisites"
- "Downloading Palm OS Emulator"
- "Versions of Palm OS Emulator"
- "Loading ROM Images"
- "Using a ROM Image in Palm OS Emulator"
Prerequisites
This section describes the software you need to use Palm OS Emulator.
Palm OS Emulator Runtime Requirements
Palm OS Emulator requires one of the following runtime environments:
- A 32-bit Windows platform: either Windows 95, Windows 98, Windows NT, Windows ME, Windows 2000, or Windows XP. Emulator is a multi-threaded 32-bit program. It does not run on Windows 3.1, even with Win32s installed.
- MacOS 8.6 or later with Carbon 1.2.5 or later
- Unix: some versions, including Linux
Using ROM Images
To run Palm OS Emulator, you need to transfer a ROM image to it. The ROM image contains all of the code used for a specific version of the Palm OS. You can obtain ROM images for different Palm OS versions from the Palm OS Resource Pavilion, or you can tell Palm OS Emulator to download the ROM from a handheld that has been placed in the handheld cradle and connected to the desktop computer. For more information about transferring a ROM image to Palm OS Emulator, see "Loading ROM Images."
When you download ROM images from the Palm OS Resource Pavilion, you can also obtain debug ROM images. Debug ROM images contain additional error checking and reporting functions that can help you debug Palm OS applications.
For more information about testing and debugging applications with Palm OS Emulator, see "Testing Applications Using Palm OS Emulator."
Downloading Palm OS Emulator
The most recent released version of Palm OS Emulator for Macintosh, Windows, and Unix is always posted on the Internet in the PalmSource developer zone:
Follow the links from the developer zone main page to the Emulator page to retrieve the released version of Emulator. If you want to test-drive the version of Palm OS Emulator that is currently under development, follow links from the developer zone page to the Emulator seed page.
The Palm OS Emulator package that you download includes the files shown in Table 2.1.
Note: For the Unix version of Palm OS Emulator, the source code is provided rather than the executables listed in the table below.
Table 2.1 Files Included in the Palm OS Emulator Package
Palm OS application used to transfer the ROM image from your handheld to your desktop. |
|
C/C++ header file declaring functions that can be used to control Palm OS Emulator. For more information about the Host Control API, see Chapter 8, "Host Control API Reference." |
Versions of Palm OS Emulator
Each released version of Palm OS Emulator has a version number that uses the following scheme:
Each field has the following semantics:
Profile Versions
Palm OS Emulator includes a profile version, which has the word profile appended to the program name. The profile version adds the ability to perform selective profiling of your program's execution, and to save the results to a file.
The code required to add profiling capability slows down your application, even when you are not using profiling. That means that you are better off using the non-profiling version of Palm OS Emulator if you don't expect to use the profiling capabilities.
For more information about profiling with Palm OS Emulator, see "Profiling Your Code".
Loading ROM Images
Because Palm OS Emulator emulates the Palm Powered™ hardware, all components of the hardware must be present. This includes a ROM image file, which is not shipped with the Emulator. There are two ways to obtain a ROM image:
Downloading a ROM Image Obtained from PalmSource
To download a debug ROM image from PalmSource, see:
The ROM image files are found in the Resource Pavilion.
The Resource Pavilion is an area for developers who have registered as members of the Palm OS Developer Program. You can find instructions for joining the Palm OS Developer Program at the developer site.
Transferring a ROM Image from a Handheld
To transfer a ROM image from a handheld, follow these steps:
- Install the Palm OS application named
ROM Transfer.prc
on your handheld. You can use the Install program in the Palm Desktop organizer software and then synchronize with the handheld to install this program. - Place the handheld in the HotSync® cradle that is connected to your desktop computer.
- Follow the steps in the appropriate section below.
Transferring a ROM File in Windows
This section describes how to transfer a ROM image from a handheld on a Windows-based desktop computer. Before proceeding, you must have the ROM Transfer.prc
program installed on the handheld, as described in the previous section.
If you are running the program for the first time, Palm OS Emulator presents the Startup dialog box shown in Figure 2.1. Click Download to begin the transfer of a ROM image from a handheld.
Figure 2.1 Palm OS Emulator Startup Dialog Box

If you are not running Palm OS Emulator for the first time, it usually restarts the session that you most recently ran, as described in "Palm OS Emulator Start Up."
To transfer a new ROM image for Palm OS Emulator to use, you can right-click on the Palm OS Emulator display (the Palm Powered handheld image) and select Transfer ROM.
Palm OS Emulator opens a Transfer ROM dialog box that will guide you through the process.
Transferring a ROM File on a Macintosh
This section describes how to transfer a ROM image from a handheld on a Macintosh desktop computer. Before proceeding, you must have the ROM Transfer.prc
program installed on the handheld, as described in the previous section.
If you are running the program for the first time, Palm OS Emulator presents the dialog box shown in Figure 2.2.
Figure 2.2 Running Palm OS Emulator for the First Time on a Macintosh System

You can dismiss this dialog box and choose Transfer ROM from the File menu.
If you are not running Palm OS Emulator for the first time, it usually restarts the session that you most recently ran. To transfer a new ROM image for Palm OS Emulator to use, select Transfer ROM from the File menu.
Palm OS Emulator opens a Transfer ROM dialog box that will guide you through the process.
Transferring a ROM File on a Unix System
This section describes how to transfer a ROM image from a handheld on a Unix-based desktop computer. Before proceeding, you must have the ROM Transfer.prc
program installed on the handheld, as described in the previous section.
When running the program on a Unix system, Palm OS Emulator presents the dialog box shown in Figure 2.3.
Figure 2.3 Running Palm OS Emulator for the First Time on a Unix System

You can dismiss this dialog box and choose Transfer ROM from the File menu to begin the transfer of a ROM image from a handheld.
If you are not running Palm OS Emulator for the first time, it usually restarts the session that you most recently ran. To transfer a new ROM image for Palm OS Emulator to use, select Transfer ROM from the File menu.
Palm OS Emulator opens a Transfer ROM dialog box that will guide you through the process.
Transferring a ROM Image over a USB Connection
Palm OS Emulator supports transferring ROM images over a USB connection. To use a USB connection, Palm OS Emulator needs the USB driver support provided by the Palm Desktop software.
On Windows, you need to have Palm Desktop 4.0.1 or later installed to get the USB driver. You must make the library for the USB driver (the file USBPort.dll
) available to Emulator. Either copy this file from the Palm Desktop software's directory to the Emulator directory, or move it into the Windows system directory.
On Macintosh, you need to have Palm Desktop 2.6.3 or later installed to get the USB driver.
Using a ROM Image in Palm OS Emulator
Once you have transferred a ROM image to disk, you need to create a new session that is based on the image. To initiate the new session, you select New from the popup menu. Table 2.2 shows the first step in creating a new session for each transfer method.
Table 2.2 Initiating a New Session after Transferring a ROM Image
After you initiate the session, Palm OS Emulator presents the new session dialog box, which is described in "Configuring a New Session". The Windows version of this dialog box is shown in Figure 2.4.
Figure 2.4 New Session Dialog Box

After you select your parameters and click OK, Palm OS Emulator begins an emulation session.
Dragging and Dropping a ROM Image
You can use drag and drop to start a new Emulator session in either of two ways:
- Drag and drop a ROM image file onto the Emulator screen to start a new session.
- Drag and drop a ROM image file onto the Emulator executable or shortcut (alias) to start the Palm OS Emulator program.
You can also drag and drop other file types, as described in "Dragging and Dropping Files".