en:docs:fapi:dosopen

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
en:docs:fapi:dosopen [2018/08/28 09:31] – created prokusheven:docs:fapi:dosopen [2021/09/29 10:38] (current) – prokushev
Line 1: Line 1:
-{{Legacy +{{page>en:templates:fapiint}} 
-|RepFunc=[[DosOpen]] + 
-|Remarks=This is part of the [[Family API]]. +====== DosOpen ====== 
-}}+
 This call opens a new file, an existing file, a replacement for an existing file, a named pipe, or a device. This call opens a new file, an existing file, a replacement for an existing file, a named pipe, or a device.
  
-==Syntax== +===== Syntax ===== 
- DosOpen (FileName, FileHandle, ActionTaken,+<code c> 
 +DosOpen (FileName, FileHandle, ActionTaken,
           FileSize, FileAttribute, OpenFlag, OpenMode, Reserved)           FileSize, FileAttribute, OpenFlag, OpenMode, Reserved)
 +</code>
 +
 +===== Parameters =====
 +
 +  * FileName ([[PSZ]]) - input : Address of the ASCIIZ path name of the file, named pipe, or device to be opened.
 +  * FileHandle ([[PHFILE]]) - output : Address of the handle for the file, named pipe, or device.
 +  * ActionTaken ([[PUSHORT]]) - output : Address of the action taken as a result of DosOpen.
 +
 +^ Value ^ Definition ^
 +| 0001H | File exists |
 +| 0002H | File created |
 +| 0003H | File replaced |
 +
 +  * FileSize ([[ULONG]]) - input : File's new logical size (EOD), in bytes. This parameter is significant only when creating a new file or replacing an existing file. Otherwise, it is ignored.
 +  * FileAttribute ([[USHORT]]) - input : File attribute bits. 
  
-==Parameters== 
-; FileName (PSZ) - input : Address of the ASCIIZ path name of the file, named pipe, or device to be opened. 
-; FileHandle (PHFILE) - output : Address of the handle for the file, named pipe, or device. 
-; ActionTaken (PUSHORT) - output : Address of the action taken as a result of DosOpen. 
- '''Value   Definition''' 
- 0001H    File exists 
- 0002H    File created 
- 0003H    File replaced. 
-; FileSize (ULONG) - input : File's new logical size (EOD), in bytes. This parameter is significant only when creating a new file or replacing an existing file. Otherwise, it is ignored. 
-; FileAttribute (USHORT) - input : File attribute bits.  
 Defined below: Defined below:
- '''Bit             Description''' + 
- 15-6        Reserved and must be zero. +^ Bit ^ Description ^ 
- 5            File archive +| 15-6 | Reserved and must be zero | 
- 4            Subdirectory +| 5 | File archive | 
- 3            Reserved and must be zero. +| 4 | Subdirectory | 
- 2            System file +| 3 | Reserved and must be zero | 
- 1            Hidden file +| 2 | System file | 
- 0            Read only file +| 1 | Hidden file | 
 +| 0 | Read only file |
  
 These bits may be set individually or in combination. For example, an attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only file that should be archived.  These bits may be set individually or in combination. For example, an attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only file that should be archived. 
  
-; OpenFlag (USHORT) - input : One-word field indicates the action to be taken if the file exists or does not exist.+  * OpenFlag (USHORT) - input : One-word field indicates the action to be taken if the file exists or does not exist.
  
- '''Bit       Description''' +^ Bit ^ Description ^ 
- 15-8      Reserved and must be zero. +| 15-8 | Reserved and must be zero | 
- 7-4        0000 = Fail if file does not exist. +| 7-4 | 0000 = Fail if file does not exist | 
-            0001 = Create file if file does not exist. +| ::: | 0001 = Create file if file does not exist | 
-             +| 3-0 | 0000 = Fail if the file already exists | 
- 3-0        0000 = Fail if the file already exists. +| ::: | 0001 = Open the file if it already exists | 
-            0001 = Open the file if it already exists. +| ::: | 0010 = Replace the file if it already exists |
-            0010 = Replace the file if it already exists. +
-             +
-; OpenMode (USHORT) - input :  The OpenMode parameter contains the following bit flags:+
  
