Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revision | |||
en:docs:fapi:dossetfhandstate [2021/08/20 07:27] – prokushev | en:docs:fapi:dossetfhandstate [2021/09/18 14:53] (current) – prokushev | ||
---|---|---|---|
Line 1: | Line 1: | ||
{{page> | {{page> | ||
+ | ====== DosSetFHandState ====== | ||
This call sets the state of the specified file. | This call sets the state of the specified file. | ||
Line 6: | Line 7: | ||
Specifies whether a handle of a named pipe can be inherited, and write-behind is allowed. | Specifies whether a handle of a named pipe can be inherited, and write-behind is allowed. | ||
- | ==Syntax== | + | ===== Syntax |
- | | + | <code c> |
+ | DosSetFHandState (FileHandle, | ||
+ | </ | ||
- | ==Parameters== | + | ===== Parameters |
- | ;FileHandle (HFILE) - input : File handle to be set. | + | |
- | ; | + | |
- | :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/ | + | |
- | ::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. | + | |
- | ==Return Code== | + | * FileHandle ([[HFILE]]) - input : File handle to be set. |
- | ;rc (USHORT) - return: | + | * FileHandleState ([[USHORT]]) - input : Contents of the open mode word defined in a previous [[DosOpen]] or [[DosOpen2]] call. |
- | * 0 NO_ERROR | + | *15 - Zero Bit field. This bit must be set to zero. |
- | * 6 ERROR_INVALID_HANDLE | + | *14 - Write-Through flag: |
- | * 87 ERROR_INVALID_PARAMETER | + | *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/ | ||
+ | *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. | ||
+ | |||
+ | ===== Return Code ===== | ||
+ | |||
+ | rc ([[USHORT]]) - return: | ||
+ | |||
+ | | ||
+ | * 6 ERROR_INVALID_HANDLE | ||
+ | * 87 ERROR_INVALID_PARAMETER | ||
+ | |||
+ | ===== Remarks ===== | ||
- | ==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 '' | 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 '' | ||
The file handle state bits set by this function can be queried by [[DosQFHandState]]. | The file handle state bits set by this function can be queried by [[DosQFHandState]]. | ||
- | ===Family API Considerations=== | + | ==== 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: | 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: | ||
- | * The validity of the file handle is not checked. | + | |
- | * The Inheritance flag must be set equal to zero. (This flag is not supported in DOS 2.X.) | + | * The Inheritance flag must be set equal to zero. (This flag is not supported in DOS 2.X.) |
- | * The Write-Through flag must be set equal to zero. | + | * The Write-Through flag must be set equal to zero. |
- | * The Fail-Errors flag must be set equal to zero. | + | * The Fail-Errors flag must be set equal to zero. |
- | ===Named Pipe Considerations=== | + | ==== 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. | DosSetFHandState allows setting of the inheritance (I) and Write-Through (W) bits. Setting W to 1 prevents write-behind operations on remote pipes. | ||
- | ==Bindings== | + | ===== Bindings ===== |
- | ===C=== | + | |
- | <PRE> | + | ==== C ==== |
+ | |||
+ | <code c> | ||
#define INCL_DOSFILEMGR | #define INCL_DOSFILEMGR | ||
Line 65: | Line 76: | ||
USHORT | USHORT | ||
USHORT | USHORT | ||
- | </PRE> | + | </code> |
+ | |||
+ | ==== MASM ==== | ||
- | ===MASM=== | + | <code asm> |
- | <PRE> | + | |
EXTRN DosSetFHandState: | EXTRN DosSetFHandState: | ||
INCL_DOSFILEMGR | INCL_DOSFILEMGR | ||
Line 77: | Line 89: | ||
Returns WORD | Returns WORD | ||
- | </PRE> | + | </code> |
{{page> | {{page> |