VFS - Interface
Programer's Guide
Author: Ulrich Riepert 
1. Introduction
2. How it works
3. Check if the PDA is supporting cards
4. Copy and Move files from memory to card
5. Copy and Move files from card to memory
6. List of files in direcory on card
7. List of files in memory
8. Short description of demo program VFS
9. Reference VFS-Interface
10. Copyright

 

1. Introduction

VFS means Virtual File System and is part of Palm OS, first introduced in version V4.0.

This part of Palm OS is called VFS-Manager and provides functions that gives access to memory cards, used for example by the Palm M125/M130 or the M5 series.

This interface provides a subset of this functions for CASL and has the following functions:

  • Checks, if the Palm has a card slot and the VFS-Manager is installed.

  • Detects the number of available cards.

  • Checks, if a card is inserted in the card slot.

  • Creates a new directory on card.

  • Checks, if a file or directory exists on card.

  • Checks the number of files in a directroy on card.

  • Retrieves the names of all files in a directory on card.

  • Copies or moves a file from memory to card.

  • Copies or moves a file from card to memory.

  • Deletes a file or an empty directory from card.

  • Information about the card: volume name, size of card (free, used, total)

  • Retrieves the size of a file

The functions

  • Delets a file in memory

  • Checks, if a file exists in memory

are core functions of CASL and not part of the interface.

With this functions, CASL can create a file in memory, archieve the file on card, move it back to memory for read and write operations and afterwards move it to card again..

Also possible:

  • Programming of an own backup program that can backup all files in memory, even non-CASL files.

  • Programming of a file manager.

top

2. How it works

CASLPro has the possibility to integrate C functions. This is used by the interface and therefore it is not possible, to run the interface with the normal CASLrt.

The result of a C function was limited in this interface on type "numeric" or "string". The more difficult handling of vector results was left to hold the interface simple. Therefore for example, the names of all files in a directory were returned from a C function as a string with separators.

The VFS-Manager is part of the Palm OS V4.0 and so you need the Palm SDK V4.0 installed on your computer:

IMPORTANT
For use of this function the Palm SDK 4.0 must be installed on your windows system! 

You have to do the following steps:
1. Download skd40.zip from the palm pages
2. Run "PALM OS SDK 4.0.exe".
3. Rename the existing c:\palmdev\sdk directory to sdk-old
4. Rename the c:\palmdev\sdk-4 directory to c:\palmdev\sdk

top

3. Checking if the PDA is supporting cards

Following steps are neccessary
(the corrresponding function of the interface is bold printed in parenthesis)

  • Check, if the PDA has a card slot and the VFS-Manager is installed (vfs_IsVFSInstalled).
    This check has to done once in the startup function. The result could be stored in a globa variable.
  • Get the available cards on this device (vfs_GetInstalledCards, used by ReadAvailableCardNo)
  • Select one card (for example in global variable MyCardNr)
  • Check, if a card in inserted in card slot (vfs_GetCardRefNum).
    Currently, the interface supports the first card slot of a PDA only. This is no restriction for current Palm devices, cause they have only one slot.
    This check has to be done before each acces to the card, cause the user may have removed it.

top

4. Copy and Move files from memory to card

Following steps are neccessary
(the corrresponding function of the interface is bold printed in parenthesis)

  • Define the file that has to be copied / moved to card.
  • Define the directory path on card, in which the file has to copyied / moved.
    Remark: a path is build with slashes ("/") , for example. "/PALM/CASL/", case is ignored.
  • Check, if the directory already exists on card (vfs_DirExistsOnCard).
  • If not, you have to create it (vfs_CreateDirOnCard).
  • Check, if the file already exists in the card directory (vfs_FileExistsOnCard).
  • If so, you have to delete the file in the card directory, otherwise the copy function will abort with an error message (vfs_DeleteOnCard).
  • Call the copy function (vfs_CopyFileToCard)
  • If you want to move the file: delete the original file in memory (CASL-Funktion delete)

top

5. Copy and Move files from card to memory

Following steps are neccessary
(the corrresponding function of the interface is bold printed in parenthesis)

  • Define the file that has to be copied / moved to memory and its directory,
  • Check, if the file already exists in memory (CASL-Funktion Exits).
  • If so, you have to delete the file in memory, otherwise the copy function will abort with an error message (CASL Funktion delete).
  • Call the copy function (vfs_CopyFileFromCard)
  • If you want to move the file: delete the original file in the directory of the card (vfs_DeleteOnCard)
  • After moving the last file you might delete the empty directory on card (vfs_DeleteOnCard)

top

6. List of files in directory on card

