The PIM Library (PIM) is a shared library for PDA Toolbox applications and is the successor to the Built-In Apps Library. It is compatible with both PDAT/Advanced and PDA Toolbox 6.0 Professional. It provides sending data to the Palm OS built-in applications and assorted other applications.

This manual assumes the reader has familiarity with the PDAT Professional or the PDAT/Advanced application.

The PIM Library is a Shareware Library for the Palm OS 4.x through OS 5.x (Garnet OS) and above with limited support for Palm OS 3.5 and below.  Expanded Memo size requires the Palm Tungsten|3 (OS 5.2.1).  The Kinoma Player and Web Browser are not built-in only on the Tungsten|3, but may be separately installed by the user on other devices.  This library requires approx. 26k of memory storage.  For more information click here.

Understanding the Library

The PIM Library is based on PalmSource's recommendations for sending data to the internal Personal Information Manager (PIM) applications.  The technique uses the Exchange Manager and has several useful side-effects:

• Device/Brand/Model Portability: Using the Exchange Manager means that you can send data to, for example, the Contact application, regardless of which model and OS is being used (4.x and higher).  This is important as starting with PalmOne's Tungsten T3, the PIM applications have started to vary considerably.  Because the internal format for the basic PIMs are standard, sending memos, tasks, appointments, and contacts through beaming and Bluetooth to a mobile phone is supported.  
• 3rd Party Portability: If a user decides they like a 3rd party replacement for one of the built-in PIM applications, there is a high likelihood that the replacement app will "register" itself with the OS to be an Exchange target.  This means that the "fancy do-all contact manager" will accept contacts sent to it rather than the application being replaced.  You can even allow the user to decide between 2 or more "handler" applications which they want to receive the data.
• Transport Layer Portability: The actual transfer method that Exchange Manager uses to send the data can vary.  You can send to the same device or send through the IR Port, Bluetooth, or WiFi all with the same library actions.

The supported applications are:

• Task app (pre OS 5.x, automatically detected)
• DateBook app (pre OS 5.x, automatically detected)
• Memos app (pre OS 5.x, automatically detected)
• Mail app (pre OS 5.x, automatically detected)
• Tasks app (OS 5.x and higher, automatically detected)
• Calendar app (OS 5.x and higher, automatically detected)
• Memos app (OS 5.x and higher, automatically detected)
• Contacts app (OS 5.x and higher, automatically detected)
• The default Web Browser (OS 4.x and higher)
• The default Email Client (OS 4.x and higher)

Your application may send data to any of these apps with many of the available application-specific options.  For example, the Task list supports the Due Date, Priority, and Notes capabilities while the Calendar supports timed and non-time appointments, alarms including advanced notice and repeating events.

All data can be sent either as a literal or as a PDA Toolbox field ID:

pim.Task "Reminder to register MyApp", 1, "OneWeek"
pim.Task [TASK], [PRIO], [DATE]

The first line shows creating a Task task with a priority of 1 and due in one week from today.  The "OneWeek" is one of several verbs that can be used with date and time specifications in the PIM Library.  If you want to include data from the active record in your PDA Toolbox app, then you specify each field ID quoted with "[ ]" symbols.  The second line shows a generic task being sent to the Task database using all database fields. 

An especially powerful feature is the ability to mix and match fields with quoted text:

pim.Task "[TASK] for [NAME]", [PRIO], [DATE]

That example will replace [TASK] and [NAME] from the database record contents, and merge into one field - "Clean Room for Zoe"

When can you use these commands?  If you are writing a "hard-wired" value (e.g. "Change Oil" in 90 days)  then you can use this anywhere.  However, if you are sending data from your database, then you must be on a open and saved record.  This means that if you have a table with a button to export data, it won't work since the database is not opened (the table is filled, but it's closed afterwards!)   For best results, use these commands in your "detail" or "editor" forms where you have a record and Next/Previous type buttons.

Behaviors

Unlike the Built-In Apps Library, the PIM Library cannot silently send information to a PIM application.  Each item that your application sends must be reviewed and accepted by the user before it can make it into the database.  Acceptance means that a brief description of the record is shown to the user along with Yes and No buttons.  If the user wants to accept the record they may tap the Yes button.  At the same time, the user may assign the record to a category within the application.  

