dos12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
DosFindFirst2 (1.2)
Function Group  Overview                          Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosFindFirst2(pszFileName, phDir, usAttribute, pBuf, cbBuf,
    pusSearchCount, usInfoLevel, ulReserved);
PSZ pszFileName;           /* pointer to filename              */
PHDIR phDir;               /* pointer to directory handle      */
USHORT usAttribute;        /* attributes of file to be found   */
PVOID pBuf;                /* pointer to buffer for results    */
USHORT cbBuf;              /* size of results buffer           */
PUSHORT pusSearchCount;    /* number of entries found          */
USHORT usInfoLevel;        /* level of information to retrieve */
ULONG ulReserved;          /* must be zero                     */
 
The DosFindFirst2 function searches a directory for the file or files whose
filename and attributes match the specified filename and attributes.
 
The DosFindFirst2 function is a family API function.
 
Parameter       Description
────────────────────────────────────────────────────────────────────────────
 
pszFileName     Points to a null-terminated string. This string must be a
                valid MS OS/2 path and can contain wildcard characters.
 
phDir           Points to the variable that contains the handle of the
                directory to search.
 
usAttribute     Specifies the file attribute(s) of the file to be located.
                This parameter can be a combination of the following
                values:
 
                Value           Meaning
                ────────────────────────────────────────────────────────────
                FILE_NORMAL     Search for normal files.
 
                FILE_READONLY   Search for read-only files.
 
                FILE_HIDDEN     Search for hidden files.
 
                FILE_SYSTEM     Search for system files.
 
                FILE_DIRECTORY  Search for subdirectories.
 
                FILE_ARCHIVED   Search for archived files.
 
pBuf            Points to the buffer in which the file information is
                returned. The format for this buffer is determined by the
                value specified in the usInfoLevel parameter.
 
cbBuf           Specifies the size (in bytes) of the buffer pointed to by
                pBuf.
 
pusSearchCount  Points to the variable that specifies the number of matching
                entries to locate. The DosFindFirst2 function copies the
                number of entries found to this parameter before returning.
 
usInfoLevel     Specifies the type of file information to retrieve. This
                parameter can be one of the following values:
 
                Value                 Meaning
                ────────────────────────────────────────────────────────────
                FIL_STANDARD          Return a FILEFINDBUF structure with
                                      the results of the search. The
                                      information returned is identical to
                                      that returned by the DosFindFirst
                                      function.
 
                FIL_QUERYEASIZE       Return a FILEFINDBUF2 structure with
                                      the results of the search, and that
                                      contains the size of the buffer needed
                                      to retrieve the extended attributes.
 
                FIL_QUERYEASFROMLIST  Return a buffer that contains both the
                                      file information and the extended
                                      attributes for the file.
 
ulReserved      Specifies a reserved value; must be zero.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
    ERROR_BUFFER_OVERFLOW
    ERROR_EAS_DIDNT_FIT
    ERROR_EA_LIST_INCONSISTENT
    ERROR_FILENAME_EXCED_RANGE
    ERROR_INVALID_EA_NAME
    ERROR_INVALID_HANDLE
    ERROR_INVALID_PARAMETER
    ERROR_META_EXPANSION_TOO_LONG
    ERROR_NO_MORE_FILES
    ERROR_NO_MORE_SEARCH_HANDLES
    ERROR_PATH_NOT_FOUND
 
Comments
 
The DosFindNext function uses the directory handle pointed to by the phDir
parameter of the DosFindFirst2 function to repeat the search. If
DosFindFirst2 returns an error value other than ERROR_EAS_DIDNT_FIT, no
directory handle is allocated.
 
If the phDir parameter is HDIR_SYSTEM, the system-default search-directory
handle is used; any previous search that used HDIR_SYSTEM terminates if this
parameter is HDIR_CREATE, the search directory used by the process is
created, and the function copies the handle of this search directory to the
variable pointed to by the phDir parameter. If the handle was created by a
previous call to DosFindFirst, it can be used in subsequent calls to
DosFindNext.
 
If the value of the usInfoLevel parameter is FILE_QUERYEASIZE, the cbList
field of the FILEFINDBUF2 structure can be used to calculate the size of the
buffer necessary for a FILE_QUERYEASFROMLIST information request. For MS
OS/2 version 1.2, the value of cbList will never exceed 65,535.
 
To use a FILE_QUERYEASFROMLIST information request, you must supply a buffer
large enough for an EAOP structure and a FILEFINDBUF structure, plus enough
space for the extended attributes. You must initialize the first portion of
this buffer as an EAOP structure, and fill in the GEALIST structure with the
extended-attribute names to retrieve. On return, the EAOP structure will be
unchanged. It will be followed immediately by a FILEFINDBUF2 structure,
without the last three fields. This is followed by an FEALIST structure (the
address is the same as the cbList field of the FILEFINDBUF2 structure). The
FEALIST structure is in turn followed by a single byte that specifies the
length of the filename, and that is followed by a null-terminated string
that specifies the filename. For an example of how to use structure pointers
to access each of these fields, see the "Example" section.
 
If there is not enough room in the output buffer to hold the
extended-attribute information, the error ERROR_EAS_DIDNT_FIT is returned.
The search handle will be allocated, however, and can be used in subsequent
calls to the DosFindNext function. If no extended attribute is found, the
FEA structure for that extended attribute will contain the name of the
attribute, but the cbValue field will be zero.
 
Example
 
This example shows how to set up pointers to access the various fields of
the buffer returned by a FIL_QUERYEASFROMLIST level request:
 
/* Declare a structure to retrieve the .TYPE attribute name. */
 
typedef struct _TYPEATTR {
    ULONG cbList;
    BYTE  cbName;
    CHAR  szName[6];
} TYPEATTR;
 
#define BUFSIZE 2 * 1024              /* default buffer size         */
 
SEL sel;                              /* selector for buffer         */
HDIR hdir = HDIR_CREATE;              /* directory handle            */
USHORT usSearchCount = 1;             /* number of files to retrieve */
TYPEATTR typeattr;                    /* TYPE attribute structure    */
PEAOP peaop;
PFILEFINDBUF2 pfindbuf2;
PFEALIST pfeal;
PSZ pszFileName;
PUCHAR pcchFileName;
 
DosAllocSeg(BUFSIZE, &sel, SEG_NONSHARED);  /* creates buffer        */
peaop = MAKEP(sel, 0);                      /* sets up peaop pointer */
 
typeattr.cbList = sizeof(TYPEATTR);         /* structure size        */
strcpy(typeattr.szName, ".TYPE");           /* EA name               */
typeattr.cbName = sizeof(typeattr.szName) - 1; /* name length        */
 
peaop->fpGEAList = (PGEALIST) &typeattr;   /* size of GEALIST struc. */
 
if (!DosFindFirst2("eafile", &hdir, FILE_NORMAL,
        peaop, BUFSIZE,
        &usSearchCount, FIL_QUERYEASFROMLIST, 0L)) {
    pfindbuf2 = MAKEP(sel, sizeof(EAOP));   /* FILEFINDBUF structure */
    pfeal = (PFEALIST) &pfindbuf2->cbList;  /* FEALIST structure     */
    pcchFileName = ((PSZ) pfeal) + pfeal->cbList; /* filename length */
    pszFileName = pcchFileName + 1;               /* filename        */
}
 
See Also
 
DosFindClose, DosFindFirst, DosFindNext, DosQFileMode, DosQFSInfo, EAOP,
FILEFINDBUF, FILEFINDBUF2