Function 3Ch Create File with Handle

mov dx, seg FileName

mov ds, dx

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

mov cx, Attributes ;file attributes

mov ah, 3Ch ;Create File with Handle

int 21h

jc error_handler ;carry set means error

mov Handle, ax ;handle of file or device

Create File with Handle (Function 3Ch) creates a file and assigns it the first available handle. If the specified file already exists, MS-DOS opens it and truncates it to zero length.

Parameters

FileName

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

Attributes

Specifies the attributes to assign to the new file. Any combination of the following values is valid:

Value

Meaning

ATTR_NORMAL (0000h)	File can be read from or written to.
ATTR_READONLY (0001h)	File can read from but not written to.
ATTR_HIDDEN (0002h)	File is hidden and does not appear in a directory listing.
ATTR_SYSTEM (0004h)	File is a system file.
ATTR_VOLUME (0008h)	FileName is used as the volume label for the current medium.
ATTR_ARCHIVE (0020h)	File is marked for archiving.

Return Value

If the function is successful, the carry flag is clear and the AX register contains the new 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

0003h	ERROR_PATH_NOT_FOUND
0004h	ERROR_TOO_MANY_OPEN_FILES
0005h	ERROR_ACCESS_DENIED

Comments

This function returns 0005h (ERROR_ACCESS_DENIED) if a read-only file with the specified name already exists in the specified path or if the file to be created is in the root directory and the root directory is full.

When MS-DOS creates a file, it opens the file with read-and-write access and compatibility sharing mode and sets the file pointer to zero. If ATTR_READONLY is specified, the attribute takes affect only after the new file is closed.

Create File with Handle creates a volume label for the medium in the specified drive only if the ATTR_VOLUME attribute is given and the current medium does not have an existing volume label.

If the specified file is on a network drive, this function creates the file only if the network has granted create (or similar) access to the drive or directory.