Dir

(Engine-Level Function)

Description:	Performs a search in the given directory and returns an array of matching file names.
Returns:	Array
Usage:	Script only.
Function Groups:	File I/O
Related to:	DriveInfo \| FileFind \| FileDialogBox \| GetFileAttribs
Format:	Dir(Path, Attributes, Option)
Parameters:

Path

Required. Any text expression that indicates the full path name for the directory to list. The search is non-recursive (i.e. it considers only the specified directory, not any of its sub-directories). Path may include a wildcard, such as "*.DAT". A known path alias for File-Related Functions may be provided in the form, :{KnownPathAlias}.

Attributes

Required. Any numeric expression that gives the attributes to match on each file listed. Files that don't match these attributes won't be listed. The Attribute parameter may be set as one of the following:

Attribute	Bit No.	Meaning
0	-	Files without attributes
8	3	All files (regardless of attributes)

... or, it may be constructed by adding together the numbers from the following table :

Attribute	Bit No.	Meaning
1	0	Read only
2	1	Hidden
4	2	System
16	4	Sub-directory
32	5	Archive

Option

Required. Any numeric expression giving the type of text information to generate. All information is placed in a single text string (which will be stored in an element of the array that is created). The information is written from left to right, with lowest option numbers first.

Option	Bit No.	Description
1	0	Short file name
2	1	Full path and file name
4	2	File size
8	3	File last modified date (in text)
16	4	File last modified time (in text)
32	5	File attributes (ADHRS)
64	6	File last modified date/time combination (in seconds since January 1, 1970)
128	7	File creation date (in text)
256	8	File creation time (in text)
512	9	File creation date/time combination (in seconds since January 1, 1970)

The attributes returned as a result of bit 5 being set are printed as the capital letters A (archive) D (subdirectory), H (hidden), R (read-only), and S (system).

Comments:

This function returns an array of text values, where each element contains the information specified by Option for each file that matches both Path and Attributes.

If no files are found, the return value will be set to invalid. Notice that the only difference between this function and the FileFind function is that FileFind searches down through the whole directory tree, while this function looks in the immediate directory only.

If you are looking for a "browse for folder" dialog box, please refer to the FileDialogBox function.

(See: Bitwise Parameters & Operations)

Example:

  If ! ValidValid(datFiles);
  [
    DatFiles = Dir("G:\Research\*.DAT" { Path }, 
                   0 { All normal files }, 
                   1 { Retrieve file name }); 
  ]

To display the first entry, try:

  ZText(10, 10, DatFiles[0], 15, 0);

The result might be something like:

"TEST.DAT"