Before performing input or output operations on a file, you must open the file and obtain a file handle. You obtain a file handle by using DosOpen. This function opens the specified file and returns a file handle for it. DosOpen can also be used to create new files.
DosOpen establishes a connection betwee n a file object and an application. This connection is in the form of a 32-bit identifier called a file handle, which is used to refer to the file object and any information associated with it. DosOpen returns a handle that is used in other file system calls to gain access to the object. The file object can be a new file, an existing file, or a replacement for an existing file. It can also be a character device, a block device, or the client end of a named pipe. The type of object is determined by the file name you pass to DosOpen.
Note: If the object is a named pipe, it must be in a listening state for DosOpen to be successful.
The following code fragment shows the use of DosOpen to:
#define INCL_DOSFILEMGR /* File System values */ #include <os2.h>
HFILE hf;
ULONG ulAction;
APIRET ulrc;
ulrc = DosOpen("SAMPLE.TXT", /* Name of file to open */
&hf, /* Address of file handle */
&ulAction, /* Action taken */
0, /* Size of file */
FILE_NORMAL, /* File attribute */
FILE_OPEN, /* Open the file */
OPEN_ACCESS_READONLY |
OPEN_SHARE_DENYNONE,
(PEAOP2) NULL); /* Extended attribute buffer */
If DosOpen successfully opens the file, it copies the file handle to the hf variable and copies a value to the ulAction variable indicating what action was taken (for example, FILE_EXISTED for "existing file opened"). A file size is not needed to open an existing file, so the fourth argument is 0. The fifth argument, FILE_NORMAL, specifies the normal file attribute. The sixth argument, FILE_OPEN, directs DosOpen to open the file if it exists or return an error if it does not exist. The seventh argument directs DosOpen to open the file for reading only and enables other applications to open the file even while the current application has it open. The final argument is a pointer to a structure containing information on extended attributes. If the file has no extended attributes, this argument must be NULL.
DosOpen returns 0 if it successfully op ens the file. Applications use the file handle in subsequent functions to read data from the file or to check the status and other file characteristics. If DosOpen fails to open the file, it returns an error value.
When you open a file you must specify whether you want to read from the file, write to it, or both read and write. Also, since more than one application might attempt to open the same file, you must also specify whether you want to allow other processes to have access to the file while you have it open. A file that is shared can be shared for reading only, writing only, or reading and writing. A file that is not shared cannot be opened by another application (or more than once by the first application) until it has been closed by the first application.
An application defines its file access rights (that is, I/O it needs to perform on a file) by setting the appropriate file access mode field in the file open-mode parameter. An application accesses a file as:
An application defines what I/O operations other processes can perform on a file by setting the appropriate sharing mode field in the OpenMode parameter. Other processes are granted:
File sharing requires cooperation between the sharing processes. For example, if process A calls DosOpen to open a file with Deny Write sharing and process B calls DosOpen to open the same file with Read/Write access, the DosOpen call made by process B fails.
You indicate whether or not you want to permit another application to access your file by combining an OPEN_ACCESS_ value and an OPEN_SHARE_ value from the following list:
File Access and Sharing Rights
旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컫컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴엿Value 쿘eaning � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_ACCESS_READONLY 쿚pen a file for reading. � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_ACCESS_WRITEONLY 쿚pen a file for writing. � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_ACCESS_READWRITE 쿚pen a file for reading and � � 퀇riting. � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_SHARE_DENYREADWRITE 쿚pen a file for exclusive use,� � 쿭enying other processes read � � 쿪nd write access. � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_SHARE_DENYWRITE 쿏eny other processes write � � 쿪ccess to a file. � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_SHARE_DENYREAD 쿏eny other processes read � � 쿪ccess to a file. � 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿚PEN_SHARE_DENYNONE 쿚pen a file with no sharing � � 퀁estrictions, granting read � � 쿪nd write access to all � � 쿾rocesses. � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴�
In general, you can combine any access method (read, write, or read and write) with any sharing method (deny reading, deny writing, deny reading and writing, or grant any access). Some combinations have to be handled carefully, however, such as opening a file for writing without denying other processes access to it.
Note: For named pipes, the access and sharing modes must be consistent with those specified by DosCreateNPipe.
Other characteristics of the file handle that can be set:
File Handle Characteristics
旼컴컴컴컴컴컴컴쩡컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 쿑lag 쿛urpose � 쳐컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 쿔nheritance 쿓andle is inherited by a child� � 쿾rocess created with � � �DosExecPgm, or is private to � � 퀃he calling process. � 쳐컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 쿥rite-Through 쿌ctual I/O for synchronous � � 퀇rites is not guaranteed as � � 쿬omplete or is guaranteed as � � 쿬omplete before the write � � 퀁eturns. � 쳐컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 쿑ail-Errors 쿘edia errors are reported by � � 퀃he system critical error � � 쿴andler, or by the � � 쿪pplication. � 쳐컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 쿏ASD 쿟he file name parameter is the� � 쿻ame of a file or device � � 쿽pened in the normal way, or a� � 쿭rive specification for a � � 쿯ixed disk or diskette drive. � � 쿟he DASD flag can be set for � � 쿭irect access to an entire � � 쿭isk or diskette volume, � � 쿶ndependent of the file � � 퀂ystem. When the DASD flag is � � 퀂et, the handle returned by � � �DosOpen represents the logical� � 퀆olume as a single file. To � � 쿫lock other processes from � � 쿪ccessing the logical volume, � � 쿪 DosDevIOCtl Category 8, � � 쿑unction 0 call should be made� � 퀅sing the handle returned by � � 쿏osOpen. The DASD flag should � � 쿫e set only by systems � � 쿾rograms, not by applications.� 쳐컴컴컴컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 쿎ache 쿟he file system caches or does� � 쿻ot cache data for I/O � � 쿽perations on the file. This � � 쿯lag is advisory only. � 읕컴컴컴컴컴컴컴좔컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸
See the DosOpen material in the Control Program Programming Reference for details of these characteristics.
After an object has been opened, its file handle state flags can be queried by calling DosQueryFHState and reset by calling DosSetFHState. See Determining and Setting the State of a File or Device Handle for information on determining the state of a file handle.
When a child process inherits a file handle, it also inherits the sharing and access rights of the file.
You cannot use metacharacters (global file name characters; * and ?) in file names you supply to DosOpen.