File system utilities (OMVFS)

The OMVFS library allows you to manipulate files and directories and to read and write data in files. It is intended to provide a unified interface to files and directories regardless of their location or the protocol used to access the them. Currently, full functionality for accessing the local file system is supported, whereas support for FTP, HTTP, and HTTPS servers is partial.

OMVFS supports the use of either local system paths or URLs for specifying files and directories. You must use URLs to access external file systems such as FTP or HTTP. You may use either local system paths or URLs to access the local file system. If you know that your function will only be accessing files on the local file system, we recommend that you use local file paths.

OMVFS support both a generic open function (vfs.open) and protocol specific open functions (vfs.open-ftp, ...). Protocol specific functions provide support for additional parameters that may not be supported by the generic open command, or may require the insertion of additional information into the URL. For flexibility, and ease of typing, we recommed that you use the generic vfs.open function unless you need to use one of the protocol specific open functions for the functionality it provides.

One of the principal advantages of using the generic vfs.open function is that it can be used to open different types of file systems at different points in the run of your program. For instance, it could be used in an application that gathered URLs from a web page and then downloaded the information pointed to by those links.

Opaque Data Types

The OMVFS library contains two opaque data types, vfs.file and vfs.directory.

You can think of vfs.file as a file handle or a file object. It is used to read and write files, to lock and unlock files, and to retrieve information about files.

The vfs.directory object is designed to act as a handle or object to represent a directory. It is intended mostly to manage the connection to external directories or directory-like data sources over HTTP or FTP protocols. Since the use of vfs.directory is not currently supported for these protocols, we recommend that you not use vfs.directory at this time.

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

Usage Note

To use OMVFS, you must import it into your program using an import declaration such as:

  import "omvfs.xmd" prefixed by vfs.

Example

Here is a very simple example of the versatility of vfs.open. The following program can be used to display a file on the console and can accept a local file path, or a FILE, FTP, or HTTP URL as an argument:

  ; showany.xom
  import "omvfs.xmd" prefixed by vfs.
  
  process
     local vfs.file file-handle
  
     set file-handle to vfs.open #args[1]
     output vfs.reader of file-handle

For example, you can print out raw markup of the Stilo homepage with a command line like this:

  omcpe -s showany.xom http://www.stilo.com/

Example

The following Windows-specific sample program will list all files in c:/temp/ which have been modified more recently than 8 am October 31st EST, 2000.

  import "omvfs.xmd" prefixed by vfs.
  include "omdate.xin"
  
  process
     local string file-names variable
     local string path-name
  
     set path-name to "c:/temp/"
  
     vfs.list matching (path-name || "*")
                  into file-names
               include vfs.all-files
  
     repeat over file-names as file-name
        local string file-attributes variable
  
        vfs.describe (path-name || file-name) into file-attributes
        output file-name || "%n" 
           when ymdhms-second-difference (file-attributes{"mtime"}, 
                                          "20001131080000-0500") > 0
     again

OMVFS Generated Exceptions

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

  • 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 name exceeds system length limits:
  • VFS005: Memory could not be allocated
  • VFS006: An internal error has occurred in omvfs
  • 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 in URL format:
  • VFS105: The path is not a valid absolute or relative path:
  • VFS109: An invalid value was specified for the content type include indicator
  • VFS111: The 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 'X' must be specified as a file with optional absolute or relative path information or as an URL
  • VFS204: The file 'X' must not have an active output or source associated with it
  • VFS206: The file 'X' must be opened with write access to enable writing to it
  • VFS207: The file 'X' must be opened with read access to enable reading from it
  • VFS209: An invalid value was specified for the absolute cursor movement
  • VFS210: Absolute and relative cursor movement may not both 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 on 'X'
  • VFS218: An invalid lock ID was specified
  • VFS300: Generic operating system error
  • VFS301: The directory 'X' does not exist
  • VFS302: The buffer length received from OmniMark is out of range
  • VFS305: The directory 'X' is not empty
  • VFS306: The file 'X' does not exist
  • VFS307: The path 'X' exists
  • VFS308: This function is not available on this operating system
  • VFS309: At least one of owner and group must be specified
  • VFS310: Insufficient permissions to complete operation
  • VFS311: Could not read data
  • VFS312: Could not write data
  • VFS400: Protocol error:
  • VFS500: Protocol unsupported on this platform.