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

Functions