Chapter 4 DR-DOS System Calls

This section gives a detailed description of the DR-DOS system functions. The function specifications in this section are arranged in numerical order for ease of use. Section 2.4, System Call Summary, provides an introduction to the different categories of system function.

Some of the system calls return error information, to which there may be references in the system call description. More extensive information concerning the type of error information returned by system calls may be found in Chapter 5, Error Handling, and you are advised to read this chapter for a full description of error codes.

The Program Terminate call restores the terminate, Ctrl-Break, and critical error exit addresses to the values saved in the Program Segment Prefix (PSP). These are the values saved on entry to the terminating program.

See the explanation of the Load and Execute a Program (4BH) call for an illustration (Figure 4-6) that describes the PSP control block.

Program Terminate flushes all file buffers and transfers control to the terminate address. Note that DR-DOS does not properly record the directory information for files that have changed in length and were not previously closed. Ensure that the CS register contains the segment address of the calling program’s PSP before invoking Program Terminate.

You should not use this call in new programs; it is provided only to support existing programs. The preferred call for this function is Terminate a Process (4CH).

Keyboard Input reads a character from the standard input device of the calling process, writes the character to the standard output device, and then returns the character in the AL register. If a character is not ready to be read, Keyboard Input waits for one before returning to the calling process.

Keyboard Input executes an INT 23H when it reads Ctrl-Break. When the calling process wants to read an extended ASCII code character, it must call Keyboard Input twice. Keyboard Input returns 00H in register AL to indicate that a subsequent call will return an extended ASCII code character.

Console Output writes the character in DL to the calling process’s standard output device. If DL contains a backspace character (08H), Console Output moves the cursor left one position.

Console Output executes an INT 23H in response to Ctrl-Break after output is completed.

Auxiliary Input reads the next byte from the standard auxiliary device and returns it in register AL.

Auxiliary Output writes the byte specified in register DL to the standard auxiliary device.

Printer Output writes the ASCII character specified in register DL to the standard printer device.

When register DL contains FFH, Direct Console I/O reads a character from the standard input device, clears the Zero flag, and returns the character in register AL. If a character is not ready from the input device, Direct Console I/O sets the Zero flag and returns 00H in AL.

If register DL contains anything other than FFH, Direct Console I/O assumes that DL contains a valid character to be written to the standard output device. Direct Console I/O does not check for Ctrl-PrtSc or Ctrl-Break input from the console.

When the calling process wants to read or write an extended ASCII code character, it must call Direct Console I/O twice. The first call returns 00H in register AL to indicate that a subsequent call will return an extended ASCII code character.

The Direct Console Input call reads a character from the standard input device of the calling process and returns the character in register AL. If a character is not ready from the input device, the call waits for one before returning to the calling process.

To read an extended ASCII code character, the calling process must make this call twice. Direct Console Input returns 00H in register AL to indicate that a subsequent call will return an extended ASCII code character.

Direct Console Input does not check for Ctrl-PrtSc or Ctrl-Break input from the console.

The Console Input without Echo call reads a character from the standard input device of the calling process and returns the character in register AL. If a character is not ready to be read, the call waits for one before returning to the calling process.

Console Input without Echo executes an INT 23H when it reads Ctrl-Break. When the calling process wants to read an extended ASCII code character, it must make this call twice. In this case, the call returns 00H in register AL to indicate that the next call will return an extended ASCII code character.

Print String sends each character in the ASCII string addressed by DS:DX and terminated by a $ character (24H) to the standard output device. If the string contains a backspace character (08H), Print String shifts the cursor left one position.

Print String executes an INT 23H when the user enters Ctrl-Break after the string is written to the console.

Buffered Console Input reads characters from the calling process’s standard input device and writes them to the input buffer addressed by registers DS:DX. Figure 4-1 shows the format of the input buffer.

Figure 4 1
Console Buffer Format

The first byte (MAX) specifies the number of characters the buffer can hold. DR-DOS sets the second byte (NCHARS) to the number of characters received. This value does not include the terminator character, a carriage return (0DH). Buffered Console Input writes the characters it reads from the input device into the buffer beginning at the third byte. When the call reads a carriage return, it stops writing to the buffer.

