DosSetFHState
Sets the state of the specified file handle.
Syntax
DosSetFHState(hFile, mode)
Parameters
- hFile (HFILE) - input
- File handle to be set.
- mode (ULONG) - input
- Contents of the fsOpenMode field defined in a previous DosOpen function.
- This parameter contains the following bit fields:
- 15 - OPEN_FLAGS_DASD (0x00008000) This bit must be set to 0.
- 14 - OPEN_FLAGS_WRITE_THROUGH (0x00004000) Write-Through flag:
- 0 Writes to the file may go through the system-buffer cache.
- 1 Writes to the file may go through the system-buffer cache, but the data is written (the actual file I/O operation is completed) before a synchronous-write call returns. This state of the file defines it as a synchronous file. For synchronous files, this bit must be set, because the data must be written to the medium for synchronous-write operations.
- This flag bit is not inherited by child processes.
- 13 - OPEN_FAIL_ON_ERROR (0x00002000) 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 Category 08h Logical Disk Control IOCtl Commands are always reported directly to the caller by way of a return code. The Fail-Errors function applies only to non-IOCtl handle-based file I/O functions.
- This flag bit is not inherited by child processes.
- 12 - OPEN_FLAGS_NO_CACHE (x00002000) Cache or No-Cache flag. The file is opened as follows:
- The disk driver should place data from I/O operations into cache.
- I/O operations to the file need not be done through the disk-driver cache.
- This bit is an advisory bit, and is used to advise file-system drivers and device drivers about whether the data should be cached. This bit, like the write-through bit, is a per-handle bit.
- This bit is not inherited by child processes.
- 11-8 - These bits must be set to 0.
- 7 - OPEN_FLAGS_NOINHERIT (0x00000080) Inheritance flag:
- 0 File handle is inherited by a process created by DosExecPgm.
- 1 File handle is private to the current process.
- 6-4 - These bits must be set to 0. Any other values are invalid.
- 3 - This bit must be set to 0.
- 2-0 - These bits must be set to 0. Any other values are invalid.
Return Code
- ulrc (APIRET) - returns
- DosSetFHState returns one of the following values:
- 0 NO_ERROR
- 6 ERROR_INVALID_HANDLE
- 87 ERROR_INVALID_PARAMETER
Remarks
The operating system does not guarantee the write order for multiple-sector write operations. If an application requires several sectors to be written in a specific order, the operator should issue the sectors as separate synchronous-write operations. Setting the Write-Through flag does not affect any previous write operation. That data can remain in the buffers.
When the application cannot handle a critical error that occurs, critical-error handling can be reset to the system. This is done by having DosSetFHState turn off the fail/errors bit, and then reissuing the I/O operation. The expected critical error recurs, 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 operations are pending.
The file-handle-state bits set by this function can be queried by DosQueryFHState.
Named-Pipe Considerations
With DosSetFHState, the inheritance (I) bit and Write-Through (W) bit can be set or reset. Setting W to 1 prevents write-behind operations on remote pipes.
Example Code
This example queries the file handle state of the file "DOSQFH.DAT".
#define INCL_DOSFILEMGR /* File Manager values */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
int main(VOID) {
UCHAR uchFileName[] = "DOSQFH.DAT"; /* File to manipulate */
HFILE fhQryFile = 0; /* File handle from DosOpen */
FILESTATUS3 fsts3FileInfo = {{0}}; /* Information associated with file */
ULONG ulOpenAction = 0; /* Action taken by DosOpen */
ULONG FHState = 0; /* File Handle State */
APIRET rc = NO_ERROR; /* Return code */
/* Create a file */
rc = DosOpen(uchFileName, &fhQryFile,
&ulOpenAction, 10L, FILE_NORMAL,
OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS,
OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L);
if (rc != NO_ERROR) {
printf("DosOpen error: return code = %u\n", rc);
return 1;
}
rc = DosQueryFHState(fhQryFile, &FHState);
if (rc != NO_ERROR) {
printf("DosQueryFHState error: return code = %u\n", rc);
return 1;
} else printf("FHState is: %x\n", FHState);
/* Change state to indicate that data should not be cached */
FHState &= 0x7F88; /* Turn off non-participating bits */
rc = DosSetFHState(fhQryFile, FHState | OPEN_FLAGS_NO_CACHE);
if (rc != NO_ERROR) {
printf("DosSetFHState error: return code = %u\n", rc);
return 1;
}
rc = DosClose(fhQryFile);
/* Should check if (rc != NO_ERROR) here... */
rc = DosDelete(uchFileName); /* Delete the file */
if (rc != NO_ERROR) {
printf("DosDelete error: return code = %u\n", rc);
return 1;
} else {
printf("File %s has been deleted.\n",uchFileName);
}
return NO_ERROR;
}