BIOS and DOS Interrupt Functions

All BIOS and DOS calls which are used are documented here. No attempt is made at an exhaustive list, since such information has been published abundantly in a variety of sources.

Interrupt 10H: BIOS Video Services

Function 0E Hex: Write TTY to Active Page

Registers ah = 0EH

al = Character to display bl = Forground color, in graphics modes

Returns: None

This function displays the character in al on the screen at the current cursor location and advances the cursor by one position. It interprets al=0DH as a carriage return, al=0AH as a line feed, al=08 as a backspace, and al=07 as a bell. When used in a graphics mode, bl is made the foreground color.

In text modes, the character attribute is left unchanged.

Interrupt 13H: BIOS Disk Services

Function 0: Reset Disk System

Registers: ah = 0

Returns: c =  set on error

This function resets the disk system, sending a reset command to the floppy disk controller.

Function 2: Read Sectors from Disk

Registers:

ah = 2 al = Number of sectors to read on same track, head cl = Sector number to start reading from ch = Track number to read dh = Head number to read dl = Drive number to read es:bx = Buffer to read sectors into

Returns:

c = set on error ah = Error code, set as follows (for all Int 13H fctns) 80 H - Disk drive failed to respond 40 H - Seek operation failed 20 H - Bad NEC controller chip 10 H - Bad CRC on disk read 09 H - 64K DMA boundary crossed 08 H - Bad DMA chip 06 H - Diskette changed 04 H - Sector not found 03 H - Write on write protected disk 02 H - Address mark not found on disk 01 H - Bad command sent to disk i/o

Function 2 reads sectors from the specified disk at a given Track, Head and Sector number into a buffer in RAM. A successful read returns ah=0 and no carry flag. If there is an error, the carry flag is set and ah is used to return an error code. Note that no waiting time for motor startup is allowed, so if this function returns an error, it should be tried up to three times.

Function 3: Write Sectors to disk

Registers:	ah = 3 al = Number of sectors to write on same track, head cl = Sector number to start writing from ch = Track number to write dh = Head number to write dl = Drive number to write es:bx = Buffer to write sectors from
Returns:	c = set on error ah = Error code (as above)

This function works just like the read, except sectors are written to disk from the specified buffer

Function 5: Format Sectors

Registers:	ah = 5 al = Number of sectors to format on this track, head cl = Not used ch = Track number to format dh = Head number to format dl = Drive number to format es:bx = Buffer for special format information
Returns:	c = set on error ah = Error code (as above)

The buffer at es:bx should contain 4 bytes for each sector to be formatted on the disk. These are the address fields which the disk controller uses to locate the sectors during read/write operations. The four bytes should be organized as C,H,R,N;C,H,R,N, etc., where C=Track number, H=Head number, R=Sector number, N=Bytes per sector, where 0=128, 1=256, 2=512, 3=1024.

Interrupt 1AH: BIOS Time of Day Services

Function 0: Read Current Clock Setting

Registers:	ah = 0
Returns:	cx = High portion of clock count dx = Low portion of clock count al = 0 if timer has not passed 24 hour count al = 1 if timer has passed 24 hour count

The clock count returned by this function is the number of timer ticks since midnight. A tick occurrs every 1193180/65536 of a second, or about 18.2 times a second.

Interrupt 21H: DOS Services

Function 9: Print String to Standard Output

Registers: ah = 9

ds:dx = Pointer to string to print

Returns: None

The character string at ds:dx is printed to the standard output device (which is usually the screen). The string must be terminated by a “$” character, and may contain carriage returns, line feeds, etc.

Function 1AH: Set Disk Transfer Area Address

Registers: ah = 1AH

ds:dx = New disk transfer area address

Returns: None

This function sets the Disk Transfer Area (DTA) address to the value given in ds:dx. It is meaningful only within the context of a given program.

When the program is terminated, etc., its DTA goes away with it. The default DTA is at offset 80H in the Program Segment Prefix (PSP).

Function 2FH: Read Disk Transfer Area Address

Registers: ah = 2FH

Returns: es:bx = Pointer to the current DTA

This is the complement of function 1A. It reads the Disk Transfer Area address into the register pair es:bx.

Function 31H: Terminate and Stay Resident

Registers: ah = 31H al = Exit code dx = Memory size to keep, in paragraphs

Returns: (Does not return)

Function 31H causes a program to become memory resident (a TSR), remaining in memory and returning control to DOS. The exit code in al will be zero if the program is terminating successfully, and something else (programmer defined) to indicate that an error occurred. The register dx must contain the number of 16 byte paragraphs of memory that DOS should leave in memory when the program terminates. For example, if one wants to leave a 367 byte COM file in memory, one must save 367+256 bytes, or 39 paragraphs. (That doesn’t leave room for a stack, either.)

Function 3DH: Open File

Registers:	ah = 3DH ds:dx = Pointer to an ASCIIZ path/file name al = Open mode
Returns:	c = set if open failed ax = File handle, if open was successful ax = Error code, if open failed

This function opens the file specified by the null terminated string at ds:dx, which may include a specific path. The value in al is broken out as follows:

Bit 7: Inheritance flag, I.

I=0 means the file is inherited by child processes I=1 means it is private to the current process.

Bits 4-6: Sharing mode, S.

S=0 is compatibility mode

S=1 is exclusive mode

S=2 is deny write mode S=3 is deny read mode S=4 is deny none mode. Bit 3: Reserved, should be 0 Bit 0-2: Access mode, A. A=0 is read mode

A=1 is write mode

A=2 is read/write mode

In this book we are only concerned with the access mode. For more information on sharing, etc., see IBM’s Disk Operating System Technical Reference or one of the other books cited in the references. The file handle returned by DOS when the open is successful may be any 16 bit number. It is unique to the file just opened, and used by all subsequent file operations to reference the file.

Function 3EH: Close File

Registers:	ah = 3EH bx = File handle of file to close
Returns:	c = set if an error occurs closing the file ax = Error code in the event of an error

This closes a file opened by Function 3DH, simply by passing the file handle to DOS.

Function 3FH: Read from a File

Registers: ah = 3FH bx = File handle cx = Number of bytes to read ds:dx = Pointer to buffer to put file data in

Returns: c = set if an error occurs ax = Number of bytes read, if read is successful ax = Error code in the event of an error

Function 3F reads cx bytes from the file referenced by handle bx into the buffer ds:dx. The data is read from the file starting at the current file pointer. The file pointer is initialized to zero when the file is opened, and updated every time a read or write is performed.

Function 40H: Write to a File

Registers:	ah = 40H bx = File handle cx = Number of bytes to write ds:dx = Pointer to buffer to get file data from
Returns:	c = set if an error occurs ax = Number of bytes written, if write is successful ax = Error code in the event of an error

Function 40H writes cx bytes to the file referenced by handle bx from the buffer ds:dx. The data is written to the file starting at the current file pointer.

Function 41H: Delete File

Registers:	ah = 41H ds:dx = Pointer to ASCIIZ string of path/file to delete
Returns:	c = set if an error occurs ax = Error code in the event of an error

This function deletes a file from disk, as specified by the path and file name in the null terminated string at ds:dx.

Function 42H: Move File Pointer

Registers: ah = 42H

al = Method of moving the pointer bx = File handle cx:dx = Distance to move the pointer, in bytes

Returns: c = set if there is an error ax = Error code if there is an error dx:ax = New file pointer value, if no error

Function 42H moves the file pointer in preparation for a read or write operation. The number in cx:dx is a 32 bit unsigned integer. The methods of moving the pointer are as follows: al=0 moves the pointer relative to the beginning of the file, al=1 moves the pointer relative to the current location, al=2 moves the pointer relative to the end of the file.

Function 43H: Get and Set File Attributes

Registers:	ah = 43H al = 0 to get attributes, 1 to set them cl = File attributes, for set function ds:dx = Pointer to an ASCIIZ path/file name
Returns:	c = set if an error occurs ax = Error code when an error occurs cl = File attribute, for get function

The file should not be open when you get/set attributes. The bits in cl correspond to the following attributes:

Bit 0 - Read Only attribute

Bit 1 - Hidden attrubute

Bit 2 - System attribute

Bit 3 - Volume Label attribute

Bit 4 - Subdirectory attribute

Bit 5 - Archive attribute

Bit 6 and 7 - Not used

Function 47H: Get Current Directory

Registers: ah = 47H

dl = Drive number, 0=Default, 1=A, 2=B, etc. ds:si = Pointer to buffer to put directory path name in

Returns: c = set if an error occurs ax = Error code when an error occurs

The path name is stored in the data area at ds:si as an ASCIIZ null terminated string. This string may be up to 64 bytes long, so one should normally allocate that much space for this buffer.

Function 4EH: Find First File Search

Registers: ah = 4EH

cl = File attribute to use in the search ds:dx = Pointer to an ASCIIZ path/file name

Returns: ax = Error code when an error occurs, or 0 if no error

The ASCIIZ string at ds:dx may contain the wildcards * and ?. For example, “c:\dos\*.com” would be a valid string. This function will return with an error if it cannot find a file. No errors indicate that the search was successful. When successful, DOS formats a 43 byte block of data in the current DTA which is used both to identify the file found, and to pass to the Find Next function, to tell it where to continue the search from. The data in the DTA is formatted as follows:

Byte Size Description

0 21 Reserved for DOS Find Next

21. 1 Attribute of file found
22. 2 Time on file found

24 2 Date on file found

26 4 Size of file found, in bytes

30 13 File name of file found

The attribute is used in a strange way for this function. If any of the Hidden, System, or Directory attributes are set when Find Next is called, DOS will search for any normal file, as well as any with the specified attributes. Archive and Read Only attributes are ignored by the search altogether. If the Volume Label attribute is specified, the search will look only for files with that attribute set.

Function 4FH: Find Next File Search

Registers: ah = 4FH

Returns: ax = 0 if successful, otherwise an error code

This function continues the search begun by Function 4E. It relies on the information in the DTA, which should not be disturbed between one call and the next. This function also modifies the DTA data block to reflect the next file found. In programming, one often uses this function in a loop until ax=18, indicating the normal end of the search.

Function 57H: Get/Set File Date and Time

Registers:	ah = 57H al = 0 to get the date/time al = 1 to set the date/time bx = File Handle cx = 2048*Hour + 32*Minute + Second/2 for set dx = 512*(Year-1980) + 32*Month + Day for set
Returns:	c = set if an error occurs ax = Error code in the event of an error cx = 2048*Hour + 32*Minute + Second/2 for get dx = 512*(Year-1980) + 32*Month + Day for get

This function gets or sets the date/time information for an open file. This information is normally generated from the system clock date and time when a file is created or modified, but the programmer can use this function to modify the date/time at will.