Art of Assembly: Chapter Thirteen-4

[CH13-1.html][Previous] [Next] [Art of Assembly][Randall Hyde]

Art of Assembly: Chapter Thirteen

13.3 - An Introduction to MS-DOS'
13.3.1 - MS-DOS Calling Sequence
13.3.2 - MS-DOS Character Oriented Functions
13.3.3 - MS-DOS Drive Commands
13.3.4 - MS-DOS "Obsolete" Filing Calls
13.3.5 - MS-DOS Date and Time Functions

13.3 An Introduction to MS-DOS'

MS-DOS provides all of the basic file manager and device manager functions required by most application programs running on an IBM PC. MS-DOS handles file I/O, character I/0, memory management, and other miscellaneous functions in a (relatively) consistent manner. If you're serious about writing software for the PC, you'll have to get real friendly with MS-DOS.

The title of this section is "An Introduction to MS-DOS". And that's exactly what it means. There is no way MS-DOS can be completely covered in a single chapter. Given all of the different books that already exist on the subject, it probably cannot even be covered by a single book (it certainly hasn't been yet. Microsoft wrote a 1,600 page book on the subject and it didn't even cover the subject fully). All this is leading up to a cop-out. There is no way this subject can be treated in more than a superficial manner in a single chapter. If you're serious about writing programs in assembly language for the PC, you'll need to complement this text with several others. Additional books on MS-DOS include: MS-DOS Programmer's Reference (also called the MS-DOS Technical Reference Manual), Peter Norton's Programmer's Guide to the IBM PC, The MS-DOS Encyclopedia, and the MS-DOS Developer's Guide. This, of course, is only a partial list of the books that are available. See the bibliography in the appendices for more details. Without a doubt, the MS-DOS Technical Reference Manual is the most important text to get your hands on. This is the official description of MS-DOS calls and parameters.

MS-DOS has a long and colorful history[2]. Throughout its lifetime, it has undergone several revisions, each purporting to be better than the last. MS-DOS' origins go all the way back to the CP/M-80 operating system written for the Intel 8080 microprocessor chip. In fact, MS-DOS v1.0 was nothing much more than a clone of CP/M-80 for Intel's 8088 microprocessor. Unfortunately, CP/M-80's file handling capabilities were horrible, to say the least. Therefore, DOS[3] improved on CP/M. New file handling capabilities, compatible with Xenix and Unix, were added to DOS, producing MS-DOS v2.0. Additional calls were added to later versions of MS-DOS. Even with the introduction of OS/2 and Windows NT (which, as this is being written, have yet to take the world by storm), Microsoft is still working on enhancements to MS-DOS which may produce even later versions.

Each new feature added to DOS introduced new DOS functions while preserving all of the functionality of the previous versions of DOS. When Microsoft rewrote the DOS file handling routines in version two, they didn't replace the old calls, they simply added new ones. While this preserved software compatibility of programs that ran under the old version of DOS, what it produced was a DOS with two sets of functionally identical, but otherwise incompatible, file services.

We're only going to concentrate on a small subset of the available DOS commands in this chapter. We're going to totally ignore those obsolete commands that have been augmented by newer, better, commands in later versions of DOS. Furthermore, we're going to skip over a description of those calls that have very little use in day to day programming. For a complete, detailed, look at the commands not covered in this chapter, you should consider the acquisition of one of the aforementioned books.

13.3.1 MS-DOS Calling Sequence

MS-DOS is called via the int 21h instruction. To select an appropriate DOS function, you load the ah register with a function number before issuing the int 21h instruction. Most DOS calls require other parameters as well. Generally, these other parameters are passed in the CPU's register set. The specific parameters will be discussed along with each call. Unless MS-DOS returns some specific value in a register, all of the CPU's registers are preserved across a call to DOS[4].

13.3.2 MS-DOS Character Oriented Functions

DOS provides 12 character oriented I/O calls. Most of these deal with writing and reading data to/from the keyboard, video display, serial port, and printer port. All of these functions have corresponding BIOS services. In fact, DOS usually calls the appropriate BIOS function to handle the I/O operation. However, due to DOS' redirected I/O and device driver facilities, these functions don't always call the BIOS routines. Therefore, you shouldn't call the BIOS routines (rather than DOS) simply because DOS ends up calling BIOS. Doing so may prevent your program from working with certain DOS-supported devices.

Except for function code seven, all of the following character oriented calls check the console input device (keyboard) for a control-C. If the user presses a control-C, DOS executes an int 23h instruction. Usually, this instruction will cause the program to abort and control will be returned to DOS. Keep this in mind when issuing these calls.

Microsoft considers these calls obsolete and does not guarantee they will be present in future versions of DOS. So take these first 12 routines with a rather large grain of salt. Note that the UCR Standard Library provides the functionality of many of these calls anyway, and they make the proper DOS calls, not the obsolete ones.
















DOS Character Oriented Functions


















Function #

(AH)






Input

Parameters






Output

Parameters






Description















1






-






al- char read






Console Input w/Echo: Reads a single character from the keyboard and displays typed character on screen.















2






dl- output char






-






Console Output: Writes a single character to the display.















3






-






al- char read






Auxiliary Input: Reads a single character from the serial port.















4






dl- output char






-






Auxiliary Output: Writes a single character to the output port















5






dl- output char






-






Printer Output: Writes a single character to the printer















6






dl- output char (if not 0FFh)






al- char read (if input dl = 0FFh)






Direct Console I/O: On input, if dl contains 0FFh, this function attempts to read a character from the keyboard. If a character is available, it returns the zero flag clear and the character in al. If no character is available, it returns the zero flag set. On input, if dl contains a value other than 0FFh, this routine sends the character to the display. This routine does not do ctrl-C checking.















7






-






al- char read






Direct Console Input: Reads a character from the keyboard. Does not echo the character to the display. This call does not check for ctrl-C















8






-






al- char read






Read Keyboard w/o Echo: Just like function 7 above, except this call checks for ctrl-C.















9






ds:dx- pointer to string terminated with "$".






-






Display String: This function displays the characters from location ds:dx up to (but not including) a terminating "$" character.















0Ah






ds:dx- pointer to input buffer.






-






Buffered Keyboard Input: This function reads a line of text from the keyboard and stores it into the input buffer pointed at by ds:dx. The first byte of the buffer must contain a count between one and 255 that contains the maximum number of allowable characters in the input buffer. This routine stores the actual number of characters read in the second byte. The actual input characters begin at the third byte of the buffer.















0Bh






-






al- status (0=not ready, 0FFh=ready)






Check Keyboard Status: Determines whether a character is available from the keyboard.















0Ch






al- DOS opcode 0, 1, 6, 7, or 8






al- input character if opcode 1, 6, 7, or 8.






Flush Buffer: This call empties the system type ahead buffer and then executes the DOS command specified in the al register (if al=0, no further action).

DOS Character Oriented Functions
Function # (AH)	Input Parameters	Output Parameters	Description
1	-	`al`- char read	Console Input w/Echo: Reads a single character from the keyboard and displays typed character on screen.
2	`dl`- output char	-	Console Output: Writes a single character to the display.
3	-	`al`- char read	Auxiliary Input: Reads a single character from the serial port.
4	`dl`- output char	-	Auxiliary Output: Writes a single character to the output port
5	`dl`- output char	-	Printer Output: Writes a single character to the printer
6	`dl`- output char (if not 0FFh)	`al`- char read (if input `dl` = 0FFh)	Direct Console I/O: On input, if `dl` contains 0FFh, this function attempts to read a character from the keyboard. If a character is available, it returns the zero flag clear and the character in `al`. If no character is available, it returns the zero flag set. On input, if `dl` contains a value other than 0FFh, this routine sends the character to the display. This routine does not do ctrl-C checking.
7	-	`al`- char read	Direct Console Input: Reads a character from the keyboard. Does not echo the character to the display. This call does not check for ctrl-C
8	-	`al`- char read	Read Keyboard w/o Echo: Just like function 7 above, except this call checks for ctrl-C.
9	`ds:dx`- pointer to string terminated with "$".	-	Display String: This function displays the characters from location `ds:dx` up to (but not including) a terminating "$" character.
0Ah	`ds:dx`- pointer to input buffer.	-	Buffered Keyboard Input: This function reads a line of text from the keyboard and stores it into the input buffer pointed at by `ds:dx`. The first byte of the buffer must contain a count between one and 255 that contains the maximum number of allowable characters in the input buffer. This routine stores the actual number of characters read in the second byte. The actual input characters begin at the third byte of the buffer.
0Bh	-	`al`- status (0=not ready, 0FFh=ready)	Check Keyboard Status: Determines whether a character is available from the keyboard.
0Ch	`al`- DOS opcode 0, 1, 6, 7, or 8	`al`- input character if opcode 1, 6, 7, or 8.	Flush Buffer: This call empties the system type ahead buffer and then executes the DOS command specified in the al register (if `al`=0, no further action).

Functions 1, 2, 3, 4, 5, 9, and 0Ah are obsolete and you should not use them. Use the DOS file I/O calls instead (opcodes 3Fh and 40h).

13.3.3 MS-DOS Drive Commands

MS-DOS provides several commands that let you set the default drive, determine which drive is the default, and perform some other operations. The following table lists those functions.

DOS Disk Drive Functions
Function # (AH)	Input Parameters	Output Parameters	Description
0Dh	-	-	Reset Drive: Flushes all file buffers to disk. Generally called by ctrl-C handlers or sections of code that need to guaranteed file consistency because an error may occur.
0Eh	`dl`- drive number	`al`- number of logical drives	Set Default Drive: sets the DOS default drive to the specified value (0=A, 1=B, 2=C, etc.). Returns the number of logical drives in the system, although they may not be contiguous from 0-`al`.
19H	-	`al`- default drive number	Get Default Drive: Returns the current system default drive number (0=A, 1=B, 2=C, etc.).
1Ah	`ds:dx`- Disk Transfer Area address.	-	Set Disk Transfer Area Address: Sets the address that MS-DOS uses for obsolete file I/O and Find First/Find Next commands.
1Bh-		`al`- sectors/cluster `cx`- bytes/sector `dx`- # of clusters `ds:bx` - points at media descriptor byte	Get Default Drive Data: Returns information about the disk in the default drive. Also see function 36h. Typical values for the media descriptor byte include: 0F0h- 3.5" 0F8h- Hard disk 0F9h- 720K 3.5" or 1.2M 5.25" 0FAh- 320K 5.25" 0FBh- 640K 3.5" 0FCh- 180K 5.25" 0FDh- 360K 5.25: 0FEh- 160K 5.25" 0FFh- 320K 5.25"
1Ch	`dl`- drive number	See above	Get Drive Data: same as above except you can specify the drive number in the dl register (0=default, 1=A, 2=B, 3=C, etc.).
1Fh	-	`al`- contains 0FFh if error, 0 if no error. `ds:bx`- ptr to DPB	Get Default Disk Parameter Block (DPB): If successful, this function returns a pointer to the following structure: Drive (byte) - Drive number (0-A, 1=B, etc.). Unit (byte) - Unit number for driver. SectorSize (word) - # bytes/sector. ClusterMask (byte) - sectors/cluster minus one. Cluster2 (byte) - 2clusters/sector FirstFAT (word) - Address of sector where FAT starts. FATCount (byte) - # of FATs. RootEntries (word) - # of entries in root directory. FirstSector (word) - first sector of first cluster. MaxCluster (word) - # of clusters on drive, plus one. FATsize (word) - # of sectors for FAT. DirSector (word) - first sector containing directory. DriverAdrs (dword) - address of device driver. Media (byte) - media descriptor byte. FirstAccess (byte) - set if there has been an access to drive. NextDPB (dword) - link to next DPB in list. NextFree (word) - last allocated cluster. FreeCnt (word) - number of free clusters.
2Eh	`al`- verify flag (0=no verify, 1=verify on).	-	Set/Reset Verify Flag: Turns on and off write verification. Usually off since this is a slow operation, but you can turn it on when performing critical I/O.
2Fh	-	`es:bx`- pointer to DTA	Get Disk Transfer Area Address: Returns a pointer to the current DTA in `es:bx`..
32h	`dl`- drive number.	Same as 1Fh	Get DPB: Same as function 1Fh except you get to specify the driver number (0=default, 1=A, 2=B, 3=C, etc.).
33h	`al`- 05 (subfunction code)	`dl`- startup drive #.	Get Startup Drive: Returns the number of the drive used to boot DOS (1=A, 2=B, 3=C, etc.).
36h	`dl`- drive number.	`ax`- sectors/cluster `bx`- available clusters `cx`- bytes/sector `dx`- total clusters	Get Disk Free Space: Reports the amount of free space. This call supersedes calls 1Bh and 1Ch that only support drives up to 32Mbytes. This call handles larger drives. You can compute the amount of free space (in bytes) by bxaxcx. If an error occurs, this call returns 0FFFFh in `ax`.
54h	-	`al`- verify state.	Get Verify State: Returns the current state of the write verify flag (`al`=0 if off, `al`=1 if on).

