DosProtectSetFHState

Description

Sets the state of the specified protected file handle.

Syntax

#define INCL_DOSFILEMGR
#include <os2.h>

HFILE     hFile;              /* File handle to be set. */
ULONG     mode;               /* Contents of the fsOpenMode field defined 
                                 in a previous DosOpen. */
FHLOCK    fhFileHandleLockID; /* The lockid of the protected file handle. */
APIRET    ulrc;               /* Return Code. */

ulrc = DosProtectSetFHState(hFile, mode, fhFileHandleLockID);

Parameters

hFile (HFILE) - input

File handle to be set.

mode (ULONG) - input

Contents of the fsOpenMode field defined in a previous DosOpen.

Possible modes are shown in the list below:

Bit       Description
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 (0x00002000)
         Cache or No-Cache flag. The file is opened as follows:

         0   The disk driver should place data from I/O operations into cache.

         1   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 are reserved, and should be set to the values returned by DosQueryFHState in these positions.

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 is reserved, and should be set to the value returned by DosQueryFHState for this position.

2-0    These bits must be set to 0. Any other values are invalid.

fhFileHandleLockID (FHLOCK) - input

The lockid of the protected file handle.

Return Code

ulrc (APIRET) - returns

DosProtectFHState 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 DosProtectFHState 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 DosProtectFHState, 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 and sets the file handle state of a protected file named "DOSPQFH.DAT".

 #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

• DosDevIOCtl
• DosDupHandle
• DosExecPgm
• DosProtectClose
• DosProtectOpen
• DosProtectQueryFHState