DosProtectQueryFHState
Queries the state of the specified protected file handle.
Contents
Syntax
#define INCL_DOSFILEMGR #include <os2.h> HFILE hFile; /* Handle of the file to be queried. */ PULONG pMode; /* Pointer to the ULONG in which the content of the fsOpenMode field defined in a previous DosOpen is returned. */ FHLOCK fhFileHandleLockID; /* The lock id of the protected file handle. */ APIRET ulrc; /* Return Code. */ ulrc = DosProtectQueryFHState(hFile, pMode, fhFileHandleLockID);
Parameters
- hFile (HFILE) - input
- Handle of the file to be queried.
- pMode (PULONG) - output
- Pointer to the ULONG in which the content of the fsOpenMode field defined in a previous DosOpen is returned.
- Possible modes include those in the following list:
Bit Description 15 OPEN_FLAGS_DASD (0x00008000) Direct Open flag:
- 0 - pszFileName from a DosOpen function represents a file to be opened normally.
- 1 - pszFileName is "drive:" (such as C: or A:). It represents a mounted disk or diskette volume to be opened for direct access.
14 OPEN_FLAGS_WRITE_THROUGH (0x00004000) Write-Through flag:
- 0 Write operations to the file go through the file system buffer cache.
- 1 Write operations to the file may go through the file system buffer cache, but the sectors are 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 is set to 1 because the data must be written to the medium for synchronous write operations.
The Write-Through flag bit is not inherited by child processes.
13 OPEN_FLAGS_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 a return code.
- Media I/O errors generated through Category 08h Logical Disk Control IOCtl Commands always are reported directly to the caller by a return code. The Fail-Errors function applies only to non-IOCtl handle-based file I/O functions.
- The Fail-Errors flag bit is not inherited by child processes.
12 OPEN_FLAGS_NO_CACHE (0x00001000)
- Cache or No-Cache:
- 0 The disk driver should place data from I/O operations into the cache on this file.
- 1 I/O operations to the file need not be done through the disk-driver cache.
- The setting of this bit determines whether it is worth caching the data for file-systems drivers and device drivers. 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 OPEN_FLAGS_NOINHERIT (0x00000080)
- Inheritance flag:
- 0 The file handle is inherited by a process that is created by issuing DosExecPgm.
- 1 The file handle is private to the current process.
- This bit is not inherited by child processes.
6-4 Sharing-Mode flags: Define the operations other processes can perform on the file:
- 001 OPEN_SHARE_DENYREADWRITE Deny read and write access.
- 010 OPEN_SHARE_DENYWRITE Deny write access.
- 011 OPEN_SHARE_DENYREAD Deny read access.
- 100 OPEN_SHARE_DENYNONE Deny neither read nor write access (deny none). Any other value is invalid.
3 Reserved. 2-0 Access-Mode flags. File access is assigned as follows:
- 000 OPEN_ACCESS_READONLY Read-only access.
- 001 OPEN_ACCESS_WRITEONLY Write-only access.
- 010 OPEN_ACCESS_READWRITE Read and write access.
- Any other value is invalid.
- fhFileHandleLockID (FHLOCK) - input
- The lock id of the protected file handle.
Return Code
ulrc (APIRET) - returns
DosProtectQueryFHState returns one of the following values:
- 0 NO_ERROR
- 6 ERROR_INVALID_HANDLE
Remarks
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 function. 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 Direct 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 be used only by system programs and not by application programs.
Named-Pipe Considerations
As defined by the operating system, D = 0. Other bits are as defined by DosCreateNPipe (serving end), DosOpen (client end), or the last DosSetFHState.
Example Code
This example opens or creates and opens a file named "DOSPQFH.DAT" in protected mode, and queries the state of its handle using this API.
#define INCL_DOSFILEMGR /* File Manager values */ #define INCL_DOSERRORS /* DOS error values */ #include <os2.h> #include <stdio.h> int main(VOID) { UCHAR uchFileName[] = "DOSPQFH.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 */ FHLOCK FileHandleLock = 0; /* File handle lock */ rc = DosProtectOpen(uchFileName, &fhQryFile, &ulOpenAction, 10L, FILE_NORMAL, OPEN_ACTION_CREATE_IF_NEW | OPEN_ACTION_OPEN_IF_EXISTS, OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE, 0L, &FileHandleLock); if (rc != NO_ERROR) { printf("DosProtectOpen error: return code = %u\n", rc); return 1; } rc = DosProtectQueryFHState(fhQryFile, &FHState, FileHandleLock); if (rc != NO_ERROR) { printf("DosProtectQueryFHState 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 = DosProtectSetFHState(fhQryFile, FHState | OPEN_FLAGS_NO_CACHE, FileHandleLock); if (rc != NO_ERROR) { printf("DosProtectSetFHState error: return code = %u\n", rc); return 1; } rc = DosProtectClose(fhQryFile, FileHandleLock); /* 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); } /* endif */ return NO_ERROR; }