dos12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
DosOpen (1.2)
Function Group  Overview  Changes               Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosOpen(pszFileName, phf, pusAction, ulFileSize, usAttribute,
    fsOpenFlags, fsOpenMode, ulReserved)
PSZ pszFileName;       /* pointer to filename                        */
PHFILE phf;            /* pointer to variable for file handle        */
PUSHORT pusAction;     /* pointer to variable for action taken       */
ULONG ulFileSize;      /* file size if file is created or truncated  */
USHORT usAttribute;    /* file attribute                             */
USHORT fsOpenFlags;    /* action taken if file exists/does not exist */
USHORT fsOpenMode;     /* open mode of file                          */
ULONG ulReserved;      /* must be zero                               */
 
The DosOpen function opens an existing file or creates a new file. This
function returns a handle that can be used to read from and write to the
file, as well as to retrieve information about the file. The DosOpen
function can also be used to open a device or a named pipe.
 
The DosOpen function is a family API function.
 
This function is included in MS OS/2 version 1.2 for compatibility purposes
only. All new applications should use the DosOpen2 function.
 
Parameter    Description
────────────────────────────────────────────────────────────────────────────
 
pszFileName  Points to the null-terminated string that specifies the name of
             the file to be opened. The string must be a valid MS OS/2
             filename and must not contain wildcard characters.
 
phf          Points to the variable that receives the handle of the opened
             file.
 
pusAction    Points to the variable receiving 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:
 
             Value           Meaning
             ───────────────────────────────────────────────────────────────
             FILE_CREATED    File was created.
 
             FILE_EXISTED    File already existed.
 
             FILE_TRUNCATED  File existed and was truncated.
 
ulFileSize   Specifies the file's new size (in bytes). This parameter
             applies only if the file is created or truncated. The size
             specification has no effect on a file that is opened only for
             reading.
 
usAttribute  Specifies the file attributes. This parameter can be a
             combination of the following values:
 
             Value          Meaning
             ───────────────────────────────────────────────────────────────
             FILE_NORMAL    File can be read from or written to.
 
             FILE_READONLY  File can be read from, but not written to.
 
             FILE_HIDDEN    File is hidden and does not appear in a
                            directory listing.
 
             FILE_SYSTEM    File is a system file.
 
             FILE_ARCHIVED  File has been archived.
 
             File attributes apply only if the file is created.
 
fsOpenFlags  Specifies the action to take both when the file exists and when
             it does not exist. This parameter can be one of the following
             values:
 
             Value                        Meaning
             ───────────────────────────────────────────────────────────────
             FILE_CREATE                  Create a new file; fail if the
                                          file already exists.
 
             FILE_OPEN                    Open an existing file; fail if the
                                          file does not exist.
 
             FILE_OPEN | FILE_CREATE      Open an existing file, or create
                                          the file if it does not exist.
 
             FILE_TRUNCATE                Open an existing file and change
                                          to a given size.
 
             FILE_TRUNCATE | FILE_CREATE  Open an existing file and truncate
                                          it, or create the file if it does
                                          not exist.
 
fsOpenMode   Specifies the modes with which to open the file. This parameter
             consists of one access mode and one share mode. All other
             values are optional; one locality mode can be specified; and
             the other values can be given in any combination.
 
             Value                        Meaning
             ───────────────────────────────────────────────────────────────
             OPEN_ACCESS_READONLY         Data can be read from the file but
                                          not written to it.
 
             OPEN_ACCESS_READWRITE        Data can be read from or written
                                          to the file.
 
             OPEN_ACCESS_WRITEONLY        Data can be written to the file
                                          but not read from it.
 
             OPEN_SHARE_DENYNONE          Other processes can open the file
                                          for any access: read-only,
                                          write-only, or read-write.
 
             OPEN_SHARE_DENYREAD          Other processes can open the file
                                          for write-only access, but they
                                          cannot open it for read-only or
                                          read-write access.
 
             OPEN_SHARE_DENYREADWRITE     The current process has exclusive
                                          access to the file. The file
                                          cannot be opened by any process
                                          (including the current process).
 
             OPEN_SHARE_DENYWRITE         Other processes can open the file
                                          for read-only access, but they
                                          cannot open it for write-only or
                                          read-write access.
 
             OPEN_FLAGS_DASD              The file handle represents a
                                          physical drive that has been
                                          opened for direct access. (The
                                          pszFileName parameter must specify
                                          a drive name.) The DosDevIOCtl
                                          function can be used with this
                                          file handle to bypass the file
                                          system and to access the sectors
                                          of the drive directly.
 
             OPEN_FLAGS_FAIL_ON_ERROR     Any function that uses the file
                                          handle returns immediately with an
                                          error value if there is an I/O
                                          error──for example, when the drive
                                          door is open or a sector is
                                          missing. If this value is not
                                          specified, the system passes the
                                          error to the system critical-error
                                          handler, which then reports the
                                          error to the user with a
                                          hard-error pop-up message. The
                                          fail-on-error flag is not
                                          inherited by child processes. The
                                          fail-on-error flag applies to all
                                          functions that use the file
                                          handle, with the exception of the
                                          DosDevIOCtl function.
 
             OPEN_FLAGS_NOINHERIT         The file handle is not available
                                          to any child process started by
                                          the current process. If this value
                                          is not specified, any child
                                          process started by the current
                                          process can use the file handle.
 
             OPEN_FLAGS_WRITE_THROUGH     This flag applies to functions,
                                          such as DosWrite, that write data
                                          to the file. If this value is
                                          specified, the system writes data
                                          to the device before the given
                                          function returns. Otherwise, the
                                          system may store the data in an
                                          internal file buffer and write the
                                          data to the device only when the
                                          buffer is full or the file is
                                          closed.
             OPEN_FLAGS_NO_LOCALITY       There is no specific information
                                          regarding the locality of
                                          reference (the degree of
                                          randomness with which the file is
                                          accessed).
 
             OPEN_FLAGS_SEQUENTIAL        The file is accessed
                                          sequentially.
 
             OPEN_FLAGS_RANDOM            The file is accessed randomly.
 
             OPEN_FLAGS_RANDOMSEQUENTIAL  The file is accessed randomly, but
                                          there is a degree of sequential
                                          I/O within that random access. For
                                          example, this flag is specified if
                                          large blocks of data are to be
                                          read or written at random
                                          locations in the file.
 
             OPEN_FLAGS_NO_CACHE          The disk drive should not cache
                                          data in I/O operations on this
                                          file.
 
