1-by-1 black pixel for creating lines
1-by-1 black pixel for creating lines
EricGiguere.com > Books > Palm Database Programming > Chapter 2
Printer-friendly version Set your preferences
Read my blogs on AdSense and affiliate marketing
Learn about these ads

Palm Database Programming — The Electronic Version

Chapter 2: What You Need To Know About Palm Devices

This material was published in 1999. See the free Palm OS Programming online course I developed for CodeWarriorU for some updated material.

Prev Chapter | Prev Section | Next Section | Next Chapter | Contents

Operating System

The Palm operating system (Palm OS) provides the environment for your applications to run in and consists of two parts, the kernel and the managers.

The Kernel

The kernel is the core of Palm operating system (Palm OS). It provides the interface between the hardware (such as trapping interrupts when the user strokes the screen with the pen) and the rest of the operating system and also manages multiple threads of execution. The kernel in current use is licensed from Kadak Products Ltd. (www.kadak.com).

Although Palm OS uses several threads internally, applications cannot create or use any threads other than the one they're running on. You can only write single-threaded applications, which means that you'll have to perform long operations in small chunks to avoid the appearance of hanging the device. We discuss this further in Chapter 4 when we deal with event processing.

Although applications are single-threaded and only one application ever appears active to the user, a second copy of the active application sometimes runs on another thread but in a more limited environment. This is also covered in Chapter 4 when we discuss application launching.

The Managers

Apart from the kernel, Palm OS consists of a series of managers, which are collections of APIs grouped by function. Your applications use the managers to obtain system resources and interact with the user. The managers can be grouped as follows:

  • The UI managers handle all interaction with the user. This includes general functions for drawing on the screen as well as functions related to specific user interface elements such as fields and lists.
  • The system managers handle non-UI interaction with the device, including access to the timers and the system event queue.
  • The memory managers handle memory allocation and management of Palm OS databases and resources, discussed later in this chapter.
  • The communication managers handle communications between the Palm device and the external world, using the serial port or the infrared port.

We discuss most of the managers as we explore Palm programming.

Palm OS Versions

As the Palm devices have evolved, Palm Computing has released new versions of the operating system. Palm OS 3.2 is the most recent version of the operating system at the time this book was written and is available on the Palm VII. The Palm IIIx and Palm V run Palm OS 3.1, while the Palm III runs Palm OS 3.0. The original Pilot 1000 and Pilot 5000 machines run Palm OS 1.0. The PalmPilot Personal and PalmPilot Professional models run Palm OS 2.0. All Palm models prior to the Palm III can be upgraded to run the latest operating system by ordering a new memory card from Palm Computing. The upgrade also provides more RAM (random-access memory) and adds some new capabilities such as infrared beaming that are missing in those models. More recent models such as the Palm III can be upgraded simply by downloading the new operating system into the device's flash memory.

To detect which version of Palm OS is installed, an application calls the FtrGet function, part of the Feature Manager:

// Get ROM version
DWord romVersion;
FtrGet( sysFtrCreator, sysFtrNumROMVersion, &romVersion );

The OS version number is returned as a four-byte value, whose format is documented in the Palm OS header file <System/SystemMgr.h> (see the next chapter for information about the Palm OS header files) as follows: 0xMMmfsbbb, where MM is the major version, m is the minor version, f is a bug fix number, s is the code stage (0 for internal development, 1 for an alpha release, 2 for a beta release, 3 for a final release), and bbb is the build number for the releases that are not final. In general, all you check are the major and minor build numbers:

if( romVersion < 0x02000000 ){
    // Palm OS 1.x
if( romVersion >= 0x03100000 ){
    // Palm OS 3.1 or higher

The version number is often checked when the application starts to ensure that the correct version of Palm OS is being used, as you'll see in Chapter 4.

Palm Computing has done its best to make each version of Palm OS upwardly compatible. Applications written for Palm OS 1.0 devices will work equally well on Palm OS 2.0 or 3.0 devices. Palm OS 2.0 applications will work on Palm OS 3.0 devices but may not work on Palm OS 1.0 devices. In some cases, an application written for an older operating system will not work correctly on a newer OS because it relied on an OS bug that the newer OS fixed. Apart from these bugs, if your application is developed using a newer OS but doesn't actually use any features specific to that version of the OS, then it will also run on older operating systems.

How can you tell if you're using a feature specific to Palm OS 2.0 or 3.0? The surest way to tell is to try running your application on a Palm OS 1.0 or 2.0 device (or using the Palm OS Emulator, which we'll discuss in the next chapter, with an older ROM image). Or you can try compiling your application using an older version of the Palm OS software development kit (SDK). The problem with both these approaches is that it is increasingly harder to get older versions of the device or the SDKs. Your best bet is to know what features were added to the OS. Since this book does not discuss Palm OS 1.0, here is a summary of what's new in Palm OS 3.0 in comparison to Palm OS 2.0:

  • More dynamic memory (96K instead of 64K). See the discussion about the dynamic heap in the next section.
  • New functions for supporting the infrared beaming capability new to the Palm III device.
  • Support for MIDI sound files.
  • The ability to dynamically create user interface objects at run time as opposed to only loading them from static definitions.
  • A simple file-streaming API for dealing with large blocks of data.
  • A Progress Manager for displaying progress dialogs during lengthy operations.

Full details of these and other changes can be found in Appendix B of Palm OS SDK Reference. Note that besides adding new routines, some Palm OS 2.0 routines were modified in Palm OS 3.0 to take extra parameters. The original routines are still available but with a V20 appended to their name. For example, Palm OS 3.0 supports both the CategoryEdit and the CategoryEditV20 routines. If you want your program to work on a Palm OS 2.0 device, you must call the V20 version of the routine, otherwise your program will crash when it tries to call the new version. There are a few Palm OS 1.0 routines that were similarly changed when 2.0 was released. The V10 suffix is used for the original version of the routine.

All applications in this book will work with Palm OS 2.0 and up unless otherwise mentioned.

Sidebar: How V10 and V20 Functions Work

For a library developer, the promise of upward compatibility can be a hard one to keep. It's often only after you make a piece of code public that you discover one of your routines could have used an extra parameter or two, or that changing the order of the parameters would make the routine easier to understand. How can you make these changes without requiring the recompilation of existing applications?

When you call a Palm OS routine, your compiler doesn't generate a call directly to the routine in ROM, but rather to an entry in a dispatch table instead. A dispatch table is an array of pointers or offsets. In C++, for example, the virtual functions of a class are stored in a dispatch table called the vtable and all calls to the virtual functions are done through the vtable entries. This allows derived classes to easily override a function by simply writing a new address for the function in the vtable.

On the Palm, the dispatch table entries  called system traps  are initialized by the operating system. Whenever a routine is added to Palm OS, the developers add a new system trap to the end of the table. Once added, a system trap's index in the dispatch table is forever fixed.

How does the compiler know which system trap to use for a particular routine? In the header files that come with the Palm OS SDK you'll see that there is a mapping for each Palm OS routine to a particular system trap. These mappings provide the link from the symbolic name  the name you use in your code   to the actual routine in ROM. When you call a Palm OS routine, the compiler uses the mapping in the header file to generate a call into the dispatch table. Change the mapping and you change which ROM routine gets called. As long as the old system trap is still valid then code compiled using the original mapping will continue to work unchanged. Only when the code is compiled using a newer SDK will changes be required, at which point the generated code will use the new mapping and hence the new system trap.

Take, for example, the CategoryEdit routine. In Palm OS 3.0 there are actually three versions of this routine: CategoryEdit, CategoryEditV20, and CategoryEditV10. In Palm OS 1.0 there was only a single CategoryEdit routine, and it took two parameters. The SDK defined a mapping from the CategoryEdit name to a system trap. Palm OS 2.0 added a three-parameter version of the routine and hence a new system trap. The new SDK remapped CategoryEdit to the new (second) system trap and mapped the "new" routine CategoryEditV10 to the old (first) system trap. Palm OS 3.0 added a four-parameter version of the routine and another new system trap. The 3.0 SDK remapped CategoryEdit to the third trap and mapped the new routine CategoryEditV20 to the second trap. Thus, calling CategoryEdit using the 1.0 SDK is equivalent to calling CategoryEditV10 when using the 2.0 or 3.0 SDKs.

Prev Chapter | Prev Section | Next Section | Next Chapter | Contents

Copyright ©1999 by Eric Giguere. All rights reserved. From Palm Database Programming: The Complete Developer's Guide. Reprinted here with permission from the publisher. Please see the copyright and disclaimer notices for more details.

If you find the material useful, consider buying one of my books, linking to this site from your own site or in your weblog, or sending me a note.

Google Web www.ericgiguere.com   
1-by-1 black pixel for creating lines
Copyright ©2003-2012 Eric Giguere | Send mail about this page | About this site | Privacy policy
Site design and programming by Eric Giguere | Hosting by KGB Internet Solutions
This site is Java-powered
Other sites: The Unofficial AdSense Blog | Google Suggest Explorer | Invisible Fence Guide | Synclastic
This page was last modified on November 17, 2003
1-by-1 black pixel for creating lines
1-by-1 black pixel for creating lines