DosOpen - Parameters

pszFileName (PSZ) - input

Address of the ASCIIZ path name of the file or device to be opened.

In the Raw File System, this is the universal naming convention (UNC) name for either a logical partition or physical disk.

Logical partitions are identified using a UNC name in the form of: \\.\X:, where X is replaced with the letter corresponding to the drive.

Physical disks are identified with a UNC name in the form of: \\.\Physical_Disk#, where # is replaced with the physical disk number as reported by the FDISK utility.

pHf (PHFILE) - output

Address of the handle for the file or device.

pulAction (PULONG) - output

Address of the variable that receives the value that specifies the action taken by the DosOpen function.

If DosOpen fails, this value has no meaning. Otherwise, it is one of the following values:

• FILE_EXISTED File already existed. This is always returned on the successful open of a device.

• FILE_CREATED
  File was created.

• FILE_TRUNCATED
  File existed and was changed to a given size (file was replaced).

cbFile (ULONG) - input

New logical size of the file (end of data, EOD), in bytes.

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.

ulAttribute (ULONG) - input

File attribute information.

This parameter is significant only when manipulating a file, it is ignored on raw file system devices.

Possible values are shown in the following list.:

Bit

Description
31-6
Reserved, must be 0.
5
FILE_ARCHIVED (0x00000020) File has been archived.
4
FILE_DIRECTORY (0x00000010)
File is a subdirectory.
3
Reserved, must be 0.
2
FILE_SYSTEM (0x00000004)
File is a system file.
1
FILE_HIDDEN (0x00000002)
File is hidden and does not appear in a directory listing.
0
FILE_READONLY (0x00000001)
File can be read from, but not written to.
0
FILE_NORMAL (0x00000000)
File can be read from or written to.
File attributes apply only if the file is created.

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.

fsOpenFlags (ULONG) - input

The action to be taken depending on whether the file exists or does not exist.

This parameter is not used in the raw file system.

Possible values are shown in the following list:

Bits

Description
31-8
Reserved, must be 0.
7-4
The following flags apply if the file does not exist:

0000

OPEN_ACTION_FAIL_IF_NEW Open an existing file; fail if the file does not exist.
0001
OPEN_ACTION_CREATE_IF_NEW
Create the file if the file does not exist.
3-0
The following flags apply if the file already exists:

0000

OPEN_ACTION_FAIL_IF_EXISTS
Open the file; fail if the file already exists.
0001
OPEN_ACTION_OPEN_IF_EXISTS
Open the file if it already exists.
0010
OPEN_ACTION_REPLACE_IF_EXISTS
Replace the file if it already exists.

fsOpenMode (ULONG) - input

The mode of the open function. Possible values are shown in the following list:

Bit

Description
31-16
Reserved, must be zero.
15
OPEN_FLAGS_DASD (0x00008000) Direct Open flag:
• pszFileName represents a file to be opened normally.

• pszFileName is "drive:" (such as C: or A:), and represents a mounted disk or diskette volume to be opened for direct access.
14
OPEN_FLAGS_WRITE_THROUGH (0x00004000)
Write-Through flag:
• Writes to the file may go through the file-system driver's cache. The file-system driver writes the sectors when the cache is full or the file is closed.

• Writes to the file may go through the file-system driver's 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 must be set, because the data must be written to the medium for synchronous write operations. This bit flag is not inherited by child processes.
13
OPEN_FLAGS_FAIL_ON_ERROR (0x00002000)
Fail-Errors flag. Media I/O errors are handled as follows:
• Reported through the system critical-error handler.
  
• Reported directly to the caller by way of a return code.

  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.

12
OPEN_FLAGS_NO_CACHE (0x00001000)
No-Cache/Cache flag:
• The file-system driver should place data from I/O operations into its cache.

• I/O operations to the file need not be done through the file-system driver's cache.

  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.

11
Reserved; must be 0.
10-8
The locality of reference flags contain information about how the application is to get access to the file. The values are as follows:

000

