Creator Codes and Database Types

Every database or application on a Palm OS device has a Name, a Type and a Creator code.  A creator code is a four-character code that uniquely identifies all of the databases or files associated with an application.  PalmSource, the company that manufactures the Palm OS, keeps a registry of creator codes to ensure their uniqueness across different software developers.  

For example, the Palm OS Address Book application has a creator code "addr".  The AddressBook program and its databases all have this creator code.  

Creator codes with only lowercase letters are reserved for Palm OS built-in applications.

Each "file" in the Palm OS also has a database type.  Programs have the type "appl", shared libraries have the type "libr", and Data files have the type "Data" or "DATA".  There are also many other database types, but these four are the most common.

The built-in Address Book application program has the name "Address Book", has a creator code "addr", and has type "appl".  The actual addresses are stored in a database called "AddressDB" with creator code "addr" and type "DATA".

Using the LAUNCH Statement

To use the LAUNCH statement, simply specify the creator code of the application you want to launch, e.g.,

LAUNCH addr

This script locates the first database that has a creator code of "addr" and a type of "appl".  In this case, this will launch the Address Book application.  

The LAUNCH statement works just like the launcher application, in other words, Pendragon Forms exits, and the other application takes over.  No information is carried from Pendragon Forms to the application that is being launched.

Using the CALL Statement to Run a C Program

The CALL statement is used to call a function in another program without leaving Pendragon Forms.  Programs that can respond to Pendragon Forms CALL statements are called "accessories".  They are created just like standard Palm OS applications except they have a database type of "acry".

Every Palm OS application has a PilotMain function that receives a pointer to some data and a launch code.  The launch code tells the program how to behave when launched.  Launch codes are used by Palm OS to notify applications of system events like Resets and HotSyncs, and to perform certain system functions such as using Global Find.

When you use the CALL statement, Pendragon Forms searches for a database with the creator code you specify and with database type "acry".  It calls the PilotMain function in the Accessory database and passes it the launch code 33333.  It also passes to the Accessory a pointer to the RESULT variable.  Any changes to the RESULT variable are preserved by the CALL statement.

Sample Accessory

Here is a sample Accessory application.  For demonstration purposes, this Accessory simply reverses the characters in the RESULT variable, e.g.,

CLICK:

   RESULT = "ABC"

   CALL "REVS"

   MSGBOX RESULT    {RESULT should be equal to "CBA"}

The C code for the PilotMain function of the Accessory looks like this:

DWord PilotMain(Word cmd, Ptr cmdPBP, Word launchFlags)
{
    Err error;
    CharPtr data;
    int i, len;
    char ch;


    error = RomVersionCompatible (ourMinVersion, launchFlags);
    if (error) return (error);


#define sysAppLaunchCmdFormsCall 33333

    switch (cmd)
    {
    case sysAppLaunchCmdFormsCall:

        data = (CharPtr) cmdPBP;
        len = StrLen(data);

        for (i = 0; i < (len / 2); i++) {
            ch = data[i];
            data[i] = data[len - i - 1];
            data[len - i - 1] = ch;
        }
        //done!
        break;
    case sysAppLaunchCmdNormalLaunch:
        error = AppStart();
        if (error) 
            return error;

        FrmGotoForm(MainForm);
        AppEventLoop();
        AppStop();
        break;

    default:
        break;

    }

    return 0;
}

The highlighted code actually does the work of reversing the text.  cmd is the launch code, and cmdPBP is a pointer to the RESULT buffer.

Other than responding to the special Pendragon Forms launch code, the only difference between an Accessory and a normal Palm OS application is that it has a database type of "acry" instead of "appl".

Note that your Accessory is launched without global variables.  If you try to access a global variable while handling a CALL, your Accessory will crash.

You may call SysAppUISwitch from your accessory to launch another application.  This is because SysUIAppSwitch launches applications by placing events in the system event queue.

You can download the complete example Accessory here.
Note that the creator code of the Accessory sample is "Acry" instead of "REVS".