DosQueryFHState

Queries the state of the specified file handle.

Syntax

#define INCL_DOSFILEMGR
#include <os2.h>

HFILE   hFile;  /* Handle of the file to be queried. */
PULONG  pMode;  /* Address of the contents of the open-mode word defined in
                   a previous DosOpen function. */
APIRET  ulrc;   /* Return Code. */

ulrc = DosQueryFHState(hFile, pMode);

Parameters

hFile (HFILE) - input

Handle of the file to be queried.

pMode (PULONG) - output

Address of the contents of the open-mode word defined in a previous DosOpen function.

15 OPEN_FLAGS_DASD (0x00008000) Direct Open flag:

0 - pszFileName field in DosOpen represents a file to be opened normally.

1 - pszFileName is the "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.

Return Code

ulrc (APIRET) - returns

DosQueryFHState 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 (OPEN_FLAGS_DASD) 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 queries and sets the handle state of the file "DOSQFH.DAT", and then displays it.

 #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;
}

Related Functions

• DosDevIOCtl
• DosOpen
• DosSetFHState