ADir()

This function creates an array containing information about files in a specified directory. Read it as "Array from directory" and it makes perfect sense.

Usage

nCount = ADIR( ArrayName [, cFileSpec [, cAttributes 
               [, nFlag | cCreatorType ] ] ] )

Parameter	Value	Meaning
ArrayName	Array Name	The array into which directory information is dumped. It's created or resized if necessary.
cFileSpec	Character	Only files matching cFileSpec are included. Wildcards * and ? can be used. cFileSpec can include a drive and directory as well.
	Empty	When used with a combination of D, H and S attributes, limits results to files matching specified attributes.
	Omitted	Include all files from current drive and directory.
cAttributes (string may contain none, any or all of these four)	Omitted	Include only file names, excluding directories and hidden and system files.
	D	Include information on sub-directories of the specified directory.
	H	Include information on hidden files.
	S	Include information on system files.
	V	Include only the volume information for the specified drive. You don't need to specify the root directory for this to work. Other attributes are ignored if "V" is included.
nFlag (VFP 7 and later)	0 or omitted	Put file names into the array in uppercase.
	1	Put file names into the array in their original case.
	2	Put file names into the array using the DOS 8.3 convention.
cCreatorType	Character	Mac file creator type—ignored in Windows.
nCount	Numeric	The number of rows in the resulting array; that is, the number of directory entries (files, directories and volume names) for which information was collected.
nCount	0	No matching files were found.

The D, H and S attributes can be combined into a single attribute string. These interact with the file specification provided to select a subset of files and/or directories. To get a list of all sub-directories, pass the empty string for cFileSpec and "D" for cAttributes.

In VFP 5 and earlier, you could get a list of sub-directories for a specified directory by passing the path and a single asterisk for the file name, like this:

ADIR(aSubDirs, cPath + "*", "D")

This approach doesn't work in VFP 6 and later—that call results in a list containing both files and directories. In those versions, you have to change to the directory of interest and then pass the empty string for the path, like this:

CD (cPath)
ADIR(aSubDirs, "", "D")

Of course, in that case, you have to remember to save the old directory and change back to it afterward.

If the volume name is requested, a single element character array is created, containing the volume name. In all other cases, the array created has five columns, as follows:

Column	Meaning
1	File name—character.
2	File size in bytes—numeric.
3	Date file was last written—date.
4	Time file was last written—character.
5	File Attributes—a single five-character string. Each position represents one attribute. If the file has that attribute, the corresponding letter is there; if not, a period is found in that location. The attributes are: R—read-only A—archive bit is set S—system file H—hidden file D—directory For example, "R...." means a read-only file, while ".A.H." means a hidden file needing to be archived.

In VFP 7, IntelliSense pops up a list of choices when you reach the attribute parameter. That's cool. What's not is that the list is wrong. It includes "Archive" and omits "Volume." Choosing "Archive" generates a spurious cAttributes value of "A." It turns out that you can pass pretty much anything for cAttributes without error, so it may be a while before you catch on that you're seeing all files, not just those in need of backup.

We received a note from someone who read the first edition of this book and wondered what ADIR() returns if it can't create the array. We haven't quite figured out how to test that one. We think the only situation in which that could happen is if there are so many files in the directory that there's not enough memory to hold the resulting array or the array would exceed the limit of 65,000 elements. Seems to us that the directory structure would probably give out long before you could put enough files there to stress memory that way.

Example

? ADIR(aFiles)            && Creates an array of all files in 
                          && current directory.
? ADIR(aDirect, "", "D")  && Creates an array of all
                          && subdirectories of current directory.
? ADIR(aDBFs, "*.DBF", 1) && Fills array with list of tables
                          && in their original case.
? ADIR(aDBFs, "DATA\*.DBF", 2)&& Fills array with list of tables 
                          && in DATA directory in DOS 8.3 format.