DosSetFHandState
Bindings: C, MASM
This call sets the state of the specified file.
DosSetFHandState (FileHandle, FileHandleState)
FileHandle (HFILE) - input
File handle to be set.
FileHandleState (USHORT) - input
Contents of the open mode word defined in a previous DosOpen or
DosOpen2 call.
Bit Description
15 Zero Bit field. This bit must be set to zero.
14 Write-Through flag:
0 = Writes to the file may be run through the system buffer
cache.
1 = Writes to the file may go through the system buffer
cache, but the data is 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 way of a return code.
Media I/O errors generated through an IOCTL category 8
function always get reported directly to the caller by way
of a return code. The Fail-Errors function applies only to
non-IOCTL handle-based type file I/O calls.
This bit is not inherited by child processes.
12 No-Cache/Cache flag. The file is opened as follows:
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 or
not. This bit, like the write-through bit, is a per-handle
bit.
This bit is not inherited by child processes.
11-8 Reserved Bits. These bits are reserved and should be set to
the values returned by DosQFHandState in these positions.
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.
6-4 Zero Bit field. These bits must be set to zero. Any other
values are invalid.
3 Reserved Bit. This bit is reserved and should be set to the
value returned by DosQFHandState for this position.
2-0 Zero Bit field. These bits must be set to zero. Any other
values are invalid.
rc (USHORT) - return
Return code descriptions are:
0 NO_ERROR
6 ERROR_INVALID_HANDLE
87 ERROR_INVALID_PARAMETER
Remarks
OS/2 does not guarantee the order that sectors are written for multiple
sector writes. If an application requires several sectors written in a
specific order, the operator should issue them as separate synchronous
write operations. Setting the write-through flag does not affect any
previous writes. That data may remain in the buffers. 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 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 file handle state bits set by this function can be queried by
DosQFHandState.
Family API Considerations
Some options operate differently in the DOS mode than in OS/2 mode.
Therefore, the following restrictions apply to DosSetFHandState when
coding for the DOS mode:
o The validity of the file handle is not checked.
o The Inheritance flag must be set equal to zero. (This flag is not
supported in DOS 2.X.)
o The Write-Through flag must be set equal to zero.
o The Fail-Errors flag must be set equal to zero.
Named Pipe Considerations
DosSetFHandState allows setting of the inheritance (I) and Write-Through
(W) bits. Setting W to 1 prevents write-behind operations on remote
pipes.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs