Purpose |
Return a filename and/or directory entry that matches a file name mask and an optional attribute. | |||||||||||||||||||
Syntax |
file$
= DIR$(mask$ [, [ONLY] attribute&, TO DirDataVar]) | |||||||||||||||||||
Remarks |
There are two forms to the DIR$() function. The
first form, which includes a mask
The second form may optionally specify the key-word NEXT to aid in self-documentation of the source code. mask$ specifies a filename or path which can include a drive name and system wildcard characters (* and ?). If the numeric attribute parameter is zero (or not specified), DIR$ returns only "Normal" files. If mask$ is a null (zero-length) string, the function call is equivalent to the second form of the function to find subsequent matching filenames. In that case, an optional attribute is ignored. If an attribute& is specified, it must use a standard operating system numeric attribute code. This causes DIR$ to include filenames with specific attributes in the search, in addition to normal files. "Normal" files are those which are not hidden or system files, nor are they a directory or a volume label.
You can search for filenames with multiple attributes set by adding the attribute codes together. For example, to search for hidden and system files, you'd add those codes together (2 and 4) to get 6. All other attribute codes (except for volume label) are normally inclusive. For example, specifying both hidden and system results in DIR$ returning all hidden files, system files, normal files, and files that are both hidden and system. If the ONLY option is included, normal files are excluded from the file search. For example: DIR$(mask$, ONLY 16) just the directory entries which match mask$ are returned. An attribute of 8 will return the volume label, if one exists. In this case, mask$ must reference the drive letter of the target drive, and additional path information is ignored. Additionally, you may specify a UNC name for a shared drive (subject to operating system restrictions), and retrieve the volume label, if one exists, and you have suitable access rights. You can also obtain the volume label for a 'hidden' share with NT/2000/XP by appending a trailing dollar symbol to the share name. ' Retrieve volume for share \\server\drive0 The DIR$ function may optionally assign the complete directory entry to an appropriate UDT variable if you include the TO clause as a parameter. The complete directory entry contains 592 bytes of data, corresponding to the following TYPE definition. This definition (DIRDATA) is built into PowerBASIC, and need not necessarily be included in your source code. The DirData UDT is identical to the Unicode version of the Win32_Find_Data structure used by the Windows API for this purpose. TYPE DirData You can declare a variable as DIRDATA for this purpose, or use any other user-defined type of at least 592 data bytes. The additional data may be used for any other purpose in your program. CreationTime, LastAccessTime, and LastWriteTime members of the DIRDATA can be assigned to a PowerTime object to convert the QUAD integer (FILETIME) values for easy calculations and conversions. LOCAL f AS STRING LOCAL d AS DIRDATA LOCAL t AS IPOWERTIME
t = CLASS "PowerTime" ... f = DIR$("c:\*.*" TO d) t.FileTime = d.CreationTime ' t contains the file creation time in a localized format.
| |||||||||||||||||||
Restrictions |
PowerBASIC performs file matching with both the long (LFN) and short (SFN) filename versions of filenames. This means that DIR$ will also return filenames that start with the specified extension (as per standard Windows operating system behavior). For example, A$ = DIR$("*.htm") will match filenames such as "Index.htm", "Default.html", "Homepages.htmb", "cgilib.htmlpages", etc. Similarly, A$ = DIR$("*.h??") and DIR$("*.ht*") will match the same filenames. DIR$ is thread-safe, so DIR$ operations in one thread do not interfere with DIR$ operations in another thread. However, you should be aware that specifying a new mask$ parameter always starts an entirely new DIR$ search loop. | |||||||||||||||||||
See also |
CURDIR$, DIR$ CLOSE, FILEATTR, GETATTR, ISFILE, PATHNAME$, PATHSCAN$, SETATTR | |||||||||||||||||||
Example |
The following code shows a typical method of retrieving filenames from a directory: DIM Listing(1000) AS DirData |