If the user declines the record, there is no notification or indicator that the record has not been accepted.  This is due to the possibility that the user may have beamed (or sent via Bluetooth/WiFi) the record to another device.  This implies that you must not assume a record made it into the target database.  Also, do not automatically delete a record after sending to a PIM as the record may have been declined!

There are a couple things that are not allowed by the Exchange Manager: You cannot set a record to be sent as "Private" and you cannot assign a category.  Both of these functions are supposed to remain in control by the end-user.

Exchange Parameter Syntax

For most of the actions in this library, the optional final three parameters are used as instructions for "how to send the data".  These "exchange parameters" control the Exchange Manager and allow you to specify how you want the data sent:

pim.Task taskItem, taskPriority, taskDate, Description, Mode, GotoApp

The Description parameter is displayed on the "Transfer" screen.  This is a very short note telling the user what you are requesting they add to their PIM.  The Description is not added into the PIM entry itself.  The Description can be created from PDAT database fields or as a literal. It may not be blank - if it is, it will default to the "PIM Item" string where PIM is the application name of the PIM.

The "Transfer" screen shown when an item is requested to be added into a user's PIM.

The Mode parameter allows you to specify the transport layer that is to be used.  A transport layer is the way the data is sent and includes sending to the PIM application on the device ( "_local" ), sending to another device using the IR Port ( "_beam" ), and sending via Bluetooth, SMS, or WiFi ( "_send" or "?_send").  This value can be a string literal and/or a string database field value.  There is an extended syntax for PDA Toolbox Professional developers.

When the mode is "_local", you can have the PIM application activated after sending it the data.  This is the GotoApp parameter and is either a "1" to switch to the PIM application or a "0" to stay in the current application.

As these exchange parameters are optional, if you do not include them, then it is assumed you want to send the data to the local device and continue your application instead of switching out to the PIM.

Branching After Action

For developers using PDAT/Advanced only, the pim.Memo, pim.Task, pim.Cal, and pim.Contact actions will return only a success/failure indicator.  If successful, then the script will continue to execute.  If the send failed or the item was not accepted, then the script exits.

For PDAT Professional SP6+ only, the pim.Memo, pim.Task, pim.Cal, and pim.Contact actions will return a branch-result.  Unlike many of the libraries, there are three branches that it can take after the pim action:

1. Success: This branch is taken after the item has been successfully sent and accepted.
2. Failure: This branch only occurs if there was an error in actually trying to send the item.  This may be memory, incorrect format of parameters, no data to send, etc.
3. User-Cancelled: This branch is taken when the item was sent ok, but the user did not accept the item into the PIM.

Branch Coding with PDAT Professional 

When programming in Professional, you must include the three GOTO Branches.  They may all branch to the same place, but they must be present.  Here is example coding for correct branching after the PIM call:

'Send the task - The 3 Goto actions are required!
   pim.Task "[TASK] for [NAME]", [PRIO], [DATE]
   Goto @Success
   Goto @Failure
   Goto @Cancelled
@Success:
   'Do something good
   Goto @Continue
@Failure:
   'Report problem or handle it.
   Goto @Continue
@Cancelled:
   'Report cancellation or handle it.
@Continue

NOTE: If you use the GotoApp parameter to switch to the PIM after successful acceptance of the data item, then the PIM action must be the last action keyword in the action block. Any branching or other statements will suppress the switch-app action.

The Actions provided by this library are divided into the following functionality categories:

Tasks Application

• pim.Task

Calendar Application

• pim.Cal
• pim.Cal.Alarm
• pim.Cal.RptAlarm

Memos Application

• pim.Memo

Contacts Application

• pim.Contact

Email Application

• pim.Mail
• pim.MailCC
• pim.SendMail

Exchange Manager Application

• pim.GoURL
• pim.Send

Before you can use the actions contained in this library, you must first "plug" it into PDAT/Advanced.  Once plugged in and registered, you will be able to use and distribute this library freely.

1. First, install the "PDATPimLib.prc" file onto your development handheld.  This should also have a copy of PDAT/Advanced.
2. At PDAT/Advanced's Open Screen, tap the menu and choose from the Advanced menu "Manage Libraries".
3. Next, if the "PIM Library" is not shown in the list, tap the "Add" button.
4. In the "Add Library" dialog, enter in the Library ID of "PIMZ" (without the quotes).
5. Next, enter the license information you received when you registered.
6. Lastly, tap the "Done" button.

