[Front] [Prev Chapter] [Next Chapter]

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.

Program Terminate (00H)

Transfer Control to Terminate Address

Entry Parameters:

Register AH:

00H

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.

Note:

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 (01H)

Read Characters from Standard Input Device

Entry Parameters:

Register AH:

01H

Returned Values:

Register AL:

ASCII character or 00H(First byte of an extended ASCII code.)

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 (02H)

Write Characters to Standard Output Device

Entry Parameters:

Register AH:

02H

DL:

ASCII 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 (03H)

Reads a Byte from Standard Auxiliary Input Device

Entry Parameters:

Register AH:

03H

Returned Values:

Register AL:

Byte value

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

Auxiliary Output (04H)

Write a Byte to Standard Auxiliary Device

Entry Parameters:

Register AH:

04H

DL:

Byte value

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

Printer Output (05H)

Write a Character to the Standard Printer Device

Entry Parameters:

Register AH:

05H

DL:

ASCII character

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

Direct Console I/O (06H)

Perform Direct Console I/O to Standard Input Device

Entry Parameters:

Register AH:

06H

DL:

FFH (Input)ASCII character (Output)

Returned Values:

Register AL:

ASCII character or 00H(First byte of an extended ASCIIcode.)

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.

Direct Console Input Without Echo (07H)

Perform Direct Console Input from Standard Input Device Without Echo

Entry Parameters:

Register AH:

07H

Returned Values:

Register AL:

ASCII character or 00H(First byte of an extended ASCIIcode.)

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.

Console Input Without Echo (08H)

Read Character From Standard Input Device Without Echo

Entry Parameters:

Register AH:

08H

Returned Values:

Register AL:

ASCII character or 00H(First byte of an extended ASCIIcode.)

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 (09H)

Send a Character String to Standard Output Device

Entry Parameters:

Register AH:

09H

DS:

String address - Segment

DX:

String address - Offset

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 (0AH)

Read Characters from Standard Input Device into Input Buffer

Entry Parameters:

Register AH:

0AH

DS:

Buffer address - Segment

DX:

Buffer address - Offset

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.

Undisplayed Graphic

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.

Note: The user can use DR-DOS editing keys and the command line history buffer when entering characters.

Check Standard Input Status (0BH)

Obtain Status of Standard Input Device

Entry Parameters:

Register AH:

0BH

Returned Values:

Register AL:

FFH or 00H (No character available)

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.

Character Input with Buffer Flush (0CH)

Flush Type-ahead Buffer and Read Character(s) From Standard Input Device

Entry Parameters:

Register AH:

0CH

AL:

Input function number

Returned Values:

Register AL:

00H (No input function performed)

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 (0DH)

Flush All File Buffers

Entry Parameters:

Register AH:

0DH

Returned Values:

Register AX:

Error code

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 (0EH)

Select a Disk as Default Drive

Entry Parameters:

Register AH:

0EH

DL:

Drive

Returned Values:

Register AL:

Number of last drive

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 (0FH)

Open a File for I/O Operations

Entry Parameters:

Register AH:

0FH

DS:

Unopened FCB Address - Segment

DX:

Unopened FCB Address - Offset

Returned Values:

Register AL:

00H - on success0FFH - on failure

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.

Close File (10H)

Close a File Following Read/Write Operations

Entry Parameters:

Register AH:

10H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

Returned Values:

Register AL:

00H - On success0FFH - Directory not updated

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.

Search for First Entry (11H)

Find First File to Match Specified FCB

Entry Parameters:

Register AH:

11H

DS:

Unopened FCB Address - Segment

DX:

Unopened FCB Address - Offset

Returned Values:

Register AL:

00H - Match found0FFH - No match found

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.

Table 4-1
File Attribute Byte Values

Bit

Attribute

0Read/Only
1Hidden
2System
3Volume Label
4Subdirectory
5Archive

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.

Search for Next Entry (12H)

Find a Subsequent File Matching the Specified FCB of a Previous Search Call

Entry Parameters:

Register AH:

12H

DS:

Unopened FCB Address - Segment

DX:

Unopened FCB Address - Offset

Returned Values:

Register AL:

00H - Match found0FFH - No match found

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.

Delete File (13H)

Delete a Disk File

Entry Parameters:

Register AH:

13H

DS:

Unopened FCB Address - Segment

DX:

Unopened FCB Address - Offset

Returned Values:

Register AL:

00H - File deleted0FFH - No matching directory entries

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 (14H)

Sequentially Read Records from a Disk File

Entry Parameters:

Register AH:

14H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

Returned Values:

Register AL:

00H - On success

01H - End-of-file encountered, no data in record

02H - Insufficient space in DTA toread a single record

03H - End-of-file encountered, partial record read, zero-filled

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.

Sequential Write (15H)

Sequentially Write Records to a Disk File

Entry Parameters:

Register AH:

15H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

Returned Values:

Register AL:

00H - On success

01H - Disk full, operation cancelled

02H - Insufficient DTA space, operation cancelled

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 (16H)

Create a Disk File

Entry Parameters:

Register AH:16H

DS:

Unopened FCB Address - Segment

DX:

Unopened FCB Address - Offset

Returned Values:

Register AL:

00H - On open0FFH - No directory entry available

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 (17H)

Rename a Disk File

Entry Parameters:

Register AH:

17H

DS:

Modified FCB Address - Segment

DX:

Modified FCB Address - Offset

Returned Values:

Register AL:

00H - File renamed0FFH - File not found, or new name already in use

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 (19H)

Return Number of Current Default Drive

Entry Parameters:

Register AH:

19H

Returned Values:

Register AL:

Current drive number

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

Set Disk Transfer Address (1AH)

Set the Address of the Disk Transfer Area (DTA)

Entry Parameters:

Register AH:

1AH

DS:

Disk Transfer Area Address - Segment

DX:

Disk Transfer Area Address - Offset

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.

Allocation Table Address (1BH)

Return Information about Default Drive

Entry Parameters:

Register AH:

1BH

Returned Values:

Register DS

FAT ID byte address - segment

BX:

FAT ID byte address - offset

DX:

Number of clusters

AL:

Number of sectors per cluster

CX:

Physical sector size

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.

Allocation Table for Specific Drive (1CH)

Return Information about Specific Drive

Entry Parameters:

Register AH:

1CH

DL:

Drive Number

Returned Values:

Register DS:

FAT ID byte Address - Segment

BX:

FAT ID byte Address - Offset

DX:

Number of allocation units

AL:

Number of sectors per allocation unit

CX:

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.

Get Drive Parameter Block for Default Drive (1Fh)

Obtain details of disk parameters for current drive

Entry Parameters:

Register AH:

1Fh

Returned Values:

Register AL:

status00h successfulDS:BX - Drive Parameter BlockFFH invalid drive

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

Random Read (21H)

Randomly Read Records from a Disk File

Entry Parameters:

Register AH:

21H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

Returned Values:

Register AL:

00H - On success

01H - End-of-file encountered, no data available

02H - Insufficient space in DTA, operation cancelled

03H - End-of-file encountered,partial record read, zero-filled

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.

Random Write (22H)

Randomly Write Records to a Disk File

Entry Parameters:

Register AH:

22H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

Returned Values:

Register AL:

00H - On success

01H - Disk full, write cancelled

02H - Insufficient space in DTA,operation cancelled

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 (23H)

Return File Size

Entry Parameters:

Register AH:

23H

DS:

Unopened FCB Address - Segment

DX:

Unopened FCB Address - Offset

Returned Values:

Register AL:

00H - On success0FFH - No matching entry found

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.

Set Random Record Field (24H)

Set File Address of Random Record Field

Entry Parameters:

Register AH:

24H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

Returned Values:

None

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.

Set Vector (25H)

Set Interrupt Vector Table

Entry Parameters:

Register AH:

25H

DS:

Interrupt routine Address - Segment

DX:

Interrupt routine Address - Offset

AL:

Interrupt number (Hex)

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).

Create New Program Segment Prefix (26H)

Create a New Program Segment Prefix for the Calling Process

Entry Parameters:

Register AH:

26H

DX:

Segment number

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.

Note: You should not use this call in new programs; it is provided only to support existing programs. The preferred call for this function is Load and Execute Program(4BH).

Random Block Read (27H)

Randomly Read Multiple Records From a Disk File

Entry Parameters:

Register AH:

27H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

CX:

Record count

Returned Values:

Register AL:

00H - On success

01H - End-of-file encountered, no data available

02H - Insufficient space in DTA, operation cancelled

03H - End-of-file encountered, partial record read, zero-filled

CX:

Number of records read


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 (28H)

Randomly Write Multiple Records to a Disk File

Entry Parameters:

Register AH:

28H

DS:

Opened FCB Address - Segment

DX:

Opened FCB Address - Offset

CX:

Record count

Returned Values:

Register AL:

00H - On success

01H - Insufficient space on disk, no records written

02H - Insufficient space in DTA, operation cancelled

CX:

Number of records written

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.

Parse Filename (29H)

Parse Specified Filename and Initialize an FCB

Entry Parameters:

Register AH:

29H

DS:

Pointer to command line - Segment

SI:

Pointer to command line - Offset

ES:

Unopened FCB Address -Segment

DI:

Unopened FCB Address - Offset

AL:

Bit map (See below)

Returned Values:

Register DS:

First character following parsedname - Segment

SI:

First character following parsed name - Offset

ES:

First byte of formatted FCB - Segment

DI:

First byte of formatted FCB - Offset

AL:

00H - No wildcard characters used01H - Wildcard character in filename or extension 0FFH - Invalid drive specifier

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.

Get Date (2AH)

Returns Current System Date

Entry Parameters:

Register AH:

2AH

Returned Values:

Register AL:

Day of the week (0-6)

CX:

Year (1980-2099)

DH:

Month (1-12)

DL:

Day (1-31)

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.

Set Date (2BH)

Set the System Time and Date

Entry Parameters:

Register AH:

2BH

CX:

Year (1980-2099)

DH:

Month (1-12)

DL:

Day (1-31)

Returned Values:

Register AL:

00H Date was valid 0FFH Date was invalid

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.

Get Time (2CH)

Returns the Current System Time

Entry Parameters:

Register AH:

2CH

Returned Values:

Register CH:

Hours (0-23)

CL:

Minutes (0-59)

DH:

Seconds (0-59)

DL:

Hundredths (0-99)

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.

Set Time (2DH)

Set the System Time

Entry Parameters:

Register AH:2DH

CH:

Hours (0-23)

CL:

Minutes (0-59)

DH:

Seconds (0-59)

DL:

Hundredths (0-99)

Returned Values:

Register AL:

00H Time is valid 0FFH Time is invalid

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.

Set/Reset Verify Switch (2EH)

Set/Reset Verify Switch for Disk Write Operations

Entry Parameters:

Register AH:

2EH

DL:

00H

AL:

01H - Verify on 00H - Verify off

Returned Values:

None

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 (2FH)

Return Address of Current Disk Transfer Area (DTA)

Entry Parameters:

Register AH:

2FH

Returned Values:

Register ES:

Current DTA - Segment

BX:

Current DTA - Offset

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.

Get Version Number (30H)

Return DR-DOS Version Numbers

Entry Parameters:

Register AH:

30H

Returned Values:

Register AL:

Major version number

AH:

Minor version number

BX:

00H

CX:

00H

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.

Keep Process (31H)

Terminate the Currently Running Process

Entry Parameters:

Register AH:

31H

AL:

Exit code

DX:

Memory value - Paragraphs

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).

Get DOS Drive Parameter Block (32H)

Obtain details of disk parameters for specified drive

Entry Parameters:

Register AH:

32H

DL:

Drive number (00h=default, 01h=A:, etc)

Returned Values

AL:

status:00h successfulDS:BX - Drive parameter block (DPB) for specified drive (see table).FFh invalid drive

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

Table 4-2
Format of DOS Drive Parameter Block

Offset

Size

Description

00h BYTE drive number e.g 00h=A:, 01h=B:)
01h BYTE number within device driver.
02h WORD bytes per sector
04h BYTE highest sector number within a cluster.
05h BYTE shift count to convert clusters into sectors.
06h WORD number of reserved sectors at beginning of drive.
08h BYTE number of FATs
09h WORD number of root directory entries.
0Bh WORD number of first sector containing user data.
0Dh WORD highest cluster number (number of data clusters +1).
0Fh WORD number of sectors per FAT.
11h WORD sector number of first directory sector.
13h DWORD address of device driver header.
17h BYTE media ID byte
18h BYTE 00h if accessed, FFh if not.
19h DWORD pointer to next DPB.
1Dh WORD cluster at which to start search for free space when writing.
1Fh WORD number of free clusters on drive, FFFFh=not known.

Ctrl-Break Check (33H)

Check Status or Set Ctrl-Break Checking Mechanism

Entry Parameters:

Register AH:

33H

AL:

00H - Get Ctrl-Break State 01H - Set Ctrl-Break State

DL:

00H - Set Ctrl-Break Off01H - Set Ctrl-Break On

Returned Values:

Register DL:

00H - Ctrl-Break Off 01H - Ctrl-Break On

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.

Get Boot Drive (3305H)

Determine drive where the system was booted

Entry Parameters:

Register AX:

3305H

Returned Values:

Register DL:

Boot drive (1=A:, ...)

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

Get DR-DOS Version (3306H)

Get DR-DOS version

Entry Parameters:

Register AX:

3306H

Returned Values:

Register BL:

major version number

Register BH:

minor version

Register DL:

revision number in the low three bits. The other bits are reserved and set to zero.

Register DH:

