Interrupt 21h Function 716Ch

Creates or opens a file.

mov ax, 716Ch          ; Create or Open File
mov bx, ModeAndFlags   ; see below
mov cx, Attributes     ; see below
mov dx, Action         ; see below
mov si, seg Filename   ; see below
mov ds, si
mov si, offset Filename
mov di, AliasHint      ; see below
int 21h

jc error
mov [Handle], ax       ; file handle
mov [ActionTaken], cx  ; action taken to open file

Parameters

ModeAndFlags
Combination of access mode, sharing mode, and open flags. This parameter can be one value each from the access and sharing modes and any combination of open flags:
Access mode Meaning
OPEN_ACCESS_READONLY (0000h)
Opens the file for reading only.
OPEN_ACCESS_WRITEONLY (0001h)
Opens the file for writing only.
OPEN_ACCESS_READWRITE (0002h)
Opens the file for reading and writing.
0003h
Reserved; do not use.
OPEN_ACCESS_RO_NOMODLASTACCESS (0004h)
Opens the file for reading only without modifying the file's last access date.

Sharing mode Meaning
OPEN_SHARE_COMPATIBLE (0000h)
Opens the file with compatibility mode, allowing any process on a given computer to open the file any number of times.
OPEN_SHARE_DENYREADWRITE (0010h)
Opens the file and denies both read and write access to other processes.
OPEN_SHARE_DENYWRITE (0020h)
Opens the file and denies write access to other processes.
OPEN_SHARE_DENYREAD (0030h)
Opens the file and denies read access to other processes.
OPEN_SHARE_DENYNONE (0040h)
Opens the file without denying read or write access to other processes, but no process may open the file for compatibility access.

Open flags Meaning
OPEN_FLAGS_NOINHERIT (0080h)
If this flag is set, a child process created with Load and Execute Program (Interrupt 21h Function 4B00h) does not inherit the file handle. If the handle is needed by the child process, the parent process must pass the handle value to the child process. If this flag is not set, child processes inherit the file handle.
OPEN_FLAGS_NO_BUFFERING (0100h)
The file is to be opened with no intermediate buffering or caching done by the system. Read and write operations access the disk directly. All reads and writes to the file must be done at file positions that are multiples of the disk sector size, in bytes, and the number of bytes read or written should also be a multiple of the sector size. Applications can determine the sector size, in bytes, with the Get Disk Free Space function (Interrupt 21h, Function 36h).
OPEN_FLAGS_NO_COMPRESS (0200h)
The file should not be compressed on a volume that performs file compression. If the volume does not perform file compression, this flag is ignored. This flag is valid only on file creation and is ignored on file open.
OPEN_FLAGS_ALIAS_HINT (0400h)
The number in the DI register is to be used as the numeric tail for the alias (short filename). For more information, see AliasHint below.
OPEN_FLAGS_NOCRITERR (2000h)
If a critical error occurs while MS-DOS is opening this file, Critical-Error Handler (Interrupt 24h) is not called. Instead, MS-DOS simply returns an error value to the program.
OPEN_FLAGS_COMMIT (4000h)
After each write operation, MS-DOS commits the file (flushes the contents of the cache buffer to disk).

Attributes
Attributes for files that are created or truncated. This parameter may be a combination of these values:
_A_NORMAL (0000h)
The file can be read from or written to. This value is valid only if used alone.
_A_RDONLY (0001h)
The file can be read from, but not written to.
_A_HIDDEN (0002h)
The file is hidden and does not appear in an ordinary directory listing.
_A_SYSTEM (0004h)
The file is part of the operating system or is used exclusively by it.
_A_VOLID (0008h)
The name specified by Filename is used as the volume label for the current medium and is restricted to the standard 8.3 format. For information about an alternative way to set the volume label, see Set Media ID (Interrupt 21h Function 440Dh Minor Code 46h) in the Microsoft MS-DOS Programmer's Reference.
_A_ARCH (0020h)
The file is an archive file. Applications use this value to mark files for backup or removal.
Action
Action to take it the file exists or if it does not exist. This parameter can be a combination of these values:
FILE_CREATE (0010h) Creates a new file if it does not already exist. The function fails if the file already exists.
FILE_OPEN (0001h) Opens the file. The function fails if the file does not exist.
FILE_TRUNCATE (0002h) Opens the file and truncates it to zero length (replaces the existing file). The function fails if the file does not exist.

The only valid combinations are FILE_CREATE combined with FILE_OPEN or FILE_CREATE combined with FILE_TRUNCATE.

Filename
Address of a null-terminated string specifying the name of the file to be opened or created. The string must be a valid path for the volume associated with the given drive. Long filenames are allowed.
AliasHint
Number that is used in the numeric tail for the alias (short filename). A numeric tail, which consists of the tilde character (~) followed a number, is appended to the end of a filename. The system constructs the alias from the first few characters of the long filename followed by the numeric tail. The system starts with the number 1 in the numeric tail. If that filename is in use, it uses the number 2. It continues in this fashion until a unique name is found. To override the default numbering scheme, you must specify the OPEN_FLAGS_ALIAS_HINT value when you create the file in addition to specifying this parameter. If a filename already exists with the specified numeric tail, the system uses the default numbering scheme. You should specify a number for this parameter, not the tilde character.

Return Value

Clears carry flag, copies the file handle to the AX register, and sets the CX register to one of the following values if successful:

ACTION_OPENED (0001h)
ACTION_CREATED_OPENED (0002h)
ACTION_REPLACED_OPENED (0003h)

Otherwise, the function sets the carry flag and sets the AX register to an error value.

Remarks

A file on a remote directory — that is, a directory on the network — cannot be opened, created, or modified, unless the appropriate permissions for the directory exist.