File Library for PDA Toolbox

version 1.0.1

© 2005 by Richard J. Watters

This library was designed to add the ability to open and save multiple databases with any PDAT application. Along with these functions, the library can also import and export between a text field and a Palm DOC. This is a plug-in library for use with PDAT/Adv and PDAT Professional. The functions included in the library are:

File.New
File.Open
File.Open.Doc
File.Save
File.Save.Doc
File.SaveAs
File.Delete
File.Prompt
File.Properties
File.Reset

The library is provided as-is with no statement of usability or suitability for a specific task. With that said, extensive time and testing has gone in to the library with available simulators and actual hardware. The library is provided as freeware for all to use and distribute. If you enjoy the library and would like to sponsor future updates, you may make a donation to sales@watters-edge.com via PayPal.

If you have any questions or requests regarding the library, you can email me at support@watters-edge.com.

Installing the Library

PDAT/Advanced

Install "PDATFileLib.prc" onto your development handheld or PalmOS Emulator. This should also have a copy of PDAT/Advanced. Run PDAT/Adv; from the main form, tap the menu bar and choose "Advanced | Manage Libraries." Tap "Add" and enter the library ID of "FILe". Tap "Done" and start programming.

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 File Library. This is available in the archive file that you downloaded from www.watters-edge.com/PDAT. Extract "PDATFileLib.dll" to your PDA Toolbox Folder. Register the dll on your computer.

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.

Library Overview

The File Library now expands your application to be able to open and save multiple databases. The database name associated with your application's Form is now considered to be the temporary database. All saved databases will be created by duplicating the temporary database using the same creator ID and the type ID of "$SAV". The File Library will keep track of the last database opened or saved by using a Palm Preference associated with your application. Therefore, a user can open a database with your application, make changes, and close the application. Then, the next time your application is run, the user can tap a Save button, for example, and your program will "remember" where to save the database.

The library also expands the reach of your application to the external memory card. Now, a user can open and save databases anywhere accessible by their Palm handheld. In addition, this library can import and export Palm Doc files or standard text files.

Library Action Details

File.New fieldID: fieldID is the 4-character name of the field where the default name of the current database is stored. This field is for your use; if you do not choose to use it, you may pass "null" to this action. File.New will first prompt the user to save the current database before creating a new blank temporary database. The properties of the temporary database (name, creator ID, and type ID) are set by the calling application, which is why this action can only be called from a form that has an active database. If the user taps "Cancel" during the Save prompt, this action is canceled and any remaining actions in your PDAT script will not be done.

File.Open fieldID: The user will first be prompted to Save the current database. If the "Cancel" button is tapped, this action is stopped, and any remaining actions in your script will not be evaluated. fieldID is the 4-character name of the field where the name of the saved database will be placed. This field is for your benefit and use, but it is not required for the File Library to function, so you can pass "null" to ignore this field. The file name stored in this field, though, may be useful to you if you have a Desktop program that can synchronize with your Palm program. This will provide your desktop application with the saved name of the open database. Note, each record in the opened database will receive the file name in the field you identify with fieldID.; The action then continues by presenting the user with a graphical interface to select a database to open. The user can select from internal memory or an external storage card. The file list of internal memory is filtered by the creator ID of the calling application to help minimize errors caused by users attempting to open databases that are not compatible with your application. Also, if the user selects a file from the external card, the library will first check for the ".pdb" extension, then it will check the creator ID of the external database before allowing the action to continue.; The Open command will then duplicate the database selected and format it based on your applications requirements, as determined from the form that called this action. So, this action requires that it be called from a primary database form.

File.Open.Doc fieldID: fieldID is the 4-character field in your database where you want to place the text of a document. This action will accomplish two potential tasks - it can open an uncompressed Palm Doc stored in internal RAM, or it can import the text of a Text file saved on an external card.; First, the file list of the RAM databases is filtered to only show Palm Docs. If one of these is selected, the document text will be read into the indicated field of the current database record. If the document is larger than 32kB, then only the first 32kB of the file will be read, and the user will be prompted to let them know the document is being truncated.; Second, if the user selects a file from an external memory card, then the library will assume that it is a text file. The file will be read as above into the noted field of the current database record. Again, if the file text is larger than 32kB, it will be truncated and the user will be notified.

File.Save fieldID: If a database has been opened by the File.Open library call, then the changes made will be saved to the same database that was opened - weather it was in internal memory or on an external card. If the database was opened from an external card, then that card was removed prior to this action, then the File.Save function will save the database on internal memory using the same name.; If the database has not been saved before, then the File.SaveAs action will be called automatically. Then the default name presented to the user for the SaveAs function will be pulled from the open database in the field identified in the parameter, fieldID.

File.Save.Doc fieldID: As with File.Open.Doc, this action can save text to an internal Palm Doc, or to a rich-text file saved on an external memory card. The text is read from the current database record and the field identified by parameter, fieldID. The user will be presented with a graphical interface to select where the file should be placed.


File.SaveAs fieldID: The user will be presented with a graphical interface to select where they want to save the current database - internal or external memory. The current database will be copied to the location indicated, with the name entered by the user. If you would like to suggest a default name, it should be stored in the field parameter, fieldID. After the database is saved, this field will be replaced with the actual name used to save the database.

File.Delete

The user will be presented with a graphical interface to select a file to delete. The user can browse internal databases (filtered by the creator ID of the calling application) or files stored on the external card.

File.Reset: This action will reset the information associated with your application for the File Library, such as the last file opened or saved.

File.Prompt filename, Yes|No: Prompt the user to save the current database. This action does not need to be called from the primary database form, so the filename of the temporary database being used by your application should be identified as the parameter, filename. If the database can not be found, the user can be prompted with an error message, though this will typically only mean that the user has not added any records to the database yet. To show the error prompt, enter "Yes" for the second parameter.; This action can be called in your termination script, since it does not need a form to be open, though it might be annoying to your user to consistently be prompted to save their data.

File.Properties: Show the current properties of the saved database associated with the current temporary database. The properties that will be shown to the user are the temporary database name, the saved path, and the date and time the database was last saved. If the database has not been currently opened or saved, then the last two parameters will be shown as "unknown" and "never", respectively.