The DR-DOS version flags which can be a combination of the following values:

DOSINROM (08h) - DR-DOS runs in ROM, otherwise it runs in RAM.

DOSINHMA (10h) - DR-DOS runs in high memory, otherwise it runs in conventional memory area.

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.

Get Vector (35H)

Return Address of Interrupt Vector For Specified Interrupt

Entry Parameters:

Register AH:

35H

AL:

Interrupt number (Hex)

Returned Values:

Register ES:

Interrupt routine Address - Segment

BX:

Interrupt routine Address - Offset

Keep Process (31H)

Terminate the Currently Running Process

Entry Parameters:

Register AH:

31H

AL:

Exit code

DX:

Memory value - Paragraphs

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 (36H)

Return Disk Free Space Information

Entry Parameters:

Register AH:

36H

DL:

Drive Number

Returned Values:

Register AX:

Number of sectors per cluster, 0FFFFH - Invalid drive number

BX:

Number of available clusters

DX:

Number of clusters in drive

CX:

Number of bytes per sector

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.

Set Country Dependent Information (38H)

Set the Country Code

Entry Parameters:

Register AH:

38H

AL:

FFH

BX:

New country code DX:0FFFFH

Returned Values:

Register AX:

Error code if the Carry flag is set

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

001 U.S.A045 Denmark
002 Canada (French)046 Sweden
003 S.America047 Norway
007 Russia049 Germany
031 Netherlands061 Australia
032 Belgium081 Japan
033 France082 Korea
034 Spain090 Turkey
036 Hungary351 Portugal
039 Italy358 Finland
041 Switzerland785 Middle East
043 Austria972 Israel
044 UK

Get Country Dependent Information (38H)

Get Country Dependent Information

Entry Parameters:

Register AH:

38H

AL:

FFH

BX:

Target country code

DS:

Pointer to buffer - Segment

DX:

Pointer to buffer - Offset

Returned Values:

Register AX:

Error code if the Carry flag is set

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.

Undisplayed Graphic

Figure 4-2
Country Dependent Data Return Block

Available countries are:

001 U.S.A045 Denmark
002 Canada (French)046 Sweden
003 S.America047 Norway
007 Russia049 Germany
031 Netherlands061 Australia
032 Belgium081 Japan
033 France082 Korea
034 Spain090 Turkey
036 Hungary351 Portugal
039 Italy358 Finland
041 Switzerland785 Middle East
043 Austria972 Israel
044 UK

The Date format is:

0M D Y - USA Standard
1D M Y - European Standard
2Y M D - Japanese Standard

The Currency format is:

Bit 0= 0 if currency symbol precedes value
= 1 if currency symbol follows value

Bit 1= 0 for 0 spaces between currency symbol and value
= 1 for 1 space between currency symbol and value

The Time format is:

Bit 0= 0 for 12-hour clock
= 1 for 24-hour clock

The Case Map call uses register AL as follows:

Entry ALASCII code for character 80H to convert to uppercase
Return ALASCII code for uppercase input character

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

Create a Subdirectory (39H)

Create a Subdirectory at the end of the Specified Path

Entry Parameters:

Register AH:

39H

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

Returned Values:

Register AX:

Error code, if Carry flag is set

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.

Remove a Subdirectory (3AH)

Remove a Subdirectory at the end of the Specified Path

Entry Parameters:

Register AH:

3AH

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

Returned Values:

Register AX:

Error code, if Carry flag is set

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 (3BH)

Set Current Directory as Specified in ASCIIZ String

Entry Parameters:

Register AH:

3BH

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

Returned Values:

Register AX:

Error code, if Carry flag is set

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 (3CH)

Create a Disk File

Entry Parameters:

Register AH:

3CH

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

CX:

File attribute

Returned Values:

Register AX:

16-bit handle, if Carry flag clear

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.

Open a File Handle (3DH)

Open a File Whose Name Matches Specified ASCIIZ String

Entry Parameters:

Register AH:

3DH

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

AL:

Access code

Returned Values:

Register AX:

Handle or error code

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:

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).

7 6 5 4 3 2 1 0
I S S S R A A A

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:

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

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 Deny None Sharing mode places no limitations on other processes.

Note: A file set to Read Only using ATTRIB can be opened by any number of processes in Compatibility mode - Read Access, Deny None - Read Access, or Deny Write - Read Access. If a Compatibility Mode Open fails due to a file sharing conflict, a critical error is generated. The error code is Not Ready, while function 59H returns File Sharing Conflict.

Close a File Handle (3EH)

Close a Specified File Handle

Entry Parameters:

Register AH:

3EH

BX:

File handle returned by Open or Create a File

Returned Values:

Register AX:

Error code, if Carry flag set

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.

Note: You should always close a file as soon as you finish using it.

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.

Erase a File from Directory (41H)

Erase Specified File From Directory

Entry Parameters:

Register AH:

41H

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

Returned Values:

Register AX:

Error code, if Carry flag set

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:

0Move pointer the number of bytes contained in CX:DX from the beginning of the file.
1Move pointer to the current location plus the offset contained in CX:DX.
2Move pointer to the end-of-file plus the specified offset;
this method can be used to determine the file’s size.

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:

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.

Notes:

This function call modifies only the Read Only (01H), Hidden (02H), System (04H) and Archive (20H) bits. You cannot change the volume and subdirectory attributes with this call.

If AL=3 on entry (set password), the file’s password mode is changed and, optionally, a new password is assigned. The following bits in CX are used to control passwords:

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
PW 0 0 0 R W E D R W E D R W E D

World

Group

Owner

If PW=1, a new password is assigned to the file or directory. The password is taken from the first 8 bytes of the current DMA address. The R, W, E, and D bits specify whether the password is to control Read, Write, Execute, or Delete access to the file. E is supported for compatibility with the FlexOS operating system, and is treated as an R bit. The present release of the DR-DOS operating system does not support owner or group identifications, and you should therefore set the same access restrictions for all three bit fields (world, group, and owner) when you set a password mode.

The R, W, and D bits provide 3 levels of password protection to a file or directory:

RThe highest level of protection, preventing anyone from reading a file until the password is issued.
WThe next level of protection. The file can be displayed on the screen, but cannot be changed without the password. This restricts editing, copying, renaming, and deleting.
DThe lowest level of protection. The file can be displayed and changed, but a password is needed to delete or rename the file.

If the Carry flag is set, this call returns 2, 3, or 5 in AX. See Chapter 5, Error Handling, for error code definitions.

Device I/O Control (44H)

This function performs operations for setting or obtaining information for input and output from character and block devices. The operation performed depends on the value supplied in register AL on entry.

Value of AL

Operation performed

00H

Obtain information about a device

01H

Set information for a device

02H

Receive a control string from a characterdevice driver

03H

Send a control string to a character device driver

04H

Receive a control string from a block device driver

05H

Send a control string to a block device driver

06H

Enables application to check directly whether the device is ready for input

