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 : 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 sub-directories, 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.

Note

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.

Examples :

      - 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
         ? FileDdat() // 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
       *
       *
       -  Using FileSeek() as Directory() function

       PROC FLstFSeek() // File List by FileSeek()

         LOCAL cFileName,;
               nFileCount := 0,;
               nFAttr :=  1 +; // ReadOnly
                          2 +; // Hidden
                           4 +; // System
                         16    // Directory ( => 23 )

         SET DATE GERM
         SET CENT ON

          /* Display system files and directories in the root directory.
         Attribute: READONLY, HIDDEN, SYSTEM, DIRECTORY --> 23 */

         ? PAD( "File Name", 32 ), "Size Date Time Attribute"
         ? REPL( "-", 32 ), "--------------- ---------- -------- ---------"

         cFileName := FileSeek("C:\*.*", nFAttr)

         WHILE .NOT. EMPTY( cFileName )
             ++nFileCount
            ? PAD( cFileName, 32) ,; // File name
              TRAN( FILESIZE(), "999,999,999,999" ) ,;
              FILEDATE(),;
              FILETIME(),;
              TRAN( FILEATTR(), "99999,999" )

            cFileName := FileSeek() // Look for next entry
         ENDDO
         ?
         ? nFileCount, "Files and directories found."
         ?
         WAIT "End of FileSeek.prg"

      RETU // FLstFSeek()

Files

lib : hbct

Seealso

FileAttr(), FileDate(), FileSize(), FileTime(), HB_FileMatch(), Directory()