Return the files in a directory

dir()

Return the files in a directory

SYNTAX

dir(name_array, type_array, directory, pattern, options)

Returns the files in a directory into two arrays, one containing file names and one containing file types.

name_array	The name of an alphanumeric subscripted field. This field receives the file names.
type_array	The name of an integer subscripted field. This field receives the file types (1=file, 2=directory).
directory	The name of the directory whose contents are to be returned, e.g.: “.” “/usr/data” The directory can be on a server, and can contain environment variables.
pattern	This argument must be one of the following: “*” Selects all files “*.x“ Selects all files with the extension x. x may be any number of characters. No other patterns are supported.
options	One or more options. Multiple options are combined using the | operator. Options are defined in the standard include file $SCULPTOR/include/files.h. The options are: DIR_FILES Return standard files. DIR_DIRS Return directory names (pattern is ignored). DIR_RMEXTN Remove filename extensions. DIR_NATIVE Keep native filename. If this is specified, filenames are returned in native format with no conversion. If not, filenames in MS-DOS/Windows are folded to lower case. Either DIR_FILES, DIR_DIRS or both must be specified.

The dir() function fills the name_array with filenames, and the type_array with the corresponding file types (1=file, 2=directory). These are also defined in $SCULPTOR/include/files.h, as follows:

FILETYPE_FILE	1
FILETYPE_DIR	2

Unused elements of the arrays are cleared. If the arrays are multi-dimensional, the first dimension is used.

The maximum number of filenames that can be returned is represented by the value of dim(name_array,1).

This function returns the number of names that were placed in name_array. If a directory listing could not be obtained, the return value is negative, as follows:

Return value	Meaning
-1	The name_array specified is not a valid field
-2	Unable to read the directory specified

---

Note

Since Sculptor version 6.2.0 this function supports field arrays with the autoredim’ed “a” flag. So that if the number of files is greater than the array, it will be redim’ed to acomodate the number of filenames.

Another way to avoid the array size limitation is to use the dir_to_file() function, that saves file names and types into a Sculptor keyed file.

---

EXAMPLES

Reads all files with the .f extension into the defined arrays:

!temp FileNames,,a20[50]
!temp FileTypes,,u1[50]

     dir(tmp.FileNames, tmp.FileTypes, "..", "*.f", DIR_FILES)

Reads all files with the .f extension from server servername and directory /sources into the defined array:

!temp FileNames,,a20[50]

     dir(tmp.FileNames, NULL, "servername:/sources", "*.f", DIR_FILES)

---

RELATED TOPICS

File and directory handling functions