DosProtectQueryFHState

Queries the state of the specified protected file handle.

Syntax
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. 
 * 1) define INCL_DOSFILEMGR  /* File Manager values */
 * 2) define INCL_DOSERRORS   /* DOS error values    */
 * 3) include 
 * 4) include 

int main(VOID) {

UCHAR      uchFileName[]   = "DOSPQFH.DAT";   /* File to manipulate        */ HFILE      fhQryFile       = 0;               /* File handle from DosOpen  */ FILESTATUS3 fsts3FileInfo  = ;  /* 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; } 

Related Functions

 * DosDevIOCtl
 * DosOpen
 * DosSetFHState