You can locate files with names that match a given pattern by using metacharacters in DosFindFirst and DosFindNext .

DosFindFirst searches the current directory and locates the first file name that matches the given pattern. DosFindNext locates the next matching file name and continues to find additional matches on each subsequent call until all matching names are found. The functions copy the file statistics on each file located to a data structure that you supply. The file information returned by a search includes file dates and times, length of data in the file, file size, file attributes, and file name.

To find all files that match the file specification, call DosFindNext repeatedly until the message ERROR_NO_MORE_FILES is returned. Then call DosFindClose to close the directory handle.

The following code fragment shows how to find all file names that have the extension ".C":

    #define INCL_DOSFILEMGR   /* File system values */
    #include <os2.h>

    HDIR         hdHdir;
    ULONG        ulFilenames;
    FILEFINDBUF3 ffbFindBuf;
    APIRET       ulrc;

    ulFilenames = 1;
    hdHdir = HDIR_SYSTEM;

    ulrc = DosFindFirst("*.C",
                        &hdHdir,            /* Directory handle                     */
                        FILE_NORMAL,        /* File attribute to look for           */
                        &ffbFindBuf,        /* Result buffer                        */
                        sizeof(ffbFindBuf), /* Size of result buffer                */
                        &ulFilenames,       /* Number of matching names to look for */
                        FIL_STANDARD);      /* Standard level of information        */

    if (!ulrc) {
        do {
            .
            .     /* Use file name in findbuf.achName */
            .
            ulrc = DosFindNext(hdHdir,
                               &ffbFindBuf,
                               sizeof(ffbFindBuf),
                               &ulFilenames);

        } while (!ulrc);
    }
    DosFindClose(hdHdir);

In this example, DosFindNext continues to retrieve matching file names until it returns an error value (it returns ERROR_NO_MORE_FILES when it cannot find any more matching files).

To keep track of which files have already been found, both functions use the directory handle, hdir.

This directory handle must be set to HDIR_SYSTEM or HDIR_CREATE before the call to DosFindFirst. HDIR_SYSTEM (00000001H) tells OS/2 to use the system handle for standard output, which is always available to the requesting process. HDIR_CREATE (FFFFFFFFH) tells OS/2 to allocate a new, unused handle.

The directory handle returned by DosFindFirst must be used in subsequent calls to DosFindNext ; it identifies for DosFindNext the name of the file being sought and the current position in the directory.

An attribute parameter for DosFindFirst allows hidden and system files, as well as normal files, to be included in searches.

After locating the files you need, use DosFindClose to close the directory handle. This ensures that when you search for the same files again, you will start at the beginning of the directory. After DosFindClose is called, a subsequent DosFindNext fails.