07H

Enables application to check directly whether the device is ready for output

08H

Checks whether the media on a block device is removable

09H

Determines whether the device is networked

0AH

Checks whether a handle refers to a local or a networked device

0BH

Controls retries on sharing and lock resource conflicts

0CH

Supports code page switching

0DH

Enables an application to request the device driver to perform functions on a block device

0EH

Checks whether there is more than one logical drive assigned to a block device and which was the last drive to be used

0FH

Sets the number of the next logical drive for use on a block device.

10h

Determines whether the specified IOCTL is supported by the device driver.

11h

Determines whether the specified IOCTL function is supported for the given drive.

The entry and return values for each operation are described fully in Appendix A, Device I/O Control.

Query Generic IOCTL (4410H)

Determine if character device supports generic IOCTL call

Entry Parameters:

Register AH:

4410H

Register BX:

Handle for device

Register CH:

Category code (see function 44h 0ch)

Register CL:

Function code

Returned Values:

Register AX:

CF clear if successful
AX=000h specified IOCTL function is supported.
CF set on error
AL=01h IOCTL not available.

Query Generic IOCTL (4411H)

Determine if block device supports generic IOCTL call

Entry Parameters:

Register AH:

4411H

BL:

Drive number

CH:

Category code (see function 44h 0Dh)

CL:

Function code

Returned Values:

Register AX:

CF clear if successful
AX=000h specified IOCTL function is supported.
CF set on error
AL=01h IOCTL not available.

Duplicate a File Handle (45H)

Return a Duplicate of an Existing File Handle

Entry Parameters:

Register AH:

45H

BX:

File handle

Returned Values:

Register AX:

New file handle, if Carry flag not set

This call returns a duplicate of the file handle contained in BX on entry. It can be used to update the directory entry for a file without the overhead of closing and re-opening the file. For example this call, followed by a Close File (3EH) call with the duplicate handle, causes DR-DOS to flush the buffers and update the directory entry while the original file remains open for Reading or Writing. The duplicate handle refers to the same file in the same directory. If you move the read/write pointer of either handle with the Read (3FH), Write (40H), or Move Pointer (42H) calls, the pointer for the other handle is also moved.

On return, if the Carry flag is set, this call returns error code 4 or 6 in AX. Error code 4, No File Handles, indicates that the number of open files exceeds system limits; error code 6 indicates an illegal file handle.

Force a Duplicate of a Handle (46H)

Force a Duplicate File Handle to Use Same Input as an Existing File Handle

Entry Parameters:

Register AH:

46H

BX:

Existing file handle

CX:

Second file handle

Returned Values:

Register AX:

Error code, if Carry flag set

This call forces the file handle in CX to refer to the same file as the handle contained in BX. If the existing file handle passed in CX refers to an open file, this call closes the file before forcing duplication. If you move the read/write pointer of either handle with the Read (3FH), Write (40H), or Move Pointer (42H) calls, the pointer for the other handle is also moved.

On return, if the Carry flag is set, this call returns error code 6 in AX to indicate that an invalid handle has been specified.

The call can be used for redirecting input/output.

Get Current Directory (47H)

Return Full Pathname of Current Directory for Specified Drive

Entry Parameters:

Register AH:

47H

DL:

Drive number (0 = default, 1 = A, 2 = B, and so on)

DS:

Path name Address - Segment

SI:

Path name Address - Offset

Returned Values:

Register AX:

Error code, if Carry flag is set

The Get Current Directory call writes the full path name of the current directory for the drive specified in DL to the 64-byte area of user memory pointed to by DS:SI. Get Current Directory does not include the drive letter or the leading backslash in the path name, and terminates the path name string with 00H.

If DL does not contain a legal drive number, Get Current Directory sets the Carry flag and returns error code 15, Invalid Drive Specified, in register AX.

Allocate Memory (48H)

Allocate Specified Number of Paragraphs to Calling Process

Entry Parameters:

Register AH:

48H

BX:

Number of paragraphs

Returned Values:

Register AX:

Address of block - segmentError code, if Carry flag set

BX:

Largest available block (on failure)

The Allocate Memory call allocates a requested number of paragraphs of memory. On entry, BX contains the number of paragraphs requested.

On return, if the call is successful AX contains a pointer to the allocated memory block. If the call fails, the Carry flag is set, AX contains error code 7 or 8 and BX contains the size, in paragraphs, of the largest available block of memory.

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

Free Allocated Memory (49H)

Free Specified Memory for Reallocation

Entry Parameters:

Register AH:

49H

ES:

Address of Block - Segment

Returned Values:

Register AX:

Error code, if Carry flag is set

The Free Allocated Memory call releases the specified memory for reallocation. On entry, ES contains the segment address of the block to be freed.

There are no return parameters. If the Carry flag is set, Free Allocated Memory returns error code 7 or 9 in AX. See Chapter 5, Error Handling, for the error code definitions.

Modify Allocated Memory Blocks (4AH)

Modify Memory to Contain Specified Block Size

Entry Parameters:

Register AH:

4AH

BX:

Number of paragraphs

ES:

Block Address - segment

Returned Values:

Register AX:

Error code, if Carry flag is set

BX:

Largest available block (on failure),if Carry flag is set

This call changes a memory block allocation to the specified block size. On entry, ES contains the segment address of the allocated memory block, and BX contains the new requested block size, in paragraphs. DR-DOS attempts to increase or decrease the allocated block size according to the contents of BX.

If DR-DOS cannot increase the size of the allocated block, Modify Allocated Memory Blocks returns the maximum possible block size in BX. If the Carry flag is set, Modify Allocated Memory Blocks returns error code 7, 8, or 9 in AX. See Chapter 5, Error Handling, for error code definitions.

Load and Execute (4BH)

Load a program into memory

Entry Parameters:

Register AH:

4BH

BX:

ES:

Returned Values:

Register AX:

Error code, if Carry flag is set

BX:

Largest available block (on failure),if Carry flag is set

The ASCIIZ string addressed by DS:DX must include the name and filetype of the file to be loaded. The drive and path name are optional.

Because DR-DOS has previously allocated all available memory to the current program, you must free enough memory for the file to be loaded. Before calling Load and Execute, use Modify Allocated Memory Blocks (4AH) to reduce the allocated memory to the minimum required by the current program.

The format of the Load Parameter Block (LPB) pointed to by ES:BX is dependent upon the type of Load and Execute call being made. See Figures 4-3 and 4-5.

If Load and Execute returns with the Carry flag set, register AX contains one of the following error codes: 1, 2, 7, 8, 10, or 11. See Chapter 5, Error Handling, for error code definitions.

Load and Execute (AL = 00H on Entry)

If AL contains 00H on entry, Load and Execute creates a Program Segment Prefix (PSP) at offset 0 in the program segment and sets its terminate address and Ctrl-Break address fields to the instruction following the Load and Execute call. Load and Execute then loads the program indicated in the ASCIIZ string at offset 100H within the program segment and gives it control. All registers are changed on return from a Load and Execute call.

