Features
Above the Fray
Follow the Money
Market Research
Big Ideas
Technoptions
Developer Insights
Q & A
Opinions

Archives
Calendar of Events
ASP Directory
Other Cahners Pubs

Submit a Release
Meet our Staff
Contact Us
Advertise
Magazine Subscription

Hopping the PalmOS Express

You’re attracted to the leading operating system for PDAs. But first you’ve gotta catch the clue train.

by bryan morgan
September/October 2001

So Palm had a rough year like nearly everyone else. Its operating system still rules in mindshare, licensees and the number of units deployed. Thousands of applications have been developed for it, proof that the lifeblood of a computing environment stems from quality applications that attract end users. If developers must “arrive” at a platform before the user base builds, however, how to attract developers?

Developers have flocked to writing applications for the Palm OS for several reasons: its modular design and powerful API support for user interfaces, databases, data synchronization, communications and memory management. These APIs are provided in standard C programming language, making C the hottest programming language for the Palm OS.

Granted, this preeminence is being challenged by other top development tools, including Pumatech Satellite Forms, AppForge and Java 2 Micro Edition. But C/C++ will probably rule commercial Palm application development due to its direct tie-in with the system APIs.

Writing applications for the Palm OS requires grasping several fundamentals. Here’s a breakdown.

Development Tool Options

The first step: settle on the best tool. Two leading C programming toolkits for Palm development are the PRC-Tools (based on GNU GCC - www.sourceforge.net/projects/prc-tools/) and Metrowerks’ CodeWarrior Integrated Development Environment. The PRC-Tools package offers a set of command-line tools, including a compiler and a linker for the Windows platform and most Unix platforms, including Linux. Metrowerks’ CodeWarrior is the leading commercial development environment. It includes a compiler, resource editor, online help, a graphical form designer and a debugger. It’s a first-class environment, available for both Windows and the MacOS. Preferences vary–some prefer command-line tools to GUI editors–while others prefer developing under Linux or using free software based on the GNU license. Either of tool will work. Download a free trial version of CodeWarrior from www.metrowerks.com/products/palm/demo.

Typical Application Architecture

First, consider the architecture of a typical Palm application, which is single-threaded (like the OS itself). Only one application may run in the foreground at any time. Each application must contain an entry-point function named PilotMain(). PilotMain() accepts a launch code as its first parameter, a value normally set to sysAppLaunchCmdNormalLaunch. This value is sent when a user selects the application’s icon from the Palm OS Launcher. The complete signature for PilotMain() is:

UInt32 PilotMain (UInt16 launchCode, MemPtr cmdPBP, UInt16 launchFlags)

where cmdPBP and launchFlags represent launch parameters and flags, respectively. Once begun, an application typically loads its main form and begins handling user events. The Palm OS is event-driven: All applications interact with the OS and the end user through the use of events, fired when something happens. For instance, clicking the device screen with the stylus triggers the penDownEvent event, which can then be “handled” by the current application. C programs handle these events through a continuous event loop that examine each event sent to the application.

The Palm OS system APIs are broken into logical groups in a handy naming convention. For instance:

• Form-related functions begin with Frm (such as FrmDispatchEvent(), FrmSetFocus(), and FrmGotoForm())

• Database functions begin with Dm (such as DmNewRecord(), DmQuickSort(), and DmQueryRecord())

• Memory-management functions begin with Mem (such as MemHandleNew() and MemPtrNew())

• Bar-code scanning functions begin with Scan (such as ScanGetDecodedData() and ScanOpenDecoder())

Another item that sets Palm applications apart from their desktop relatives is the use of a 4-byte Creator ID to help identify an application, specifically the databases used by that application. This is used by the system when displaying application size, during synchronization and during cleanup after an application has been marked for deletion. Before deploying your application, visit to obtain your Creator ID.

On with the Code!

Now, let’s explore a typical entry point in more detail. Nearly every Palm OS application includes a PilotMain that looks very similar to PilotMain (). Note the call to StartApplication (for general application initialization functionality, such as database initialization, form loading, etc.) followed by the starting of the event loop. This event loop will run for the life of the application until some event (such as appStopEvent) is sent by the operating system, ordering the application to exit. When the event loop exits, StopApplication is called to perform any necessary clean-up.

A conventional StartApplication() function might load and display the application’s main form using the FrmGotoForm() system API call:

In the code just above, frmMain references the handle to an application “resource” defined in a separate code file. If you’re using CodeWarrior, this application resource can be created using the Constructor resource designer tool. The real work of the application is handled inside the EventLoop() function that we have defined. EventLoop() and inside the ApplicationHandleEvent() function. Check out the code listing below. This process gives the system and the menu bar a “first shot” at handling the event. If they choose not to handle it, we can examine the event inside our own ApplicationHandleEvent() function. If we also choose to pass on it, we send it back on to the operating system using the FrmDispatchEvent() API call.

After a bit of routine work, all of our efforts come down to the ApplicationHandleEvent() function that we must define. It is inside this function that we set up our event handler functions
for each form in our application. In the code listing below, the ApplicationHandleEvent() function traps the frmLoadEvent event for our main form, makes it active, then sets the event handler for that form using the FrmSetEventHandler() API call.

Within that event handler function (we’ve called ours frmMainEventHandler()), we then write code to handle every possible user action, including button clicks, combo box selections
or any other event that we’d like to handle.) By understanding this event-driven paradigm, you are well on your way to beginning the Palm OS development project of your choice.

Final Notes...

Thanks to programmer Greg Hewgill, Palm developers are able to quickly test and debug running applications on their desktop through the use of the Palm OS Emulator tool, or “POSE” as it is better known. POSE may be downloaded for free from Palm at www.palmos.com/dev/tech/tools/emulator/, but you’ll need a valid device ROM first. A ROM can be
obtained off an actual Palm OS device (using the ROM Transfer.prc application included with POSE) or they can be obtained directly from the Palm Resource Pavilion at www.palmos.com/alliance/resources/, pending registration and approval.

Perhaps your next development project involves synchronizing the data to/from the mobile device back to an enterprise database. Palm handles this through the HotSync process and the Conduit API. Conduits are libraries run on the desktop (or on a department server) as part of the HotSync process and must be developed separately from the actual mobile device application. Palm currently supplies Conduit APIs for a range of languages including C, Java, and COM (for Visual Basic, Delphi, etc.). For more on conduits, download the free Palm Conduit Development Kit, or CDK.

The Palm OS is far from being a closed-end, “gadget” platform. Its rich suite of software APIs and hardware capabilities make it the platform of choice for more than 100,000 registered Palm developers. No matter what language you’re planning on developing with, getting started with C programming on the Palm OS allows one to become fully versed in the Palm OS system architecture. Knowing what goes on “beneath the hood” can save a great deal of debugging time and separates great developers from the rest.

Bryan Morgan is a software developer for a major corporation and a regular DevBiz contributor.