Following steps are neccessary
(the corrresponding function of the interface is bold printed in parenthesis)

  • Define the directory path that contains the files.
  • Get the number of files in the directory (vfs_NumFilesOnCard)
  • Get a string with the names of the files (vfs_GetFilesOnCard).
    The name are separated with a special separator character that is given to the vfs_GetFilesOnCard function as a parameter. Choice a character as seprator, that could not be a part of a file name like "?"
  • Break the string in its components and store these in a string array or in a CASL database.
  • Those data could be showed on display for user selection or to copy / move all files of a directory.

top

7.  List of files in memory

Following steps are neccessary:

Only CASL functions required

  • Use a file selector object.
  • Call the put function with the name of the file. Wildcards are added automatically, so the use of put filesel "VFSDemo" will show all files which have "VFSDemo" as part of their names.

top

8. Short description of demo program VFS

In the demo program you can see the most important functions in practice.

The program creates 5 files VFSDemo_01 ... VFSDemo_05 in memeory, that will be displayed in a file selector (left on screen "Files im RAM"). 

In a text field "Directory on Card" can be typed in the name of a directory on card. (default  "/palm/CASL/").

The left button "Move to Card" moves the selected file from "Files in RAM"  to the given directory  "Directory on Card". If the directory does not exist, it will be created..

After moving the file is shown in the right selector "Files on Card". This is a normal CASL selector, that was enabled with the interface function to have the same behaviour as a fileselector for a card.

With the button "Move from Card" you can move the file back to memory.

You can edit the path in text field "Directroy on Card". Push the button "Refresh Card Dir", to show the files in the direkctory. If you type in "/", the root directory of the card with all files and subdirectories are displayed.

The button "Availables Cards" brings up a messagebox with the cards numbers avaliable on this device.

