DIR$ function

Purpose

Return a filename that matches the given mask and optional attribute.

Syntax

f$ = DIR$
f$ = DIR$(mask$ [, attribute])

Remarks

mask$ specifies a filename or path which can include a drive name and DOS compatible wildcard characters (* and ?). If the numeric attribute parameter is not specified, DIR$ returns the name of the first file that matches mask$.

Further calls to DIR$ with no parameters returns subsequent matching filenames.

When the returned string is null (zero-length), there are no further matching filenames to retrieve. If mask$ is a null (zero-length) string, the function call is equivalent to DIR$ with no parameters.

DIR$ can use, and return, Long File Names (LFNs).

If 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 regular files. "Regular" files are files that do not have their hidden or system attributes set; however, regular files do include read-only and archived files.

You can search for files 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 inclusive, for example: specifying both hidden and system results in DIR$ returning all hidden files, system files, regular files, and files that are both hidden and system.

Specifying directories will return all subdirectory names as well as regular files. You can use the GETATTR function to distinguish subdirectories from files.

A useful search attribute is 23, which returns subdirectories as well as System, Hidden and Read-only files. To return files without directories, use a search attribute of 7.

Specifying a volume label will return only the volume label, if any. In this case, mask$ must reference the drive letter of the target drive, and any additional path information is ignored. For example:

' Retrieve the disk volume for Drive C:

A$ = DIR$("C:", 8)

' Retrieve the disk volume for Drive H:

A$ = DIR$("H:\*.*", %VLABEL)

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 volume label for a 'hidden' share with NT/2000 PC's, 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 following table identifies equates that can be used to make your code more easily read:

Attribute	Description	Equate*
0 **	Normal	%NORMAL
1 **	Read-only	%READONLY
2	Hidden	%HIDDEN
4	System	%SYSTEM
8 ***	Volume Label	%VLABEL
16	Directory	%SUBDIR
32 **	Archived	%ARCHIVE

* Appropriate equates are defined in the WIN32API.INC file.

** These attributes are ignored by DIR$. DIR$ always returns read-only and archived files, as they're considered "regular".

*** If the attribute includes 8, the attribute code for the volume label, only the volume label will be returned (if one exists). Regular files aren't included in the search. Further calls to DIR$ will return an empty string, even if the original call included other attribute codes.

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 changing the mask during a DIR$ search loop (within the same thread) will affect the search loop operation. That is, if a typical DIR$ search loop block such as shown in the Example code below, changes the search mask mid-way through the loop, subsequent calls to DIR$ will begin to return files matching the new mask.

This is rarely a problem if the mask change takes place within the search loop code block, since the DIR$("mask") change will be plainly visible in the loop block code. However, the mask can also be changed from within a Sub/Function that is called from within the search loop block (provided that the Sub/Function is located within the same compiled module).

While such techniques are perfectly valid, the cause of the mask change may not be immediately obvious when viewing just the search loop code block. PowerBASIC allows the mask to be changed in this manner, since it may be an intended behavior on the part of the programmer, but in doing so, it opens up the potential for subtle bugs to be introduced into your code if this technique is not anticipated.