The VFS Storage Library (VFS)  is a shared library for PDA Toolbox applications and is the successor to the Memory Card Storage Library (McStore).  It provides external database storage actions on either built-in drives or on external memory cards. 

This library provides higher level actions for storing databases on external expansion cards through the Virtual File System (VFS) operating system calls.  As PDA Toolbox always reads and writes data to the internal memory card, there is no way to make it write to the memory card directly.  Following the lead of how the Palm OS™ runs applications from an expansion card, this library copies databases it needs from the card when the application starts and writes them back to the card after the application ends.  This implies that there needs to be enough room on the device internal memory for this library to function correctly.

Care has been take to ensure there is room on the device's internal memory or the card's free space before the databases are copied.  This results in all databases being copied or no databases being copied.  If a database exists both on the internal memory and the card, and you're copying to the internal memory, the user will be prompted to overwrite or leave the database.  This allows restored databases to be brought into the application. 

This manual assumes the reader has familiarity with the PDA Toolbox Professional application.

The VFS Storage Library is a shareware library for the Palm OS® 3.5 and above.  This library requires approx. 15k of internal hand-held memory.  For purchasing information click here.

For PDA Toolbox 6.0 Professional

• The Windows plug-in PDATVFSLib.dll must be copied into the PDA Toolbox folder.
• In the Script Editor, browse for the library from Tools/Options/Libraries dialog.
• Enter your license information when requested, or leave blank to run in trial mode.
• Detailed documentation is included with the Windows plug-in available at www.SandsUSA.com/PDAT.

When distributing, you must include the "PDATVFSLib.prc" file in your installation.  This library must be installed on the device's internal memory.

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.

There are three commands that you use to implement full storage on the device internal memory or expansion cards.  This can safely be used on both devices that support or do not support expansion memory.  If the device does not support it, then these commands are ignored and databases remain in internal memory (of course).

Application Startup Script

Place a GET action to get the databases from the card.  This should list all databases your application uses in a single command so memory storage sizes can be checked.

vfs.Get "MyApp Data", "MyApp Cats"

Application Termination Script

Place a PUT action to put the databases onto the card.  This should list all databases your application uses in a single command so memory storage sizes can be checked.

vfs.Put "MyApp Data", "MyApp Cats"

Configure Button or Menu Item

By default, the application uses internal memory.  The user may choose to store the databases onto the expansion card.  This command allows them to make that choice.

vfs.Dialog 

That's it!

You may want to offer backing up your application's databases to the expansion card.  This is easily accomplished by using the vfs.Backup and vfs.Restore actions.  These actions ignore the User's "Use Expansion Card" setting.

Backup Script

Backing up will copy the databases specified to the expansion card.   Existing 

vfs.Backup "/PALM/MyApp/Backup/MyApp Data", "/PALM/MyApp/Backup/MyApp Cats"

Restore Script

Restoring will copy the databases from the expansion card back to internal memory and start using the databases right away.

vfs.Restore "/PALM/MyApp/Backup/MyApp Data", "/PALM/MyApp/Backup/MyApp Cats"

Again, that's it!

You can test and develop on the emulator with OS 4.0 ROMS by using a program called HOSTFS.PRC available at http://www.palmos.com/dev/tools/emulator (last time I checked).  Note though, that this program is somewhat unrealistic.  For one thing it allows up to 8 expansion cards to be installed.  This library assumes one expansion card with one volume.

Before and during installation of HostFS.prc, be sure to have it's doc handy.  There are some squirrelly things about setting this up.  For one thing, everytime you reset the emulator, it comes up with a warning about not all slots being configured and mounted (unless you have configured and mounted them).

However, once set up, it works pretty good for initial testing.  Final testing should always be done with a real device.

This section pertains to using the Private Eye Library database encryption routines with this library. 

Under normal circumstances, encrypting databases and storing them on an expansion card is a perfectly safe operation. There are guidelines: 

For GET in the Startup Script: 

1. GET your databases from the card 
2. Decrypt the databases 

For PUT in the Termination Script: 

1. Encrypt the databases 
2. PUT your databases on the card 

There are some requirements for backing up or restoring an encrypted database to/from a card: 

Restore: 

1. RESTORE the databases from the card 
2. Decrypt the databases. 

Backup: 

1. Encrypt the databases. 
2. BACKUP the databases to the card 

