DosOpen
Description
Opens a new file, an existing file, or a replacement for an existing file. An open file can have extended attributes.
Syntax
#define INCL_DOSFILEMGR
#include <os2.h>
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. */
APIRET ulrc; /* Return Code. */
ulrc = DosOpen(pszFileName, pHf, pulAction, cbFile,
ulAttribute, fsOpenFlags, fsOpenMode, peaop2);
Parameters
- pszFileName (PSZ) - input
- Address of the ASCIIZ path name of the file or device to be opened.
- pHf (PHFILE) - output
- Address of the handle for the file. A file handle of zero is valid.
- 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:
- 1 - FILE_EXISTED
- File already existed.
- 2 - FILE_CREATED
- File was created.
- 3 - FILE_TRUNCATED
- File existed and was changed to a given size (file was replaced).
- 1 - FILE_EXISTED
- 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.
- Possible values are shown in the following list:
- 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.
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:
0 pszFileName represents a file to be opened normally.
1 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:
0 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.
1 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:
0 The file-system driver should place data from I/O operations into its cache.
1 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:
0 File handle is inherited by a process created from a call to DosExecPgm.
1 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 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.
- 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. 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.
Return Code
ulrc (APIRET) - returns
DosOpen returns one of the following values:
- 0 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
Remarks
A successful DosOpen request returns a handle for accessing the file. A file handle of zero is valid. The read/write pointer is set at the first byte of the file. The position of the pointer can be changed with DosSetFilePtr or by read and write operations on the file.
The file's date and time can be queried with DosQueryFileInfo. They are set with DosSetFileInfo.
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 DosSetFSInfo with a logical drive number. Volume labels cannot be opened.
cbFile affects the size of the file only when the file is new or a is replacement. If an existing file is opened, cbFile is ignored. To change the size of the existing file, issue DosSetFileSize.
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 DosOpen and DosSetFHState. An application can query the file-handle state bits, as well as the rest of the Open Mode field, by issuing DosQueryFHState.
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.
Example Code
This example opens or creates and opens a normal file named "DOSTEST.DAT", writes to it, reads from it, and finally closes it.
#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; /* Handle for file being manipulated */
ULONG ulAction = 0; /* Action taken by DosOpen */
ULONG ulBytesRead = 0; /* Number of bytes read by DosRead */
ULONG ulWrote = 0; /* Number of bytes written by DosWrite */
ULONG ulLocal = 0; /* File pointer position after DosSetFilePtr */
UCHAR uchFileName[20] = "dostest.dat", /* Name of file */
uchFileData[100] = " "; /* Data to write to file */
APIRET rc = NO_ERROR; /* Return code */
/* Open the file test.dat. Use an existing file or create a new */
/* one if it doesn't exist. */
rc = DosOpen(uchFileName, /* File path name */
&hfFileHandle, /* File handle */
&ulAction, /* Action taken */
100L, /* 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 */
if (rc != NO_ERROR) {
printf("DosOpen error: return code = %u\n", rc);
return 1;
} else {
printf ("DosOpen: Action taken = %ld\n", ulAction);
} /* endif */
/* Write a string to the file */
strcpy (uchFileData, "testing...\n1...\n2...\n3\n");
rc = DosWrite (hfFileHandle, /* File handle */
(PVOID) uchFileData, /* String to be written */
sizeof (uchFileData), /* Size of string to be written */
&ulWrote); /* Bytes actually written */
if (rc != NO_ERROR) {
printf("DosWrite error: return code = %u\n", rc);
return 1;
} else {
printf ("DosWrite: Bytes written = %u\n", ulWrote);
} /* endif */
/* Move the file pointer back to the beginning of the file */
rc = DosSetFilePtr (hfFileHandle, /* File Handle */
0L, /* Offset */
FILE_BEGIN, /* Move from BOF */
&ulLocal); /* New location address */
if (rc != NO_ERROR) {
printf("DosSetFilePtr error: return code = %u\n", rc);
return 1;
}
/* Read the first 100 bytes of the file */
rc = DosRead (hfFileHandle, /* File Handle */
uchFileData, /* String to be read */
100L, /* Length of string to be read */
&ulBytesRead); /* Bytes actually read */
if (rc != NO_ERROR) {
printf("DosRead error: return code = %u\n", rc);
return 1;
} else {
printf ("DosRead: Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
} /* endif */
rc = DosClose(hfFileHandle); /* Close the file */
if (rc != NO_ERROR) {
printf("DosClose error: return code = %u\n", rc);
return 1;
}
return NO_ERROR;
}
The following example shows how to open a communications port:
#define INCL_DOSFILEMGR /* File Manager values */
#define INCL_DOSERRORS /* DOS Error values */
#define INCL_DOSPROCESS /* DOS Process values */
#define INCL_DOSMISC /* DOS Miscellanous values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
int main(void) {
PSZ pszCommPort = "COM1"; /* Port name, could use "\\DEV\COM1" */
HFILE hPort = NULLHANDLE; /* Handle for accessing port */
ULONG ulAction = 0L; /* DosOpen action */
ULONG ulWrote = 0; /* Number of bytes written to port */
UCHAR uchPortData[100] = " "; /* Data to write to port */
APIRET rc = NO_ERROR; /* Return code */
DosError( FERR_DISABLEHARDERR); /* Disable hard error pop-up messages */
rc = DosOpen( pszCommPort, /* Communications port to open */
&hPort,
&ulAction, /* Returns action taken by DosOpen */
0L, /* Not needed for byte stream devices */
FILE_NORMAL,
OPEN_ACTION_OPEN_IF_EXISTS,
OPEN_ACCESS_READWRITE |
OPEN_FLAGS_NOINHERIT |
OPEN_SHARE_DENYREADWRITE , /* Prevents us from opening port */
/* if another application is using it */
/* and prevents other applications */
/* from using port while we have it */
0L); /* No extended attributes */
DosError( FERR_ENABLEHARDERR); /* Re-enable hard error pop-ups */
if (rc != NO_ERROR) {
printf("DosOpen error: return code = %u\n", rc);
return 1;
} else {
printf ("DosOpen: Action taken = %ld\n", ulAction);
} /* endif */