We are currently updating the IFS document, but the updates are not
complete at this time.  However, the following change is the most
requested clarification/revision that we have received.

Mary Monahan


FS_FINDFIRST
FIND FIRST MATCHING FILE NAME(S)


| Purpose

| Find first occurrence(s) of matching file name(s) in a directory.


  Calling Sequence

    int far pascal FS_FINDFIRST (pcdfsi, pcdfsd, pName, iCurDirEnd,
                                    attr, pfsfsi, pfsfsd,
                                    pData, cbData, pcMatch, level, flags)
    struct cdfsi far *    pcdfsi;
    struct cdfsd far *    pcdfsd;
    char far *             pName;
    unsigned short    iCurDirEnd;
    unsigned short          attr;
    struct fsfsi far *    pfsfsi;
    struct fsfsd far *    pfsfsd;
    char far *             pData;
    unsigned short        cbData;
    unsigned short far * pcMatch;
    unsigned short         level;
    unsigned short         flags;



  Where

  PCDFSI
  ______
     is a pointer to the file-system-independent working directory structure.

  PCDFSD
  ______
     is a pointer to the file-system-dependent working directory structure.

  PNAME
  _____
     is a pointer to the ASCIIZ name of the file or directory.

     Wildcard characters are allowed only in the last component.  The FSD does
     not need to validate this pointer.

  ICURDIREND
  __________
     is the index of the end of the current directory in pName.

|    This is provided to allow optimization of FSD path processing.  If
     iCurDirEnd == -1 there is no current directory relevant to the name text,
     that is, a device.

  ATTR
  ____
     is a bit field that governs the match.

|    Any directory entry whose attribute bit mask is a subset of attr and whose
|    name matches that in pName should be returned.  The attr field is two byte
|    sized attribute bit masks.  The least significant byte contains the "may
|    have" bits.  For example,  a "may have" attribute of system and hidden is
|    passed in.  A file with the same name and an attribute of system is found.
|    This file is returned.  A file with the same name and no attributes (a
|    regular file) is also returned.  The "may have" attributes read-only and
|    file-archive will not be passed in and should be ignored when comparing
|    directory attributes.  The most significant byte contains the "must have"
|    bits.  A file with a matching name must also have the attributes in the
|    "must have" bits to be returned.  See the OS/2 Version 3.0 Control Program
                                               ________________________________
|    Programming Reference for more information about the attribute field under
     _____________________
|    DosFindFirst.

|    The value of attr passed to the FSD will be valid.  The bit 0x0040 indi-
|    cates a non-8.3 filename format.  It should be treated the same way as
|    system and hidden attributes are.  You should not return a file name that
|    does not conform to 8.3 filename format if this bit is not set in the "may
|    have" bits.

  PFSFSI
  ______
     is a pointer to the file-system-independent file-search structure.

     The FSD should not update this structure.

  PFSFSD
  ______
     is a pointer to the file-system-dependent file-search structure.

    The FSD may use this to store information about continuation of the
    search.

 PDATA
 _____
    is the address of the application data area.

    Addressing of this data area is not validated by the kernel (see
    FSH_PROBEBUF).  The FSD will fill in this area with a set of packed,
    variable-length structures that contain the requested data and matching
    file name.

 CBDATA
 ______
    is the length of the application data area in bytes.

 PCMATCH
 _______
    is a pointer to the number of matching entries.

     The FSD returns, at most, this number of entries;  the FSD returns in this
     parameter the number of entries actually placed in the data area.

     The FSD does not need to validate this pointer.

  LEVEL
  _____
     is the information level to be returned.

|    Level selects among a series of data structures to be returned (see
|    below).  The level passed to the FSD is valid.

  FLAGS
  _____
     indicates whether to return file-position information.

|    flags == FF_NOPOS (0x00) indicates that file-position information should
|              not be returned (see below).
|    flags == FF_GETPOS (0x01) indicates that file-position information should
               be returned and the information format described below should be
               used.

     The flag passed to the FSD has a valid value.


  Remarks

  NOTE:

| The find structure passed back to the user is the structure defined for the
| 16 bit DosFindFirst API with some modification if the flags parameter is set.
| The basic, level one FILEFINDBUF structure is

|   struct FileFindBuf  {
|     unsigned short  dateCreate;
|     unsigned short  timeCreate;
|     unsigned short  dateAccess;
|     unsigned short  timeAccess;
|     unsigned short   dateWrite;
|     unsigned short   timeWrite;
|     long                 cbEOF;
|     long               cbAlloc;
|     unsigned short        attr;
|     unsigned char       cbName;
|     unsigned char     szNameY";
|   }

