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.

◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosQFHandState(hf, pfsOpenMode)
HFILE hf;               /* file handle                               */
PUSHORT pfsOpenMode;    /* pointer to variable for file-handle state */
 
The DosQFHandState function retrieves the state of the specified file
handle. The file-handle state indicates whether the file may be read from or
written to and whether it may be opened for reading or writing by other
processes.
 
The DosQFHandState function is a family API function.
 
Parameter            Description
────────────────────────────────────────────────────────────────────────────
 
hf                   Identifies the file whose file-handle state is to be
                     retrieved. This handle must have been previously
                     created by using the DosOpen function.
 
pfsOpenMode          Points to the variable that receives the file-handle
                     state. The file-handle state consists of one access
                     mode, one share mode, and optional flags. It is
                     identical to the values specified in the fsOpenMode
                     parameter of the DosOpen function. Which values are set
                     can be determined by using the AND operator to combine
                     the value returned in the pfsOpenMode parameter with
                     one or more of the following values:
 
                     Value                     Meaning
                     ───────────────────────────────────────────────────────
                     OPEN_ACCESS_READONLY      Data can be read from the
                                               file but not written to it.
 
                     OPEN_ACCESS_READWRITE     Data can be read from or
                                               written to the file.
 
                     OPEN_ACCESS_WRITEONLY     Data can be written to the
                                               file but not read from it.
 
                     OPEN_SHARE_DENYNONE       Other processes can open the
                                               file for any access:
                                               read-only, write-only, or
                                               read-write.
 
                     OPEN_SHARE_DENYREAD       Other processes can open the
                                               file for write-only access
                                               but not for read-only or
                                               read-write access.
 
                     OPEN_SHARE_DENYREADWRITE  The current process has
                                               exclusive access to the
                                               file.
 
                     OPEN_SHARE_DENYWRITE      Other processes can open the
                                               file for read-only access but
                                               not for write-only or
                                               read-write access.
 
                     OPEN_FLAGS_DASD           The file handle represents a
                                               physical drive that has been
                                               opened for direct access.
 
                     OPEN_FLAGS_FAIL_ON_ERROR  Any function that uses the
                                               file handle returns
                                               immediately with an error
                                               code if there is an I/O
                                               error.
 
                     OPEN_FLAGS_NOINHERIT      The file handle is private to
                                               the current process.
 
                     OPEN_FLAGS_WRITE_THROUGH  The system writes data to the
                                               device before the given
                                               function returns.
 
                     OPEN_FLAGS_NO_CACHE       The system does not cache
                                               file data.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be the following:
 
     ERROR_INVALID_HANDLE
 
Example
 
This example calls the DosQFHandState function by using the handle of a
previously opened file, and then checks the variable fsOpenMode and reports
whether the file is open for read/write access:
 
HFILE hf;
USHORT fsOpenMode;
    .
    .
    .
DosQFHandState(hf, &fsOpenMode);
if (fsOpenMode & OPEN_ACCESS_READWRITE)
    VioWrtTTY("File opened for read/write access\r\n", 35, 0);
if (fsOpenMode & OPEN_SHARE_DENYREADWRITE)
    VioWrtTTY("File cannot be shared\r\n", 23, 0);
 
See Also
 
DosDevIOCtl, DosExecPgm, DosOpen, DosSetFHandState
 
                                      ♦