ID Number: Q39529
4.00 4.01
MS-DOS
docerr
Summary:
This article contains information on interrupt 21H, function 6CH,
which is new to MS-DOS Version 4.00. This information was not included
in the "MS-DOS Version 4.00 Programmer's Reference." For additional
information on this service, please refer to Pages B-138 to B-139 of
the IBM PC-DOS Version 4.00 technical reference manual.
This application note is also available from Microsoft Product Support
Services by calling (206) 454-2030.
More Information:
Extended Open/Create (Function 6CH)
Call:
-----
AH = 6CH
AL = reserved (must be 00H)
BX = open mode (see text)
CX = create attribute (see section 1.5.5, "File Attributes")
DX = function control flag (see text)
DS:SI = pointer to filename
Returns:
--------
Carry Set:
AX = error code:
01H = invalid function
02H = file not found
03H = path not found
04H = no free handles
05H = access denied
0CH = invalid access
50H = file already exists
Carry Not Set:
No error
AX = file handle
CX = Action code taken:
1 = file successfully opened
2 = file successfully opened/created
3 = file successfully replaced/opened
Comments:
---------
Function 6CH opens and/or creates a file, incorporating the features
of the MS-DOS functions 3CH (Create File Handle), 3DH (Open File
Handle), and 5BH (Create New File Handle). It also incorporates new
features not available in the older functions, such as the ability to
automatically commit new data to disk and to bypass an Interrupt 24H
critical error during an open/create.
For file-sharing abilities to be active, the MS-DOS SHARE.EXE utility
must be loaded. For additional information about this function, refer
to Functions 3CH, 3DH, and 5BH.
Open Mode
The value in BX is made up of five parts that specify whether the file
is to be opened for read, write, or both (access code); what access
other processes have to the file (sharing mode); whether a child
process inherits the file (inherit bit); whether critical errors
should be directed to the Interrupt 24H handler (critical error bit);
and whether disk should be automatically updated to disk.
|---|---|---|-------------------|---|-----------|---|-----------|
Bit |15 |14 |13 |12 11 10 9 8 | 7 | 6 5 4 | 3 | 2 1 0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
\_/ \_/ \_/ \_________________/ \_/ \_________/ \_/ \_________/
| | | | | | | |
| | | | | | | +-> access mode
| | | | | | |
| | | | | | +-> reserved
| | | | | |
| | | | | +-> sharing mode
| | | | |
| | | | +-> inherit bit
| | | |
| | | +-> reserved
| | |
| | +-> critical error bit
| |
| +-> write through bit
|
+-> reserved
Reserved
Bits 3, 8 through 12, and 15 of this word are reserved by MS-DOS for
future use and must be set to zero (0).
Write Through Bit
The write through bit (bit 14) specifies if the file is updated
automatically by the system. If the bit is 1, any disk write using
the handle returned by the function will be automatically followed by
a call to Function 68H (Commit File). If the bit is 0, no additional
action is taken following disk writes to this handle.
Critical-Error Bit
The critical-error bit (bit 13) specifies the action the MS-DOS
critical-error handler will take to this handle. If the bit is 1, the
Interrupt 24H critical error is disabled for the handle that is
returned by this function, and the extended error handler will not
be called, instead returning the extended error code to the calling
application. If the bit is 0, the Interrupt 24H critical error handler
will handle the critical errors generated by this file handle.
Inherit Bit
The inherit bit (bit 7) specifies whether the file is inherited by a
child process created with Function 4BH (Load and Execute Program or
Overlay). If the bit is 0, the child process inherits the file; if the
bit is 1, it doesn't.
Sharing Mode
The sharing-mode bits (bits 4-6) specify what access, if any, other
processes have to the open file. It can have the following values:
Sharing-Mode Bit Values
----------------------------------------------------------------------------
Bits 4-6 Sharing Mode Description
----------------------------------------------------------------------------
000 Compatibility On a given machine, any process can open the file
any number of times with this mode. Fails if the
file has been opened with any of the other sharing
modes.
001 Deny both Fails if the file has been opened in compatibility
mode or for read or write access, even if by the
current process.
010 Deny write Fails if the file has been opened in compatibility
mode or for write access by any other process.
011 Deny read Fails if the file has been opened in compatibility
mode or for read access by any other process.
100 Deny none Fails if the file has been opened in compatibility
mode by any other process.
----------------------------------------------------------------------------
Access Mode
The access mode (bits 0-2) specifies how the file is to be used. It can
have the following values:
Access-Mode Bit Values
-----------------------------------------------------------------
Bits 0-2 Access Description
-----------------------------------------------------------------
000 Read Fails if the file has been opened in deny read
or deny both sharing mode.
001 Write Fails if the file has been opened in deny write
or deny both sharing mode.
010 Both Fails if the file has been opened in deny read,
deny write, or deny both sharing mode.
-----------------------------------------------------------------
Function-Control Flag:
The value in DX controls the way in which this function operates if
the file exists (exist mode) and if the file does not exist (not
exist mode).
|-------------------------------|---------------|---------------|
Bit |15 14 13 12 11 10 9 8 | 7 6 5 4 | 3 2 1 0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
\_____________________________/ \_____________/ \_____________/
| | |
| | +-> exist mode
| |
| +-> not exist mode
|
+-> reserved
Reserved
Bits 8 through 15 of this word are reserved by MS-DOS for future use
and must be set to 0.
Exist Mode
The exist mode (bits 0-3) specifies how the function should behave if
the file exists. It can have the following values:
Exist-Mode Bit Values
-------------------------------------------------------------------
Bits 0-3 Mode Description
-------------------------------------------------------------------
000 Fail Fails if the file already exists.
001 Open Opens the file if the file exists.
010 Open/Replace Opens/replaces the file if the file exists.
-------------------------------------------------------------------
Not-Exist Mode
The not-exist mode (bits 4-7) specifies how the function should behave
if the file does not exist. It can have the following values:
Not-Exist Mode Bit Values
-------------------------------------------------------------
Bits 4-7 Mode Description
-------------------------------------------------------------
000 Fail Fails if the file does not exist.
001 Create Create the file if the file does not exist.
-------------------------------------------------------------
If there is an error, the carry flag (CF) is set and the error code
is returned in AX:
Error Return Codes
-------------------------------------------------------------------
Code Meaning
-------------------------------------------------------------------
01H Incorrect information was sent to the function.
02H The file is invalid or does not exist.
03H The directory is invalid or does not exist.
04H There are no free file handles in the current process, or
internal system file handle tables are full.
05H Program attempted to open a directory, volume ID, or tried to
open a read-only file for writing.
0CH Access mode (bits 0-3 of BX) not 00H, 01H, or 02H.
50H A file with the same specification already exists.
-------------------------------------------------------------------