DIR$ function

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]) file$ = DIR$([NEXT] [TO DirDataVar])

Remarks

There are two forms to the DIR$() function. The first form, which includes a mask string and optional attribute, is used to find the first filename which matches. The second form, without those parameters, returns subsequent matching filenames. When the returned string is null (zero-length), there are no further matching filenames.

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.

Attribute | Description | Equate
0 | Normal | %NORMAL
2 | Hidden | %HIDDEN
4 | System | %SYSTEM
8 | Volume Label | %VLABEL
16 | Directory | %SUBDIR

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. Another useful search attribute is 6, which returns normal, hidden, and system file, but no directories.

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

A$ = DIR$("\\server\drive0", 8)

' Retrieve volume for hidden share D: (\d$)

A$ = DIR$("\\server\d$", %VLABEL)

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

FileAttributes AS DWORD

CreationTime AS QUAD

LastAccessTime AS QUAD

LastWriteTime AS QUAD

FileSizeHigh AS DWORD

FileSizeLow AS DWORD

Reserved0 AS DWORD

Reserved1 AS DWORD

FileName AS WSTRINGZ * 260

ShortName AS WSTRINGZ * 14

END TYPE

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.

Previous versions of PowerBASIC used an ANSI version of DirData which was only 318 bytes in size. However, if you utilized the built-in form of DirData, your program should execute correctly under this version with no changes needed.

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, DISPLAY BROWSE, DISPLAY OPENFILE, 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

DIM x&, temp$

temp$ = DIR$("*.*", TO Listing(x&))

WHILE LEN(temp$) AND x& < 1000 ' max = 1000

INCR x&

temp$ = DIR$(NEXT, TO Listing(x&) )

WEND