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.
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.
To use OMVFS, you must import it into your program using an import declaration such as:
import "omvfs.xmd" prefixed by vfs.
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/
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
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.