December 16, 2017
Hot Topics:

Application Launching

  • August 21, 2003
  • By Alex Gusev
  • Send Email »
  • More Articles »


The goal of this article is to describe what do you need to do to effectively use Palm OS's launching mechanism. Under an operating system such as Windows, an application usually starts when a user requests it. This may be a result of using some kind of input device such as a keyboard, mouse, or stylus. It may also result from another application. This is also true for Palm OS applications. Additionally, a Palm application may also start in response to events like a HotSync action, a global find, a reset and so forth. Some application may even support specific launch codes that allow other programs use them as a subroutine. Let's start with the code for launching an application in the Palm environment.

Launch Codes

Palm OS application begins to work just after they receive launch code from the operating system. The first parameter of PilotMain is used to pass this code through:

UInt32 PilotMain ( UInt16 cmd, 
                   void *cmdPBP, 
                   UInt16 launchFlags)

In many cases an application is launched normally and thus the application responds to cmd = sysAppLaunchCmdNormalLaunch. Each time the user changes the system time, presses the HotSync button, resets the PDA or does any other action that may launch an application, then the Palm OS sends a corresponding launch code to all installed applications. Therefore, launch codes may be used as a means of communicating between the Palm OS and an application. Other applications are able to interact with each other in this same way.

Let's take a look at the Datebook entry point:

static UInt32 DBPilotMain ( UInt16 cmd, 
                            void *cmdPBP, 
                            UInt16 launchFlags)
   UInt16 error;
   Boolean launched;

   // This app makes use of PalmOS 2.0 features.It will crash
   // if run on an earlier version of PalmOS. Detect and warn
   // if this happens, then exit.
   error = RomVersionCompatible (version20, launchFlags);
   if (error)
      return error;

   // Launch code sent by the launcher or the datebook
   // button.
   if (cmd == sysAppLaunchCmdNormalLaunch) {
      error = StartApplication ();
      if (error) return (error);

      FrmGotoForm (DayView);
      EventLoop ();
      StopApplication ();

   // Launch code sent by text search.
   else if (cmd == sysAppLaunchCmdFind) {
      Search ((FindParamsPtr)cmdPBP);

   // This launch code might be sent to the app when it's
   // already running if the user hits the "Go To" button in
   // the Find Results dialog box.
   else if (cmd == sysAppLaunchCmdGoTo) {
      launched = launchFlags & sysAppLaunchFlagNewGlobals;
      if (launched) {
         error = StartApplication ();
         if (error) return (error);

         GoToItem ((GoToParamsPtr) cmdPBP, launched);

         EventLoop ();
         StopApplication ();
         GoToItem ((GoToParamsPtr) cmdPBP, launched);

   // Launch code sent by sync application to notify the
   // datebook application that its database has been synced.
   // ...
   // Launch code sent by Alarm Manager to notify the
   // datebook application that an alarm has triggered.
   // ...
   // Launch code sent by Alarm Manager to notify the
   // datebook application that is should display its alarm
   // dialog.
   // ...
   // Launch code sent when the system time is changed.
   // ...
   // Launch code sent after the system is reset. We use this
   // time to create our default database if this is a hard
   // reset
   // ...
   // Launch code sent by the DesktopLink server when it
   // creates a new database.  We will initialize the new
   // database.
   return (0);

As you see, there are lot of codes your application may receive. It's totally your responsibility to decide which of them your application will respond to. Additionally, you may define your own launch codes as. If you create your own, you'll want to see the note in SystemMgr.h:

// Custom action code base (custom action codes begin at this value)
#define  sysAppLaunchCmdCustomBase  0x8000

// Your custom launch codes can be defined like this:
//  typedef enum {
//    myAppCmdDoSomething = sysAppLaunchCmdCustomBase,
//    myAppCmdDoSomethingElse,
//    myAppCmdEtcetera
//    } MyAppCustomActionCodes;

You may ask why a custom launch code may be needed. The answer is that such an approach gives you powerfull possibility to use your application from others mdash; it provides a kind of API. There are many software packages mdash; written for printing, sending e-mails and so forth mdash; that can be used from other programs using custom launch codes.

An important thing to know is that you might not have access to global variables when your application receives launch codes with the exceptions of sysAppLaunchCmdNormalLaunch, sysAppLaunchCmdGoto and sysAppLaunchCmdURLParams, because they aren't allocated. A good practice for determining if your application has access to globals is to check the launch flags (the third parameter of PilotMain). If sysAppLaunchFlagNewGlobals flag is set, globals are allocated:

Boolean bGlobalsAreAllocated = 
    ((launchFlags & sysAppLaunchFlagNewGlobals) == 

The only exception to this rule is when your application calls itself (i.e. is running as current application). In this case the sysAppLaunchFlagNewGlobals flag may not be set, but global variables were already allocated through the previous call. You may check it as follows:

Boolean bAppIsRunning = 
    ((launchFlags & sysAppLaunchFlagSubCall) == 

Additionionally, if the application is multisegment, you cannot access code outside of the first segment if the application doesn't have access to global variables.

Page 1 of 2

Comment and Contribute


(Maximum characters: 1200). You have characters left.



Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date