Built-In Apps Library
Version 1.13 for PDAT/Advanced

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

Table of Contents
1. Library Overview 5. Library Actions Reference
2. Library Actions Overview 6. Purchasing Information
3. Plugging In the Library 7. Support and Version History
4. Distribution 8. Warranty/License

Library Actions Reference by $Action Name
BA.ToDo BA.MailCC
BA.DateBk BA.Memo
BA.DateBk.Alarm BA.PlayKMovie  (ver. 1.10)
BA.DateBk.RptAlarm BA.Send  (ver. 1.11)
BA.GoURL (ver. 1.10) BA.SendMail
BA.Mail
Library Overview

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

The supported applications are the To-do list, date book, email, and the memo pad application.  Your application may send data to any of these apps with many of the available application-specific options.  The To-do list supports the Due Date, Priority, and Notes capabilities.  The Date Book supports timed and non-time appointments, alarms including advanced notice and repeating events.

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

$BA.ToDo "Reminder to register MyApp", 1, "OneWeek"
$BA.ToDo [TASK], [PRIO], [DATE]

The first line shows creating a To-do 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 Built-In Apps 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 To-do database using all database fields. 

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

$BA.ToDo "[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.

It is also used as a "Plug-In" to PDAT/Advanced to provide additional Actions to your PDA Toolbox programs.  

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

The Built-In Apps Library is a Shareware Library for the Palm OS 3.1 and above.  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. 16k of memory storage.  For more information click here.

Library Actions Overview

The Actions provided by this library are divided into four categories of functionality: ToDo, DateBook, Email, and Memo applications.

To-Do Application

Date Book Application

Email Application

Memo Application

Exchange Manager Application

Plugging In The Library

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 "PDATBIA.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 "Built-In Apps Library" is not shown in the list, tap the "Add" button.
  4. In the "Add Library" dialog, enter in the Library ID of "Posa" (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 Built-In Apps 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.

Distribution

The file "PDATBIA.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.

Library Actions Reference

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:

Parameter
Type		 Possible Values
text
  • "any text literal that will not change" - Any text.
  • "[AFLD]" - A database TEXT field. 
  • \xxx - Embed a character you can't normally enter in the range of \000 to \255 (e.g. \065 = "A")
  • \n - Embed a line-feed into the string
  • \q - Embed a double-quote into the string ("\qTest\q" would be "Test")
  • \\ - Embed a "\" character into the string

All of these items may be embedded in one string: "Zen Master Says \q[QUOT]\q"
number
  • Any integer number.
  • [AFLD] - A database TEXT or CHECKBOX field.
date
  • [AFLD] - A database DATE or date value of an ALARM field
  • Any integer number - Today+Num days in the future.
  • "NoDate" - No date specified.
  • "Today" - Today's date
  • "Tomorrow" - Tomorrow's date
  • "OneWeek" - One week from today
  • NOTE: Literal dates are not supported (e.g. 5/15/2002)
time
  • [AFLD] - A database TIME  or time value of an ALARM field
  • 0 - 2400 representing a specific time/minutes in 24 hour notation.  This may be a starting or ending time.
  • +Mins - Used with an ending time only, specifies a duration (e.g. +45 would add 45 minutes to the starting time and use that for the ending time).
  • "NoTime" - May be used as appropriate to indicate a non-time.
  • NOTE: Literal times are not supported (e.g. 5:30)

DATABASE NOTE: 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 them :)

$BA.ToDo task, priority, duedate, note
Description: Creates a "To Do" list item.
Parameters: task: Text. The task item description.
  priority: Number. Priority level 1 to 5.  You can use 0, too.  Do not use over 5.
  duedate: Date. The date that this task is due.
  note: Text.  A note or "" if none.
Example: 

$BA.ToDo "[TASK]", "[PRIO]", [DUED], [NOTE]
$BA.ToDo "Check For New Software", 1, [DUED], ""

You can use this command to add "tasks" either entered by the user or coded into the program.

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

$BA.DateBk des, date, stime, etime, note
Description: Creates a basic date book appointment.
Parameters: des: Text. The appointment item description.
  date: Date. Date of the appointment.
  stime: Time.  Start time of the appointment.
  etime: Time.  Ending time of the appointment.  This is NOT the duration, but actual time
  note: Text.  A note.
Example: 