- '''Bit        Description'''  +  * OpenMode ([[USHORT]]) - input :  The OpenMode parameter contains the following bit flags:
- 15         DASD Open flag: +
-             0 = FileName represents a file to be opened in the normal way. +
-             1 = FileName is "Drive:" and represents a mounted disk or diskette volume  +
-                 to be opened for direct access.  +
-                  +
- 14         Write-Through flag: +
-             0 = Writes to the file may be run through the file system buffer cache. +
-             1 = Writes to the file may go through the file system buffer cache but +
-                 the sectors are written (actual file I/O completed) before a synchronous +
-                 write call returns. This state of the file defines it as a synchronous file.  +
-                 For synchronous files, this is a mandatory bit in that the data must be  +
-                 written out to the medium for synchronous write operations. +
-  +
-            This bit is not inherited by child processes.  +
-                +
- 13         Fail-Errors flag. Media I/O errors are handled as follows: +
-             0 = Reported through the system critical error handler. +
-             1 = Reported directly to the caller by way of return code.+
  
-            Media I/O errors generated through an IOCTL Category 8 function always get  +^ Bit ^ Description ^ 
-            reported directly to the caller by way of return code. The Fail-Errors function  +| 15 | DASD Open flag: | 
-            applies only to non-IOCTL handle-based file I/O calls. +| ::: | 0 = FileName represents a file to be opened in the normal way. | 
-  +| ::: | 1 = FileName is "Drive:" and represents a mounted disk or diskette volume to be opened for direct access | 
-            This bit is not inherited by child processes.  +| 14 | Write-Through flag: | 
-                 +| ::: | 0 = Writes to the file may be run through the file system buffer cache. | 
- 12         No-Cache/Cache flag: +| ::: | 1 = Writes to the file may go through the file system buffer cache but the sectors are written (actual file I/O completed) before a synchronous | 
-             0 = It is advisable for the disk driver to cache the data in I/O operations  +| ::: | write call returns. This state of the file defines it as a synchronous file. | 
-                 on this file. +| ::: | For synchronous files, this is a mandatory bit in that the data must be written out to the medium for synchronous write operations. | 
-             1 = I/O to the file need not be done through the disk driver cache. +| ::: | This bit is not inherited by child processes. | 
-  +| 13 | Fail-Errors flag. Media I/O errors are handled as follows: | 
-            This bit advises FSDs and device drivers whether it is worth caching the data.  +| ::: | 0 = Reported through the system critical error handler. | 
-            Like the write-through bit, this is a per-handle bit and is not inherited by  +| ::: | 1 = Reported directly to the caller by way of return code. | 
-            child processes.  +| ::: | Media I/O errors generated through an IOCTL Category 8 function always get | 
-  +| ::: | reported directly to the caller by way of return code. The Fail-Errors function | 
- 11         Reserved and must be zero. +| ::: | applies only to non-IOCTL handle-based file I/O calls. | 
-  +| ::: | This bit is not inherited by child processes. | 
- 10-8 +| 12 | No-Cache/Cache flag: | 
-            The locality of reference flags contain information about how the application +| ::: | 0 = It is advisable for the disk driver to cache the data in I/O operations on this file. | 
-            is to access the file. +| ::: | 1 = I/O to the file need not be done through the disk driver cache. | 
-            Value      Definition +| ::: | This bit advises FSDs and device drivers whether it is worth caching the data. | 
-            000        No locality known.  +| ::: | Like the write-through bit, this is a per-handle bit and is not inherited by child processes. | 
-            001        Mainly sequential access.  +| 11 | Reserved and must be zero. | 
-            010        Mainly random access.  +| 10-8 |The locality of reference flags contain information about how the application is to access the file. | 
-            011        Random with some locality. +| ::: | Value   Definition | 
-  +| ::: | 000        No locality known. | 
-  7         Inheritance flag: +| ::: | 001        Mainly sequential access. | 
-             0 = File handle is inherited by a spawned process resulting from a  +| ::: | 010        Mainly random access. | 
-                 DosExecPgm call. +| ::: | 011        Random with some locality.| 
-             1 = File handle is private to the current process. +|  7  | Inheritance flag: | 
-                 This bit is not inherited by child processes.  +| ::: | 0 = File handle is inherited by a spawned process resulting from a DosExecPgm call. | 
-                +| ::: | 1 = File handle is private to the current process. | 
- 6-4        Sharing Mode flags.  +| ::: | This bit is not inherited by child processes. | 
-            This field defines any restrictions to file access placed by the caller on +| 6-4 | Sharing Mode flags. | 
-            other processes:   +| ::: | This field defines any restrictions to file access placed by the caller on other processes:  | 
-            '''Value       Definition'''  +| ::: | Value       Definition | 
-            001          Deny Read/Write access  +| ::: | 001          Deny Read/Write access | 
-            010          Deny Write access  +| ::: | 010          Deny Write access | 
-            011          Deny Read access  +| ::: | 011          Deny Read access | 
-            100          Deny neither Read or Write access (Deny None). Any other value is invalid. +| ::: | 100          Deny neither Read or Write access (Deny None). Any other value is invalid. | 
-  +|  3  | Reserved and must be zero. | 
- 3          Reserved and must be zero. +| 2-0 | Access Mode flags. This field defines file access required by the caller: | 
-  +| ::: | Value           Definition | 
- 2-0        Access Mode flags. This field defines file access required by the caller:  +| ::: | 000             Read-Only access | 
-            Value           Definition  +| ::: | 001             Write-Only access  | 
-            000             Read-Only access  +| ::: | 010             Read/Write access.  |
-            001             Write-Only access  +
-            010             Read/Write access. +
  
 Any other value is invalid.  Any other value is invalid. 