| For flags == 1, the FSD must store in the first DWORD of the per-file attri-
| butes structure adequate information that in addition with the file name will
| allow the search to be resumed from the file by calling FS_FINDFROMNAME.  For
| example,  an ordinal representing the file's position in the directory could
| be stored.  If the filename must be used to restart the search, the DWORD may
| be left blank.

| For level 0x0001 and flags == 1, directory information for FS_FINDFIRST is
| returned in the following format:
|   struct FileFromFindBuf  {
|     long              position;  /* position given to FSD on following */
|                                  /* FS_FINDFROMNAME call            */
|     unsigned short  dateCreate;
|     unsigned short  timeCreate;
|     unsigned short  dateAccess;
|     unsigned short  timeAccess;
|     unsigned short   dateWrite;
|     unsigned short   timeWrite;
|     long                 cbEOF;
|     long               cbAlloc;
|     unsigned short        attr;
|     unsigned char       cbName;
|     unsigned char     szNameY";
|   }

| The other information levels have similar format, with the position the first
| field in the structure for flags == 1.  For level 0x0002 and flags == 1,
| directory information for FS_FINDFIRST is returned in the following format:

|   struct FileFromFindBuf  {
|     long              position;  /* this field is not present if flags */
|                                  /* is 0                               */
|     unsigned short  dateCreate;
|     unsigned short  timeCreate;
|     unsigned short  dateAccess;
|     unsigned short  timeAccess;
|     unsigned short   dateWrite;
|     unsigned short   timeWrite;
|     long                 cbEOF;
|     long               cbAlloc;
|     unsigned short        attr;
|     unsigned long       cbList;  /* size of EAs for the file           */
|     unsigned char       cbName;
|     unsigned char     szNameY";
|   }

| For level 0x0003 and flags == 1, the directory information for FS_FINDFIRST
| is a bit more complicated.  An EAOP struction will be located at the begin-
| ning of pData.  You should start filling in the data after the EAOP struc-
| ture.  The data format is:

|   struct FileFromFindBuf  {
|     long              position;  /* this field is not present if flags */
|                                  /* is 0.                              */
|     unsigned short  dateCreate;
|     unsigned short  timeCreate;
|     unsigned short  dateAccess;
|     unsigned short  timeAccess;
|     unsigned short   dateWrite;
|     unsigned short   timeWrite;
|     long                 cbEOF;
|     long               cbAlloc;
|     unsigned short        attr;
|     FEALIST            fealist;  /* this is a variable length field    */
|     unsigned char       cbName;
|     unsigned char     szNameY";
|   }

| For a description of the FEALIST structure, see "FEAs" on page 1-10.

  If the non-8.3 filename format bit is set in the attributes of a file found
  by FS_FINDFIRST/NEXT/FROMNAME, it must be turned off in the copy of the
  attributes returned in pData.

  If FS_FINDFIRST for a particular search returns an error, an FS_FINDCLOSE for
  that search will not be issued.

  Sufficient information to find the next matching directory entry must be
  saved in the fsfsd data structure.

  In the case where directory entry information overflows the pData area, the
  FSD should be able to continue the search from the entry which caused the
  overflow on the next FS_FINDNEXT or FS_FINDFROMNAME.

  In the case of a global search in a directory, the first two entries in that
  directory as reported by the FSD should be '.' and '..' (current and the
  parent directories).

  NOTE:  The FSD will be called with the FINDFIRST/FINDFROMNAME interface when
  the 32-bit DosFindFirst/DosFindNext APIs are called.  THIS IS A CHANGE FROM
  1.X IFS interface for redirector FSDs.  The kernel will also be massaging the
  find records so that they appear the way the caller expects.  Redirectors who
  have to resume searches should take this information into account.  (i.e. You
  might want to reduce the size of the buffer sent to the server, so that the
  position fields can be added to the beginning of all the find records).

| APPLICATION NOTE:  Some applications have been coded to expect behavior
| beyond the architectural requirements.  For example, there are applications
| that require DosFindFirst to return an entry for a file that has been open-
| created, but which has never been closed.  You can debate whether a file
| truly exists until it has been closed, but unless the applications are
| changed they will still not work.  Consequently, it is recommended that FSDs
| exhibit this behavior.

