Interrupt 21h Function 714Eh

Searches a directory for the first file or directory whose name and attributes match the specified name and attributes.

mov ax, 714Eh             ; Find First File
mov ch, MustMatchAttrs    ; see below 
mov cl, SearchAttrs       ; see below
mov dx, seg Filename      ; see below
mov ds, dx
mov dx, offset Filename
mov di, seg FindData      ; see below
mov es, di
mov di, offset FindData
mov si, DateTimeFormat    ; see below
int 21h

jc  error
mov [Handle], ax          ; search handle
mov [ConversionCode], cx  ; Unicode to OEM/ANSI conversion OK?

Parameters

MustMatchAttrs

Additional filter on the attributes specified in SearchAttrs. This parameter can be a combination of these values:

_A_NORMAL (0000h)
	The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
	The file can be read from, but not written to.
_A_HIDDEN (0002h)
	The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
	The file is part of the operating system or is used exclusively by it.
_A_VOLID (0008h)
	The name specified by Filename is used as the volume label for the current medium.
_A_SUBDIR (0010h)
	The name specified by Filename is used as a directory, not a file.
_A_ARCH (0020h)
	The file is an archive file. Applications use this value to mark files for backup or removal.

SearchAttrs

File attributes to search for. This parameter can be a combination of these values:

_A_NORMAL (0000h)

_A_RDONLY (0001h)

_A_HIDDEN (0002h)

_A_SYSTEM (0004h)

_A_VOLID (0008h)

_A_SUBDIR (0010h)

_A_ARCH (0020h)

Filename

Address of a null-terminated string specifying the name of the file or directory to search for. The name, which must be a valid filename or directory name, can include the "*" and "?" wildcard characters. Long filenames are allowed.

FindData

Address of a WIN32_FIND_DATA structure that receives information about the file.

DateTimeFormat

Date and time format to be returned. This parameter must be one of these values:

0	Returns the date and time in 64-bit file time format.
1	Returns the MS-DOS date and time values. MS-DOS date and time values are returned in the low doubleword of the FILETIME structure. Within the doubleword, the date is returned in the high-order word; the time is in the low-order word.

Return Value

Clears the carry flag, copies information about the file to the specified buffer, returns the search handle in the AX register, and sets the CX register to a combination of the following values if successful:

Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

Find First File and subsequent calls to Find Next File (Interrupt 21h Function 714Fh) use the following algorithm to match the attributes of a file or directory (referred to as Attributes in the algorithm) against MustMatchAttrs and SearchAttrs.

if  ((((<MustMatchAttrs> & ~<Attributes>) & 0x3F) == 0)
      && (((~<SearchAttrs> & <Attributes>) & 0x1E) == 0))
    {
         return the file or directory name 
    }
    else
    {
         continue searching for the next name
    }
 

The following table lists the MustMatchAttrs and SearchAttrs values for some common searches where the specified filename is "*.*". In the table, the word normal means that the read only, hidden, or system attributes have not been set. Parentheses are used to indicate that a file or directory has more than one attribute. For example, (hidden and system) indicates that a file or directory has both the hidden attribute and the system attribute.

This function can be used to return the volume label by specifying only _A_VOLID (0008h) in both MustMatchAttrs and SearchAttrs.

An application may use the handle returned in the AX register in subsequent calls to Find Next File (Interrupt 21h Function 714Fh). It is important to close the handle when it is no longer needed by calling Find Close (Interrupt 21h Function 71A1h).

Wildcard searches are more flexible in Windows 95 than in MS-DOS. For example, *1 finds the filenames (both long filenames and aliases) that end in a 1, and *mid* finds filenames that contain the characters mid. In MS-DOS and in Windows 95 searching on real-mode FAT directories, all characters after the first * are ignored.