CitectVBA Programming Reference > CitectVBA Function Reference > File I/O Functions > Dir


Dir function returns a file or directory name that matches the given File and Attrib arguments.

Dir supports the use of multiple-character (*) and single-character (?) wildcards to specify multiple files.

Dir returns the first file name that matches both File and Attrib. To get any additional file names that match, call Dir again with no arguments. When no more file names match, Dir returns a zero-length string (" "). Once a zero-length string is returned, you must specify argument/s in the next call (to reset the function), or an error occurs.

Calling Dir with any argument will reset the function, and it will treat the call as a new call. Previous arguments passed to the Dir function are overwritten and forgotten (reset). You can reset the function (by supplying arguments in the function call) at any time, even if it has not yet returned every possible argument match result.

Calling Dir with the Directory attribute (16) does not continually return Directory names. You will need to check the attribute value of every return result to determine if the return is a valid directory name. To do so, use the GetAttr function. Because file names are retrieved in no particular order, you may want to store returned file names in an array and then sort the array.

Note: The file system keeps track of the current drive, and the current directory of every drive. Use the CurDir statement to determine the current directory. The current drive letter can be extracted from the Left character returned in the CurDir statement.


Dir(File, Attrib)


A string or expression that can represent a valid file name, and may include a DOS path structure including directory or folder names, and a drive letter.


A number or expression that can represent a sum of the attribute values of a file . This can be a constant or a numeric expression which includes any combination of attribute numeric values, whose sum specifies all relevant attributes of a file.


Possible combinations of values can sum to 0, 1, 2, 3, in fact every number from 0 to 64, each representing a unique combination of attribute values. For example, a file attribute value of 6 represents that the file has both System (4) and Hidden (2) attributes set.

Return Value

Returns a String representing the name of a file, directory, or folder that matches a specified pattern or file attribute, or the volume label of a drive. If File is not found, a zero-length string (" ") is returned. If Attrib is omitted, all files are returned that match File.

Related Functions

ChDir| ChDrive| CurDir, CurDir$| MkDir| RmDir


Dim strCurPath As String		' declare string to store current path
Dim strFileName As String ' declare string to store retrieved file name
Dim intFileCount As Integer ' declare integer to keep count of retrieved files
Dim arrFileList() As String ' declare string array to store file names
strCurPath = CurDir$() ' store current path for later restoration
ChDir "\" ' change to root directory of current drive
strFileName = Dir(*.dat) ' retrieve file name with .dat extension
Do ' initialize loop
If strFileName = "" Then ' check to see if valid filename returned
exit do ' exit from loop
intFileCount = intFileCount + 1 ' increment file counter variable
arrFileList(intFileCount) = strFileName ' store file name in array Redim arrFileList(intFileCount) ' increase array size to count value
strFileName = Dir() ' retrieve next file name to match original Dir call
Loop Until strFileName = "" ' loop again
ChDir strCurPath 'restore previous current directory