The important thing to do to make a backup/restore work, is that it must not occur on a primary db form that uses any of the encrypted databases. The problem when you do backup/restore to a primary db form that uses the databases is that between the call to the restore and the call to decrypt, the form is reloaded. Reloading an encrypted database will mostly crash the device. The solution to this is to perform the operation on a non-primary db form. This will prevent the loading of the encrypted databases and allow the script to continue normally.

Each Action in the library will be described here.

Specifying Databases

Most of the actions in this library take one or more database filenames as parameters.  Here are some things to keep in mind:

• Filenames should be double-quoted (e.g. "MyApp Data") as most contain spaces.
• Folder names may be included in the filename, but if omitted, the folder will default to "/PALM/PDAT".
• If a folder name is used, then it must start with the forward slash character ("/").
• Folder names should not have spaces in them although database names may.
• Folder and database names must be limited to 75 characters.

Example filenames:

vfs.Ask TaltID, Text
Description:	A protected OK/Cancel Alert.
Parameters:	TaltID:	A Talt ID or "default"
	Text:	Text to display in the alert.
Example:	vfs.Ask default, "Insert card with MyApp's Data" vfs.Ask 2310, "Insert card with MyApp's Data"

This will display an alert and return OK or Cancel.  If OK is returned, the script will continue.  If Cancel is returned, then the script will cancel.  This is a protected alert which means that if the user changes the memory card, the OS will not automatically end the application and switch to the card folder as it normally does when a card is inserted.

If you want to use the default alert, then specify "default" as the Talt ID.  This will display an alert with your message with a title of "Expansion Card."  If you specify a Talt ID, then this alert must exist in your application with a text message that includes "^1" which will be replaced with the text provided to this action..

This action copies the specified databases to the memory card in the specified folders or "/PALM/PDAT" if not specified.  The difference between this and the .PUT action is that it leaves your databases on the device internal memory.  This allows you to use the databases locally, but to have them backed up as needed.  See vfs.Restore to bring them back.

Deletes one or more databases from the expansion card in the specified folders or "/PALM/PDAT" if not specified.

If the user does not have expansion card capability or an OS less than 3.5, this command is ignored.

By default, the application uses internal memory.  The user may choose to store the databases onto the expansion card.  This command allows them to make that choice.

This tests if ALL the files specified exist on the current preferred storage location.  So, if the user is currently using the LifeDrive's internal drive, then the test would return a whether all the files existed on it.   All three modes, internal RAM, internal Drive, and external Card are supported for testing.

This method returns a branching offset.  Scripting should take that into account:

For example:

Action testIfFilesExist

   vfs.Exist "/MyApp/MyApp-DATA", "/MyApp/MyApp-CATA"
   Goto @Exists   
   Goto @DoesNotExist

@Exists:
   au.alert "The file exists!"
   Goto @Continue

@DoesNotExist:
   au.alert "File does not exist"
   Goto @Continue

@Continue:
EndAction

Copies one or more databases from the expansion card to the device's internal memory.  This action will not copy applications - only databases.    All databases are stored in the specified folders or "/PALM/PDAT" if not specified.

If the user does not have expansion card capability or an OS less than 3.5, this command is ignored.   If there is not enough room for all of the databases specified on the device's internal memory, then this commands is halted and a message is displayed to the user.  The user must make more room before running the application.

This action is best used in the Application Startup Script.

The behavior of this action has been changed with version 1.01: A check is performed initially to check if any of the databases being copied to internal memory exist in internal memory.  If so, the user is prompted one time if they want to overwrite the internal memory databases.  If the user cancels at this point, then the whole action is skipped.  If the user OKs, the as the files are being copied to internal memory, if they do not exist on the memory card, then the operation for that file is skipped without explanation.  The file in internal memory is left intact in that situation.

This provides a method to test what the storage location is.  The mode values are identical to vfs.Use so consult that parameter chart.

This method returns a branching offset.  Scripting should take that into account:

For example:

Action testIfUsingMemory

   vfs.IfUsing vfsMemory
   Goto @Memory   'Yes, Using vfsMemory
   Goto @Other    'No, using vfsDrive or vfsExternal

@Memory:
   au.alert "using internal memory."
   Goto @Continue

@Other:
   au.alert "using card/drive memory."
   Goto @Continue

@Continue:
EndAction

Sets the Put/Get storage location to use internal memory, external memory (an expansion card), or an internal drive (T5 and LifeDrive).  The PDAT Pro Script Editor has mnemonics defined according to this table:

If you pass in vfsDrive to use a T5/LifeDrive internal drive, and the device does not have one, then it is set to vfsExternal. If you can pass in vfsMemory, you are essentially turning off using storage cards.

Copies one or more databases from the device's internal memory to the expansion card.  This action will not copy applications - only databases.    After successful coping of the databases, the databases are removed from the device internal memory.  All databases are stored in the specified folders or "/PALM/PDAT" if not specified.

If the user does not have expansion card capability or an OS less than 3.5, this command is ignored.   If there is not enough room for all of the databases specified on the expansion card, then an message is displayed, the databases are left on the device memory, and a vfs.Off is performed.

This action is best used in the Application Termination Script.

Provides a method to check if the internal drive or external card is ready for use.  Ready means that the card is present and mounted.  If you pass in a value of Zero (0) or vfsMemory, it will always branch to the true section.  The mode values are identical to vfs.Use so consult that parameter chart.

This method returns a branching offset.  Scripting should take that into account:

For example:

Action testIfReady

   vfs.IfUsing vfsExternal
   Goto @Yes
   Goto @No

@Yes:
   au.alert "External card is ready for use."
   Goto @Continue

@No:
   au.alert "Please insert a card!"
   Goto @Continue

@Continue:
EndAction

This action copies the specified databases from the memory card from the specified folders or "/PALM/PDAT" if not specified, to the internal memory.  The databases remain on the memory card.  This allows you to use the databases locally, but to have them backed up as needed.  If the database(s) being restored are used by the current form, the databases become active immediately.  See vfs.Backup to back them up initially.

The behavior of this action has been changed with version 1.01: A check is performed initially to check if any of the databases being copied to internal memory exist in internal memory.  If so, the user is prompted one time if they want to overwrite the internal memory databases.  If the user cancels at this point, then the whole action is skipped.  If the user OKs, the as the files are being copied to internal memory, if they do not exist on the memory card, then the operation for that file is skipped without explanation.  The file in internal memory is left intact in that situation.

This action will removes one or more folders from the expansion card.  The folders must be empty of files and subfolders and must be tips only:  Given the path "/MyApp/Data", you could not remove the folder "/MyApp" because a subfolder is present.  Each tip must be deleted in order: vfs.RmDir "/MyApp/Data", "/MyApp".  All paths must start with the "/" as there is no default path.

Set the status message to show while expansion card operations take place.

The operations this apply to are: DELETE, GET, PUT.

This will read the text file specified in filename into the field ID specified.  The filename must start with a "/" character and include the full path, filename, and extension.  Text files are limited to 32700 bytes since that is the limit of a PDA Toolbox record.  

The database record that this data is being read into must exist (not be new).

This will read the text file specified in filename into a list of specified field IDs.  The filename must start with a "/" character and include the full path, filename, and extension.  Text files are limited to 32700 bytes since that is the limit of a PDA Toolbox record.  

Each physical line of data corresponds to the n'th field ID specified.  Each line of data must be terminated with a carriage-return/line-feed (ascii 13, 10 or \r\n).  Blank lines are treated as an empty value and is assigned to the field as such.  The database record that this data is being read into must exist (not be new).

In the above example, the data.txt might look like:

Sands
Rick
101 Binary Ave.
Denver
Co.
80123
1234

This will write string to the text file overwriting the text file if it exists.  The filename must start with a "/" character and include the full path, filename, and extension. If the folders do not exist, they will be created. Text files are limited to 32700 bytes since that is the limit of a PDA Toolbox record. 

The record that this data is being written from must exist (not be new).

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

 The cost of this package is US$12.95 and can be purchased at eSellerate or at www.SandsUSA.com/PDAT.  Upgrade pricing from the Memory Card Storage Library is available only through the www.SandsUSA.com/PDAT site.  You must supply your Memory Card Storage Library license code to qualify.

Primary support for this library is at the PDAT Nuts & Bolts Support Forum at www.PDATNutsAndBolts.com.

You can always contact me at:  email: Rick@SandsUSA.com or at my site http://www.SandsUSA.com.

"The Software" is "VFS Storage Library" aka "PDATVFSLib.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 "PDATVFSLib.prc"  but 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 as many computers as you own for your own development use. 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
VFS Storage Library 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
Database Extreme Documentation Copyright (C) 2002-2003 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.