The PDAT/Advanced Utility Library (AU) is a shared library for PDA Toolbox applications.  It provides a set of miscellaneous routines that may not require a separate library.  

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 PDAT/Advanced Utility Library is a Freeware Library for the Palm OS™ 3.1 and up.  It requires approx. 18k of hand-held memory. 

The Actions provided by this library are divided into several categories of functionality:

For PDA Toolbox 6.0 Professional

• The Windows plug-in PDATUtilLib.dll must be copied into the PDA Toolbox folder.
• In the Script Editor, browse for the library from Tools/Options/Libraries dialog.
• Detailed documentation is included with the Windows plug-in available at www.SandsUSA.com/PDAT.

For PDAT/Advanced Only

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 "PDATAdvUtilsLib.prc" file onto your development handheld or emulator.  This device 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 "Advanced Utility Library" is not shown in the list, tap the "Add" button.
4. In the "Add Library" dialog, enter in the Library ID of "paUL" (without the quotes).
5. 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 file "PDATAdvUtilsLib.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:

Shows an information alert. If a record is available you can use the [FLDX] syntax as in the Built-In Library (see Text above).  You may pass "" if you do not require text to be inserted into the alert.

Shows an information alert using an Alert Resource from your application. If a record is available you can use the [FLDX] syntax as in the Built-In Library.  

For au.Alert.Custom, this will handle one or two buttons. If the first button is tapped, then the action continues with the script.  If the second button is tapped, then the script is aborted.  When using au.Alert.CustomEx, when it returns, it will branch to the n^th line after the au.Alert.CustomEX: The first button tapped goes to the following line, the second button tapped goes to the 2^nd line following, the third goes to the third line, etc.  The following example displays a custom alert with three buttons:

Action btnTest
   au.Alert.CustomEx TestAlert, "3 Button Test"
   Goto +3
   Goto +4
   Goto +5
   au.Alert.Custom ResultAlert, "You tapped OK"
   Goto +2 
   au.ALert.Custom ResultAlert, "You tapped Maybe"
   Goto +2
   au.ALert.Custom ResultAlert, "You tapped Cancel"
EndAction

To properly create the alert so that it accepts the text passed to it, you must include in the text the placeholder "^1" as in "Do you want to ^1" where the ^1 is replaced with the text in the au.AlertCustom action.

You may pass "" if you do not require text to be inserted into the alert.

Beams an application or a database to another device.  You must specify the database without the ".prc" or ".pdb" as they do not actually exist on the device.  Embedded text codes in both the filename and description are allowed and if a record is available you can use the [FLDX] syntax.

This action beams the contents of a record formatted for MemoPad via the IR port.  This is useful if you want to be able to send data without sending the application or doing a multi-step Export to MemoPad, switch to MemoPad and beam.  You can send the record using the string formatting typically used in this library. E.g. "Name: [NAME]" where [NAME] is a field from the record. 

Copies text to the clipboard.  If the clipboard current has something, it is replaced with the text.

Deletes all databases in the list without confirmation.  Embedded text codes in the filename are allowed and if a record is available you can use the [FLDX] syntax.  No error is returned by this action so execution continues at the next statement.

For au.Exists, this action verifies that the listed files exist on the handheld and (optionally) displays a message if not.  In addition, you can tell it you want it to QUIT or CONTINUE after a file has been determined to be missing.  The app will terminate if you choose QUIT.  Regardless of what the Quit/Continue state is, if there are missing files, the script lines following are not executed. 

Custom Alerts (Talt) must have a message with one parameter in it: 

^1 - The name of the field that failed validation.
E.g. "^1 is required but missing."

For au.ExistsEx, this action will perform the same duties as au.Exists, however, it supports branching rather than the Talt/Quit type parameters.  If all the files exists, then it goes to the next action.  If any of the files do not exist, then it skips the next action and proceeds to the second following the au.ExistsEx action:

Action btnTest
   au.ExistsEx "TestApp", "SomeLib", "Contacts-PAdd"
   Goto +2
   Goto +3
   au.Alert.Custom ResultAlert, "All files present!"
   Goto +2 
   au.ALert.Custom ResultAlert, "Some files are missing!"
EndAction

 These actions support a form "stack," which allows you to easily create common forms that are called from different forms in your application.   The au.FormReset action clears the current form stack to no entries.  I recommend that this action go into your startup script.  It can also be used to clear the stack and jump to a know location.

The au.FormAnchor and au.FormBack actions work together and allow you to "save" the current form and call one or more other forms, and then navigate back through the path the user followed.  To save the current form "location", you invoke the au.FormAnchor action and then either $GotoForm or $GotoFormNew to the target form.   The form that you went to can call au.FormAnchor again and go to another form, or it can call au.FormBack to return.

The stack is set to 8 forms.  If you go over that, additional entries will be silently ignored.  If you try to au.FormBack more times than you have called au.FormAnchor, then the action will be ignored and the script will exit.

In the case where an alarm triggers a form to be open directly instead of being opened through the normal sequence, the form stack may be empty and a au.FormBack would just sit there and "flash" at you (do nothing).  To gracefully handle this, if you have a form with alarm fields on it, you should supply a "default form id" that will direct the user to the best page.  This would look something like: "au.FormBack 1100" where form 1100 is used instead of the "form stack" IF the form stack is empty.

NOTE: You don't want to have a au.FormAnchor and then jump to the same form.  This will fill the stack and the au.FormReset will have to be called.

See the "FormRtn" sample available at www.SandsUSA.com/PDATAdv to look at the code "behind" the buttons.

Plays a 'wave' resource within your application.  This is useful for short sound-bites.  Maximum wave file that can be use is 64k in size but this would be a stretch.

Currently, only WAVE data is recognized; in this case, the wave resource must start with the “RIFF” ID (byte 0 in a simple .wav file).

Supported WAVE Format

• Uncompressed (PCM) or IMA 4-bit adaptive differential (IMA ADPCM). The ADPCM type is also known as DVI ADPCM; in a WAVE file, it’s known as format 0x11. 

• One or two-channels

• All normal sampling rates (8k, 11k, 22.05k, 44.1k, 48, 96k).

You can’t interrupt or abort a resource playback once it’s been initiated. The resource always play to the end of the data.

Creating a Wave File.

With PDA Toolbox 6.0, you can merely rename a wave file (*.wav) to a filename that consists of the word "wave" followed by a four digit hex value representing the ID with a file type (extension) of ".bin".  If this file is placed into your codeset\bin folder, then it will be included into your application when it's compiled.  For example, a "testing.wav" could be merged into a 'wave' resource of 1000 by renaming it to "wave03e8.bin" where the 03e8 is hex for 1000 decimal.  Your script would then play it by au.PlayWave 1000.

This is only available on devices that have the "Sound Stream Feature Set" present.  Basically, this means OS 5.0 devices.

Transfers execution to another application (ie. runs a program and returns to the launcher).   Don't look for a au.CALL command as it won't work with PDAT/Advanced Libraries.  This is the only command that will be available.

If the program you want to run has spaces, you must include double-quotes around the name.

NOTE: It is best to test this command outside of the PDAT/Advanced environment.

This command sorts the database by the keys specified.  Up to four key pairs are allowed.  Each pair must consist of a Field ID and a Sort Direction.  

The sort directions are defined as follows:

Custom Alerts (Talt) must have a message with two parameters in it: 

^1 - Filename of the database being sorted
^2 - Status

E.g. "The ^1 sort ^2."

Exports specific fields to the Memo Pad or DOC reader application.  For memos, if your database size is larger than 4k (4096) characters, then the export function will slop over into multiple memos.  Multiple memos are created at the first record, then the second record, third, etc.  There is no title or other indication that the memo has continued into the next memo record.  For DOC format, the filename will automatically be created by prepending "doc_" to the name of the database.  You may not export multiple tables at this time.