13.3.4 MS-DOS "Obsolete" Filing Calls

DOS functions 0Fh - 18h, 1Eh, 20h-24h, and 26h - 29h are the functions left over from the days of CP/M-80. In general, you shouldn't bother at all with these calls since MS-DOS v2.0 and later provides a much better way to accomplish the operations performed by these calls.

13.3.5 MS-DOS Date and Time Functions

The MS-DOS date and time functions return the current date and time based on internal values maintained by the real time clock (RTC). Functions provided by DOS include reading and setting the date and time. These date and time values are used to perform date and time stamping of files when files are created on the disk. Therefore, if you change the date or time, keep in mind that it will have an effect on the files you create thereafter. Note that the UCR Standard Library also provides a set of date and time functions which, in many cases, are somewhat easier to use than these DOS calls.

Date and Time Functions
Function # (AH)	Input Parameters	Output Parameters	Description
2Ah	-	`al`- day (0=Sun, 1=Mon, etc.). `cx`- year `dh`- month (1=Jan, 2=Feb, etc.). `dl`- Day of month (1-31).	Get Date: returns the current MS-DOS date.
2Bh	`cx`- year (1980 - 2099) `dh`- month (1-12) `dl`- day (1-31)	-	Set Date: sets the current MS-DOS date.
2CH	-	`ch`- hour (24hr fmt) `cl`- minutes `dh`- seconds `dl`- hundredths	Get Time: reads the current MS-DOS time. Note that the hundredths of a second field has a resolution of 1/18 second.
2Dh	`ch`- hour `cl`- minutes `dh`- seconds `dl`- hundredths	-	Set Time: sets the current MS-DOS time.

[2] The MS-DOS Encyclopedia gives Microsoft's account of the history of MS-DOS. Of course, this is a one-sided presentation, but it's interesting nonetheless.

[3] This text uses "DOS" to mean MS-DOS.

[4] So Microsoft claims. This may or may not be true across all versions of DOS.

13.3 - An Introduction to MS-DOS'
13.3.1 - MS-DOS Calling Sequence
13.3.2 - MS-DOS Character Oriented Functions
13.3.3 - MS-DOS Drive Commands
13.3.4 - MS-DOS "Obsolete" Filing Calls
13.3.5 - MS-DOS Date and Time Functions