DosQFHandState
 Legacy Function Warning
| |
|---|---|
| It is recommended to use a newer replacement for this function. | |
| Replacement: | N/A |
| Remarks: | |
This call queries the state of the specified file.
Determines whether the handle can be inherited and if write-behind is allowed.
Syntax
DosQFHandState (FileHandle, FileHandleState)
Parameters
- FileHandle (HFILE) - input
- Handle of the file to be queried.
- FileHandleState (PUSHORT) - output
- Address of the contents of the open mode word defined in a previous DosOpen or DosOpen2 call.
- 15 - Direct Open flag:
- 0 = PathName represents a file to be opened in the normal way.
- 1 = PathName is "Drive:" and represents a mounted disk or diskette volume to be opened for direct access.
- 14 - Write-Through flag:
- 0 = Writes to the file may be run through the file system buffer cache.
- 1 = Writes to the file may go through the file system buffer cache but the sectors are written (actual file I/O completed) before a synchronous write call returns. This state of the file defines it as a synchronous file. For synchronous files, this is a mandatory bit in that the data must be written out to the medium for synchronous write operations.
- This bit is not inherited by child processes.
- 13 - Fail-Errors flag. Media I/O errors are handled as follows:
- 0 = Reported through the system critical error handler.
- 1 = Reported directly to the caller by return code.
- Media I/O errors generated through an IOCTL Category 8 function always get reported directly to the caller by return code. The Fail-Errors function applies only to non-IOCTL handle-based file I/O calls.
- This bit is not inherited by child processes.
- 12 - No-Cache/Cache:
- 0 = It is advisable for the disk driver to cache the data in I/O operations on this file.
- 1 = I/O to the file need not be done through the disk driver cache.
- This bit is an advisory bit, and is used to advise FSDs and device drivers on whether it is worth caching the data. This bit, like the write-through bit, is a per-handle bit.
- This bit is not inherited by child processes.
- 11-8 - Reserved Bits.
- 7 - Inheritance flag:
- 0 = File handle is inherited by a spawned process resulting from a DosExecPgm call.
- 1 = File handle is private to the current process.
- This bit is not inherited by child processes.
- 6-4 - Sharing Mode flags: The file sharing mode flags define what operations other processes may perform on the file shown as follows:
- 001 - Deny Read/Write access
- 010 -Deny Write access
- 011 - Deny Read access
- 100 - Deny neither Read or Write access (Deny None).
- Any other value is invalid.
- 3 - Reserved Bit.
- 2-0 - Access Mode flags. The file access is assigned as follows:
- 000 - Read-Only access
- 001 - Write-Only access
- 010 - Read/Write access.
- Any other value is invalid.
Return Code
rc (USHORT) - return
Return code descriptions are:
- 0 NO_ERROR
- 6 ERROR_INVALID_HANDLE
Remarks
When a critical error occurs that the application cannot handle, it may reset critical error handling to be performed by the system. This is done by calling DosSetFHandState to turn off the fail/errors bit and then reissuing the I/O call. The expected critical error reoccurs, and control is passed to the system critical error handler. The precise time that the effect of this function is visible at the application level is unpredictable when asynchronous I/O is pending.
The DASD Open bit parameter is the "Direct I/O flag." It provides an access mechanism to a disk or diskette volume independent of the file system. This mode should only be used by systems programs and not by application programs.
Named Pipe Considerations
As defined by OS/2 D = 0. Other bits as defined by DosMakeNmPipe (serving end), DosOpen (client end), or the last DosSetFHandState.
Example Code
C Binding
#define INCL_DOSFILEMGR USHORT rc = DosQFHandState(FileHandle, FileHandleState); HFILE FileHandle; /* File handle */ PUSHORT FileHandleState; /* File handle state (returned) */ USHORT rc; /* return code */
MASM Binding
EXTRN DosQFHandState:FAR INCL_DOSFILEMGR EQU 1 PUSH WORD FileHandle ;File handle PUSH@ WORD FileHandleState ;File handle state (returned) CALL DosQFHandState Returns WORD