When the input buffer contains MAX-1 characters, Buffered Console Input ignores additional input and sounds the bell until it reads a carriage return.

Check Standard Input Status returns FFH in register AL when a character is available from the standard input device. If the call returns 00H in AL, a character is not available. Check Standard Input Status executes an INT 23H when it detects a Ctrl-Break character.

The Character Input with Buffer Flush discards the contents of the type-ahead buffer of the standard input device and invokes the input call whose number is entered in register AL.

The calling process can pass the following system call numbers:

01H - Keyboard Input

06H - Direct Console I/O

07H - Direct Console Input

08H - Console Input without Echo

0AH - Buffered Console Input (see Function 0AH for other
parameters)

Disk Reset flushes all file buffers by writing the contents of all modified buffers to disk. The call does not update disk directory information for those files which were left open and have changed in size. (To update this information you must either close the disk or use the Commit File (68H) function.)

Your program does not need to call Disk Reset before a disk change when all files written have been closed.

See Chapter 5, Error Handling, for error code definitions.

Select Disk first determines whether the drive specified in DL is valid, then selects it as the default drive. Drives are numbered starting with zero, where 0 is A, 1 is B, and so forth.

AL returns the number of the last drive in the system. For example, if AL = 5, the last drive is E:. The value is set to the last physical drive that is found during initialization, unless the LASTDRIVE = statement is included in the CONFIG.SYS file and specifies a higher number than that of the last physical drive.

Open File searches the current directory for a specified file and places information required for I/O operations in the File Control Block (FCB).

On entry, registers DS:DX point to an unopened FCB that names a file in the current directory which is to be opened. On return Open File sets the value in AL to 0FFH if the file was not found and to 00H if the call was successful. If the file has not been found, use the Get Extended Error (59H) function call to determine the actual error condition.

Additionally, Open File sets certain fields in the FCB to contain information about the file. If the drive field is set to zero, indicating the default drive, Open File places the actual drive number in this field, where 1 is A, 2 is B, and so forth. This ensures that changing the default drive does not interfere with subsequent operations on this file. The other FCB fields that are set are the file size and date fields, which Open File fills with information obtained from the directory, and the current block and record size fields. Open File sets the current block field to zero and sets the file record size to 80H.

On return from Open File you should set certain other fields in the FCB before requesting any disk operations. If the file’s record size is not 80H, you must set the actual record size in the field (offset 0EH in the FCB). Also, you must set the current record (offset 20H) and/or random record (offset 21H) fields, depending on the type of access required.

For more detailed information about DR-DOS FCBs, see Section 2.3, FCB Oriented File Management.

The Close File call closes a file when all read or write operations have completed. You must call Close File when you have finished with the file.

On entry, DS:DX point to an opened FCB. Close File sets AL to 00H to indicate a successful close. If the file is not found in the directory, Close File sets AL to 0FFH. Use the Get Extended Error (59H) function call to determine the actual error condition.

The Search for First Entry call searches the current directory for the first filename that matches the filename in the unopened FCB specified in DS:DX. The filename may include the question mark character, which matches any character in the same position in a filename. If the calling program points to an extended FCB, Search for First Entry bases its search on the contents of the attribute byte in the FCB prefix. (See Section 2.3.2, Extended FCB, for a discussion of Extended FCBs.) Table 4-1 lists the attribute byte values.

If the call does not find a match, it returns 0FFH in AL. Use the Get Extended Error (59H) function call to determine the actual error condition.

If the call finds a match, it returns 00H in AL and places information in the Disk Transfer Area (DTA) of the calling program. This information differs according to whether the FCB pointed to on entry is a normal or an extended FCB.

If the search FCB is a normal FCB, Search for First Entry sets the first byte in the calling program’s Disk Transfer Area (DTA) to the drive number of the drive containing the matching FCB, where A is 1, B is 2, and so forth. DR-DOS copies the directory entry for the matching file into the next 32 bytes in the DTA.

