Home > Language Reference > File Functions > Dir

Dir

The Dir function returns a list of the files found matching the specified filespec.

Usage

In an automation task, you often have to repeat the same actions for all the files within a folder, or for all the files with a specific extension. Dir function returns the needed list of files to process. We recommend to use DirTree instead of Dir.

Syntax

count=Dir(<file_spec>, tab_long_filename$(), tab_short_filename$(), tab_attribute_filename$(), <option_string>)

Parameters

<file_spec>, string. For example, to return the list of files in the c:\wttest folder specify "c:\wttest\*.*"   . If the path is omitted, the search is performed in the current working folder. If option "R" is specified, the files are searched in the current folder and all its subfolders.

tab_long_filename$(), array of strings. It contains the long file names of the files found (including hidden or system files), without their paths.

tab_short_filename$(), array of strings. It contains the short file names (DOS 8.3 format) of the files found with their paths.

tab_attribute_filename$(), array of strings. It contains the attributes of the files found. The possible values are:
Return value   Attribute description
 D  Folder
 R  Read only
 H  Hidden
 A  Archive
 S  System

<option_string>, string which specifies the search and sort order of the result arrays. It may contain one or more of the following letters:
 <option_string>  Description 
 N   Sort by name
 S  Sort by size
 E  Sort by extension
 D   Sort by date
 G  Returns folders first
 R   Include subfolders
 A  Sort by last access date
For example,  if <option_string> is "AN", the arrays will be sorted by last access date. For identical access dates, files will be sorted by name. 

Return value

count, optional integer. If the function succeeds, it returns the number of files found. If the function fails, the return value is -1 (see File Functions Error Codes).

Remarks

The arrays used as arguments for the Dir function must be declared at the beginning of the script using Dim function.

If <file_spec> ends with "*.*", the first 2 items in the arrays tab_long_filename$() and tab_short_filename$() will be "." and ".." as in a DOS DIR command listing. In tab_attribute_filename$(), they will appear with the "D" attribute (folder).

If Dir function is used with the "R" option, file names appear in the specified order, whatever folder they reside in. If the "R" option is used in a search for "*.*", tab_long_filename$() and tab_short_filename$() will contain "." and ".." several times (see the example below).

See also

DirTree
FileAttr$

Example

Dim tab1$(100)
Dim tab2$(100)
Dim tab3$(100)
 
spec$="*.lst"
'Returns all the *.LST filenames within the current folder and its subfolders.
num=dir(spec$,tab1$(),tab2$(),tab3$(),"R")
if num=0 then stop endif
i=0
repeat
msgbox(tab1$(i))
i=i+1
until i>=num