ulReserved   Specifies a reserved value; must be zero.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_ACCESS_DENIED
     ERROR_CANNOT_MAKE
     ERROR_DISK_FULL
     ERROR_DRIVE_LOCKED
     ERROR_FILE_NOT_FOUND
     ERROR_FILENAME_EXCED_RANGE
     ERROR_INVALID_ACCESS
     ERROR_INVALID_PARAMETER
     ERROR_NOT_DOS_DISK
     ERROR_OPEN_FAILED
     ERROR_PATH_NOT_FOUND
     ERROR_SHARING_BUFFER_EXCEEDED
     ERROR_SHARING_VIOLATION
     ERROR_TOO_MANY_OPEN_FILES
 
Comments
 
The ERROR_ACCESS_DENIED value is returned if you try to open a file in a
mode that is incompatible with the file's current access and sharing
modes──for example, if you attempt to open a read-only file for writing.
 
The ERROR_SHARING_VIOLATION value is returned if some other process has
opened the file with a sharing method that denies the type of access you
have requested.
 
Once the file is opened, the DosSetFHandState function can be used to change
the OPEN_FLAGS_FAIL_ON_ERROR, OPEN_FLAGS_NOINHERIT, and
OPEN_FLAGS_WRITE_THROUGH flags specified in fsOpenMode.
 
MS OS/2 does not provide a built-in method to inform a child process that it
has inherited a given file handle. The parent process must pass this
information to a child process. If the file is created without the
OPEN_FLAGS_NOINHERIT flag, and the parent process terminates without closing
the file, the file will remain open until all child processes have
terminated.
 
The DosOpen function can be used to open the client end of a named pipe and
return a handle of the pipe. The pipe must be in "listen" state for the open
operation to succeed; otherwise the open operation fails and the
ERROR_PIPE_BUSY error value is returned. Until a given instance of a named
pipe has been closed by a client, that same instance cannot be opened by
another client; however, the opening process can duplicate the open handle
as many times as required. The access and sharing modes specified when a
pipe is opened must be consistent with the modes specified in the call to
the DosMakeNmPipe function. Pipes are always opened with the pipe-specific
states set to lock, read, and write operations and are read as a byte
stream.
 
Restrictions
 
In real mode, the following restrictions apply to the DosOpen function:
 
♦  Only the access modes and the OPEN_FLAGS_DASD flag can be specified for
   the fsOpenMode parameter.
 
♦  The Category 8 functions DSK_READTRACK and DSK_WRITETRACK are not
   supported in MS-DOS versions 3.x and 4.x. You cannot use the DosOpen
   function to read or write to a track when you are running MS-DOS.
 
Example
 
This example calls the DosOpen function to create a file abc that is 100
bytes long and open it for write-only access. The fsOpenFlags parameter is
set to FILE_CREATE so that DosOpen will return an error if the file already
exists.
 
HFILE hf;
USHORT usAction;
DosOpen("abc",                      /* filename to open       */
    &hf,                            /* address of file handle */
    &usAction,                      /* action taken           */
    100L,                           /* size of new file       */
    FILE_NORMAL,                    /* file attribute         */
    FILE_CREATE,                    /* create the file        */
    OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, /* open mode */
    0L);                            /* reserved               */
 
See Also
 
DosBufReset, DosClose, DosDevIOCtl, DosOpen2, DosDupHandle, DosQFHandState,
DosQFileInfo, DosQFileMode, DosQFSInfo, DosSetFHandState, DosSetFileMode,
DosWrite