File system utilities (OMVFS legacy)

The omvfs library is a collection of OmniMark external functions for file and directory access and manipulation.

The omvfs library provides a unified interface for easy, efficient, and portable access to files and directories regardless of the location of the file or directory, or the protocol used to access the file.

The omvfs functions and opaque data types:

omvfs functions allow you to:

connect to and disconnect from a directory (vfsConnect, vfsConnectDir, vfsDisconnect)
open and close files vfsOpen, vfsClose)
manipulate files and directories (vfsChangeDir, vfsMakeDir, vfsDeleteDir, vfsDeleteFile, vfsCopy, vfsMove)
access information on a directory (vfsList, vfsDescribe, vfsDirName)
access information on a file (vfsFileName, vfsFileDir, vfsDescribeFile, vfsRead, vfsCursorPosition)
modify the contents of a file (vfsWrite, vfsTruncate)
move the cursor position in a file (vfsMoveCursor)
lock or unlock a file or a portion of a file (vfsLock, vfsUnlock)
link to a file or directory (vfsLink) (Note: UNIX systems only)
change file or directory attributes (vfsChangePermissions, vfsChangeOwner)
determine the library version information(vfsLibraryVersion), vfsIsVersionCompatible

All paths in omvfs operations are system independent and use the "/" UNIX-style separator. Windows style paths are supported when running under Windows.

The functions in this library use the following opaque data types:

vfsDir - used by functions performing actions in a directory other than the current working directory.
vfsFile - used by functions performing actions on a file.

Requirements

The omvfs external function library requires OmniMark 6.0 or later.

You must include the following line at the beginning of any OmniMark program using the omvfs library functions:

  include "omvfs.xin"

Usage Notes

General OS operation failure exceptions will return external exception VFS300. The accompanying text will contain details on the reason for the exception.

For complete details on absolute URLs and valid encoding, see Internet Standards RFC 1738: Uniform Resource Locators.

For complete details on relative URLs, see Internet Standards RFC 1808: Relative Uniform Resource Locators.

Example

Here is a sample program that will list all files in /temp/ which have been modified more recently than 8 am October 31st EST, 2000.

  include "omvfs.xin"
  include "omdate.xin"
  
  process
     local stream listing variable
     local vfsDir list-dir
  
     set list-dir to vfsConnect "file:///temp/"
  
     vfsList on list-dir into listing include VFS-FILES
  
     repeat over listing
        local stream attrs variable
        vfsDescribe listing on list-dir into attrs
        output listing || '%n' when ymdhms-second-difference ( attrs{"mtime"},
           "20001131080000-0500" ) > 0
     again

omvfs Generated Exceptions

This is a complete list of the VFS library external exceptions that may be thrown back to the calling OmniMark program. These are all catchable using the #external-exception label.

  VFS000 	Memory could not be allocated
  VFS001 	The requested function is not supported for the type of connection
  VFS002 	The requested function is only available on UNIX platforms
  VFS003 	vfsDir objects cannot be created for local paths
  VFS004 	The specified path name exceeds system length limits
  VFS100 	The vfsDir object must be connected before it can be used
  VFS101 	The connection location must be specified as an absolute or relative path
  VFS103 	An invalid host name was specified
  VFS104 	An invalid TCP/IP port number was specified
  VFS105 	The specified path is not a valid absolute or relative path
  VFS109 	An invalid value was specified for the content type include indicator
  VFS110 	The filename must not contain path information
  VFS111 	The specified URL contains invalid encoding
  VFS200 	The vfsFile object must be opened before it can be used
  VFS201 	An invalid value was specified for the file access
  VFS203 	The file name must be specified as a file with optional absolute or relative path information or as an URL
  VFS204 	The file must not have an active output or source associated with it
  VFS206 	The file must be opened with write access to enable writing to it
  VFS207 	The file must be opened with read access to enable reading from it
  VFS209 	An invalid value was specified for the absolute cursor movement
  VFS210 	Both absolute and relative cursor movement may not be specified
  VFS211 	The cursor cannot be positioned before the start of the file
  VFS212 	An invalid value was specified for the start of the locked region
  VFS213 	An invalid value was specified for the end of the locked region
  VFS214 	An invalid timeout value was specified
  VFS215 	The locked region must be at least one character long
  VFS216 	The specified lock region overlaps an existing lock region for the file
  VFS217 	The function timed out before the lock could be obtained
  VFS218 	An invalid lock ID was specified
  VFS300 	Generic operating system error exception
  VFS301 	The specified directory does not exist
  VFS302 	Unable to connect to the specified host and port
  VFS303 	Username and password was rejected by host
  VFS305 	The specified directory is not empty
  VFS306 	The specified file does not exist
  VFS307 	The specified file exists