After successful registration, when you are editing actions, you'll have a second button named "Lib" which pops up a list of all the commands available to you.

The DEMO MODE will allow you to compile your application, but will display a "Nag" alert every time the library is invoked.

Using With PDA Toolbox 6.0 Pro Script Editor

To use this library with the Pro Script Editor, you need to download the PDA Toolbox Windows Plug-In for the PIM Library.  This is available at www.SandsUSA.com/PDAT.  Follow the installation instructions contained within the archive.

The primary difference between using these actions with PDAT/Advanced and the Pro Script Editor is that the Script Editor does not require the leading "$" for each action.  In addition, in PDAT/Advanced, you can can wrap your action statements with carriage-returns and in the Script Editor, you must use the "_" line continuation character.

The file "PDATPimLib.prc" must be distributed with any application that uses this library.  Since you are distributing multiple PRC files that must be installed on the hand-held device, you may want to check out Ecamm's NutShell for the Palm OS at http://www.ecamm.com/palm/nutshell.  Nutshell is a unique installer solution, which allows users distribute multiple Palm files and data as a single self-expanding PRC file.  With this tool, the user installs a single file onto their hand-held and the first time your app is run, all the libraries, databases, and sub-programs are automatically unpacked and your app runs.  A very good solution to a sticky problem.

Each Action in the library will be described here.

Many of the parameters in this lib are "smart" and perform more than meets the eye.  The following table details the parameter types and the values they may have:

DATABASE NOTE: For hand-helds running an OS prior to OS 4.x, these routines all expect that the database for the Palm OS App in question have been created.  In other words, if the database is not there, an error occurs.  This will probably be ok for 99.9% of all people as folks tend to at least look at their apps before buying replacements for them  :)

You can use this action to send a task to the PIM Tasks application.  This uses the standard VCAL format so it may be compatible with different platforms (e.g. PalmOne, Sony, Microsoft Windows Mobile, and Symbian).  For PDAT Professional, this action will make a 3-way branch after the action is executed.  See Branching After Action for coding and details on how to use this.

You may omit any or all of the Description, Mode, and GotoApp parameters.  If you use Mode, then you must include Description, and if you use GotoApp, then you must include Description and Mode.  When omitted, these will default to "", "_local", and "0". 

Some 3rd party replacement applications for Tasks may receive the data instead of the Tasks app.  This is desired behavior.

Creates a basic date book appointment or bulleted calendar "note" without an alarm.  This uses the standard VCAL format so it may be compatible with different platforms (e.g. PalmOne, Sony, Microsoft Windows Mobile, and Symbian).  For PDAT Professional, this action will make a 3-way branch after the action is executed.  See Branching After Action for coding and details on how to use this.

You may omit any or all of the Description, Mode, and GotoApp parameters.  If you use Mode, then you must include Description, and if you use GotoApp, then you must include Description and Mode.  When omitted, these will default to "", "_local", and "0". 

Some 3rd party replacement applications for Calendar may receive the data instead of the Calendar app.  This is desired behavior.

Creates a basic date book appointment or bulleted calendar "note" with an alarm.  This uses the standard VCAL format so it may be compatible with different platforms (e.g. PalmOne, Sony, Microsoft Windows Mobile, and Symbian). For PDAT Professional, this action will make a 3-way branch after the action is executed.  See Branching After Action for coding and details on how to use this. 

You may omit any or all of the Description, Mode, and GotoApp parameters.  If you use Mode, then you must include Description, and if you use GotoApp, then you must include Description and Mode.  When omitted, these will default to "", "_local", and "0". 

Some 3rd party replacement applications for Calendar may receive the data instead of the Calendar app.  This is desired behavior.

Creates a basic date book appointment or bulleted calendar "note" with an alarm that repeats. This uses the standard VCAL format so it may be compatible with different platforms (e.g. PalmOne, Sony, Microsoft Windows Mobile, and Symbian).

The value of RptDay depends on the Type parameter.   If the Type=2 (Weekly), the RptDay parameter is the day of the week that you want to repeat on.  This is a set of flags:

If you wanted the to repeat every Sunday, then RptDay = 1.  If you wanted to repeat weekly on Sun and Mon, then the value is 1 + 2 = 3.  This allows you to have multiple days defined for weekly repeatition.   However, if you want to repeat based on the current date, then enter 0.  This will take the current day and repeat forward.  The value of 1=Sun actually depends on the system preferences.

If the Type parameter is 3 (MonthlyByDay), the RptDay value is the day of the month (e.g. 21st) that is converted to a repeating pattern (e.g. 4th Friday of Each Month).  If the value is 0 then the current date/day is used and converted to a repeating pattern.

If the Type parameter is 4 (MonthlyByDate) then the repeating pattern is the appointment's date repeated monthly.

For all other types, the RptDay should be zero.

You may omit any or all of the Description, Mode, and GotoApp parameters.  If you use Mode, then you must include Description, and if you use GotoApp, then you must include Description and Mode.  When omitted, these will default to "", "_local", and "0". 

Some 3rd party replacement applications for Calendar may receive the data instead of the Calendar app.  This is desired behavior.

This action is only supported on Palm OS® 4.x and higher.

For PDAT Professional, both of these actions are identical: They create a contact entry in the Contacts application. This uses the standard VCARD format so it may be compatible with different platforms (e.g. PalmOne, Sony, Microsoft Windows Mobile, and Symbian).  PDAT/Advanced developers must provide all the parameters with each parameter being self-explanatory.  For PDAT Professional, this action will make a 3-way branch after the action is executed.  See Branching After Action for coding and details on how to use this.

Unlike the other PIM Actions, the pim.Contact action has so many parameters available to it that the syntax is modified.  The first parameter is a list of the fields you want to send to the contact.  The remaining fields are provided in the order shown in the first parameter:  If your first parameter is "^name ^company" then it means you are going to provide two additional parameters - the first evaluates to a name and the second evaluates to the company name:

pim.Contact "^name ^company", "[NAME]", "[COMP] Inc."

The list of parameter tags that you may use are a super-set of the tags used with the PhoneBook action.  The following table summarizes them:

Note #1: These values are not supported by the PhoneBook action.  The customLbl- tags are only used to smart-match up custom data on the destination.  They may or may not have any impact.
Note #2: The Description, Mode, and GotoApp parameters are treated the same as any other parameter except they have default values ("", "_local", "0").

Some 3rd party replacement applications for Contacts may receive the data instead of the Contacts app.  This is desired behavior.

This action takes a URL and launches the app that is responsible for it.   It is, however, a launch and pray operation as there may be no application defined to handle it.  If there is a browser installed on the handheld, then this action should work. 

You can also use the "mailto" URL syntax, however, there are some very mixed reports on the ability for the various mail client software to handle this.  This function will be expanded as more info is know.  The syntax for the mailto is similar to the following examples:

• pim.GoURL "mailto:Rick@SandsUSA.com"
• pim.GoURL "mailto:Rick@SandsUSA.com?subject=Test Sub&body=This is a test message."
• pim.GoURL "?mailto:Rick@SandsUSA.com" (this should ask which email client if more than one!)
• pim.GoURL "http://www.SandsUSA.com"

This action seeks out and supports the following browsers:

• Blazer 3.0 (NetFront-based, OS5, Treo600)
• Blazer 1.0/2.0
• Netfront (Sony CLIE)
• Novarra Web Pro
• PalmSource Web Browser/NetFront
• AvantGo
• EudoraWeb
• Clipper (Web Clipping)
• When none of these are present, it will try to launch the URL via the exchange manager.

It does not support the following due to them not being "launchable":

• PocketLink
• Xiino / PalmScape

Branching after the action is not supported since the browser needs to switch into memory.

Creates a new message in the email application Outbox.  See comments in pim.SendMail for details on how this message is actually sent as the SendMail action is actually used for mail composition..

Creates a new message in the email application Outbox.  See comments in pim.SendMail for details on how this message is actually sent as the SendMail action is actually used for mail composition..

This action creates a memo in the MemoPad or Memos application.  For PDAT Professional, this action will make a 3-way branch after the action is executed.  See Branching After Action for coding and details on how to use this.

Remember that the first line is used as a title.  In the above example, the "Test Memo" is considered the title since there is a "\n" after it, and the [NOTE] is replaced from the current record's "NOTE" field.

