Dir

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

• The File argument is optional, and represents a string expression that specifies a valid file name, and may include a DOS path structure including directory or folder names, and a drive letter. You must specify File the first time you call the Dir function, or an error occurs.
• The Attrib argument is optional, and can be a constant or numeric expression whose sum specifies file attribute values. If you specify file attributes in the function call, File must be included. If the Volume attribute value (8) is specified, all other attribute values are ignored.

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.

Syntax

Dir(File, Attrib)

File:

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.

Attrib:

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.

where:

• 0 = Normal
• 1 = Read Only
• 2 = Hidden
• 4 = System
• 8 = Volume
• 16 = Directory or Folder
• 32 = Archive

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

Example

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

	Else

		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

	EndIf

Loop Until strFileName = ""			' loop again

ChDir strCurPath					'restore previous current directory