OPEN_FLAGS_NO_LOCALITY (0x00000000)
No locality known.
001
OPEN_FLAGS_SEQUENTIAL (0x00000100)
Mainly sequential access.
010
OPEN_FLAGS_RANDOM (0x00000200)
Mainly random access.
011
OPEN_FLAGS_RANDOMSEQUENTIAL (0x00000300)
Random with some locality.
7
OPEN_FLAGS_NOINHERIT (0x00000080)
Inheritance flag:
• File handle is inherited by a process created from a call to DosExecPgm.

• File handle is private to the current process.

  This bit is not inherited by child processes.

6-4
Sharing Mode flags. This field defines any restrictions to file access placed by the caller on other processes. The values are as follows:

001

OPEN_SHARE_DENYREADWRITE (0x00000010)
Deny read/write access.
010
OPEN_SHARE_DENYWRITE (0x00000020)
Deny write access.
011
OPEN_SHARE_DENYREAD (0x00000030)
Deny read access.
100
OPEN_SHARE_DENYNONE (0x00000040)
Deny neither read nor write access (deny none).
Any other value is invalid.
3
Reserved; must be 0.
2-0
Access-Mode flags. This field defines the file access required by the caller. The values are as follows:

000

OPEN_ACCESS_READONLY (0x00000000)
Read-only access
001
OPEN_ACCESS_WRITEONLY (0x00000001)
Write-only access
010
OPEN_ACCESS_READWRITE (0x00000002)
Read/write access.
Any other value is invalid, as are any other combinations.
File Sharing

File sharing requires the cooperation of sharing processes. This cooperation is communicated through sharing and access modes. Any sharing restrictions placed on a file opened by a process are removed when the process closes the file with a DosClose request.

Sharing Mode

Specifies the type of file access that other processes may have. For example, if other processes can continue to read the file while your process is operating on it, specify Deny Write. The sharing mode prevents other processes from writing to the file but still allows them to read it.
Access Mode
Specifies the type of file access (access mode) needed by your process. For example, if your process requires read/write access, and another process has already opened the file with a sharing mode of Deny None, your DosOpen request succeeds. However, if the file is open with a sharing mode of Deny Write, the process is denied access.

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.

Raw File System

When a device is opened in the raw file system, the only valid access mode is OPEN_ACCESS_READWRITE. The valid sharing modes are:

Mode

Function
OPEN_SHARE_DENYNONE
Allows other processes to perform read and write operations to the device.
OPEN_SHARE_DENYREADWRITE
Locks device and prohibits access to device by other processes or file systems.
All other flags are either invalid or not implemented in this release of OS/2.

peaop2 (PEAOP2) - in/out

Extended attributes.

This parameter is only used to specify extended attributes (EAs) when creating a new file, replacing an existing file, or truncating an existing file. It is ignored when used on a device. When opening existing files, it should be set to null.

Input

The address of the extended-attribute buffer, which contains an EAOP2 structure. fpFEA2List points to a data area where the relevant FEA2 list is to be found. fpGEA2List and oError are ignored.
Output
fpGEA2List and fpFEA2List are unchanged. The area that fpFEA2List points to is unchanged. If an error occurred during the set, oError is the offset of the FEA2 entry where the error occurred. The return code from DosOpen is the error code for that error condition. If no error occurred, oError is undefined.

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.

ulrc (APIRET) - returns

Return Code.

DosOpen returns one of the following values:

• NO_ERROR 2
  ERROR_FILE_NOT_FOUND
  3
  ERROR_PATH_NOT_FOUND
  4
  ERROR_TOO_MANY_OPEN_FILES
  5
  ERROR_ACCESS_DENIED
  12
  ERROR_INVALID_ACCESS
  26
  ERROR_NOT_DOS_DISK
  32
  ERROR_SHARING_VIOLATION
  36
  ERROR_SHARING_BUFFER_EXCEEDED
  82
  ERROR_CANNOT_MAKE
  87
  ERROR_INVALID_PARAMETER
  99
  ERROR_DEVICE_IN_USE
  108
  ERROR_DRIVE_LOCKED
  110
  ERROR_OPEN_FAILED
  112
  ERROR_DISK_FULL
  206
  ERROR_FILENAME_EXCED_RANGE
  231
  ERROR_PIPE_BUSY
  For a full list of error codes, see Errors.

---

[Back: DosOpen Return Value - ulrc]
[Next: DosOpen - Remarks]