If the Memo Pad database has not been created then an error message is displayed and the action returns a failure.

For the Palm Tungsten|3 handhelds, the maximum memo size is 32k.  For all other devices, the maximum memo size is 4k.

You may omit any or all of the Description, Mode, and GotoApp parameters.  If you use Mode, then you must include Description, and if you use GotoApp, then you must include Description and Mode.  When omitted, these will default to "", "_local", and "0". 

Some 3rd party replacement applications for Memos may receive the data instead of the Memos app.  This is desired behavior.

From the Kinoma SDK:

Branching after the action is not supported since the Kinoma Player needs to switch into memory.

This is similar to Beam Memo, but giving the choice of whatever client applications are capable of sending text.  For example, on a Tungsten T3, it is capable of sending text via Bluetooth, SMS, or VersaMail by default.  The user selects the tool to perform the send.

The Text field can be built using a literal or a combination of literals and field IDs.  It may be blank.  The required filename does not have a path, but an file type is important.  The ".txt" tells Exchange Manager to send it to text accepting clients.  A file type of ".prc" will send a PRC to the other device's Launcher application.

Creates a new message in the email application Outbox with all options.   

The various flags can be field references to checkbox field values in the current record.  

How is the Message Sent?

Sending a message with pim.Mail, pim.MailCC, and pim.SendMail is not guaranteed to work as the PDA may not have a valid email client.  The approach that is taken on this is to try to send to a specific (known) email client, and if that fails, then try to send to a known web browser.  You do not need to URL-encode the parameters.

The directly compatible email clients are:

• SnapperMail (www.snappermail.com)
• VersaMail (www.PalmOne.com)
• Palm OS Mail (on some older devices (pre-OS5.x))

And if those are not present, then it will send to whatever browser is available on the system using the "mailto:" URL, if any.

NOTES:

•  SnapperMail and "mailto:" do not processes the Priority, ConfID, ConfR, and Sig.  
• The "From" parameter is ignored by VersaMail: It always assumes the account it's being sent from is the "from"

This program is not Freeware.  It is Shareware.  This means that you can, and should, try the library before buying.  Shortly after you register via PayPal, PalmGear, or Handango, you will receive an unlock key that will enable full development with this library.

You may use the unregistered version for testing purposes only.  A nag alert will display as you run your application.

 The cost of this package is US$12.95.  For registered owners of the Built-In Apps Library, an upgrade can be purchased for US$5.45.

You can always contact me at:

email: Rick@SandsUSA.com or at my site http://www.SandsUSA.com/PDAT.

Version History

Version 2.02 - Jun-22-2005

• PlayKMovie accesses just the external memory card if a leading "/" is supplied.

Version 2.01 - May-2-2005

• Fixed problems with SendMail (Mail, MailCC)
• New: VersaMail added as supported email client.

Version 2.00 - Mar-13-2005

• Renamed from Built-In Apps Library to PIM Library
• Prefix changed from "ba." to "pim."
• Task renamed to Task
• DateBk/DateBook now referred to as Cal (Calendar)
• Added support for sending Contact info (VCARD)
• Added support for sending Calendar info via VCAL
• Added support for sending Task info via VCAL (Calendar passes on to appropriate Tasks Manager)

Version 1.11 - May-14-2004

• $ba.Send uses the Exchange Manager to send via a user selected client application to another device.

Version 1.10 - Oct-18-2003

• $ba.Memo will now automatically support the 32k Memos for the Memos app in ROM on the Palm Tungsten|3
• New: ba.PlayKMovie allows playing videos using the Kinoma Player (in ROM on the Palm Tungsten|3)
• New: ba.GoURL will launch a website from a connected device.

Version 1.09 - Jan-19-2003

• Now formatting Dates using system short date preference (effects most actions)
• Now formatting Times using system time preference (effects most actions)

Version 1.08 - Dec-14-2002

• Updated Documentation with minimum Palm OS
• Now checks ToDo, Datebk, and Memo for missing databases.
• Version number corrected on file, version resource, and info dialog.

Version 1.07 - Sep-22-2002

• Fixed: Literal string coding \xxx now allows for characters > \199.

Version 1.06 - Jul-08-2002

• New: Default values for Weekly and Monthly-By-Day Repeating Alarms (use current if value = 0).
• Updated: Clarified documentation on repeating appointments.

