The OMVFS library allows you to manipulate files and directories and to read and write data in files.

The OMVFS library is intended to provide a unified interface to files and directories regardless of their location or the protocol used to access the them. Full OMVFS functionality is being delivered in stages. The current version supports full functionality for accessing the local file system and partial functionality for accessing FTP, HTTP, and HTTPS servers.

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, etc.). 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.

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 UTR as an argument:

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

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

  ompvm -load showany.xvc http://www.stilo.com/

OMX components

The OMVFS library contains two OMX components, 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.

Usage note

The OMVFS library is packaged as a module. To use OMVFS, you must import the OMVFS module into your program using a statement like this:

  import "omvfs.xmd" prefixed by vfs.

Note that the prefix "vfs.", which is attached to all functions, constants, and OMX's exported by this library, is set in this statement and can be changed. For readability, we recommend that you always use the standard prefix when importing modules supplied by OmniMark.

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.

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.

  process
     local stream listing variable
     local stream list-dir
  
     set list-dir to "c:/temp/"
  
     vfs.list matching (list-dir || "*")
      into listing
      include vfs.all-files
  
     repeat over listing
        local stream attrs variable
        vfs.describe (list-dir || listing)
         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.

  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:

Functions    vfs.change-directory    vfs.change-owner    vfs.change-permissions    vfs.close    vfs.connect    vfs.connect-directory    vfs.copy    vfs.cursor-position    vfs.default-certificates-file    vfs.delete-directory    vfs.delete-file    vfs.describe    vfs.describe-file    vfs.directory    vfs.directory-name    vfs.disconnect    vfs.file    vfs.file-directory    vfs.file-name    vfs.link    vfs.list    vfs.lock    vfs.make-directory    vfs.move    vfs.move-cursor    vfs.omvfs-version    vfs.open    vfs.open-file-system    vfs.open-ftp    vfs.open-http    vfs.open-https    vfs.reader    vfs.set-default-certificates-file    vfs.truncate    vfs.unlock    vfs.writer

Platforms    HP/UX    HP-UX Itanium 2    IBM AIX 5.3    Linux (Intel)    Linux Red Hat Enterprise 5    MS Windows 98/ME    MS Windows NT/2000/XP    MS Windows Vista    Sun Solaris 8

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]