Line 119: Line 103:
 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. 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+==== Sharing Mode ==== 
                                                  
 Specify the type of access other processes may have to the file (sharing mode). For example, if it is permissible for other processes to continue reading the file while your process is operating on it, specify Deny Write. This sharing mode prevents other processes from writing to the file but still allows them to read it.  Specify the type of access other processes may have to the file (sharing mode). For example, if it is permissible for other processes to continue reading the file while your process is operating on it, specify Deny Write. This sharing mode prevents other processes from writing to the file but still allows them to read it. 
  
-;Access Mode+==== Access Mode ====
                                                  
 Specify the type of access to the file needed by your process (access mode). Specify the type of access to the file needed by your process (access mode).
Line 133: Line 118:
 If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions are also duplicated.  If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions are also duplicated. 
  
-; Reserved (ULONG) - input : Reserved and must be set to zero.+  * Reserved (ULONG) - input : Reserved and must be set to zero. 
 + 
 +===== Return Code =====
  
-==Return Code== +rc (USHORT) - return
- rc (USHORT) - return+
  
 Return code descriptions are: Return code descriptions are:
-* 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 
-* 108  ERROR_DRIVE_LOCKED 
-* 110  ERROR_OPEN_FAILED 
-* 112  ERROR_DISK_FULL 
-* 206  ERROR_FILENAME_EXCED_RANGE 
-* 231  ERROR_PIPE_BUSY 
-* 99  ERROR_DEVICE_IN_USE 
  
-==Remarks==+  * 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 
 +  * 108  ERROR_DRIVE_LOCKED 
 +  * 110  ERROR_OPEN_FAILED 
 +  * 112  ERROR_DISK_FULL 
 +  * 206  ERROR_FILENAME_EXCED_RANGE 
 +  * 231  ERROR_PIPE_BUSY 
 +  * 99  ERROR_DEVICE_IN_USE 
 + 
 +===== Remarks ===== 
 A successful DosOpen request for a file returns a handle to access the file. The read/write pointer is set at the first byte of the file. The pointer's position may be changed by a DosChgFilePtr request or by read and write operations on the file. A successful DosOpen request for a file returns a handle to access the file. The read/write pointer is set at the first byte of the file. The pointer's position may be changed by a DosChgFilePtr request or by read and write operations on the file.
  
Line 174: Line 162:
 The file handle state bits can be set by the DosOpen and DosSetFHandState requests. An application can query the file handle state bits as well as the rest of the Open Mode field, by calling DosQFHandState. If a program running with the NEWFILES bit set tries to create or replace a file with blanks immediately preceding the dot on a FAT drive, the system rejects the name. For example, if c: is a FAT drive, the name "file .txt" is rejected and the name "file.txt" is accepted. The file handle state bits can be set by the DosOpen and DosSetFHandState requests. An application can query the file handle state bits as well as the rest of the Open Mode field, by calling DosQFHandState. If a program running with the NEWFILES bit set tries to create or replace a file with blanks immediately preceding the dot on a FAT drive, the system rejects the name. For example, if c: is a FAT drive, the name "file .txt" is rejected and the name "file.txt" is accepted.
  
-===Family API Considerations===+==== Family API Considerations ==== 
 Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restrictions apply to DosOpen when coding for the DOS mode: Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restrictions apply to DosOpen when coding for the DOS mode:
  
 OpenMode restrictions: OpenMode restrictions:
-* Handles returned in response to DASD open are valid only for DosDevIOCtl. +  * Handles returned in response to DASD open are valid only for DosDevIOCtl. 
-* Inheritance flag is not supported in DOS 2.X. +  * Inheritance flag is not supported in DOS 2.X. 
-* Write-Through flag must be set to zero. +  * Write-Through flag must be set to zero. 
-* Fail-errors flag must be set to zero. +  * Fail-errors flag must be set to zero. 
-* Sharing mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not loaded. Sharing mode is not supported in DOS 2.X. +  * Sharing mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not loaded. Sharing mode is not supported in DOS 2.X. 
-* Access mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not loaded. Access mode field is not supported in DOS 2.X.  +  * Access mode field has meaning only if Sharing is loaded in DOS 3.X, ignored if Sharing is not loaded. Access mode field is not supported in DOS 2.X.  
-* Access mode is valid only if Sharing is loaded. +  * Access mode is valid only if Sharing is loaded.  
 + 
 +==== Named Pipe Considerations ==== 
  
-===Named Pipe Considerations=== 
 DosOpen opens the client end of a pipe by name and returns a handle. The open succeeds only if the pipe is in a listening state; otherwise, the open returns with ERROR_PIPE_BUSY. The pipe can be busy because of the following reasons: DosOpen opens the client end of a pipe by name and returns a handle. The open succeeds only if the pipe is in a listening state; otherwise, the open returns with ERROR_PIPE_BUSY. The pipe can be busy because of the following reasons:
 * All instances of the pipe are already open. * All instances of the pipe are already open.
Line 198: Line 189:
 The access and sharing modes specified on the open must be consistent with those specified on the DosMakeNmPipe request. The access and sharing modes specified on the open must be consistent with those specified on the DosMakeNmPipe request.
  
-==Example Code== +===== Bindings ===== 
-===C Binding=== + 
-<PRE>+==== C Binding ==== 
 + 
 +<code c>
 #define INCL_DOSFILEMGR #define INCL_DOSFILEMGR
  
Line 216: Line 209:
  
 USHORT           rc;            /* return code */ USHORT           rc;            /* return code */
-</PRE>+</code> 
 + 
 +==== MASM Binding ==== 
 + 
 +<code asm> 
 +EXTRN  DosOpen:FAR 
 +INCL_DOSFILEMGR     EQU 1 
 + 
 +PUSH@  ASCIIZ  FileName      ;File path name string 
 +PUSH@  WORD    FileHandle    ;File handle (returned) 
 +PUSH@  WORD    ActionTaken   ;Action taken (returned) 
 +PUSH   DWORD   FileSize      ;File primary allocation 
 +PUSH   WORD    FileAttribute ;File Attribute 
 +PUSH   WORD    OpenFlag      ;Open function type 
 +PUSH   WORD    OpenMode      ;Open mode of the file 
 +PUSH   DWORD   0             ;Reserved (must be zero) 
 +CALL   DosOpen 
 + 
 +Returns WORD 
 +</code> 
 + 
 +===== Example =====
  
 This example opens a file. This example opens a file.
-<PRE>+<code c>
 #define INCL_DOSFILEMGR #define INCL_DOSFILEMGR
  
Line 257: Line 271:
                 SHARE_FLAG | ACCESS_FLAG,                 SHARE_FLAG | ACCESS_FLAG,
                 RESERVED);               /* Reserved (must be zero) */                 RESERVED);               /* Reserved (must be zero) */
-</PRE> +</code>
- +
-===MASM Binding=== +
-<PRE> +
-EXTRN  DosOpen:FAR +
-INCL_DOSFILEMGR     EQU 1 +
- +
-PUSH@  ASCIIZ  FileName      ;File path name string +
-PUSH@  WORD    FileHandle    ;File handle (returned) +
-PUSH@  WORD    ActionTaken   ;Action taken (returned) +
-PUSH   DWORD   FileSize      ;File primary allocation +
-PUSH   WORD    FileAttribute ;File Attribute +
-PUSH   WORD    OpenFlag      ;Open function type +
-PUSH   WORD    OpenMode      ;Open mode of the file +
-PUSH   DWORD   0             ;Reserved (must be zero) +
-CALL   DosOpen +
- +
-Returns WORD +
-</PRE>+
  
-=== Note ===+===== Note =====
  
 Text based on [[http://www.edm2.com/index.php/DosOpen_(FAPI)]] Text based on [[http://www.edm2.com/index.php/DosOpen_(FAPI)]]