If the search FCB is an extended FCB, Search for First Entry sets the first byte in the calling program’s DTA to 0FFH. The call sets the following five bytes to zero and copies the attribute byte and drive code from the search FCB to the following two bytes. It then copies the matching directory entry into the following 32 bytes. On return, the calling program’s DTA contains an unopened, extended FCB with the same attributes as the search FCB.

If the attribute byte is zero, the call finds only normal file entries that have no attributes set, or have the Read/only and/or the Archive attribute set. Search for First Entry will not return entries for the volume label, subdirectories, or hidden and system files.

If the attribute byte is set for hidden (bit 1 set) or system files (bit 2 set), or for subdirectories (bit 4 set), Search for First Entry searches all normal entries plus all entries matching the specified attributes. To look at all directory entries except the volume label, set bits 1, 2, and 4 in the attribute byte.

If bit 3 is set, Search for First Entry searches only for a volume label.

After Search for First Entry finds a match to an ambiguous filename, you can call Search for Next Entry to look for the next match. An ambiguous filename is one that contains question mark characters. The Entry parameters and returned values are the same as those for Search for First Entry (11H).

If the call does not find a match, it returns 0FFH in AL. Use the Get Extended Error (59H) function call to determine the actual error condition.

Do not perform any disk operations with the search FCB between Search for First and Search for Next calls, or between two Search for Next Calls, because DR-DOS stores information necessary to continue the search in the reserved area of the search FCB. This information would be overwritten by a disk operation that intervened between two search calls.

The Delete File call deletes all entries that match the specified filename in the current directory. On entry, DS:DX point to an unopened FCB. The question mark character is allowed in the filename and extension. If no entries match, Delete File returns 0FFH in AL. Use the Get Extended Error (59H) function call to determine the actual error condition.

Sequential Read reads the record in the file pointed to by the current block (offset 0CH) and current record (offset 20H) fields in the file’s FCB. It copies the record to the calling program’s DTA, then increments the current record field in the FCB. DR-DOS determines the length of a file’s record from the record size field in the FCB (offset 0EH).

Sequential Read and Sequential Write (15H) increment the FCB’s current block field when the current record number field overflows. The range of the current record number field is 0-127. You must initialize the current record number to zero for a read or write that starts from the beginning of the file. For more information on the current block and current record number fields, see Section 2.3, FCB Oriented File Management.

Sequential Read returns 01H or 03H in AL if an end-of-file character is encountered. A return of 01H indicates no data in the record; 03H indicates a partial record was read and filled out with zeros.

Sequential Read returns 02H in AL if there was not enough space in the calling program’s DTA to read a single record and the read was ended. The call determines this condition when the DTA offset plus the record length exceeds FFFFH. 00H is returned in AL if the read was completed successfully. Use the Get Extended Error (59H) function call to determine the actual error condition.

The Sequential Write call writes data from the calling program’s DTA to the position in the file pointed to by the current block and current record fields in the FCB. After writing each record, Sequential Write increments the current record field in the FCB.

Sequential Write determines the file’s record length from the record size field in the FCB. If the record size is smaller than a single sector, Sequential Write buffers data until a sector is filled out, at which time the write is performed.

Sequential Write returns 00H in AL if the write is successfully completed. 01H in AL indicates that the destination disk is full. 02H indicates there is insufficient space in the calling program’s DTA (DTA offset plus record length exceeds FFFFH) to hold one record and the operation is ended. Use the Get Extended Error (59H) function call to determine the actual error condition.

Create File searches the current directory for an entry matching the FCB pointed to by DS:DX. If a matching entry is found, it is reused. If no match is found, Create File searches the directory for an empty entry. When Create File finds an empty directory entry, it initializes the entry to a zero-length file, calls Open File (0FH), and returns 00H in AL. If no directory entry is available (AL=0FFH), use the Get Extended Error (59H) function call to determine the actual error condition.

