DosFindFirst

Bindings:  C, MASM 

This call finds the first file object or group of file objects whose 
name(s) match the specification. 

 DosFindFirst     (FileName, DirHandle, Attribute, ResultBuf, 
                  ResultBufLen, SearchCount, Reserved) 
 

 FileName (PSZ) - input 
    Address of the ASCIIZ path name of the file or subdirectory to be 
    found. The name component may contain global file name characters. 

 DirHandle (PHDIR) - input/output 
    Address of the handle associated with a specific DosFindFirst request. 
    The values that can be specified are: 

    Value     Definition 
    0001H     Assign handle 1, which is always available to a process. 
    FFFFH     The system allocates and returns a handle. If on input FFFFH 
              is specified, on output DirHandle contains the handle 
              allocated by the system. 

              The DosFindFirst handle is used with subsequent DosFindNext 
              requests. Reuse of this handle in another DosFindFirst 
              closes the association with the previous DosFindFirst and 
              opens a new association. 

 Attribute (USHORT) - input 
    Attribute value that determines the file objects to be searched for. 

    Bit       Description 
    15-6      Reserved and must be zero. 
    5         File archive 
    4         Subdirectory 
    3         Reserved and must be zero. 
    2         System file 
    1         Hidden file 
    0         Read only file 

   
    These bits may be set individually or in combination.  For example, an 
    attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only 
    file that should be archived. 

   
    If Attribute is 0, normal file entries are found.  Entries for 
    subdirectories, hidden, and system files, are not returned.  If 
    Attribute is set for hidden or system files, or directory entries, it 
    is considered an inclusive search.  All normal file entries plus all 
    entries matching the specific attributes are returned.  Set Attribute 
    to hidden+system+directory (all three bits on) to look at all 
    directory entries except the volume label. 

   
    Attribute cannot specify the volume label.  Volume labels are queried 
    using DosQFSInfo. Attributes of a file are queried and set with 
    DosQFileMode and DosSetFileMode. 

 ResultBuf (PFILEFINDBUF) - output 
    Address of the structure that contains the returned directory 
    information. The information reflects the last DosClose, DosBufReset, 
    DosSetFileMode, DosSetFileInfo, and DosSetPathInfo calls. 

    filedate (FDATE) 
       Structure containing the date of file creation. 

       Bit       Description 
       15-9      Year, in binary, of file creation 
       8-5       Month, in binary, of file creation 
       4-0       Day, in binary, of file creation. 

    filetime (FTIME) 
       Structure containing the time of file creation. 

       Bit       Description 
       15-11     Hours, in binary, of file creation 
       10-5      Minutes, in binary, of file creation 
       4-0       Seconds, in binary number of two-second increments, of 
                 file creation. 

    fileaccessdate (FDATE) 
       Structure containing the date of last access. See FDATE in 
       filedate. 

    fileaccesstime (FTIME) 
       Structure containing the time of last access. See FTIME in 
       filetime. 

    writeaccessdate (FDATE) 
       Structure containing the date of last write. See FDATE in filedate. 
       

    writeaccesstime (FTIME) 
       Structure containing the time of last write. See FTIME in filetime. 
       

    filesize (ULONG) 
       File size. 

    filealloc (ULONG) 
       Allocated file size. 

    fileattrib (USHORT) 
       Attributes of the file, defined in DosSetFileMode. 

    length (UCHAR) 
       Length of the ASCIIZ name string. 

    matchfilename (CHAR) 
       ASCIIZ name string for the first occurrence of FileName. 

 ResultBufLen (USHORT) - input 
    Length of ResultBuf 

 SearchCount (PUSHORT) - input/output 
    Address of the number of matching entries requested in ResultBuf. On 
    return, this field contains the number of entries placed into 
    ResultBuf. 

 Reserved (ULONG) - input 
    Reserved, must be set to zero. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    2         ERROR_FILE_NOT_FOUND 
    3         ERROR_PATH_NOT_FOUND 
    6         ERROR_INVALID_HANDLE 
    18        ERROR_NO_MORE_FILES 
    26        ERROR_NOT_DOS_DISK 
    87        ERROR_INVALID_PARAMETER 
    108       ERROR_DRIVE_LOCKED 
    111       ERROR_BUFFER_OVERFLOW 
    113       ERROR_NO_MORE_SEARCH_HANDLES 
    206       ERROR_FILENAME_EXCED_RANGE 
 
 Remarks 

 DosFindFirst returns directory entries (up to the number requested in 
 SearchCount) for as many files or subdirectories whose names and 
 attributes match the specification and whose information fits in 
 ResultBuf. On output, SearchCount contains the actual number of directory 
 entries returned. 

 DosFindNext uses the directory handle associated with DosFindFirst to 
 continue the search started by the DosFindFirst request. 

 Any non-zero return code indicates no handle has been allocated, 
 including such non-error indicators as ERROR_NO_MORE_FILES. 

 DosQSysInfo is called by an application to determine the maximum path 
 length allowed by OS/2. 

 For programs running without the NEWFILES bit set, only 8.3 filename 
 format names are returned.  These names are changed to uppercase. 

 
 Family API Considerations 

 Some options operate differently in the DOS mode than in OS/2 mode. 
  Therefore, the following restrictions apply to DosFindFirst when coding 
 for the DOS mode: 

 DirHandle must always equal hex 0001H or FFFFH on the initial call to 
 DosFindFirst. Subsequent calls to DosFindFirst must have a DirHandle of 
 hex 0001H unless a DosFindClose had been issued.  In this case, 0001H or 
 FFFFH is allowed.