NOTE: If the Memo Pad application has never been used, the first export may fail. Following exports will be successful.

The Memo Pad export is memory intensive in order to support creating multiple memos when exporting a lot of data.  The export is always broken into a new memo on an even record boundary.  So when the action starts, it attempts to allocate an internal memory buffer of 4096 characters to hold a single record.  If this fails, it tries 2048 characters, then 1024, then 512 characters to hold a single record.  If it cannot create a buffer of at least 512 characters then the action fails with an error message.

Custom Alerts (Talt) must have a message with two parameters in it: 

^1 - Filename of the database being sorted
^2 - Status

E.g. "The ^1 exported ^2."

These export routines will ignore all "deleted" or "archived" records.

Deletes (purges) all records that are OLDER than (Today-Days).  The Days parameter must be a literal value (e.g. 7 or 30) and may not be a field id.

Custom Alerts (Talt) must have a message with two parameters in it: 

^1 - Number of records removed or the word "No"
^2 - Database name

E.g. "^1 record(s) removed from  ^2."

Deletes (purges) all records that are selected.  Selection is done by having a field in your database that is a type Checkbox that has a checked value.

Custom Alerts (Talt) must have a message with two parameters in it: 

^1 - Number of records removed or the word "No"
^2 - Database name

E.g. "^1 record(s) removed from  ^2."

This will change the Creator ID, Type ID, or Filename of the database specified with CID/TID.  This action is primarily intended for converting an old database to a new format (ie. an upgrade utility).   Embedded text codes in the filename are allowed and if a record is available you can use the [FLDX] syntax.

No error is returned by this action as you may want to change several.  Use another method to determine if the database(s) has been successfully processed.

This will rename one or more field IDs.  Always include pairs of (oldField, newField).  This action is primarily intended for converting an old database to a new format (ie. an upgrade utility).

No error is returned by this action as you may want to call this several times.

This action takes a list of CreatorIDs and TypeIDs and attempts to mark databases as "dirty" so they will be backed up.  Normally this is not needed, but if you have a situation of multiple desktop applications, it may be desirable to do this.

This command opens up each database if possible, reads a record, and marks the record as having been edited.

SetText will assign a text field the contents of Text. Text may be in the same form as the Alerts (e.g. "[LNAM], [FNAM]" is valid. This, in effect, can perform field concatenation.

This will validate required fields. The first field that does not exist, or if text, is empty, will display the talt and quit executing the current actions.  Validation continues through the list of fld/name pairs until one fails or they all pass.

If the current record does not exist or is empty or the field is missing or blank, then the field is considered to be missing and the alert will display.

Custom Alerts (Talt) must have a message with one parameter in it: 

^1 - The name of the field that failed validation.
E.g. "^1 is required."

Assigns the HotSyncID to a fld.  This is useful if you have an application where records are beamed or merged with other databases and you want to keep tracked of where the original record came from.

Sends a soft or hard key value to the system based on a numeric value.  Most of the common keys are the same across devices and OS's, but some of the special buttons found on different devices may be unique (e.g. Sony Jog Buttons).

The value parameter above may be one of these values:

This library is freeware.   As freeware, I may not always be able to support this product in timely manner.  Your best bet for support is at the PDAT Nuts & Bolts user forum.  However, you can always contact me at:

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

"The Software" is "PDAT/Advanced Utility Library" aka "PDATAdvUtilsLib.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 enhancing the applications created with PDA Toolbox(tm) Application Generator.  This is a Freeware product, however, use of this product implicitly becomes a "licensed product" and is in it's entirety protected by US and foreign copyright.

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 "PDATAdvUtilsLib.prc". 

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, ShellReg, ShellMaker, DeskReg, and MyName is Copyrighed by Richard R. Sands dba Sands USA

PDAT Toolbox is Copyrighted by Paul Prejean

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-2006 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.