Difference between revisions of "DosProtectQueryFHState"
(Created page with "==Description== Queries the state of the specified protected file handle. ==Syntax== <PRE> #define INCL_DOSFILEMGR #include <os2.h> HFILE hFile; /* Handle...") |
m |
||
(4 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | |||
Queries the state of the specified protected file handle. | Queries the state of the specified protected file handle. | ||
==Syntax== | ==Syntax== | ||
− | + | DosProtectQueryFHState(hFile, pMode, fhFileHandleLockID) | |
− | + | ||
− | + | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==Parameters== | ==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. | |
− | ; 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 | |
− | Possible modes include those in the following list: | + | |
− | + | ||
− | + | ||
15 OPEN_FLAGS_DASD (0x00008000) Direct Open flag: | 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) | 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) | 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) | 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. | 11-8 Reserved bits. | ||
− | |||
7 OPEN_FLAGS_NOINHERIT (0x00000080) | 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. | |
− | 6-4 | + | ::100 OPEN_SHARE_DENYNONE Deny neither read nor write access (deny none). Any other value is invalid. |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
3 Reserved. | 3 Reserved. | ||
− | |||
2-0 Access-Mode flags. File access is assigned as follows: | 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. | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | ; fhFileHandleLockID (FHLOCK) - input : The lock id of the protected file handle. | + | |
==Return Code== | ==Return Code== | ||
− | + | ulrc (APIRET) - returns | |
− | + | ||
DosProtectQueryFHState returns one of the following values: | DosProtectQueryFHState returns one of the following values: | ||
+ | *0 NO_ERROR | ||
+ | *6 ERROR_INVALID_HANDLE | ||
− | |||
− | |||
==Remarks== | ==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. | 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. | ||
Line 121: | Line 60: | ||
===Named-Pipe Considerations=== | ===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. | As defined by the operating system, D = 0. Other bits are as defined by DosCreateNPipe (serving end), DosOpen (client end), or the last DosSetFHState. | ||
Line 181: | Line 119: | ||
return NO_ERROR; | return NO_ERROR; | ||
} | } | ||
+ | </PRE> | ||
− | |||
==Related Functions== | ==Related Functions== | ||
− | * [[ | + | * [[DosDevIOCtl]] |
− | * [[ | + | * [[DosOpen]] |
− | * [[ | + | * [[DosSetFHState]] |
− | + | ||
− | [[Category: | + | [[Category:Dos]] |
Latest revision as of 21:38, 6 January 2018
Queries the state of the specified protected file handle.
Contents
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.
#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; }