vfsList

function

Library: File system utilities (OMVFS legacy)
Include: omvfs.xin

Declaration

define external function vfsList
   matching  value       stream   path-match optional  initial {"*"}
       into  modifiable  stream   namelist
    include  value       integer  include    optional  initial {VFS-FULL-CONTENTS}

or

define external function vfsList
   matching  value       stream   URL-match  optional  initial {"*"}
         on  value       vfsDir   dir
       into  modifiable  stream   namelist
    include  value       integer  include    optional  initial {VFS-FULL-CONTENTS}

Argument definitions

path-match: is the name matching criteria expressed in local file system format.

URL-match: is the name matching criteria expressed a relative URL using the file scheme and with the specified vfsDir object as its base.

dir: is a vfsDir object created by connecting to a directory using either vfsConnect or vfsConnectDir.

namelist: is the returned shelf of matched directory items

include: specifies the type of items to include (directories, files, or both)

Purpose

Use vfsList to list the files and/or subdirectories in a directory. The results are returned as the items in a modifiable stream shelf. This shelf is initially cleared of all contents.

Requirements

You must include the following line at the beginning of your OmniMark program:

  include "omvfs.xin"

path-match:

must be in local file system format
may be specified using wild cards ("*" and "?")

If path-match is not specified, the action will be performed on the current working directory of the local file system as if a match value of "*" was used.

URL-match:

must be expressed as a relative URL based on the current working directory for dir (else external exception VFS105)
may be specified using wild cards ("*" and "?")

If URL-match is not specified, the action will be performed on the current working directory for the vfsDir object dir as if a match value of "*" was used.

The vfsDir object dir must:

represent an existing connection made using vfsConnect or vfsConnectDir (else external exception VFS100)
represent a connection made using the File scheme (else external exception VFS001)

include must be one of the following values:

VFS-FILES - only file names are items in the modifiable shelf stream
VFS-DIRS - only directory names are items in the modifiable shelf stream
VFS-FULL-CONTENTS - both file and directory names are items in the modifiable shelf stream

If the value supplied for include is not one of these an exception will be thrown (external exception VFS109). If include is not supplied, the action will be performed as if an include value of VFS-FULL-CONTENTS was used.

Usage Notes

An item is added to the names shelf for every directory and/or file that meets

the match specification, and
the include specification

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

The precise wildcard matching algorithm used is platform dependent, and thus a given file pattern may match a slightly different set of files on different platforms in some cases.

External exception VFS111 is thrown if an URL supplied as a parameter to this function contains invalid encoding.

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.

External exception VFS004 is thrown if the URL or path exceeds system length limits.

Example: Listing all the files and directories in the current directory

This program will collect a list of all items in the current working directory, check the last modified date, and output a list of everything that has been modified since 8:00am EST, October 31, 2000

    include "omvfs.xin"
    include "omdate.xin"
    process
       local stream listing variable
  	. . .
       vfsList
       	into listing
       	include VFS-FULL-CONTENTS
       repeat over listing
          local stream attrs variable
          vfsDescribe listing
             into attrs
          output listing || "%n" when ymdhms-second-difference ( attrs{"mtime"},
             "20001131080000-0500" ) > 0
       again

Other Library Functions