For testing a file manager is necessary  to check the actions of VFS. I  recommend the freeware programm  Filez (http://www.nosleep.net/software.asp).

top

9. Reference VFS Interface

# Virtual File System C function V1.1 (for CASLPro 3.2/3.3)
# 
# Sept 2002 by Ulrich Riepert (http://www.ulrich-riepert.de)
# 
# Enables CASL to copy a file from RAM to card and vice versa
# 
# 
# 
# 
# 

 external "CASL_VFS";
 #
-----------------------------------------------------------------------------------------------
 # checks, if the device has a card slot
 function vfs_IsVFSInstalled() as numeric;
 # return true or false 
#
-----------------------------------------------------------------------------------------------
 # enumerate the card ref numbers available
 function vfs_GetInstalledCards as string;
# returns a comma separated string

-----------------------------------------------------------------------------------------------
 # checks, if a card is inserted
 function vfs_GetCardRefNum (numeric CardNum) as numeric;
 # CardNum: 1 = first card
# 2 = second card
# Remark:
# CardNum is ignored in this version (allways set to 1 = first card)
#
# Returns > 0: Card Reference Number that identifies the card für I/O operation
# < 0: No Card available
#
# The Card Reference Number is a input parameter to other vfs functions

-----------------------------------------------------------------------------------------------
 # copies a file from RAM to card
 function vfs_CopyFileToCard(string RAMDbName, numeric CardRefNum, string CardPath) as numeric;
 # CardPath = path AND name of the file on card eg. "/PALM/Launcher/db1"
# Returns =0 = no error
# >0 = Error Code (see below)

-----------------------------------------------------------------------------------------------
 # copies a file from card to RAM
 function vfs_CopyFileFromCard(numeric CardRefNum, string CardPath) as numeric;
 # CardFile = path and name of the file on card eg. "/PALM/Launcher/db1"
# Returns =0 = no error
# >0 = Error Code (see below)

-----------------------------------------------------------------------------------------------
 # deletes a file or an empty directory on card
 function vfs_DeleteOnCard (numeric CardRefNum, string CardFile) as numeric;
 # CardFile = path and name of the file on card eg. "/PALM/Launcher/db1"
# returns =0 = no error
# >0 = Error Code (see below)

-----------------------------------------------------------------------------------------------
 # checks, if a file exists on card
 function vfs_FileExistsOnCard (numeric CardRefNum, string CardFile) as numeric;
 # returns true = file does exist 
# false = file does not exist 

-----------------------------------------------------------------------------------------------
 # checks, if a directory exists on card 
 function vfs_DirExistsOnCard (numeric CardRefNum, string CardPath) as numeric;
 # returns true = dir does exist 
# false = dir does not exist 

-----------------------------------------------------------------------------------------------
 # creates a new directory on card 
 function vfs_CreateDirOnCard (numeric CardRefNum, string CardPath) as numeric;
 # returns =0 = no error
# >0 = Error Code (see below)

-----------------------------------------------------------------------------------------------
 # retrieves the number of files in a directory
 function vfs_NumFilesOnCard (numeric CardRefNum, string CardPath) as numeric;
 # returns >=0 number of files
# <0: Error 

-----------------------------------------------------------------------------------------------
 # retrieves a list of existing files in a directory
 function vfs_GetFilesOnCard (numeric CardRefNum, string CardPath, string Sep, numeric MaxEntries) as string;
# returns a sting like "db1?db2?db3", where ? is the separator Sep
# returns empty string, if an error occurs

-----------------------------------------------------------------------------------------------
 # retrieves size of the card
 function vfs_GetCardSize (numeric CardRefNum, string Mode) as numeric;
# Mode = "free", "used", "total"
# returns >= 0: Size in Bytes
# <= 0: Errror

-----------------------------------------------------------------------------------------------
 # retrieves name of the card
 function vfs_GetCardName (numeric CardRefNum) as string;
# returns name of card 
# or empty string, if an error occurs
# 

-----------------------------------------------------------------------------------------------
 # retrieves size of file
 function vfs_GetFileSize (numeric CardRefNum, string CardPath) as numeric;
# returns >= 0: Size in Bytes
# <= 0: Errror

 end_external;
#------------------------------------------------------------------------------
variables;
   numeric MaxCountCardNo = 4;
  numeric LogCardNo[MaxCountCardNo];
  numeric CountCardNo;
end;
#------------------------------------------------------------------------------
function ReadAvailableCardNo;
 # Input: none
# Output: - available CardNo for this device --> LogCardNo[0], ...LogCardNo[3];
# - number of available cards --> CountCardNo
  variables;
    string tstr;
    numeric Pos;
    numeric ScanDone;
    numeric i;
    numeric k;
    string sep = ",";
  end;

  tstr = vfs_GetInstalledCards;
  # scanning for separator
  ScanDone = false;
  i = 0;
  while not ScanDone;
    Pos = find(",",tstr,0);
    if Pos < 0;
      ScanDone = true;
    else;
      LogCardNo[i] = value(left(tstr,Pos));
      Pos = length(tstr)-Pos-1;
      if Pos > 0;
        tstr = right(tstr,Pos);
      else;
        ScanDone = true;
      end_if; 
      i=i+1;
      if i >= MaxCountCardNo;
        ScanDone = true;
      end_if;
    end_if;
  end_while;
  CountCardNo = i;
end;

-----------------------------------------------------------------------------------------------
# Error codes of the vfs manager
# ------------------------------
# If you want to make a error handlng in CASL, you could remove the # and use the 
# variables to generate error messages:
#
# variables
# numeric ErrBufferOverflow = 10753; # passed in buffer is too small
# numeric ErrFileGeneric = 10754; # Generic file error.
# numeric ErrFileBadRef = 10755; # the fileref is invalid (has been closed, or was not obtained from VFSFileOpen())
# numeric ErrFileStillOpen = 10756; # returned from FSFileDelete if the file is still open
# numeric ErrFilePermissionDenied = 10757; # The file is read only
# numeric ErrFileAlreadyExists = 10758; # a file of this name exists already in this location
# numeric ErrFileEOF = 10759; # file pointer is at end of file
# numeric ErrFileNotFound = 10760; # file was not found at the path specified
# numeric ErrVolumeBadRef = 10761; # the volume refnum is invalid.
# numeric ErrVolumeStillMounted = 10762; # returned from FSVolumeFormat if the volume is still mounted
# numeric ErrNoFileSystem = 10763; # no installed filesystem supports this operation
# numeric ErrBadData = 10764; # operation could not be completed because of invalid data (i.e., import DB from .PRC file)
# numeric ErrDirNotEmpty = 10765; # can't delete a non-empty directory
# numeric ErrBadName = 10766; # invalid filename, or path, or volume label or something...
# numeric ErrVolumeFull = 10767; # not enough space left on volume
# numeric ErrUnimplemented = 10768; # this call is not implemented
# numeric ErrNotADirectory = 10769; # This operation requires a directory
# numeric ErrIsADirectory = 10770; # This operation requires a regular file, not a directory
# numeric ErrDirectoryNotFound = 10771; # Returned from VFSFileCreate when the path leading up to the new file does not exist
# numeric ErrNameShortened = 10772; # A volume name or filename was automatically shortened to conform to filesystem spec
# end;

top

10. Copyright

 

Copyright 2002-2005 by Ulrich Riepert 

Homepage: Uli's Palmpages (www.ulrich-riepert.de) 

EMail: ulrich@riepert-online.de

Palm, CASL are registered trademarks.

top 

 

 

 

 

 

 

 

 

  © 2005 Ulrich Riepert / Authorized for posting at CASLSoft.com