A file created with the Create File call can be assigned the hidden attribute by using an extended FCB and setting the file’s attribute byte to 02H. Section 2.3.3, File Attribute Byte, describes the attribute byte.

Rename File changes the name of files in the current directory according to information held in a modified FCB. On entry to Rename File, registers DS:DX point to a modified FCB which contains a drive code and filename in the normal position, with a second filename in an area that is normally reserved. The second filename begins six bytes after the end of the normal filename field (DS:DX+11H).

The first filename in the FCB is the name for which Rename File searches and the second filename is the new name for the file. The second name may include question mark characters, indicating that the corresponding positions in the original name are not to be changed.

Rename File returns 00H in AL if the call is successful and 0FFH if no match is found for the first filename or if the second filename is already in use. Use the Get Extended Error (59H) function call to determine the actual error condition.

Current Disk returns the number of the current default drive, where 0 is A, 1 is B, and so forth.

The Set Disk Transfer Area call sets the address of the Disk Transfer Area (DTA) to the value specified in DS:DX. If you do not set the DTA, DR-DOS uses the standard DTA, located at offset 80H in the Program Segment Prefix (PSP).

The area between the specified offset and the end of the DTA segment should be large enough to accommodate your largest record, to ensure that DR-DOS is able to perform disk transfers. The DR-DOS FCB read and write calls (14H, 15H, 21H, 22H, 27H, and 28H) do not read or write data beyond the end of the segment specified for the DTA, nor do they wrap to the segment’s beginning.

The Allocation Table Address call returns information about the default drive. Upon return, registers DS:BX point to the File Allocation Table (FAT) identification byte for the default drive. DX contains the number of clusters in the drive, AL contains the sectors per cluster, and CX contains the size of a physical sector.

This call is identical to call 1BH, except that DL contains a specific drive number. Drive numbers start with zero, where 0 is the default drive, 1 is A, 2 is B, and so forth.

See also Function 32h - this function shows the format of the DOS Drive Parameter Block.

Upon entry to Random Read, DS:DX point to an opened FCB. Random Read first sets the current block (offset 0CH) and current record fields (offset 20H) in the FCB to correspond with the random record field (offset 21H). It then reads the indicated record into the calling program’s DTA.

Random Read returns 00H in AL when the read is successfully completed. If Random Read encounters an end-of-file indicator, it returns 01H in AL, indicating no more data is available, or 03H, meaning a record was partially read and its remainder filled out with zeros.

Random Read returns 02H in AL when there is not enough space in the DTA to read one record (offset plus record length is greater than 0FFFFH) and the operation was ended. Use the Get Extended Error (59H) function call to determine the actual error condition.

Upon entry to Random Write, DS:DX point to an opened FCB. After Random Write has set the current block (offset 0CH) and current record fields (offset 20H) in the FCB to correspond with the random record field (offset 21H), it writes the indicated record from the calling program’s DTA.

Random Write returns 00H in AL when the write is successfully completed. Random Write returns 01H in AL if the destination disk is full and the operation was cancelled. Random Write returns 02H in AL when there is insufficient space in the DTA (offset plus record length is greater than 0FFFFH) to write a single record and the operation was cancelled. Use the Get Extended Error (59H) function call to determine the actual error condition.

File Size searches the current directory for the first entry that matches the specified FCB pointed to in DS:DX. To receive accurate information from File Size, you must set the record size field (offset 0EH) in the referenced FCB before your program performs the call.

When a matching entry is found, File Size sets the random record field in the FCB to the number of records in the file. File Size counts records in terms of the length of record specified in the FCB’s record size field, rounded up. If no matching entry is found, File Size returns 0FFH in AL. Use the Get Extended Error (59H) function call to determine the actual error condition.

The Set Random Record Field call sets the random record field (offset 21H) to the file address stored in the current block (offset 0CH) and current record (offset 20H) fields in the FCB.

The Set Vector call sets the interrupt vector table for the interrupt number passed by the calling process in AL to the address in DS:DX. You can find out the current contents of the interrupt vector table by calling Get Vector (35H).