Undisplayed Graphic

Figure 4-3
Load and Execute Parameter Block

You must restore the stack segment, stack pointer, and any other required registers. The program can return from Load and Execute in one of five ways:

When control returns to the process that called Load and Execute, interrupt vectors 22H, 23H, and 24H are restored from the values in the terminate address, Ctrl-Break address, and critical error exit address fields of the child’s Program Segment Prefix.

All files that the parent opens with the inheritance bit set to zero are duplicated by DR-DOS for the child created by the Load and Execute call. The new process inherits the standard input, output, printer, and auxiliary device definitions from the calling process. The child process also inherits a block of text strings or “environment” from the calling process. If the value of the Environment String Address field in the Load Parameter Block is 0000H, the child process inherits the environment unchanged. Note that the environment must always be located on a paragraph boundary.

Table 4-3 defines the fields in the Parameter Block.

Table 4-3
Load Parameter Block Fields

Field

Definition

Environment String Address

Word address (segment) of theenvironment passed to PSP.

Command Line Address

Double-word address of command line to be placed at offset 80H in PSP.

First FCB Address

Double-word address of FCB to beplaced at offset 5CH in PSP.

Second FCB Address

Double-word address of FCB to beplaced at offset 6CH in PSP.

Figure 4-4 shows the format of the environment string.

Undisplayed Graphic

Figure 4-4
Environment String Format

Load Overlay (AL = 03H on Entry)

If the calling process passes 03H in AL on entry, DR-DOS loads the program indicated in the ASCIIZ string, but does not establish a PSP or begin executing the program. Load Overlay loads the program in the segment pointed to by the Load Parameter Block depicted in Figure 4-5. Use this type of Load call to load program overlays. Figure 4-6 shows the Program Segment Prefix.

Undisplayed Graphic

Figure 4-5
Load Overlay Parameter Block

Table 4-3 defines the fields in the Parameter Block.

Table 4-4
Load Overlay Parameter Block Fields

Field

Definition

Overlay Segment

Word address of segment in which to load file.

Relocation Factor

Fix-up segment to be applied to the image.

Figure 4-6
Program Segment Prefix

Undisplayed Graphic

Load Program (4B01H)

Load a program into memory

Entry Parameters:

Register AH:

4BH

AL:

01h

ES:

Returned Values:

Register AX:

Error code, if Carry flag is set

BX:

Largest available block (on failure), if Carry flag is set

This function loads a program into memory and creates a new segment prefix (PSP) but does not transfer control to the new program.

Set Execution State (4B05H)

Prepares new program for execution

Entry Parameters:

Register AH:

4B05H

DS:DX:

execution state structure (see table)

Returned Values:

Register AX:

CF clear if successful
AX=000hCF set on error
AX=error code (see 59h)

This function prepares a new program for execution. This includes setting the DR-DOS version number for the program as specified by the SETVER command.

This function is required for programs that intercept function 4B00h. When the function returns, the calling program has to transfer execution control to the new program as soon as possible. Before starting the new program, no DOS, BIOS or other software interrupts may be called.

If DR-DOS is running in high memory, the A20 line is turned off making the HMA inaccessible.

Table 4-5
Format of Execution State Structure

Offset

Size

Description

00h

WORD

reserved (00h)

02h

WORD

type flags
bit 0:program is .EXE
bit 1:program is an overlay.

04h

DWORD

pointer to ASCIZ name of program file

08h

WORD

PSP segment of new program.

0Ah

DWORD

starting CP:IP of new program.

0Eh

DWORD

program size including PSP.

Terminate a Process (4CH)

Terminate Current Process and Return Control to Calling Process

Entry Parameters:

Register AH:

4CH

AL:

Return code

The Terminate a Process call terminates the current process and returns control to the process that invoked Load and Execute (4BH). Terminate a Process also closes any handles opened by the current process. The calling process can place a binary return code in register AL before invoking Terminate a Process. This code can then be retrieved by the parent process through Get Subprocess Return Code (4DH).

Get Subprocess Return Code (4DH)

Return Completion Code to Calling Process

Entry Parameters:

Register AH:

4DH

Returned Values:

Register AX:

Exit code

The Get Subprocess Return Code call returns the binary exit or completion code specified by another process with the Keep Process (31H) or Terminate a Process (4CH) calls. The low byte of register AX contains the exit code specified by the terminating process; the high byte can return one of the following values:

Find First Matching File (4EH)

Find First Filename to Match Specified ASCIIZ String

Entry Parameters:

Register AH:

4EH

DS:

ASCIIZ string Address - Segment

DX:

ASCIIZ string Address - Offset

CX:

File attribute

Returned Values:

Register AX:

Error code if Carry flag is set

The Find First Matching File call searches for the first file that matches the filename specified in the ASCIIZ string to which DS:DX points on entry. The ASCIIZ string contains a drive, path, and filename to be matched. The filename portion of the ASCIIZ string may include question mark characters, which match any character in the same position in the filename.

Register CX contains the file attribute which specifies which files are to be included in the search. The use of the file attribute byte during a search is explained in the description of Search for First Entry (11H). If the call finds a matching file it places the following information in the Disk Transfer Area (DTA) of the calling program:

21 bytes Reserved for use with subsequent Find Next Matching
File (4FH) calls

1 byte Attribute of matching file

2 bytes Matching file’s time of creation

2 bytes Matching file’s date of creation

2 bytes Low word of matching file’s size

2 bytes High word of matching file’s size

13 bytes Matching file’s filename and extension, followed by a
byte of zeros

On return, if the Carry flag is set, AX contains error code 2 or 18. Error code 2 indicates that the file was not found. Error code 18 indicates that no matching files could be found, when question mark characters were used.

Find Next Matching File (4FH)

Find Next Matching File From Previous Find First Call

Entry Parameters:

Register AH:

4FH

Returned Values:

Register AX:

Error code, if Carry flag is set

The Find Next Matching File call searches for the next file matching the filename specified in a previous Find First Matching File (4EH) call or Find Next Matching File (4FH). On entry, the Disk Transfer Area (DTA) must contain the information supplied by a previous Find First File (4EH) call.

If a matching file is found, this call sets the calling program’s DTA as described under Find First Matching File, above. If no additional matching files are found, this call returns error code 18, No More Matching Files, in AX.

Get Verify State (54H)

Return Current Value of Verify State

Entry Parameters:

Register AH:

54H

Returned Values:

Register AL:

00H - Verify off01H - Verify on

Get Verify State returns the value of the Verify flag. Get Verify State returns 01H in AL if Verify is on, 00H if Verify is off.

Rename a File (56H)

Rename a File to Specified ASCIIZ String

Entry Parameters:

RegisterAH:56H
DS:ASCIIZ string Address - Segment
DX:ASCIIZ string Address - Offset
ES:ASCIIZ string Address - Segment
DI:ASCIIZ string Address - Offset

Returned Values:

Register AX:

Error code, if Carry flag is set

The Rename a File call renames the file specified using the ASCIIZ string pointed to by DS:DX, which contains the drive, path, and name. The ASCIIZ string passed in ES:DI contains the path and new filename. If a drive is specified in the second ASCIIZ string, it must be the same as that specified in the first string. On return, if the Carry flag is set, AX may contain error code 3, 5, or 17. See Chapter 5, Error Handling, for error code definitions.

Get/Set Time and Date Stamps (57H)

Set or Obtain a File’s Date and Time of Creation

Entry Parameters:

,/tr>
RegisterAH:57H
AL:00H - Get date/time
01H - Set date/time
BX:File handle
CX:Time to be set (Set date/time only)
DX:Date to be set (Set date/time only)

Returned Values:

RegisterDX:Current date (Get date/time only)
CX:Current time (Get date/time only)

This call gets or sets the date and time that a file was last modified. If AL contains 01H on entry, this call sets a file’s time and date to the values contained in CX and DX. If AL contains zero on entry, this call returns a file’s time and date in CX and DX. Date and time formats are the same as the formats for a DOS directory entry. The time and date formats are shown in Figures 4-7 and 4-8, respectively.

Undisplayed Graphic

Figure 4-7
Time Format

h is the binary number of hours, 0 through 23
m is the binary number of minutes, 0 through 59
s is the binary number of two second increments

Undisplayed Graphic

Figure 4-8
Date Format

y is the binary number of years, 0 through 119 (1980-2099)
m is the binary number of months, 1 through 12
d is a binary number of days, 1 through 31

On return, if the Carry flag is set, AX may contain error code 1 or 6. See Chapter 5, Error Handling, for the error code definitions.

Get Memory Allocation Strategy (58H)

Gets the method DR-DOS uses to allocate memory

Entry Parameters:

Register AH:

58h

AL:

subfunction
00h get allocation strategy

Returned Values:

Register AX:

CF set on error
AX = error code (01h) see function 59h
CF clear if successful
AX = current strategy:
00h low memory first fit
01h low memory best fit
02h low memory last fit
40h high memory first fit
41h high memory best fit
42h high memory last fit
80h first fit, try high then low memory
81h best fit, try high then low memory
82h last fit, try high then low memory

Set Memory Allocation Strategy (5801H)

Sets the method DR-DOS uses to allocate memory

Entry Parameters:

Register AH:

58h

AL:

subfunction
01h set allocation strategy

Returned Values:

Register BL:BH:

new allocation strategy (see above function)00h

Get Upper Memory Link State (5802H)

Entry Parameters:

Register AH:

58h

AL:

subfunction
02h get UMB link state

Returned Values:

Register AL:

00h UMBs not part of the DR-DOS chain.
01h UMBs in DR-DOS memory chain.

Set Upper Memory Link State (5803H)

Entry Parameters:

Register AH:

58h

AL:

subfunction
03h set UMB link state

Returned Values:

Register BX:

0000h remove UMBs from the DR-DOS memory chain.
0001h add UMBs to memory chain.

See also functions 48h, 49h and 4Ah.

Get Extended Error (59H)

Get Extended Error Information

Entry Parameters:

Register AH:

59H

BX:

0000H

Returned Values:

Register AX:Extended error
Register BH:Class of error
Register BL:Response
Register CH:Resource

This function can be called from Interrupt 21H function calls which return a Carry-flag error, Interrupt 24H error handlers and FCB function calls which return FFH in order to obtain further error information. The contents of registers DX, SI, DI, ES, CL and DS are destroyed on return.

Class of Error

The contents of Register BH give details of the type of error.

Value

Description

1

Out of Resource: Insufficient space, channels, and so on.

2

Temporary Situation: A temporary error that will resolve itself without specific remedial action.

3

Authorization: Problem with access permission.

4

Internal: System software error. Not a user problem or system failure but a suspected bug in the system software.

5

Hardware Failure: A major problem. Not a user program error.

6

System Failure: Serious system software failure, possibly involving configuration files.

7

Application Program Error: For example several processes may be trying to open the same file.

8

Not Found: File or item not located.

9

Bad Format: File or item of invalid type, format or in some other way invalid or inappropriate.

10

Locked: File or item interlocked.

11

Media: Media failure. Wrong disk inserted in drive, bad area on disk, and so forth.

12

Already Exists: Attempt to use an item that already exists.

13

Unknown: Unavailable or inappropriate classification.

Responses

Suggested responses to the error conditions are given in BL, as follows:

Value

Description

1

Retry: Retry several times then provide a prompt for the user to decide whether the program should be continued or aborted.

2

Delay Retry: Retry several times, pausing each time, then provide a prompt for the user to decide if the program should be continued or aborted.

3

User: Request user to rekey input. The user may have mistyped a parameter used in the system call and should be requested to rekey the input. DR-DOS will not request a retry for values supplied directly by a program.

4

Abort: Discontinue the application with a tidy closedown. The application cannot continue, but the system can close down tidily.

5

Immediate Exit: Abort application without closedown. The application should be abandoned at once without attempting to close files or update indexes.

6

Ignore: Ignore.

7

Retry After User Intervention: The user should perform an action such as checking that the printer is on line, before retrying the operation.

Resource

These values give details of the physical resource that caused the error, in CH.

Value

Description

1

Unknown: Non-specific. Not appropriate.

2

Block Device: Refers to random access mass storage.

3

Net: Refers to the network.

4

Serial Device: Refers to serial devices.

5

Memory: Refers to random access memory.

Create Unique File (5AH)

Create a File with a Unique Filename

Entry Parameters:

RegisterAH:5AH
CX:Attribute
DS:Pointer to ASCIIZ path with final backslash - Segment
DX:Pointer to ASCIIZ path with final backslash - Offset

Returned Values:

RegisterAX:Error code if Carry flag is set, file handle if not
DS:new filename appended to ASCIIZ path - Segment
DX:new filename appended to ASCIIZ path - Offset

The function appends a unique filename to the end of the path supplied and attempts to create this file. If the file already exists a new filename is generated and the process is repeated. The file is opened in Compatibility mode with Read/Write access. It will not automatically be deleted when the program ends.


Create New File (5BH)

Create a New File

Entry Parameters:

RegisterAH:5BH
CX:Attribute
DS:ASCIIZ string address - Segment
DX:ASCIIZ string address - Offset

Returned Values:

RegisterAX: Error code if Carry flag is set, file handle if not

This call is the same as 3CH except that it will fail if the filename already exists. The file is opened in Compatibility mode with Read/Write access.

Lock/Unlock File Access (5CH)

Lock or Unlock Bytes in an Opened File

Entry Parameters:

RegisterAH:5CH
AL:00H to lock
01H to unlock
BX:File handle
DX:High offset
CX:Low offset
SI:High length
DI:Low length

Returned Values:

Register AX:

Error code if Carry flag is set

This call should only be used in the Deny Read or Deny None sharing modes. It offers a simple way to deny other processes Read/Write access to regions of a file for a limited time. These regions can be anywhere in the file, but it is recommended that this call be used only over short durations.

Note: If SHARE is not loaded, error 1 Illegal Function is returned.

Set Extended Error Information (5D0AH)

Modifies extended error information returned by function 59h

Entry Parameters:

RegisterAH:5D0Ah
DS:DX:DR-DOS Parameter list

Returned Values:

None. The next call to function 59h returns values from fields AX, BX, CX, DX, DI and ES in the corresponding registers.

Table 4-6
Format of DR-DOS Parameter List

Offset

Size

Description

00h

WORD

AX

02h

WORD

BX

04h

WORD

CX

06h

WORD

DX

08h

WORD

SI

0Ah

WORD

DI

0Ch

WORD

DS

0Eh

WORD

ES

10h

WORD

reserved (0)

12h

WORD

computer ID (0=current system)

14h

WORD

process ID (PSP segment on specified computer)

Get Machine Name (5E00H)

Gets the Machine Name

Entry Parameters:

RegisterAX:5E00H
DS:DX Pointer to the buffer where the ASCIIZ machine name is returned

Returned Values:

RegisterAX:Error code if the Carry flag is set
CH:Validity of machine name
0 = name/number not defined
not 0 = name/number defined
CL:NETBIOS number for the machine name

This call returns the current machine name, used to identify the machine to the network. The name is a 16-byte ASCIIZ string. If the name has not been set, CH returns with 00H, and the value in CL is invalid. The local area network program must be loaded, otherwise the results of this function are unpredictable.

Note: This call is supported only if the network program is loaded.

Set Printer Setup (5E02H)

Sets the Printer Setup String for Printer Files

Entry Parameters:

RegisterAX:5E02H
BX:Redirection list index
CX:Length of setup string
(max. of 64 bytes)
DS:SIPointer to printer setup string

Returned Values:

RegisterAX: Error code if the Carry flag is set

All files sent to a given network printer are preceded by the specified string. This call allows several users to specify their own mode of operation for that printer. The redirection list in BX is an index to a table that identifies the printer as a device on the network. BX is set to the same index as is used in the Get Redirection List Entry (5F02H) call. If print redirection is paused, or if the local area network program is not loaded, an error code is returned.

Error codes are returned in AX. Use the Get Extended Error (59H) function call to determine the actual error condition.

You should issue the Set Printer Setup call immediately after you issue Get Redirection List Entry (5F02H), because the redirection index value may change if a Redirect Device (5F03H) call or a Cancel Redirection (5F04H) call is issued between the time the redirection list is scanned and the Set Printer Setup (5E02H) call is issued.

Note: This call is supported only if the network program is loaded.

Get Printer Setup (5E03H)

Returns the Printer Setup String for Printer Files

Entry Parameters:

RegisterAX:5E03H
BX:Redirection list index
ES:DIPointer to printer setup buffer

Returned Values:

RegisterAX:Error code if the Carry flag is set
CX:Length of printer setup string (bytes)
ES:DIPointer to printer setup string

This call returns the printer setup string specified by the Set Printer Setup (5E02H) call. The value in BX is set to the same as for the Set Printer Setup call. If the local area network is not loaded, error code 1, Invalid Function Number, is returned.

Error codes are returned in AX. Use the Get Extended Error (59H) function call to determine the actual error condition.

You should issue Get Printer Setup immediately after you issue Get Redirection List Entry (5F02H), because the redirection index value may change if a Redirect Device (5F03H) call or a Cancel Redirection (5F04H) call is issued between the time the redirection list is scanned and the Get Printer Setup (5E02H) call is issued.

Note: This call is supported only if the network program is loaded.

Get Redirection List Entry (5F02H)

Returns a List of Network Redirection

Entry Parameters:

RegisterAX:5F02H
BX:Redirection index (zero-based)
DS:DIPointer to 128-byte buffer for the local device name
ES:DIPointer to 128-byte buffer for the network name

Returned Values:

RegisterAX:Error code if Carry flag is set
BH:Device status flag
Bit 0 = 0 Device valid
= 1Device invalid
Bits 1-7 reserved
Device type
BL:03 = Printer
04 = File
Stored parameter value
CX:Destroyed
DX:Destroyed
BP:Pointer to ASCIIZ local name
DS:DIPointer to ASCIIZ network name
ES:DI

This call returns a list of network redirections for devices on the network. These redirections are created through the Redirect Device (5F03H) call. The call is not affected if either disk or print redirection is paused. Each call returns one redirection, so BX should be incremented by 1 each time to step through the list. Note, though, that the contents of the list may change between calls. Error code 18, No More Files, identifies the end of the list. Error code 1, Invalid Function Number, is returned if the local area network program is not loaded.

Error codes are returned in AX. Use the Get Extended Error (59H) function call to determine the actual error condition.

Note: This call is supported only if the network program is loaded.

Redirect Device (5F03H)

Set Redirection List Entries

Entry Parameters:

RegisterAX:5F03H
BL:Device type
03 = Printer device
04 = File device
CX:Value to save for caller
DS:SIPointer to ASCIIZ local device name
ES:DIPointer to ASCIIZ network path with password

Returned Values:

RegisterAX: Error code if the Carry flag is set


This call defines network redirection of printers and disk directories on the network. It establishes redirection list index numbers for the redirected devices.

Printer Device

If BL = 03, the source string specifies a local printer, pointed to by DS:SI, and the destination string specifies a network path pointed to by ES:DI. The source string must be one of the following printer names: PRN, LPT1, LPT2, or LPT3 (each ending with 00H). The destination string must point to a network name string of the following form:

\\machinename\pathname,null,password,null

The ASCIIZ password can be a maximum of eight characters, and must follow immediately after the network string. A null (zero-length) password is considered to be no password.

Register CX should be set to 0; values other than 0 are reserved for the local area network program. CX has a word that DOS maintains for the programmer, and this word can be retrieved through the Get Redirection List (5F02H) call. All output to the specified printer is buffered, and sent to the network printer spooler for that device. The printers are redirected at the INT 17H level.

File Device

If BL = 04, the source string, pointed to by DS:SI, specifies a drive letter and colon (ending with 00H) or it can be a null string. The destination, pointed to by ES:DI, specifies an ASCIIZ network path. If the source string represents a valid drive letter, an association is made between the drive letter and the network path. All subsequent references to the drive letter are translated to references to the network path. If DS:SI points to a null string, the system attempts to grant access to the destination with the specified password without redirecting any device.

The ASCIIZ password for access to the remote path must follow immediately after the network string. A null (zero-length) password is considered to be no password.