Version 1.05 - Jul-05-2002

• Fixed: Alarm time was being "rounded." 

Version 1.04 - Jul-04-2002

• Fixed: Wrong parameter count after combining Datebook routines - now it repeats correctly.
• Fixed: Changed the DateBk.RptAlarm parameter list when inserted into the script so it all shows (sort of).
• Fixed: The "NoDate" dates were being obliterated into "today" values.
• Updated: Documentation to reflect correct parameters for the date repeating alarms.

Version 1.03 - Jul-01-2002

• Fixed: Another bug if the database existed but the record was new and untouched it would crash.  Not anymore...

Version 1.02 - Jun-24-2002

• Fixed: Trying to send a new database record to a built-in app.
• Updated: Documentation

Version 1.01 - Jun-20-2002 - Initial Release

Version 1.0 - May-2002 - Beta Release

"The Software" is "PIM Library" aka "PDATPimLib.prc" by Richard R. Sands dba Sands USA.

DISCLAIMER #1 - MUST READ

This product is an "After-Market" utility for PDA Toolbox(tm) and as such, is subject to obsolescence by changes in PDA Toolbox or the Palm OS(tm) itself.  This cannot be prevented.  I may choose to stop or limit development and support of this product if such situation occurs. 

USER LICENSE AGREEMENT

This Agreement sets forth your licensed rights to use "The Software" and is granted to you upon condition that you accept the terms of this license. Your electronic indication of agreement, or your use of the program constitute acceptance of all of the terms of this license.

The program copy and documentation are furnished to make "The Software" available for your use and remain the property of Sands USA.

IF YOU DO NOT AGREE WITH ANY PART OF THIS LICENSE, DO NOT USE THIS SOFTWARE. Delete "The Software" and all associated files from all media on which it has been copied. 

LICENSE TERMS AND CONDITIONS

THE LICENSED PRODUCT
"The Software" comprises copyrighted computer programs and utilities for the reporting of Palm OS(tm) application databases (PRC) created by the PDA Toolbox(tm) Application Generator. The Licensed Product in its entirety is protected by US and foreign copyright.  YOU MAY NOT DISTRIBUTE THE LICENSE CODE provided to you.

YOUR USE OF THE LICENSED PRODUCT
General Use. You have the right to use "The Software" with PDAT/Advanced and to distribute the library file "PDATPELib.prc" but not documentation, license codes, or other information about this library.  For those purposes, you have the right to install the "The Software" and any associated files on one (1) computer. Use of "The Software" on a network or any other arrangement by which its functions are accessible to more than one user at a time is not permitted. 

LIMITATIONS ON USE
General Use Limitations. You have no right to reproduce, transfer, publish or otherwise distribute either the "The Software" software, or any components or documentation provided.

ALL RIGHTS NOT SPECIFICALLY GRANTED BY THIS LICENSE ARE RESERVED BY SANDS USA. 

WARRANTIES, WARNING, DISCLAIMER

Warning and Disclaimer of All Warranties. THE PROGRAM IS FURNISHED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, IN ALL JURISDICTIONS WHERE ALL WARRANTIES MAY BE DISCLAIMED IN THE LICENSING OF INTELLECTUAL PROPERTY.

PDAT/Advanced is Copyrighed by Richard R. Sands dba Sands USA
PDAT Toolbox is Copyrighted by Paul Prejean
PDA Toolbox Professional are Copyrighed by Paul R. Anderson and Richard R. Sands dba Sands USA

Nutshell executable and documentation are Copyright ©2002 by Ecamm Network. All rights reserved.
RsrcEdit is apparently not copyrighted by Quartus, but they are the caretakers of RsrcEdit.
Windows is a Trademark of Microsoft Corporation

Documentation Copyright (C) 2002-2005 Richard R. Sands dba Sands USA
All Rights Reserved

And Finally, ...

palmOne, Zire, Tungsten, Treo, Blazer, VersaMail, Addit, Handspring, stylizations and design marks associated with all the preceding, and trade dressings are associated with palmOne, Inc.’s products, are among the trademarks or registered trademarks owned by or exclusively licensed to palmOne, Inc. All other brand and product names are or may be trademarks of, and are used to identify products or services of, their respective owners.