Dir function (LotusScript® Language)

Syntax

Dir[$] [ ( fileSpec [ , attributeMask ] ) ]

Elements

fileSpec

A string expression that specifies a path and the file names you want returned. The argument is required only for the first call to Dir$ for any path.

Standard wildcard characters can be used in fileSpec to designate all files satisfying the wildcard criterion. Asterisk ( * ) for either the file name or the extension designates all files with any characters in that position. Question mark ( ? ) in any character position in either part of the name designates any single character in that position.

attributeMask

An integer expression whose value specifies what names should be returned. If this argument is omitted, the names of normal files that match fileSpec are returned. If you supply an attributeMask argument, you must supply a fileSpec argument.

Dir$ always returns the names of normal files. To include other files in the returned list of file names, specify the sum of those values in the following table that correspond to the desired kinds of files:

Return value

Dir returns a Variant of DataType 8 (String), and Dir$ returns a String.

If the directory path specified in the argument does not exist, this function throws error "Path not found" (ErrPathNotFound in lserr.lss).

If the directory path exists, but there are no files matching the filespec, it does not throw an error, but returns "" (empty string).

Usage

The constants in the table are defined in the file lsconst.lss. Including this file in your script allows you to use constant names instead of their numeric values.

To determine whether a particular file exists, use an exact file name for the file_spec argument to Dir or Dir$. The return value is either the file name or, if the file does not exist, the empty string ("").

The first call to Dir or Dir$ returns the name of the first file in the specified directory that fits the file name specifications in the fileSpec argument. Then:

• Subsequent calls to Dir or Dir$ without an argument retrieve additional file names that match fileSpec. You can call the Dir function with no arguments as either Dir or Dir( ). You can call the Dir$ function with no arguments as either Dir$ or Dir$().
• If there are no more file names in the specified directory that match the specification, Dir returns a Variant of DataType 8 (String); Dir$ returns the empty string ("").

If Dir or Dir$ is called without an argument after the empty string has been returned, LotusScript® generates an error.

The Dir or Dir$ function may not be called recursively.

Example