DosProtectQueryFHState

From EDM2
Revision as of 13:11, 19 June 2016 by Martini (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Description

Queries the state of the specified protected file handle.

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

Related Functions