Purpose
DosProtectOpenL opens a new file, an existing file, or a replacement for an existing file and returns a protected file handle. An open file can have extended attributes.
Syntax
#define INCL DOSFILEMGR #include os2.h
APIRET DosProtectOpenL
Parameters
pszFileName PSZ) input
If DosProtectOpenL fails, this value has no meaning. Otherwise, it is one of the following values
File already existed.
File was created.
File existed and was changed to a given size (file was replaced).
This parameter is significant only when creating a new file or replacing an existing one. Otherwise, it is ignored. It is an error to create or replace a file with a nonzero length if the fsOpenMode Access-Mode flag is set to read-only.
This parameter contains the following bit fields
Bits
File has been archived.
File is a subdirectory.
File is a system file.
File is hidden and does not appear in a directory listing.
File can be read from, but not written to.
File can be read from or written to.
These bits may be set individually or in combination. For example, an attribute value of 0x00000021 (bits 5 and 0 set to 1) indicates a read-only file that has been archived.
This parameter contains the following bit fields
Bits
0000
Open an existing file; fail if the file does not exist.
Create the file if the file does not exist.
0000
Open the file; fail if the file already exists.
Open the file if it already exists.
Replace the file if it already exists.
This parameter contains the following bit fields
Bits
Protected file handle flag.
Protected handle requires the pfhFileHandleLockID to be specified on subsequent DosProtectxxxx calls.
Unprotected handle requires the pfhFileHandleLockID value to be specified as zero on subsequent DosProtectxxxx calls. An unprotected handle may be used with the unprotected calls such as DosRead and DosWrite.
Direct Open flag
Write-Through flag
This bit flag is not inherited by child processes.
Fail-Errors flag. Media I O errors are handled as follows
Media I/O errors generated through Category 08h Logical Disk Control IOCtl Commands always get reported directly to the caller by way of return code. The Fail-Errors function applies only to non-IOCtl handle-based file I/O calls.
This flag bit is not inherited by child processes.
No-Cache/Cache flag
The setting of this bit determines whether file-system drivers should place data into the cache. Like the write-through bit, this is a per-handle bit, and is not inherited by child processes.
000
No locality known.
Mainly sequential access.
Mainly random access.
Random with some locality.
Inheritance flag
This bit is not inherited by child processes.
001
Deny read write access.
Deny write access.
Deny read access.
Deny neither read nor write access (deny none).
Deny read/write access by the DosOpen command
A file opened by DosOpenL will not be allowed to grow larger than 2GB while that same file is open via a legacy DosOpen call. Setting this bit to 1 will prevent access by the obsolete DosOpen API and ensure that no error will occur when growing the file.
Any other value is invalid.
000
Read-only access
Write-only access
Read/write access.
Any other value is invalid, as are any other combinations.
Sharing Mode
If the file is inherited by a child process, all sharing and access restrictions also are inherited.
If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions also are duplicated.
Input
If peaop2 is zero, then no extended attributes are defined for the file. If extended attributes are not to be defined or modified, the pointer peaop2 must be set to zero.
Returns
ulrc APIRET) returns
DosProtectOpenL returns one of the following values
12
Remarks
A successful DosProtectOpenL request returns a handle and a 32-bit lockid for accessing the file. The read/write pointer is set at the first byte of the file. The position of the pointer can be changed with DosProtectSetFilePtrL or by read and write operations on the file.
The file s date and time can be queried with DosProtectQueryFileInfo. They are set with DosProtectSetFileInfo.
The read-only attribute of a file can be set with the ATTRIB command.
ulAttribute cannot be set to Volume Label. To set volume-label information, issue DosProtectSetFileInfo with a logical drive number. Volume labels cannot be opened.
cbFile affects the size of the file only when the file is new or is a replacement. If an existing file is opened, cbFile is ignored. To change the size of the existing file, issue DosProtectSetFileSizeL.
The value in cbFile is a recommended size. If the full size cannot be allocated, the open request may still succeed. The file system makes a reasonable attempt to allocate the new size in an area that is as nearly contiguous as possible on the medium. When the file size is extended, the values of the new bytes are undefined.
The Direct Open bit provides direct access to an entire disk or diskette volume, independent of the file system. This mode of opening the volume that is currently on the drive returns a handle to the calling function; the handle represents the logical volume as a single file. The calling function specifies this handle with a DosDevIOCtl Category 8, DSK_LOCKDRIVE request to prevent other processes from accessing the logical volume. When you are finished using the logical volume, issue a DosDevIOCtl Category 8, DSK_UNLOCKDRIVE request to allow other processes to access the logical volume.
The file-handle state bits can be set by DosProtectOpenL and DosProtectSetFHState. An application can query the file-handle state bits, as well as the rest of the Open Mode field, by issuing DosProtectQueryFHState.
You can use an EAOP2 structure to set extended attributes in peaop2 when creating a file, replacing an existing file, or truncating an existing file. No extended attributes are set when an existing file is just opened.
A replacement operation is logically equivalent to atomically deleting and re-creating the file. This means that any extended attributes associated with the file also are deleted before the file is re-created.
The pfhFileHandleLockID returned is required on each of the DosProtectxxx functions. An incorrect pfhFileHandleLockID on subsequent DosProtectxxx calls results in an ERROR_ACCESS_DENIED return code.
The DosProtectxxx functions can be used with a NULL filehandle lockid, if the subject filehandle was obtained from DosOpen.
Related Functions
Example Code
This example opens or creates and opens a file named DOSPROT.DAT , writes to it, reads from it, and finally closes it using DosProtect functions.
#define INCL_DOSFILEMGR /* File Manager values */#define INCL_DOSERRORS /* DOS Error values */
#include os2.h
#include stdio.h
#include string.h
int main(VOID)
HFILE hfFileHandle = 0L;
ULONG ulAction = 0;
ULONG ulBytesRead = 0;
ULONG ulWrote = 0;
LONGLONG ullLocal = 0;
UCHAR uchFileName 20 = "dosprot.dat",
uchFileData 100 = " ";
FHLOCK FileHandleLock = 0; /* File handle lock */
APIRET rc = NO_ERROR; /* Return code */
/* Open the file dosprot.dat. Make it read/write, open it */
/* if it already exists and create it if it is new. */
rc = DosProtectOpenL(uchFileName, /* File path name */
hfFileHandle, /* File handle */
ulAction, /* Action taken */
(LONGLONG)100, /* File primary allocation */
FILE_ARCHIVED | FILE_NORMAL, /* File attribute */
OPEN_ACTION_CREATE_IF_NEW |
OPEN_ACTION_OPEN_IF_EXISTS, /* Open function type */
OPEN_FLAGS_NOINHERIT |
OPEN_SHARE_DENYNONE |
OPEN_ACCESS_READWRITE, /* Open mode of the file */
0L, /* No extended attribute */
FileHandleLock); /* File handle lock id */
if (rc != NO_ERROR)
printf("DosProtectOpenL error return code = %u\n", rc);
return 1;
else
printf ("DosProtectOpenL Action taken = %u\n", ulAction);
/* endif */
/* Write a string to the file */
strcpy (uchFileData, "testing...\n3...\n2...\n1\n");
rc = DosProtectWrite (hfFileHandle, /* File handle */
(PVOID) uchFileData, /* String to be written */
sizeof (uchFileData), /* Size of string to be written */
ulWrote, /* Bytes actually written */
FileHandleLock); /* File handle lock id */if (rc != NO_ERROR)
printf("DosProtectWrite error return code = %u\n", rc);
return 1;
else
printf ("DosProtectWrite Bytes written = %u\n", ulWrote);
/* endif */
/* Move the file pointer back to the beginning of the file */
rc = DosProtectSetFilePtrL (hfFileHandle, /* File Handle */
(LONGLONG)0, /* Offset */
FILE_BEGIN, /* Move from BOF */
ullLocal, /* New location address */
FileHandleLock); /* File handle lock id */
if (rc != NO_ERROR)
printf("DosSetFilePtrL error return code = %u\n", rc);
return 1;
/* Read the first 100 bytes of the file */
rc = DosProtectRead (hfFileHandle, /* File Handle */
uchFileData, /* String to be read */
100L, /* Length of string to be read */
ulBytesRead, /* Bytes actually read */
FileHandleLock); /* File handle lock id */
if (rc != NO_ERROR)
printf("DosProtectRead error return code = %u\n", rc);
return 1;
else
printf("DosProtectRead Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
/* endif */
rc = DosProtectClose(hfFileHandle, FileHandleLock); /* Close the file */
if (rc != NO_ERROR)
printf("DosProtectClose error return code = %u\n", rc);
return 1;
return NO_ERROR;