The Create New Program Segment Prefix (PSP) call copies the entire 100H area from location 0 in the current PSP of the calling program into location 0 of the segment whose number is passed in register DX.

This call updates the memory size field (offset 06H) and saves the terminate, Ctrl-Break, and critical error exit addresses for interrupts 22H, 23H, and 24H in the new Program Segment Prefix (PSP) starting at offset 0AH. These addresses are restored from the PSP when the current program terminates.

See the Load and Execute Program (4BH) call for a description of the PSP.

The Random Block Read call reads the specified number of records from the point in the file specified by the random record field into the calling program’s disk transfer area (DTA). On entry, registers DS:DX point to an opened FCB and CX contains a record count that must not be zero. Random Block Read counts records in terms of the record length specified in the record size field (offset 0EH) in the FCB.

If the read is successfully completed, Random Block Read returns 00H in AL. If an end-of-file indicator is reached before all records have been read, the call returns either 01H or 03H in AL. 01H indicates that the last record is complete; 03H indicates that it is a partial record and zero-filled.

Random Block Read reads records into the DTA until the DTA offset plus record length exceeds 0FFFFH. If not all of the specified records have been read, 02H is returned in AL. Use the Get Extended Error (59H) function call to determine the actual error condition.

In any event, Random Block Read returns the actual number of records read in CX and sets the random record, current block (offset 0CH), and current record (offset 20H) fields to point to the next record in the file; that is, the first record that has not been read.

Random Block Write writes the specified number of records from the calling program’s DTA to the file address specified by the random record field in the opened FCB specified in DS:DX. Random Block Write returns 00H in AL if the write was successfully completed, or 01H in AL when there is insufficient space on the destination disk and the operation is cancelled.

Random Block Write returns 02H in AL when there is insufficient space in the calling program’s DTA (offset plus record length is greater than 0FFFFH) to hold one record and the operation is ended. Use the Get Extended Error (59H) function call to determine the actual error condition.

If CX is zero upon entry, no records are written, but the file is set to the length specified by the random record field. If the new file size is longer or shorter than the file size specified in the FCB (at offset 10H), clusters are allocated or released as appropriate.

The Parse Filename call parses an ASCII file specification and prepares an FCB. Upon entry, DS:SI point to a command line to parse and ES:DI point to a buffer to be filled with an unopened FCB.

The command line is parsed for a file name of the form:

d:filename.ext

If found, Parse Filename creates an unopened FCB for the file at the address pointed to by ES:DI. If no drive specifier is present, the default drive is assumed. If no extension is present, Parse Filename assumes it to be all blanks. If the asterisk (*) character appears in the filename or extension, Parse Filename replaces the asterisk and any remaining characters in the filename or extension with question marks.

The contents of the byte in AL upon entry determine how Parse Filename acts on the specified command line. The bit map for this AL register entry parameter is as follows:

If bit 0 is 1, Parse Filename scans leading separators off the source command line. If bit 0 is 0, no scan-off is performed.

If bit 1 is 1, Parse Filename changes the drive field in the result FCB only if a drive was specified in the command line.

If bit 2 is 1, Parse Filename changes the filename field in the result FCB only if the command line contains a filename.

If bit 3 is 1, Parse Filename changes the extension field in the result FCB only if the command line contains an extension.

Parse Filename ignores bits 4-7.

Filename separators include the following characters:

: colon
. Period
; semicolon
, comma
= equal sign
+ plus sign
tab
space

Filename terminators include all of the separator characters plus:

\ backslash
< less than
> greater than
| vertical bar
/ slash
“ quotation marks
[ left square bracket
] right square bracket

Filename terminators also include any control characters.

Parse Filename returns the segment and offset addresses of the first character after the filename in DS and SI, respectively, and returns the address of the first byte of the formatted FCB in ES:DI. If the target command line does not contain a valid filename, Parse Filename returns a blank at ES:DI+1.

If the question mark or asterisk wildcard characters appear in the filename or extension, Parse Filename returns 01H in AL. If no wildcard characters appear, AL contains 00H. If the drive specifier is invalid, AL contains 0FFH.

