Function 3Dh Open File with Handle

mov dx, seg FileName

mov ds, dx

mov dx, offset FileName ;ds:dx points to name of file or device

mov al, FileAccess ;modes with which to open file

mov ah, 3Dh ;Open File with Handle

int 21h

jc error_handler ;carry set means error

mov Handle, ax ;handle of file or device

Open File with Handle (Function 3Dh) opens any file, including hidden and system files, for input or output.

Parameters

FileName

Points to a zero-terminated ASCII string that specifies the file to open. This string must be a valid MS-DOS filename and cannot contain wildcards.

FileAccess

Specifies the modes with which to open the file. FileAccess can be a combination of values from the following table. The access value is required; the sharing and inheritance values are optional.

Value Meaning

OPEN_ACCESS_READONLY (0000h) Open the file for read-only access.
OPEN_ACCESS_WRITEONLY (0001h) Open the file for write-only access.
OPEN_ACCESS_READWRITE (0002h) Open the file for read-and-write access.
OPEN_SHARE_COMPATIBILITY (0000h) Permit other programs any access to the file. On a given computer, any program can open the file any number of times with this mode. This is the default sharing value.
OPEN_SHARE_DENYREADWRITE (0010h) Do not permit any other program to open the file.
OPEN_SHARE_DENYWRITE (0020h) Do not permit any other program to open the file for write access.
OPEN_SHARE_DENYREAD (0030h) Do not permit any other program to open the file for read access.
OPEN_SHARE_DENYNONE (0040h) Permit other programs read or write access, but no program may open the file for compatibility access.
OPEN_FLAGS_NOINHERIT (0080h) A child program created with Load and Execute Program (Function 4B00h) does not inherit the file handle. If this mode is not set, child programs inherit the file handle.

Return Value

If the function is successful, the carry flag is clear and the AX register contains the file handle. Otherwise, the carry flag is set and the AX register contains an error value, which may be one of the following values:

Value Name

0002h ERROR_FILE_NOT_FOUND
0003h ERROR_PATH_NOT_FOUND
0004h ERROR_TOO_MANY_OPEN_FILES
0005h ERROR_ACCESS_DENIED
000Ch ERROR_INVALID_ACCESS

Comments

When the file is opened, the file pointer is set to zero (the first byte in the file).

This function returns 0005h (ERROR_ACCESS_DENIED) if a program attempts to open a directory or volume identifier or to open a read-only file for write access.

MS-DOS ignores the OPEN_SHARE_DENYREADWRITE, OPEN_SHARE_DENYWRITE, OPEN_SHARE_DENYREAD, and OPEN_SHARE_DENYNONE modes if SHARE.EXE is not loaded. If this function fails because of a file-sharing error, a subsequent call to Get Extended Error (Function 59h) returns the error value that specifies a sharing violation.

If the specified file is on a network drive, Open File with Handle opens the file only if the network has granted read access, write access, or read-and-write access to the drive or directory.

See Also

Function 3Eh Close File with Handle
Function 3Fh Read File or Device
Function 40h Write File or Device
Function 42h Move File Pointer
Function 59h Get Extended Error
Function 6Ch Extended Open/Create
Interrupt 2Fh Function 1000h Get SHARE.EXE Installed State