Register CX should be set to 0; values other than 0 are reserved for the local area network program. CX has a word that DOS maintains for the programmer, and this word can be retrieved through a Get Redirection List (5F02H) call.

Error codes are returned in AX. Use the Get Extended Error (59H) function call to determine the actual error condition.

Notes:

This call is supported only if the network program is loaded.

Devices redirected through the Redirect Device call are not displayed by the NET USE command.

An error is returned if you try to redirect a file device while disk redirection is paused, or if you try to redirect a printer while print redirection is paused.

Only the application that redirects a device can get access to that device.

Cancel Redirection (5F04H)

Cancels a Redirection

Entry Parameters:

RegisterAX:5F04H
DS:SIPointer to ASCIIZ device name or path

Returned Values:

RegisterAX:Error code if Carry flag is set

This call cancels a redirection created by the Redirect Device (5F03H) call.

If DS:SI points to a drive letter and the drive is associated with a network name, the association is terminated, and the drive is restored to its original physical meaning.

If DS:SI points to a redirected printer (PRN, LPT1, LPT2, or LPT3), and the device has an association with a network device, the association is terminated and the device is restored to its original physical meaning.

If DS:SI points to a network path, the association between the local machine and the network directory specified in the string is terminated.

An error is returned if you try to cancel a redirected file device while disk redirection is paused, or if you try to cancel a redirected printer while print redirection is paused. Error code 1, Invalid Function Number, is returned if the local area network program is not loaded.

Error codes are returned in AX. Use the Get Extended Error (59H) function call to determine the actual error condition.

Note: This call is supported only if the network program is loaded.

Get Program Segment Prefix Address (62H)

Return Current Program Segment Prefix Address

Entry Parameters:

Register AH:

62H

Returned Values:

Register BX:

Segment address of Current Program Segment Prefix

Get Extended Country Information (65H)

Return More Information on Country Codes

Entry Parameters:

RegisterAH:65H
AL:1, 2, 4, 5, 6, or 7, depending on information sought
BX:Code page of interest (-1 = active CON device)
DX:Target country code (-1 = default)
CX:Amount of information to be returned (minimum: 5)
ES:DIPointer to buffer where information is returned

Returned Values:

RegisterAX:Error code if Carry flag is set
ES:Extended Country Information table
DI:Extended Country Information table

The country code and the code page must match: otherwise an error code of 2 (File Not Found) is returned in AX. If more information is provided than requested by CX, it is truncated without generating an error. The value of AL determines precisely what information is provided.

Note that NLSFUNC must be loaded to return anything except information on the default country and code page.

Figure 4-9 shows the response when AL = 01H.

When AL = 02H, the response is a 1-byte function ID (02H) followed by a 4-byte doubleword pointer to the uppercase table. This table starts with a 2-byte length field followed by 128 bytes of uppercase values for ASCII characters.

When AL = 04H, the response is a 1-byte function ID (04H) followed by a 4-byte doubleword pointer to the filename uppercase table. This table starts with a 2-byte length field followed by 128 bytes of uppercase values for ASCII characters.

When AL=05h it returns the address of the filename-character table for the specified code page and country code.

When AL = 06H, the response is a 1-byte function ID (06H) followed by a 4-byte doubleword pointer to the collating sequence. This table starts with a 2-byte length field followed by 256 ASCII values placed in order.

When AL = 07H, the response is a 4-byte double-word pointer to the Double Byte Character Set (DBCS) table. The format of the table is shown in Figure 4-10. Each entry in the table specifies a range of characters that are recognized as lead bytes in double-byte characters.

Undisplayed Graphic

Figure 4-9
Extended Country Information (AL = 01)

Undisplayed Graphic

Figure 4-10
Double Byte Character Set Table

For example, the Double Byte Character Set table for code page 932, country code 81, Japan, is as follows:

Undisplayed Graphic

Any value lying within the range 81H to 9FH, inclusive, or E0H to FCH, inclusive, is a valid Kanji lead byte, that is, the first byte of a double-byte character.

Character Capitalization (65H 20h-22h)

Country dependent character capitalization

Entry Parameters:

RegisterAH:65H
AL:20H capitalize character
DL=character to capitalize
Return: DL=capitalized character
21h capitalize string
DS:DX - string to capitalize
CX =length of string
22h capitalize ASCIZ string
DS:DX - ASCIZ string to capitalize

Returned Values:

RegisterAX:CF set on error
AX =error code - see function 59h
CF clear if successful

Get/Set Global Code Page (66H)

Get/Set Current Country’s Code Page

Entry Parameters:

RegisterAH:66H
AL:01H to get global code page
02H to set global code page
BX:Requested code page (whenAL=02H)

Returned Values:

RegisterAX:Error code if Carry flag is set
BX:Global code page (when AL=01H)
DX:DOS system code page (whenAL=01H)

This call, when used to set the global code page, causes the correct code page data to be read from COUNTRY.SYS and placed in the country information data area. A code page SELECT to the new code page is then performed on all devices that support code page switching. These devices are determined by their declaration in CONFIG.SYS.

If any device fails to SELECT, error code 65H is returned in AX, and the Carry flag is set.

If the code page is not valid for the current country, or the COUNTRY.SYS file cannot be opened or read, error code 02H is returned in AX, and the Carry flag is set.

Note: NLSFUNC must be loaded to change the global code page.

Set Handle Count (67H)

Allow a Process to Open More than 20 Files

Entry Parameters:

RegisterAH:67H
BX:Number of open handles to be permitted (max. 64K)

Returned Values:

RegisterAX:Error code if Carry flag is set

This call is used to modify the maximum number of open handles a process is permitted. Additional memory must be released, using the Modify Allocated Memory Block (4AH) call, to contain the extended handle list.

If the requested number of handles is less than 20, the number is rounded up to 20.

Commit File (68H)

Write Buffered Data for a File to the Device

Entry Parameters:

Register AH:68H
Register BX:File Handle

Returned Values:

None

This function updates the directory entry for the open file and flushes all data and FAT buffers associated with the file. It has the same effect as closing the file and reopening it but offers a more secure way of changing file information in a multiuser network, for example.

Extended Open/Create (6CH)

Combines older Open and Create functions into single function

Entry Parameters:

RegisterAH:6CH
BL:Open mode as in AL for normal Open.
BH:flags
bit 6=auto commit on every write (see also 68h)
bit 5=return error rather than doing INT 24h.
CX:create attribute
DL:action if file exists/does not exist
0000 fail
0001 create
bit 3-0 action if file exists
0000 fail
0001 open
0010 replace/open
DH:00h (reserved)
DS:SI:ASCIZ file name

Returned Values:

AX:CF set on error
AX=error code (see table)
CF clear if successful
AX=file handle
CX=status
1 file open
2 file created
3 file replaced

[Front] [Prev Chapter] [Next Chapter]


info@caldera.com
Copyright © 1993, 1997 Caldera, Inc All rights reserved.