The Get Date call returns the day of the week, year, month, and day as recorded by the system clock.Get Date returns the year in CX, the month in DH, and the day in DL. All returned values are in binary. DR-DOS takes into account the number of days in the month and whether the year is a leap year when calculating the date.

Days of the week are numbered from 0 through 6, starting with Sunday. Valid years are 1980 through 2099. Valid months are numbered 1 through 12. Valid days are numbered 1 through 31, with allowance made for the number of days in a given month and whether the specified year is a leap year.

The date is adjusted automatically when the time of day clock advances to the next day.

The Set Date call sets the system date. On entry, CX must contain a valid year, DH a valid month, and DL a valid day.

Set Date returns 00H in AL if the date is set successfully, and returns a value of 0FFH if the date you specified is not valid.

Valid years are 1980 through 2099. Valid months are numbered 1 through 12. Valid days are numbered 1 through 31, with allowance made for the number of days in a given month and whether the specified year is a leap year.

The Get Time call returns the system time in hours, minutes, seconds, and hundredths of a second, using the 24 hour clock. Get Time returns the time in four 8-bit quantities. You can easily convert Get Time’s returned values to a printable form or use these values in calculations, such as working out how long a program has been active.

The Set Time sets the system time using the 24 hour clock. On entry, CH contains the hours, CL the minutes, DH the seconds, and DL the hundredths of a second. If any component of the time is invalid, the set operation is terminated and Set Time returns 0FFH in AL. If the time is valid and the time is successfully set, Set Time returns 00H in AL.

When Verify is on, DR-DOS verifies every disk write operation performed by the current application. Use function 54H to get the status of the Verify flag.

Get Disk Transfer Address returns the address of the current Disk Transfer Area (DTA) in ES:BX. You can set the Disk Transfer Area by calling Set Disk Transfer Address (1AH). The DTA is described in Section 2.3.4, Disk Transfer Area.

The Get DOS Version Number call returns the high part of the DR-DOS version number in register AL and the low part in AH. Registers BX and CX are set to 00H. For the current version of DR-DOS the values returned are 03H in AL and 1FH in AH.

The Keep Process call terminates the calling process but keeps the number of paragraphs of memory designated by DX. The memory is retained above the start of the current Program Segment Prefix (PSP).

Files opened by the process are not closed when the call is executed.

The binary error (or exit) code passed in register AL can be retrieved by the parent process through Get Subprocess Return Code (4DH).

The following table describes the format of the DOS drive parameter block.

The Ctrl-Break Check call can get or set the current state of Ctrl-Break checking. If register AL = 00H, Ctrl-Break Check returns the current state of the Ctrl-Break checking mechanism in register DL.

If AL contains 01H on entry, Ctrl-Break checking is set according to the value passed in register DL.

This function does not use any of the DOS internal stacks so it can be called at any time.

This function returns the actual version number and not the version number set by the SETVER command. Using Function 30h however, the return value can be changed with SETVER.

The Get Vector call returns the CS:IP interrupt routine address in registers ES:BX for the interrupt number specified in AL. Use the Set Vector (25H) call to set interrupt vectors.

Get Disk Free Space returns information about the free space on a specified drive. Upon entry, DL contains a drive number, where 0 is the default drive, 1 is A, 2 is B, and so forth. Get Disk Free Space returns the number of available clusters in BX, the total number of clusters in the drive in DX, the number of bytes per sector in CX, and the number of sectors per cluster in AX.

This changes the default country code to that specified in register BX. Available country codes are:

This call returns the country dependent information shown in Figure 4-2 to the block of memory addressed in registers DS:DX. Register BX specifies the required country. A country code of 0 returns the current country data.

Figure 4-2
Country Dependent Data Return Block

Available countries are:

The Date format is:

The Currency format is:

The Time format is:

The Case Map call uses register AL as follows:

If the Carry flag is set, register AX contains an error code on return. See Chapter 5, Error Handling, for error code definitions.