$BA.DateBk "This is a note", today, notime, notime, ""  (this will create a bullet appointment)
 

$BA.DateBk "Meet [NAME]", [DATE], [TIME], "+60", "[NOTE]"  (this will create an appointment on date/time for 1 hour (60 minutes)

Creates a basic date book appointment or bulleted calendar "note" without an alarm.

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

$BA.DateBk.Alarm des, date, stime, etime, adv, advUnits, note
Description: Creates a date book appointment with an alarm.
Parameters: des: Text. The appointment item description.
  date: Date. Date of the appointment.
  stime: Time.  Start time of the appointment.
  etime: Time.  Ending time of the appointment.  This is NOT the duration, but actual time
  adv: Number.  Number of minutes, hours, days.  Depends on value of advUnits.
  advUnits: Number.  0=Minutes, 1=Hours, 2=Days
  note: Text.  A note.
Example: 

$BA.DateBk.Alarm "[APPT]", [DATE], [TIME], "+60", 10, 0, "[NOTE]"  (Creates an appointment on date/time for 1 hour (60 minutes with alarm and a 10 minute advanced warning)
$BA.DateBk.Alarm "[APPT]", [DATE], [TIME], "+60", 2, 1, "[NOTE]"  (Creates an appointment on date/time for 1 hour (60 minutes with alarm and a 2 hour advanced warning)

Creates a basic date book appointment or bulleted calendar "note" with an alarm.

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

$BA.DateBk.RptAlarm des, date, stime, etime, adv, advUnits, Type, StopDate, freq, RptDay, note
Description: Creates a date book appointment with a repeating alarm.
Parameters: des: Text. The appointment item description.
  date: Date. Date of the appointment.
  stime: Time.  Start time of the appointment.
  etime: Time.  Ending time of the appointment.  This is NOT the duration, but actual time
  adv: Number.  Number of minutes, hours, days.  Depends on value of advUnits.
  advUnits: Number.  0=Minutes, 1=Hours, 2=Days
  Type: Number. Type of repeating date:
0=None, 1=Daily, 2=Weekly, 3=MonthlyByDay, 4=MonthlyByDate, 5=Yearly
  StopDate: Date. Date to stop repeating.  "NoDate" means repeat forever.
  freq: Repeat frequency value: i.e. every 2 days if Type=daily(1)
  RptDay: Day of week/month if monthlyByDay and repeatWeekly only. Otherwise 0.
  note: Text.  A note.
Example: 

$BA.DateBk.RptAlarm "[APPT]", [DATE], [TIME], "+60", 10, 0, 1, "NoDate", 1, 0, "[NOTE]"  (Creates an appointment on date/time for 1 hour (60 minutes with alarm and a 10 minute advanced warning which repeats every day forever.)

Creates a basic date book appointment or bulleted calendar "note" with an alarm that repeats.

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:

1 - Sun 2 - Mon 4 - Tue 8 - Wed 16 - Thur 32 - Fri 64 -Sat

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.

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

$BA.GoURL text
Description: Launches text as a URL using the default web browser.
Parameters: text: A valid URL encoded string
Example: 

$BA.GoURL "http://www.SandsUSA.com"
$BA.GoURL "http://www.[FURL].com"

This should be able to take a URL and launch 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:

$BA.Mail subject, message, to, from, priority
Description: Creates a new message in the email application Outbox.
Parameters: subject: Text. Subject text.
  message: Text. Body of the email message.
  to: Text. Email address of recipients.
  from: Text. Email address of sender.
  priority: Number. Message priority 0=High, 1=Normal, 2=Low
Example: 

$BA.MailCC "[APPx] Reg Info", "Reg name = \q[NAME]\q\nReg code is [CODE]",  [USEM], [MYEM], 1

Creates a new message in the email application Outbox.

$BA.MailCC subject, message, to, from, priority, cc, bcc
Description: Creates a new message in the email application Outbox.
Parameters: subject: Text. Subject text.
  message: Text. Body of the email message.
  to: Text. Email address of recipients.
  from: Text. Email address of sender.
  priority: Number. Message priority 0=High, 1=Normal, 2=Low
  cc: Text. Email address of carbon copy recipients
  bcc: Text. Email address of blind copy recipients
Example: 

$BA.MailCC "[APPx] Reg Info", "Reg name = \q[NAME]\q\nReg code is [CODE]",  [USEM], [MYEM], 1, [MYCC], [MYBC]

Creates a new message in the email application Outbox.

$BA.Memo text
Description: Creates a new message in the email application Outbox.
Parameters: text: Text. Whatever you want.
Example: 

$BA.Memo "Test Memo\n[NOTE]"

Creates a new entry in the MemoPad application.

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.

$BA.PlayKMovie filename
Description: Plays a movie using the Kinoma Movie Player and returns to the application.
Parameters: filename: filename of the movie to play
Example: 

$BA.PlayKMovie "Catalina"
$BA.PlayKMovie "[MOVI]"

From the Kinoma SDK:

Starting with version 1.1, Kinoma Player may be launched by other applications to open and play any Kinoma movie installed in main device memory. Beginning with version 1.5, Kinoma Player may also be launched to display a Kinoma movie stored anywhere on a VFS accessible storage device*. This capability allows any Palm OS based application to use Kinoma Player to display video and still images encoded in the Kinoma movie format.

There are some items to keep in mind that apply to sub-launching Kinoma Player whether the movie to be displayed is stored in main device memory or on a VFS storage device:

1. Do not assume that when Kinoma Player completes playback of the movie that the user will return to the launching application. The user can use the hard buttons or silk screen buttons on their Palm handheld to launch another application.

2. The controls and other user interface elements of Kinoma Player can be hidden by encoding the movie in Kinoma Producer by specifying a custom layout in the Advanced Settings dialog.

*Currently, movies on the expansion card are not available.

$BA.Send text, filename
Description: Launches a dialog to send text to another device.  
Parameters: text: Any text literal or text from a record.
  filename: A filename to send the text as. 
Example: 

$BA.Send "This is a memo!", "test.txt"
$BA.Send "Site: [SITE]\nhttp:// [URLS]\n", "URLS.txt"
$BA.Send "", "PDATBIALib.prc"

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.

$BA.SendMail subject, message, to, from, priority, cc, bcc, confD, confR, Sig
Description: Creates a new message in the email application Outbox with all options.
Parameters: subject: Text. Subject text.
  message: Text. Body of the email message.
  to: Text. Email address of recipients.
  from: Text. Email address of sender.
  priority: Number. Message priority 0=High, 1=Normal, 2=Low
  cc: Text. Email address of carbon copy recipients
  bcc: Text. Email address of blind copy recipients
  confD: Number. Confirm Delivery flag.   0=No, 1=Yes
  confR: Number. Confirm Read flag.  0=No, 1=Yes
  Sig: Number. Add signature to message.  0=No, 1=Yes
Example: 

$BA.SendMail "[APPx] Reg Info", "Reg name = \q[NAME]\q\nReg code is [CODE]",  [USEM], [MYEM], 1, [MYCC], [MYBC], 0, 0, 1

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.

Purchasing Information

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$7.50.

Support and Version History

You can always contact me at:

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

Version History

Version 1.13 - Mar-05-2005

Version 1.12 - Feb-18-2005

Version 1.11 - May-14-2004

Version 1.10 - Oct-18-2003

Version 1.09 - Jan-19-2003

Version 1.08 - Dec-14-2002

Version 1.07 - Sep-22-2002

Version 1.06 - Jul-08-2002

Version 1.05 - Jul-05-2002

Version 1.04 - Jul-04-2002

Version 1.03 - Jul-01-2002

Version 1.02 - Jun-24-2002

Version 1.01 - Jun-20-2002 - Initial Release

Version 1.0 - May-2002 - Beta Release

Warranty and User License Agreement

"The Software" is "Built-In Apps Library" aka "PDATBIA.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-2004 Richard R. Sands dba Sands USA
All Rights Reserved
And Finally, ...
Palm OS, Palm Computing, HandFAX, HandSTAMP, HandWEB, Graffiti, HotSync, iMessager, MultiMail, Palm.Net, PalmPak, PalmConnect, PalmGlove, PalmModem, PalmPoint, PalmPrint, and PalmSource are registered trademarks of Palm, Inc.  Palm, the Palm logo, MyPalm, PalmGear, PalmPix, PalmPower, AnyDay, EventClub, HandMAIL, the HotSync logo, PalmGlove, Palm Powered, the Palm trade dress, Smartcode, Simply Palm, WeSync, and Wireless Refresh are trademarks of Palm, Inc.