FILESEEK()
 Searches for files by name and attribute
------------------------------------------------------------------------------
 Syntax

     FILESEEK([<cFileMap>, [<nFileAttr>], [<lExact>]])
         --> cFileName

 Arguments

     <cFileMap>  Designates a file name including its path and drive
     designation.  It may contain wildcards.

     <nFileAttr>  Designates the file attribute that corresponds to the
     ones described in the table on the next page.  The default value is 0.

     <lExact>  If you designate .T. as the optional parameter, FILESEEK()
     also checks for the exact agreement of the file attributes of the
     respective file with the value passed by <nFileAttr>.

     ()  If you call the function without parameters, it serves as a
     sequential call for a FILESEEK() with file specifications, and returns
     sequential entries as long as these are found.

 Returns

     FILESEEK() returns the name of the first or next entry (when called
     without parameter) located in the selected directory.

 Description

     FILESEEK() provides the foundation for a variety of functions.  As a
     group, they permit access to desired information about directory
     entries.  Implement the FILESEEK() function when you want information
     about a file group (wildcards).  When you call it with the <cFileMap>
     parameter, it searches for the first entry in the designated directory.
     If you call it without parameters, it searches for the next matching
     entry in the directory.  If no more entries are present, it returns a
     null string.  An attribute mask can further define a file group that is
     being searched for.  The desired file attributes are coded as follows:

     Table 7-15:  Coding the File Attribute
     ------------------------------------------------------------------------
     Value   Symb. constants     Assigned attribute
     ------------------------------------------------------------------------
     0       FA_NORMAL
     1       FA_READONLY         READ ONLY (Read-only)
     2       FA_HIDDEN           HIDDEN (Hidden files)
     4       FA_SYSTEM           SYSTEM (System files)
     8       FA_VOLUME           VOLUME (Name of a floppy/hard disk)
     16      FA_DIRECTORY        DIR (Directory)
     32      FA_ARCHIVE          ARCHIVE (Changes since last backup)
     ------------------------------------------------------------------------

     If you implement multiple attributes simultaneously, the table values
     are added accordingly.  Of course, not all combinations are useful.

 Exact File Attributes

     DOS does not make an exact comparison with a designated attribute mask
     and attributes actually found in a file.  Specify only the SYSTEM,
     HIDDEN, VOLUME, or DIR attributes for an entry to be found.  Files with
     only one other attribute bit set are always returned, regardless of the
     value specified in the attribute mask.  This way, a function call with a
     mask value of 16 returns not only subdirectories, but all files without
     a set attribute (e.g., all the ARCHIVE and R/O files).

     To avoid this, you can designate .T. as the third parameter.  The
     function itself also reviews the designated attribute mask with the
     actual file attributes, for an exact agreement.  Then, the designation
     of a 16 mask and .T., only returns subdirectories.

 Internal Data Buffer

     Every time you use FILESEEK() all the data for a directory entry is
     saved to an internal buffer.  Individual information such as size, time,
     or date is easily accessible.  To do this, the FILETIME(), FILEDATE(),
     etc., functions are called without parameters; otherwise, it requires
     another call to the disk, instead of taking the data from an internal
     buffer.

 Notes

     .  Use the recursive sample function SCANFILES() in the
        accompanying Tooldemo.prg file, to produce the most effective
        programs to work with entire directory structures.

     .  Display the date and size of all files with the extension .TXT
        in a directory:

        cFile  :=  FILESEEK("C:\TEXT\*.TXT")
        DO WHILE .NOT. EMPTY(cFile)
           ? FILESIZE()               // Size of file in buffer
           ? FILEDATE()               // Date of file in buffer
           cFile  :=  FILESEEK()      // Search for next entry
        ENDDO

     .  Display system files in the root directory.  Attribute: READ
        ONLY, HIDDEN, SYSTEM, ARCHIVE --> 39, although 6(2 + 4) will
        suffice as an attribute:

        cFile  :=  FILESEEK("C:\*.*", 39)
        DO WHILE .NOT. EMPTY(cFile)
           ? cFile                    // File name
           cFile := FILESEEK()        // Look for next entry
        ENDDO

     .  Only query the subdirectory:

        cSubDir := FILESEEK("C:\*.*, 16, .T.)
        DO WHILE .NOT. EMPTY(cSubDir)
           ? cSubDir                  // Name of the directory
           cSubDir := FILESEEK()      // Search for next directory
        ENDDO