The ASCIIZ string addressed by registers DS:DX specifies a drive and directory path name. MKDIR returns to the calling process with a new directory created at the end of the specified path. MKDIR does not add the new directory to the directory structure if any directory of the specified path does not exist. MKDIR returns error code 3 or 5 in register AX. See Chapter 5, Error Handling, for error code definitions.

RMDIR removes the directory specified in the ASCIIZ string addressed by registers DS:DX from the directory structure. RMDIR will not remove the current directory.

RMDIR returns error code 5 if the directory to be removed is not empty, or is being accessed by any process. RMDIR returns error code 3 if the ASCIIZ string specifies an invalid path.

Change Current Directory sets the current directory as specified in the ASCIIZ string addressed by registers DS:DX.

If any directory of the specified path does not exist, Change Current Directory sets the Carry flag and returns error code 3, Path Not Found, in register AX.

Create a File creates a new file. If there is already a file with the specified name the call truncates the file to zero length in preparation for writing. If the file does not exist, this call creates a file in the directory indicated in the ASCIIZ string and gives the file the read/write attribute (see Section 2.3.3, File Attribute Byte). Create a File returns the file’s handle in AX.

If the Carry flag is set, Create a File returns error code 3, 4, or 5 in AX. Error code 5, Access Denied, indicates that the specified directory is full or a file of the same name exists and is marked read/only. See Chapter 5, Error Handling, for other error code definitions. Note that you can use Change File Mode (43H) to change the file’s attribute.

The Open a File Handle call opens a file with the name and directory location specified in the ASCIIZ string. The call can open both normal and hidden files. Device names must not end with a colon.

On entry, DS:DX point to the ASCIIZ string containing the drive, path, and filename for the file to be opened. Register AL defines the mode in which the file may be opened.

On return, if the Carry flag is not set, Open a File Handle returns a 16-bit file handle that must be used for subsequent input and output to the file. If the Carry flag is set, the call returns an extended error code in AX, indicating why the call failed. The code may be any one of the following:

• Error code 2 - file not found

• Error code 4 - no file handles (too many open files)

• Error code 5 - access denied

• Error code 12 - invalid access code

If the call is successful, Open a File Handle sets the Read/Write pointer to the first byte of the file and sets the record size of the file to one byte. You can move the file pointer with the Move File Pointer call (42H). You can obtain or change a file attribute with the Change File Mode call (43H). File attributes are described in Section 2.3.3, File Attribute Byte.

The combination of values that may be supplied in register AL on entry to the Open a File Handle call allow great control on access to the file. The Access code is defined by four fields in AL: these are the Inheritance flag (one bit), the Sharing Mode (three bits), a reserved field (one bit) and the Access field (three bits).

The Inheritance flag indicates whether the file is private (I=1) or is inherited by a child process (I=0).

The Access field limits the operations that may be performed on this file as directed by one of three codes:

• 00H - Open file for reading only

• 01H - Open file for writing only

• 02H - Open file for reading and writing

The Sharing mode controls the access other processes have to this file while it is open, according to one of five codes:

• 00H - Compatibility

• 01H - Read/Write Denied

• 02H - Write Denied

• 03H - Read Denied

• 04H - None Denied

Note that SHARE must be loaded before these bits can be used.

File sharing requires precise co-operation between all involved processes. If any process opens a file in a mode that denies a level of access, all subsequent requests by other processes to open the file with that level of access will fail. Further, any attempt to open a file with a sharing mode that is already breached by an existing process always fails.

You should always bear in mind the effects of opening a file in a given sharing mode. In particular note the following situations which always cause the Open a File Handle call to fail:

• The file is already open in Compatibility mode

• The file is already open in Deny Read/Write mode

• Deny Write and requested access is Write or Read/Write

• Deny Read and requested access is Read or Read/Write

The Deny None Sharing mode places no limitations on other processes.

The Close a File Handle call closes the specified file handle, writes the contents of all internal buffers associated with the file to disk, and updates the file’s directory. If the Carry flag is set, Close a File Handle returns error code 6 in AX to indicate that an illegal file handle was specified.

