File I/O and Extended Attributes - part II

More on DosOpen

APIRET  DosOpen(
 PSZ      pszFileName, /* Address of the ASCIIZ path name of the file or device to be opened. */
 PHFILE   pHf,         /* Address of the handle for the file. */
 PULONG   pulAction,   /* Address of the variable that receives the value that specifies the action taken by the DosOpen function. */
 ULONG    cbFile,      /* New logical size of the file (end of data, EOD), in bytes. */
 ULONG    ulAttribute, /* File attribute information. */
 ULONG    fsOpenFlags, /* The action to be taken depending on whether the file exists or does not exist.*/
 ULONG    fsOpenMode,  /* The mode of the open function. Possible values are shown in the following list: */
 PEAOP2   peaop2);     /* Extended attributes. */

The first three arguments are clearly identified.

The action variable on output will have the following useful values:

The next three input arguments can create the most confusion.
 

ulFileAttribute	Double word containing the files attributes
ulOpenFlag	Double word containing the desired open conditions
ulOpenMode	Double word containing the mode/sharing conditions

They create confusion because the same DosOpen  call can be used to open files, disk volumes, pipes, and other devices. For example, if a user wanted to open a named pipe, some of the sharing flags and the ulFileSize value are ignored by the operating system because the pipes buffer sizes are specified by the DosCreareNPipe  API. Also, the ulFileSize may not make sense if the user is opening a disk volume for direct access. Sometimes device drivers allow DosOpen calls with a device name specified in place of the pszFileName. It is still a null-terminated string, but in the case of a device driver the string contains the device name, such as "DEVICE$". Specifying ulFileSize or other ulFileAttribute flags makes no sense, and thus some of the input parameters are ignored. All three input flag parameters are bit-encoded, meaning each bit that is set represents a new or unique flag condition. Most of the bits can be set in combination. All of the flags are 32 bits wide, but not all of the 32 bits are used at this time. Some are reserved for future use and must be set to zero. For example, the ulFileAttribute bit values are shown in Figure 4.1.

Figure 4.1 File attribute bit flags.

0 FILE_READONLY 1 FILE_HIDDEN 2 FILE_SYSTEM 3 RESERVED, must be set to ZERO 4 FILE_DIRECTORY 5  FILE_ARCHIVED

6-15 RESERVED, must be set to ZERO 16-31 RESERVED, must be set to ZERO

Table 4.4 describes the file attribute bit flags.
 

Table 4.4 File Attribute Bit Flag Descriptions

Value	Description
FILE_READONLY	File can be read but not written to
FILE_NORMAL	File can be read and written to
FILE_HIDDEN	File is a hidden file
FILE_SYSTEM	File is a system file
FILE_DIRECTORY	File is a subdirectory
FILE_ARCHIVED	File has archive bit set

To allow the file read-only access and to declare the file to be of system type, the following combination is used.

ulFileAttribute = FILE_READONLY | FILE_SYSTEM;

The ulOpenFlag describes the actions that the DosOpen   will perform based on the bit encoding specified by the programmer. These actions deal with conditions of file existence, replacement, and creation. A user may want to allow the DosOpen  API to fail, if the file already exists. If so, specify:

  ulOpenFlag = OPEN_ACTION_FAIL_IF_EXISTS;

If the user wants the DosOpen  call to open the file if it exists, and fail if it does not exist, the following  should be specified:

 ulOpenFlag = OPEN_ACTION_FAIL_IF_NEW  |
              OPEN_ACTION_OPEN_IF_EXISTS;

Table 4.5  describes the file open action flags that are available.
 

Table 4.5 File Open Action Flags

Value	Description
OPEN_ACTION_FAIL_IF_EXISTS	DosOpen will fail if the file already exists; file is created
OPEN_ACTION_OPEN_IF_EXISTS	File is opened if it already exists
OPEN_ACTION_REPLACE_IF_EXISTS	File is replaced if it already exists
OPEN_ACTION_FAIL_IF_NEW	DosOpen will fail if file does not exist; file is opened if it does exist
OPEN_ACTION_CREATE_IF_NEW	File is created if it does not exist

The ulOpenMode describes the mode that the open call will set for the file object. This flag will tell the system how to behave when other users request access to the file that is currently in use by someone else. It is here that the system write-through buffering is specified and the error reporting is decided. For example, the user may want to allow the system to use its cache to transfer the data between the application and the file object, but the actual write must complete prior to the return of the call. Also, the user may want to have all of the errors reported directly to his or her application and not through the system critical-error handle.. On top of that, a programmer may want to open this file in read-only mode and not allow anyone else write access to the file while in use. Wow! Well, for a combination of conditions like that, use the following flags:

 ulOpenFlag = OPEN_FLAGS_WRITE_THROUGH
              | OPEN_FLAGS_FAIL_ON_ERROR
              | OPEN_SHARE_DENY_WRITE
              | OPEN_ACCESS_READONLY ;