Read from a File or Device (3FH)
Read a Specified Number of Bytes into Buffer
Entry Parameters:
Register AH:	3FH
BX:	File handle
DS:	Buffer address - Segment
DX:	Buffer address - Offset
CX:	Number of bytes to be read
Returned Values:
Register AX:	Number of bytes read, if Carry flag not set

The Read from a File or Device call transfers a number of bytes, specified in CX, from a file into the buffer addressed by DS:DX. On return, if the Carry flag is set, AX contains error code 5 or 6. See Chapter 5, Error Handling, for error code definitions.

If the call is successful, the Carry flag is not set and AX contains the number of bytes read from the file or device. If the call is used to read from a device, the characteristics of the device may limit the number of bytes that can be read to fewer than the number specified in CX.

When reading from a file a value in AX less than the value specified in CX indicates that the program has read up to the end of the file. A value of zero indicates an attempt to start the read at the end of the file.

Write to a File or Device (40H)
Write Specified Number of Bytes From Buffer
Entry Parameters:
Register AH:	40H
BX:	File handle
DS:	Buffer Address - Segment
DX:	Buffer Address - Offset
CX:	Number of bytes to write
Returned Values:
Register AX:	Number of bytes written, if Carry flag not set

The Write to a File or Device call transfers the number of bytes specified in CX from the buffer pointed to by DS:DX to the file indicated by the file handle in BX.

On return, if the Carry flag is set, this call returns error code 5 or 6 in AX. Error code 5 indicates access denied; error code 6 indicates an illegal file handle. If the Carry flag is not set, Write to a File or Device returns the actual number of bytes written in AX. If register CX = 0, the file is truncated at the position of the current file pointer.

This call removes a directory entry associated with a filename. The question mark and asterisk wildcard characters are not allowed in any part of the ASCIIZ string pointed to in DS:DX.

This call does not delete read/only files. To delete a read/only file, you must first use the Change File Mode call (43H) to change the file’s attribute.

On return, if the Carry flag is set, this call returns error code 2 or 5 in AX to indicate file not found or access denied, respectively.

Move File Read/Write Pointer (42H)
Move Read/Write Pointer to Specified Location
Entry Parameters:
Register AH:	42H
CX:	Offset to move, in bytes (most significant portion)
DX:	Offset to move, in bytes (least significant portion)
AL:	Move from: 0 - beginning of file 1 - current location 2 - end-of-file
BX:	File Handle
Returned Values:
Register DX:	New pointer location - (mostsignificant portion), if Carry flag not set
AX:	New pointer location - (leastsignificant portion), if Carry flag notset Error code, if Carry flag set

This call moves the read/write pointer according to the location specified by the value passed in AL. On entry, CX:DX contains the distance to move the pointer. On return, if the Carry flag is not set, DX:AX contains the new pointer location. DX contains the most significant part of the value. If the Carry flag is set, this call returns error code 1 or 6 in AX. See Chapter 5, Error Handling, for error code definitions.

Set register AL to one of the following values:

Change File Mode (43H)
Change a File’s Attribute or Password
Entry Parameters:
Register AH:	43H
DS:	Address of ASCIIZ Pathname -Segment
DX:	Address of ASCIIZ Pathname -Offset
CX:	File attributes (AL=1) or password mode (AL=3)
AL:	0 = return attribute
	1 = set attribute to CX
	2 = get password mode
	3 = set password or password mode
Returned Values:
Register AX:	Error code, if Carry flag is set
CX:	File’s current attribute, if Carry flag
	not set and AL contains zero on
	entry, or password mode if AL=2 on
	entry and the Carry flag is not set.

The Change File Mode call:

• Changes or returns the attributes of the file specified by the ASCIIZ string.

• Gets or sets the password mode of the file, and assigns a new password.

If AL=1 on entry, Change File Mode changes the file’s attribute to the one specified in CX. On return, if AL contains zero and the carry flag is not set, this call returns the file’s current attribute in CX. The DOS file attribute byte is described in Section 2.3.3, File Attribute Byte.