may be read or written by an application only under very specific conditions, and timing loops burn up CPU cycles that can be used by other processes. As I mentioned earlier in this chapter, display routines constitute the most common area of hardware dependence in an MS-DOS application. Direct manipulation of the video adapter and its regen buffer poses obvious difficulties in a multitasking, protected-memory environment such as OS/2. For porting purposes, you must convert all routines that write text to the display, modify character attributes, or affect cursor shape or position into Int 21H Function 40H calls using ANSI escape sequences or into ROM BIOS Int 10H calls. Similarly, you must convert all hardware-dependent keyboard operations to Int 21H Function 3FH or ROM BIOS Int 16H calls. Once all hardware dependence has been expunged from your program, your next priority is to make it well-behaved in its use of system memory. Under MS-DOS an application is typically handed all remaining memory in the system to do with as it will; under OS/2 the converse is true: A process is initially allocated only enough memory to hold its code, declared data storage, and stack. You can make the MS-DOS loader behave like the OS/2 loader by linking your application with the /CPARMAXALLOC switch. Alternatively, your program can give up all extra memory during its initialization with Int 21H Function 4AH, as recommended earlier in this chapter. After your program completes its initialization sequence, it should dynamically obtain and release any additional memory it may require for buffers and tables with MS-DOS Int 21H Functions 48H and 49H. To ensure compatibility with protected mode, limit the size of any single allocated block to 65,536 bytes or less, even though MS-DOS allows larger blocks to be allocated. Finally, you must turn your attention to file and device handling. Replace any calls to FCB file functions with their handle-based equivalents, because OS/2 does not support FCBs in protected mode at all. Check pathnames for validity within the application; although MS-DOS and the 3.x Box silently truncate a name or extension, OS/2 refuses to open or create a file in protected mode if the name or extension is too long and returns an error instead. Replace any use of the predefined handles for the standard auxiliary and standard list devices with explicit opens of COM1, PRN, LPT1, and so on, using the resulting handle for read and write operations. OS/2 does not supply processes with standard handles for the serial communications port or printer. Encapsulation When you reach this point, with a well-behaved, segmented MS-DOS application in hand, the worst of a port to OS/2 is behind you. You are now ready to prepare your program for true conversion to protected-mode operation by encapsulating, in individual subroutines, every part of the program that is specific to the host operating system. The objective here is to localize the program's "knowledge" of the environment into small procedures that can be subsequently modified without affecting the remainder of the program. As an example of encapsulation, consider a typical call by an MS-DOS application to write a string to the standard output device (Figure 16-1). In order to facilitate conversion to OS/2, you would replace every instance of such a write to a file or device with a call to a small subroutine that "hides" the mechanics of the actual operating-system function call, as illustrated in Figure 16-2. Another candidate for encapsulation, which does not necessarily involve an operating-system function call, is the application's code to gain access to command-line parameters, environment-block variables, and the name of the file it was loaded from. Under MS-DOS, this information is divided between the program segment prefix (PSP) and the environment block, as we saw in Chapters 3 and 12; under OS/2, there is no such thing as a PSP, and the program filename and command-line information are appended to the environment block. ────────────────────────────────────────────────────────────────────────── stdin equ 0 ; standard input handle stdout equ 1 ; standard output handle stderr equ 2 ; standard error handle msg db 'This is a sample message' msg_len equ $-msg . . . mov dx,seg msg ; DS:DX = message address mov ds,dx mov dx,offset DGROUP:msg mov cx,msg_len ; CX = message length mov bx,stdout ; BX = handle mov ah,40h ; AH = function 40h write int 21h ; transfer to MS-DOS jc error ; jump if error cmp ax,msg_len ; all characters written? jne diskfull ; no, device is full . . . ────────────────────────────────────────────────────────────────────────── Figure 16-1. Typical in-line code for an MS-DOS function call. This particular sequence writes a string to the standard output device. Since the standard output might be redirected to a file without the program's knowledge, it must also check that all of the requested characters were actually written; if the returned length is less than the requested length, this usually indicates that the standard output has been redirected to a disk file and that the disk is full. ────────────────────────────────────────────────────────────────────────── stdin equ 0 ; standard input handle stdout equ 1 ; standard output handle stderr equ 2 ; standard error handle msg db 'This is a sample message' msg_len equ $-msg . . . mov dx,seg msg ; DS:DX = message address mov ds,dx mov dx,offset DGROUP:msg mov cx,msg_len ; CX = message length mov bx,stdout ; BX = handle call write ; perform the write jc error ; jump if error cmp ax,msg_len ; all characters written? jne diskfull ; no, device is full . . . write proc near ; write to file or device ; Call with: ; BX = handle ; CX = length of data ; DS:DX = address of data ; returns: ; if successful, carry clear ; and AX = bytes written ; if error, carry set ; and AX = error code mov ah,40h ; function 40h = write int 21h ; transfer to MS-DOS ret ; return status in CY and AX write endp . . . ────────────────────────────────────────────────────────────────────────── Figure 16-2. Code from Figure 16-1 after "encapsulation." The portion of the code that is operating-system dependent has been isolated inside a subroutine that is called from other points within the application. When you have completed the encapsulation of system services and access to the PSP and environment, subject your program once more to thorough testing under MS-DOS. This is your last chance, while you are still working in a familiar milieu and have access to your favorite debugging tools, to detect any subtle errors you may have introduced during the three conversion steps discussed thus far. Conversion Next, you must rewrite each system-dependent procedure you created during the encapsulation stage to conform to the OS/2 protected-mode API. In contrast to MS-DOS functions, which are actuated through software interrupts and pass parameters in registers, OS/2 API functions are requested through a far call to a named entry point. Parameters are passed on the stack, along with the addresses of variables within the calling program's data segment that will receive any results returned by the function. The status of an operation is returned in register AX──zero if the function succeeded, an error code otherwise. All other registers are preserved. Although it is not my intention here to provide a detailed introduction to OS/2 programming, Figure 16-3 illustrates the final form of our previous example, after conversion for OS/2. Note especially the addition of the extrn statement, the wlen variable, and the simulation of the MS-DOS function status. This code may not be elegant, but it serves the purpose of limiting the necessary changes to a very small portion of the source file. Some OS/2 functions (such as DosOpen) require parameters that have no counterpart under MS-DOS; you can usually select reasonable values for these extra parameters that will make their existence temporarily invisible to the remainder of the application. ────────────────────────────────────────────────────────────────────────── stdin equ 0 ; standard input handle stdout equ 1 ; standard output handle stderr equ 2 ; standard error handle extrn DosWrite:far msg db 'This is a sample message' msg_len equ $-msg wlen dw ? ; receives actual number ; of bytes written . . . mov dx,seg msg ; DS:DX = message address mov ds,dx mov dx,offset DGROUP:msg mov cx,msg_len ; CX = message length mov bx,stdout ; BX = handle call write ; perform the write jc error ; jump if error cmp ax,msg_len ; all characters written? jne diskfull ; no, device is full . . . write proc near ; write to file or device ; call with: ; BX = handle ; CX = length of data ; DS:DX = address of data ; returns: ; if successful, carry clear ; and AX = bytes written ; if error, carry set ; and AX = error code push bx ; handle push ds ; address of data push dx push cx ; length of data push ds ; receives length written mov ax,offset DGROUP:wlen push ax call DosWrite ; transfer to OS/2 or ax,ax ; did write succeed? jnz write1 ; jump, write failed mov ax,wlen ; no error, OR cleared CY ret ; and AX := bytes written write1: stc ; write error, return CY set ret ; and AX = error number write endp . . . ────────────────────────────────────────────────────────────────────────── Figure 16-3. Code from Figure 16-2 after "conversion." The MS-DOS function call has been replaced with the equivalent OS/2 function call. Since the knowledge of the operating system has been hidden inside the subroutine by the previous encapsulation step, the surrounding program's requests for write operations should run unchanged. Note that the OS/2 function had to be declared as an external name with the "far" attribute, and that a variable named wlen was added to the data segment of the application to receive the actual number of bytes written. Figures 16-4, 16-5, and 16-6 list the OS/2 services that are equivalent to selected MS-DOS and ROM BIOS Int 21H, Int 10H, and Int 16H calls. MS-DOS functions related to FCBs and PSPs are not included in these tables because OS/2 does not support either of these structures. The MS-DOS terminate-and-stay-resident functions are also omitted. Because OS/2 is a true multitasking system, a process doesn't need to terminate in order to stay resident while another process is running. ╓┌─┌───────────────────┌────────────────────────────────┌────────────────────╖ MS-DOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── Int 21H Function 0 Terminate process DosExit 1 Character input with echo KbdCharIn 2 Character output VioWrtTTY 3 Auxiliary input DosRead MS-DOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── 3 Auxiliary input DosRead 4 Auxiliary output DosWrite 5 Printer output DosWrite 6 Direct console I/O KbdCharIn, VioWrtTTY 7 Unfiltered input without echo KbdCharIn 8 Character input without echo KbdCharIn 9 Display string VioWrtTTY 0AH (10) Buffered keyboard input KbdStringIn 0BH (11) Check input status KbdPeek 0CH (12) Reset buffer and input KbdFlushBuffer, KbdCharIn 0DH (13) Disk reset DosBufReset 0EH (14) Select disk DosSelectDisk 19H (25) Get current disk DosQCurDisk 1BH (27) Get default drive data DosQFSInfo 1CH (28) Get drive data DosQFSInfo 2AH (42) Get date DosGetDateTime 2BH (43) Set date DosSetDateTime MS-DOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── 2BH (43) Set date DosSetDateTime 2CH (44) Get time DosGetDateTime 2DH (45) Set time DosSetDateTime 2EH (46) Set verify flag DosSetVerify 30H (48) Get MS-DOS version DosGetVersion 36H (54) Get drive allocation DosQFSInfo information 38H (56) Get or set country DosGetCtryInfo information 39H (57) Create directory DosMkdir 3AH (58) Delete directory DosRmdir 3BH (59) Set current directory DosChdir 3CH (60) Create file DosOpen 3DH (61) Open file DosOpen 3EH (62) Close file DosClose 3FH (63) Read file or device DosRead 40H (64) Write file or device DosWrite 41H (65) Delete file DosDelete 42H (66) Set file pointer DosChgFilePtr MS-DOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── 42H (66) Set file pointer DosChgFilePtr 43H (67) Get or set file attributes DosQFileMode, DosSetFileMode 44H (68) I/O control (IOCTL) DosDevIOCtl 45H (69) Duplicate handle DosDupHandle 46H (70) Redirect handle DosDupHandle 47H (71) Get current directory DosQCurDir 48H (72) Allocate memory block DosAllocSeg 49H (73) Release memory block DosFreeSeg 4AH (74) Resize memory block DosReAllocSeg 4BH (75) Execute program DosExecPgm 4CH (76) Terminate process with DosExit return code 4DH (77) Get return code DosCWait 4EH (78) Find first file DosFindFirst 4FH (79) Find next file DosFindNext 54H (84) Get verify flag DosQVerify 56H (86) Rename file DosMove 57H (87) Get or set file date and time DosQFileInfo, MS-DOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── 57H (87) Get or set file date and time DosQFileInfo, DosSetFileInfo 59H (89) Get extended error DosErrClass information 5BH (91) Create new file DosOpen 5CH (92) Lock or unlock file region DosFileLocks 65H (101) Get extended country DosGetCtryInfo information 66H (102) Get or set code page DosGetCp, DosSetCp 67H (103) Set handle count DosSetMaxFH 68H (104) Commit file DosBufReset 6CH (108) Extended open file DosOpen ────────────────────────────────────────────────────────────────────────── Figure 16-4. Table of selected MS-DOS function calls and their OS/2 counterparts. Note that OS/2 functions are typically more powerful and flexible than the corresponding MS-DOS functions, and that this is not a complete list of OS/2 services. ROM BIOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── Int 10H Function 0 Select display mode VioSetMode 1 Set cursor type VioSetCurType 2 Set cursor position VioSetCurPos 3 Get cursor position VioGetCurPos 6 Initialize or scroll window up VioScrollUp 7 Initialize or scroll window down VioScrollDn 8 Read character and attribute VioReadCellStr 9 Write character and attribute VioWrtNCell 0AH (10) Write character VioWrtNChar 0EH (14) Write character in teletype mode VioWrtTTY 0FH (15) Get display mode VioGetMode 10H (16) Set palette, border color, etc. VioSetState 13H (19) Write string in teletype mode VioWrtTTY ────────────────────────────────────────────────────────────────────────── Figure 16-5. Table of ROM BIOS Int 10H video-display driver functions used by MS-DOS applications and their OS/2 equivalents. This is not a complete list of OS/2 video services. ROM BIOS Description OS/2 function ────────────────────────────────────────────────────────────────────────── Int 16H Function 0 Read keyboard character KbdCharIn 1 Get keyboard status KbdPeek 2 Get keyboard flags KbdGetStatus ────────────────────────────────────────────────────────────────────────── Figure 16-6. Table of ROM BIOS Int 16H keyboard driver functions used by MS-DOS applications and their OS/2 equivalents. This is not a complete list of OS/2 keyboard services. Optimization Once your program is running in protected mode, it is time to unravel some of the changes made for purposes of conversion and to introduce various optimizations. Three obvious categories should be considered: 1. Modifying the program's user-interface code for the more powerful OS/2 keyboard and display API functions. 2. Incorporating 80286-specific machine instructions where appropriate. 3. Revamping the application to exploit the OS/2 facilities that are unique to protected mode. (Of course, the application benefits from OS/2's virtual memory capabilities automatically; it can allocate memory until physical memory and disk swapping space are exhausted.) Modifying subroutines that encapsulate user input and output to take advantage of the additional functionality available under OS/2 is straight-forward, and the resulting performance improvements can be quite dramatic. For example, the OS/2 video driver offers a variety of services that are far superior to the screen support in MS-DOS and the ROM BIOS, including high-speed display of strings and attributes at any screen position, "reading back" selected areas of the display into a buffer, and scrolling in all four directions. The 80286-specific machine instructions can be very helpful in reducing code size and increasing execution speed. The most useful instructions are the shifts and rotates by an immediate count other than one, the three-operand multiply where one of the operands is an immediate (literal) value, and the push immediate value instruction (particularly handy for setting up OS/2 function calls). For example, in Figure 16-3, the sequence mov ax,offset DGROUP:wlen push ax could be replaced by the single instruction push offset DGROUP:wlen Restructuring an application to take full advantage of OS/2's protected-mode capabilities requires close study of both the application and the OS/2 API, but such study can pay off with sizable benefits in performance, ease of maintenance, and code sharing. Often, for instance, different parts of an application are concerned with I/O devices of vastly different speeds, such as the keyboard, disk, and video display. It both simplifies and enhances the application to separate these elements into subprocesses (called threads in OS/2) that execute asynchronously, communicate through shared data structures, and synchronize with each other, when necessary, using semaphores. As another example, when several applications are closely related and contain many identical or highly similar procedures, OS/2 allows you to centralize those procedures in a dynamic link library. Routines in a dynamic link library are bound to a program at its load time (rather than by LINK, as in the case of traditional runtime libraries) and are shared by all the processes that need them. This reduces the size of each application .EXE file and allows more efficient use of memory. Best of all, dynamic link libraries drastically simplify code maintenance; the routines in the libraries can be debugged or improved at any time, and the applications that use them will automatically benefit the next time they are executed. ──────────────────────────────────────────────────────────────────────────── SECTION 2 MS-DOS FUNCTIONS REFERENCE ──────────────────────────────────────────────────────────────────────────── Notes to the Reader This section documents the services that the MS-DOS kernel provides to application programs via software interrupts 20H─2FH. Each MS-DOS function is described in the same format: ■ A heading containing the function's name, software interrupt and function number, and an icon indicating the MS-DOS version in which the function was first supported. You can assume that the function is available in all subsequent MS-DOS versions unless explicitly noted otherwise. ■ A synopsis of the actions performed by the function and the circumstances under which it would be used. ■ A summary of the function's arguments. ■ The results and/or error indicators returned by the function. A comprehensive list of error codes can be found in the entry for Int 21H Function 59H. ■ Notes describing special uses or dependencies of the function. ■ A skeleton example of the function's use, written in assembly language. Version icons used in the synopsis, arguments, results, or Notes sections refer to specific minor or major versions, unless they include a + sign to indicate a version and all subsequent versions. For purposes of clarity, the examples may include instructions that would not be necessary if the code were inserted into a working program. For example, most of the examples explicitly set the segment registers when passing the address of a filename or buffer to MS-DOS; in real applications, the segment registers are usually initialized once at entry to the program and left alone thereafter. Int 21H Function Summary by Number ╓┌─┌───────┌────────┌───────────────────────────────────────┌───────┌────────╖ Hex Dec Function name Vers F/H☼ Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 00H 0 Terminate Process 1.0+ 01H 1 Character Input with Echo 1.0+ 02H 2 Character Output 1.0+ 03H 3 Auxiliary Input 1.0+ 04H 4 Auxiliary Output 1.0+ 05H 5 Printer Output 1.0+ 06H 6 Direct Console I/O 1.0+ 07H 7 Unfiltered Character Input Without Echo 1.0+ 08H 8 Character Input Without Echo 1.0+ 09H 9 Display String 1.0+ 0AH 10 Buffered Keyboard Input 1.0+ 0BH 11 Check Input Status 1.0+ 0CH 12 Flush Input Buffer and Then Input 1.0+ 0DH 13 Disk Reset 1.0+ 0EH 14 Select Disk 1.0+ 0FH 15 Open File 1.0+ F 10H 16 Close File 1.0+ F 11H 17 Find First File 1.0+ F 12H 18 Find Next File 1.0+ F Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 12H 18 Find Next File 1.0+ F 13H 19 Delete File 1.0+ F 14H 20 Sequential Read 1.0+ F 15H 21 Sequential Write 1.0+ F 16H 22 Create File 1.0+ F 17H 23 Rename File 1.0+ F 18H 24 Reserved 19H 25 Get Current Disk 1.0+ 1AH 26 Set DTA Address 1.0+ 1BH 27 Get Default Drive Data 1.0+ 1CH 28 Get Drive Data 2.0+ 1DH 29 Reserved 1EH 30 Reserved 1FH 31 Reserved 20H 32 Reserved 21H 33 Random Read 1.0+ F 22H 34 Random Write 1.0+ F 23H 35 Get File Size 1.0+ F 24H 36 Set Relative Record Number 1.0+ F Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 24H 36 Set Relative Record Number 1.0+ F 25H 37 Set Interrupt Vector 1.0+ 26H 38 Create New PSP 1.0+ 27H 39 Random Block Read 1.0+ F 28H 40 Random Block Write 1.0+ F 29H 41 Parse Filename 1.0+ 2AH 42 Get Date 1.0+ 2BH 43 Set Date 1.0+ 2CH 44 Get Time 1.0+ 2DH 45 Set Time 1.0+ 2EH 46 Set Verify Flag 1.0+ 2FH 47 Get DTA Address 2.0+ 30H 48 Get MS-DOS Version Number 2.0+ 31H 49 Terminate and Stay Resident 2.0+ 32H 50 Reserved 33H 51 Get or Set Break Flag, Get Boot Drive 2.0+ 34H 52 Reserved 35H 53 Get Interrupt Vector 2.0+ 36H 54 Get Drive Allocation Information 2.0+ Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 36H 54 Get Drive Allocation Information 2.0+ 37H 55 Reserved 38H 56 Get or Set Country Information 2.0+ 39H 57 Create Directory 2.0+ 3AH 58 Delete Directory 2.0+ 3BH 59 Set Current Directory 2.0+ 3CH 60 Create File 2.0+ H 3DH 61 Open File 2.0+ H 3EH 62 Close File 2.0+ H 3FH 63 Read File or Device 2.0+ H 40H 64 Write File or Device 2.0+ H 41H 65 Delete File 2.0+ H 42H 66 Set File Pointer 2.0+ H 43H 67 Get or Set File Attributes 2.0+ 44H 68 IOCTL (I/O Control) 2.0+ 45H 69 Duplicate Handle 2.0+ 46H 70 Redirect Handle 2.0+ 47H 71 Get Current Directory 2.0+ 48H 72 Allocate Memory Block 2.0+ Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 48H 72 Allocate Memory Block 2.0+ 49H 73 Release Memory Block 2.0+ 4AH 74 Resize Memory Block 2.0+ 4BH 75 Execute Program (EXEC) 2.0+ 4CH 76 Terminate Process with Return Code 2.0+ 4DH 77 Get Return Code 2.0+ 4EH 78 Find First File 2.0+ H 4FH 79 Find Next File 2.0+ H 50H 80 Reserved 51H 81 Reserved 52H 82 Reserved 53H 83 Reserved 54H 84 Get Verify Flag 2.0+ 55H 85 Reserved 56H 86 Rename File 2.0+ 57H 87 Get or Set File Date and Time 2.0+ H 58H 88 Get or Set Allocation Strategy 3.0+ 59H 89 Get Extended Error Information 3.0+ 5AH 90 Create Temporary File 3.0+ H Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 5AH 90 Create Temporary File 3.0+ H 5BH 91 Create New File 3.0+ H 5CH 92 Lock or Unlock File Region 3.0+ H 5DH 93 Reserved 5EH 94 Get Machine Name, Get or Set Printer 3.1+ Setup 5FH 95 Device Redirection 3.1+ 60H 96 Reserved 61H 97 Reserved 62H 98 Get PSP Address 3.0+ 63H 99 Get DBCS Lead Byte Table 2.25 only 64H 100 Reserved 65H 101 Get Extended Country Information 3.3+ 66H 102 Get or Set Code Page 3.3+ 67H 103 Set Handle Count 3.3+ 68H 104 Commit File 3.3+ H 69H 105 Reserved 6AH 106 Reserved Hex Dec Function name Vers F/H☼ ────────────────────────────────────────────────────────────────────────── 6AH 106 Reserved 6BH 107 Reserved 6CH 108 Extended Open File 4.0+ H ────────────────────────────────────────────────────────────────────────── Int 21H Function Summary by Category ╓┌─┌───────┌────────┌───────────────────────────────────────┌───────┌────────╖ Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── Character I/O 01H 1 Character Input with Echo 1.0+ 02H 2 Character Output 1.0+ 03H 3 Auxiliary Input 1.0+ 04H 4 Auxiliary Output 1.0+ 05H 5 Printer Output 1.0+ 06H 6 Direct Console I/O 1.0+ Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 06H 6 Direct Console I/O 1.0+ 07H 7 Unfiltered Character Input Without Echo 1.0+ 08H 8 Character Input Without Echo 1.0+ 09H 9 Display String 1.0+ 0AH 10 Buffered Keyboard Input 1.0+ 0BH 11 Check Input Status 1.0+ 0CH 12 Flush Input Buffer and Then Input 1.0+ File Operations 0FH 15 Open File 1.0+ F 10H 16 Close File 1.0+ F 11H 17 Find First File 1.0+ F 12H 18 Find Next File 1.0+ F 13H 19 Delete File 1.0+ F 16H 22 Create File 1.0+ F 17H 23 Rename File 1.0+ F 23H 35 Get File Size 1.0+ F 29H 41 Parse Filename 1.0+ F 3CH 60 Create File 2.0+ H Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 3CH 60 Create File 2.0+ H 3DH 61 Open File 2.0+ H 3EH 62 Close File 2.0+ H 41H 65 Delete File 2.0+ H 43H 67 Get or Set File Attributes 2.0+ 45H 69 Duplicate Handle 2.0+ 46H 70 Redirect Handle 2.0+ 4EH 78 Find First File 2.0+ H 4FH 79 Find Next File 2.0+ H 56H 86 Rename File 2.0+ 57H 87 Get or Set File Date and Time 2.0+ H 5AH 90 Create Temporary File 3.0+ H 5BH 91 Create New File 3.0+ H 67H 103 Set Handle Count 3.3+ 68H 104 Commit File 3.3+ H 6CH 108 Extended Open File 4.0+ H Record Operations 14H 20 Sequential Read 1.0+ F Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 14H 20 Sequential Read 1.0+ F 15H 21 Sequential Write 1.0+ F 1AH 26 Set DTA Address 1.0+ 21H 33 Random Read 1.0+ F 22H 34 Random Write 1.0+ F 24H 36 Set Relative Record Number 1.0+ F 27H 39 Random Block Read 1.0+ F 28H 40 Random Block Write 1.0+ F 2FH 47 Get DTA Address 2.0+ 3FH 63 Read File or Device 2.0+ H 40H 64 Write File or Device 2.0+ H 42H 66 Set File Pointer 2.0+ H 5CH 92 Lock or Unlock File Region 3.0+ H Directory Operations 39H 57 Create Directory 2.0+ 3AH 58 Delete Directory 2.0+ 3BH 59 Set Current Directory 2.0+ 47H 71 Get Current Directory 2.0+ Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 47H 71 Get Current Directory 2.0+ Disk Management 0DH 13 Disk Reset 1.0+ 0EH 14 Select Disk 1.0+ 19H 25 Get Current Disk 1.0+ 1BH 27 Get Default Drive Data 1.0+ 1CH 28 Get Drive Data 2.0+ 2EH 46 Set Verify Flag 1.0+ 36H 54 Get Drive Allocation Information 2.0+ 54H 84 Get Verify Flag 2.0+ Process Management 00H 0 Terminate Process 1.0+ 26H 38 Create New PSP 1.0+ 31H 49 Terminate and Stay Resident 2.0+ 4BH 75 Execute Program (EXEC) 2.0+ 4CH 76 Terminate Process with Return Code 2.0+ 4DH 77 Get Return Code 2.0+ Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 4DH 77 Get Return Code 2.0+ 62H 98 Get PSP Address 3.0+ Memory Management 48H 72 Allocate Memory Block 2.0+ 49H 73 Release Memory Block 2.0+ 4AH 74 Resize Memory Block 2.0+ 58H 88 Get or Set Allocation Strategy 3.0+ Network Functions 5EH 94 Get Machine Name, Get or Set Printer 3.1+ Setup 5FH 95 Device Redirection 3.1+ Time and Date 2AH 42 Get Date 1.0+ 2BH 43 Set Date 1.0+ 2CH 44 Get Time 1.0+ 2DH 45 Set Time 1.0+ Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 2DH 45 Set Time 1.0+ Miscellaneous System Functions 25H 37 Set Interrupt Vector 1.0+ 30H 48 Get MS-DOS Version Number 2.0+ 33H 51 Get or Set Break Flag, Get Boot Drive 2.0+ 35H 53 Get Interrupt Vector 2.0+ 38H 56 Get or Set Country Information 2.0+ 44H 68 IOCTL (I/O Control) 2.0+ 59H 89 Get Extended Error Information 3.0+ 63H 99 Get Lead Byte Table 2.25 only 65H 101 Get Extended Country Information 3.3+ 66H 102 Get or Set Code Page 3.3+ Reserved Functions 18H 24 Reserved 1DH 29 Reserved 1EH 30 Reserved Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── 1EH 30 Reserved 1FH 31 Reserved 20H 32 Reserved 32H 50 Reserved 34H 52 Reserved 37H 55 Reserved 50H 80 Reserved 51H 81 Reserved 52H 82 Reserved 53H 83 Reserved 55H 85 Reserved 5DH 93 Reserved 60H 96 Reserved 61H 97 Reserved 64H 100 Reserved 69H 105 Reserved 6AH 106 Reserved 6BH 107 Reserved ────────────────────────────────────────────────────────────────────────── Hex Dec Function name Vers F/H ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 20H [1.0] Terminate process ──────────────────────────────────────────────────────────────────────────── Terminates the current process. This is one of several methods that a program can use to perform a final exit. MS-DOS then takes the following actions: ■ All memory belonging to the process is released. ■ File buffers are flushed and any open handles for files or devices owned by the process are closed. ■ The termination handler vector (Int 22H) is restored from PSP:000AH. ■ The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. ■ [2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. ■ Control is transferred to the termination handler. If the program is returning to COMMAND.COM, control transfers to the resident portion, and the transient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and interpreted; otherwise, a prompt is issued for the next user command. Call with: CS = segment address of program segment prefix Returns: Nothing Notes: ■ Any files that have been written to using FCBs should be closed before performing this exit call; otherwise, data may be lost. ■ Other methods of performing a final exit are: ∙ Int 21H Function 00H ∙ Int 21H Function 31H ∙ Int 21H Function 4CH ∙ Int 27H ■ [2.0+] Int 21H Functions 31H and 4CH are the preferred methods for termination, since they allow a return code to be passed to the parent process. ■ [3.0+] If the program is running on a network, it should remove all locks it has placed on file regions before terminating. Example: Terminate the current program, returning control to the program's parent. . . . int 20h ; transfer to MS-DOS ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 00H Terminate process ──────────────────────────────────────────────────────────────────────────── Terminates the current process. This is one of several methods that a program can use to perform a final exit. MS-DOS then takes the following actions: ■ All memory belonging to the process is released. ■ File buffers are flushed and any open handles for files or devices owned by the process are closed. ■ The termination handler vector (Int 22H) is restored from PSP:000AH. ■ The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. ■ [2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. ■ Control is transferred to the termination handler. If the program is returning to COMMAND.COM, control transfers to the resident portion, and the transient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and interpreted; otherwise, a prompt is issued for the next user command. Call with: AH = 00H CS = segment address of program segment prefix Returns: Nothing Notes: ■ Any files that have been written to using FCBs should be closed before performing this exit call; otherwise, data may be lost. ■ Other methods of performing a final exit are: ∙ Int 20H ∙ Int 21H Function 31H ∙ Int 21H Function 4CH<21H4CH> ∙ Int 27H ■ [2.0+] Int 21H Functions 31H and 4CH are the preferred methods for termination, since they allow a return code to be passed to the parent process. ■ [3.0+] If the program is running on a network, it should remove all locks it has placed on file regions before terminating. Example: Terminate the current program, returning control to the program's parent. . . . mov ah,0 ; function number int 21h ; transfer to MS-DOS ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 01H Character input with echo ──────────────────────────────────────────────────────────────────────────── [1] Inputs a character from the keyboard, then echoes it to the display. If no character is ready, waits until one is available. [2.0+] Reads a character from the standard input device and echoes it to the standard output device. If no character is ready, waits until one is available. Input can be redirected. (If input has been redirected, there is no way to detect EOF.) Call with: AH = 01H Returns: AL = 8-bit input data Notes: ■ If the standard input is not redirected, and the character read is a Ctrl-C, an Int 23H is executed. If the standard input is redirected, a Ctrl-C is detected at the console, and BREAK is ON, an Int 23H is executed. ■ To read extended ASCII codes (such as the special function keys F1 to F10) on the IBM PC and compatibles, you must call this function twice. The first call returns the value 00H to signal the presence of an extended code. ■ See also Int 21H Functions 06H, 07H, and 08H, which provide character input with various combinations of echo and/or Ctrl-C sensing. ■ [2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using the predefined handle for the standard input (0000H), if input has not been redirected, or a handle obtained by opening the logical device CON. Example: Read one character from the keyboard into register AL, echo it to the display, and store it in the variable char. char db 0 ; input character . . . mov ah,1 ; function number int 21h ; transfer to MS-DOS mov char,al ; save character . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 02H Character output ──────────────────────────────────────────────────────────────────────────── [1] Outputs a character to the currently active video display. [2.0+] Outputs a character to the standard output device. Output can be redirected. (If output is redirected, there is no way to detect disk full.) Call with: AH = 02H DL = 8-bit data for output Returns: Nothing Notes: ■ If a Ctrl-C is detected at the keyboard after the requested character is output, an Int 23H is executed. ■ If the standard output has not been redirected, a backspace code (08H) causes the cursor to move left one position. If output has been redirected, the backspace code does not receive any special treatment. ■ [2.0+] You can also send strings to the display by performing a write (Int 21H Function 40H) using the predefined handle for the standard output (0001H), if output has not been redirected, or a handle obtained by opening the logical device CON. Example: Send the character "*" to the standard output device. . . . mov ah,2 ; function number mov dl,'*' ; character to output int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 03H Auxiliary input ──────────────────────────────────────────────────────────────────────────── [1] Reads a character from the first serial port. [2.0+] Reads a character from the standard auxiliary device. The default is the first serial port (COM1). Call with: AH = 03H Returns: AL = 8-bit input data Notes: ■ In most MS-DOS systems, the serial device is unbuffered and is not interrupt-driven. If the auxiliary device sends data faster than your program can process it, characters may be lost. ■ At startup on the IBM PC, PC-DOS initializes the first serial port to 2400 baud, no parity, 1 stop bit, and 8 data bits. Other implementations of MS-DOS may initialize the serial device differently. ■ There is no way for a user program to read the status of the auxiliary device or to detect I/O errors (such as lost characters) through this function call. On the IBM PC, more precise control can be obtained by calling ROM BIOS Int 14H or by driving the communications controller directly. ■ If a Ctrl-C is detected at the keyboard, an Int 23H is executed. ■ [2.0+] You can also input from the auxiliary device by requesting a read (Int 21H Function 3FH) using the predefined handle for the standard auxiliary device (0003H) or using a handle obtained by opening the logical device AUX. Example: Read a character from the standard auxiliary input and store it in the variable char. char db 0 ; input character . . . mov ah,3 ; function number int 21h ; transfer to MS-DOS mov char,al ; save character . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 04H Auxiliary output ──────────────────────────────────────────────────────────────────────────── [1] Outputs a character to the first serial port. [2.0+] Outputs a character to the standard auxiliary device. The default is the first serial port (COM1). Call with: AH = 04H DL = 8-bit data for output Returns: Nothing Notes: ■ If the output device is busy, this function waits until the device is ready to accept a character. ■ There is no way to poll the status of the auxiliary device using this function. On the IBM PC, more precise control can be obtained by calling ROM BIOS Int 14H or by driving the communications controller directly. ■ If a Ctrl-C is detected at the keyboard, an Int 23H is executed. ■ [2.0+] You can also send strings to the auxiliary device by performing a write (Int 21H Function 40H) using the predefined handle for the standard auxiliary device (0003H) or using a handle obtained by opening the logical device AUX. Example: Output a "*'' character to the auxiliary device. . . . mov ah,4 ; function number mov dl,'*' ; character to output int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 05H Printer output ──────────────────────────────────────────────────────────────────────────── [1] Sends a character to the first list device (PRN or LPT1). [2.0+] Sends a character to the standard list device. The default device is the printer on the first parallel port (LPT1), unless explicitly redirected by the user with the MODE command. Call with: AH = 05H DL = 8-bit data for output Returns: Nothing Notes: ■ If the printer is busy, this function waits until the printer is ready to accept the character. ■ There is no standardized way to poll the status of the printer under MS-DOS. ■ If a Ctrl-C is detected at the keyboard, an Int 23H is executed. ■ [2.0+] You can also send strings to the printer by performing a write (Int 21H Function 40H) using the predefined handle for the standard printer device (0004H) or using a handle obtained by opening the logical device PRN or LPT1. Example: Output the character "*'' to the list device. . . . mov ah,5 ; function number mov dl,'*' ; character to output int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 06H Direct console I/O ──────────────────────────────────────────────────────────────────────────── Used by programs that need to read and write all possible characters and control codes without any interference from the operating system. [1] Reads a character from the keyboard or writes a character to the display. [2.0+] Reads a character from the standard input device or writes a character to the standard output device. I/O may be redirected. (If I/O has been redirected, there is no way to detect EOF or disk full.) Call with: AH = 06H DL = function requested 00H─FEH if output request 0FFH if input request Returns: If called with DL = 00H─0FEH Nothing If called with DL = FFH and a character is ready Zero flag = clear AL = 8-bit input data If called with DL = FFH and no character is ready Zero flag = set Notes: ■ No special action is taken upon entry of a Ctrl-C when this service is used. ■ To read extended ASCII codes (such as the special function keys F1 to F10) on the IBM PC and compatibles, you must call this function twice. The first call returns the value 00H to signal the presence of an extended code. ■ See also Int 21H Functions 01H, 07H, and 08H, which provide character input with various combinations of echo and/or Ctrl-C sensing, and Functions 02H and 09H, which may be used to write characters to the standard output. ■ [2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using the predefined handle for the standard input (0000H), if input has not been redirected, or a handle obtained by opening the logical device CON. ■ [2.0+] You can also send characters to the display by issuing a write (Int 21H Function 40H) using the predefined handle for the standard output (0001H), if output has not been redirected, or a handle obtained by opening the logical device CON. Examples: Send the character "*" to the standard output device. . . . mov ah,6 ; function number mov dl,'*' ; character to output int 21h ; transfer to MS-DOS . . . Read a character from the standard input device and save it in the variable char. If no character is ready, wait until one is available. char db 0 ; input character . . . wait: mov ah,6 ; function number mov dl,0ffh ; parameter for read int 21h ; transfer to MS-DOS jz wait ; wait until char ready mov char,al ; save the character . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 07H Unfiltered character input without echo ──────────────────────────────────────────────────────────────────────────── [1] Reads a character from the keyboard without echoing it to the display. If no character is ready, waits until one is available. [2.0+] Reads a character from the standard input device without echoing it to the standard output device. If no character is ready, waits until one is available. Input may be redirected. (If input has been redirected, there is no way to detect EOF.) Call with: AH = 07H Returns: AL = 8-bit input data Notes: ■ No special action is taken upon entry of a Ctrl-C when this function is used. If Ctrl-C checking is required, use Int 21H Function 08H instead. ■ To read extended ASCII codes (such as the special function keys F1 to F10) on the IBM PC and compatibles, you must call this function twice. The first call returns the value 00H to signal the presence of an extended code. ■ See also Int 21H Functions 01H, 06H, and 08H, which provide character input with various combinations of echo and/or Ctrl-C sensing. ■ [2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using the predefined handle for the standard input (0000H), if input has not been redirected, or a handle obtained by opening the logical device CON. Example: Read a character from the standard input without echoing it to the display, and store it in the variable char. char db 0 ; input character . . . mov ah,7 ; function number int 21h ; transfer to MS-DOS mov char,al ; save character . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 08H Character input without echo ──────────────────────────────────────────────────────────────────────────── [1] Reads a character from the keyboard without echoing it to the display. If no character is ready, waits until one is available. [2.0+] Reads a character from the standard input device without echoing it to the standard output device. If no character is ready, waits until one is available. Input may be redirected. (If input has been redirected, there is no way to detect EOF.) Call with: AH = 08H Returns: AL = 8-bit input data Notes: ■ If the standard input is not redirected, and the character read is a Ctrl-C, an Int 23H is executed. If the standard input is redirected, a Ctrl-C is detected at the console, and BREAK is ON, an Int 23H is executed. To avoid possible interruption by a Ctrl-C, use Int 21H Function 07H instead. ■ To read extended ASCII codes (such as the special function keys F1 to F10) on the IBM PC and compatibles, you must call this function twice. The first call returns the value 00H to signal the presence of an extended code. ■ See also Int 21H Functions 01H, 06H, and 07H, which provide character input with various combinations of echo and/or Ctrl-C sensing. ■ [2.0+] You can also read the keyboard by issuing a read (Int 21H Function 3FH) using the predefined handle for the standard input (0000H), if input has not been redirected, or a handle obtained by opening the logical device CON. Example: Read a character from the standard input without echoing it to the display, allowing possible detection of Ctrl-C, and store the character in the variable char. char db 0 . . . mov ah,8 ; function number int 21h ; transfer to MS-DOS mov char,al ; save character . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 09H Display string ──────────────────────────────────────────────────────────────────────────── [1] Sends a string of characters to the display. [2.0+] Sends a string of characters to the standard output device. Output may be redirected. (If output has been redirected, there is no way to detect disk full.) Call with: AH = 09H DS:DX = segment:offset of string Returns: Nothing Notes: ■ The string must be terminated with the character $ (24H), which is not transmitted. Any other ASCII codes, including control codes, can be embedded in the string. ■ See Int 21H Functions 02H and 06H for single-character output to the video display or standard output device. ■ If a Ctrl-C is detected at the keyboard, an Int 23H is executed. ■ [2.0+] You can also send strings to the display by performing a write (Int 21H Function 40H) using the predefined handle for the standard output (0001H), if it has not been redirected, or a handle obtained by opening the logical device CON. Example: Send the string Hello World, followed by a carriage return and line feed, to the standard output device. cr equ 0dh lf equ 0ah msg db 'Hello World',cr,lf,'$' . . . mov ah,9 ; function number mov dx,seg msg ; address of string mov ds,dx mov dx,offset msg int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 0AH (10) Buffered keyboard input ──────────────────────────────────────────────────────────────────────────── [1] Reads a line from the keyboard and places it in a user-designated buffer. The characters are echoed to the display. [2.0+] Reads a string of bytes from the standard input device, up to and including an ASCII carriage return (0DH), and places them in a user-designated buffer. The characters are echoed to the standard output device. Input may be redirected. (If input has been redirected, there is no way to detect EOF.) Call with: AH = 0AH DS:DX = segment:offset of buffer Returns: Nothing (data placed in buffer) Notes: ■ The buffer used by this function has the following format: Byte Contents ──────────────────────────────────────────────────────────────────────── 0 maximum number of characters to read, set by program 1 number of characters actually read (excluding carriage return), set by MS-DOS 2+ string read from keyboard or standard input, terminated by a carriage return (0DH) ──────────────────────────────────────────────────────────────────────── ■ If the buffer fills to one fewer than the maximum number of characters it can hold, subsequent input is ignored and the bell is sounded until a carriage return is detected. ■ This input function is buffered with type-ahead capability, and all of the standard keyboard editing commands are active. ■ If the standard input is not redirected, and a Ctrl-C is detected at the console, an Int 23H is executed. If the standard input is redirected, a Ctrl-C is detected at the console, and BREAK is ON, an Int 23H is executed. ■ See Int 21H Functions 01H, 06H, 07H, and 08H for single-character input from the keyboard or standard input device. ■ [2.0+] You can also read strings from the keyboard by performing a read (Int 21H Function 3FH) using the predefined handle for the standard input (0000H), if it has not been redirected, or a handle obtained by opening the logical device CON. Example: Read a string that is a maximum of 80 characters long from the standard input device, placing it in the buffer named buff. buff db 81 ; maximum length of input db 0 ; actual length of input db 81 dup (0) ; actual input placed here . . . mov ah,0ah ; function number mov dx,seg buff ; input buffer address mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 0BH (11) Check input status ──────────────────────────────────────────────────────────────────────────── [1] Checks whether a character is available from the keyboard. [2.0+] Checks whether a character is available from the standard input device. Input can be redirected. Call with: AH = 0BH Returns: AL = 00H if no character is available FFH if at least one character is available Notes: ■ [1] If a Ctrl-C is detected, an Int 23H is executed. ■ [2.0+] If the standard input is not redirected, and a Ctrl-C is detected at the console, an Int 23H is executed. If the standard input is redirected, a Ctrl-C is detected at the console, and BREAK is ON, an Int 23H is executed. ■ If a character is waiting, this function will continue to return a true flag until the character is consumed with a call to Int 21H Function 01H, 06H, 07H, 08H, 0AH, or 3FH. ■ This function is equivalent to IOCTL Int 21H Function 44H Subfunction 06H. Example: Test whether a character is available from the standard input. . . . mov ah,0bh ; function number int 21h ; transfer to MS-DOS or al,al ; character waiting? jnz ready ; jump if char ready . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 0CH (12) Flush input buffer and then input ──────────────────────────────────────────────────────────────────────────── [1] Clears the type-ahead buffer and then invokes one of the keyboard input functions. [2.0+] Clears the standard input buffer and then invokes one of the character input functions. Input can be redirected. Call with: AH = 0CH AL = number of input function to be invoked after resetting buffer (must be 01H, 06H, 07H, 08H, or 0AH) (if AL = 0AH) DS:DX = segment:offset of input buffer Returns: (if called with AL = 01H, 06H, 07H, or 08H) AL = 8-bit input data (if called with AL = 0AH) Nothing (data placed in buffer) Notes: ■ The function exists to allow a program to defeat MS-DOS's type-ahead feature. It discards any characters that are waiting in MS-DOS's internal type-ahead buffer, forcing the specified input function to wait for a character (usually a keyboard entry) that is truly entered after the program's request. ■ The presence or absence of Ctrl-C checking during execution of this function depends on the function number placed in register AL. ■ A function number in AL other than 01H, 06H, 07H, 08H, or 0AH simply flushes the input buffer and returns control to the calling program. Example: Clear the type-ahead buffer, then wait for a character to be entered, echoing it and then returning it in AL. Store the character in the variable char. char db 0 . . . mov ah,0ch ; function number mov al,1 ; subfunction = input char int 21h ; transfer to MS-DOS mov char,al ; save character . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 0DH (13) Disk reset ──────────────────────────────────────────────────────────────────────────── Flushes all file buffers. All data that has been logically written by user programs, but has been temporarily buffered within MS-DOS, is physically written to the disk. Call with: AH = 0DH Returns: Nothing Notes: ■ This function does not update the disk directory for any files that are still open. If your program fails to properly close all files before the disk is removed, and files have changed size, the data forced out to the disk by this function may still be inaccessible because the directory entries will not be correct. ■ [3.3+] Int 21H Function 68H (Commit File) should be used in preference to this function, since it also updates the disk directory. Example: Flush all MS-DOS internal disk buffers. . . . mov ah,0dh ; function number int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 0EH (14) Select disk ──────────────────────────────────────────────────────────────────────────── Selects the specified drive to be the current, or default, disk drive and returns the total number of logical drives in the system. Call with: AH = 0EH DL = drive code (0 = A, 1 = B, etc.) Returns: AL = number of logical drives in system Notes: ■ [1] 16 drive designators (0 through 0FH) are available. ■ [2] 63 drive designators (0 through 3FH) are available. ■ [3.0+] 26 drive designators (0 through 19H) are available. ■ To preserve upward compatibility, new applications should limit themselves to the drive letters A─Z (0 = A, 1 = B, etc.). ■ Logical drives means the total number of block devices: floppy disks, simulated disk drives (RAMdisks), and hard-disk drives. A single physical hard-disk drive is frequently partitioned into two or more logical drives. ■ [1] [2] In single-drive IBM PC─compatible systems, the value 2 is returned in AL, because PC-DOS supports two logical drives (A: and B:) on the single physical floppy-disk drive. The actual number of physical drives in the system can be determined with ROM BIOS Int 11H. ■ [3.0+] The value returned in AL is either 5 or the drive code corresponding to the LASTDRIVE entry (if any) in CONFIG.SYS, whichever is greater. Example: Make drive B the current (default) disk drive. Save the total number of logical drives in the system in the variable drives. drives db 0 . . . mov ah,0eh ; function number mov dl,1 ; drive 1 = B int 21h ; transfer to MS-DOS mov drives,al ; save total drives . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 0FH (15) Open file ──────────────────────────────────────────────────────────────────────────── Opens a file and makes it available for subsequent read/write operations. Call with: AH = 0FH DS:DX = segment:offset of file control block Returns: If function successful (file found) AL = 00H and FCB filled in by MS-DOS as follows: drive field (offset 00H) = 1 for drive A, 2 for drive B, etc. current block field (offset 0CH) = 00H record size field (offset 0EH) = 0080H [2.0+] size field (offset 10H) = file size from directory [2.0+] date field (offset 14H) = date stamp from directory [2.0+] time field (offset 16H) = time stamp from directory If function unsuccessful (file not found) AL = 0FFH Notes: ■ If your program is going to use a record size other than 128 bytes, it should set the record-size field at FCB offset 0EH after the file is successfully opened and before any other disk operation. ■ If random access is to be performed, the calling program must also set the FCB relative-record field (offset 21H) after successfully opening the file. ■ For format of directory time and date, see Int 21H Function 57H. ■ [2.0+] Int 21H Function 3DH, which allows full access to the hierarchical directory structure, should be used in preference to this function. ■ [3.0+] If the program is running on a network, the file is opened for read/write access in compatibility sharing mode. Example: Attempt to open the file named QUACK.DAT on the default disk drive. myfcb db 0 ; drive = default db 'QUACK ' ; filename, 8 characters db 'DAT' ; extension, 3 characters db 25 dup (0) ; remainder of FCB . . . mov ah,0fh ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if open failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 10H (16) Close file ──────────────────────────────────────────────────────────────────────────── Closes a file, flushes all MS-DOS internal disk buffers associated with the file to disk, and updates the disk directory if the file has been modified or extended. Call with: AH = 10H DS:DX = segment:offset of file control block Returns: If function successful (directory update successful) AL = 00H If function unsuccessful (file not found in directory) AL = FFH Notes: ■ [1] [2] MS-DOS versions 1 and 2 do not reliably detect a floppy-disk change, and an error can occur if the user changes disks while a file is still open on that drive. In the worst case, the directory and file allocation table of the newly inserted disk can be damaged or destroyed. ■ [2.0+] Int 21H Function 3EH should be used in preference to this function. Example: Close the file that was previously opened using the file control block named myfcb. myfcb db 0 ; drive = default db 'QUACK ' ; filename, 8 characters db 'DAT' ; extension, 3 characters db 25 dup (0) ; remainder of FCB . . . mov ah,10h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if close failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 11H (17) Find first file ──────────────────────────────────────────────────────────────────────────── Searches the current directory on the designated drive for a matching filename. Call with: AH = 11H DS:DX = segment:offset of file control block Returns: If function successful (matching filename found) AL = 00H and buffer at current disk transfer area (DTA) address filled in as an unopened normal FCB or extended FCB, depending on which type of FCB was input to function If function unsuccessful (no matching filename found) AL = FFH Notes: ■ Use Int 21H Function 1AH to set the DTA to point to a buffer of adequate size before calling this function. ■ The wildcard character ? is allowed in the filename in all versions of MS-DOS. In versions 3.0 and later, the wildcard character * may also be used in a filename. If ? or * is used, this function returns the first matching filename. ■ An extended FCB must be used to search for files that have the system, hidden, read-only, directory, or volume-label attributes. ■ If an extended FCB is used, its attribute byte determines the type of search that will be performed. If the attribute byte contains 00H, only ordinary files are found. If the volume-label attribute bit is set, only volume labels will be returned (if any are present). If any other attribute or combination of attributes is set (such as hidden, system, or read-only), those files and all ordinary files will be matched. ■ [2.0+] Int 21H Function 4EH, which allows full access to the hierarchical directory structure, should be used in preference to this function. Example: Search for the first file with the extension .COM in the current directory. buff db 37 dup (0) ; receives search result myfcb db 0 ; drive = default db '????????' ; wildcard filename db 'COM' ; extension = COM db 25 dup (0) ; remainder of FCB . . . ; set DTA address mov ah,1ah ; function number mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS ; search for first match mov ah,11h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if no match . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 12H (18) Find next file ──────────────────────────────────────────────────────────────────────────── Given that a previous call to Int 21H Function 11H has been successful, returns the next matching filename (if any). Call with: AH = 12H DS:DX = segment:offset of file control block Returns: If function successful (matching filename found) AL = 00H and buffer at current disk transfer area (DTA) address set up as an unopened normal FCB or extended FCB, depending on which type of FCB was originally input to Int 21H Function 11H If function unsuccessful (no more matching filenames found) AL = FFH Notes: ■ This function assumes that the FCB used as input has been properly initialized by a previous call to Int 21H Function 11H (and possible subsequent calls to Int 21H Function 12H) and that the filename or extension being searched for contained at least one wildcard character. ■ As with Int 21H Function 11H, it is important to use Int 21H Function 1AH to set the DTA to a buffer of adequate size before calling this function. ■ [2.0+] Int 21H Functions 4EH and 4FH, which allow full access to the hierarchical directory structure, should be used in preference to this function. Example: Assuming a previous successful call to function 11H, search for the next file with the extension .COM in the current directory. If the DTA has not been changed since the previous search, another call to Function 1AH is not necessary. buff db 37 dup (0) ; receives search result my_fcb db 0 ; drive = default db '????????' ; wildcard filename db 'COM' ; extension = COM db 25 dup (0) ; remainder of FCB . . . ; set DTA address mov ah,1ah ; function number mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS ; search for next match mov ah,12h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if no match . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 13H (19) Delete file ──────────────────────────────────────────────────────────────────────────── Deletes all matching files from the current directory on the default or specified disk drive. Call with: AH = 13H DS:DX = segment:offset of file control block Returns: If function successful (file or files deleted) AL = 00H If function unsuccessful (no matching files were found, or at least one matching file was read-only) AL = FFH Notes: ■ The wildcard character ? is allowed in the filename; if ? is present and there is more than one matching filename, all matching files will be deleted. ■ [2.0+] Int 21H Function 41H, which allows full access to the hierarchical directory structure, should be used in preference to this function. ■ [3.0+] If the program is running on a network, the user must have Create rights to the directory containing the file to be deleted. Example: Delete the file MYFILE.DAT from the current disk drive and directory. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . mov ah,13h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump, delete failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 14H (20) Sequential read ──────────────────────────────────────────────────────────────────────────── Reads the next sequential block of data from a file, then increments the file pointer appropriately. Call with: AH = 14H DS:DX = segment:offset of previously opened file control block Returns: AL = 00H if read successful 01H if end of file 02H if segment wrap 03H if partial record read at end of file Notes: ■ The record is read into memory at the current disk transfer area (DTA) address, specified by the most recent call to Int 21H Function 1AH. If the size of the record and the location of the buffer are such that a segment overflow or wraparound would occur, the function fails with a return code of 02H. ■ The number of bytes of data to be read is specified by the record-size field (offset 0EH) of the file control block (FCB). ■ The file location of the data that will be read is specified by the combination of the current block field (offset 0CH) and current record field (offset 20H) of the file control block (FCB). These fields are also automatically incremented by this function. ■ If a partial record is read at the end of file, it is padded to the requested record length with zeros. ■ [3.0+] If the program is running on a network, the user must have Read access rights to the directory containing the file to be read. Example: Read 1024 bytes of data from the file specified by the previously opened file control block myfcb. myfcb db 0 ; drive = default db 'QUACK ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . mov ah,14h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb ; set record size mov word ptr myfcb+0eH,1024 int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if read failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 15H (21) Sequential write ──────────────────────────────────────────────────────────────────────────── Writes the next sequential block of data into a file, then increments the file pointer appropriately. Call with: AH = 15H DS:DX = segment:offset of previously opened file control block Returns: AL = 00H if write successful 01H if disk is full 02H if segment wrap Notes: ■ The record is written (logically, not necessarily physically) to the disk from memory at the current disk transfer area (DTA) address, specified by the most recent call to Int 21H Function 1AH. If the size of the record and the location of the buffer are such that a segment overflow or wraparound would occur, the function fails with a return code of 02H. ■ The number of bytes of data to be written is specified by the record-size field (offset 0EH) of the file control block (FCB). ■ The file location of the data that will be written is specified by the combination of the current block field (offset 0CH) and current record field (offset 20H) of the file control block (FCB). These fields are also automatically incremented by this function. ■ [3.0+] If the program is running on a network, the user must have Write access rights to the directory containing the file to be written. Example: Write 1024 bytes of data to the file specified by the previously opened file control block myfcb. myfcb db 0 ; drive = default db 'QUACK ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . mov ah,15h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb ; set record size mov word ptr myfcb+0eh,1024 int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if write failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 16H (22) Create file ──────────────────────────────────────────────────────────────────────────── Creates a new directory entry in the current directory or truncates any existing file with the same name to zero length. Opens the file for subsequent read/write operations. Call with: AH = 16H DS:DX = segment:offset of unopened file control block Returns: If function successful (file was created or truncated) AL = 00H and FCB filled in by MS-DOS as follows: drive field (offset 00H) = 1 for drive A, 2 for drive B, etc. current block field (offset 0CH) = 00H record size field (offset 0EH) = 0080H [2.0+] size field (offset 10H) = file size from directory [2.0+] date field (offset 14H) = date stamp from directory [2.0+] time field (offset 16H) = time stamp from directory If function unsuccessful (directory full) AL = FFH Notes: ■ Since an existing file with the specified name is truncated to zero length (i.e., all data in that file is irretrievably lost), this function must be used with caution. ■ If this function is called with an extended file control block (FCB), the new file may be assigned a special attribute, such as hidden or system, during its creation by setting the appropriate bit in the extended FCB's attribute byte. ■ Since this function also opens the file, a subsequent call to Int 21H Function 0FH is not required. ■ For format of directory time and date, see Int 21H Function 57H. ■ [2.0+] Int 21H Functions 3CH, 5AH, 5BH, and 6CH, which provide full access to the hierarchical directory structure, should be used in preference to this function. ■ [3.0+] If the program is running on a network, the user must have Create rights to the directory that will contain the new file. Example: Create a file in the current directory using the name in the file control block myfcb. myfcb db 0 ; drive = default db 'QUACK ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . mov ah,16h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if create failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 17H (23) Rename file ──────────────────────────────────────────────────────────────────────────── Alters the name of all matching files in the current directory on the disk in the specified drive. Call with: AH = 17H DS:DX = segment:offset of "special" file control block Returns: If function successful (one or more files renamed) AL = 00H If function unsuccessful (no matching files, or new filename matched an existing file) AL = FFH Notes: ■ The special file control block has a drive code, filename, and extension in the usual position (bytes 0 through 0BH) and a second filename starting 6 bytes after the first (offset 11H). ■ The ? wildcard character can be used in the first filename. Every file matching the first file specification will be renamed to match the second file specification. ■ If the second file specification contains any ? wildcard characters, the corresponding letters in the first filename are left unchanged. ■ The function terminates if the new name to be assigned to a file matches that of an existing file. ■ [2.0+] An extended FCB can be used with this function to rename a directory. ■ [2.0+] Int 21H Function 56H, which allows full access to the hierarchical directory structure, should be used in preference to this function. Example: Rename the file OLDNAME.DAT to NEWNAME.DAT. myfcb db 0 ; drive = default db 'OLDNAME ' ; old file name, 8 chars db 'DAT' ; old extension, 3 chars db 6 dup (0) ; reserved area db 'NEWNAME ' ; new file name, 8 chars db 'DAT' ; new extension, 3 chars db 14 dup (0) ; reserved area . . . mov ah,17h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if rename failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 18H (24) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 19H (25) Get current disk ──────────────────────────────────────────────────────────────────────────── Returns the drive code of the current, or default, disk drive. Call with: AH = 19H Returns: AL = drive code (0 = A, 1 = B, etc.) Notes: ■ To set the default drive, use Int 21H Function 0EH. ■ Some other Int 21H functions use drive codes beginning at 1 (that is, 1 = A, 2 = B, etc.) and reserve drive code zero for the default drive. Example: Get the current disk drive and save the code in the variable cdrive. cdrive db 0 ; current drive code . . . mov ah,19h ; function number int 21h ; transfer to MS-DOS mov cdrive,al ; save drive code . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 1AH (26) Set DTA address ──────────────────────────────────────────────────────────────────────────── Specifies the address of the disk transfer area (DTA) to be used for subsequent FCB-related function calls. Call with: AH = 1AH DS:DX = segment:offset of disk transfer area Returns: Nothing Notes: ■ If this function is never called by the program, the DTA defaults to a 128-byte buffer at offset 0080H in the program segment prefix. ■ In general, it is the programmer's responsibility to ensure that the buffer area specified is large enough for any disk operation that will use it. The only exception to this is that MS-DOS will detect and abort disk transfers that would cause a segment wrap. ■ Int 21H Function 2FH can be used to determine the current disk transfer address. ■ The only handle-type operations that rely on the DTA address are the directory search functions, Int 21H Functions 4EH and 4FH. Example: Set the current disk transfer area address to the buffer labeled buff. buff db 128 dup (?) . . . mov ah,1ah ; function number mov dx,seg buff ; address of disk mov ds,dx ; transfer area mov dx,offset buff int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 1BH (27) Get default drive data ──────────────────────────────────────────────────────────────────────────── Obtains selected information about the default disk drive and a pointer to the media identification byte from its file allocation table. Call with: AH = 1BH Returns: If function successful AL = sectors per cluster DS:BX = segment:offset of media ID byte CX = size of physical sector (bytes) DX = number of clusters for default drive If function unsuccessful (invalid drive or critical error) AL = FFH Notes: ■ The media ID byte has the following meanings: 0F0H 3.5-inch double-sided, 18 sectors or "other" 0F8H fixed disk 0F9H 5.25-inch double-sided, 15 sectors or 3.5-inch double-sided, 9 sectors 0FCH 5.25-inch single-sided, 9 sectors 0FDH 5.25-inch double-sided, 9 sectors 0FEH 5.25-inch single-sided, 8 sectors 0FFH 5.25-inch double-sided, 8 sectors ■ To obtain information about disks other than the one in the default drive, use Int 21H Function 1CH or 36H. ■ [1] The address returned in DS:BX points to a copy of the first sector of the actual FAT, with the media ID byte in the first byte. ■ [2.0+] The address returned in DS:BX points only to a copy of the media ID byte from the disk's FAT; the memory above that address cannot be assumed to contain the FAT or any other useful information. If direct access to the FAT is required, use Int 25H to read it into memory. Example: Determine whether the current disk drive is fixed or removable. . . . mov ah,1bh ; function number int 21h ; transfer to MS-DOS ; check media ID byte cmp byte ptr [bx],0f8h je fixed ; jump if fixed disk jmp floppy ; else assume floppy . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 1CH (28) Get drive data ──────────────────────────────────────────────────────────────────────────── Obtains allocation information about the specified disk drive and a pointer to the media identification byte from its file allocation table. Call with: AH = 1CH DL = drive code (0 = default, 1 = A, etc.) Returns: If function successful AL = sectors per cluster DS:BX = segment:offset of media ID byte CX = size of physical sector (bytes) DX = number of clusters for default or specified drive If function unsuccessful (invalid drive or critical error) AL = FFH Notes: ■ The media ID byte has the following meanings: 0F0H 3.5-inch double-sided, 18 sectors or "other" 0F8H fixed disk 0F9H 5.25-inch double-sided, 15 sectors or 3.5-inch double-sided, 9 sectors 0FCH 5.25-inch single-sided, 9 sectors 0FDH 5.25-inch double-sided, 9 sectors 0FEH 5.25-inch single-sided, 8 sectors 0FFH 5.25-inch double-sided, 8 sectors ■ In general, this call is identical to Int 21H Function 1BH, except for the ability to designate a specific disk drive. See also Int 21H Function 36H, which returns similar information. ■ [1] The address returned in DS:BX points to a copy of the first sector of the actual FAT, with the media ID byte in the first byte. ■ [2.0+] The address returned in DS:BX points only to a copy of the media ID byte from the disk's FAT; the memory above that address cannot be assumed to contain the FAT or any other useful information. If direct access to the FAT is required, use Int 25H to read it into memory. Example: Determine whether disk drive C is fixed or removable. . . . mov ah,1ch ; function number mov dl,3 ; drive code 3 = C int 21h ; transfer to MS-DOS ; check media ID byte cmp byte ptr ds:[bx],0f8h je fixed ; jump if fixed disk jmp floppy ; else assume floppy . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 1DH (29) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 1EH (30) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 1FH (31) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 20H (32) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 21H (33) Random read ──────────────────────────────────────────────────────────────────────────── Reads a selected record from a file into memory. Call with: AH = 21H DS:DX = segment:offset of previously opened file control block Returns: AL = 00H if read successful 01H if end of file 02H if segment wrap, read canceled 03H if partial record read at end of file Notes: ■ The record is read into memory at the current disk transfer area address, specified by the most recent call to Int 21H Function 1AH. It is the programmer's responsibility to ensure that this area is large enough for any record that will be transferred. If the size and location of the buffer are such that a segment overflow or wraparound would occur, the function fails with a return code of 02H. ■ The file location of the data to be read is determined by the combination of the relative-record field (offset 21H) and the record-size field (offset 0EH) of the FCB. The default record size is 128 bytes. ■ The current block field (offset 0CH) and current record field (offset 20H) are updated to agree with the relative-record field as a side effect of the function. ■ The relative-record field of the FCB is not incremented by this function; it is the responsibility of the application to update the FCB appropriately if it wishes to read successive records. Compare with Int 21H Function 27H, which can read multiple records with one function call and automatically increments the relative-record field. ■ If a partial record is read at end of file, it is padded to the requested record length with zeros. ■ [3.0+] If the program is running on a network, the user must have Read access rights to the directory containing the file to be read. Example: Open the file MYFILE.DAT, set the record length to 1024 bytes, then read record number 4 from the file into the buffer named buff. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB buff db 1024 dup (?) ; receives read data . . . ; open the file mov ah,0fh ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check open status jnz error ; jump if no file ; set DTA address mov ah,1ah ; function number mov dx,offset buff ; read buffer address int 21h ; transfer to MS-DOS ; set record size mov word ptr myfcb+0eh,1024 ; set record number mov word ptr myfcb+21h,4 mov word ptr myfcb+23h,0 ; read the record mov ah,21h ; function number mov dx,offset myfcb ; address of FCB int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if read failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 22H (34) Random write ──────────────────────────────────────────────────────────────────────────── Writes data from memory into a selected record in a file. Call with: AH = 22H DS:DX = segment:offset of previously opened file control block Returns: AL = 00H if write successful 01H if disk full 02H if segment wrap, write canceled Notes: ■ The record is written (logically, not necessarily physically) to the file from memory at the current disk transfer address, specified by the most recent call to Int 21H Function 1AH. If the size and location of the buffer are such that a segment overflow or wraparound would occur, the function fails with a return code of 02H. ■ The file location of the data to be written is determined by the combination of the relative-record field (offset 21H) and the record-size field (offset 0EH) of the FCB. The default record size is 128 bytes. ■ The current block field (offset 0CH) and current record field (offset 20H) are updated to agree with the relative-record field as a side effect of the function. ■ The relative-record field of the FCB is not incremented by this function; it is the responsibility of the application to update the FCB appropriately if it wishes to write successive records. Compare with Int 21H Function 28H, which can write multiple records with one function call and automatically increments the relative-record field. ■ If a record is written beyond the current end of file, the space between the old end of file and the new record is allocated but not initialized. ■ [3.0+] If the program is running on a network, the user must have Write access rights to the directory containing the file to be written. Example: Open the file MYFILE.DAT, set the record length to 1024 bytes, write record number 4 into the file from the buffer named buff, then close the file. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB buff db 1024 dup (?) ; buffer for write . . . ; open the file mov ah,0fh ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if no file ; set DTA address mov dx,offset buff ; buffer address mov ah,1ah ; function number int 21h ; transfer to MS-DOS ; set record size mov word ptr myfcb+0eh,1024 ; set record number mov word ptr myfcb+21h,4 mov word ptr myfcb+23h,0 ; write the record mov ah,22h ; function number mov dx,offset myfcb ; address of FCB int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if write failed ; close the file mov ah,10h ; function number mov dx,offset myfcb ; address of FCB int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if close failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 23H (35) Get file size ──────────────────────────────────────────────────────────────────────────── Searches for a matching file in the current directory; if one is found, updates the FCB with the file's size in terms of number of records. Call with: AH = 23H DS:DX = segment:offset of unopened file control block Returns: If function successful (matching file found) AL = 00H and FCB relative-record field (offset 21H) set to the number of records in the file, rounded up if necessary to the next complete record If function unsuccessful (no matching file found) AL = FFH Notes: ■ An appropriate value must be placed in the FCB record-size field (offset 0EH) before calling this function. There is no default record size for this function. Compare with the FCB-related open and create functions (Int 21H Functions 0FH and 16H), which initialize the FCB for a default record size of 128 bytes. ■ The record-size field can be set to 1 to find the size of the file in bytes. ■ Because record numbers are zero based, this function can be used to position the FCB's file pointer to the end of file. Example: Determine the size in bytes of the file MYFILE.DAT and leave the result in registers DX:AX. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . mov ah,23h ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb ; record size = 1 byte mov word ptr myfcb+0eh,1 int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if no file ; get file size in bytes mov ax,word ptr myfcb+21h mov dx,word ptr myfcb+23h . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 24H (36) Set relative record number ──────────────────────────────────────────────────────────────────────────── Sets the relative-record-number field of a file control block (FCB) to correspond to the current file position as recorded in the opened FCB. Call with: AH = 24H DS:DX = segment:offset of previously opened file control block Returns: AL is destroyed (other registers not affected) FCB relative-record field (offset 21H) updated Notes: ■ This function is used when switching from sequential to random I/O within a file. The contents of the relative-record field (offset 21H) are derived from the record size (offset 0EH), current block (offset 0CH), and current record (offset 20H) fields of the file control block. ■ All four bytes of the FCB relative-record field (offset 21H) should be initialized to zero before calling this function. Example: After a series of sequential record transfers have been performed using the file control block myfcb, obtain the current relative-record position in the file and leave the record number in DX. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . mov dx,seg myfcb ; make FCB addressable mov ds,dx ; initialize relative ; record field to zero mov word ptr myfcb+21h,0 mov word ptr myfcb+23h,0 ; now set record number mov ah,24h ; function number mov dx,offset myfcb ; address of FCB int 21h ; transfer to MS-DOS ; load record number in DX mov dx,word ptr myfcb+21h . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 25H (37) Set interrupt vector ──────────────────────────────────────────────────────────────────────────── Initializes a CPU interrupt vector to point to an interrupt handling routine. Call with: AH = 25H AL = interrupt number DS:DX = segment:offset of interrupt handling routine Returns: Nothing Notes: ■ This function should be used in preference to direct editing of the interrupt-vector table by well-behaved applications. ■ Before an interrupt vector is modified, its original value should be obtained with Int 21H Function 35H and saved, so that it can be restored using this function before program termination. Example: Install a new interrupt handler, named zdiv, for "divide by zero" CPU exceptions. . . . mov ah,25h ; function number mov al,0 ; interrupt number mov dx,seg zdiv ; address of handler mov ds,dx mov dx,offset zdiv int 21h ; transfer to MS-DOS . . . zdiv: ; int 00h handler iret ; (does nothing) ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 26H (38) Create new PSP ──────────────────────────────────────────────────────────────────────────── Copies the program segment prefix (PSP) of the currently executing program to a specified segment address in free memory, then updates the new PSP to make it usable by another program. Call with: AH = 26H DX = segment of new program segment prefix Returns: Nothing Notes: ■ After the executing program's PSP is copied into the new segment, the memory size information in the new PSP is updated appropriately and the current contents of the termination (Int 22H), Ctrl-C handler (Int 23H), and critical-error handler (Int 24H) vectors are saved starting at offset 0AH. ■ This function does not load another program or in itself cause one to be executed. ■ [2.0+] Int 21H Function 4BH (EXEC), which can be used to load and execute programs or overlays in either .COM or .EXE format, should be used in preference to this function. Example: Create a new program segment prefix 64 KB above the currently executing program. This example assumes that the running program was loaded as a .COM file so that the CS register points to its PSP throughout its execution. If the running program was loaded as a .EXE file, the address of the PSP must be obtained with Int 21H Function 62H (under MS-DOS 3.0 or later) or by saving the original contents of the DS or ES registers at entry. . . . mov ah,26h ; function number mov dx,cs ; PSP segment of ; this program add dx,1000h ; add 64 KB as ; paragraph address int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 27H (39) Random block read ──────────────────────────────────────────────────────────────────────────── Reads one or more sequential records from a file into memory, starting at a designated file location. Call with: AH = 27H CX = number of records to read DS:DX = segment:offset of previously opened file control block Returns: AL = 00H if all requested records read 01H if end of file 02H if segment wrap 03H if partial record read at end of file CX = actual number of records read Notes: ■ The records are read into memory at the current disk transfer area address, specified by the most recent call to Int 21H Function 1AH. It is the programmer's responsibility to ensure that this area is large enough for the group of records that will be transferred. If the size and location of the buffer are such that a segment overflow or wraparound would occur, the function fails with a return code of 02H. ■ The file location of the data to be read is determined by the combination of the relative-record field (offset 21H) and the record-size field (offset 0EH) of the FCB. The default record size is 128 bytes. ■ After the disk transfer is performed, the current block (offset 0CH), current record (offset 20H), and relative-record (offset 21H) fields of the FCB are updated to point to the next record in the file. ■ If a partial record is read at the end of file, the remainder of the record is padded with zeros. ■ Compare with Int 21H Function 21H, which transfers only one record per function call and does not update the FCB relative-record field. ■ [3.0+] If the program is running on a network, the user must have Read access rights to the directory containing the file to be read. Example: Read four 1024-byte records starting at record number 8 into the buffer named buff, using the file control block myfcb. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB buff db 4096 dup (?) ; buffer for data . . . ; set DTA address mov ah,1ah ; function number mov dx,seg buff ; address of buffer mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS ; set relative-record number mov word ptr myfcb+21h,8 mov word ptr myfcb+23h,0 ; set record size mov word ptr myfcb+0eh,1024 ; read the records mov ah,27h ; function number mov cx,4 ; number of records mov dx,offset myfcb ; address of FCB int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if read error . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 28H (40) Random block write ──────────────────────────────────────────────────────────────────────────── Writes one or more sequential records from memory to a file, starting at a designated file location. Call with: AH = 28H CX = number of records to write DS:DX = segment:offset of previously opened file control block Returns: AL = 00H if all requested records written 01H if disk full 02H if segment wrap CX = actual number of records written Notes: ■ The records are written (logically, not necessarily physically) to disk from memory at the current disk transfer area address, specified by the most recent call to Int 21H Function 1AH. If the size and location of the buffer are such that a segment overflow or wraparound would occur, the function fails with a return code of 02H. ■ The file location of the data to be written is determined by the combination of the relative-record field (offset 21H) and the record-size field (offset 0EH) of the FCB. The default record size is 128 bytes. ■ After the disk transfer is performed, the current block (offset 0CH), current record (offset 20H), and relative-record (offset 21H) fields of the FCB are updated to point to the next record in the file. ■ If this function is called with CX = 0, no data is written to the disk but the file is extended or truncated to the length specified by combination of the record-size (offset 0EH) and the relative-record (offset 21H) fields of the FCB. ■ Compare with Int 21H Function 22H, which transfers only one record per function call and does not update the FCB relative-record field. ■ [3.0+] If the program is running on a network, the user must have Write access rights to the directory containing the file to be written. Example: Write four 1024-byte records, starting at record number 8, to disk from the buffer named buff, using the file control block myfcb. myfcb db 0 ; drive = default db 'MYFILE ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB buff db 4096 dup (?) ; buffer for data . . . ; set DTA address mov ah,1ah ; function number mov dx,seg buff ; address of buffer mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS ; set relative-record number mov word ptr myfcb+21h,8 mov word ptr myfcb+23h,0 ; set record size mov word ptr myfcb+0eh,1024 ; write the records mov ah,28h ; function number mov cx,4 ; number of records mov dx,offset myfcb ; address of FCB int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if write error . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 29H (41) Parse filename ──────────────────────────────────────────────────────────────────────────── Parses a text string into the various fields of a file control block (FCB). Call with: AH = 29H AL = flags to control parsing Bit 3 = 1 if extension field in FCB will be modified only if an extension is specified in the string being parsed. = 0 if extension field in FCB will be modified regardless; if no extension is present in the parsed string, FCB extension is set to ASCII blanks. Bit 2 = 1 if filename field in FCB will be modified only if a filename is specified in the string being parsed. = 0 if filename field in FCB will be modified regardless; if no filename is present in the parsed string, FCB filename is set to ASCII blanks. Bit 1 = 1 if drive ID byte in FCB will be modified only if a drive was specified in the string being parsed. = 0 if the drive ID byte in FCB will be modified regardless; if no drive specifier is present in the parsed string, FCB drive-code field is set to 0 (default). Bit 0 = 1 if leading separators will be scanned off (ignored). = 0 if leading separators will not be scanned off. DS:SI = segment:offset of string ES:DI = segment:offset of file control block Returns: AL = 00H if no wildcard characters encountered 01H if parsed string contained wildcard characters FFH if drive specifier invalid DS:SI = segment:offset of first character after parsed filename ES:DI = segment:offset of formatted unopened file control block Notes: ■ This function regards the following as separator characters: [1] : . ; , = + tab space / " [ ] [2.0+] : . ; , = + tab space ■ This function regards all control characters and the following as terminator characters: : . ; , = + tab space < > | / " [ ] ■ If no valid filename is present in the string to be parsed, upon return ES:DI + 1 points to an ASCII blank. ■ If the * wildcard character occurs in a filename or extension, it and all remaining characters in the corresponding field in the FCB are set to ?. ■ This function (and file control blocks in general) cannot be used with file specifications that include a path. Example: Parse the string fname into the file control block myfcb. fname db 'D:QUACK.DAT',0 ; filename to be parsed myfcb db 37 dup (0) ; becomes file control block . . . mov ah,29h ; function number mov al,01h ; skip leading separators mov si,seg fname ; address of filename mov ds,si mov si,offset fname mov di,seg myfcb ; address of FCB mov es,di mov di,offset myfcb int 21h ; transfer to MS-DOS cmp al,0ffh ; check status je error ; jump, drive invalid . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 2AH (42) Get date ──────────────────────────────────────────────────────────────────────────── Obtains the system day of the month, day of the week, month, and year. Call with: AH = 2AH Returns: CX = year (1980 through 2099) DH = month (1 through 12) DL = day (1 through 31) Under MS-DOS versions 1.1 and later AL = day of the week (0 = Sunday, 1 = Monday, etc.) Notes: ■ This function's register format is the same as that required for Int 21H Function 2BH (Set Date). ■ This function can be used together with Int 21H Function 2BH to find the day of the week for an arbitrary date. The current date is first obtained with Function 2AH and saved. The date of interest is then set with Function 2BH, and the day of the week for that date is obtained with a subsequent call to Function 2AH. Finally, the current date is restored with an additional call to Function 2BH, using the values obtained with the original Function 2AH call. Example: Obtain the current date and save its components in the variables year, day, and month. year dw 0 month db 0 day db 0 . . . mov ah,2ah ; function number int 21h ; transfer to MS-DOS mov year,cx ; save year (word) mov month,dh ; save month (byte) mov day,dl ; save day (byte) . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 2BH (43) Set date ──────────────────────────────────────────────────────────────────────────── Initializes the system clock driver to a specific date. The system time is not affected. Call with: AH = 2BH CX = year (1980 through 2099) DH = month (1 through 12) DL = day (1 through 31) Returns: AL = 00H if date set successfully FFH if date not valid (ignored) Note: ■ This function's register format is the same as that required for Int 21H Function 2AH (Get Date). Example: Set the system date according to the contents of the variables year, day, and month. year dw 0 month db 0 day db 0 . . . mov ah,2bh ; function number mov cx,year ; get year (word) mov dh,month ; get month (byte) mov dl,day ; get day (byte) int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if date invalid . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 2CH (44) Get time ──────────────────────────────────────────────────────────────────────────── Obtains the time of day from the system real-time clock driver, converted to hours, minutes, seconds, and hundredths of seconds. Call with: AH = 2CH Returns: CH = hours (0 through 23) CL = minutes (0 through 59) DH = seconds (0 through 59) DL = hundredths of seconds (0 through 99) Notes: ■ This function's register format is the same as that required for Int 21H Function 2DH (Set Time). ■ On most IBM PC─compatible systems, the real-time clock does not have a resolution of single hundredths of seconds. On such machines, the values returned by this function in register DL are discontinuous. Example: Obtain the current time and save its two major components in the variables hours and minutes. hours db 0 minutes db 0 . . . mov ah,2ch ; function number int 21h ; transfer to MS-DOS mov hours,ch ; save hours (byte) mov minutes,cl ; save minutes (byte) . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 2DH (45) Set time ──────────────────────────────────────────────────────────────────────────── Initializes the system real-time clock to a specified hour, minute, second, and hundredth of second. The system date is not affected. Call with: AH = 2DH CH = hours (0 through 23) CL = minutes (0 through 59) DH = seconds (0 through 59) DL = hundredths of seconds (0 through 99) Returns: AL = 00H if time set successfully FFH if time not valid (ignored) Note: ■ This function's register format is the same as that required for Int 21H Function 2CH (Get Time). Example: Set the system time according to the contents of the variables hours and minutes. Force the current seconds and hundredths of seconds to zero. hours db 0 minutes db 0 . . . mov ah,2dh ; function number mov ch,hours ; get hours (byte) mov cl,minutes ; get minutes (byte) mov dx,0 ; force seconds and ; hundredths to zero int 21h ; transfer to MS-DOS or al,al ; check status jnz error ; jump if time invalid . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [1.0] Function 2EH (46) Set verify flag ──────────────────────────────────────────────────────────────────────────── Turns off or turns on the operating-system flag for automatic read-after-write verification of data. Call with: AH = 2EH AL = 00H if turning off verify flag 01H if turning on verify flag DL = 00H (MS-DOS versions 1 and 2) Returns: Nothing Notes: ■ Because read-after-write verification slows disk operations, the default setting of the verify flag is OFF. ■ If a particular disk unit's device driver does not support read-after-write verification, this function has no effect. ■ The current state of the verify flag can be determined using Int 21H Function 54H. ■ The state of the verify flag is also controlled by the MS-DOS commands VERIFY OFF and VERIFY ON. Example: Save the current state of the system verify flag in the variable vflag, then force all subsequent disk writes to be verified. vflag db 0 ; previous verify flag . . . ; get verify flag mov ah,54h ; function number int 21h ; transfer to MS-DOS mov vflag,al ; save current flag state ; set verify flag mov ah,2eh ; function number mov al,1 ; AL = 1 for verify on mov dl,0 ; DL must be zero int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 2FH (47) Get DTA address ──────────────────────────────────────────────────────────────────────────── Obtains the current address of the disk transfer area (DTA) for FCB file read/write operations. Call with: AH = 2FH Returns: ES:BX = segment:offset of disk transfer area Note: ■ The disk transfer area address is set with Int 21H Function 1AH. The default DTA is a 128-byte buffer at offset 80H in the program segment prefix. Example: Obtain the current disk transfer area address and save it in the variable olddta. olddta dd ? ; save disk transfer address . . . mov ah,2fh ; function number int 21h ; transfer to MS-DOS ; save it as DWORD pointer mov word ptr olddta,bx mov word ptr olddta+2,es . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 30H (48) Get MS-DOS version number ──────────────────────────────────────────────────────────────────────────── Returns the version number of the host MS-DOS operating system. This function is used by application programs to determine the capabilities of their environment. Call with: AH = 30H AL = 00H Returns: If running under MS-DOS version 1 AL = 00H If running under MS-DOS versions 2.0 or later AL = major version number (MS-DOS 3.10 = 3, etc.) AH = minor version number (MS-DOS 3.10 = 0AH, etc.) BH = Original Equipment Manufacturer's (OEM's) serial number (OEM-dependent──usually 00H for IBM's PC-DOS, 0FFH or other values for MS-DOS) BL:CX = 24-bit user serial number (optional, OEM-dependent) Notes: ■ Because this function was not defined under MS-DOS version 1, it should always be called with AL = 00H. In an MS-DOS version 1 environment, AL will be returned unchanged. ■ Care must be taken not to exit in an unacceptable fashion if an MS-DOS version 1 environment is detected. For example, Int 21H Function 4CH (Terminate Process with Return Code), Int 21H Function 40H (Write to File or Device), and the standard error handle are not available in MS-DOS version 1. In such cases a program should display an error message using Int 21H Function 09H and then terminate with Int 20H or Int 21H Function 00H. Example: Get the MS-DOS version number, terminating the current process with an error message if not running under MS-DOS version 2.0 or later. cr equ 0dh ; ASCII carriage return lf equ 0ah ; ASCII line feed msg db cr,lf db 'Wrong MS-DOS version' db cr,lf,'$' . . . mov ax,3000h ; function number int 21h ; transfer to MS-DOS cmp al,2 ; version 2 or later? jae label1 ; yes, jump ; display error message mov ah,09 ; function number mov dx,offset msg ; message address int 21h ; transfer to MS-DOS ; terminate process mov ah,0 ; function number int 21h ; transfer to MS-DOS label1: . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 31H (49) Terminate and stay resident ──────────────────────────────────────────────────────────────────────────── Terminates execution of the currently executing program, passing a return code to the parent process, but reserves part or all of the program's memory so that it will not be overlaid by the next transient program to be loaded. MS-DOS then takes the following actions: ■ File buffers are flushed and any open handles for files or devices owned by the process are closed. ■ The termination handler vector (Int 22H) is restored from PSP:000AH. ■ The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. ■ [2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. ■ Control is transferred to the termination handler. If the program is returning to COMMAND.COM, control transfers to the resident portion, and the transient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and interpreted; otherwise, a prompt is issued for the next user command. Call with: AH = 31H AL = return code DX = amount of memory to reserve (in paragraphs) Returns: Nothing Notes: ■ This function call is typically used to allow user-written utilities, drivers, or interrupt handlers to be loaded as ordinary .COM or .EXE programs and then remain resident. Subsequent entrance to the code is via a hardware or software interrupt. ■ This function attempts to set the initial memory allocation block to the length in paragraphs specified in register DX. If other memory blocks have been requested by the application using Int 21H Function 48H, they will not be released by this function. ■ Other methods of performing a final exit are: ∙ Int 20H ∙ Int 21H Function 00H ∙ Int 21H Function 4CH ∙ Int 27H ■ The return code may be retrieved by a parent process with Int 21H Function 4DH (Get Return Code). It can also be tested in a batch file with an IF ERRORLEVEL statement. By convention, a return code of zero indicates successful execution, and a nonzero return code indicates an error. ■ This function should not be called by .EXE programs that are loaded at the high end of the transient program area (that is, linked with the /HIGH switch) because doing so reserves the memory that is normally used by the transient part of COMMAND.COM. If COMMAND.COM cannot be reloaded, the system will fail. ■ [2.0+] This function should be used in preference to Int 27H because it supports return codes, allows larger amounts of memory to be reserved, and does not require CS to contain the segment of the program segment prefix. ■ [3.0+] If the program is running on a network, it should remove all locks it has placed on file regions before terminating. Example: Exit with a return code of 1 but stay resident, reserving 16 KB of memory starting at the program segment prefix of the process. . . . mov ah,31h ; function number mov al,1 ; return code for parent mov dx,0400h ; paragraphs to reserve int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 32H (50) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 33H (51) Get or set break flag, get boot drive ──────────────────────────────────────────────────────────────────────────── Obtains or changes the status of the operating system's break flag, which influences Ctrl-C checking during function calls. Also returns the system boot drive in version 4.0. Call with: If getting break flag AH = 33H AL = 00H If setting break flag AH = 33H AL = 01H DL = 00H if turning break flag OFF 01H if turning break flag ON [4] If getting boot drive AH = 33H AL = 05H Returns: If called with AL = 00H or 01H DL = 00H break flag is OFF 01H break flag is ON [4] If called with AL = 05H DL = boot drive (1 = A, 2 = B, etc.) Notes: ■ When the system break flag is on, the keyboard is examined for a Ctrl-C entry whenever any operating-system input or output is requested; if Ctrl-C is detected, control is transferred to the Ctrl-C handler (Int 23H). When the break flag is off, MS-DOS only checks for a Ctrl-C entry when executing the traditional character I/O functions (Int 21H Functions 01H through 0CH). ■ The break flag is not part of the local environment of the currently executing program; it affects all programs. An application that alters the flag should first save the flag's original status, then restore the flag before terminating. Example: Save the current state of the system break flag in the variable brkflag, then turn the break flag off to disable Ctrl-C checking during most MS-DOS function calls. brkflag db 0 ; save break flag . . . ; get current break flag mov ah,33h ; function number mov al,0 ; AL = 0 to get flag int 21h ; transfer to MS-DOS mov brkflag,dl ; save current flag ; now set break flag mov ah,33h ; function number mov al,1 ; AL = 1 to set flag mov dl,0 ; set break flag OFF int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 34H (52) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 35H (53) Get interrupt vector ──────────────────────────────────────────────────────────────────────────── Obtains the address of the current interrupt-handler routine for the specified machine interrupt. Call with: AH = 35H AL = interrupt number Returns: ES:BX = segment:offset of interrupt handler Note: ■ Together with Int 21H Function 25H (Set Interrupt Vector), this function is used by well-behaved application programs to modify or inspect the machine interrupt vector table. Example: Obtain the address of the current interrupt handler for hardware interrupt level 0 (divide by zero) and save it in the variable oldint0. oldint0 dd ? ; previous handler address . . . mov ah,35h ; function number mov al,0 ; interrupt level int 21h ; transfer to MS-DOS ; save old handler address mov word ptr oldint0,bx mov word ptr oldint0+2,es . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 36H (54) Get drive allocation information ──────────────────────────────────────────────────────────────────────────── Obtains selected information about a disk drive, from which the drive's capacity and remaining free space can be calculated. Call with: AH = 36H DL = drive code (0 = default, 1 = A, etc.) Returns: If function successful AX = sectors per cluster BX = number of available clusters CX = bytes per sector DX = clusters per drive If function unsuccessful (drive invalid) AX = FFFFH Notes: ■ This function regards "lost" clusters as being in use and does not report them as part of the number of available clusters, even though they are not assigned to a file. ■ Similar information is returned by Int 21H Functions 1BH and 1CH. Example: Calculate the capacity of disk drive C in bytes, leaving the result in the variable drvsize. (This code assumes that the product of sectors/cluster * bytes/sector will not overflow 16 bits.) drvsize dd ? ; drive C size in bytes . . . mov ah,36h ; function number mov dl,3 ; drive C = 3 int 21h ; transfer to MS-DOS mul cx ; sectors/cluster ; * bytes/sector mul dx ; * total clusters ; result now in DX:AX ; store low word mov word ptr drvsize,ax ; store high word mov word ptr drvsize+2,dx . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 37H (55) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 38H (56) Get or set country information ──────────────────────────────────────────────────────────────────────────── [2] Obtains internationalization information for the current country. [3.0+] Obtains internationalization information for the current or specified country or sets the current country code. Call with: If getting country information (MS-DOS version 2) AH = 38H AL = 0 to get "current" country information DS:DX = segment:offset of buffer for returned information If getting country information (MS-DOS versions 3.0 and later) AH = 38H AL = 0 to get "current" country information 1─FEH to get information for countries with code < 255 FFH to get information for countries with code >= 255 BX = country code, if AL = FFH DS:DX = segment:offset of buffer for returned information If setting current country code (MS-DOS versions 3.0 and later) AH = 38H AL = 1─FEH country code for countries with code < 255 FFH for countries with code >= 255 BX = country code, if AL = 0FFH DX = FFFFH Returns: If function successful Carry flag = clear and, if getting internationalization information BX = country code DS:DX = segment:offset of buffer holding internationalization information and buffer filled in as follows: (for PC-DOS 2.0 and 2.1) Byte(s) Contents 00H─01H date format 0 = USA m d y 1 = Europe d m y 2 = Japan y m d 02H─03H ASCIIZ currency symbol 04H─05H ASCIIZ thousands separator 06H─07H ASCIIZ decimal separator 08H─1FH reserved (for MS-DOS versions 2.0 and later, PC-DOS versions 3.0 and later) Byte(s) Contents 00H─01H date format 0 = USA m d y 1 = d m y Europe 2 = Japan y m d 02H─06H ASCIIZ currency symbol string 07H─08H ASCIIZ thousands separator character 09H─0AH ASCIIZ decimal separator character 0BH─0CH ASCIIZ date separator character 0DH─0EH ASCIIZ time separator character 0FH currency format bit 0 = 0 if currency symbol precedes value = 1 if currency symbol follows value bit 1 = 0 if no space between value and currency symbol = 1 if one space between value and currency symbol bit 2 = 0 if currency symbol and decimal are separate = 1 if currency symbol replaces decimal separator 10H number of digits after decimal in currency 11H time format bit 0 = 0 if 12-hour clock = 1 if 24-hour clock 12H─15H case-map call address 16H─17H ASCIIZ data-list separator 18H─21H reserved If function unsuccessful Carry flag = set AX = error code Notes: ■ The default country code is determined by the COUNTRY= directive in CONFIG.SYS or by the KEYBxx keyboard driver file if one is loaded. Otherwise, the default country code is OEM-dependent. ■ The previous contents of register CX may be destroyed by the Get Country Information subfunction. ■ The case-map call address is the segment:offset of a FAR procedure that performs country-specific mapping on character values from 80H through 0FFH. The procedure must be called with the character to be mapped in register AL. If an alternate value exists for that character, it is returned in AL; otherwise, AL is unchanged. In general, lowercase characters are mapped to their uppercase equivalents, and accented or otherwise modified vowels are mapped to their plain vowel equivalents. ■ [3.0+] The value in register DX is used by MS-DOS to select between the Set Country and Get Country Information subfunctions. ■ [3.3+] Int 21H Function 65H (Get Extended Country Information) returns a superset of the information supplied by this function. Examples: Obtain internationalization information for the current country in the buffer ctrybuf. ctrybuf db 34 dup (0) . . . mov ah,38h ; function number mov al,0 ; get current country mov dx,seg ctrybuf ; address of buffer mov ds,dx ; for country information mov dx,offset ctrybuf int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . If the program is running under PC-DOS 3.3 and the current country code is 49 (West Germany), ctrybuf is filled in with the following information: dw 0001h ; date format db 'DM',0,0,0 ; ASCIIZ currency symbol db '.',0 ; ASCIIZ thousands separator db ',',0 ; ASCIIZ decimal separator db '.',0 ; ASCIIZ date separator db '.',0 ; ASCIIZ time separator db 02h ; currency format db 02h ; digits after decimal db 01h ; time format dd 026ah:176ch ; case-map call address db ';',0 ; ASCIIZ data-list separator db 10 dup (0) ; reserved ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 39H (57) Create directory ──────────────────────────────────────────────────────────────────────────── Creates a directory using the specified drive and path. Call with: AH = 39H DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Note: ■ The function fails if: ∙ any element of the pathname does not exist. ∙ a directory with the same name at the end of the same path already exists. ∙ the parent directory for the new directory is the root directory and is full. ∙ [3.0+] the program is running on a network and the user running the program has insufficient access rights. Example: Create a directory named MYSUB in the root directory on drive C. dname db 'C:\MYSUB',0 . . . mov ah,39h ; function number mov dx,seg dname ; address of pathname mov ds,dx mov dx,offset dname int 21h ; transfer to MS-DOS jc error ; jump if create failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 3AH (58) Delete directory ──────────────────────────────────────────────────────────────────────────── Removes a directory using the specified drive and path. Call with: AH = 3AH DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Note: ■ The function fails if: ∙ any element of the pathname does not exist. ∙ the specified directory is also the current directory. ∙ the specified directory contains any files. ∙ [3.0+] the program is running on a network and the user running the program has insufficient access rights. Example: Remove the directory named MYSUB in the root directory on drive C. dname db 'C:\MYSUB',0 . . . mov ah,3ah ; function number mov dx,seg dname ; address of pathname mov ds,dx mov dx,offset dname int 21h ; transfer to MS-DOS jc error ; jump if delete failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 3BH (59) Set current directory ──────────────────────────────────────────────────────────────────────────── Sets the current, or default, directory using the specified drive and path. Call with: AH = 3BH DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ The function fails if any element of the pathname does not exist. ■ Int 21H Function 47H can be used to obtain the name of the current directory before using Int 21H Function 3BH to select another, so that the original directory can be restored later. Example: Change the current directory for drive C to the directory \MYSUB. dname db 'C:\MYSUB',0 . . . mov ah,3bh ; function number mov dx,seg dname ; address of pathname mov ds,dx mov dx,offset dname int 21h ; transfer to MS-DOS jc error ; jump if bad path . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 3CH (60) Create file ──────────────────────────────────────────────────────────────────────────── Given an ASCIIZ pathname, creates a new file in the designated or default directory on the designated or default disk drive. If the specified file already exists, it is truncated to zero length. In either case, the file is opened and a handle is returned that can be used by the program for subsequent access to the file. Call with: AH = 3CH CX = file attribute (bits may be combined) Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3 volume label 4 reserved (0) 5 archive 6─15 reserved (0) DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear AX = handle If function failed Carry flag = set AX = error code Notes: ■ The function fails if: ∙ any element of the pathname does not exist. ∙ the file is being created in the root directory and the root directory is full. ∙ a file with the same name and the read-only attribute already exists in the specified directory. ∙ [3.0+] the program is running on a network and the user running the program has insufficient access rights. ■ A file is usually given a normal (0) attribute when it is created. The file's attribute can subsequently be modified with Int 21H Function 43H. ■ [3.0+] A volume label can be created using an attribute of 0008H, if one does not already exist. When files are created, bit 3 of the attribute parameter should always be clear (0). ■ [3.0+] See the entries for Int 21H Functions 5AH and 5BH, which may also be used to create files. ■ [4.0+] Int 21H Function 6CH combines the services of Functions 3CH, 3DH, and 5BH. Example: Create and open, or truncate to zero length and open, the file C:\MYDIR\MYFILE.DAT, and save the handle for subsequent access to the file. fname db 'C:\MYDIR\MYFILE.DAT',0 fhandle dw ? . . . mov ah,3ch ; function number xor cx,cx ; normal attribute mov dx,seg fname ; address of pathname mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if create failed mov fhandle,ax ; save file handle . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 3DH (61) Open file ──────────────────────────────────────────────────────────────────────────── Given an ASCIIZ pathname, opens the specified file in the designated or default directory on the designated or default disk drive. A handle is returned which can be used by the program for subsequent access to the file. Call with: AH = 3DH AL = access mode Bit(s) Significance 0─2 access mode 000 = read access 001 = write access 010 = read/write access 3 reserved (0) 4─6 sharing mode (MS-DOS versions 3.0 and later) 000 = compatibility mode 001 = deny all 010 = deny write 011 = deny read 100 = deny none 7 inheritance flag (MS-DOS versions 3.0 and later) 0 = child process inherits handle 1 = child does not inherit handle DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear AX = handle If function unsuccessful Carry flag = set AX = error code Notes: ■ Any normal, system, or hidden file with a matching name will be opened by this function. If the file is read-only, the success of the operation also depends on the access code in bits 0─2 of register AL. After opening the file, the file read/write pointer is set to offset zero (the first byte of the file). ■ The function fails if: ∙ any element of the pathname does not exist. ∙ the file is opened with an access mode of read/write and the file has the read-only attribute. ∙ [3.0+] SHARE.EXE is loaded and the file has already been opened by one or more other processes in a sharing mode that is incompatible with the current program's request. ■ The file's date and time stamp can be accessed after a successful open call with Int 21H Function 57H. ■ The file's attributes (hidden, system, read-only, or archive) can be obtained with Int 21H Function 43H. ■ When a file handle is inherited by a child process or is duplicated with Int 21H Function 45H or 46H, all sharing and access restrictions are also inherited. ■ [2] Only bits 0─2 of register AL are significant; the remaining bits should be zero for upward compatibility. ■ [3.0+] Bits 4─7 of register AL control access to the file by other programs. (Bits 4─6 have no effect unless SHARE.EXE is loaded.) ■ [3.0+] A file-sharing error causes a critical-error exception (Int 24H) with an error code of 02H. Int 21H Function 59H can be used to obtain information about the sharing violation. ■ [4.0+] Int 21H Function 6CH combines the services of Functions 3CH, 3DH, and 5BH. Example: Open the file C:\MYDIR\MYFILE.DAT for both reading and writing, and save the handle for subsequent access to the file. fname db 'C:\MYDIR\MYFILE.DAT',0 fhandle dw ? . . . mov ah,3dh ; function number mov al,2 ; mode = read/write mov dx,seg fname ; address of pathname mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if open failed mov fhandle,ax ; save file handle . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 3EH (62) Close file ──────────────────────────────────────────────────────────────────────────── Given a handle that was obtained by a previous successful open or create operation, flushes all internal buffers associated with the file to disk, closes the file, and releases the handle for reuse. If the file was modified, the time and date stamp and file size are updated in the file's directory entry. Call with: AH = 3EH BX = handle Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Note: ■ If you accidentally call this function with a zero handle, the standard input device is closed, and the keyboard appears to go dead. Make sure you always call the close function with a valid, nonzero handle. Example: Close the file whose handle is saved in the variable fhandle. fhandle dw 0 . . . mov ah,3eh ; function number mov bx,fhandle ; file handle int 21h ; transfer to MS-DOS jc error ; jump if close failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 3FH (63) Read file or device ──────────────────────────────────────────────────────────────────────────── Given a valid file handle from a previous open or create operation, a buffer address, and a length in bytes, transfers data at the current file-pointer position from the file into the buffer and then updates the file pointer position. Call with: AH = 3FH BX = handle CX = number of bytes to read DS:DX = segment:offset of buffer Returns: If function successful Carry flag = clear AX = bytes transferred If function unsuccessful Carry flag = set AX = error code Notes: ■ If reading from a character device (such as the standard input) in cooked mode, at most one line of input will be read (i.e., up to a carriage return character or the specified length, whichever comes first). ■ If the carry flag is returned clear but AX = 0, then the file pointer was already at end of file when the program requested the read. ■ If the carry flag is returned clear but AX < CX, then a partial record was read at end of file or there is an error. ■ [3.0+] If the program is running on a network, the user must have Read access rights to the directory and file. Example: Using the file handle from a previous open or create operation, read 1024 bytes at the current file pointer into the buffer named buff. buff db 1024 dup (?) ; buffer for read fhandle dw ? ; contains file handle . . . mov ah,3fh ; function number mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff mov bx,fhandle ; file handle mov cx,1024 ; length to read int 21h ; transfer to MS-DOS jc error ; jump, read failed cmp ax,cx ; check length of read jl done ; jump, end of file . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 40H (64) Write file or device ──────────────────────────────────────────────────────────────────────────── Given a valid file handle from a previous open or create operation, a buffer address, and a length in bytes, transfers data from the buffer into the file and then updates the file pointer position. Call with: AH = 40H BX = handle CX = number of bytes to write DS:DX = segment:offset of buffer Returns: If function successful Carry flag = clear AX = bytes transferred If function unsuccessful Carry flag = set AX = error code Notes: ■ If the carry flag is returned clear but AX < CX, then a partial record was written or there is an error. This can be caused by a Ctrl-Z (1AH) embedded in the data if the destination is a character device in cooked mode or by a disk full condition if the destination is a file. ■ If the function is called with CX = 0, the file is truncated or extended to the current file pointer position. ■ [3.0+] If the program is running on a network, the user must have Write access rights to the directory and file. Example: Using the handle from a previous open or create operation, write 1024 bytes to disk at the current file pointer from the buffer named buff. buff db 1024 dup (?) ; buffer for write fhandle dw ? ; contains file handle . . . mov ah,40h ; function number mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff mov bx,fhandle ; file handle mov cx,1024 ; length to write int 21h ; transfer to MS-DOS jc error ; jump, write failed cmp ax,1024 ; entire record written? jne error ; no, jump . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 41H (65) Delete file ──────────────────────────────────────────────────────────────────────────── Deletes a file from the specified or default disk and directory. Call with: AH = 41H DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ This function deletes a file by replacing the first character of its filename in the directory with the character e (E5H) and marking the file's clusters as "free" in the disk's file allocation table. The actual data stored in those clusters is not overwritten. ■ Only one file at a time may be deleted with this function. Unlike the FCB-related Delete File function (Int 21H Function 13H), the * and ? wildcard characters are not allowed in the file specification. ■ The function fails if: ∙ any element of the pathname does not exist. ∙ the designated file exists but has the read-only attribute. (Int 21H Function 43H can be used to examine and modify a file's attribute before attempting to delete it.) ∙ [3.0+] the program is running on a network, and the user running the program has insufficient access rights. Example: Delete the file named MYFILE.DAT from the directory \MYDIR on drive C. fname db 'C:\MYDIR\MYFILE.DAT',0 . . . mov ah,41h ; function number mov dx,seg fname ; filename address mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if delete failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 42H (66) Set file pointer ──────────────────────────────────────────────────────────────────────────── Sets the file location pointer relative to the start of file, end of file, or current file position. Call with: AH = 42H AL = method code 00H absolute offset from start of file 01H signed offset from current file pointer 02H signed offset from end of file BX = handle CX = most significant half of offset DX = least significant half of offset Returns: If function successful Carry flag = clear DX = most significant half of resulting file pointer AX = least significant half of resulting file pointer If function unsuccessful Carry flag = set AX = error code Notes: ■ This function uses a method code and a double-precision (32-bit) value to set the file pointer. The next record read or written in the file will begin at the new file pointer location. No matter what method is used in the call to this function, the file pointer returned in DX:AX is always the resulting absolute byte offset from the start of file. ■ Method 02H may be used to find the size of the file by calling Int 21H Function 42H with an offset of 0 and examining the pointer location that is returned. ■ Using methods 01H or 02H, it is possible to set the file pointer to a location that is before the start of file. If this is done, no error is returned by this function, but an error will be encountered upon a subsequent attempt to read or write the file. Examples: Using the file handle from a previous open or create operation, set the current file pointer position to 1024 bytes after the start of file. fhandle dw ? . . . mov ah,42h ; function number mov al,0 ; method = absolute mov bx,fhandle ; file handle mov cx,0 ; upper half of offset mov dx,1024 ; lower half of offset int 21h ; transfer to MS-DOS jc error ; jump, function failed . . . The following subroutine accepts a record number, record size, and handle and sets the file pointer appropriately. ; call this routine with BX = handle ; AX = record number ; CX = record size ; returns all registers unchanged ; setptr proc near push ax ; save record number push cx ; save record size push dx ; save whatever's in DX mul cx ; size * record number mov cx,ax ; upper part to CX xchg cx,dx ; lower part to DX mov ax,4200h ; function number & method int 21h ; transfer to MS-DOS pop dx ; restore previous DX pop cx ; restore record size pop ax ; restore record number ret ; back to caller setptr endp ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 43H (67) Get or set file attributes ──────────────────────────────────────────────────────────────────────────── Obtains or alters the attributes of a file (read-only, hidden, system, or archive) or directory. Call with: AH = 43H AL = 00H to get attributes 01H to set attributes CX = file attribute, if AL = 01H (bits can be combined) Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3─4 reserved (0) 5 archive 6─15 reserved (0) DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear CX = file attribute Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3 volume label 4 directory 5 archive 6─15 reserved (0) If function unsuccessful Carry flag = set AX = error code Notes: ■ Bits 3 and 4 of register CX must always be clear (0) when this function is called; in other words, you cannot change an existing file into a directory or volume label. However, you can assign the "hidden" attribute to an existing directory with this function. ■ [3.0+] If the program is running on a network, the user must have Create access rights to the directory containing the file whose attribute is to be modified. Example: Change the attribute of the file D:\MYDIR\MYFILE.DAT to read-only, so that it cannot be accidentally modified or deleted by other application programs. rdonly equ 01h ; file attributes hidden equ 02h system equ 04h volume equ 08h subdir equ 10h archive equ 20h fname db 'D:\MYDIR\MYFILE.DAT',0 . . . mov ah,43h ; function number mov al,01h ; subfunction = modify mov cx,rdonly ; read-only attribute mov dx,seg fname ; filename address mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if modify failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) IOCTL (I/O control) ──────────────────────────────────────────────────────────────────────────── Provides a direct path of communication between an application program and a device driver. Allows a program to obtain hardware-dependent information and to request operations that are not supported by other MS-DOS function calls. The IOCTL subfunctions and the MS-DOS versions in which they first became available are: ╓┌─┌──────────────┌──────────────────────────────────────────┌───────────────╖ Subfunction Name MS-DOS version ────────────────────────────────────────────────────────────────────────── 00H Get Device Information 2.0 01H Set Device Information 2.0 02H Receive Control Data from Character 2.0 Device Driver 03H Send Control Data to Character Device 2.0 Driver 04H Receive Control Data from Block Device 2.0 Driver 05H Send Control Data to Block Device Driver 2.0 06H Check Input Status 2.0 07H Check Output Status 2.0 08H Check If Block Device Is Removable 3.0 Subfunction Name MS-DOS version ────────────────────────────────────────────────────────────────────────── 08H Check If Block Device Is Removable 3.0 09H Check If Block Device Is Remote 3.1 0AH (10) Check If Handle Is Remote 3.1 0BH (11) Change Sharing Retry Count 3.1 0CH (12) Generic I/O Control for Character Devices CL = 45H: Set Iteration Count 3.2 CL = 4AH: Select Code Page 3.3 CL = 4CH: Start Code Page Preparation 3.3 CL = 4DH: End Code Page Preparation 3.3 CL = 5FH: Set Display Information 4.0 CL = 65H: Get Iteration Count 3.2 CL = 6AH: Query Selected Code Page 3.3 CL = 6BH: Query Prepare List 3.3 CL = 7FH: Get Display Information 4.0 0DH (13) Generic I/O Control for Block Devices CL = 40H: Set Device Parameters 3.2 CL = 41H: Write Track 3.2 CL = 42H: Format and Verify Track 3.2 CL = 47H: Set Access Flag 4.0 Subfunction Name MS-DOS version ────────────────────────────────────────────────────────────────────────── CL = 47H: Set Access Flag 4.0 CL = 60H: Get Device Parameters 3.2 CL = 61H: Read Track 3.2 CL = 62H: Verify Track 3.2 CL = 67H: Get Access Flag 4.0 0EH (14) Get Logical Drive Map 3.2 0FH (15) Set Logical Drive Map 3.2 ────────────────────────────────────────────────────────────────────────── Only IOCTL Subfunctions 00H, 06H, and 07H may be used for handles associated with files. Subfunctions 00H─08H are not supported on network devices. ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 00H IOCTL: get device information ──────────────────────────────────────────────────────────────────────────── Returns a device information word for the file or device associated with the specified handle. Call with: AH = 44H AL = 00H BX = handle Returns: If function successful Carry flag = clear DX = device information word For a file: Bit(s) Significance 0─5 drive number (0 = A, 1 = B, etc.) 6 0 if file has been written 1 if file has not been written 7 0, indicating a file 8─15 reserved For a device: Bit(s) Significance 0 1 if standard input 1 1 if standard output 2 1 if NUL device 3 1 if clock device 4 reserved 5 0 if handle in ASCII mode 1 if handle in binary mode 6 0 if end of file on input 7 1, indicating a device 8─13 reserved 14 0 if IOCTL subfunctions 02H and 03H not supported 1 if IOCTL subfunctions 02H and 03H supported 15 reserved If function unsuccessful Carry flag = set AX = error code Notes: ■ Bits 8─15 of DX correspond to the upper 8 bits of the device-driver attribute word. ■ Bit 5 of the device information word for a handle associated with a character device signifies whether MS-DOS considers that handle to be in binary ("raw") mode or ASCII ("cooked") mode. In ASCII mode, MS-DOS filters the character stream and may take special action when the characters Ctrl-C, Ctrl-S, Ctrl-P, Ctrl-Z, and carriage return are detected. In binary mode, all characters are treated as data, and the exact number of characters requested is always read or written. Example: See Int 21H Function 44H Subfunction 01H. ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 01H IOCTL: set device information ──────────────────────────────────────────────────────────────────────────── Sets certain flags for a handle associated with a character device. This subfunction may not be used for a handle that is associated with a file. Call with: AH = 44H AL = 01H BX = handle DX = device information word Bit(s) Significance 0 1 if standard input 1 1 if standard output 2 1 if NUL device 3 1 if clock device 4 reserved (0) 5 0 to select ASCII mode 1 to select binary mode 6 reserved (0) 7 1, indicating a device 8─15 reserved (0) Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ If register DH does not contain 00H, control returns to the program with the carry flag set and error code 0001H (invalid function) in register AX. ■ Bit 5 of the information word for a handle associated with a character device signifies whether MS-DOS considers that handle to be in binary ("raw") or ASCII ("cooked") mode. See Notes for Int 21H Function 44H Subfunction 00H. Example: Place the standard output handle into binary ("raw") mode. This speeds up output by disabling checking for Ctrl-C, Ctrl-S, and Ctrl-P between each character. . . . ; get device information mov ax,4400h ; function & subfunction mov bx,1 ; standard output handle int 21h ; transfer to MS-DOS mov dh,0 ; force DH = 0 or dl,20h ; set binary mode bit ; set device information mov ax,4401h ; function & subfunction int 21h ; transfer to MS-DOS . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 02H IOCTL: read control data from character device driver ──────────────────────────────────────────────────────────────────────────── Reads control data from a character-device driver. The length and contents of the data are specific to each device driver and do not follow any standard format. This function does not necessarily result in any input from the physical device. Call with: AH = 44H AL = 02H BX = handle CX = number of bytes to read DS:DX = segment:offset of buffer Returns: If function successful Carry flag = clear AX = bytes read and buffer contains control data from driver If function unsuccessful Carry flag = set AX = error code Notes: ■ If supported by the driver, this subfunction can be used to obtain hardware-dependent status and availability information that is not supported by other MS-DOS function calls. ■ Character-device drivers are not required to support IOCTL Subfunction 02H. A program can test bit 14 of the device information word returned by IOCTL Subfunction 00H to determine whether the driver supports this subfunction. If Subfunction 02H is requested and the driver does not have the ability to process control data, control returns to the program with the carry flag set and error code 0001H (invalid function) in register AX. Example: Read a control string from the standard list driver into the buffer buff. stdprn equ 4 ; standard list handle buflen equ 64 ; length of buffer ctllen dw ? ; length of control string buff db buflen dup (0) ; receives control string . . . mov ax,4402h ; function & subfunction mov bx,stdprn ; standard list handle mov cx,buflen ; buffer length mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS jc error ; jump if read failed mov ctllen,ax ; save control string length . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 03H IOCTL: write control data to character-device driver ──────────────────────────────────────────────────────────────────────────── Transfers control data from an application to a character-device driver. The length and contents of the data are specific to each device driver and do not follow any standard format. This function does not necessarily result in any output to the physical device. Call with: AH = 44H AL = 03H BX = handle CX = number of bytes to write DS:DX = segment:offset of data Returns: If function successful Carry flag = clear AX = bytes transferred If function unsuccessful Carry flag = set AX = error code Notes: ■ If supported by the driver, this subfunction can be used to request hardware-dependent operations (such as setting baud rate for a serial port) that are not supported by other MS-DOS function calls. ■ Character-device drivers are not required to support IOCTL Subfunction 03H. A program can test bit 14 of the device information word returned by IOCTL Subfunction 00H to determine whether the driver supports this subfunction. If Subfunction 03H is requested and the driver does not have the ability to process control data, control returns to the program with the carry flag set and error code 0001H (invalid function) in register AX. Example: Write a control string from the buffer buff to the standard list device driver. The length of the string is assumed to be in the variable ctllen. stdprn equ 4 ; standard list handle buflen equ 64 ; length of buffer ctllen dw ? ; length of control data buff db buflen dup (?) ; contains control data . . . mov ax,4403h ; function & subfunction mov bx,stdprn ; standard list handle mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff mov cx,ctllen ; length of control data int 21h ; transfer to MS-DOS jc error ; jump if write failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 04H IOCTL: read control data from block-device driver ──────────────────────────────────────────────────────────────────────────── Transfers control data from a block-device driver directly into an application program's buffer. The length and contents of the data are specific to each device driver and do not follow any standard format. This function does not necessarily result in any input from the physical device. Call with: AH = 44H AL = 04H BL = drive code (0 = default, 1 = A, 2 = B, etc.) CX = number of bytes to read DS:DX = segment:offset of buffer Returns: If function successful Carry flag = clear AX = bytes transferred and buffer contains control data from device driver If function unsuccessful Carry flag = set AX = error code Notes: ■ When supported by the driver, this subfunction can be used to obtain hardware-dependent status and availability information that is not provided by other MS-DOS function calls. ■ Block-device drivers are not required to support IOCTL Subfunction 04H. If this subfunction is requested and the driver does not have the ability to process control data, control returns to the program with the carry flag set and error code 0001H (invalid function) in register AX. Example: Read a control string from the block-device driver for drive C into the buffer buff. buflen equ 64 ; length of buffer ctllen dw ? ; length of control string buff db buflen dup (0) ; receives control string . . . mov ax,4404h ; function & subfunction mov bl,3 ; drive C = 3 mov cx,buflen ; buffer length mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff int 21h ; transfer to MS-DOS jc error ; jump if read failed mov ctllen,ax ; save control string length . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 05H IOCTL: write control data to block-device driver ──────────────────────────────────────────────────────────────────────────── Transfers control data from an application program directly to a block-device driver. The length and contents of the control data are specific to each device driver and do not follow any standard format. This function does not necessarily result in any output to the physical device. Call with: AH = 44H AL = 05H BL = drive code (0 = default, 1 = A, 2 = B, etc.) CX = number of bytes to write DS:DX = segment:offset of data Returns: If function successful Carry flag = clear AX = bytes transferred If function unsuccessful Carry flag = set AX = error code Notes: ■ When supported by the driver, this subfunction can be used to request hardware-dependent operations (such as tape rewind or disk eject) that are not provided by other MS-DOS function calls. ■ Block-device drivers are not required to support IOCTL Subfunction 05H. If this subfunction is requested and the driver does not have the ability to process control data, control returns to the program with the carry flag set and error code 0001H (invalid function) in register AX. Example: Write a control string from the buffer buff to the block-device driver for drive C. The length of the string is assumed to be in the variable ctllen. buflen equ 64 ; length of buffer ctllen dw ? ; length of control data buff db buflen dup (?) ; contains control data . . . mov ax,4405h ; function & subfunction mov bl,3 ; drive C = 3 mov dx,seg buff ; buffer address mov ds,dx mov dx,offset buff mov cx,ctllen ; length of control data int 21h ; transfer to MS-DOS jc error ; jump if write failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 06H IOCTL: check input status ──────────────────────────────────────────────────────────────────────────── Returns a code indicating whether the device or file associated with a handle is ready for input. Call with: AH = 44H AL = 06H BX = handle Returns: If function successful Carry flag = clear and, for a device: AL = 00H if device not ready FFH if device ready or, for a file: AL = 00H if file pointer at EOF FFH if file pointer not at EOF If function unsuccessful Carry flag = set AX = error code Note: ■ This function can be used to check the status of character devices, such as the serial port, that do not have their own "traditional" MS-DOS status calls. Example: Check whether a character is ready from the standard auxiliary device (usually COM1). stdaux equ 3 ; standard auxiliary handle . . . mov ax,4406h ; function & subfunction mov bx,stdaux ; standard auxiliary handle int 21h ; transfer to MS-DOS jc error ; jump if function failed or al,al ; test status flag jnz ready ; jump if character ready . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 44H (68) Subfunction 07H IOCTL: check output status ──────────────────────────────────────────────────────────────────────────── Returns a code indicating whether the device associated with a handle is ready for output. Call with: AH = 44H AL = 07H BX = handle Returns: If function successful Carry flag = clear and, for a device: AL = 00H if device not ready FFH if device ready or, for a file: AL = FFH If function unsuccessful Carry flag = set AX = error code Note: ■ When used with a handle for a file, this function always returns a ready status, even if the disk is full or no disk is in the drive. Example: Check whether the standard auxiliary device (usually COM1) can accept a character for output. stdaux equ 3 ; standard auxiliary handle . . . mov ax,4407h ; function & subfunction mov bx,stdaux ; standard auxiliary handle int 21h ; transfer to MS-DOS jc error ; jump if function failed or al,al ; test status flag jnz ready ; jump if not busy . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 44H (68) Subfunction 08H IOCTL: check if block device is removable ──────────────────────────────────────────────────────────────────────────── Checks whether the specified block device contains a removable storage medium, such as a floppy disk. Call with: AH = 44H AL = 08H BL = drive number (0 = default, 1 = A, 2 = B, etc.) Returns: If function successful Carry flag = clear AL = 00H if medium is removable 01H if medium is not removable If function unsuccessful Carry flag = set AX = error code Notes: ■ If a file is not found as expected on a particular drive, a program can use this subfunction to determine whether the user should be prompted to insert another disk. ■ This subfunction may not be used for a network drive. ■ Block drivers are not required to support Subfunction 08H. If this subfunction is requested and the block device cannot supply the information, control returns to the program with the carry flag set and error code 0001H (invalid function) in register AX. Example: Check whether drive C is removable. . . . mov ax,4408h ; function & subfunction mov bl,3 ; drive 3 = C int 21h ; transfer to MS-DOS jc error ; jump if function failed and al,1 ; test type of medium jnz fixed ; jump if not removable . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 44H (68) Subfunction 09H IOCTL: check if block device is remote ──────────────────────────────────────────────────────────────────────────── Checks whether the specified block device is local (attached to the computer running the program) or remote (redirected to a network server). Call with: AH = 44H AL = 09H BL = drive number (0 = default, 1 = A, 2 = B, etc.) Returns: If function successful Carry flag = clear DX = device attribute word bit 12 = 0 if drive is local 1 if drive is remote If function unsuccessful Carry flag = set AX = error code Note: ■ Use of this subfunction should be avoided. Application programs should not distinguish between files on local and remote devices. Example: Check whether drive D is mounted on the machine running the program or is a network drive. . . . mov ax,4409h ; function & subfunction mov bl,4 ; drive 4 = D int 21h ; transfer to MS-DOS jc error ; jump if function failed and dx,1000h ; test local/remote bit jnz remote ; jump if network drive . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 44H (68) Subfunction 0AH (10) IOCTL: check if handle is remote ──────────────────────────────────────────────────────────────────────────── Checks whether the specified handle refers to a file or device that is local (located on the PC that is running the program) or remote (located on a network server). Call with: AH = 44H AL = 0AH BX = handle Returns: If function successful Carry flag = clear DX = attribute word for file or device bit 15 = 0 if local 1 if remote If function unsuccessful Carry flag = set AX = error code Notes: ■ Application programs should not ordinarily attempt to distinguish between files on local and remote devices. ■ If the network has not been started, control returns to the calling program with the carry flag set and error code 0001H (invalid function) in register AX. Example: Check if the handle saved in the variable fhandle is associated with a file or device on the machine running the program or on a network server. fhandle dw ? ; device handle . . . mov ax,440ah ; function & subfunction mov bx,fhandle ; file/device handle int 21h ; transfer to MS-DOS jc error ; jump if function failed and dx,8000h ; test local/remote bit jnz remote ; jump if network handle . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 44H (68) Subfunction 0BH (11) IOCTL: change sharing retry count ──────────────────────────────────────────────────────────────────────────── Sets the number of times MS-DOS retries a disk operation after a failure caused by a file-sharing violation before it returns an error to the requesting process. This subfunction is not available unless the file-sharing module (SHARE.EXE) is loaded. Call with: AH = 44H AL = 0BH CX = delays per retry (default = 1) DX = number of retries (default = 3) Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ The length of a delay is a machine-dependent value determined by the CPU type and clock speed. Each delay consists of the following instruction sequence: xor cx,cx loop $ which executes 65,536 times before falling out of the loop. ■ The sharing retry count affects the behavior of the system as a whole and is not a local parameter for the process. If a program changes the sharing retry count, it should restore the default values before terminating. Example: Change the number of automatic retries for a file-sharing violation to five. . . . mov ax,440bh ; function & subfunction mov cx,1 ; delays per retry mov dx,5 ; number of retries int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.2] Function 44H (68) Subfunction 0CH (12) IOCTL: generic I/O control for character devices ──────────────────────────────────────────────────────────────────────────── Provides a general-purpose mechanism for communication between application programs and character-device drivers. Call with: AH = 44H AL = 0CH BX = handle CH = category (major) code: 00H = unknown 01H = COM1, COM2, COM3, or COM4 (3.3) 03H = CON (keyboard and display) (3.3) 05H = LPT1, LPT2, or LPT3 (3.2) CL = function (minor) code: 45H = Set Iteration Count (3.2) 4AH = Select Code Page (3.3) 4CH = Start Code Page Preparation (3.3) 4DH = End Code Page Preparation (3.3) 5FH = Set Display Information (4.0) 65H = Get Iteration Count (3.2) 6AH = Query Selected Code Page (3.3) 6BH = Query Prepare List (3.3) 7FH = Get Display Information (4.0) DS:DX = segment:offset of parameter block Returns: If function successful Carry flag = clear and, if called with CL = 65H, 6AH, 6BH, or 7FH DS:DX = segment:offset of parameter block If function unsuccessful Carry flag = set AX = error code Notes: ■ If the minor code is 45H (Set Iteration Count) or 65H (Get Iteration Count), the parameter block is simply a 2-byte buffer containing or receiving the iteration count for the printer. This call is valid only for printer drivers that support Output Until Busy, and determines the number of times the device driver will wait for the device to signal ready before returning from the output call. ■ The parameter block for minor code 4DH (End Code Page Preparation) has the following format: dw 2 ; length of following data dw 0 ; (reserved) ■ For MS-DOS version 3.3, the parameter block for minor codes 4AH (Select Code Page) and 6AH (Query Code Page) has the following format: dw 2 ; length of following data dw ? ; code page ID For MS-DOS version 4.0, minor codes 4AH and 6AH also set or get the double-byte character set (DBCS) lead byte table, and the following format is used: dw (n+2)*2+1 ; length of following data dw ? ; code page ID db start,end ; DBCS lead byte range 1 . . . db start,end ; DBCS lead byte range n db 0,0 ■ The parameter block for minor code 4CH (Start Code Page Preparation) has the following format: dw 0 ; font type ; bit 0 = 0 downloaded ; = 1 cartridge ; bits 1-15 = reserved (0) dw (n+1)*2 ; length of remainder of ; parameter block dw n ; number of code pages in ; the following list dw ? ; code page 1 dw ? ; code page 2 . . . dw ? ; code page n ■ The parameter block for minor code 6BH (Query Prepare List) has the following format, assuming n hardware code pages and m prepared code pages (n <= 12, m <= 12): dw (n+m+2)*2 ; length of following data dw n ; number of hardware code pages dw ? ; hardware code page 1 dw ? ; hardware code page 2 . . . dw ? ; hardware code page n dw m ; number of prepared code pages dw ? ; prepared code page 1 dw ? ; prepared code page 2 . . . dw ? ; prepared code page m ■ After a minor code 4CH (Start Code Page Preparation) call, the data defining the code page font is written to the driver using one or more calls to the IOCTL Write Control Data subfunction (Interrupt 21H, Function 44H, Subfunction 03H). The format of the data is device- and driver-specific. After the font data has been written to the driver, a minor code 4DH (End Code Page Preparation) call must be issued. If no data is written to the driver between the minor code 4CH and 4DH calls, the driver interprets the newly prepared code pages as hardware code pages. ■ A special variation of the minor code 4CH (Start Code Page Preparation) call, called "Refresh," is required to actually load the peripheral device with the prepared code pages. The refresh operation is obtained by requesting minor code 4CH with each code page position in the parameter block set to -1, followed by an immediate call for minor code 4DH (End Code Page Preparation). ■ [4.0+] For minor codes 5FH (Set Display Information) and 7FH (Get Display Information), the parameter block is formatted as follows: db 0 ; level (0 in MS-DOS 4.0) db 0 ; reserved (must be 0) dw 14 ; length of following data dw ? ; control flags ; bit 0 = 0 intensity ; = 1 blink ; bits 1-15 = reserved (0) db ? ; mode type (1 = text, 2 = APA) db 0 ; reserved (must be 0) dw ? ; colors ; 0 = monochrome compatible ; 1 = 2 colors ; 2 = 4 colors ; 4 = 16 colors ; 8 = 256 colors dw ? ; pixel columns dw ? ; pixel rows dw ? ; character columns dw ? ; character rows Example: Get the current code page for the standard list device. stdprn equ 4 ; standard list handle pars dw 2 ; length of data dw ? ; receives code page . . . mov ax,440ch ; function & subfunction mov bx,stdprn ; standard list handle mov ch,5 ; LPTx category mov cl,6ah ; query code page mov dx,seg pars ; parameter block address mov ds,dx mov dx,offset pars int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.2] Function 44H Subfunction 0DH (13) IOCTL: generic I/O control for block devices ──────────────────────────────────────────────────────────────────────────── Provides a general-purpose mechanism for communication between application programs and block-device drivers. Allows a program to inspect or change device parameters for a logical drive and to read, write, format, and verify disk tracks in a hardware-independent manner. Call with: AH = 44H AL = 0DH BL = drive code (0 = default, 1 = A, 2 = B, etc.) CH = category (major) code: 08H = disk drive CL = function (minor) code: 40H = Set Device Parameters 41H = Write Track 42H = Format and Verify Track 47H = Set Access Flag (4.0) 60H = Get Device Parameters 61H = Read Track 62H = Verify Track 67H = Get Access Flag (4.0) DS:DX = segment:offset of parameter block Returns: If function successful Carry flag = clear and, if called with CL = 60H or 61H DS:DX = segment:offset of parameter block If function unsuccessful Carry flag = set AX = error code Notes: ■ The minor code 40H (Set Device Parameters) function must be used before an attempt to write, read, format, or verify a track on a logical drive. In general, the following sequence applies to any of these operations: ∙ Get the current parameters (minor code 60H). Examine and save them. ∙ Set the new parameters (minor code 40H). ∙ Perform the task. ∙ Retrieve the original parameters and restore them with minor code 40H. ■ For minor codes 40H (Set Device Parameters) and 60H (Get Device Parameters), the parameter block is formatted as follows: Special-functions field: offset 00H, length = 1 byte Bit(s) Value Meaning 0 0 device BPB field contains a new default BPB 1 use current BPB 1 0 use all fields in parameter block 1 use track layout field only 2 0 sectors in track may be different sizes (should always be avoided) 1 sectors in track are all same size; sector numbers range from 1 to the total number of sectors in the track (should always be used) 3─7 0 reserved Device type field: offset 01H, length 1 byte Value Meaning 0 320/360 KB, 5.25-inch disk 1 1.2 MB, 5.25-inch disk 2 720 KB, 3.5-inch disk 3 single-density, 8-inch disk 4 double-density, 8-inch disk 5 fixed disk 6 tape drive 7 other type of block device Device attributes field: offset 02H, length 1 word Bit(s) Value Meaning 0 0 removable storage medium 1 nonremovable storage medium 1 0 door lock not supported 1 door lock supported 2─15 0 reserved Number of cylinders field: offset 04H, length 1 word Maximum number of cylinders supported on the block device Media type field: offset 06H, length 1 byte Value Meaning 0 1.2 MB, 5.25-inch disk 1 320/360 KB, 5.25-inch disk Device BPB field: offset 07H, length 31 bytes For format of the device BPB, see separate Note below. If bit 0 = 0 in special-functions field, this field contains the new default BPB for the device. If bit 0 = 1 in special-functions field, the BPB in this field is returned by the device driver in response to subsequent Build BPB requests. Track layout field: offset 26H, variable-length table Length Meaning Word number of sectors in track Word number of first sector in track Word size of first sector in track . . . Word number of last sector in track Word size of last sector in track ■ The device BPB field is a 31-byte data structure that describes the current disk and its control areas. The field is formatted as follows: Byte(s) Meaning 00H─01H bytes per sector 02H sectors per cluster (allocation unit) 03─04H reserved sectors, beginning at sector 0 05H number of file allocation tables (FATs) 06H─07H maximum number of root-directory entries 08H─09H number of sectors 0AH media descriptor 0BH─0CH sectors per FAT 0DH─0EH sectors per track 0FH─10H number of heads 11H─14H number of hidden sectors 15H─18H large number of sectors (if bytes 08H─09H=0) 19H─1EH reserved ■ When minor code 40H (Set Device Parameters) is used, the number of cylinders should not be altered, or some or all of the volume may become inaccessible. ■ For minor codes 41H (Write Track) and 61H (Read Track), the parameter block is formatted as follows: Byte(s) Meaning 00H special-functions field (must be 0) 01H─02H head 03H─04H cylinder 05H─06H starting sector 07H─08H sectors to transfer 09H─0CH transfer buffer address ■ For minor codes 42H (Format and Verify Track) and 62H (Verify Track), the parameter block is formatted as follows: Byte(s) Meaning 00H special-functions field Bit(s) Significance 0 0 = Format/Verify track 1 = Format status call (MS-DOS 4.0 only) 1─7 reserved (0) 01H─02H head 03H─04H cylinder In MS-DOS 4.0, this function may be called with bit 0 of the special-functions field set after a minor code 40H call (Set Device Parameters) to determine whether the driver supports the specified number of tracks and sectors per track. A status is returned in the special-functions field which is interpreted as follows: Value Meaning 0 specified number of tracks and sectors per track supported 1 this function not supported by the ROM BIOS 2 specified number of tracks and sectors per track not supported 3 no disk in drive ■ For minor codes 47H (Set Access Flag) and 67H (Get Access Flag), the parameter block is formatted as follows: Byte Meaning 00H special-functions field (must be 0) 01H disk access flag When the disk access flag is zero, access to the medium is blocked by the driver. The flag is set to zero when the driver detects an unformatted medium or a medium with an invalid boot record. When the access flag is nonzero, read/write operations to the medium are allowed by the driver. A formatting program must clear the disk access flag with minor code 47H before it requests minor code 42H (Format and Verify Track). Example: Get the device parameter block for disk drive C. dbpb db 128 dup (0) ; device parameter block . . . mov ax,440dh ; function & subfunction mov bl,3 ; drive C = 3 mov ch,8 ; disk category mov cl,60h ; get device parameters mov dx,seg dbpb ; buffer address mov ds,dx mov dx,offset dbpb int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.2] Function 44H (68) Subfunction 0EH (14) IOCTL: get logical drive map ──────────────────────────────────────────────────────────────────────────── Returns the logical drive code that was most recently used to access the specified block device. Call with: AH = 44H AL = 0EH BL = drive code (0 = default, 1 = A, 2 = B, etc.) Returns: If function successful Carry flag = clear AL = mapping code 00H if only one logical drive code assigned to the block device 01H─1AH logical drive code (1 = A, 2 = B, etc.) mapped to the block device If function unsuccessful Carry flag = set AX = error code Note: ■ If a drive has not been assigned a logical mapping with Function 44H Subfunction 0FH, the logical and physical drive codes are the same. Example: Check whether drive A has more than one logical drive code. . . . mov ax,440eh ; function & subfunction mov bl,1 ; drive 1 = A int 21h ; transfer to MS-DOS jc error ; jump if function failed or al,al ; test drive code jz label1 ; jump, no drive aliases . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.2] Function 44H (68) Subfunction 0FH (15) IOCTL: set logical drive map ──────────────────────────────────────────────────────────────────────────── Sets the next logical drive code that will be used to reference a block device. Call with: AH = 44H AL = 0FH BL = drive code (0 = default, 1 = A, 2 = B, etc.) Returns: If function successful Carry flag = clear AL = mapping code 00H if only one logical drive code assigned to the block device 01H─1AH logical drive code (1 = A, 2 = B, etc.) mapped to the block device If function unsuccessful Carry flag = set AX = error code Note: ■ When a physical block device is aliased to more than one logical drive code, this function can be used to inform the driver which drive code will next be used to access the device. Example: Notify the floppy-disk driver that the next access will be for logical drive B. . . . mov ax,440fh ; function & subfunction mov bl,2 ; drive 2 = B int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 45H (69) Duplicate handle ──────────────────────────────────────────────────────────────────────────── Given a handle for a currently open device or file, returns a new handle that refers to the same device or file at the same position. Call with: AH = 45H BX = handle to be duplicated Returns: If function successful Carry flag = clear AX = new handle If function unsuccessful Carry flag = set AX = error code Notes: ■ A seek, read, or write operation that moves the file pointer for one of the two handles also moves the file pointer associated with the other. ■ This function can be used to efficiently update the directory for a file that has changed in length, without incurring the overhead of closing and then reopening the file. The handle for the file is simply duplicated with this function and the duplicate is closed, leaving the original handle open for further read/write operations. ■ [3.3] See also Int 21H Function 68H (Commit File). Example: Duplicate the handle stored in the variable fhandle, then close the duplicate. This ensures that all buffered data is physically written to disk and that the directory entry for the corresponding file is updated, but leaves the original handle open for subsequent file operations. fhandle dw 0 ; file handle . . . ; get duplicate handle mov ah,45h ; function number mov bx,fhandle ; original file handle int 21h ; transfer to MS-DOS jc error ; jump if dup failed ; now close dup'd handle mov bx,ax ; put handle into BX mov ah,3eh ; function number int 21h ; transfer to MS-DOS jc error ; jump if close failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 46H (70) Redirect handle ──────────────────────────────────────────────────────────────────────────── Given two handles, makes the second handle refer to the same device or file at the same location as the first handle. The second handle is then said to be redirected. Call with: AH = 46H BX = handle for file or device CX = handle to be redirected Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ If the handle passed in CX already refers to an open file, that file is closed first. ■ A seek, read, or write operation that moves the file pointer for one of the two handles also moves the file pointer associated with the other. ■ This function is commonly used to redirect the standard input and output handles to another file or device before a child process is executed with Int 21H Function 4BH. Example: Redirect the standard output to the list device, so that all output directed to the console will appear on the printer instead. Later, restore the original meaning of the standard output handle. stdin equ 0 stdout equ 1 stderr equ 2 stdaux equ 3 stdprn equ 4 dhandle dw 0 ; duplicate handle . . . ; get dup of stdout mov ah,45h ; function number mov bx,stdout ; standard output handle int 21h ; transfer to MS-DOS jc error ; jump if dup failed mov dhandle,ax ; save dup'd handle ; ; redirect standard output ; to standard list device mov ah,46h ; function number mov bx,stdprn ; standard list handle mov cx,stdout ; standard output handle int 21h ; transfer to MS-DOS jc error ; jump if redirect failed . . . ; restore standard output ; to original meaning mov ah,46h ; function number mov bx,dhandle ; saved duplicate handle mov cx,stdout ; standard output handle int 21h ; transfer to MS-DOS jc error ; jump if redirect failed ; close duplicate handle ; because no longer needed mov ah,3eh ; function number mov bx,dhandle ; saved duplicate handle int 21h ; transfer to MS-DOS jc error ; jump if close failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 47H (71) Get current directory ──────────────────────────────────────────────────────────────────────────── Obtains an ASCIIZ string that describes the path from the root to the current directory, and the name of that directory. Call with: AH = 47H DL = drive code (0 = default, 1 = A, etc.) DS:SI = segment:offset of 64-byte buffer Returns: If function successful Carry flag = clear and buffer is filled in with full pathname from root of current directory. If function unsuccessful Carry flag = set AX = error code Notes: ■ The returned path name does not include the drive identifier or a leading backslash (\). It is terminated with a null (00H) byte. Consequently, if the current directory is the root directory, the first byte in the buffer will contain 00H. ■ The function fails if the drive code is invalid. ■ The current directory may be set with Int 21H Function 3BH. Example: Get the name of the current directory for drive C into the buffer named dbuff. dbuff db 64 dup (0) ; receives path string . . . mov ah,47h ; function number mov dl,03 ; drive C = 3 mov si,seg dbuff ; buffer address mov ds,si mov si,offset dbuff int 21h ; transfer to MS-DOS jc error ; jump if error . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 48H (72) Allocate memory block ──────────────────────────────────────────────────────────────────────────── Allocates a block of memory and returns a pointer to the beginning of the allocated area. Call with: AH = 48H BX = number of paragraphs of memory needed Returns: If function successful Carry flag = clear AX = base segment address of allocated block If function unsuccessful Carry flag = set AX = error code BX = size of largest available block (paragraphs) Notes: ■ If the function succeeds, the base address of the newly allocated block is AX:0000. ■ The default allocation strategy used by MS-DOS is "first fit"; that is, the memory block at the lowest address that is large enough to satisfy the request is allocated. The allocation strategy can be altered with Int 21H Function 58H. ■ When a .COM program is loaded, it ordinarily already "owns" all of the memory in the transient program area, leaving none for dynamic allocation. The amount of memory initially allocated to a .EXE program at load time depends on the MINALLOC and MAXALLOC fields in the .EXE file header. See Int 21H Function 4AH. Example: Request a 64 KB block of memory for use as a buffer. bufseg dw ? ; segment base of new block . . . mov ah,48h ; function number mov bx,1000h ; block size (paragraphs) int 21h ; transfer to MS-DOS jc error ; jump if allocation failed mov bufseg,ax ; save segment of new block . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 49H (73) Release memory block ──────────────────────────────────────────────────────────────────────────── Releases a memory block and makes it available for use by other programs. Call with: AH = 49H ES = segment of block to be released Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ This function assumes that the memory block being released was previously obtained by a successful call to Int 21H Function 48H. ■ The function will fail or can cause unpredictable system errors if: ∙ the program releases a memory block that does not belong to it. ∙ the segment address passed in register ES is not a valid base address for an existing memory block. Example: Release the memory block that was previously allocated in the example for Int 21H Function 48H (page 438). bufseg dw ? ; segment base of block . . . mov ah,49h ; function number mov es,bufseg ; base segment of block int 21h ; transfer to MS-DOS jc error ; jump if release failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 4AH (74) Resize memory block ──────────────────────────────────────────────────────────────────────────── Dynamically shrinks or extends a memory block, according to the needs of an application program. Call with: AH = 4AH BX = desired new block size in paragraphs ES = segment of block to be modified Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code BX = maximum block size available (paragraphs) Notes: ■ This function modifies the size of a memory block that was previously allocated with a call to Int 21H Function 48H. ■ If the program is requesting an increase in the size of an allocated block, and this function fails, the maximum possible size for the specified block is returned in register BX. The program can use this value to determine whether it should terminate, or continue in a degraded fashion with less memory. ■ A program that uses EXEC (Int 21H Function 4BH) to load and execute a child program must call this function first to make memory available for the child, passing the address of its PSP in register ES and the amount of memory needed for its own code, data, and stacks in register BX. Example: Resize the memory block that was allocated in the example for Int 21H Function 48H (page 438), shrinking it to 32 KB. bufseg dw ? ; segment base of block . . . mov ah,4ah ; function number mov bx,0800h ; new size (paragraphs) mov es,bufseg ; segment base of block int 21h ; transfer to MS-DOS jc error ; jump, resize failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 4BH (75) Execute program (EXEC) ──────────────────────────────────────────────────────────────────────────── Allows an application program to run another program, regaining control when it is finished. Can also be used to load overlays, although this use is uncommon. Call with: AH = 4BH AL = subfunction 00H = Load and Execute Program 03H = Load Overlay ES:BX = segment:offset of parameter block DS:DX = segment:offset of ASCIIZ program pathname Returns: If function successful Carry flag = clear [2] all registers except for CS:IP may be destroyed [3.0+] registers are preserved in the usual fashion If function unsuccessful Carry flag = set AX = error code Notes: ■ The parameter block format for Subfunction 00H (Load and Execute Program) is as follows: Bytes Contents 00H─01H segment pointer to environment block 02H─03H offset of command line tail 04H─05H segment of command line tail 06H─07H offset of first FCB to be copied into new PSP + 5CH 08H─09H segment of first FCB 0AH─0BH offset of second FCB to be copied into new PSP + 6CH 0CH─0DH segment of second FCB ■ The parameter block format for Subfunction 03H (Load Overlay) is as follows: Bytes Contents 00H─01H segment address where overlay is to be loaded 02H─03H relocation factor to apply to loaded image ■ The environment block must be paragraph-aligned. It consists of a sequence of ASCIIZ strings in the form: db 'COMSPEC=A:\COMMAND.COM',0 The entire set of strings is terminated by an extra null (00H) byte. ■ The command tail format consists of a count byte, followed by an ASCII string, terminated by a carriage return (which is not included in the count). The first character in the string should be an ASCII space (20H) for compatibility with the command tail passed to programs by COMMAND.COM. For example: db 6,' *.DAT',0dh ■ Before a program uses Int 21H Function 4BH to run another program, it must release all memory it is not actually using with a call to Int 21H Function 4AH, passing the segment address of its own PSP and the number of paragraphs to retain. ■ Ordinarily, all active handles of the parent program are inherited by the child program, although the parent can prevent this in MS-DOS 3.0 and later by setting the inheritance bit when the file or device is opened. Any redirection of the standard input and/or output in the parent process also affects the child process. ■ The environment block can be used to pass information to the child process. If the environment block pointer in the parameter block is zero, the child program inherits an exact copy of the parent's environment. In any case, the segment address of the child's environment is found at offset 002CH in the child's PSP. ■ After return from the EXEC function call, the termination type and return code of the child program may be obtained with Int 21H Function 4DH. Example: See Chapter 12. ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 4CH (76) Terminate process with return code ──────────────────────────────────────────────────────────────────────────── Terminates the current process, passing a return code to the parent process. This is one of several methods that a program can use to perform a final exit. MS-DOS then takes the following actions: ■ All memory belonging to the process is released. ■ File buffers are flushed and any open handles for files or devices owned by the process are closed. ■ The termination handler vector (Int 22H) is restored from PSP:000AH. ■ The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. ■ [2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. ■ Control is transferred to the termination handler. If the program is returning to COMMAND.COM, control transfers to the resident portion and the transient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and interpreted; otherwise, a prompt is issued for the next user command. Call with: AH = 4CH AL = return code Returns: Nothing Notes: ■ [2.0+] This is the preferred method of termination for application programs because it allows a return code to be passed to the parent program and does not rely on the contents of any segment register. Other methods of performing a final exit are: ∙ Int 20H ∙ Int 21H Function 00H ∙ Int 21H Function 31H ∙ Int 27H ■ Any files that have been opened using FCBs and modified by the program should be closed before program termination; otherwise, data may be lost. ■ The return code can be retrieved by the parent process with Int 21H Function 4DH (Get Return Code). It can also be tested in a batch file with an IF ERRORLEVEL statement. By convention, a return code of zero indicates successful execution, and a non-zero return code indicates an error. ■ [3.0+] If the program is running on a network, it should remove all locks it has placed on file regions before terminating. Example: Terminate the current process, passing a return code of 1 to the parent process. . . . mov ah,4ch ; function number mov al,01h ; return code int 21h ; transfer to MS-DOS ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 4DH (77) Get return code ──────────────────────────────────────────────────────────────────────────── Used by a parent process, after the successful execution of an EXEC call (Int 21H Function 4BH), to obtain the return code and termination type of a child process. Call with: AH = 4DH Returns: AH = exit type 00H if normal termination by Int 20H, Int 21H Function 00H, or Int 21H Function 4CH 01H if termination by user's entry of CtrlDC 02H if termination by critical-error handler 03H if termination by Int 21H Function 31H or Int 27H AL = return code passed by child process (0 if child terminated by Int 20H, Int 21H Function 00H, or Int 27H) Notes: ■ This function will yield the return code of a child process only once. A subsequent call without an intervening EXEC (Int 21H Function 4BH) will not necessarily return any valid information. ■ This function does not set the carry flag to indicate an error. If no previous child process has been executed, the values returned in AL and AH are undefined. Example: Get the return code and termination kind of child process that was previously executed with Int 21H Function 4BH (EXEC). retcode dw ? ; return code, termination type . . . mov ah,4dh ; function number int 21h ; transfer to MS-DOS mov retcode,ax ; save child process info . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 4EH (78) Find first file ──────────────────────────────────────────────────────────────────────────── Given a file specification in the form of an ASCIIZ string, searches the default or specified directory on the default or specified drive for the first matching file. Call with: AH = 4EH CX = search attribute (bits may be combined) Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3 volume label 4 directory 5 archive 6─15 reserved (0) DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful (matching file found) Carry flag = clear and search results returned in current disk transfer area as follows: Byte(s) Description 00H─14H reserved (0) 15H attribute of matched file or directory 16H─17H file time bits 00H─04H = 2-second increments (0─29) bits 05H─0AH = minutes (0─59) bits 0BH─0FH = hours (0─23) 18H─19H file date bits 00H─04H = day (1─31) bits 05H─08H = month (1─12) bits 09H─0FH = year (relative to 1980) 1AH─1DH file size 1EH─2AH ASCIIZ filename and extension If function unsuccessful (no matching files) Carry flag = set AX = error code Notes: ■ This function assumes that the DTA has been previously set by the program with Int 21H Function 1AH to point to a buffer of adequate size. ■ The * and ? wildcard characters are allowed in the filename. If wildcard characters are present, this function returns only the first matching filename. ■ If the attribute is 0, only ordinary files are found. If the volume label attribute bit is set, only volume labels will be returned (if any are present). Any other attribute or combination of attributes (hidden, system, and directory) results in those files and all normal files being matched. Example: Find the first .COM file in the directory \MYDIR on drive C. fname db 'C:\MYDIR\*.COM',0 dbuff db 43 dup (0) ; receives search results . . . ; set DTA address mov ah,1ah ; function number mov dx,seg dbuff ; result buffer address mov ds,dx mov dx,offset dbuff int 21h ; transfer to MS-DOS ; search for first match mov ah,4eh ; function number mov cx,0 ; normal attribute mov dx,seg fname ; address of filename mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if no match . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 4FH (79) Find next file ──────────────────────────────────────────────────────────────────────────── Assuming a previous successful call to Int 21H Function 4EH, finds the next file in the default or specified directory on the default or specified drive that matches the original file specification. Call with: AH = 4FH Assumes DTA points to working buffer used by previous successful Int 21H Function 4EH or 4FH. Returns: If function successful (matching file found) Carry flag = clear and search results returned in current disk transfer area as described for Int 21H Function 4EH If function unsuccessful (no more matching files) Carry flag = set AX = error code Notes: ■ Use of this call assumes that the original file specification passed to Int 21H Function 4EH contained one or more * or ? wildcard characters. ■ When this function is called, the current disk transfer area (DTA) must contain information from a previous successful call to Int 21H Function 4EH or 4FH. Example: Continuing the search operation in the example for Int 21H Function 4EH, find the next .COM file (if any) in the directory \MYDIR on drive C. fname db 'C:\MYDIR\*.COM',0 dbuff db 43 dup (0) ; receives search results . . . ; search for next match mov ah,4fh ; function number int 21h ; transfer to MS-DOS jc error ; jump if no more files . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 50H (80) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 51H (81) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 52H (82) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 53H (83) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 54H (84) Get verify flag ──────────────────────────────────────────────────────────────────────────── Obtains the current value of the system verify (read-after-write) flag. Call with: AH = 54H Returns: AL = current verify flag value 00H if verify off 01H if verify on Notes: ■ Because read-after-write verification slows disk operations, the default state of the system verify flag is OFF. ■ The state of the system verify flag can be changed through a call to Int 21H Function 2EH or by the MS-DOS commands VERIFY ON and VERIFY OFF. Example: Obtain the state of the system verify flag. . . . mov ah,54h ; function number int 21h ; transfer to MS-DOS cmp al,01h ; check verify state je label1 ; jump if verify on ; else assume verify off . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 55H (85) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 56H (86) Rename file ──────────────────────────────────────────────────────────────────────────── Renames a file and/or moves its directory entry to a different directory on the same disk. In MS-DOS version 3.0 and later, this function can also be used to rename directories. Call with: AH = 56H DS:DX = segment:offset of current ASCIIZ pathname ES:DI = segment:offset of new ASCIIZ pathname Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ The function fails if: ∙ any element of the pathname does not exist. ∙ a file with the new pathname already exists. ∙ the current pathname specification contains a different disk drive than does the new pathname. ∙ the file is being moved to the root directory, and the root directory is full. ∙ [3.0+] the program is running on a network and the user has insufficient access rights to either the existing file or the new directory. ■ The * and ? wildcard characters are not allowed in either the current or new pathname specifications. Example: Change the name of the file MYFILE.DAT in the directory \MYDIR on drive C to MYTEXT.DAT. At the same time, move the file to the directory \SYSTEM on the same drive. oldname db 'C:\MYDIR\MYFILE.DAT',0 newname db 'C:\SYSTEM\MYTEXT.DAT',0 . . . mov ah,56h ; function number mov dx,seg oldname ; old filename address mov ds,dx mov dx,offset oldname mov di,seg newname ; new filename address mov es,di mov di,offset newname int 21h ; transfer to MS-DOS jc error ; jump if rename failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.0] Function 57H (87) Get or set file date and time ──────────────────────────────────────────────────────────────────────────── Obtains or modifies the date and time stamp in a file's directory entry. Call with: If getting date and time AH = 57H AL = 00H BX = handle If setting date and time AH = 57H AL = 01H BX = handle CX = time bits 00H─04H = 2-second increments (0─29) bits 05H─0AH = minutes (0─59) bits 0BH─0FH = hours (0─23) DX = date bits 00H─04H = day (1─31) bits 05H─08H = month (1─12) bits 09H─0FH = year (relative to 1980) Returns: If function successful Carry flag = clear and, if called with AL = 00H CX = time DX = date If function unsuccessful Carry flag = set AX = error code Notes: ■ The file must have been previously opened or created via a successful call to Int 21H Function 3CH, 3DH, 5AH, 5BH, or 6CH. ■ If the 16-bit date for a file is set to zero, that file's date and time are not displayed on directory listings. ■ A date and time set with this function will prevail, even if the file is modified afterwards before the handle is closed. Example: Get the date that the file MYFILE.DAT was created or last modified, and then decompose the packed date into its constituent parts in the variables month, day, and year. fname db 'MYFILE.DAT',0 month dw 0 day dw 0 year dw 0 . . . ; first open the file mov ah,3dh ; function number mov al,0 ; read-only mode mov dx,seg fname ; filename address mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if open failed ; get file date/time mov bx,ax ; copy handle to BX mov ah,57h ; function number mov al,0 ; 0 = get subfunction int 21h ; transfer to MS-DOS jc error ; jump if function failed mov day,dx ; decompose date and day,01fh ; isolate day mov cl,5 shr dx,cl mov month,dx ; isolate month and month,0fh mov cl,4 shr dx,cl ; isolate year and dx,03fh ; relative to 1980 add dx,1980 ; correct to real year mov year,dx ; save year ; now close file, ; handle still in BX mov ah,3eh ; function number int 21h ; transfer to MS-DOS jc error ; jump if close failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 58H (88) Get or set allocation strategy ──────────────────────────────────────────────────────────────────────────── Obtains or changes the code indicating the current MS-DOS strategy for allocating memory blocks. Call with: If getting strategy code AH = 58H AL = 00H If setting strategy code AH = 58H AL = 01H BX = desired strategy code 00H = first fit 01H = best fit 02H = last fit Returns: If function successful Carry flag = clear and, if called with AL = 00H AX = current strategy code If function unsuccessful Carry flag = set AX = error code Notes: ■ The memory allocation strategies are: ∙ First fit: MS-DOS searches the available memory blocks from low addresses to high addresses, assigning the first one large enough to satisfy the block allocation request. ∙ Best fit: MS-DOS searches all available memory blocks and assigns the smallest available block that will satisfy the request, regardless of its position. ∙ Last fit: MS-DOS searches the available memory blocks from high addresses to low addresses, assigning the highest one large enough to satisfy the block allocation request. ■ The default MS-DOS memory allocation strategy is First Fit (code 0). Example: Save the code indicating the current memory allocation strategy in the variable strat, then change the system's memory allocation strategy to "best fit." strat dw 0 ; previous strategy code . . . ; get current strategy mov ah,58h ; function number mov al,0 ; 0 = get strategy int 21h ; transfer to MS-DOS jc error ; jump if function failed mov strat,ax ; save strategy code ; now set new strategy mov ah,58h ; function number mov al,1 ; 1 = set strategy mov bx,1 ; 1 = best fit int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 59H (89) Get extended error information ──────────────────────────────────────────────────────────────────────────── Obtains detailed error information after a previous unsuccessful Int 21H function call, including the recommended remedial action. Call with: AH = 59H BX = 00H Returns: AX = extended error code 01H function number invalid 02H file not found 03H path not found 04H too many open files 05H access denied 06H handle invalid 07H memory control blocks destroyed 08H insufficient memory 09H memory block address invalid 0AH (10) environment invalid 0BH (11) format invalid 0CH (12) access code invalid 0DH (13) data invalid 0EH (14) unknown unit 0FH (15) disk drive invalid 10H (16) attempted to remove current directory 11H (17) not same device 12H (18) no more files 13H (19) disk write-protected 14H (20) unknown unit 15H (21) drive not ready 16H (22) unknown command 17H (23) data error (CRC) 18H (24) bad request structure length 19H (25) seek error 1AH (26) unknown media type 1BH (27) sector not found 1CH (28) printer out of paper 1DH (29) write fault 1EH (30) read fault 1FH (31) general failure 20H (32) sharing violation 21H (33) lock violation 22H (34) disk change invalid 23H (35) FCB unavailable 24H (36) sharing buffer exceeded 25H─31H reserved 32H (50) unsupported network request 33H (51) remote machine not listening 34H (52) duplicate name on network 35H (53) network name not found 36H (54) network busy 37H (55) device no longer exists on network 38H (56) netBIOS command limit exceeded 39H (57) error in network adapter hardware 3AH (58) incorrect response from network 3BH (59) unexpected network error 3CH (60) remote adapter incompatible 3DH (61) print queue full 3EH (62) not enough space for print file 3FH (63) print file canceled 40H (64) network name deleted 41H (65) network access denied 42H (66) incorrect network device type 43H (67) network name not found 44H (68) network name limit exceeded 45H (69) netBIOS session limit exceeded 46H (70) file sharing temporarily paused 47H (71) network request not accepted 48H (72) print or disk redirection paused 49H─4FH reserved 50H (80) file already exists 51H (81) reserved 52H (82) cannot make directory 53H (83) fail on Int 24H (critical error) 54H (84) too many redirections 55H (85) duplicate redirection 56H (86) invalid password 57H (87) invalid parameter 58H (88) network device fault 59H (89) function not supported by network 5AH (90) required system component not installed BH = error class 01H if out of resource (such as storage or handles) 02H if not error, but temporary situation (such as locked region in file) that can be expected to end 03H if authorization problem 04H if internal error in system software 05H if hardware failure 06H if system software failure not the fault of the active process (such as missing configuration files) 07H if application program error 08H if file or item not found 09H if file or item of invalid type or format 0AH (10) if file or item locked 0BH (11) if wrong disk in drive, bad spot on disk, or storage medium problem 0CH (12) if item already exists 0DH (13) unknown error BL = recommended action 01H retry reasonable number of times, then prompt user to select abort or ignore 02H retry reasonable number of times with delay between retries, then prompt user to select abort or ignore 03H get corrected information from user (typically caused by incorrect filename or drive specification) 04H abort application with cleanup (i.e., terminate the program in as orderly a manner as possible: releasing locks, closing files, etc.) 05H perform immediate exit without cleanup 06H ignore error 07H retry after user intervention to remove cause of error CH = error locus 01H unknown 02H block device (disk or disk emulator) 03H network 04H serial device 05H memory and, for MS-DOS 3.0 and later, ES:DI = ASCIIZ volume label of disk to insert, if AX = 0022H (invalid disk change) Notes: ■ This function may be called after any other Int 21H function call that returned an error status, in order to obtain more detailed information about the error type and the recommended action. If the previous Int 21H function call had no error, 0000H is returned in register AX. This function may also be called during the execution of a critical-error (Int 24H) handler. ■ The contents of registers CL, DX, SI, DI, BP, DS, and ES are destroyed by this function. ■ Note that extended error codes 13H─1FH (19─31) and 34 (22H) correspond exactly to the error codes 0─0CH (0─12) and 0FH (15) returned by Int 24H. ■ You should not code your programs to recognize only specific error numbers if you wish to ensure upward compatibility, because new error codes are added in each version of MS-DOS. Example: Attempt to open the file named NOSUCH.DAT using a file control block; if the open request fails, get the extended error code. myfcb db 0 ; drive = default db 'NOSUCH ' ; filename, 8 chars db 'DAT' ; extension, 3 chars db 25 dup (0) ; remainder of FCB . . . label1: ; open the file mov ah,0fh ; function number mov dx,seg myfcb ; address of FCB mov ds,dx mov dx,offset myfcb int 21h ; transfer to MS-DOS or al,al ; check open status jz success ; jump if opened OK ; open failed, get ; extended error info mov ah,59h ; function number xor bx,bx ; BX must = 0 int 21h ; transfer to MS-DOS or ax,ax ; double check for error jz success ; jump if no error cmp bl,2 ; should we retry? jle label1 ; yes, jump jmp error ; no, give up . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 5AH (90) Create temporary file ──────────────────────────────────────────────────────────────────────────── Creates a file with a unique name, in the current or specified directory on the default or specified disk drive, and returns a handle that can be used by the program for subsequent access to the file. The name generated for the file is also returned in a buffer specified by the program. Call with: AH = 5AH CX = attribute (bits may be combined) Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3─4 reserved (0) 5 archive 6─15 reserved (0) DS:DX = segment:offset of ASCIIZ path Returns: If function successful Carry flag = clear AX = handle DS:DX = segment:offset of complete ASCIIZ pathname If function unsuccessful Carry flag = set AX = error code Notes: ■ The ASCIIZ path supplied to this function should be followed by at least 13 additional bytes of buffer space. MS-DOS adds a backslash (\) to the supplied path, if necessary, then appends a null-terminated filename that is a function of the current time. ■ Files created with this function are not automatically deleted when the calling program terminates. ■ The function fails if ∙ any element of the pathname does not exist. ∙ the file is being created in the root directory, and the root directory is full. ■ See also Int 21H Functions 3CH, 5BH, and 6CH, which provide additional facilities for creating files. ■ [3.0+] If the program is running on a network, the file is created and opened for read/write access in compatibility sharing mode. Example: Create a temporary file with a unique name and normal attribute in directory \TEMP of drive C. Note that you must allow room for MS-DOS to append the generated filename to the supplied path. The complete file specification should be used to delete the temporary file before your program terminates. fname db 'C:\TEMP\' ; pathname for temp file db 13 dup (0) ; receives filename fhandle dw ? ; file handle . . . mov ah,5ah ; function number mov cx,0 ; normal attribute mov dx,seg fname ; address of pathname mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if create failed mov fhandle,ax ; save file handle . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 5BH (91) Create new file ──────────────────────────────────────────────────────────────────────────── Given an ASCIIZ pathname, creates a file in the designated or default directory on the designated or default drive, and returns a handle that can be used by the program for subsequent access to the file. If a file with the same name already exists, the function fails. Call with: AH = 5BH CX = attribute (bits may be combined) Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3 volume label 4 reserved (0) 5 archive 6─15 reserved (0) DS:DX = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear AX = handle If function unsuccessful Carry flag = set AX = error code Notes: ■ The function fails if: ∙ any element of the specified path does not exist. ∙ a file with the identical pathname (i.e., the same filename and extension in the same location in the directory structure) already exists. ∙ the file is being created in the root directory, and the root directory is full. ∙ [3.0+] the program is running on a network, and the user has insufficient access rights to the directory that will contain the file. ■ The file is usually given a normal attribute (0) when it is created, and is opened for both read and write operations. The attribute can subsequently be modified with Int 21H Function 43H. ■ See also Int 21H Functions 3CH, 5AH, and 6CH, which provide alternative ways of creating files. ■ This function may be used to implement semaphores in a network or multitasking environment. If the function succeeds, the program has acquired the semaphore. To release the semaphore, the program simply deletes the file. Example: Create and open a file named MYFILE.DAT in the directory \MYDIR on drive C; MS-DOS returns an error if a file with the same name already exists in that location. fname db 'C:\MYDIR\MYFILE.DAT',0 fhandle dw ? ; file handle . . . mov ah,5bh ; function number xor cx,cx ; normal attribute mov dx,seg fname ; filename address mov ds,dx mov dx,offset fname int 21h ; transfer to MS-DOS jc error ; jump if create failed mov fhandle,ax ; save file handle . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 5CH (92) Lock or unlock file region ──────────────────────────────────────────────────────────────────────────── Locks or unlocks the specified region of a file. This function is not available unless the file-sharing module (SHARE.EXE) is loaded. Call with: AH = 5CH AL = 00H if locking region 01H if unlocking region BX = handle CX = high part of region offset DX = low part of region offset SI = high part of region length DI = low part of region length Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ This function is useful for file and record synchronization in a multitasking environment or network. Access to the file as a whole is controlled by the attribute and file-sharing parameters passed in open or create calls and by the file's attributes, which are stored in its directory entry. ■ The beginning location in the file to be locked or unlocked is supplied as a positive double precision integer, which is a byte offset into the file. The length of the region to be locked or unlocked is similarly supplied as a positive double precision integer. ■ For every call to lock a region of a file, there must be a subsequent unlock call with exactly the same file offset and length. ■ Locking beyond the current end of file is not an error. ■ Duplicate handles created with Int 21H Function 45H, or handles redirected to the file with Int 21H Function 46H, are allowed access to locked regions within the same process. ■ Programs that are loaded with the EXEC call (Int 21H Function 4BH) inherit the handles of their parent but not any active locks. ■ If a process terminates without releasing active locks on a file, the result is undefined. Therefore, programs using this function should install their own Int 23H and Int 24H handlers so that they cannot be terminated unexpectedly. Example: Assume that a file was previously opened and that its handle was saved in the variable fhandle. Lock a 4096 byte region of the file, starting at 32,768 bytes from the beginning of the file, so that it cannot be accessed by other programs. fhandle dw ? ; file handle . . . mov ah,5ch ; function number mov al,0 ; subfunction 0 = lock mov bx,fhandle ; file handle mov cx,0 ; upper part of offset mov dx,32768 ; lower part of offset mov si,0 ; upper part of length mov di,4096 ; lower part of length int 21h ; transfer to MS-DOS jc error ; jump if lock failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 5DH (93) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 5EH (94) Subfunction 00H Get machine name ──────────────────────────────────────────────────────────────────────────── Returns the address of an ASCIIZ (null-terminated) string identifying the local computer. This function call is only available when Microsoft Networks is running. Call with: AH = 5EH AL = 00H DS:DX = segment:offset of buffer to receive string Returns: If function successful Carry flag = clear CH = 00H if name not defined <> 00H if name defined CL = netBIOS name number (if CH <> 0) DX:DX = segment:offset of identifier (if CH <> 0 ) If function unsuccessful Carry flag = set AX = error code Notes: ■ The computer identifier is a 15-byte string, padded with spaces and terminated with a null (00H) byte. ■ The effect of this call is unpredictable if the file-sharing support module is not loaded. Example: Get the machine name of the local computer into the buffer named mname. mname db 16 dup (?) . . . mov ax,5e00h ; function & subfunction mov dx,seg mname ; address of buffer mov ds,dx mov dx,offset mname int 21h ; transfer to MS-DOS jc error ; jump if function failed or ch,ch ; make sure name exists jz error ; jump if no name defined . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 5EH (94) Subfunction 02H Set printer setup string ──────────────────────────────────────────────────────────────────────────── Specifies a string to be sent in front of all files directed to a particular network printer, allowing users at different network nodes to specify individualized operating modes on the same printer. This function call is only available when Microsoft Networks is running. Call with: AH = 5EH AL = 02H BX = redirection list index CX = length of setup string DS:SI = segment:offset of setup string Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ The redirection list index passed in register BX is obtained with Function 5FH Subfunction 02H (Get Redirection List Entry). ■ See also Function 5EH Subfunction 03H, which may be used to obtain the existing setup string for a particular network printer. Example: Initialize the setup string for the printer designated by redirection list index 2 so that the device is put into boldface mode before printing a file requested by this network node. setup db 01bh,045h ; selects boldface mode . . . mov ax,5e02h ; function & subfunction mov bx,2 ; redirection list index 2 mov cx,2 ; length of setup string mov si,seg setup ; address of setup string mov ds,si mov si,offset setup int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 5EH (94) Subfunction 03H Get printer setup string ──────────────────────────────────────────────────────────────────────────── Obtains the printer setup string for a particular network printer. This function call is only available when Microsoft Networks is running. Call with: AH = 5EH AL = 03H BX = redirection list index ES:DI = segment:offset of buffer to receive setup string Returns: If function successful Carry flag = clear CX = length of printer setup string ES:DI = address of buffer holding setup string If function unsuccessful Carry flag = set AX = error code Notes: ■ The redirection list index passed in register BX is obtained with Function 5FH Subfunction 02H (Get Redirection List Entry). ■ See also Int 21H Function 5EH Subfunction 02H, which is used to specify a setup string for a network printer. Example: Get the setup string for this network node associated with the printer designated by redirection list index 2. setup db 64 dup (?) ; receives setup string . . . mov ax,5e03h ; function & subfunction mov bx,2 ; redirection list index 2 mov di,seg setup ; address of buffer mov es,di mov di,offset setup int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 5FH (95) Subfunction 02H Get redirection list entry ──────────────────────────────────────────────────────────────────────────── Allows inspection of the system redirection list, which associates local logical names with network files, directories, or printers. This function call is only available when Microsoft Networks is running and the file-sharing module (SHARE.EXE) has been loaded. Call with: AH = 5FH AL = 02H BX = redirection list index DS:SI = segment:offset of 16-byte buffer to receive local device name ES:DI = segment:offset of 128-byte buffer to receive network name Returns: If function successful Carry flag = clear BH = device status flag bit 0 = 0 if device valid = 1 if not valid BL = device type 03H if printer 04H if drive CX = stored parameter value DX = destroyed BP = destroyed DS:SI = segment:offset of ASCIIZ local device name ES:DI = segment:offset of ASCIIZ network name If function unsuccessful Carry flag = set AX = error code Note: ■ The parameter returned in CX is a value that was previously passed to MS-DOS in register CX with Int 21H Function 5FH Subfunction 03H (Redirect Device). It represents data that is private to the applications which store and retrieve it and has no meaning to MS-DOS. Example: Get the local and network names for the device specified by the first redirection list entry. local db 16 dup (?) ; receives local device name network db 128 dup (?) ; receives network name . . . mov ax,5f02h ; function & subfunction mov bx,0 ; redirection list entry 0 mov si,seg local ; local name buffer addr mov ds,si mov si,offset local mov di,seg network ; network name buffer addr mov es,di mov di,offset network int 21h ; transfer to MS-DOS jc error ; jump if call failed or bh,bh ; check device status jnz error ; jump if device not valid . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 5FH (95) Subfunction 03H Redirect device ──────────────────────────────────────────────────────────────────────────── Establishes redirection across the network by associating a local device name with a network name. This function call is only available when Microsoft Networks is running and the file-sharing module (SHARE.EXE) has been loaded. Call with: AH = 5FH AL = 03H BL = device type 03H if printer 04H if drive CX = parameter to save for caller DS:SI = segment:offset of ASCIIZ local device name ES:DI = segment:offset of ASCIIZ network name, followed by ASCIIZ password Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ The local name can be a drive designator (a letter followed by a colon, such as "D:"), a printer name, or a null string. Printer names must be one of the following: PRN, LPT1, LPT2, or LPT3. If a null string followed by a password is used, MS-DOS attempts to grant access to the network directory with the specified password. ■ The parameter passed in CX can be retrieved by later calls to Int 21H Function 5FH Subfunction 02H. It represents data that is private to the applications which store and retrieve it and has no meaning to MS-DOS. Example: Redirect the local drive E to the directory \FORTH on the server named LMI, using the password FRED. locname db 'E:',0 ; local drive netname db '\\LMI\FORTH',0 db 'FRED',0 . . . mov ax,5f03h ; function & subfunction mov bl,4 ; code 4 = disk drive mov si,seg locname ; address of local name mov ds,si mov si,offset locname mov di,seg netname ; address of network name mov es,di mov di,offset netname int 21h ; transfer to MS-DOS jc error ; jump if redirect failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.1] Function 5FH (95) Subfunction 04H Cancel device redirection ──────────────────────────────────────────────────────────────────────────── Cancels a previous redirection request by removing the association of a local device name with a network name. This function call is only available when Microsoft Networks is running and the file-sharing module (SHARE.EXE) has been loaded. Call with: AH = 5FH AL = 04H DS:SI = segment:offset of ASCIIZ local device name Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Note: ■ The supplied name can be a drive designator (a letter followed by a colon, such as "D:"), a printer name, or a string starting with two backslashes (\\). Printer names must be one of the following: PRN, LPT1, LPT2, or LPT3. If the string with two backslashes is used, the connection between the local machine and the network directory is terminated. Example: Cancel the redirection of local drive E to the network server. locname db 'E:',0 . . . mov ax,5f04h ; function & subfunction mov si,seg locname ; address of local name mov ds,si mov si,offset locname int 21h ; transfer to MS-DOS jc error ; jump if cancel failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 60H (96) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 61H (97) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [3.0] Function 62H (98) Get PSP address ──────────────────────────────────────────────────────────────────────────── Obtains the segment (paragraph) address of the program segment prefix (PSP) for the currently executing program. Call with: AH = 62H Returns: BX = segment address of program segment prefix Notes: ■ Before a program receives control from MS-DOS, its program segment prefix is set up to contain certain vital information, such as: ∙ the segment address of the program's environment block ∙ the command line originally entered by the user ∙ the original contents of the terminate, Ctrl-C, and critical-error handler vectors ∙ the top address of available RAM ■ The segment address of the PSP is normally passed to the program in registers DS and ES when it initially receives control from MS-DOS. This function allows a program to conveniently recover the PSP address at any point during its execution, without having to save it at program entry. Example: Get the segment base of the program segment prefix, then copy the command tail from the PSP into the local buffer named buff. ctail equ 080H ; PSP offset, command tail buff db 80 dup (?) ; copy of command tail . . . ; get PSP address mov ah,62H ; function number int 21h ; transfer to MS-DOS ; copy command tail mov ds,bx ; PSP segment to DS mov si,offset ctail ; offset of command tail mov di,seg buff ; local buffer address mov es,di mov di,offset buff mov cl,[si] ; length of command tail inc cl ; include count byte xor ch,ch cld rep movsb ; copy to local buffer . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [2.25 only] Function 63H (99) Get DBCS lead byte table ──────────────────────────────────────────────────────────────────────────── Obtains the address of the system table of legal lead byte ranges for double-byte character sets (DBCS), or sets or obtains the interim console flag. Int 21H Function 63H is available only in MS-DOS version 2.25; it is not supported in MS-DOS versions 3.0 and later. Call with: AH = 63H AL = subfunction 00H if getting address of DBCS lead byte table 01H if setting or clearing interim console flag 02H if obtaining value of interim console flag If AL = 01H DL = 00H if clearing interim console flag 01H if setting interim console flag Returns: If function successful Carry flag = clear and, if called with AL = 00H DS:SI = segment:offset of DBCS lead byte table or, if called with AL = 02H DL = value of interim console flag If function unsuccessful Carry flag = set AX = error code Notes: ■ The DBCS lead byte table consists of a variable number of two byte entries, terminated by two null (00H) bytes. Each pair defines the beginning and ending value for a range of lead bytes. The value of a legal lead byte is always in the range 80─0FFH. ■ Entries in the lead byte table must be in ascending order. If no legal lead bytes are defined in a given system, the table consists only of the two null bytes. ■ If the interim console flag is set, Int 21H Functions 07H (Unfiltered Character Input), 08H (Character Input without Echo), and 0BH (Keyboard Status) will support interim characters. ■ Unlike most other MS-DOS services, this function call does not necessarily preserve any registers except SS:SP. ■ [4.0] The address of the DBCS lead byte table can also be obtained with Int 21H Function 65H. ──────────────────────────────────────────────────────────────────────────── Int 21H Function 64H (100) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [3.3] Function 65H (101) Get extended country information ──────────────────────────────────────────────────────────────────────────── Obtains information about the specified country and/or code page. Call with: AH = 65H AL = subfunction 01H = Get General Internationalization Information 02H = Get Pointer to Uppercase Table 04H = Get Pointer to Filename Uppercase Table 06H = Get Pointer to Collating Table 07H = Get Pointer to Double-Byte Character Set (DBCS) Vector (MS-DOS versions 4.0 and later) BX = code page of interest (-1 = active CON device) CX = length of buffer to receive information (must be >= 5) DX = country ID (-1 = default) ES:DI = address of buffer to receive information Returns: If function successful Carry flag = clear and requested data placed in calling program's buffer If function unsuccessful Carry flag = set AX = error code Notes: ■ The information returned by this function is a superset of the information returned by Int 21H Function 38H. ■ This function may fail if either the country code or the code page number is invalid, or if the code page does not match the country code. ■ The function fails if the specified buffer length is less than five bytes. If the buffer to receive the information is at least five bytes long but is too short for the requested information, the data is truncated and no error is returned. ■ The format of the data returned by Subfunction 01H is: Byte(s) Contents 00H information ID code (1) 01H─02H length of following buffer 03H─04H country ID 05H─06H code page number 07H─08H date format 0 = USA m d y 1 = Europe d m y 2 = Japan y m d 09H─0DH ASCIIZ currency symbol 0EH─0FH ASCIIZ thousands separator 10H─11H ASCIIZ decimal separator 12H─13H ASCIIZ date separator 14H─15H ASCIIZ time separator 16H currency format flags bit 0 =>0 if currency symbol precedes value =>1 if currency symbol follows value bit 1 =>0 if no space between value and currency symbol =>1 if one space between value and currency symbol bit 2 =>0 if currency symbol and decimal are separate =>1 if currency symbol replaces decimal separator 17H number of digits after decimal in currency 18H time format bit 0 = 0 if 12-hour clock = 1 if 24-hour clock 19H─1CH case-map routine call address 1DH─1EH ASCIIZ data list separator 1FH─28H reserved ■ The format of the data returned by Subfunctions 02H, 04H, 06H, and 07H is: Byte(s) Contents 00H information ID code (2, 4, or 6) 01H─05H double-word pointer to table ■ The uppercase and filename uppercase tables are a maximum of 130 bytes long. The first two bytes contain the size of the table; the following bytes contain the uppercase equivalents, if any, for character codes 80H─FFH. The main use of these tables is to map accented or otherwise modified vowels to their plain vowel equivalents. Text translated with the help of this table can be sent to devices that do not support the IBM graphics character set, or used to create filenames that do not require a special keyboard configuration for entry. ■ The collating table is a maximum of 258 bytes long. The first two bytes contain the table length, and the subsequent bytes contain the values to be used for the corresponding character codes (0─FFH) during a sort operation. This table maps uppercase and lowercase ASCII characters to the same collating codes so that sorts will be case-insensitive, and it maps accented vowels to their plain vowel equivalents. ■ [4.0+] Subfunction 07H returns a pointer to a variable length table of that defines ranges for double-byte character set (DBCS) lead bytes. The table is terminated by a pair of zero bytes, unless it must be truncated to fit in the buffer, and has the following format: dw length db start1,end1 db start2,end2 . . . db 0,0 For example: dw 4 db 81h,9fh db 0e0h,0fch db 0,0 ■ In some cases a truncated translation table may be presented to the program by MS-DOS. Applications should always check the length at the beginning of the table, to make sure it contains a translation code for the particular character of interest. Examples: Obtain the extended country information associated with the default country and code page 437. buffer db 41 dup (0) ; receives country info . . . mov ax,6501h ; function & subfunction mov bx,437 ; code page mov cx,41 ; buffer length mov dx,-1 ; default country mov di,seg buffer ; buffer address mov es,di mov di,offset buffer int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . In this case, MS-DOS filled the following extended country information into the buffer: buffer db 1 ; info ID code dw 38 ; length of following buffer dw 1 ; country ID (USA) dw 437 ; code page number dw 0 ; date format db '$',0,0,0,0 ; currency symbol db ',',0 ; thousands separator db '.',0 ; decimal separator db '-',0 ; date separator db ':',0 ; time separator db 0 ; currency format flags db 2 ; digits in currency db 0 ; time format dd 026ah:176ch ; case map entry point db ',',0 ; data list separator db 10 dup (0) ; reserved Obtain the pointer to the uppercase table associated with the default country and code page 437. buffer db 5 dup (0) ; receives pointer info . . . mov ax,6502h ; function number mov bx,437 ; code page mov cx,5 ; length of buffer mov dx,-1 ; default country mov di,seg buffer ; buffer address mov es,di mov di,offset buffer int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . In this case, MS-DOS filled the following values into the buffer: buffer db 2 ; info ID code dw 0204h ; offset of uppercase table dw 1140h ; segment of uppercase table and the table at 1140:0204H contains the following data: 0 1 2 3 4 5 6 7 8 9 A B C D E F 0123456789ABCDE 1140:0200 80 00 80 9A 45 41 8E 41 8F 80 45 45 ....EA.A..E 1140:0210 45 49 49 49 8E 8F 90 92 92 4F 99 4F 55 55 59 99 EIII.....O.OUUY 1140:0220 9A 9B 9C 9D 9E 9F 41 49 4F 55 A5 A5 A6 A7 A8 A9 ......AIOU..... 1140:0230 AA AB AC AD AE AF B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 ............... 1140:0240 BA BB BC BD BE BF C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 ............... 1140:0250 CA CB CC CD CE CF D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 ............... 1140:0260 DA DB DC DD DE DF E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 ............... 1140:0270 EA EB EC ED EE EF F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 ............... 1140:0280 FA FB FC FD FE FF ...... ──────────────────────────────────────────────────────────────────────────── Int 21H [3.3] Function 66H (102) Get or set code page ──────────────────────────────────────────────────────────────────────────── Obtains or selects the current code page. Call with: AH = 66H AL = subfunction 01H = Get Code Page 02H = Select Code Page BX = code page to select, if AL = 02H Returns: If function successful Carry flag = clear and, if called with AL = 01H BX = active code page DX = default code page If function unsuccessful Carry flag = set AX = error code Note: ■ When the Select Code Page subfunction is used, MS-DOS gets the new code page from the COUNTRY.SYS file. The device must be previously prepared for code page switching with the appropriate DEVICE= directive in the CONFIG.SYS file and NLSFUNC and MODE CP PREPARE commands (placed in the AUTOEXEC.BAT file, usually). Example: Force the active code page to be the same as the system's default code page, that is, restore the code page that was active when the system was first booted. . . . ; get current and ; default code page mov ax,6601h ; function number int 21h ; transfer to MS-DOS jc error ; jump if function failed ; set code page mov bx,dx ; active = default mov ax,6602h ; function number int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.3] Function 67H (103) Set handle count ──────────────────────────────────────────────────────────────────────────── Sets the maximum number of files and devices that may be opened simultaneously using handles by the current process. Call with: AH = 67H BX = number of desired handles Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ This function call controls the size of the table that relates handle numbers for the current process to MS-DOS's internal, global table for all of the open files and devices in the system. The default table is located in the reserved area of the process's PSP and is large enough for 20 handles. ■ The function fails if the requested number of handles is greater than 20 and there is not sufficient free memory in the system to allocate a new block to hold the enlarged table. ■ If the number of handles requested is larger than the available entries in the system's global table for file and device handles (controlled by the FILES entry in CONFIG.SYS), no error is returned. However, a subsequent attempt to open a file or device, or create a new file, will fail if all the entries in the system's global file table are in use, even if the requesting process has not used up all its own handles. Example: Set the maximum handle count for the current process to thirty, so that the process can have as many as 30 files or devices opened simultaneously. (Five of the handles are already assigned to the standard devices when the process starts up.) Note that a FILES=30 (or greater value) entry in the CONFIG.SYS file would also be required for the process to successfully open 30 files or devices. . . . mov ah,67h ; function number mov bx,30 ; maximum number of handles int 21h ; transfer to MS-DOS jc error ; jump if function failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H [3.3] Function 68H (104) Commit file ──────────────────────────────────────────────────────────────────────────── Forces all data in MS-DOS's internal buffers associated with a specified handle to be physically written to the device. If the handle refers to a file, and the file has been modified, the time and date stamp and file size in the file's directory entry are updated. Call with: AH = 68H BX = handle Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code Notes: ■ The effect of this function is equivalent to closing and reopening a file, or to duplicating a handle for the file with Int 21H Function 45H and then closing the duplicate. However, this function has the advantage that it will not fail due to lack of handles, and the application does not risk losing control of the file in multitasking or network environments. ■ If this function is requested for a handle associated with a character device, a success flag is returned, but there is no other effect. Example: Assume that the file MYFILE.DAT has been previously opened and that the handle for that file is stored in the variable fhandle. Call the Commit File function to ensure that any data in MS-DOS's internal buffers associated with the handle is written out to disk and that the directory and file allocation table are up to date. fname db 'MYFILE.DAT',0 ; ASCIIZ filename fhandle dw ? ; file handle . . . mov ah,68h ; function number mov bx,fhandle ; file handle int 21h ; transfer to MS-DOS jc error ; jump if commit failed . . . ──────────────────────────────────────────────────────────────────────────── Int 21H Function 69H (105) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 6AH (106) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H Function 6BH (107) Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 21H [4.0] Function 6CH (108) Extended open file ──────────────────────────────────────────────────────────────────────────── Given an ASCIIZ pathname, opens, creates or replaces a file in the designated or default directory on the designated or default disk drive. Returns a handle that can be used by the program for subsequent access to the file. Call with: AH = 6CH AL = 00H BX = open mode Bit(s) Significance 0─2 access type 000 = read-only 001 = write-only 010 = read/write 3 reserved (0) 4─6 sharing mode 000 = compatibility 001 = deny read/write (deny all) 010 = deny write 011 = deny read 100 = deny none 7 inheritance 0 = child process inherits handle 1 = child does not inherit handle 8─12 reserved (0) 13 critical error handling 0 = execute Int 24H 1 = return error to process 14 write-through 0 = writes may be buffered and deferred 1 = physical write at request time 15 reserved (0) CX = file attribute (bits may be combined; ignored if open) Bit(s) Significance (if set) 0 read-only 1 hidden 2 system 3 volume label 4 reserved (0) 5 archive 6─15 reserved (0) DX = open flag Bits Significance 0─3 action if file exists 0000 = fail 0001 = open file 0010 = replace file 4─7 action if file doesn't exist 0000 = fail 0001 = create file 8─15 reserved (0) DS:SI = segment:offset of ASCIIZ pathname Returns: If function successful Carry flag = clear AX = handle CX = action taken 1 = file existed and was opened 2 = file did not exist and was created 3 = file existed and was replaced If function failed Carry flag = set AX = error code Notes: ■ The function fails if: ∙ any element of the pathname does not exist. ∙ the file is being created in the root directory and the root directory is full. ∙ the file is being created and a file with the same name and the read-only attribute already exists in the specified directory. ∙ the program is running on a network and the user running the program has insufficient access rights. ■ A file is usually given a normal (0) attribute when it is created. The file's attribute can subsequently be modified with Int 21H Function 43H. ■ This function combines the capabilities of Int 21H Functions 3CH, 3DH, and 5BH. It was added to MS-DOS for compatibility with the DosOpen function of OS/2. Example: Create the file MYFILE.DAT, if it does not already exist, in directory \MYDIR on drive C, and save the handle for subsequent access to the file. fname db 'C:\MYDIR\MYFILE.DAT',0 fhandle dw ? . . . mov ax,6c00h ; function number mov bx,4042h ; read/write, deny none, ; write-through mode xor cx,cx ; normal attribute mov dx,0010h ; create if doesn't exist, ; fail if exists mov si,seg fname ; address of pathname mov ds,si mov si,offset fname int 21h ; transfer to MS-DOS jc error ; jump if open failed mov fhandle,ax ; save file handle . . . ──────────────────────────────────────────────────────────────────────────── Int 22H [1.0] Terminate handler address ──────────────────────────────────────────────────────────────────────────── The machine interrupt vector for Int 22H (memory locations 0000:0088H through 0000:008BH) contains the address of the routine that receives control when the currently executing program terminates via Int 20H, Int 27H, or Int 21H Functions 00H, 31H, or 4CH. The address in this vector is also copied into offsets 0AH through 0DH of the program segment prefix (PSP) when a program is loaded but before it begins executing, and is restored from the PSP (in case it was modified by the application) as part of MS-DOS's termination handling. This interrupt should never be issued directly. ──────────────────────────────────────────────────────────────────────────── Int 23H [1.0] Ctrl-C handler address ──────────────────────────────────────────────────────────────────────────── The machine interrupt vector for Int 23H (memory locations 0000:008CH though 0000:008FH) contains the address of the routine which receives control when a Ctrl-C is detected during any character I/O function and, if the Break flag is ON, during most other MS-DOS function calls. The address in this vector is also copied into locations 0EH through 11H of the program segment prefix (PSP) when a program is loaded but before it begins executing, and is restored from the PSP (in case it was modified by the application) as part of MS-DOS's termination handling. This interrupt should never be issued directly. Notes: ■ The initialization code for an application can use Int 21H Function 25H to reset the Interrupt 23H vector to point to its own routine for Ctrl-C handling. In this way, the program can avoid being terminated unexpectedly as the result of the user's entry of a Ctrl-C or Ctrl-Break. ■ When a Ctrl-C is detected and the program's Int 23H handler receives control, all registers are set to their values at the point of the original function call. The handler can then do any of the following: ∙ Set a local flag for later inspection by the application, or take any other appropriate action, and perform an IRET. All registers must be preserved. The MS-DOS function in progress will be restarted from scratch and will proceed to completion, control finally returning to the application in the normal manner. ∙ Take appropriate action and then perform a RET FAR to give control back to MS-DOS. The state of the carry flag is used by MS-DOS to determine what action to take. If the carry flag is set, the application will be terminated; if the carry flag is clear, the application will continue in the normal manner. ∙ Retain control by transferring to an error-handling routine within the application and then resume execution or take other appropriate action, never performing a RET FAR or IRET to end the interrupt-handling sequence. This option will cause no harm to the system. ■ Any MS-DOS function call may be used within the body of an Int 23H handler. Example: See Chapter 5. ──────────────────────────────────────────────────────────────────────────── Int 24H [1.0] Critical-error handler address ──────────────────────────────────────────────────────────────────────────── The machine interrupt vector for Int 24H (memory locations 0000:0090H through 0000:0093H) contains the address of the routine that receives control when a critical error (usually a hardware error) is detected. This address is also copied into locations 12H through 15H of the program segment prefix (PSP) when a program is loaded but before it begins executing, and is restored from the PSP (in case it was modified by the application) as part of MS-DOS's termination handling. This interrupt should never be issued directly. Notes: ■ On entry to the critical-error interrupt handler, bit 7 of register AH is clear (0) if the error was a disk I/O error; otherwise, it is set (1). BP:SI contains the address of a device-driver header from which additional information can be obtained. Interrupts are disabled. The registers will be set up for a retry operation, and an error code will be in the lower half of the DI register, with the upper half undefined. The lower byte of DI contains: 00H write-protect error 01H unknown unit 02H drive not ready 03H unknown command 04H data error (CRC) 05H bad request structure length 06H seek error 07H unknown media type 08H sector not found 09H printer out of paper 0AH write fault 0BH read fault 0CH general failure 0DH reserved 0EH reserved 0FH invalid disk change (MS-DOS version 3 only) Note that these are the same error codes returned by the device driver in the request header. Also, upon entry, the stack is set up as shown in Figure 8-8, page 149. ■ When a disk I/O error occurs, MS-DOS automatically retries the operation before issuing a critical-error Int 24H. The number of retries varies in different versions of MS-DOS, but is typically in the range three to five. ■ Int 24H handlers must preserve the SS, SP, DS, ES, BX, CX, and DX registers. Only Int 21H Functions 01H─0CH and 59H can be used by an Int 24H handler; other function calls will destroy the MS-DOS stack and its ability to retry or ignore an error. ■ When the Int 24H handler issues an IRET, it should return an action code in AL that will be interpreted by DOS as follows: 0 ignore the error 1 retry the operation 2 terminate the program 3 [3.0+] fail the function call in progress ■ If the Int 24H handler returns control directly to the application program rather than to MS-DOS, it must restore the program's registers, removing all but the last three words from the stack, and issue an IRET. Control returns to the instruction immediately following the function call that caused the error. This option leaves MS-DOS in an unstable state until a call to an Int 21H function higher than Function 0CH is made. Example: See Chapter 8. ──────────────────────────────────────────────────────────────────────────── Int 25H [1.0] Absolute disk read ──────────────────────────────────────────────────────────────────────────── Provides a direct linkage to the MS-DOS BIOS module to read data from a logical disk sector into memory. Call with: For access to partitions <= 32 MB AL = drive number (0 = A, 1 = B, etc) CX = number of sectors to read DX = starting sector number DS:BX = segment:offset of buffer For access to partitions > 32 MB (MS-DOS 4.0 and later) AL = drive number (0 = A, 1 = B, etc) CX = -1 DS:BX = segment:offset of parameter block (see Notes) Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code (see Notes) Notes: ■ All registers except the segment registers may be destroyed. ■ When this function returns, the CPU flags originally pushed on the stack by the INT 25H instruction are still on the stack. The stack must be cleared by a POPF or ADD SP,2 to prevent uncontrolled stack growth and to make accessible any other values that were pushed on the stack before the call to INT 25H. ■ Logical sector numbers are obtained by numbering each disk sector sequentially from cylinder 0, head 0, sector 1, and continuing until the last sector on the disk is counted. The head number is incremented before the track number. Logically adjacent sectors may not be physically adjacent, due to interleaving that occurs at the device-adapter level for some disk types. ■ The error code is interpreted as follows: The lower byte (AL) is the same error code that is returned in the lower byte of DI when an Int 24H is issued. The upper byte (AH) contains: 01H if bad command 02H if bad address mark 04H if requested sector not found 08H if direct memory access (DMA) failure 10H if data error (bad CRC) 20H if controller failed 40H if seek operation failed 80H if attachment failed to respond ■ [4.0+] When accessing partitions larger than 32 MB under MS-DOS version 4, this function uses a parameter block with the following format: Bytes Description 00H─03H 32-bit sector number 04H─05H number of sectors to read 06H─07H offset of buffer 08H─09H segment of buffer Example: Read logical sector 1 of drive A into the memory area named buff. (On most MS-DOS floppy disks, this sector contains the beginning of the file allocation table.) buff db 512 dup (?) ; receives data from disk . . . mov al,0 ; drive A mov cx,1 ; number of sectors mov dx,1 ; beginning sector number mov bx,seg buff ; buffer address mov ds,bx mov bx,offset buff int 25h ; request disk read jc error ; jump if read failed add sp,2 ; clear stack . . . ──────────────────────────────────────────────────────────────────────────── Int 26H [1.0] Absolute disk write ──────────────────────────────────────────────────────────────────────────── Provides a direct linkage to the MS-DOS BIOS module to write data from memory to a logical disk sector. Call with: For access to partitions <= 32 MB AL = drive number (0 = A, 1 = B, etc) CX = number of sectors to write DX = starting sector number DS:BX = segment:offset of buffer For access to partitions > 32 MB (MS-DOS 4.0 and later) AL = drive number (0 = A, 1 = B, etc) CX = -1 DS:BX = segment:offset of parameter block (see Notes) Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AX = error code (see Notes) Notes: ■ All registers except the segment registers may be destroyed. ■ When this function returns, the CPU flags originally pushed onto the stack by the INT 26H instruction are still on the stack. The stack must be cleared by a POPF or ADD SP,2 to prevent uncontrolled stack growth and to make accessible any other values that were pushed on the stack before the call to INT 26H. ■ Logical sector numbers are obtained by numbering each disk sector sequentially from cylinder 0, head 0, sector 1, and continuing until the last sector on the disk is counted. The head number is incremented before the track number. Logically adjacent sectors may not be physically adjacent, due to interleaving that occurs at the device-adapter level for some disk types. ■ The error code is interpreted as follows: The lower byte (AL) is the same error code that is returned in the lower byte of DI when an Int 24H is issued. The upper byte (AH) contains: 01H if bad command 02H if bad address mark 03H if write-protect fault 04H if requested sector not found 08H if direct memory access (DMA) failure 10H if data error (bad CRC) 20H if controller failed 40H if seek operation failed 80H if attachment failed to respond ■ [4.0+] When accessing partitions larger than 32 MB under MS-DOS version 4, this function uses a parameter block with the following format: Bytes Description 00H─03H 32-bit sector number 04H─05H number of sectors to read 06H─07H offset of buffer 08H─09H segment of buffer Example: Write the contents of the memory area named buff into logical sector 3 of drive C. Warning: Verbatim use of the following code could damage the file system on your fixed disk. There is, unfortunately, no way to provide a really safe example of this function. buff db 512 dup (?) ; contains data for write . . . mov al,2 ; drive C mov cx,1 ; number of sectors mov dx,3 ; beginning sector number mov bx,seg buff ; buffer address mov ds,bx mov bx,offset buff int 26h ; request disk write jc error ; jump if write failed add sp,2 ; clear stack . . . ──────────────────────────────────────────────────────────────────────────── Int 27H [1.0] Terminate and stay resident ──────────────────────────────────────────────────────────────────────────── Terminates execution of the currently executing program, but reserves part or all of its memory so that it will not be overlaid by the next transient program to be loaded. MS-DOS then takes the following actions: ■ File buffers are flushed and any open handles for files or devices owned by the process are closed. ■ The termination handler vector (Int 22H) is restored from PSP:000AH. ■ The Ctrl-C handler vector (Int 23H) is restored from PSP:000EH. ■ [2.0+] The critical-error handler vector (Int 24H) is restored from PSP:0012H. ■ Control is transferred to the termination handler. If the program is returning to COMMAND.COM, control transfers to the resident portion and the transient portion is reloaded if necessary. If a batch file is in progress, the next line of the file is fetched and interpreted; otherwise a prompt is issued for the next user command. Call with: DX = offset of the last byte plus one (relative to the program segment prefix) of program to be protected CS = segment of program segment prefix Returns: Nothing Notes: ■ This function call is typically used to allow user-written utilities, drivers, or interrupt handlers to be loaded as ordinary .COM or .EXE programs, then remain resident. Subsequent entrance to the code is via a hardware or software interrupt. ■ This function attempts to set the initial memory allocation block to the length in bytes specified in register DX. If other memory blocks have been requested by the application via Int 21H Function 48H, they will not be released by this function. ■ Other methods of performing a final exit are: ∙ Int 20H ∙ Int 21H Function 00H ∙ Int 21H Function 31H ∙ Int 21H Function 4CH ■ This function should not be called by .EXE programs that are loaded at the high end of the transient program area (i.e., linked with the /HIGH switch), because doing so reserves the memory normally used by the transient part of COMMAND.COM. If COMMAND.COM cannot be reloaded, the system will fail. ■ This function does not work correctly when DX contains values in the range 0FFF1H─0FFFFH. In this case, MS-DOS discards the high bit of the value in DX, resulting in the reservation of 32 KB less memory than was requested by the program. ■ [2.0+] Int 21H Function 31H should be used in preference to this function, because it supports return codes, allows larger amounts of memory to be reserved, and does not require CS to contain the segment of the program segment prefix. ■ [3.0+] If the program is running on a network, it should remove all locks it has placed on file regions before terminating. Example: Terminate and stay resident, reserving enough memory to contain the entire program. . . . mov dx,offset pend ; DX = bytes to reserve int 27h ; terminate, stay resident . . . pend equ $ ; offset, end of program end ──────────────────────────────────────────────────────────────────────────── Int 28H Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 29H Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 2AH Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 2BH Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 2CH Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 2DH Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 2EH Reserved ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 2FH [3.0] Multiplex interrupt ──────────────────────────────────────────────────────────────────────────── Provides a general-purpose avenue of communication with another process or with MS-DOS extensions, such as the print spooler, ASSIGN, SHARE, and APPEND. The multiplex number in register AH specifies the process or extension being communicated with. The range 00H─BFH is reserved for MS-DOS; applications may use the range C0H─FFH. ──────────────────────────────────────────────────────────────────────────── Int 2FH [3.0] Function 01H Print spooler ──────────────────────────────────────────────────────────────────────────── Submits a file to the print spooler, removes a file from the print spooler's queue of pending files, or obtains the status of the printer. The print spooler, which is contained in the file PRINT.COM, was first added to MS-DOS in version 2.0, but the application program interface to the spooler was not documented until MS-DOS version 3. Call with: AH = 01H AL = subfunction 00H = Get Installed State 01H = Submit File to be Printed 02H = Remove File from Print Queue 03H = Cancel All Files in Queue 04H = Hold Print Jobs for Status Read 05H = Release Hold DS:DX = segment:offset of packet (Subfunction 01H) segment:offset of ASCIIZ pathname (Subfunction 02H) Returns: If function successful Carry flag = clear and, if called with AL = 00H AL = print spooler state 00H if not installed, ok to install 01H if not installed, not ok to install FFH if installed or, if called with AL = 04H DX = error count DS:SI = segment:offset of print queue file list If function unsuccessful Carry flag = set AX = error code Notes: ■ The packet passed to Subfunction 01H consists of five bytes. The first byte contains the level, which should be 00H for current versions of MS-DOS. The following four bytes contain the segment:offset of an ASCIIZ pathname, which may not include wildcard characters. If the specified file exists, it is added to the print queue. ■ The * and ? wildcard characters may be included in a pathname passed to Subfunction 02H, making it possible to delete multiple files from the print queue with one call. ■ The address returned by Subfunction 04H points to a list of 64-byte entries, each containing an ASCIIZ pathname. The first pathname in the list is the file currently being printed. The last entry in the list is a null string (a single 00H byte). ──────────────────────────────────────────────────────────────────────────── Int 2FH [3.2] Function 02H ASSIGN ──────────────────────────────────────────────────────────────────────────── Returns a code indicating whether the resident portion of the ASSIGN utility has been loaded. Call with: AH = 02H AL = subfunction 00H = Get Installed State Returns: If function successful Carry flag = clear AL = ASSIGN installed status 00H if not installed, ok to install 01H if not installed, not ok to install FFH if installed If function unsuccessful Carry flag = set AX = error code ──────────────────────────────────────────────────────────────────────────── Int 2FH [3.2] Function 10H (16) SHARE ──────────────────────────────────────────────────────────────────────────── Returns a code indicating whether the SHARE.EXE file-sharing module has been loaded. Call with: AH = 10H AL = subfunction 00H = Get Installed State Returns: If function successful Carry flag = clear AL = SHARE installed status 00H if not installed, ok to install 01H if not installed, not ok to install FFH if installed If function unsuccessful Carry flag = set AX = error code ──────────────────────────────────────────────────────────────────────────── Int 2FH [3.3] Function B7H (183) APPEND ──────────────────────────────────────────────────────────────────────────── Allows an application to test whether APPEND has been installed. If APPEND is resident, returns the APPEND version, state, and the path used to search for data files. Call with: AH = B7H AL = subfunction 00H = Get Installed State 02H = Get Append Version (4.0) 04H = Get Append Path Pointer (4.0) 06H = Get Append Function State (4.0) 07H = Set Append Function State (4.0) 11H = Set Return Found Name State (4.0, see Note) BX = APPEND state (if AL = 07H) Bit(s) Significance (if set) 0 APPEND enabled 1─12 Reserved (0) 13 /PATH switch active 14 /E switch active 15 /X switch active Returns: If function successful Carry flag = clear and, if called with AL = 00H AL = APPEND installed status 00H if not installed, ok to install 01H if not installed, not ok to install FFH if installed or, if called with AL = 02H (MS-DOS 4.0) AX = FFFFH if MS-DOS 4.0 APPEND or, if called with AL = 04H (MS-DOS 4.0) ES:DI = segment:offset of active APPEND path or, if called with AL = 06H (MS-DOS 4.0) BX = APPEND state (see above) If function unsuccessful Carry flag = set AX = error code Note: ■ If the Return Found Name State is set with Subfunction 11H, the fully qualified filename is returned to the next application to call Int 21H Function 3DH, 43H, or 6CH. The name is placed at the same address as the ASCIIZ parameter string for the Int 21H function, so the application must be sure to provide a buffer of adequate size. The Return Found Name State is reset after APPEND processes one Int 21H function call. ──────────────────────────────────────────────────────────────────────────── SECTION 3 IBM ROM BIOS AND MOUSE FUNCTIONS REFERENCE ──────────────────────────────────────────────────────────────────────────── Notes to the Reader In the headers for ROM BIOS video driver (Int 10H) function calls, the following icons are used: [MDA] Monochrome Display Adapter [CGA] Color/Graphics Adapter [PCjr] PCjr system board video controller [EGA] Enhanced Graphics Adapter [MCGA] Multi-Color Graphics Array (PS/2 Models 25 & 30) [VGA] Video Graphics Array (PS/2 Models 50 and above) In the remainder of this section, the following icons are used: [PC] Original IBM PC, PC/XT, and PCjr, unless otherwise noted. [AT] PC/AT and PC/XT-286, unless otherwise noted. [PS/2] All PS/2 models (including Models 25 and 30), unless otherwise noted. ROM BIOS functions that are unique to the PC Convertible have been omitted. Some functions are supported only in very late revisions of a particular machine's ROM BIOS (such as Int 1AH Functions 00H and 01H on the PC/XT). In general, such functions are not given an icon for that machine since a program could not safely assume that they were available based on the machine ID byte(s). Summary of ROM BIOS and Mouse Function Calls ╓┌─┌──────┌────────────┌─────────────┌───────────────────────────────────────╖ Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 10H Video Driver 10H 00H Set Video Mode 10H 01H Set Cursor Type 10H 02H Set Cursor Position 10H 03H Get Cursor Position 10H 04H Get Light Pen Position 10H 05H Set Display Page 10H 06H Initialize or Scroll Window Up 10H 07H Initialize or Scroll Window Down 10H 08H Read Character and Attribute at Cursor 10H 09H Write Character and Attribute at Cursor 10H 0AH (10) Write Character at Cursor Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 10H 0AH (10) Write Character at Cursor 10H 0BH (11) Set Palette, Background, or Border 10H 0CH (12) Write Graphics Pixel 10H 0DH (13) Read Graphics Pixel 10H 0EH (14) Write Character in Teletype Mode 10H 0FH (15) Get Video Mode 10H 10H (16) 00H Set Palette Register 10H 10H (16) 01H Set Border Color 10H 10H (16) 02H Set Palette and Border 10H 10H (16) 03H Toggle Blink/Intensity Bit 10H 10H (16) 07H Get Palette Register 10H 10H (16) 08H Get Border Color 10H 10H (16) 09H Get Palette and Border 10H 10H (16) 10H (16) Set Color Register 10H 10H (16) 12H (18) Set Block of Color Registers 10H 10H (16) 13H (19) Set Color Page State 10H 10H (16) 15H (21) Get Color Register 10H 10H (16) 17H (23) Get Block of Color Registers 10H 10H (16) 1AH (26) Get Color Page State Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 10H 10H (16) 1AH (26) Get Color Page State 10H 10H (16) 1BH (27) Set Gray-Scale Values 10H 11H (17) 00H Load User Font 10H 11H (17) 01H Load ROM 8-by-14 Font 10H 11H (17) 02H Load ROM 8-by-8 Font 10H 11H (17) 03H Set Block Specifier 10H 11H (17) 04H Load ROM 8-by-16 Font 10H 11H (17) 10H (16) Load User Font, Reprogram Controller 10H 11H (17) 11H (17) Load ROM 8-by-14 Font, Reprogram Controller 10H 11H (17) 12H (18) Load ROM 8-by-8 Font, Reprogram Controller 10H 11H (17) 14H (20) Load ROM 8-by-16 Font, Reprogram Controller 10H 11H (17) 20H (32) Set Int 1FH Pointer 10H 11H (17) 21H (33) Set Int 43H for User's Font 10H 11H (17) 22H (34) Set Int 43H for ROM 8-by-14 Font 10H 11H (17) 23H (35) Set Int 43H for ROM 8-by-8 Font 10H 11H (17) 24H (36) Set Int 43H for Rom 8-by-16 Font Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 10H 11H (17) 24H (36) Set Int 43H for Rom 8-by-16 Font 10H 11H (17) 30H (48) Get Font Information 10H 12H (18) 10H (16) Get Configuration Information 10H 12H (18) 20H (32) Select Alternate PrintScreen 10H 12H (18) 30H (48) Set Scan Lines 10H 12H (18) 31H (49) Enable/Disable Palette Loading 10H 12H (18) 32H (50) Enable/Disable Video 10H 12H (18) 33H (51) Enable/Disable Gray-Scale Summing 10H 12H (18) 34H (52) Enable/Disable Cursor Emulation 10H 12H (18) 35H (53) Switch Active Display 10H 12H (18) 36H (54) Enable/Disable Screen Refresh 10H 13H (19) Write String in Teletype Mode 10H 1AH (26) Get or Set Display Combination Code 10H 1BH (27) Get Functionality/State Information 10H 1CH (28) Save or Restore Video State 11H Get Equipment Configuration 12H Get Conventional Memory Size 13H Disk Driver 13H 00H Reset Disk System Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 13H 00H Reset Disk System 13H 01H Get Disk System Status 13H 02H Read Sector 13H 03H Write Sector 13H 04H Verify Sector 13H 05H Format Track 13H 06H Format Bad Track 13H 07H Format Drive 13H 08H Get Drive Parameters 13H 09H Initialize Fixed Disk Characteristics 13H 0AH (10) Read Sector Long 13H 0BH (11) Write Sector Long 13H 0CH (12) Seek 13H 0DH (13) Reset Fixed Disk System 13H 0EH (14) Read Sector Buffer 13H 0FH (15) Write Sector Buffer 13H 10H (16) Get Drive Status 13H 11H (17) Recalibrate Drive 13H 12H (18) Controller RAM Diagnostic Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 13H 12H (18) Controller RAM Diagnostic 13H 13H (19) Controller Drive Diagnostic 13H 14H (20) Controller Internal Diagnostic 13H 15H (21) Get Disk Type 13H 16H (22) Get Disk Change Status 13H 17H (23) Set Disk Type 13H 18H (24) Set Media Type for Format 13H 19H (25) Park Heads 13H 1AH (26) Format ESDI Drive 14H Serial Communications Port Driver 14H 00H Initialize Communications Port 14H 01H Write Character to Communications Port 14H 02H Read Character from Communications Port 14H 03H Get Communications Port Status 14H 04H Extended Initialize Communications Port 14H 05H Extended Communications Port Control 15H I/O Subsystem Extensions 15H 00H Turn On Cassette Motor 15H 01H Turn Off Cassette Motor Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 15H 01H Turn Off Cassette Motor 15H 02H Read Cassette 15H 03H Write Cassette 15H 0FH (15) Format ESDI Drive Periodic Interrupt 15H 21H (33) 00H Read POST Error Log 15H 21H (33) 01H Write POST Error Log 15H 4FH (79) Keyboard Intercept 15H 80H (128) Device Open 15H 81H (129) Device Close 15H 82H (130) Process Termination 15H 83H (131) Event Wait 15H 84H (132) Read Joystick 15H 85H (133) SysReq Key 15H 86H (134) Delay 15H 87H (135) Move Extended Memory Block 15H 88H (136) Get Extended Memory Size 15H 89H (137) Enter Protected Mode 15H 90H (144) Device Wait 15H 91H (145) Device Post Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 15H 91H (145) Device Post 15H C0H (192) Get System Environment 15H C1H (193) Get Address of Extended BIOS Data Area 15H C2H (194) 00H Enable/Disable Pointing Device 15H C2H (194) 01H Reset Pointing Device 15H C2H (194) 02H Set Sample Rate 15H C2H (194) 03H Set Resolution 15H C2H (194) 04H Get Pointing Device Type 15H C2H (194) 05H Initialize Pointing Device Interface 15H C2H (194) 06H Set Scaling or Get Status 15H C2H (194) 07H Set Pointing Device Handler Address 15H C3H (195) Set Watchdog Time-Out 15H C4H (196) Programmable Option Select 16H Keyboard Driver 16H 00H Read Character from Keyboard 16H 01H Get Keyboard Status 16H 02H Get Keyboard Flags 16H 03H Set Repeat Rate 16H 04H Set Keyclick Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 16H 04H Set Keyclick 16H 05H Push Character and Scan Code 16H 10H (16) Read Character from Enhanced Keyboard 16H 11H (17) Get Enhanced Keyboard Status 16H 12H (18) Get Enhanced Keyboard Flags 17H Parallel Port Printer Driver 17H 00H Write Character to Printer 17H 01H Initialize Printer Port 17H 02H Get Printer Status 18H ROM BASIC 19H Reboot System 1AH Real-time (CMOS) Clock Driver 1AH 00H Get Tick Count 1AH 01H Set Tick Count 1AH 02H Get Time 1AH 03H Set Time 1AH 04H Get Date 1AH 05H Set Date 1AH 06H Set Alarm Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 1AH 06H Set Alarm 1AH 07H Reset Alarm 1AH 0AH (10) Get Day Count 1AH 0BH (11) Set Day Count 1AH 80H (128) Set Sound Source 33H Microsoft Mouse Driver 33H 00H Reset Mouse and Get Status 33H 01H Show Mouse Pointer 33H 02H Hide Mouse Pointer 33H 03H Get Mouse Position and Button Status 33H 04H Set Mouse Pointer Position 33H 05H Get Button Press Information 33H 06H Get Button Release Information 33H 07H Set Horizontal Limits for Pointer 33H 08H Set Vertical Limits for Pointer 33H 09H Set Graphics Pointer Shape 33H 0AH (10) Set Text Pointer Type 33H 0BH (11) Read Mouse Motion Counters 33H 0CH (12) Set User-defined Mouse Event Handler Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 33H 0CH (12) Set User-defined Mouse Event Handler 33H 0DH (13) Turn On Light Pen Emulation 33H 0EH (14) Turn Off Light Pen Emulation 33H 0FH (15) Set Mickeys to Pixels Ratio 33H 10H (16) Set Mouse Pointer Exclusion Area 33H 13H (19) Set Double Speed Threshold 33H 14H (20) Swap User-defined Mouse Event Handlers 33H 15H (21) Get Mouse Save State Buffer Size 33H 16H (22) Save Mouse Driver State 33H 17H (23) Restore Mouse Driver State 33H 18H (24) Set Alternate Mouse Event Handler 33H 19H (25) Get Address of Alternate Mouse Event Handler 33H 1AH (26) Set Mouse Sensitivity 33H 1BH (27) Get Mouse Sensitivity 33H 1CH (28) Set Mouse Interrupt Rate 33H 1DH (29) Select Pointer Page 33H 1EH (30) Get Pointer Page 33H 1FH (31) Disable Mouse Driver Int Function Subfunction Name ────────────────────────────────────────────────────────────────────────── 33H 1FH (31) Disable Mouse Driver 33H 20H (32) Enable Mouse Driver 33H 21H (33) Reset Mouse Driver 33H 22H (34) Set Language for Mouse Driver Messages 33H 23H (35) Get Language Number 33H 24H (36) Get Mouse Information ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 00H Set video mode ──────────────────────────────────────────────────────────────────────────── Selects the current video display mode. Also selects the active video controller, if more than one video controller is present. Call with: AH = 00H AL = video mode (see Notes) Returns: Nothing Notes: ■ The video modes applicable to the various IBM machine models and video adapters are as follows: ╓┌─┌─────┌───────────┌────────┌───────────┌─────┌─────┌────┌─────┌─────┌─────╖ Mode Resolution Colors Text/ MDA CGA PCjr EGA MCGA VGA graphics ────────────────────────────────────────────────────────────────────────── 00H 40-by-25 16 text * * * * * color burst off Mode Resolution Colors Text/ MDA CGA PCjr EGA MCGA VGA graphics ────────────────────────────────────────────────────────────────────────── off 01H 40-by-25 16 text * * * * * 02H 80-by-25 16 text * * * * * color burst off 03H 80-by-25 16 text * * * * * 04H 320-by-200 4 graphics * * * * * 05H 320-by-200 4 graphics * * * * * color burst off 06H 640-by-200 2 graphics * * * * * 07H 80-by-25 2☼ text * * * 08H 160-by-200 16 graphics * 09H 320-by-200 16 graphics * 0AH 640-by-200 4 graphics * 0BH reserved 0CH reserved 0DH 320-by-200 16 graphics * * Mode Resolution Colors Text/ MDA CGA PCjr EGA MCGA VGA graphics ────────────────────────────────────────────────────────────────────────── 0DH 320-by-200 16 graphics * * 0EH 640-by-200 16 graphics * * 0FH 640-by-350 2☼ graphics * * 10H 640-by-350 4 graphics *☼ 10H 640-by-350 16 graphics *☼ * 11H 640-by-480 2 graphics * * 12H 640-by-480 16 graphics * 13H 320-by-200 256 graphics * * ────────────────────────────────────────────────────────────────────────── ■ The presence or absence of color burst is only significant when a composite monitor is being used. For RGB monitors, there is no functional difference between modes 00H and 01H or modes 02H and 03H. On the CGA, two palettes are available in mode 04H and one in mode 05H. ■ On the PC/AT, PCjr, and PS/2, if bit 7 of AL is set, the display buffer is not cleared when a new mode is selected. On the PC or PC/XT, this capability is available only when an EGA or VGA (which have their own ROM BIOS) is installed. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 01H Set cursor type ──────────────────────────────────────────────────────────────────────────── Selects the starting and ending lines for the blinking hardware cursor in text display modes. Call with: AH = 01H CH bits 0─4 = starting line for cursor CL bits 0─4 = ending line for cursor Returns: Nothing Notes: ■ In text display modes, the video hardware causes the cursor to blink, and the blink cannot be disabled. In graphics modes, the hardware cursor is not available. ■ The default values set by the ROM BIOS are: Display Start End ──────────────────────────────────────────────────────────────────────── monochrome mode 07H 11 12 text modes 00H─03H 6 7 ──────────────────────────────────────────────────────────────────────── ■ On the EGA, MCGA, and VGA in text modes 00H─03H, the ROM BIOS accepts cursor start and end values as though the character cell were 8 by 8 and remaps the values as appropriate for the true character cell dimensions. This mapping is called cursor emulation. ■ You can turn off the cursor in several ways. On the MDA, CGA, and VGA, setting register CH = 20H causes the cursor to disappear. Techniques that involve setting illegal starting and ending lines for the current display mode are unreliable. An alternative is to position the cursor to a nondisplayable address, such as (x,y)=(0,25). ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 02H Set cursor position ──────────────────────────────────────────────────────────────────────────── Positions the cursor on the display, using text coordinates. Call with: AH = 02H BH = page DH = row (y coordinate) DL = column (x coordinate) Returns: Nothing Notes: ■ A separate cursor is maintained for each display page, and each can be set independently with this function regardless of the currently active page. The number of available display pages depends on the video adapter and current display mode. See Int 10H Function 05H. ■ Text coordinates (x,y)=(0,0) are the upper left corner of the screen. ■ The maximum value for each text coordinate depends on the video adapter and current display mode, as follows: Mode Maximum x Maximum y ──────────────────────────────────────────────────────────────────────── 00H 39 24 01H 39 24 02H 79 24 03H 79 24 04H 39 24 05H 39 24 06H 79 24 07H 79 24 08H 19 24 09H 39 24 0AH 79 24 0BH reserved 0CH reserved 0DH 39 24 0EH 79 24 0FH 79 24 10H 79 24 11H 79 29 12H 79 29 13H 39 24 ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 03H Get cursor position ──────────────────────────────────────────────────────────────────────────── Obtains the current position of the cursor on the display, in text coordinates. Call with: AH = 03H BH = page Returns: CH = starting line for cursor CL = ending line for cursor DH = row (y coordinate) DL = column (x coordinate) Note: ■ A separate cursor is maintained for each display page, and each can be inspected independently with this function regardless of the currently active page. The number of available display pages depends on the video adapter and current display mode. See Int 10H Function 05H. ──────────────────────────────────────────────────────────────────────────── Int 10H [CGA] [PCjr] [EGA] Function 04H Get light pen position ──────────────────────────────────────────────────────────────────────────── Obtains the current status and position of the light pen. Call with: AH = 04H Returns: AH = 00H if light pen not down/not triggered 01H if light pen down/triggered BX = pixel column (graphics x coordinate) CH = pixel row (graphics y coordinate, modes 04H─06H) CX = pixel row (graphics y coordinate, modes 0DH─13H) DH = character row (text y coordinate) DL = character column (text x coordinate) Notes: ■ The range of text and graphics coordinates returned by this function depends on the current display mode. ■ On the CGA, the graphics coordinates returned by this function are not continuous. The y coordinate is always a multiple of two; the x coordinate is either a multiple of four (for 320-by-200 graphics modes) or a multiple of eight (for 640-by-200 graphics modes). ■ Careful selection of background and foreground colors is necessary to obtain maximum sensitivity from the light pen across the full screen width. ──────────────────────────────────────────────────────────────────────────── Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 05H Set display page ──────────────────────────────────────────────────────────────────────────── Selects the active display page for the video display. Call with: For CGA, EGA, MCGA, VGA AH = 05H AL = page 0─7 for modes 00H and 01H (CGA, EGA, MCGA, VGA) 0─3 for modes 02H and 03H (CGA) 0─7 for modes 02H and 03H (EGA, MCGA, VGA) 0─7 for mode 07H (EGA, VGA) 0─7 for mode 0DH (EGA, VGA) 0─3 for mode 0EH (EGA, VGA) 0─1 for mode 0FH (EGA, VGA) 0─1 for mode 10H (EGA, VGA) For PCjr only AH = 05H AL = subfunction 80H = read CRT/CPU page registers 81H = set CPU page register 82H = set CRT page register 83H = set both CPU and CRT page registers BH = CRT page (Subfunctions 82H and 83H) BL = CPU page (Subfunctions 81H and 83H) Returns: If CGA, EGA, MCGA, or VGA adapter Nothing If PCjr and if function called with AL = 80H─83H BH = CRT page register BL = CPU page register Notes: ■ Video mode and adapter combinations not listed above support one display page (for example, a Monochrome Adapter in mode 7). ■ Switching between pages does not affect their contents. In addition, text can be written to any video page with Int 10H Functions 02H, 09H, and 0AH, regardless of the page currently being displayed. ■ On the PCjr, the CPU page determines the part of the physical memory region 00000H─1FFFFH that will be hardware mapped onto 16 KB of memory beginning at segment B800H. The CRT page determines the starting address of the physical memory used by the video controller to refresh the display. Smooth animation effects can be achieved by manipulation of these registers. Programs that write directly to the B800H segment can reach only the first 16 KB of the video refresh buffer. Programs requiring direct access to the entire 32 KB buffer in modes 09H and 0AH can obtain the current CRT page from the ROM BIOS variable PAGDAT at 0040:008AH. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 06H Initialize or scroll window up ──────────────────────────────────────────────────────────────────────────── Initializes a specified window of the display to ASCII blank characters with a given attribute or scrolls up the contents of a window by a specified number of lines. Call with: AH = 06H AL = number of lines to scroll (if zero, entire window is blanked) BH = attribute to be used for blanked area CH = y coordinate, upper left corner of window CL = x coordinate, upper left corner of window DH = y coordinate, lower right corner of window DL = x coordinate, lower right corner of window Returns: Nothing Notes: ■ In video modes that support multiple pages, this function affects only the page currently being displayed. ■ If AL contains a value other than 00H, the area within the specified window is scrolled up by the requested number of lines. Text that is scrolled beyond the top of the window is lost. The new lines that appear at the bottom of the window are filled with ASCII blanks carrying the attribute specified by register BH. ■ To scroll down the contents of a window, see Int 10H Function 07H. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 07H Initialize or scroll window down ──────────────────────────────────────────────────────────────────────────── Initializes a specified window of the display to ASCII blank characters with a given attribute, or scrolls down the contents of a window by a specified number of lines. Call with: AH = 07H AL = number of lines to scroll (if zero, entire window is blanked) BH = attribute to be used for blanked area CH = y coordinate, upper left corner of window CL = x coordinate, upper left corner of window DH = y coordinate, lower right corner of window DL = x coordinate, lower right corner of window Returns: Nothing Notes: ■ In video modes that support multiple pages, this function affects only the page currently being displayed. ■ If AL contains a value other than 00H, the area within the specified window is scrolled down by the requested number of lines. Text that is scrolled beyond the bottom of the window is lost. The new lines that appear at the top of the window are filled with ASCII blanks carrying the attribute specified by register BH. ■ To scroll up the contents of a window, see Int 10H Function 06H. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 08H Read character and attribute at cursor ──────────────────────────────────────────────────────────────────────────── Obtains the ASCII character and its attribute at the current cursor position for the specified display page. Call with: AH = 08H BH = page Returns: AH = attribute AL = character Note: ■ In video modes that support multiple pages, characters and their attributes may be read from any page, regardless of the page currently being displayed. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 09H Write character and attribute at cursor ──────────────────────────────────────────────────────────────────────────── Writes an ASCII character and its attribute to the display at the current cursor position. Call with: AH = 09H AL = character BH = page BL = attribute (text modes) or color (graphics modes) CX = count of characters to write (replication factor) Returns: Nothing Notes: ■ In graphics modes, the replication factor in CX produces a valid result only for the current row. If more characters are written than there are remaining columns in the current row, the result is unpredictable. ■ All values of AL result in some sort of display; control characters, including bell, backspace, carriage return, and line feed, are not recognized as special characters and do not affect the cursor position. ■ After a character is written, the cursor must be moved explicitly with Int 10H Function 02H to the next position. ■ To write a character without changing the attribute at the current cursor position, use Int 10H Function 0AH. ■ If this function is used to write characters in graphics mode and bit 7 of BL is set (1), the character will be exclusive-OR'd (XOR) with the current display contents. This feature can be used to write characters and then "erase" them. ■ For the CGA and PCjr in graphics modes 04H─06H, the bit patterns for character codes 80H─FFH are obtained from a table whose address is stored in the vector for Int 1FH. On the PCjr, the address of the table for character codes 00H─7FH is stored in the vector for Int 44H. Alternative character sets may be installed by loading them into memory and updating this vector. ■ For the EGA, MCGA, and VGA in graphics modes, the address of the character definition table is stored in the vector for Int 43H. See Int 10H Function 11H. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 0AH (10) Write character at cursor ──────────────────────────────────────────────────────────────────────────── Writes an ASCII character to the display at the current cursor position. The character receives the attribute of the previous character displayed at the same position. Call with: AH = 0AH AL = character BH = page BL = color (graphics modes, PCjr only) CX = count of characters to write (replication factor) Returns: Nothing Notes: ■ In graphics modes, the replication factor in CX produces a valid result only for the current row. If more characters are written than there are remaining columns in the current row, the result is unpredictable. ■ All values of AL result in some sort of display; control characters, including bell, backspace, carriage return, and line feed, are not recognized as special characters and do not affect the cursor position. ■ After a character is written, the cursor must be moved explicitly with Int 10H Function 02H to the next position. ■ To write a character and attribute at the current cursor position, use Int 10H Function 09H. ■ If this function is used to write characters in graphics mode and bit 7 of BL is set (1), the character will be exclusive-OR'd (XOR) with the current display contents. This feature can be used to write characters and then "erase" them. ■ For the CGA and PCjr in graphics modes 04H─06H, the bit patterns for character codes 80H─FFH are obtained from a table whose address is stored in the vector for Int 1FH. On the PCjr, the address of the table for character codes 00H─7FH is stored in the vector for Int 44H. Alternative character sets may be installed by loading them into memory and updating this vector. ■ For the EGA, MCGA, and VGA in graphics modes, the address of the character definition table is stored in the vector for Int 43H. See Int 10H Function 11H. ──────────────────────────────────────────────────────────────────────────── Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 0BH (11) Set palette, background, or border ──────────────────────────────────────────────────────────────────────────── Selects a palette, background, or border color. Call with: To set the background color and border color for graphics modes or the border color for text modes AH = 0BH BH = 00H BL = color To select the palette (320-by-200 4-color graphics modes) AH = 0BH BH = 01H BL = palette (see Notes) Returns: Nothing Notes: ■ In text modes, this function selects only the border color. The background color of each individual character is controlled by the upper 4 bits of that character's attribute byte. ■ On the CGA and EGA, this function is valid for palette selection only in 320-by-200 4-color graphics modes. ■ In 320-by-200 4-color graphics modes, if register BH = 01H, the following palettes may be selected: Palette Pixel value Color ──────────────────────────────────────────────────────────────────────── 0 0 same as background 1 green 2 red 3 brown or yellow 1 0 same as background 1 cyan 2 magenta 3 white ──────────────────────────────────────────────────────────────────────── ■ On the CGA in 640-by-200 2-color graphics mode, the background color selected with this function actually controls the display color for nonzero pixels; zero pixels are always displayed as black. ■ On the PCjr in 640-by-200 2-color graphics mode, if BH = 00H and bit 0 of register BL is cleared, pixel value 1 is displayed as white; if bit 0 is set, pixel value 1 is displayed as black. ■ See also Int 10H Function 10H, which is used for palette programming on the PCjr, EGA, MCGA, and VGA. ──────────────────────────────────────────────────────────────────────────── Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 0CH (12) Write graphics pixel ──────────────────────────────────────────────────────────────────────────── Draws a point on the display at the specified graphics coordinates. Call with: AH = 0CH AL = pixel value BH = page CX = column (graphics x coordinate) DX = row (graphics y coordinate) Returns: Nothing Notes: ■ The range of valid pixel values and (x,y) coordinates depends on the current video mode. ■ If bit 7 of AL is set, the new pixel value will be exclusive-OR'd (XOR) with the current contents of the pixel. ■ Register BH is ignored for display modes that support only one page. ──────────────────────────────────────────────────────────────────────────── Int 10H [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 0DH (13) Read graphics pixel ──────────────────────────────────────────────────────────────────────────── Obtains the current value of the pixel on the display at the specified graphics coordinates. Call with: AH = 0DH BH = page CX = column (graphics x coordinate) DX = row (graphics y coordinate) Returns: AL = pixel value Notes: ■ The range of valid (x,y) coordinates and possible pixel values depends on the current video mode. ■ Register BH is ignored for display modes that support only one page. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 0EH (14) Write character in teletype mode ──────────────────────────────────────────────────────────────────────────── Writes an ASCII character to the display at the current cursor position, using the specified color (if in graphics modes), and then increments the cursor position appropriately. Call with: AH = 0EH AL = character BH = page BL = foreground color (graphics modes) Returns: Nothing Notes: ■ The special ASCII codes for bell (07H), backspace (08H), carriage return (0DH), and line feed (0AH) are recognized, and the appropriate action is taken. All other characters are written to the display (even if they are control characters), and the cursor is moved to the next position. ■ In video modes that support multiple pages, characters can be written to any page, regardless of the page currently being displayed. ■ Line wrapping and scrolling are provided. If the cursor is at the end of a line, it is moved to the beginning of the next line. If the cursor reaches the end of the last line on the screen, the screen is scrolled up by one line and the cursor is placed at the beginning of a new blank line. The attribute for the entire new line is taken from the last character that was written on the preceding line. ■ The default MS-DOS console driver (CON) uses this function to write text to the screen. You cannot use this function to specify the attribute of a character. One method of writing a character to the screen with a specific attribute is to first write an ASCII blank (20H) with the desired attribute at the current cursor location using Int 10H Function 09H and then write the actual character with Int 10H Function 0EH. This technique, although somewhat clumsy, does not require the program to explicitly handle line wrapping and scrolling. ■ See also Int 10H Function 13H. ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 0FH (15) Get video mode ──────────────────────────────────────────────────────────────────────────── Obtains the current display mode of the active video controller. Call with: AH = 0FH Returns: AH = number of character columns on screen AL = display mode (see Int 10H Function 00H) BH = active display page Note: ■ This function can be called to obtain the screen width before clearing the screen with Int 10H Functions 06H or 07H. ──────────────────────────────────────────────────────────────────────────── Int 10H [PCjr] [EGA] [MCGA] [VGA] Function 10H (16) Subfunction 00H Set palette register ──────────────────────────────────────────────────────────────────────────── Sets the correspondence of a palette register to a displayable color. Call with: On the PCjr, EGA, or VGA AH = 10H AL = 00H BH = color value BL = palette register (00─0FH) On the MCGA AH = 10H AL = 00H BX = 0712H Returns: Nothing Note: ■ On the MCGA, this function can only be called with BX = 0712H and selects a color register set with eight consistent colors. ──────────────────────────────────────────────────────────────────────────── Int 10H [PCjr] [EGA] [VGA] Function 10H (16) Subfunction 01H Set border color ──────────────────────────────────────────────────────────────────────────── Controls the color of the screen border (overscan). Call with: AH = 10H AL = 01H BH = color value Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 10H [PCjr] [EGA] [VGA] Function 10H (16) Subfunction 02H Set palette and border ──────────────────────────────────────────────────────────────────────────── Sets all palette registers and the border color (overscan) in one operation. Call with: AH = 10H AL = 02H ES:DX = segment:offset of color list Returns: Nothing Notes: ■ The color list is 17 bytes long. The first 16 bytes are the color values to be loaded into palette registers 0─15, and the last byte is stored in the border color register. ■ In 16-color graphics modes, the following default palette is set up: Pixel value Color ──────────────────────────────────────────────────────────────────────── 01H blue 02H green 03H cyan 04H red 05H magenta 06H brown 07H white 08H gray 09H light blue 0AH light green 0BH light cyan 0CH light red 0DH light magenta 0EH yellow 0FH intense white ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 10H [PCjr] [EGA] [MCGA] [VGA] Function 10H (16) Subfunction 03H Toggle blink/intensity bit ──────────────────────────────────────────────────────────────────────────── Determines whether the most significant bit of a character attribute will select blinking or intensified display. Call with: AH = 10H AL = 03H BL = blink/intensity toggle 0 = enable intensity 1 = enable blinking Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 10H (16) Subfunction 07H Get palette register ──────────────────────────────────────────────────────────────────────────── Returns the color associated with the specified palette register. Call with: AH = 10H AL = 07H BL = palette register Returns: BH = color ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 10H (16) Subfunction 08H Get border color ──────────────────────────────────────────────────────────────────────────── Returns the current border color (overscan). Call with: AH = 10H AL = 08H Returns: BH = color ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 10H (16) Subfunction 09H Get palette and border ──────────────────────────────────────────────────────────────────────────── Gets the contents of all palette registers and the border color (overscan) in one operation. Call with: AH = 10H AL = 09H ES:DX = segment:offset of 17-byte buffer Returns: ES:DX = segment:offset of buffer and buffer contains palette values in bytes 00H─0FH and border color in byte 10H. ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 10H (16) Subfunction 10H (16) Set color register ──────────────────────────────────────────────────────────────────────────── Programs an individual color register with a red-green-blue (RGB) combination. Call with: AH = 10H AL = 10H BX = color register CH = green value CL = blue value DH = red value Returns: Nothing Note: ■ If gray-scale summing is enabled, the weighted gray-scale value is calculated as described under Int 10H Function 10H Subfunction 1BH and is stored into all three components of the color register. See also Int 10H Function 12H Subfunction 33H. ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 10H (16) Subfunction 12H (18) Set block of color registers ──────────────────────────────────────────────────────────────────────────── Programs a group of consecutive color registers in one operation. Call with: AH = 10H AL = 12H BX = first color register CX = number of color registers ES:DX = segment:offset of color table Returns: Nothing Notes: ■ The table consists of a series of 3-byte entries, one entry per color register to be programmed. The bytes of an individual entry specify the red, green, and blue values (in that order) for the associated color register. ■ If gray-scale summing is enabled, the weighted gray-scale value for each register is calculated as described under Int 10H Function 10H Subfunction 1BH and is stored into all three components of the color register. See also Int 10H Function 12H Subfunction 33H. ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 10H (16) Subfunction 13H (19) Set color page state ──────────────────────────────────────────────────────────────────────────── Selects the paging mode for the color registers, or selects an individual page of color registers. Call with: To select the paging mode AH = 10H AL = 13H BH = paging mode 00H for 4 pages of 64 registers 01H for 16 pages of 16 registers BL = 00H To select a color register page AH = 10H AL = 13H BH = page BL = 01H Returns: Nothing Note: ■ This function is not valid in mode 13H (320-by-200 256-color graphics). ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 10H (16) Subfunction 15H (21) Get color register ──────────────────────────────────────────────────────────────────────────── Returns the contents of a color register as its red, green, and blue components. Call with: AH = 10H AL = 15H BX = color register Returns: CH = green value CL = blue value DH = red value ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 10H (16) Subfunction 17H (23) Get block of color registers ──────────────────────────────────────────────────────────────────────────── Allows the red, green, and blue components associated with each of a set of color registers to be read in one operation. Call with: AH = 10H AL = 17H BX = first color register CX = number of color registers ES:DX = segment:offset of buffer to receive color list Returns: ES:DX = segment:offset of buffer and buffer contains color list Note: ■ The color list returned in the caller's buffer consists of a series of 3-byte entries corresponding to the color registers. Each 3-byte entry contains the register's red, green, and blue components in that order. ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 10H (16) Subfunction 1AH (26) Get color page state ──────────────────────────────────────────────────────────────────────────── Returns the color register paging mode and current color page. Call with: AH = 10H AL = 1AH Returns: BH = color page BL = paging mode 00H if 4 pages of 64 registers 01H if 16 pages of 16 registers Note: ■ See Int 10H Function 10H Subfunction 13H, which allows selection of the paging mode or current color page. ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 10H (16) Subfunction 1BH (27) Set gray-scale values ──────────────────────────────────────────────────────────────────────────── Transforms the red, green, and blue values of one or more color registers into the gray-scale equivalents. Call with: AH = 10H AL = 1BH BX = first color register CX = number of color registers Returns: Nothing Note: ■ For each color register, the weighted sum of its red, green, and blue values is calculated (30% red + 59% green + 11% blue) and written back into all three components of the color register. The original red, green, and blue values are lost. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunctions 00H and 10H (16) Load user font ──────────────────────────────────────────────────────────────────────────── Loads the user's font (character definition) table into the specified block of character generator RAM. Call with: AH = 11H AL = 00H or 10H (see Notes) BH = points (bytes per character) BL = block CX = number of characters defined by table DX = first character code in table ES:BP = segment:offset of font table Returns: Nothing Notes: ■ This function provides font selection in text (alphanumeric) display modes. For font selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Subfunctions 20H─24H. ■ If AL = 10H, page 0 must be active. The points (bytes per character), rows, and length of the refresh buffer are recalculated. The controller is reprogrammed with the maximum scan line (points - 1), cursor start (points - 2), cursor end (points - 1), vertical display end ((rows*points) - 1), and underline location (points - 1, mode 7 only). If Subfunction 10H is called at any time other than immediately after a mode set, the results are unpredictable. ■ On the MCGA, a Subfunction 00H call should be followed by a Subfunction 03H call so that the ROM BIOS will load the font into the character generator's internal font pages. ■ Subfunction 10H is reserved on the MCGA. If it is called, Subfunction 00H is executed. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [VGA] Function 11H (17) Subfunctions 01H and 11H (17) Load ROM 8-by-14 font ──────────────────────────────────────────────────────────────────────────── Loads the ROM BIOS default 8-by-14 font table into the specified block of character generator RAM. Call with: AH = 11H AL = 01H or 11H (see Notes) BL = block Returns: Nothing Notes: ■ This function provides font selection in text (alphanumeric) display modes. For font selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Subfunctions 20H─24H. ■ If AL = 11H, page 0 must be active. The points (bytes per character), rows, and length of the refresh buffer are recalculated. The controller is reprogrammed with the maximum scan line (points - 1), cursor start (points - 2), cursor end (points - 1), vertical display end ((rows*points) - 1), and underline location (points - 1, mode 7 only). If Subfunction 11H is called at any time other than immediately after a mode set, the results are unpredictable. ■ Subfunctions 01H and 11H are reserved on the MCGA. If either is called, Subfunction 04H is executed. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunctions 02H and 12H (18) Load ROM 8-by-8 font ──────────────────────────────────────────────────────────────────────────── Loads the ROM BIOS default 8-by-8 font table into the specified block of character generator RAM. Call with: AH = 11H AL = 02H or 12H (see Notes) BL = block Returns: Nothing Notes: ■ This function provides font selection in text (alphanumeric) display modes. For font selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Subfunctions 20H─24H. ■ If AL = 12H, page 0 must be active. The points (bytes per character), rows, and length of the refresh buffer are recalculated. The controller is reprogrammed with the maximum scan line (points - 1), cursor start (points - 2), cursor end (points - 1), vertical display end ((rows*points) - 1), and underline location (points - 1, mode 7 only). If Subfunction 12H is called at any time other than immediately after a mode set, the results are unpredictable. ■ On the MCGA, a Subfunction 02H call should be followed by a Subfunction 03H call, so that the ROM BIOS will load the font into the character generator's internal font pages. ■ Subfunction 12H is reserved on the MCGA. If it is called, Subfunction 02H is executed. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunction 03H Set block specifier ──────────────────────────────────────────────────────────────────────────── Determines the character blocks selected by bit 3 of character attribute bytes in alphanumeric (text) display modes. Call with: AH = 11H AL = 03H BL = character generator block select code (see Notes) Returns: Nothing Notes: ■ On the EGA and MCGA, the bits of BL are used as follows: Bits Significance ──────────────────────────────────────────────────────────────────────── 0─1 character block selected by attribute bytes with bit 3 = 0 2─3 character block selected by attribute bytes with bit 3 = 1 4─7 not used (should be 0) ──────────────────────────────────────────────────────────────────────── ■ On the VGA, the bits of BL are used as follows: Bits Significance ──────────────────────────────────────────────────────────────────────── 0,1,4 character block selected by attribute bytes with bit 3 = 0 2,3,5 character block selected by attribute bytes with bit 3 = 1 6─7 not used (should be 0) ──────────────────────────────────────────────────────────────────────── ■ When using a 256-character set, both fields of BL should select the same character block. In such cases, character attribute bit 3 controls the foreground intensity. When using 512-character sets, the fields of BL designate the blocks holding each half of the character set, and bit 3 of the character attribute selects the upper or lower half of the character set. ■ When using a 512-character set, a call to Int 10H Function 10H Subfunction 00H with BX = 0712H is recommended to set the color planes to eight consistent colors. ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 11H (17) Subfunctions 04H and 14H (20) Load ROM 8-by-16 font ──────────────────────────────────────────────────────────────────────────── Loads the ROM BIOS default 8-by-16 font table into the specified block of character generator RAM. Call with: AH = 11H AL = 04H or 14H (see Notes) BL = block Returns: Nothing Notes: ■ This function provides font selection in text (alphanumeric) display modes. For font selection in graphics (all-points-addressable) modes, see Int 10H Function 11H Subfunctions 20H─24H. ■ If AL = 14H, page 0 must be active. The points (bytes per character), rows, and length of the refresh buffer are recalculated. The controller is reprogrammed with the maximum scan line (points - 1), cursor start (points - 2), cursor end (points - 1), vertical display end (rows*points - 1 for 350- and 400-line modes, or rows *points *2 - 1 for 200-line modes), and underline location (points - 1, mode 7 only). If Subfunction 14H is called at any time other than immediately after a mode set, the results are unpredictable. ■ On the MCGA, a Subfunction 04H call should be followed by a Subfunction 03H call so that the ROM BIOS will load the font into the character generator's internal font pages. ■ Subfunction 14H is reserved on the MCGA. If it is called, Subfunction 04H is executed. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunction 20H (32) Set Int 1FH font pointer ──────────────────────────────────────────────────────────────────────────── Sets the Int 1FH pointer to the user's font table. This table is used for character codes 80H─FFH in graphics modes 04H─06H. Call with: AH = 11H AL = 20H ES:BP = segment:offset of font table Returns: Nothing Notes: ■ This function provides font selection in graphics (all-points-addressable) display modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H Subfunctions 00H─14H. ■ If this subfunction is called at any time other than immediately after a mode set, the results are unpredictable. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunction 21H (33) Set Int 43H for user's font ──────────────────────────────────────────────────────────────────────────── Sets the vector for Int 43H to point to the user's font table and updates the video ROM BIOS data area. The video controller is not reprogrammed. Call with: AH = 11H AL = 21H BL = character rows specifier 00H if user specified (see register DL) 01H = 14 (0EH) rows 02H = 25 (19H) rows 03H = 43 (2BH) rows CX = points (bytes per character) DL = character rows per screen (if BL = 00H) ES:BP = segment:offset of user font table Returns: Nothing Notes: ■ This function provides font selection in graphics (all-points-addressable) display modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H Subfunctions 00H─14H. ■ If this subfunction is called at any time other than immediately after a mode set, the results are unpredictable. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunction 22H (34) Set Int 43H for ROM 8-by-14 font ──────────────────────────────────────────────────────────────────────────── Sets the vector for Int 43H to point to the ROM BIOS default 8-by-14 font and updates the video ROM BIOS data area. The video controller is not reprogrammed. Call with: AH = 11H AL = 22H BL = character rows specifier 00H if user specified (see register DL) 01H = 14 (0EH) rows 02H = 25 (19H) rows 03H = 43 (2BH) rows DL = character rows per screen (if BL = 00H) Returns: Nothing Notes: ■ This function provides font selection in graphics (all-points-addressable) display modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H Subfunctions 00H─14H. ■ If this subfunction is called at any time other than immediately after a mode set, the results are unpredictable. ■ When this subfunction is called on the MCGA, Subfunction 24H is substituted. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunction 23H (35) Set Int 43H for ROM 8-by-8 font ──────────────────────────────────────────────────────────────────────────── Sets the vector for Int 43H to point to the ROM BIOS default 8-by-8 font and updates the video ROM BIOS data area. The video controller is not reprogrammed. Call with: AH = 11H AL = 23H BL = character rows specifier 00H if user specified (see register DL) 01H = 14 (0EH) rows 02H = 25 (19H) rows 03H = 43 (2BH) rows DL = character rows per screen (if BL = 00H) Returns: Nothing Notes: ■ This function provides font selection in graphics (all-points-addressable) display modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H Subfunctions 00H─14H. ■ If this subfunction is called at any time other than immediately after a mode set, the results are unpredictable. ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 11H (17) Subfunction 24H (36) Set Int 43H for ROM 8-by-16 font ──────────────────────────────────────────────────────────────────────────── Sets the vector for Int 43H to point to the ROM BIOS default 8-by-16 font and updates the video ROM BIOS data area. The video controller is not reprogrammed. Call with: AH = 11H AL = 24H BL = row specifier 00H if user specified (see register DL) 01H = 14 (0EH) rows 02H = 25 (19H) rows 03H = 43 (2BH) rows DL = character rows per screen (if BL = 00H) Returns: Nothing Notes: ■ This function provides font selection in graphics (all-points-addressable) display modes. For font selection in text (alphanumeric) modes, see Int 10H Function 11H Subfunctions 00H─14H. ■ If this subfunction is called at any time other than immediately after a mode set, the results are unpredictable. ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [MCGA] [VGA] Function 11H (17) Subfunction 30H (48) Get font information ──────────────────────────────────────────────────────────────────────────── Returns a pointer to the character definition table for a font and the points (bytes per character) and rows for that font. Call with: AH = 11H AL = 30H BH = font code 00H = current Int 1FH contents 01H = current Int 43H contents 02H = ROM 8-by-14 font (EGA, VGA only) 03H = ROM 8-by-8 font (characters 00H─7FH) 04H = ROM 8-by-8 font (characters 80H─FFH) 05H = ROM alternate 9-by-14 font (EGA, VGA only) 06H = ROM 8-by-16 font (MCGA, VGA only) 07H = ROM alternate 9-by-16 font (VGA only) Returns: CX = points (bytes per character) DL = rows (character rows on screen - 1) ES:BP = segment:offset of font table ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [VGA] Function 12H (18) Subfunction 10H (16) Get configuration information ──────────────────────────────────────────────────────────────────────────── Obtains configuration information for the active video subsystem. Call with: AH = 12H BL = 10H Returns: BH = display type 0 if color display 1 if monochrome display BL = memory installed on EGA board 00H if 64 KB 01H if 128 KB 02H if 192 KB 03H if 256 KB CH = feature bits (see Notes) CL = switch setting (see Notes) Notes: ■ The feature bits are set from Input Status register 0 in response to an output on the specified Feature Control register bits: Feature Feature control Input status bit(s) output bit bit ──────────────────────────────────────────────────────────────────────── 0 0 5 1 0 6 2 1 5 3 1 6 4─7 not used ──────────────────────────────────────────────────────────────────────── ■ The bits in the switch settings byte indicate the state of the EGA's configuration DIP switch (1 = off, 0 = on). Bit(s) Significance ──────────────────────────────────────────────────────────────────────── 0 configuration switch 1 1 configuration switch 2 2 configuration switch 3 3 configuration switch 4 4─7 not used ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 10H [EGA] [VGA] Function 12H (18) Subfunction 20H (32) Select alternate printscreen ──────────────────────────────────────────────────────────────────────────── Selects an alternate print-screen routine for the EGA and VGA that works properly if the screen length is not 25 lines. The ROM BIOS default print-screen routine always prints 25 lines. Call with: AH = 12H BL = 20H Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 12H (18) Subfunction 30H (48) Set scan lines ──────────────────────────────────────────────────────────────────────────── Selects the number of scan lines for alphanumeric modes. The selected value takes effect the next time Int 10H Function 00H is called to select the display mode. Call with: AH = 12H AL = scan line code 00H = 200 scan lines 01H = 350 scan lines 02H = 400 scan lines BL = 30H Returns: If the VGA is active AL = 12H If the VGA is not active AL = 00H ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 12H (18) Subfunction 31H (49) Enable/disable default palette loading ──────────────────────────────────────────────────────────────────────────── Enables or disables loading of a default palette when a video display mode is selected. Call with: AH = 12H AL = 00H to enable default palette loading 01H to disable default palette loading BL = 31H Returns: If function supported AL = 12H ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 12H (18) Subfunction 32H (50) Enable/disable video ──────────────────────────────────────────────────────────────────────────── Enables or disables CPU access to the video adapter's I/O ports and video refresh buffer. Call with: AH = 12H AL = 00H to enable access 01H to disable access BL = 32H Returns: If function supported AL = 12H ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 12H (18) Subfunction 33H (51) Enable/disable gray-scale summing ──────────────────────────────────────────────────────────────────────────── Enables or disables gray-scale summing for the currently active display. Call with: AH = 12H AL = 00H to enable gray-scale summing 01H to disable gray-scale summing BL = 33H Returns: If function supported AL = 12H Note: ■ When enabled, gray-scale summing occurs during display mode selection, palette programming, and color register loading. ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 12H (18) Subfunction 34H (52) Enable/disable cursor emulation ──────────────────────────────────────────────────────────────────────────── Enables or disables cursor emulation for the currently active display. When cursor emulation is enabled, the ROM BIOS automatically remaps Int 10H Function 01H cursor starting and ending lines for the current character cell dimensions. Call with: AH = 12H AL = 00H to enable cursor emulation 01H to disable cursor emulation BL = 34H Returns: If function supported AL = 12H ──────────────────────────────────────────────────────────────────────────── Int 10H [MCGA] [VGA] Function 12H (18) Subfunction 35H (53) Switch active display ──────────────────────────────────────────────────────────────────────────── Allows selection of one of two video adapters in the system when memory usage or port addresses conflict between the two adapters. Call with: AH = 12H AL = switching function 00H to disable initial video adapter 01H to enable system board video adapter 02H to disable active video adapter 03H to enable inactive video adapter BL = 35H ES:DX = segment:offset of 128-byte buffer (if AL = 00H, 02H, or 03H) Returns: If function supported AL = 12H and, if called with AL = 00H or 02H Video adapter state information saved in caller's buffer or, if called with AL = 03H Video adapter state restored from information in caller's buffer Notes: ■ This subfunction cannot be used unless both video adapters have a disable capability (Int 10H Function 12H Subfunction 32H). ■ If there is no conflict between the system board video and the adapter board video in memory or port usage, both video controllers can be active simultaneously and this subfunction is not required. ──────────────────────────────────────────────────────────────────────────── Int 10H [VGA] Function 12H (18) Subfunction 36H (54) Enable/disable screen refresh ──────────────────────────────────────────────────────────────────────────── Enables or disables the video refresh for the currently active display. Call with: AH = 12H AL = 00H to enable refresh 01H to disable refresh BL = 36H Returns: If function supported AL = 12H ──────────────────────────────────────────────────────────────────────────── Int 10H [MDA] [CGA] [PCjr] [EGA] [MCGA] [VGA] Function 13H (19) Write string in teletype mode ──────────────────────────────────────────────────────────────────────────── Transfers a string to the video buffer for the currently active display, starting at the specified position. Call with: AH = 13H AL = write mode 0 attribute in BL; string contains character codes only; and cursor position is not updated after write 1 attribute in BL; string contains character codes only; and cursor position is updated after write 2 string contains alternating character codes and attribute bytes; and cursor position is not updated after write 3 string contains alternating character codes and attribute bytes; and cursor position is updated after write BH = page BL = attribute, if AL = 00H or 01H CX = length of character string DH = y coordinate (row) DL = x coordinate (column) ES:BP = segment:offset of string Returns: Nothing Notes: ■ This function is not available on the original IBM PC or PC/XT unless an EGA video adapter (which contains its own ROM BIOS) is installed. ■ This function may be thought of as an extension to Int 10H Function 0EH. The control characters bell (07H), backspace (08H), line feed (0AH), and carriage return (0DH) are recognized and handled appropriately. ──────────────────────────────────────────────────────────────────────────── Int 10H [PS/2] Function 1AH (26) Get or set display combination code ──────────────────────────────────────────────────────────────────────────── Returns a code describing the installed display adapter(s) or updates the ROM BIOS's variable describing the installed adapter(s). Call with: AH = 1AH AL = subfunction 00H = get display combination code 01H = set display combination code BH = inactive display code (if AL = 01H) BL = active display code (if AL = 01H) Returns: If function supported AL = 1AH and, if called with AL = 00H BH = inactive display code BL = active display code Note: ■ The display codes are interpreted as follows: Code(s) Video subsystem type ──────────────────────────────────────────────────────────────────────── 00H no display 01H MDA with 5151 monitor 02H CGA with 5153 or 5154 monitor 03H reserved 04H EGA with 5153 or 5154 monitor 05H EGA with 5151 monitor 06H PGA with 5175 monitor 07H VGA with analog monochrome monitor 08H VGA with analog color monitor 09H reserved 0AH MCGA with digital color monitor 0BH MCGA with analog monochrome monitor 0CH MCGA with analog color monitor 0DH─FEH reserved FFH unknown ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 10H [PS/2] Function 1BH (27) Get functionality/state information ──────────────────────────────────────────────────────────────────────────── Obtains information about the current display mode as well as a pointer to a table describing the characteristics and capabilities of the video adapter and monitor. Call with: AH = 1BH BX = implementation type (always 00H) ES:DI = segment:offset of 64-byte buffer Returns: If function supported AL = 1BH and information placed in caller's buffer (see Notes) Notes: ■ The caller's buffer is filled in with information that depends on the current video display mode: ╓┌───┌─────────┌─────────────────────────────────────────────────────────────╖ Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 00H─03H pointer to functionality information (see next Note) 04H current video mode 05H─06H number of character columns 07H─08H length of video refresh buffer (bytes) 09H─0AH starting address in buffer of upper left corner of display 0BH─1AH cursor position for video pages 0─7 as eight 2-byte entries; first byte of each pair is y coordinate, second byte is x coordinate 1BH cursor starting line 1CH cursor ending line 1DH active display page 1EH─1FH adapter base port address (3BXH monochrome, 3DXH color) 20H current setting of register 3B8H or 3D8H 21H current setting of register 3B9H or 3D9H 22H number of character rows 23H─24H character height in scan lines 25H active display code (see Int 10H Function 1AH) 26H inactive display code (see Int 10H Function 1AH) Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 26H inactive display code (see Int 10H Function 1AH) 27H─28H number of displayable colors (0 for monochrome) 29H number of display pages 2AH number of scan lines 00H = 200 scan lines 01H = 350 scan lines 02H = 400 scan lines 03H = 480 scan lines 04H─FFH = reserved 2BH primary character block (see Int 10H Function 11H Subfunction 03H) 2CH secondary character block 2DH miscellaneous state information Bit(s) Significance 0 = 1 if all modes on all displays active (always 0 on MCGA) 1 = 1 if gray-scale summing active 2 = 1 if monochrome display attached Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 2 = 1 if monochrome display attached 3 = 1 if mode set default palette loading disabled 4 = 1 if cursor emulation active (always 0 on MCGA) 5 = state of I/B toggle (0 = intensity, 1 = blink) 6─7 = reserved 2EH─30H reserved 31H video memory available 00H = 64 KB 01H = 128 KB 02H = 192 KB 03H = 256 KB 32H save pointer state information Bit(s) Significance 0 = 1 if 512-character set active Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 0 = 1 if 512-character set active 1 = 1 if dynamic save area active 2 = 1 if alpha font override active 3 = 1 if graphics font override active 4 = 1 if palette override active 5 = 1 if display combination code (DCC) extension active 6─7 = reserved 33H─3FH reserved ──────────────────────────────────────────────────────────────────────── ■ Bytes 0─3 of the caller's buffer contain a DWORD pointer (offset in lower word, segment in upper word) to the following information about the display adapter and monitor: ╓┌───┌─────────┌─────────────────────────────────────────────────────────────╖ Byte(s) Contents Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 00H video modes supported Bit Significance 0 = 1 if mode 00H supported 1 = 1 if mode 01H supported 2 = 1 if mode 02H supported 3 = 1 if mode 03H supported 4 = 1 if mode 04H supported 5 = 1 if mode 05H supported 6 = 1 if mode 06H supported 7 = 1 if mode 07H supported 01H video modes supported Bit Significance 0 = 1 if mode 08H supported 1 = 1 if mode 09H supported 2 = 1 if mode 0AH supported 3 = 1 if mode 0BH supported Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 3 = 1 if mode 0BH supported 4 = 1 if mode 0CH supported 5 = 1 if mode 0DH supported 6 = 1 if mode 0EH supported 7 = 1 if mode 0FH supported 02H video modes supported Bit(s) Significance 0 = 1 if mode 10H supported 1 = 1 if mode 11H supported 2 = 1 if mode 12H supported 3 = 1 if mode 13H supported 4─7 = reserved 03H─06H reserved 07H scan lines available in text modes Bit(s) Significance Byte(s) Contents ──────────────────────────────────────────────────────────────────────── Bit(s) Significance 0 = 1 if 200 scan lines 1 = 1 if 350 scan lines 2 = 1 if 400 scan lines 3─7 = reserved 08H character blocks available in text modes (see Int 10H Function 11H) 09H maximum number of active character blocks in text modes 0AH miscellaneous BIOS capabilities Bit Significance 0 = 1 if all modes active on all displays (always 0 for MCGA) 1 = 1 if gray-scale summing available 2 = 1 if character font loading available 3 = 1 if mode set default palette loading available 4 = 1 if cursor emulation available Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 4 = 1 if cursor emulation available 5 = 1 if EGA (64-color) palette available 6 = 1 if color register loading available 7 = 1 if color register paging mode select available 0BH miscellaneous BIOS capabilities Bit(s) Significance 0 = 1 if light pen available 1 = 1 if save/restore video state available (always 0 on MCGA) 2 = 1 if background intensity/blinking control available 3 = 1 if get/set display combination code available 4─7 = reserved 0CH─0DH reserved Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 0CH─0DH reserved 0EH save area capabilities Bit(s) Significance 0 = 1 if supports 512-character sets 1 = 1 if dynamic save area available 2 = 1 if alpha font override available 3 = 1 if graphics font override available 4 = 1 if palette override available 5 = 1 if display combination code extension available 6─7 = reserved 0FH reserved ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 10H [PS/2] Function 1CH (28) Save or restore video state ──────────────────────────────────────────────────────────────────────────── Saves or restores the digital-to-analog converter (DAC) state and color registers, ROM BIOS video driver data area, or video hardware state. Call with: AH = 1CH AL = subfunction 00H to get state buffer size 01H to save state 02H to restore state CX = requested states Bit(s) Significance (if set) 0 save/restore video hardware state 1 save/restore video BIOS data area 2 save/restore video DAC state and color registers 3─15 reserved ES:BX = segment:offset of buffer Returns: If function supported AL = 1CH and, if called with AL = 00H BX = buffer block count (64 bytes per block) or, if called with AL = 01H State information placed in caller's buffer or, if called with AL = 02H Requested state restored according to contents of caller's buffer Notes: ■ Subfunction 00H is used to determine the size of buffer that will be necessary to contain the specified state information. The caller must supply the buffer. ■ The current video state is altered during a save state operation (AL = 01H). If the requesting program needs to continue in the same video state, it can follow the save state request with an immediate call to restore the video state. ■ This function is supported on the VGA only. ──────────────────────────────────────────────────────────────────────────── Int 11H [PC] [AT] [PS/2] Get equipment configuration ──────────────────────────────────────────────────────────────────────────── Obtains the equipment list code word from the ROM BIOS. Call with: Nothing Returns: AX = equipment list code word Bit(s) Significance 0 = 1 if floppy disk drive(s) installed 1 = 1 if math coprocessor installed 2 = 1 if pointing device installed (PS/2) 2─3 system board ram size (PC, see Note) 00 = 16 KB 01 = 32 KB 10 = 48 KB 11 = 64 KB 4─5 initial video mode 00 reserved 01 40-by-25 color text 10 80-by-25 color text 11 80-by-25 monochrome 6─7 number of floppy disk drives (if bit 0 = 1) 00 = 1 01 = 2 10 = 3 11 = 4 8 reserved 9─11 number of RS-232 ports installed 12 = 1 if game adapter installed 13 = 1 if internal modem installed (PC and XT only) = 1 if serial printer attached (PCjr) 14─15 number of printers installed Note: ■ Bits 2─3 of the returned value are used only in the ROM BIOS for the original IBM PC with the 64 KB system board and on the PCjr. ──────────────────────────────────────────────────────────────────────────── Int 12H [PC] [AT] [PS/2] Get conventional memory size ──────────────────────────────────────────────────────────────────────────── Returns the amount of conventional memory available for use by MS-DOS and application programs. Call with: Nothing Returns: AX = memory size (in KB) Notes: ■ On some early PC models, the amount of memory returned by this function is controlled by the settings of the dip switches on the system board and may not reflect all the memory that is physically present. ■ On the PC/AT, the value returned is the amount of functional memory found during the power-on self-test, regardless of the memory size configuration information stored in CMOS RAM. ■ The value returned does not reflect any extended memory (above the 1 MB boundary) that may be installed on 80286 or 80386 machines such as the PC/AT or PS/2 (Models 50 and above). ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 00H Reset disk system ──────────────────────────────────────────────────────────────────────────── Resets the disk controller, recalibrates its attached drives (the read/write arm is moved to cylinder 0), and prepares for disk I/O. Call with: AH = 00H DL = drive 00H─7FH floppy disk 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function should be called after a failed floppy disk Read, Write, Verify, or Format request before retrying the operation. ■ If called with DL >= 80H (i.e., selecting a fixed disk drive), the floppy disk controller and then the fixed disk controller are reset. See also Int 13H Function 0DH, which allows the fixed disk controller to be reset without affecting the floppy disk controller. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 01H Get disk system status ──────────────────────────────────────────────────────────────────────────── Returns the status of the most recent disk operation. Call with: AH = 01H DL = drive 00H─7FH floppy disk 80H─FFH fixed disk Returns: AH = 00H AL = status of previous disk operation 00H no error 01H invalid command 02H address mark not found 03H disk write-protected (F) 04H sector not found 05H reset failed (H) 06H floppy disk removed (F) 07H bad parameter table (H) 08H DMA overrun (F) 09H DMA crossed 64 KB boundary 0AH bad sector flag (H) 0BH bad track flag (H) 0CH media type not found (F) 0DH invalid number of sectors on format (H) 0EH control data address mark detected (H) 0FH DMA arbitration level out of range (H) 10H uncorrectable CRC☼ or ECC☼ data error 11H ECC corrected data error (H) 20H controller failed 40H seek failed 80H disk timed-out (failed to respond) AAH drive not ready (H) BBH undefined error (H) CCH write fault (H) E0H status register error (H) FFH sense operation failed (H) H = fixed disk only, F = floppy disk only Note: ■ On fixed disks, error code 11H (ECC data error) indicates that a recoverable error was detected during a preceding Read Sector (Int 13H Function 02H) function. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 02H Read sector ──────────────────────────────────────────────────────────────────────────── Reads one or more sectors from disk into memory. Call with: AH = 02H AL = number of sectors CH = cylinder CL = sector DH = head DL = drive 00H─7FH floppy disk 80H─FFH fixed disk ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear AH = 00H AL = number of sectors transferred If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ■ On fixed disks, error code 11H indicates that a read error occurred that was corrected by the ECC algorithm; in this event, register AL contains the burst length. The data returned is probably good, although there is a small chance that the data was not corrected properly. If a multi-sector transfer was requested, the operation was terminated after the sector containing the read error. ■ On floppy disk drives, an error may result from the drive motor being off at the time of the request. The ROM BIOS does not automatically wait for the drive to come up to speed before attempting the read operation. The requesting program should reset the floppy disk system (Int 13H Function 00H) and retry the operation three times before assuming that the error results from some other cause. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 03H Write sector ──────────────────────────────────────────────────────────────────────────── Writes one or more sectors from memory to disk. Call with: AH = 03H AL = number of sectors CH = cylinder CL = sector DH = head DL = drive 00H─7FH floppy disk 80H─FFH fixed disk ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear AH = 00H AL = number of sectors transferred If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ■ On floppy disk drives, an error may result from the drive motor being off at the time of the request. The ROM BIOS does not automatically wait for the drive to come up to speed before attempting the write operation. The requesting program should reset the floppy disk system (Int 13H Function 00H) and retry the operation three times before assuming that the error results from some other cause. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 04H Verify sector ──────────────────────────────────────────────────────────────────────────── Verifies the address fields of one or more sectors. No data is transferred to or from memory by this operation. Call with: AH = 04H AL = number of sectors CH = cylinder CL = sector DH = head DL = drive 00H─7FH floppy disk 80H─FFH fixed disk ES:BX = segment:offset of buffer (see Notes) Returns: If function successful Carry flag = clear AH = 00H AL = number of sectors verified If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ On PCs, PC/XTs, and PC/ATs with ROM BIOS dated earlier than 11/15/85, ES:BX should point to a valid buffer. ■ On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ■ This function can be used to test whether a readable media is in a floppy disk drive. An error may result from the drive motor being off at the time of the request, because the ROM BIOS does not automatically wait for the drive to come up to speed before attempting the verify operation. The requesting program should reset the floppy disk system (Int 13H Function 00H) and retry the operation three times before assuming that a readable floppy disk is not present. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 05H Format track ──────────────────────────────────────────────────────────────────────────── Initializes disk sector and track address fields on the specified track. Call with: AH = 05H AL = interleave (PC/XT fixed disks) CH = cylinder DH = head DL = drive 00H─7FH floppy disk 80H─FFH fixed disk ES:BX = segment:offset of address field list (except PC/XT fixed disk, see Note) Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ On floppy disks, the address field list consists of a series of 4-byte entries, one entry per sector, in the following format: Byte(s) Contents 0 cylinder 1 head 2 sector 3 sector-size code 00H if 128 bytes per sector 01H if 256 bytes per sector 02H if 512 bytes per sector (standard) 03H if 1024 bytes per sector ■ On floppy disks, the number of sectors per track is taken from the BIOS floppy disk parameter table whose address is stored in the vector for Int 1EH. ■ When this function is used for floppy disks on the PC/AT or PS/2, it should be preceded by a call to Int 13H Function 17H to select the type of medium to be formatted. ■ On fixed disks, the upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ■ On PC/XT-286, PC/AT, and PS/2 fixed disks, ES:BX points to a 512-byte buffer containing byte pairs for each physical disk sector, as follows: Byte(s) Contents 0 00H for good sector 80H for bad sector 1 sector number For example, to format a track with 17 sectors and an interleave of two, ES:BX would point to the following 34-byte array at the beginning of a 512-byte buffer: db 00h,01h,00h,0ah,00h,02h,00h,0bh,00h,03h,00h,0ch db 00h,04h,00h,0dh,00h,05h,00h,0eh,00h,06h,00h,0fh db 00h,07h,00h,10h,00h,08h,00h,11h,00h,09h ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] Function 06H Format bad track ──────────────────────────────────────────────────────────────────────────── Initializes a track, writing disk address fields and data sectors and setting bad sector flags. Call with: AH = 06H AL = interleave CH = cylinder DH = head DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is defined for PC/XT fixed disk drives only. ■ For additional information, see Notes for Int 13H Function 05H. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] Function 07H Format drive ──────────────────────────────────────────────────────────────────────────── Formats the entire drive, writing disk address fields and data sectors, starting at the specified cylinder. Call with: AH = 07H AL = interleave CH = cylinder DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is defined for PC/XT fixed disk drives only. ■ For additional information, see Notes for Int 13H Function 05H. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 08H Get drive parameters ──────────────────────────────────────────────────────────────────────────── Returns various parameters for the specified drive. Call with: AH = 08H DL = drive 00H─7FH floppy disk 80H─FFH fixed disk Returns: If function successful Carry flag = clear BL = drive type (PC/AT and PS/2 floppy disks) 01H if 360 KB, 40 track, 5.25" 02H if 1.2 MB, 80 track, 5.25" 03H if 720 KB, 80 track, 3.5" 04H if 1.44 MB, 80 track, 3.5" CH = low 8 bits of maximum cylinder number CL = bits 6─7 high-order 2 bits of maximum cylinder number bits 0─5 maximum sector number DH = maximum head number DL = number of drives ES:DI = segment:offset of disk drive parameter table If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ On the PC and PC/XT, this function is supported on fixed disks only. ■ The value returned in register DL reflects the true number of physical drives attached to the adapter for the requested drive. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 09H Initialize fixed disk characteristics ──────────────────────────────────────────────────────────────────────────── Initializes the fixed disk controller for subsequent I/O operations, using the values found in the ROM BIOS disk parameter block(s). Call with: AH = 09H DL = drive 80H─FFH fixed disk and, on the PC/XT Vector for Int 41H must point to disk parameter block or, on the PC/AT and PS/2 Vector for Int 41H must point to disk parameter block for drive 0 Vector for Int 46H must point to disk parameter block for drive 1 Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is supported on fixed disks only. ■ For PC and PC/XT fixed disks, the parameter block format is as follows: Byte(s) Contents 00H─01H maximum number of cylinders 02H maximum number of heads 03H─04H starting reduced write current cylinder 05H─06H starting write precompensation cylinder 07H maximum ECC burst length 08H drive options Bit(s) Significance (if set) 0─2 drive option 3─5 reserved (0) 6 disable ECC retries 7 disable disk-access retries 09H standard time-out value 0AH time-out value for format drive 0BH time-out value for check drive 0CH─0FH reserved ■ For PC/AT and PS/2 fixed disks, the parameter block format is as follows: Byte(s) Contents 00H─01H maximum number of cylinders 02H maximum number of heads 03H─04H reserved 05H─06H starting write precompensation cylinder 07H maximum ECC burst length 08H drive options Bit(s) Significance (if set) 0─2 not used 3 more than 8 heads 4 not used 5 manufacturer's defect map present at maximum cylinder + 1 6─7 nonzero (10, 01, or 11) if retries disabled 09H─0BH reserved 0CH─0DH landing zone cylinder 0EH sectors per track 0FH reserved ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 0AH (10) Read sector long ──────────────────────────────────────────────────────────────────────────── Reads a sector or sectors from disk into memory, along with a 4-byte ECC code for each sector. Call with: AH = 0AH AL = number of sectors CH = cylinder CL = sector (see Notes) DH = head DL = drive 80H─FFH fixed disk ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear AH = 00H AL = number of sectors transferred If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is supported on fixed disks only. ■ The upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ■ Unlike the normal Read Sector function (Int 13H Function 02H), ECC errors are not automatically corrected. Multisector transfers are terminated after any sector with a read error. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 0BH (11) Write sector long ──────────────────────────────────────────────────────────────────────────── Writes a sector or sectors from memory to disk. Each sector's worth of data must be followed by its 4-byte ECC code. Call with: AH = 0BH AL = number of sectors CH = cylinder CL = sector (see Notes) DH = head DL = drive 80H─FFH fixed disk ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear AH = 00H AL = number of sectors transferred If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is supported on fixed disks only. ■ The upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 0CH (12) Seek ──────────────────────────────────────────────────────────────────────────── Positions the disk read/write heads to the specified cylinder, but does not transfer any data. Call with: AH = 0CH CH = lower 8 bits of cylinder CL = upper 2 bits of cylinder in bits 6─7 DH = head DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is supported on fixed disks only. ■ The upper 2 bits of the 10-bit cylinder number are placed in the upper 2 bits of register CL. ■ The Read Sector, Read Sector Long, Write Sector, and Write Sector Long functions include an implied seek operation and need not be preceded by an explicit call to this function. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 0DH (13) Reset fixed disk system ──────────────────────────────────────────────────────────────────────────── Resets the fixed disk controller, recalibrates attached drives (moves the read/write arm to cylinder 0), and prepares for subsequent disk I/O. Call with: AH = 0DH DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported on fixed disks only. It differs from Int 13H Function 00H in that the floppy disk controller is not reset. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] Function 0EH (14) Read sector buffer ──────────────────────────────────────────────────────────────────────────── Transfers the contents of the fixed disk adapter's internal sector buffer to system memory. No data is read from the physical disk drive. Call with: AH = 0EH ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported by the PC/XT's fixed disk adapter only. It is not defined for fixed disk adapters on the PC/AT or PS/2. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] Function 0FH (15) Write sector buffer ──────────────────────────────────────────────────────────────────────────── Transfers data from system memory to the fixed disk adapter's internal sector buffer. No data is written to the physical disk drive. Call with: AH = 0FH ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is supported by the PC/XT's fixed disk adapter only. It is not defined for fixed disk adapters on the PC/AT or PS/2. ■ This function should be called to initialize the contents of the sector buffer before formatting the drive with Int 13H Function 05H. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 10H (16) Get drive status ──────────────────────────────────────────────────────────────────────────── Tests whether the specified fixed disk drive is operational and returns the drive's status. Call with: AH = 10H DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported on fixed disks only. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 11H (17) Recalibrate drive ──────────────────────────────────────────────────────────────────────────── Causes the fixed disk adapter to recalibrate itself for the specified drive, positioning the read/write arm to cylinder 0, and returns the drive's status. Call with: AH = 11H DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported on fixed disks only. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] Function 12H (18) Controller RAM diagnostic ──────────────────────────────────────────────────────────────────────────── Causes the fixed disk adapter to carry out a built-in diagnostic test on its internal sector buffer, indicating whether the test was passed by the returned status. Call with: AH = 12H Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported on PC/XT fixed disks only. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] Function 13H (19) Controller drive diagnostic ──────────────────────────────────────────────────────────────────────────── Causes the fixed disk adapter to run internal diagnostic tests of the attached drive, indicating whether the test was passed by the returned status. Call with: AH = 13H Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported on PC/XT fixed disks only. ──────────────────────────────────────────────────────────────────────────── Int 13H [PC] [AT] [PS/2] Function 14H (20) Controller internal diagnostic ──────────────────────────────────────────────────────────────────────────── Causes the fixed disk adapter to carry out a built-in diagnostic self-test, indicating whether the test was passed by the returned status. Call with: AH = 14H Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is supported on fixed disks only. ──────────────────────────────────────────────────────────────────────────── Int 13H [AT] [PS/2] Function 15H (21) Get disk type ──────────────────────────────────────────────────────────────────────────── Returns a code indicating the type of floppy or fixed disk referenced by the specified drive code. Call with: AH = 15H DL = drive 00H─7FH floppy disk 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = drive type code 00H if no drive present 01H if floppy disk drive without change-line support 02H if floppy disk drive with change-line support 03H if fixed disk and, if fixed disk (AH = 03H) CX:DX = number of 512-byte sectors If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is not supported on the PC or PC/XT. ──────────────────────────────────────────────────────────────────────────── Int 13H [AT] [PS/2] Function 16H (22) Get disk change status ──────────────────────────────────────────────────────────────────────────── Returns the status of the change line, indicating whether the disk in the drive may have been replaced since the last disk access. Call with: AH = 16H DL = drive 00H─7FH floppy disk Returns: If change line inactive (disk has not been changed) Carry flag = clear AH = 00H If change line active (disk may have been changed) Carry flag = set AH = 06H Notes: ■ If this function returns with the carry flag set, the disk has not necessarily been changed; the change line can be activated by simply unlocking and locking the disk drive door without removing the floppy disk. ■ This function is not supported for floppy disks on the PC or PC/XT. ──────────────────────────────────────────────────────────────────────────── Int 13H [AT] [PS/2] Function 17H (23) Set disk type ──────────────────────────────────────────────────────────────────────────── Selects a floppy disk type for the specified drive. Call with: AH = 17H AL = floppy disk type code 00H not used 01H 320/360 KB floppy disk in 360 KB drive 02H 320/360 KB floppy disk in 1.2 MB drive 03H 1.2 MB floppy disk in 1.2 MB drive 04H 720 KB floppy disk in 720 KB drive SL = drive 00H─7FH floppy disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This function is not supported for floppy disks on the PC or PC/XT. ■ If the change line is active for the specified drive, it is reset. The ROM BIOS then sets the data rate for the specified drive and media type. ──────────────────────────────────────────────────────────────────────────── Int 13H [AT] [PS/2] Function 18H (24) Set media type for format ──────────────────────────────────────────────────────────────────────────── Selects media characteristics for the specified drive. Call with: AH = 18H CH = number of cylinders CL = sectors per track DL = drive 00H─7FH floppy disk Returns: If function successful Carry flag = clear AH = 00H ES:DI = segment:offset of disk parameter table for media type If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ A floppy disk must be present in the drive. ■ This function should be called prior to formatting a disk with Int 13H Function 05H so that the ROM BIOS can set the correct data rate for the media. ■ If the change line is active for the specified drive, it is reset. ──────────────────────────────────────────────────────────────────────────── Int 13H [PS/2] Function 19H (25) Park heads ──────────────────────────────────────────────────────────────────────────── Moves the read/write arm to a track that is not used for data storage, so that data will not be damaged when the drive is turned off. Call with: AH = 19H DL = drive 80H─FFH fixed disk Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Note: ■ This function is defined for PS/2 fixed disks only. ──────────────────────────────────────────────────────────────────────────── Int 13H [PS/2] Function 1AH (26) Format ESDI drive ──────────────────────────────────────────────────────────────────────────── Initializes disk sector and track address fields on a drive attached to the ESDI Fixed Disk Drive Adapter/A. Call with: AH = 1AH AL = relative block address (RBA) defect table count 0 if no RBA table >0 if RBA table used CL = format modifier bits Bit(s) Significance (if set) 0 ignore primary defect map 1 ignore secondary defect map 2 update secondary defect map (see Notes) 3 perform extended surface analysis 4 generate periodic interrupt (see Notes) 5─7 reserved (must be 0) DL = drive 80H─FFH fixed disk ES:BX = segment:offset of RBA table Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 13H Function 01H) Notes: ■ This operation is sometimes called a "low level format" and prepares the disk for physical read/write operations at the sector level. The drive must be subsequently partitioned with the FDISK command and then given a "high level format" with the FORMAT command to install a file system. ■ If bit 4 of register CL is set, Int 15H is called with AH = 0FH and AL = phase code after each cylinder is formatted or analyzed. The phase code is defined as: 0 = reserved 1 = surface analysis 2 = formatting See also Int 15H Function 0FH. ■ If bit 2 of register CL is set, the drive's secondary defect map is updated to reflect errors found during surface analysis. If both bit 2 and bit 1 are set, the secondary defect map is replaced. ■ For an extended surface analysis, the disk should first be formatted by calling this function with bit 3 cleared, then analyzed by calling this function with bit 3 set. ──────────────────────────────────────────────────────────────────────────── Int 14H [PC] [AT] [PS/2] Function 00H Initialize communications port ──────────────────────────────────────────────────────────────────────────── Initializes a serial communications port to a desired baud rate, parity, word length, and number of stop bits. Call with: AH = 00H AL = initialization parameter (see Notes) DX = communications port number (0 = COM1, 1 = COM2, etc.) Returns: AH = port status Bit Significance (if set) 0 receive data ready 1 overrun error detected 2 parity error detected 3 framing error detected 4 break detected 5 transmit holding register empty 6 transmit shift register empty 7 timed-out AL = modem status Bit Significance (if set) 0 change in clear-to-send status 1 change in data-set-ready status 2 trailing edge ring indicator 3 change in receive line signal detect 4 clear-to-send 5 data-set-ready 6 ring indicator 7 receive line signal detect Notes: ■ The initialization parameter byte is defined as follows: 7 6 5 4 3 2 1 0 Baud rate Parity Stop bits Word length ──────────────────────────────────────────────────────────────────────── 000 = 110 X0 = none 0 = 1 bit 10 = 7 bits 001 = 150 01 = odd 1 = 2 bits 11 = 8 bits 010 = 300 11 = even 011 = 600 100 = 1200 101 = 2400 110 = 4800 111 = 9600 ──────────────────────────────────────────────────────────────────────── ■ To initialize the serial port for data rates greater than 9600 baud on PS/2 machines, see Int 14H Functions 04H and 05H. ──────────────────────────────────────────────────────────────────────────── Int 14H [PC] [AT] [PS/2] Function 01H Write character to communications port ──────────────────────────────────────────────────────────────────────────── Writes a character to the specified serial communications port, returning the current status of the port. Call with: AH = 01H AL = character DX = communications port number (0 = COM1, 1 = COM2, etc.) Returns: If function successful AH bit 7 = 0 AH bits = port status 0─6 Bit Significance (if set) 0 receive data ready 1 overrun error detected 2 parity error detected 3 framing error detected 4 break detected 5 transmit holding register empty 6 transmit shift register empty AL = character (unchanged) If function unsuccessful (timed-out) AH bit 7 = 1 AL = character (unchanged) ──────────────────────────────────────────────────────────────────────────── Int 14H [PC] [AT] [PS/2] Function 02H Read character from communications port ──────────────────────────────────────────────────────────────────────────── Reads a character from the specified serial communications port, also returning the port's status. Call with: AH = 02H DX = communications port number (0 = COM1, 1 = COM2, etc.) Returns: If function successful AH bit 7 = 0 AH bits 0─6 = status Bit Significance (if set) 1 overrun error detected 2 parity error detected 3 framing error detected 4 break detected AL = character If function unsuccessful (timed-out) AH bit 7 = 1 ──────────────────────────────────────────────────────────────────────────── Int 14H [PC] [AT] [PS/2] Function 03H Get communications port status ──────────────────────────────────────────────────────────────────────────── Returns the status of the specified serial communications port. Call with: AH = 03H DX = communications port number (0 = COM1, 1 = COM2, etc.) Returns: AH = port status (see Int 14H Function 00H) AL = modem status (see Int 14H Function 00H) ──────────────────────────────────────────────────────────────────────────── Int 14H [PS/2] Function 04H Extended initialize communications port ──────────────────────────────────────────────────────────────────────────── Initializes a serial communications port to a desired baud rate, parity, word length, and number of stop bits. Provides a superset of Int 14H Function 00H capabilities for PS/2 machines. Call with: AH = 04H AL = break flag 00H no break 01H break BH = parity 00H none 01H odd 02H even 03H stick parity odd 04H stick parity even BL = stop bits 00H 1 stop bit 01H 2 stop bits if word length = 6─8 bits 01H 1.5 stop bits if word length = 5 bits CH = word length 00H 5 bits 01H 6 bits 02H 7 bits 03H 8 bits CL = baud rate 00H 110 baud 01H 150 baud 02H 300 baud 03H 600 baud 04H 1200 baud 05H 2400 baud 06H 4800 baud 07H 9600 baud 08H 19,200 baud DX = communications port number (0 = COM1, 1 = COM2, etc.) Returns: AH = port status (see Int 14H Function 00H) AL = modem status (see Int 14H Function 00H) ──────────────────────────────────────────────────────────────────────────── Int 14H [PS/2] Function 05H Extended communications port control ──────────────────────────────────────────────────────────────────────────── Reads or sets the modem control register (MCR) for the specified serial communications port. Call with: AH = 05H AL = subfunction 00H to read modem control register 01H to write modem control register BL = modem control register contents (if AL = 01H) Bit(s) Significance 0 data-terminal ready 1 request-to-send 2 Out1 3 Out2 4 loop (for testing) 5─7 reserved DX = communications port number (0 = COM1, 1 = COM2, etc.) Returns: If called with AL = 00H BL = modem control register contents (see above) If called with AL = 01H AH = port status (see Int 14H Function 00H) AL = modem status (see Int 14H Function 00H) ──────────────────────────────────────────────────────────────────────────── Int 15H [PC] Function 00H Turn on cassette motor ──────────────────────────────────────────────────────────────────────────── Turns on the motor of the cassette tape drive. Call with: AH = 00H Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status 86H if cassette not present Note: ■ This function is available only on the PC and the PCjr. It is not supported on the PC/XT and all subsequent models. ──────────────────────────────────────────────────────────────────────────── Int 15H [PC] Function 01H Turn off cassette motor ──────────────────────────────────────────────────────────────────────────── Turns off the motor of the cassette tape drive. Call with: AH = 01H Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status 86H if cassette not present Note: ■ This function is available only on the PC and the PCjr. It is not supported on the PC/XT and all subsequent models. ──────────────────────────────────────────────────────────────────────────── Int 15H [PC] Function 02H Read cassette ──────────────────────────────────────────────────────────────────────────── Reads one or more 256-byte blocks of data from the cassette tape drive to memory. Call with: AH = 02H CX = number of bytes to read ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear DX = number of bytes actually read ES:BX = segment:offset + 1 of last byte read If function unsuccessful Carry flag = set AH = status 01H if CRC error 02H if bit signals scrambled 04H if no data found 80H if invalid command 86H if cassette not present Note: ■ This function is available only on the PC and on the PCjr. It is not supported on the PC/XT and all subsequent models. ──────────────────────────────────────────────────────────────────────────── Int 15H [PC] Function 03H Write cassette ──────────────────────────────────────────────────────────────────────────── Writes one or more 256-byte blocks of data from memory to the cassette tape drive. Call with: AH = 03H CX = number of bytes to write ES:BX = segment:offset of buffer Returns: If function successful Carry flag = clear CX = 00H ES:BX = segment:offset + 1 of last byte written If function unsuccessful Carry flag = set AH = status 80H if invalid command 86H if cassette not present Note: ■ This function is available only on the PC and on the PCjr. It is not supported on the PC/XT and all subsequent models. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function 0FH (15) Format ESDI drive periodic interrupt ──────────────────────────────────────────────────────────────────────────── Invoked by the ROM BIOS on the ESDI Fixed Disk Drive Adapter/A during a format or surface analysis operation after each cylinder is completed. Call with: AH = 0FH AL = phase code 0 = reserved 1 = surface analysis 2 = formatting Returns: If formatting or analysis should continue Carry flag = clear If formatting or analysis should be terminated Carry flag = set Notes: ■ This function call can be captured by a program so that it will be notified as each cylinder is formatted or analyzed. The program can count interrupts for each phase to determine the current cylinder number. ■ The default ROM BIOS handler for this function returns with the carry flag set. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function 21H (33) Subfunction 00H Read POST error log ──────────────────────────────────────────────────────────────────────────── Returns error information that was accumulated during the most recent power-on self-test (POST). Call with: AH = 21H AL = 00H Returns: If function successful Carry flag = clear AH = 00H BX = number of POST error codes stored ES:DI = segment:offset of POST error log If function unsuccessful Carry flag = set AH = status 80H = invalid command 86H = function not supported Notes: ■ The error log consists of single-word entries. The first byte of an entry is the device error code, and the second is the device identifier. ■ This function is not available on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function 21H (33) Subfunction 01H Write POST error log ──────────────────────────────────────────────────────────────────────────── Adds an entry to the power-on self-test (POST) error log. Call with: AH = 21H AL = 01H BH = device identifier BL = device error code Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status 01H = error list full 80H = invalid command 86H = function not supported Note: ■ This function is not available on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function 4FH (79) Keyboard intercept ──────────────────────────────────────────────────────────────────────────── Invoked for each keystroke by the ROM BIOS's Int 09H keyboard interrupt handler. Call with: AH = 4FH AL = scan code Returns: If scan code consumed Carry flag = clear If scan code not consumed Carry flag = set AL = unchanged or new scan code Notes: ■ An operating system or a resident utility can capture this function to filter the raw keyboard data stream. The new handler can substitute a new scan code, return the same scan code, or return the carry flag clear causing the keystroke to be discarded. The default ROM BIOS routine simply returns the scan code unchanged. ■ A program can call Int 15H Function C0H to determine whether the host machine's ROM BIOS supports this keyboard intercept. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 80H (128) Device open ──────────────────────────────────────────────────────────────────────────── Acquires ownership of a logical device for a process. Call with: AH = 80H BX = device ID CX = process ID Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status Note: ■ This function call, along with Int 15H Functions 81H and 82H, defines a simple protocol that can be used to arbitrate usage of devices by multiple processes. A multitasking program manager would be expected to capture Int 15H and provide the appropriate service. The default BIOS routine for this function simply returns with the carry flag clear and AH = 00H. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 81H (129) Device close ──────────────────────────────────────────────────────────────────────────── Releases ownership of a logical device for a process. Call with: AH = 81H BX = device ID CX = process ID Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status Note: ■ A multitasking program manager would be expected to capture Int 15H and provide the appropriate service. The default BIOS routine for this function simply returns with the carry flag clear and AH = 00H. See also Int 15H Functions 80H and 82H. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 82H (130) Process termination ──────────────────────────────────────────────────────────────────────────── Releases ownership of all logical devices for a process that is about to terminate. Call with: AH = 82H BX = process ID Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status Note: ■ A multitasking program manager would be expected to capture Int 15H and provide the appropriate service. The default BIOS routine for this function simply returns with the carry flag clear and AH = 00H. See also Int 15H Functions 80H and 81H. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 83H (131) Event wait ──────────────────────────────────────────────────────────────────────────── Requests setting of a semaphore after a specified interval or cancels a previous request. Call with: If requesting event wait AH = 83H AL = 00H CX:DX = microseconds ES:BX = segment:offset of semaphore byte If canceling event wait AH = 83H AL = 01H Returns: If called with AL = 00H, and function successful Carry flag = clear If called with AL = 00H, and function unsuccessful (Event Wait already active) Carry flag = set If called with AL = 01H Nothing Notes: ■ The function call returns immediately. If the function is successful, bit 7 of the semaphore byte is set when the specified interval has elapsed. The calling program is responsible for clearing the semaphore before requesting this function. ■ The actual duration of an event wait is always an integral multiple of 976 microseconds. The CMOS date/clock chip interrupts are used to implement this function. ■ Use of this function allows programmed, hardware-independent delays at a finer resolution than can be obtained through use of the MS-DOS Get Time function (Int 21H Function 2CH, which returns time in hundredths of a second). ■ See also Int 15H Function 86H, which suspends the calling program for the specified interval in milliseconds. ■ This function is not supported on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 84H (132) Read joystick ──────────────────────────────────────────────────────────────────────────── Returns the joystick switch settings and potentiometer values. Call with: AH = 84H DX = subfunction 00H to read switch settings 01H to read resistive inputs Returns: If function successful Carry flag = clear and, if called with DX = 00H AL = switch settings (bits 4─7) or, if called with DX = 01H AX = A(x) value BX = A(y) value CX = B(x) value DX = B(y) value If function unsuccessful Carry flag = set Notes: ■ An error condition is returned if DX does not contain a valid subfunction number. ■ If no game adapter is installed, AL is returned as 00H for Subfunction 00H (i.e., all switches open); AX, BX, CX, and DX are returned containing 00H for Subfunction 01H. ■ Using a 250 KOhm joystick, the potentiometer values usually lie within the srange 0─416 (0000─01A0H). ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 85H (133) SysReq key ──────────────────────────────────────────────────────────────────────────── Invoked by the ROM BIOS keyboard driver when the SysReq key is detected. Call with: AH = 85H AL = key status 00H if key make (depression) 01H if key break (release) Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status Note: ■ The ROM BIOS handler for this function call is a dummy routine that always returns a success status unless called with an invalid subfunction number in AL. A multitasking program manager would be expected to capture Int 15H so that it can be notified when the user strikes the SysReq key. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 86H (134) Delay ──────────────────────────────────────────────────────────────────────────── Suspends the calling program for a specified interval in microseconds. Call with: AH = 86H CX:DX = microseconds to wait Returns: If function successful (wait was performed) Carry flag = clear If function unsuccessful (wait was not performed) Carry flag = set Notes: ■ The actual duration of the wait is always an integral multiple of 976 microseconds. ■ Use of this function allows programmed, hardware-independent delays at a finer resolution than can be obtained through use of the MS-DOS Get Time function (Int 21H Function 2CH, which returns time in hundredths of a second). ■ See also Int 15H Function 83H, which triggers a semaphore after a specified interval but does not suspend the calling program. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 87H (135) Move extended memory block ──────────────────────────────────────────────────────────────────────────── Transfers data between conventional memory and extended memory. Call with: AH = 87H CX = number of words to move ES:SI = segment:offset of Global Descriptor Table (see Notes) Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status 01H if RAM parity error 02H if exception interrupt error 03H if gate address line 20 failed Notes: ■ Conventional memory lies at addresses below the 640 KB boundary, and is used for the execution of MS-DOS and its application programs. Extended memory lies at addresses above 1 MB, and can only be accessed by an 80286 or 80386 CPU running in protected mode. As much as 15 MB of extended memory can be installed in an IBM PC/AT or compatible. ■ The Global Descriptor Table (GDT) used by this function must be set up as follows: Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 00H─0FH reserved (should be 0) 10H─11H segment length in bytes (2*CX - 1 or greater) 12H─14H 24-bit source address 15H access rights byte (always 93H) 16H─17H reserved (should be 0) 18H─19H segment length in bytes (2*CX - 1 or greater) 1AH─1CH 24-bit destination address 1DH access rights byte (always 93H) 1EH─2FH reserved (should be 0) ──────────────────────────────────────────────────────────────────────── The table is composed of six 8-byte descriptors to be used by the CPU in protected mode. The four descriptors in offsets 00H─0FH and 20H─2FH are filled in by the ROM BIOS before the CPU mode switch. ■ The addresses used in the descriptor table are linear (physical) 24-bit addresses in the range 000000H─FFFFFFH──not segments and offsets──with the least significant byte at the lowest address and the most significant byte at the highest address. ■ The block move is performed with interrupts disabled; thus, use of this function may interfere with the operation of communications programs, network drivers, or other software that relies on prompt servicing of hardware interrupts. ■ Programs and drivers that access extended memory with this function cannot be executed in the Compatibility Environment of OS/2. ■ This function is not supported on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 88H (136) Get extended memory size ──────────────────────────────────────────────────────────────────────────── Returns the amount of extended memory installed in the system. Call with: AH = 88H Returns: AX = amount of extended memory (in KB) Notes: ■ Extended memory is memory at addresses above 1 MB, which can only be accessed by an 80286 or 80386 CPU running in protected mode. Because MS-DOS is a real-mode operating system, extended memory can be used for storage of volatile data but cannot be used for execution of programs. ■ Programs and drivers that use this function cannot be executed in the Compatibility Environment of OS/2. ■ This function is not supported on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 89H (137) Enter protected mode ──────────────────────────────────────────────────────────────────────────── Switches the CPU from real mode into protected mode. Call with: AH = 89H BH = interrupt number for IRQ0, written to ICW2 of 8259 PIC #1 (must be evenly divisible by 8, determines IRQ0─IRQ7) BL = interrupt number for IRQ8, written to ICW2 of 8259 PIC #2 (must be evenly divisible by 8, determines IRQ8─IRQ15) ES:SI = segment:offset of Global Descriptor Table (GDT) Returns: If function successful (CPU is in protected mode) Carry flag = clear AH = 00H CS = user-defined selector DS = user-defined selector ES = user-defined selector SS = user-defined selector If function unsuccessful (CPU is in real mode) Carry flag = set AH = FFH Notes: ■ The Global Descriptor Table must contain eight descriptors set up as follows: Offset Descriptor usage ──────────────────────────────────────────────────────────────────────── 00H dummy descriptor (initialized to 0) 08H Global Descriptor Table (GDT) 10H Interrupt Descriptor Table (IDT) 18H user's data segment (DS) 20H user's extra segment (ES) 28H user's stack segment (SS) 30H user's code segment (CS) 38H BIOS code segment ──────────────────────────────────────────────────────────────────────── The user must initialize the first seven descriptors; the eighth is filled in by the ROM BIOS to provide addressability for its own execution. The calling program may modify and use the eighth descriptor for any purpose after return from this function call. ■ This function is not supported on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 90H (144) Device wait ──────────────────────────────────────────────────────────────────────────── Invoked by the ROM BIOS fixed disk, floppy disk, printer, network, and keyboard drivers prior to performing a programmed wait for I/O completion. Call with: AH = 90H AL = device type 00H─7FH serially reusable devices 80H─BFH reentrant devices C0H─FFH wait-only calls, no corresponding Post function ES:BX = segment:offset of request block for device types 80H─FFH Returns: If no wait (driver must perform its own time-out) Carry flag = clear AH = 00H If wait was performed Carry flag = set Notes: ■ Predefined device types are: 00H disk (may time-out) 01H floppy disk (may time-out) 02H keyboard (no time-out) 03H pointing device (PS/2, may time-out) 80H network (no time-out) FCH fixed disk reset (PS/2, may time-out) FDH floppy disk drive motor start (may time-out) FEH printer (may time-out) ■ For network adapters, ES:BX points to a network control block (NCB). ■ A multitasking program manager would be expected to capture Int 15H Function 90H so that it can dispatch other tasks while I/O is in progress. The default BIOS routine for this function simply returns with the carry flag clear and AH = 00H. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function 91H (145) Device post ──────────────────────────────────────────────────────────────────────────── Invoked by the ROM BIOS fixed disk, floppy disk, network, and keyboard drivers to signal that I/O is complete and/or the device is ready. Call with: AH = 91H AL = device type 00H─7FH serially reusable devices 80H─BFH reentrant devices ES:BX = segment:offset of request block for device types 80H─BFH Returns: AH = 00H Notes: ■ Predefined device types that may use Device Post are: 00H disk (may time-out) 01H floppy disk (may time-out) 02H keyboard (no time-out) 03H pointing device (PS/2, may time-out) 80H network (no time-out) ■ The ROM BIOS printer routine does not invoke this function because printer output is not interrupt driven. ■ A multitasking program manager would be expected to capture Int 15H Function 91H so that it can be notified when I/O is completed and awaken the requesting task. The default BIOS routine for this function simply returns with the carry flag clear and AH = 00H. ──────────────────────────────────────────────────────────────────────────── Int 15H [AT] [PS/2] Function C0H (192) Get system environment ──────────────────────────────────────────────────────────────────────────── Returns a pointer to a table containing various information about the system configuration. Call with: AH = C0H Returns: ES:BX = segment:offset of configuration table (see Notes) Notes: ■ The format of the system configuration table is as follows: Byte(s) Contents ──────────────────────────────────────────────────────────────────────── 00H─01H length of table in bytes 02H system model (see following Note) 03H system submodel (see following Note) 04H BIOS revision level 05H configuration flags Bit Significance (if set) 0 reserved 1 Micro Channel implemented 2 extended BIOS data area allocated 3 Wait for External Event is available 4 keyboard intercept (Int 15H Function 4FH) available 5 real-time clock available 6 slave 8259 present (cascaded IRQ2) 7 DMA channel 3 used 06H─09H reserved ──────────────────────────────────────────────────────────────────────── ■ The system model and type bytes are assigned as follows: Machine Model byte Submodel byte ──────────────────────────────────────────────────────────────────────── PC FFH PC/XT FEH PC/XT FBH 00H or 01H PCjr FDH PC/AT FCH 00H or 01H PC/XT-286 FCH 02H PC Convertible F9H PS/2 Model 30 FAH 00H PS/2 Model 50 FCH 04H PS/2 Model 60 FCH 05H PS/2 Model 70 F8H 04H or 09H PS/2 Model 80 F8H 00H or 01H ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C1H (193) Get address of extended BIOS data area ──────────────────────────────────────────────────────────────────────────── Returns the segment address of the base of the extended BIOS data area. Call with: AH = C1H Returns: If function successful Carry flag = clear ES = segment of extended BIOS data area If function unsuccessful Carry flag = set Notes: ■ The extended BIOS data area is allocated at the high end of conventional memory during the POST (Power-On-Self-Test) sequence. The word at 0040:0013H (memory size) is updated to reflect the reduced amount of memory available for MS-DOS and application programs. The first byte in the extended BIOS data area is initialized to its length in KB. ■ A program can determine whether the extended BIOS data area exists with Int 15H Function C0H. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 00H Enable/disable pointing device ──────────────────────────────────────────────────────────────────────────── Enables or disables the system's mouse or other pointing device. Call with: AH = C2H AL = 00H BH = enable/disable flag 00H = disable 01H = enable Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status 01H if invalid function call 02H if invalid input 03H if interface error 04H if resend 05H if no far call installed ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 01H Reset pointing device ──────────────────────────────────────────────────────────────────────────── Resets the system's mouse or other pointing device, setting the sample rate, resolution, and other characteristics to their default values. Call with: AH = C2H AL = 01H Returns: If function successful Carry flag = clear AH = 00H BH = device ID If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) Notes: ■ After a reset operation, the state of the pointing device is as follows: ∙ disabled; ∙ sample rate at 100 reports per second; ∙ resolution at 4 counts per millimeter; ∙ and scaling at 1 to 1. The data package size is unchanged by this function. ■ The application can use the other Int 15H Function C2H subfunctions to initialize the pointing device to other sample rates, resolution, and scaling, and then enable the device with Int 15H Function C2H Subfunction 00H. ■ See also Int 15H Function C2H Subfunction 05H, which incidentally resets the pointing device in a similar manner. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 02H Set sample rate ──────────────────────────────────────────────────────────────────────────── Sets the sampling rate of the system's mouse or other pointing device. Call with: AH = C2H AL = 02H BH = sample rate value 00H = 10 reports per second 01H = 20 reports per second 02H = 40 reports per second 03H = 60 reports per second 04H = 80 reports per second 05H = 100 reports per second 06H = 200 reports per second Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) Note: ■ The default sample rate is 100 reports per second after a reset operation (Int 15H Function C2H Subfunction 01H). ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 03H Set resolution ──────────────────────────────────────────────────────────────────────────── Sets the resolution of the system's mouse or other pointing device. Call with: AH = C2H AL = 03H BH = resolution value 00H = 1 count per millimeter 01H = 2 counts per millimeter 02H = 4 counts per millimeter 03H = 8 counts per millimeter Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) Note: ■ The default resolution is 4 counts per millimeter after a reset operation (Int 15H Function C2H Subfunction 01H). ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 04H Get pointing device type ──────────────────────────────────────────────────────────────────────────── Returns the identification code for the system's mouse or other pointing device. Call with: AH = C2H AL = 04H Returns: If function successful Carry flag = clear AH = 00H BH = device ID If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 05H Initialize pointing device interface ──────────────────────────────────────────────────────────────────────────── Sets the data package size for the system's mouse or other pointing device, and initializes the resolution, sampling rate, and scaling to their default values. Call with: AH = C2H AL = 05H BH = data package size in bytes (1─8) Returns: If function successful Carry flag = clear AH = 00H If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) Note: ■ After this operation, the state of the pointing device is as follows: ∙ disabled; ∙ sample rate at 100 reports per second; ∙ resolution at 4 counts per millimeter; ∙ and scaling at 1 to 1. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 06H Set scaling or get status ──────────────────────────────────────────────────────────────────────────── Returns the current status of the system's mouse or other pointing device or sets the device's scaling factor. Call with: AH = C2H AL = 06H BH = extended command 00H = return device status 01H = set scaling at 1:1 02H = set scaling at 2:1 Returns: If function successful Carry flag = clear AH = 00H and, if called with BH = 00H BL = status byte Bit Significance 0 = 1 if right button pressed 1 = reserved 2 = 1 if left button pressed 3 = reserved 4 = 0 if 1:1 scaling 1 if 2:1 scaling 5 = 0 if device disabled 1 if device enabled 6 = 0 if stream mode 1 if remote mode 7 = reserved CL = resolution 00H = 1 count per millimeter 01H = 2 counts per millimeter 02H = 4 counts per millimeter 03H = 8 counts per millimeter DL = sample rate 0AH = 10 reports per second 14H = 20 reports per second 28H = 40 reports per second 3CH = 60 reports per second 50H = 80 reports per second 64H = 100 reports per second C8H = 200 reports per second If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C2H (194) Subfunction 07H Set pointing device handler address ──────────────────────────────────────────────────────────────────────────── Notifies the ROM BIOS pointing device driver of the address for a routine to be called each time pointing device data is available. Call with: AH = C2H AL = 07H ES:BX = segment:offset of user routine Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set AH = status (see Int 15H Function C2H Subfunction 00H) Notes: ■ The user's handler for pointing device data is entered via a far call with four parameters on the stack: SS:SP+0AH status SS:SP+08H x coordinate SS:SP+06H y coordinate SS:SP+04H z coordinate (always 0) The handler must exit via a far return without removing the parameters from the stack. ■ The status parameter passed to the user's handler is interpreted as follows: Bit(s) Significance (if set) ──────────────────────────────────────────────────────────────────────── 0 left button pressed 1 right button pressed 2─3 reserved 4 sign of x data is negative 5 sign of y data is negative 6 x data has overflowed 7 y data has overflowed 8─15 reserved ──────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C3H (195) Set watchdog time-out ──────────────────────────────────────────────────────────────────────────── Enables or disables a watchdog timer. Call with: AH = C3H AL = subfunction 00H to disable watchdog time-out 01H to enable watchdog time-out BX = watchdog timer counter (if AL = 01H) Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set Notes: ■ The watchdog timer generates an NMI interrupt. ■ This function is not available on the PS/2 Models 25 and 30. ──────────────────────────────────────────────────────────────────────────── Int 15H [PS/2] Function C4H (196) Programmable option select ──────────────────────────────────────────────────────────────────────────── Returns the base Programmable Option Select register address, enables a slot for setup, or enables an adapter. Call with: AH = C4H AL = subfunction 00H to return base POS adapter register address 01H to enable slot 02H to enable adapter BL = slot number (if AL = 01H) Returns: If function successful Carry flag = clear and, if called with AL = 00H DX = base POS adapter register address If function unsuccessful Carry flag = set Notes: ■ This function is available only on machines using the Micro Channel Architecture (MCA) bus. ■ After a slot is enabled with Subfunction 01H, specific information can be obtained for the adapter in that slot by performing port input operations: Port Function 100H MCA ID (low byte) 101H MCA ID (high byte) 102H Option Select Byte 1 bit 0 = 1 if enabled, = 0 if disabled 103H Option Select Byte 2 104H Option Select Byte 3 105H Option Select Byte 4 bits 6─7 = channel check indicators 106H Subaddress Extension (low byte) 107H Subaddress Extension (high byte) ──────────────────────────────────────────────────────────────────────────── Int 16H [PC] [AT] [PS/2] Function 00H Read character from keyboard ──────────────────────────────────────────────────────────────────────────── Reads a character from the keyboard, also returning the keyboard scan code. Call with: AH = 00H Returns: AH = keyboard scan code AL = ASCII character ──────────────────────────────────────────────────────────────────────────── Int 16H [PC] [AT] [PS/2] Function 01H Get keyboard status ──────────────────────────────────────────────────────────────────────────── Determines whether a character is ready for input, returning a flag and also the character itself, if one is waiting. Call with: AH = 01H Returns: If key waiting to be input Zero flag = clear AH = keyboard scan code AL = character If no key waiting Zero flag = set Note: ■ The character returned by this function when the zero flag is clear is not removed from the type-ahead buffer. The same character and scan code will be returned by the next call to Int 16H Function 00H. ──────────────────────────────────────────────────────────────────────────── Int 16H [PC] [AT] [PS/2] Function 02H Get keyboard flags ──────────────────────────────────────────────────────────────────────────── Returns the ROM BIOS flags byte that describes the state of the various keyboard toggles and shift keys. Call with: AH = 02H Returns: AL = flags Bit Significance (if set) 0 right Shift key is down 1 left Shift key is down 2 Ctrl key is down 3 Alt key is down 4 Scroll Lock on 5 Num Lock on 6 Caps Lock on 7 Insert on Note: ■ The keyboard flags byte is stored in the ROM BIOS data area at 0000:0417H. ──────────────────────────────────────────────────────────────────────────── Int 16H [PC] [AT] [PS/2] Function 03H Set repeat rate ──────────────────────────────────────────────────────────────────────────── Sets the ROM BIOS key repeat ("typematic") rate and delay. Call with: On the PC/AT and PS/2 AH = 03H AL = 05H BH = repeat delay (see Notes) BL = repeat rate (see Notes) On the PCjr AH = 03H AL = subfunction 00H to restore default rate and delay 01H to increase initial delay 02H to decrease repeat rate by one-half 03H to increase delay and decrease repeat rate by one-half 04H to turn off keyboard repeat Returns: Nothing Notes: ■ Subfunctions 00H─04H are available on the PCjr but are not supported by the PC or PC/XT ROM BIOS. Subfunction 05H is available on PC/ATs with ROM BIOS's dated 11/15/85 and later, and on the PS/2. ■ On the PC/AT and PS/2, the value in BH controls the amount of delay before the first repeat key is generated. The delay is always a multiple of 250 milliseconds: Value Delay (msec.) 00H 250 01H 500 02H 750 03H 1000 ■ On the PC/AT and PS/2, the value for the repeat rate in characters per second can be chosen from the following table: Value Repeat rate (characters per second) 00H 30.0 01H 26.7 02H 24.0 03H 21.8 04H 20.0 05H 18.5 06H 17.1 07H 16.0 08H 15.0 09H 13.3 0AH 12.0 0BH 10.9 0CH 10.0 0DH 9.2 0EH 8.6 0FH 8.0 10H 7.5 11H 6.7 12H 6.0 13H 5.5 14H 5.0 15H 4.6 16H 4.3 17H 4.0 18H 3.7 19H 3.3 1AH 3.0 1BH 2.7 1CH 2.5 1DH 2.3 1EH 2.1 1FH 2.0 ──────────────────────────────────────────────────────────────────────────── Int 16H [PC] Function 04H Set keyclick ──────────────────────────────────────────────────────────────────────────── Turns the keyboard click on or off. Call with: AH = 04H AL = subfunction 00H to turn off keyboard click 01H to turn on keyboard click Returns: Nothing Note: ■ This function is supported by the PCjr BIOS only. ──────────────────────────────────────────────────────────────────────────── Int 16H [AT] [PS/2] Function 05H Push character and scan code ──────────────────────────────────────────────────────────────────────────── Places a character and scan code in the keyboard type-ahead buffer. Call with: AH = 05H CH = scan code CL = character Returns: If function successful Carry flag = clear AL = 00H If function unsuccessful (type-ahead buffer is full) Carry flag = set AL = 01H Note: ■ This function can be used by keyboard enhancers and other utilities to interpolate keys into the data stream seen by application programs. ──────────────────────────────────────────────────────────────────────────── Int 16H [AT] [PS/2] Function 10H (16) Read character from enhanced keyboard ──────────────────────────────────────────────────────────────────────────── Reads a character and scan code from the keyboard type-ahead buffer. Call with: AH = 10H Returns: AH = keyboard scan code AL = ASCII character Note: ■ Use this function for the enhanced keyboard instead of Int 16H Function 00H. It allows applications to obtain the scan codes for the additional F11, F12, and cursor control keys. ──────────────────────────────────────────────────────────────────────────── Int 16H [AT] [PS/2] Function 11H (17) Get enhanced keyboard status ──────────────────────────────────────────────────────────────────────────── Determines whether a character is ready for input, returning a flag and also the character itself, if one is waiting. Call with: AH = 11H Returns: If key waiting to be input Zero flag = clear AH = keyboard scan code AL = character If no key waiting Zero flag = set Notes: ■ Use this function for the enhanced keyboard instead of Int 16H Function 00H. It allows applications to test for the additional F11, F12, and cursor control keys. ■ The character returned by this function when the zero flag is clear is not removed from the type-ahead buffer. The same character and scan code will be returned by the next call to Int 16H Function 10H. ──────────────────────────────────────────────────────────────────────────── Int 16H [AT] [PS/2] Function 12H (18) Get enhanced keyboard flags ──────────────────────────────────────────────────────────────────────────── Obtains the status of various enhanced keyboard special keys and keyboard driver states. Call with: AH = 12H Returns: AX = flags Bit Significance (if set) 0 right Shift key is down 1 left Shift key is down 2 either Ctrl key is down 3 either Alt key is down 4 Scroll Lock toggle is on 5 Num Lock toggle is on 6 Caps Lock toggle is on 7 Insert toggle is on 8 left Ctrl key is down 9 left Alt key is down 10 right Ctrl key is down 11 right Alt key is down 12 Scroll key is down 13 Num Lock key is down 14 Caps Lock key is down 15 SysReq key is down Note: ■ Use this function for the enhanced keyboard instead of Int 16H Function 02H. ──────────────────────────────────────────────────────────────────────────── Int 17H [PC] [AT] [PS/2] Function 00H Write character to printer ──────────────────────────────────────────────────────────────────────────── Sends a character to the specified parallel printer interface port and returns the current status of the port. Call with: AH = 00H AL = character DX = printer number (0 = LPT1, 1 = LPT2, 2 = LPT3) Returns: AH = status Bit Significance (if set) 0 printer timed-out 1 unused 2 unused 3 I/O error 4 printer selected 5 out of paper 6 printer acknowledge 7 printer not busy ──────────────────────────────────────────────────────────────────────────── Int 17H [PC] [AT] [PS/2] Function 01H Initialize printer port ──────────────────────────────────────────────────────────────────────────── Initializes the specified parallel printer interface port and returns its status. Call with: AH = 01H DX = printer number (0 = LPT1, 1 = LPT2, 2 = LPT3) Returns: AH = status (see Int 17H Function 00H) ──────────────────────────────────────────────────────────────────────────── Int 17H [PC] [AT] [PS/2] Function 02H Get printer status ──────────────────────────────────────────────────────────────────────────── Returns the current status of the specified parallel printer interface port. Call with: AH = 02H DX = printer number (0 = LPT1, 1 = LPT2, 2 = LPT3) Returns: AH = status (see Int 17H Function 00H) ──────────────────────────────────────────────────────────────────────────── Int 18H [PC] [AT] [PS/2] ROM BASIC ──────────────────────────────────────────────────────────────────────────── Transfers control to ROM BASIC. Call with: Nothing Returns: Nothing Note: ■ This function is invoked when the system is turned on or restarted if attempts to read a boot sector from the fixed disk or floppy disk drives are unsuccessful. ──────────────────────────────────────────────────────────────────────────── Int 19H [PC] [AT] [PS/2] Reboot system ──────────────────────────────────────────────────────────────────────────── Reboots the operating system from the floppy disk or fixed disk drive. Call with: Nothing Returns: Nothing Notes: ■ The bootstrap routine reads Sector 1, Track 0 into memory at location 0000:7C00H and transfers control to the same address. If attempts to read a boot sector from the floppy disk or fixed disk are unsuccessful, control is transferred to ROM BASIC by execution of an Int 18H. ■ If location 0000:0472H does not contain the value 1234H, a memory test will be performed before reading the boot sector. ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 00H Get tick count ──────────────────────────────────────────────────────────────────────────── Returns the contents of the clock tick counter. Call with: AH = 00H Returns: AL = rolled-over flag 00H if midnight not passed since last read <>00H if midnight was passed since last read CX:DX = tick count (high 16 bits in CX) Notes: ■ This function is supported by the PC/XT and PCjr ROM BIOS, but is not present in the ROM BIOS for the original PC. ■ The returned value is the cumulative number of clock ticks since midnight. There are 18.2 clock ticks per second. When the counter reaches 1,573,040, it is cleared to zero, and the rolled-over flag is set. ■ The rolled-over flag is cleared by this function call, so the flag will only be returned nonzero once per day. ■ Int 1AH Function 01H can be used to set the clock tick counter to an arbitrary 32-bit value. ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 01H Set tick count ──────────────────────────────────────────────────────────────────────────── Stores a 32-bit value in the clock tick counter. Call with: AH = 01H CX:DX = tick count (high 16 bits in CX) Returns: Nothing Notes: ■ This function is supported by the PC/XT and PCjr ROM BIOS, but is not present in the ROM BIOS for the original PC. ■ Int 1AH Function 00H is used to read the value of the clock tick counter. ■ The rolled-over flag is cleared by this function call. ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 02H Get time ──────────────────────────────────────────────────────────────────────────── Reads the current time from the CMOS time/date chip. Call with: AH = 02H Returns: CH = hours in binary coded decimal (BCD) CL = minutes in BCD DH = seconds in BCD DL = daylight-saving-time code 00H if standard time 01H if daylight saving time and, if clock running Carry flag = clear or, if clock stopped Carry flag = set ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 03H Set time ──────────────────────────────────────────────────────────────────────────── Sets the time in the CMOS time/date chip. Call with: AH = 03H CH = hours in binary coded decimal (BCD) CL = minutes in BCD DH = seconds in BCD DL = daylight-saving-time code 00H if standard time 01H if daylight saving time Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 04H Get date ──────────────────────────────────────────────────────────────────────────── Reads the current date from the CMOS time/date chip. Call with: AH = 04H Returns: CH = century (19 or 20) in binary coded decimal (BCD) CL = year in BCD DH = month in BCD DL = day in BCD and, if clock running Carry flag = clear or, if clock stopped Carry flag = set ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 05H Set date ──────────────────────────────────────────────────────────────────────────── Sets the date in the CMOS time/date chip. Call with: AH = 05H CH = century (19 or 20) in binary coded decimal (BCD) CL = year in BCD DH = month in BCD DL = day in BCD Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 06H Set alarm ──────────────────────────────────────────────────────────────────────────── Sets an alarm in the CMOS date/time chip. Call with: AH = 06H CH = hours in binary coded decimal (BCD) CL = minutes in BCD DH = seconds in BCD Returns: If function successful Carry flag = clear If function unsuccessful (alarm already set, or clock stopped) Carry flag = set Notes: ■ A side effect of this function is that the clock chip's interrupt level (IRQ8) is enabled. ■ Only one alarm may be active at any given time. The alarm occurs every 24 hours at the specified time until it is reset with Int 1AH Function 07H. ■ The program using this function must place the address of its interrupt handler for the alarm in the vector for Int 4AH. ──────────────────────────────────────────────────────────────────────────── Int 1AH [AT] [PS/2] Function 07H Reset alarm ──────────────────────────────────────────────────────────────────────────── Cancels any pending alarm request on the CMOS date/time chip. Call with: AH = 07H Returns: Nothing Note: ■ This function does not disable the clock chip's interrupt level (IRQ8). ──────────────────────────────────────────────────────────────────────────── Int 1AH [PS/2] Function 0AH (10) Get day count ──────────────────────────────────────────────────────────────────────────── Returns the contents of the system's day counter. Call with: AH = 0AH Returns: If function successful Carry flag = clear CX = count of days since January 1, 1980 If function unsuccessful Carry flag = set ──────────────────────────────────────────────────────────────────────────── Int 1AH [PS/2] Function 0BH (11) Set day count ──────────────────────────────────────────────────────────────────────────── Stores an arbitrary value in the system's day counter. Call with: AH = 0BH CX = count of days since January 1, 1980 Returns: If function successful Carry flag = clear If function unsuccessful Carry flag = set ──────────────────────────────────────────────────────────────────────────── Int 1AH [PC] Function 80H (128) Set sound source ──────────────────────────────────────────────────────────────────────────── Sets up the source for tones that will appear on the PCjr's "Audio Out" or RF modulator. Call with: AH = 80H AL = sound source 00H if 8253 programmable timer, channel 2 01H if cassette input 02H if "Audio In" line on I/O channel 03H if sound generator chip Returns: Nothing Note: ■ This function is supported on the PCjr only. ──────────────────────────────────────────────────────────────────────────── Int 33H Microsoft Mouse driver ──────────────────────────────────────────────────────────────────────────── The Microsoft Mouse driver makes its functions available to application programs via Int 33H. These functions have become a de facto standard for pointer device drivers of all varieties. Unlike the other function calls described in this section, the Microsoft Mouse driver is not part of the ROM BIOS but is loaded by a DEVICE= directive in the CONFIG.SYS file. All mouse-function information applies to the Microsoft Mouse driver version 6. Earlier versions of the driver may not support all of these functions. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 00H Reset mouse and get status ──────────────────────────────────────────────────────────────────────────── Initializes the mouse driver and returns the driver status. If the mouse pointer was previously visible, it is removed from the screen, and any previously installed user handlers for mouse events are disabled. Call with: AX = 0000H Returns: If mouse support is available AX = FFFFH BX = number of mouse buttons If mouse support is not available AX = 0000H Note: ■ After a call to this function, the mouse driver is initialized to the following state: ∙ Mouse pointer at screen center (see Int 33H Functions 03H and 04H) ∙ Display page for mouse pointer set to zero (see Int 33H Functions 1DH and 1EH) ∙ Mouse pointer hidden (see Int 33H Functions 01H, 02H, and 10H) ∙ Mouse pointer set to default arrow shape in graphics modes, or reverse block in text modes (see Int 33H Functions 09H and 0AH) ∙ User mouse event handler disabled (see Int 33H Functions 0CH and 14H) ∙ Light pen emulation enabled (see Int 33H Functions 0DH and 0EH) ∙ Horizontal mickeys to pixels ratio at 8 to 8, vertical ratio at 16 to 8 (see Int 33H Function 0FH) ∙ Double speed threshold set to 64 mickeys/second (see Int 33H Function 19H) ∙ Minimum and maximum horizontal and vertical pointer position limits set to include the entire screen in the current display mode (see Int 33H Functions 07H and 08H) ──────────────────────────────────────────────────────────────────────────── Int 33H Function 01H Show mouse pointer ──────────────────────────────────────────────────────────────────────────── Displays the mouse pointer, and cancels any mouse pointer exclusion area previously defined with Int 33H Function 10H. Call with: AX = 0001H Returns: Nothing Note: ■ A counter is maintained which is decremented by calls to Int 33H Function 02H (Hide Mouse Pointer) and incremented (if nonzero) by this function. When the counter is zero or becomes zero, the mouse pointer is displayed. When the mouse driver is reset with Int 33H Function 00H, the counter is forced to -1. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 02H Hide mouse pointer ──────────────────────────────────────────────────────────────────────────── Removes the mouse pointer from the display. The driver continues to track the mouse position. Call with: AX = 0002H Returns: Nothing Note: ■ A counter is maintained which is decremented by calls to this function and incremented (if nonzero) by Int 33H Function 01H (Show Mouse Pointer). When the counter is zero, the mouse pointer is displayed. When the mouse driver is reset with Int 33H Function 00H, the counter is forced to -1. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 03H Get mouse position and button status ──────────────────────────────────────────────────────────────────────────── Returns the current mouse button status and pointer position. Call with: AX = 0003H Returns: BX = mouse button status Bit(s) Significance (if set) 0 left button is down 1 right button is down 2 center button is down 3─15 reserved (0) CX = horizontal (X) coordinate DX = vertical (Y) coordinate Note: ■ Coordinates are returned in pixels regardless of the current display mode. Position (x,y) = (0,0) is the upper left corner of the screen. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 04H Set mouse pointer position ──────────────────────────────────────────────────────────────────────────── Sets the position of the mouse pointer. The pointer is displayed at the new position unless it has been hidden with Int 33H Function 02H, or the new position lies within an exclusion area defined with Int 33H Function 10H. Call with: AX = 0004H CX = horizontal (X) coordinate DX = vertical (Y) coordinate Returns: Nothing Notes: ■ Coordinates are specified in pixels regardless of the current display mode. Position (x,y) = (0,0) is the upper left corner of the screen. ■ The position is adjusted if necessary to lie within the horizontal and vertical limits specified with a previous call to Int 33H Functions 07H and 08H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 05H Get button press information ──────────────────────────────────────────────────────────────────────────── Returns the current status of all mouse buttons, and the number of presses and position of the last press for a specified mouse button since the last call to this function for that button. The press counter for the button is reset to zero. Call with: AX = 0005H BX = button identifier 0 = left button 1 = right button 2 = center button Returns: AX = button status Bit(s) Significance (if set) 0 left button is down 1 right button is down 2 center button is down 3─15 reserved (0) BX = button press counter CX = horizontal (X) coordinate of last button press DX = vertical (Y) coordinate of last button press ──────────────────────────────────────────────────────────────────────────── Int 33H Function 06H Get button release information ──────────────────────────────────────────────────────────────────────────── Returns the current status of all mouse buttons, and the number of releases and position of the last release for a specified mouse button since the last call to this function for that button. The release counter for the button is reset to zero. Call with: AX = 0006H BX = button identifier 0 = left button 1 = right button 2 = center button Returns: AX = button status Bit(s) Significance (if set) 0 left button is down 1 right button is down 2 center button is down 3─15 reserved (0) BX = button release counter CX = horizontal (X) coordinate of last button release DX = vertical (Y) coordinate of last button release ──────────────────────────────────────────────────────────────────────────── Int 33H Function 07H Set horizontal limits for pointer ──────────────────────────────────────────────────────────────────────────── Limits the mouse pointer display area by assigning minimum and maximum horizontal (X) coordinates for the mouse pointer. Call with: AX = 0007H CX = minimum horizontal (X) coordinate DX = maximum horizontal (X) coordinate Returns: Nothing Notes: ■ If the minimum value is greater than the maximum value, the two values are swapped. ■ The mouse pointer will be moved if necessary so that it lies within the specified horizontal coordinates. ■ See also Int 33H Function 10H, which defines an exclusion area for the mouse pointer. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 08H Set vertical limits for pointer ──────────────────────────────────────────────────────────────────────────── Limits the mouse pointer display area by assigning minimum and maximum vertical (Y) coordinates for the mouse pointer. Call with: AX = 0008H CX = minimum vertical (Y) coordinate DX = maximum vertical (Y) coordinate Returns: Nothing Notes: ■ If the minimum value is greater than the maximum value, the two values are swapped. ■ The mouse pointer will be moved if necessary so that it lies within the specified vertical coordinates. ■ See also Int 33H Function 10H, which defines an exclusion area for the mouse pointer. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 09H Set graphics pointer shape ──────────────────────────────────────────────────────────────────────────── Defines the shape, color, and hot spot of the mouse pointer in graphics modes. Call with: AX = 0009H BX = hot spot offset from left CX = hot spot offset from top ES:DX = segment:offset of pointer image buffer Returns: Nothing Notes: ■ The pointer image buffer is 64 bytes long. The first 32 bytes contain a bit mask which is ANDed with the screen image, and the second 32 bytes contain a bit mask which is XORed with the screen image. ■ The hot spot is relative to the upper left corner of the pointer image, and each pixel offset must be in the range -16 through 16. In display modes 4 and 5, the horizontal offset must be an even number. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 0AH (10) Set text pointer type ──────────────────────────────────────────────────────────────────────────── Defines the shape and attributes of the mouse pointer in text modes. Call with: AX = 000AH BX = pointer type 0 = software cursor 1 = hardware cursor CX = AND mask value (if BX = 0) or starting line for cursor (if BX = 1) DX = XOR mask value (if BX = 0) or ending line for cursor (if BX = 1) Returns: Nothing Notes: ■ If the software text cursor is selected (BX = 0), the masks in CX and DX are mapped as follows: Bit(s) Significance ──────────────────────────────────────────────────────────────────────── 0─7 character code 8─10 foreground color 11 intensity 12─14 background color 15 blink ──────────────────────────────────────────────────────────────────────── For example, the following values would yield a software mouse cursor that inverts the foreground and background colors: AX = 000AH BX = 0000H CX = 77FFH DX = 7700H ■ When the hardware text cursor is selected (BX = 1), the values in CX and DX are the starting and ending scan lines for the blinking cursor generated by the video adapter. The maximum scan line which may be used depends on the type of adapter and the current display mode. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 0BH (11) Read mouse motion counters ──────────────────────────────────────────────────────────────────────────── Returns the net mouse displacement since the last call to this function. The returned value is in mickeys; a positive number indicates travel to the right or downwards, a negative number indicates travel to the left or upwards. One mickey represents approximately 1/200 of an inch of mouse movement. Call with: AX = 000BH Returns: CX = horizontal (X) mickey count DX = vertical (Y) mickey count ──────────────────────────────────────────────────────────────────────────── Int 33H Function 0CH (12) Set user-defined mouse event handler ──────────────────────────────────────────────────────────────────────────── Sets the address and event mask for an application program's mouse event handler. The handler is called by the mouse driver whenever the specified mouse events occur. Call with: AX = 000CH CX = event mask Bit(s) Significance (if set) 0 mouse movement 1 left button pressed 2 left button released 3 right button pressed 4 right button released 5 center button pressed 6 center button released 7─15 reserved (0) ES:DX = segment:offset of handler Returns: Nothing Notes: ■ The user-defined event handler is entered from the mouse driver by a far call with registers set up as follows: AX mouse event flags (see event mask) BX button state Bit(s) Significance (if set) 0 left button is down 1 right button is down 2 center button is down 3─15 reserved (0) CX horizontal (X) pointer coordinate DX vertical (Y) pointer coordinate SI last raw vertical mickey count DI last raw horizontal mickey count DS mouse driver data segment ■ If an event does not generate a call to the user-defined handler because its bit is not set in the event mask, it is still reported in the event flags during calls to the handler for events which are enabled. ■ Calls to the handler are disabled with Int 33H Function 00H or by calling this function with an event mask of zero. ■ See also Int 33H Functions 14H and 18H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 0DH (13) Turn on light pen emulation ──────────────────────────────────────────────────────────────────────────── Enables light pen emulation by the mouse driver for IBM BASIC. A "pen down" condition is created by pressing the left and right mouse buttons simultaneously. Call with: AX = 000DH Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 33H Function 0EH (14) Turn off light pen emulation ──────────────────────────────────────────────────────────────────────────── Disables light pen emulation by the mouse driver for IBM BASIC. Call with: AX = 000EH Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 33H Function 0FH (15) Set mickeys to pixels ratio ──────────────────────────────────────────────────────────────────────────── Sets the number of mickeys per 8 pixels for horizontal and vertical mouse motion. One mickey represents approximately 1/200 of an inch of mouse travel. Call with: AX = 000FH CX = horizontal mickeys (1─32,767, default = 8) DX = vertical mickeys (1─32,767, default = 16) Returns: Nothing ──────────────────────────────────────────────────────────────────────────── Int 33H Function 10H (16) Set mouse pointer exclusion area ──────────────────────────────────────────────────────────────────────────── Defines an exclusion area for the mouse pointer. When the mouse pointer lies within the specified area, it is not displayed. Call with: AX = 0010H CX = upper left X coordinate DX = upper left Y coordinate SI = lower right X coordinate DI = lower right Y coordinate Returns: Nothing Note: ■ The exclusion area is replaced by another call to this function or cancelled by Int 33H Functions 00H or 01H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 13H (19) Set double speed threshold ──────────────────────────────────────────────────────────────────────────── Sets the threshold speed for doubling pointer motion on the screen. The default threshold speed is 64 mickeys/second. Call with: AX = 0013H DX = threshold speed in mickeys/second Returns: Nothing Note: ■ Doubling of pointer motion can be effectively disabled by setting the threshold to a very large value (such as 10,000). ──────────────────────────────────────────────────────────────────────────── Int 33H Function 14H (20) Swap user-defined mouse event handlers ──────────────────────────────────────────────────────────────────────────── Sets the address and event mask for an application program's mouse event handler and returns the address and event mask for the previous handler. The newly installed handler is called by the mouse driver whenever the specified mouse events occur. Call with: AX = 0014H CX = event mask Bit(s) Significance (if set) 0 mouse movement 1 left button pressed 2 left button released 3 right button pressed 4 right button released 5 center button pressed 6 center button released 7─15 reserved (0) ES:DX = segment:offset of event handler Returns: CX = previous event mask ES:DX = segment:offset of previous handler Notes: ■ The Notes for Int 33H Function 0CH describe the information passed to the user-defined event handler. See also Int 33H Function 18H. ■ Calls to the event handler are disabled with Int 33H Function 00H or by setting an event mask of zero. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 15H (21) Get mouse save state buffer size ──────────────────────────────────────────────────────────────────────────── Gets the size of the buffer required to store the current state of the mouse driver. Call with: AX = 0015H Returns: BX = buffer size (bytes) Note: ■ See also Int 33H Functions 16H and 17H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 16H (22) Save mouse driver state ──────────────────────────────────────────────────────────────────────────── Saves the mouse driver state in a user buffer. The minimum size for the buffer must be determined by a previous call to Int 33H Function 15H. Call with: AX = 0016H ES:DX = segment:offset of buffer Returns: Nothing Note: ■ Call this function before executing a child program with Int 21H Function 4BH (EXEC), in case the child also uses the mouse. After the EXEC call, restore the previous mouse driver state with Int 33H Function 17H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 17H (23) Restore mouse driver state ──────────────────────────────────────────────────────────────────────────── Restores the mouse driver state from a user buffer. Call with: AX = 0017H ES:DX = segment:offset of buffer Returns: Nothing Note: ■ The mouse driver state must have been previously saved into the same buffer with Int 33H Function 16H. The format of the data in the buffer is undocumented and subject to change. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 18H (24) Set alternate mouse event handler ──────────────────────────────────────────────────────────────────────────── Sets the address and event mask for a an application program mouse event handler. As many as three handlers with distinct event masks can be registered with this function. When an event occurs that matches one of the masks, the corresponding handler is called by the mouse driver. Call with: AX = 0018H CX = event mask Bit(s) Significance (if set) 0 mouse movement 1 left button pressed 2 left button released 3 right button pressed 4 right button released 5 Shift key pressed during button press or release 6 Ctrl key pressed during button press or release 7 Alt key pressed during button press or release 8─15 reserved (0) ES:DX = segment:offset of handler Returns: If function successful AX = 0018H If function unsuccessful AX = FFFFH Notes: ■ When this function is called, at least one of the bits 5, 6, and 7 must be set in register CX. ■ The user-defined event handler is entered from the mouse driver by a far call with registers set up as follows: AX mouse event flags (see event mask) BX button state Bit(s) Significance (if set) 0 left button is down 1 right button is down 2 center button is down 3─15 reserved (0) CX horizontal (X) pointer coordinate DX vertical (Y) pointer coordinate SI last raw vertical mickey count DI last raw horizontal mickey count DS mouse driver data segment ■ If an event does not generate a call to the user-defined handler because its bit is not set in the event mask, it can still be reported in the event flags during calls to the handler for events that are enabled. ■ Calls to the handler are disabled with Int 33H Function 00H. ■ See also Int 33H Functions 0CH and 14H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 19H (25) Get address of alternate mouse event handler ──────────────────────────────────────────────────────────────────────────── Returns the address for the mouse event handler matching the specified event mask. Call with: AX = 0019H CX = event mask (see Int 33H Function 18H) Returns: If function successful CX = event mask ES:DX = segment:offset of alternate event handler If function unsuccessful (no handler installed or event mask does not match any installed handler) CX = 0000H Note: ■ Int 33H Function 18H allows as many as three event handlers with distinct event masks to be installed. This function can be called to search for a handler that matches a specific event, so that it can be replaced or disabled. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 1AH (26) Set mouse sensitivity ──────────────────────────────────────────────────────────────────────────── Sets the number of mickeys per 8 pixels for horizontal and vertical mouse motion and the threshold speed for doubling pointer motion on the screen. One mickey represents approximately 1/200 of an inch of mouse travel. Call with: AX = 001AH BX = horizontal mickeys (1─32,767, default = 8) CX = vertical mickeys (1─32,767, default = 16) DX = double speed threshold in mickeys/second (default = 64) Returns: Nothing Note: ■ See also Int 33H Functions 0FH and 13H, which allow the mickeys to pixels ratio and threshold speed to be set separately, and Int 33H Function 1BH, which returns the current sensitivity values. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 1BH (27) Get mouse sensitivity ──────────────────────────────────────────────────────────────────────────── Returns the current mickeys to pixels ratios for vertical and horizontal screen movement and the threshold speed for doubling of pointer motion. Call with: AX = 001BH Returns: BX = horizontal mickeys (1─32,767, default = 8) CX = vertical mickeys (1─32,767, default = 16) DX = double speed threshold in mickeys/second (default = 64) Note: ■ See also Int 33H Functions 0FH, 13H, and 1AH. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 1CH (28) Set mouse interrupt rate ──────────────────────────────────────────────────────────────────────────── Sets the rate at which the mouse driver polls the status of the mouse. Faster rates provide better resolution in graphics mode but may degrade the performance of application programs. Call with: AX = 001CH BX = interrupt rate flags Bit(s) Significance 0 no interrupts allowed 1 30 interrupts/second 2 50 interrupts/second 3 100 interrupts/second 4 200 interrupts/second 5─15 reserved (0) Returns: Nothing Notes: ■ This function is applicable for the InPort Mouse only. ■ If more than one bit is set in register BX, the lowest order bit prevails. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 1DH (29) Select pointer page ──────────────────────────────────────────────────────────────────────────── Selects the display page for the mouse pointer. Call with: AX = 001DH BX = page Returns: Nothing Note: ■ The valid page numbers depend on the current display mode. See Int 10H Function 05H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 1EH (30) Get pointer page ──────────────────────────────────────────────────────────────────────────── Returns the current display page for the mouse pointer. Call with: AX = 001EH Returns: BX = page ──────────────────────────────────────────────────────────────────────────── Int 33H Function 1FH (31) Disable mouse driver ──────────────────────────────────────────────────────────────────────────── Disables the mouse driver and returns the address of the previous Int 33H handler. Call with: AX = 001FH Returns: If function successful AX = 001FH ES:BX = segment:offset of previous Int 33H handler If function unsuccessful AX = FFFFH Notes: ■ When this function is called, the mouse driver releases any interrupt vectors it has captured other than Int 33H (which may include Int 10H, Int 71H, and/or Int 74H). The application program can complete the process of logically removing the mouse driver by restoring the original contents of the Int 33H vector with Int 21H Function 25H, using the address returned by this function in ES:BX. ■ See also Int 33H Function 20H. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 20H (32) Enable mouse driver ──────────────────────────────────────────────────────────────────────────── Enables the mouse driver and the servicing of mouse interrupts. Call with: AX = 0020H Returns: Nothing Note: ■ See also Int 33H Function 1FH. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 21H (33) Reset mouse driver ──────────────────────────────────────────────────────────────────────────── Resets the mouse driver and returns driver status. If the mouse pointer was previously visible, it is removed from the screen, and any previously installed user handlers for mouse events are disabled. Call with: AX = 0021H Returns: If mouse support is available AX = FFFFH BX = number of mouse buttons If mouse support is not available AX = 0021H Note: ■ This function differs from Int 33H Function 00H in that there is no initialization of the mouse hardware. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 22H (34) Set language for mouse driver messages ──────────────────────────────────────────────────────────────────────────── Selects the language that will be used by the mouse driver for prompts and error messages. Call with: AX = 0022H BX = language number 0 = English 1 = French 2 = Dutch 3 = German 4 = Swedish 5 = Finnish 6 = Spanish 7 = Portuguese 8 = Italian Returns: Nothing Note: ■ This function is only available in international versions of the Microsoft Mouse driver. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 23H (35) Get language number ──────────────────────────────────────────────────────────────────────────── Returns the number of the language that is used by the mouse driver for prompts and error messages. Call with: AX = 0023H Returns: BX = language number (see Int 33H Function 22H) Note: ■ This function is only available in international versions of the Microsoft Mouse driver. ──────────────────────────────────────────────────────────────────────────── Int 33H Function 24H (36) Get mouse information ──────────────────────────────────────────────────────────────────────────── Returns the mouse driver version number, mouse type, and the IRQ number of the interrupt used by the mouse adapter. Call with: AX = 0024H Returns: BH = major version number (6 for version 6.10, etc.) BL = minor version number (0AH for version 6.10, etc.) CH = mouse type 1 = bus mouse 2 = serial mouse 3 = InPort mouse 4 = PS/2 mouse 5 = HP mouse CL = IRQ number 0 = PS/2 2, 3, 4, 5, or 7 = IRQ number ──────────────────────────────────────────────────────────────────────────── SECTION 4 LOTUS/INTEL/MICROSOFT EMS FUNCTIONS REFERENCE ──────────────────────────────────────────────────────────────────────────── Notes to the Reader The Lotus/Intel/Microsoft Expanded Memory Specification (EMS) defines a hardware/software subsystem, compatible with 80x86-based microcomputers running MS-DOS, that allows applications to access as much as 32 MB of bank-switched random-access memory. The software component, called the Expanded Memory Manager (EMM), is installed during system initialization by a DEVICE= directive in the CONFIG.SYS file in the root directory on the boot disk. After ensuring that the EMM is present (see Chapter 11), an application program communicates directly with the EMM using software interrupt 67H. A particular EMM function is selected by the value in register AH and a success or error status is returned in register AH (error codes are listed on pages 207─209). Other parameters and results are passed or returned in registers or buffers. An icon in each function heading indicates the EMS version in which that function was first supported. You can assume that the function is available in all subsequent EMS versions unless explicitly noted otherwise. Version icons used in the synopsis, parameters, results, or Notes section refer to specific minor or major EMS versions, unless they include a + sign to indicate a version and all subsequent versions. The material in this section has been verified against the Expanded Memory Specification version 4.0, dated October 1987, Intel part number 300275-005. This document can be obtained from Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124. Summary of EMM Functions ╓┌─┌────────────┌───────────────┌────────────────────────────────────────────╖ Function Subfunction Description ────────────────────────────────────────────────────────────────────────── 40H (64) Get Status 41H (65) Get Page Frame Address 42H (66) Get Number of Pages 43H (67) Allocate Handle and Pages 44H (68) Map Expanded Memory Page 45H (69) Release Handle and Expanded Memory 46H (70) Get Version 47H (71) Save Page Map 48H (72) Restore Page Map 49H (73) Reserved 4AH (74) Reserved 4BH (75) Get Handle Count 4CH (76) Get Handle Pages 4DH (77) Get Pages for All Handles 4EH (78) 00H Save Page Map 4EH (78) 01H Restore Page Map 4EH (78) 02H Save and Restore Page Map 4EH (78) 03H Get Size of Page Map Information 4FH (79) 00H Save Partial Page Map Function Subfunction Description ────────────────────────────────────────────────────────────────────────── 4FH (79) 00H Save Partial Page Map 4FH (79) 01H Restore Partial Page Map 4FH (79) 02H Get Size of Partial Page Map Information 50H (80) 00H Map Multiple Pages by Number 50H (80) 01H Map Multiple Pages by Address 51H (81) Reallocate Pages for Handle 52H (82) 00H Get Handle Attribute 52H (82) 01H Set Handle Attribute 52H (82) 02H Get Attribute Capability 53H (83) 00H Get Handle Name 53H (83) 01H Set Handle Name 54H (84) 00H Get All Handle Names 54H (84) 01H Search for Handle Name 54H (84) 02H Get Total Handles 55H (85) 00H Map Pages by Number and Jump 55H (85) 01H Map Pages by Address and Jump 56H (86) 00H Map Pages by Number and Call 56H (86) 01H Map Pages by Address and Call 56H (86) 02H Get Space for Map Page and Call Function Subfunction Description ────────────────────────────────────────────────────────────────────────── 56H (86) 02H Get Space for Map Page and Call 57H (87) 00H Move Memory Region 57H (87) 01H Exchange Memory Regions 58H (88) 00H Get Addresses of Mappable Pages 58H (88) 01H Get Number of Mappable Pages 59H (89) 00H Get Hardware Configuration 59H (89) 01H Get Number of Raw Pages 5AH (90) 00H Allocate Handle and Standard Pages 5AH (90) 01H Allocate Handle and Raw Pages 5BH (91) 00H Get Alternate Map Registers 5BH (91) 01H Set Alternate Map Registers 5BH (91) 02H Get Size of Alternate Map Register Save Area 5BH (91) 03H Allocate Alternate Map Register Set 5BH (91) 04H Deallocate Alternate Map Register Set 5BH (91) 05H Allocate DMA Register Set 5BH (91) 06H Enable DMA on Alternate Map Register Set 5BH (91) 07H Disable DMA on Alternate Map Register Set 5BH (91) 08H Deallocate DMA Register Set 5CH (92) Prepare Expanded Memory Manager for Warm Boot Function Subfunction Description ────────────────────────────────────────────────────────────────────────── 5CH (92) Prepare Expanded Memory Manager for Warm Boot 5DH (93) 00H Enable EMM Operating-System Functions 5DH (93) 01H Disable EMM Operating-System Functions 5DH (93) 02H Release Access Key ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 40H (64) Get status ──────────────────────────────────────────────────────────────────────────── Returns a status code indicating whether the expanded memory software and hardware are present and functional. Call with: AH = 40H Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ This call should be used only after an application has established that the Expanded Memory Manager is in fact present, using one of the techniques described in Chapter 11. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 41H (65) Get page frame address ──────────────────────────────────────────────────────────────────────────── Returns the segment address of the page frame used by the Expanded Memory Manager. Call with: AH = 41H Returns: If function successful AH = 00H BX = segment base of page frame If function unsuccessful AH = error code Notes: ■ The page frame is divided into four 16 KB pages, which are used to map logical expanded memory pages into the physical memory space of the CPU. ■ The application need not have already acquired an EMM handle to use this function. ■ [EMS 4.0] Mapping of expanded memory pages is not necessarily limited to the 64 KB page frame. See also Int 67H Function 58H Subfunction 00H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 42H (66) Get number of pages ──────────────────────────────────────────────────────────────────────────── Obtains the total number of logical expanded memory pages present in the system and the number of pages that are not already allocated. Call with: AH = 42H Returns: If function successful AH = 00H BX = unallocated pages DX = total pages If function unsuccessful AH = error code Notes: ■ The application need not have already acquired an EMM handle to use this function. ■ [EMS 4.0] See also Int 67H Function 59H Subfunction 01H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 43H (67) Allocate handle and pages ──────────────────────────────────────────────────────────────────────────── Obtains an EMM handle and allocates logical pages of expanded memory to be controlled by that handle. Call with: AH = 43H BX = number of pages to allocate (must be nonzero) Returns: If function successful AH = 00H DX = EMM handle If function unsuccessful AH = error code Notes: ■ This is the equivalent of a file open function for the expanded memory manager. The handle that is returned is analogous to a file handle and owns a certain number of expanded memory pages. The handle must be used with every subsequent request to map memory and must be released by a close operation before the application terminates. ■ This function may fail because there are no handles left to allocate or because there is an insufficient number of expanded memory pages to satisfy the request. In the latter case, Int 67H Function 42H can be used to determine the actual number of pages available. ■ [EMS 4.0] Int 67H Function 51H can be called to change the number of pages allocated to an EMM handle. ■ [EMS 4.0] The pages allocated by this function are always 16 KB for compatibility with earlier versions of EMS. See also Int 67H Function 5AH Subfunctions 00H and 01H. ■ [EMS 4.0] Handle 0000H is always available for use by the operating system, and a prior call to this function is not required. The operating system must call Int 67H Function 51H to assign the desired number of pages to its reserved handle. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 44H (68) Map expanded memory page ──────────────────────────────────────────────────────────────────────────── Maps one of the logical pages of expanded memory assigned to a handle onto a physical memory page that can be accessed by the CPU. Call with: AH = 44H AL = physical page BX = logical page DX = EMM handle Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The logical page number is in the range {0...n-1}, where n is the number of pages allocated or reallocated to the handle by a previous call to Int 67H Function 43H, 51H, or 5AH. Logical pages allocated by Int 67H Function 43H or Function 5AH Subfunction 00H are always 16 KB long; logical pages allocated by Int 67H Function 5AH Subfunction 01H are referred to as raw pages and are not necessarily 16 KB. ■ [EMS 3] The physical page is in the range 0─3 and lies within the EMM page frame, whose base address is obtained from Int 67H Function 41H. ■ [EMS 4.0] A list of the available physical pages and their addresses may be obtained from Int 67H Function 58H Subfunction 00H. ■ [EMS 4.0] If this function is called with BX = -1, the specified physical page is unmapped (made inaccessible for reading or writing). ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 45H (69) Release handle and expanded memory ──────────────────────────────────────────────────────────────────────────── Deallocates the expanded memory pages assigned to a handle and then releases the handle. Call with: AH = 45H DX = EMM handle Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ If this function is not called before a program terminates, the EMS pages it owned remain unavailable until the system is restarted. Programs that use EMS should install their own Ctrl-C handlers and critical-error handlers (Ints 23H and 24H) so that they cannot be terminated unexpectedly. ■ [EMS 4.0] When a handle is released, its name is set to all ASCII nulls. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 46H (70) Get version ──────────────────────────────────────────────────────────────────────────── Returns the EMS version supported by the expanded memory manager. Call with: AH = 46H Returns: If function successful AH = 00H AL = version number If function unsuccessful AH = error code Notes: ■ The version number is returned in binary code decimal (BCD) format, with the integer portion in the upper 4 bits of AL and the fractional portion in the lower 4 bits. For example, under an EMM that supports EMS version 3.2, AL is returned as the value 32H. ■ Applications should always check the EMM version number to ensure that all of the EMM functions they require are available. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 47H (71) Save page map ──────────────────────────────────────────────────────────────────────────── Saves the contents of the page-mapping registers on the expanded memory hardware, associating those contents with a particular EMM handle. Call with: AH = 47H DX = EMM handle Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ This function is used by interrupt handlers or device drivers that must access expanded memory. The EMM handle supplied to this function is the handle that was assigned to the handler or driver during its own initialization sequence, not to the program that was interrupted. ■ The mapping context is restored by a subsequent call to Int 67H Function 48H. ■ [EMS 4.0] This function saves only the mapping state for the 64 KB page frame defined in EMS 3. Programs that are written to take advantage of the additional capabilities of EMS 4.0 should use Int 67H Function 4EH or 4FH in preference to this function. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 48H (72) Restore page map ──────────────────────────────────────────────────────────────────────────── Restores the contents of the page-mapping registers on the expanded memory hardware to the values associated with the specified handle by a previous call to Int 67H Function 47H. Call with: AH = 48H DX = EMM handle Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ This function is used by interrupt handlers or device drivers that must access expanded memory. The EMM handle supplied to this function is the handle that was assigned to the handler or driver during its own initialization sequence, not to the program that was interrupted. ■ [EMS 4.0] This function restores only the mapping state for the 64 KB page frame defined in EMS 3. Programs that are written to take advantage of the additional capabilities of EMS 4.0 should use Int 67H Function 4EH or 4FH in preference to this function. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 49H (73) Reserved ──────────────────────────────────────────────────────────────────────────── This function was defined in EMS version 3.0 but is not documented for later EMS versions, so it should be avoided in application programs. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 4AH (74) Reserved ──────────────────────────────────────────────────────────────────────────── This function was defined in EMS version 3.0 but is not documented for later EMS versions, so it should be avoided in application programs. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 4BH (75) Get handle count ──────────────────────────────────────────────────────────────────────────── Returns the number of active expanded memory handles. Call with: AH = 4BH Returns: If function successful AH = 00H BX = number of active EMM handles If function unsuccessful AH = error code Notes: ■ If the returned number of EMM handles is zero, the expanded memory manager is idle, and none of the expanded memory is in use. ■ The value returned by this function is not necessarily the same as the number of programs using expanded memory because one program may own multiple EMM handles. ■ The number of active EMM handles never exceeds 255. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 4CH (76) Get handle pages ──────────────────────────────────────────────────────────────────────────── Returns the number of expanded memory pages allocated to a specific EMM handle. Call with: AH = 4CH DX = EMM handle Returns: If function successful AH = 00H BX = number of EMM pages If function unsuccessful AH = error code Notes: ■ [EMS 3] The total number of pages allocated to a handle never exceeds 512. A handle never has zero pages allocated to it. ■ [EMS 4.0] The total number of pages allocated to a handle never exceeds 2048. A handle may have zero pages of expanded memory. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.0] Function 4DH (77) Get pages for all handles ──────────────────────────────────────────────────────────────────────────── Returns an array that contains all the active handles and the number of expanded memory pages associated with each handle. Call with: AH = 4DH ES:DI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H BX = number of active EMM handles and buffer filled in as described in Notes If function unsuccessful AH = error code Notes: ■ The buffer is filled in with a series of DWORD (32-bit) entries, one per active EMM handle. The first word of an entry contains the handle, and the second word contains the number of pages allocated to that handle. ■ The maximum number of active handles is 256 (including the operating system handle 0), so a buffer size of 1024 bytes is adequate in all cases. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.2] Function 4EH (78) Subfunction 00H Save page map ──────────────────────────────────────────────────────────────────────────── Saves the current page-mapping state of the expanded memory hardware in the specified buffer. Call with: AH = 4EH AL = 00H ES:DI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H and buffer filled in with mapping information (see Notes) If function unsuccessful AH = error code Notes: ■ The buffer receives the information necessary to restore the state of the mapping registers using Int 67H Function 4EH Subfunction 01H. The format of the information may vary. ■ The size of the buffer required by this function can be determined with Int 67H Function 4EH Subfunction 03H. ■ Unlike Int 67H Function 47H, this function does not require a handle. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.2] Function 4EH (78) Subfunction 01H Restore page map ──────────────────────────────────────────────────────────────────────────── Restores the page-mapping state of the expanded memory hardware using the information in the specified buffer. Call with: AH = 4EH AL = 01H DS:SI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The buffer contains information necessary to restore the state of the mapping registers from a previous call to Int 67H Function 4EH Subfunction 00H or 02H. The format of the information may vary. ■ Unlike Int 67H Function 48H, this function does not require a handle. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.2] Function 4EH (78) Subfunction 02H Save and restore page map ──────────────────────────────────────────────────────────────────────────── Saves the current page-mapping state of the expanded memory hardware in a buffer and then sets the mapping state using the information in another buffer. Call with: AH = 4EH AL = 02H DS:SI = segment:offset of buffer containing mapping information (see Notes) ES:DI = segment:offset of buffer to receive mapping information (see Notes) Returns: If function successful AH = 00H and buffer pointed to by ES:DI filled in with mapping information (see Notes) If function unsuccessful AH = error code Notes: ■ The buffer addressed by DS:SI contains information necessary to restore the state of the mapping registers from a previous call to Int 67H Function 4EH Subfunction 00H or 02H. The format of the information may vary. ■ The sizes of the buffers required by this function can be determined with Int 67H Function 4EH Subfunction 03H. ■ Unlike Int 67H Functions 47H and 48H, this function does not require a handle. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 3.2] Function 4EH (78) Subfunction 03H Get size of page map information ──────────────────────────────────────────────────────────────────────────── Returns the size of the buffer that is required to receive page-mapping information using Int 67H Function 4EH Subfunctions 00H and 02H. Call with: AH = 4EH AL = 03H Returns: If function successful AH = 00H AL = size of buffer (bytes) If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 4FH (79) Subfunction 00H Save partial page map ──────────────────────────────────────────────────────────────────────────── Saves the state of a subset of the expanded memory page-mapping registers in the specified buffer. Call with: AH = 4FH AL = 00H DS:SI = segment:offset of map list (see Notes) ES:DI = segment:offset of buffer to receive mapping state (see Notes) Returns: If function successful AH = 00H and buffer filled in with mapping information (see Notes) If function unsuccessful AH = error code Notes: ■ The map list contains the number of mappable segments in the first word, followed by the segment addresses of the mappable memory regions (one segment per word). ■ To determine the size of the buffer required for the mapping state, use Int 67H Function 4FH Subfunction 02H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 4FH (79) Subfunction 01H Restore partial page map ──────────────────────────────────────────────────────────────────────────── Restores the state of a subset of the expanded memory page-mapping registers. Call with: AH = 4FH AL = 01H DS:SI = segment:offset of buffer (see Note) Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ The buffer contains mapping information and must have been prepared by a previous call to Int 67H Function 4FH Subfunction 00H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 4FH (79) Subfunction 02H Get size of partial page map information ──────────────────────────────────────────────────────────────────────────── Returns the size of the buffer which will be required to receive partial page-mapping information using Int 67H Function 4FH Subfunction 00H. Call with: AH = 4FH AL = 02H BX = number of pages Returns: If function successful AH = 00H AL = size of array (bytes) If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 50H (80) Subfunction 00H Map multiple pages by number ──────────────────────────────────────────────────────────────────────────── Maps one or more of the logical expanded memory pages assigned to a handle onto physical memory pages that can be accessed by the CPU. Physical pages are referenced by their numbers. Call with: AH = 50H AL = 00H CX = number of pages to map DX = EMM handle DS:SI = segment:offset of buffer (see Note) Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ The buffer contains a series of DWORD (32-bit) entries that control the pages to be mapped. The first word of each entry contains the logical expanded memory page number, and the second word contains the physical page number to which it should be mapped. If the logical page is -1, the physical page is unmapped (made inaccessible for reading or writing). ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 50H (80) Subfunction 01H Map multiple pages by address ──────────────────────────────────────────────────────────────────────────── Maps one or more of the logical expanded memory pages assigned to a handle onto physical memory pages that can be accessed by the CPU. Physical pages are referenced by their segment addresses. Call with: AH = 50H AL = 01H CX = number of pages to map DX = EMM handle DS:SI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The buffer contains a series of DWORD (32-bit) entries that control the pages to be mapped. The first word of each entry contains the logical page number, and the second word contains the physical page segment address to which it should be mapped. If the logical page is -1, the physical page is unmapped (made inaccessible for reading or writing). ■ The mappable segment addresses may be obtained by calling Int 67H Function 58H Subfunction 00H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 51H (81) Reallocate pages for handle ──────────────────────────────────────────────────────────────────────────── Modifies the number of expanded memory pages allocated to an EMM handle. Call with: AH = 51H BX = new number of pages DX = EMM handle Returns: If function successful AH = 00H BX = logical pages owned by EMM handle If function unsuccessful AH = error code Note: ■ If the requested number of pages is zero, the handle is still active, and pages can be reallocated to the handle at a later time; also, the handle must still be released with Int 67H Function 45H before the application terminates. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 52H (82) Subfunction 00H Get handle attribute ──────────────────────────────────────────────────────────────────────────── Returns the attribute (volatile or nonvolatile) associated with the specified handle. A nonvolatile memory handle and the contents of the expanded memory pages that are allocated to it are maintained across a warm boot operation (system restart using Ctrl-Alt-Del). Call with: AH = 52H AL = 00H DX = EMM handle Returns: If function successful AH = 00H AL = attribute 0 = volatile 1 = nonvolatile If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 52H (82) Subfunction 01H Set handle attribute ──────────────────────────────────────────────────────────────────────────── Sets the attribute (volatile or nonvolatile) associated with the specified handle. A nonvolatile memory handle and the contents of the expanded memory pages that are allocated to it are maintained across a warm boot operation (system restart using Ctrl-Alt-Del). Call with: AH = 52H AL = 01H BL = attribute 0 = volatile 1 = nonvolatile DX = EMM handle Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ If the expanded memory hardware cannot support nonvolatile pages, this function returns an error. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 52H (82) Subfunction 02H Get attribute capability ──────────────────────────────────────────────────────────────────────────── Returns a code indicating whether the Expanded Memory Manager and hardware can support the nonvolatile attribute for EMM handles. Call with: AH = 52H AL = 02H Returns: If function successful AH = 00H AL = attribute capability 0 = only volatile handles supported 1 = volatile and nonvolatile handles supported If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 53H (83) Subfunction 00H Get handle name ──────────────────────────────────────────────────────────────────────────── Returns the 8-character name assigned to a handle. Call with: AH = 53H AL = 00H DX = EMM handle ES:DI = segment:offset of 8-byte buffer Returns: If function successful AH = 00H and name for handle in specified buffer If function unsuccessful AH = error code Note: ■ A handle's name is initialized to 8 zero bytes when it is allocated or deallocated. Another name may be assigned to an active handle with Int 67H Function 53H Subfunction 01H. The bytes in a handle name need not be ASCII characters. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 53H (83) Subfunction 01H Set handle name ──────────────────────────────────────────────────────────────────────────── Assigns a name to an EMM handle. Call with: AH = 53H AL = 01H DX = EMM handle DS:SI = segment:offset of 8-byte name Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The bytes in a handle name need not be ASCII characters, but the sequence of 8 zero bytes is reserved for no name (the default after a handle is allocated or deallocated). A handle name should be padded with zero bytes, if necessary, to a length of 8 bytes. ■ A handle may be renamed at any time. ■ All handle names are initialized to 8 zero bytes when the system is turned on. The name of a nonvolatile handle is preserved across a warm boot. (See Int 67H Function 52H Subfunctions 00H and 02H.) ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 54H (84) Subfunction 00H Get all handle names ──────────────────────────────────────────────────────────────────────────── Returns the names for all active handles. Call with: AH = 54H AL = 00H ES:DI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H AL = number of active handles and buffer filled in with handle-name information (see Notes) If function unsuccessful AH = error code Notes: ■ The function fills the buffer with a series of 10-byte entries. The first 2 bytes of each entry contain an EMM handle, and the next 8 bytes contain the name associated with the handle. Handles that have never been assigned a name have 8 bytes of 0 as a name. ■ Because there is a maximum of 255 active handles, the buffer need not be longer than 2550 bytes. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 54H (84) Subfunction 01H Search for handle name ──────────────────────────────────────────────────────────────────────────── Returns the EMM handle associated with the specified name. Call with: AH = 54H AL = 01H DS:SI = segment:offset of 8-byte handle name Returns: If function successful AH = 00H DX = EMM handle If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 54H (84) Subfunction 02H Get total handles ──────────────────────────────────────────────────────────────────────────── Returns the total number of handles that are supported by the Expanded Memory Manager, including the operating-system handle (0). Call with: AH = 54H AL = 02H Returns: If function successful AH = 00H BX = number of handles If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 55H (85) Subfunctions 00H and 01H Map pages and jump ──────────────────────────────────────────────────────────────────────────── Alters the expanded memory mapping context and transfers control to the specified address. Call with: AH = 55H AL = subfunction 0 = map using physical page numbers 1 = map using physical page segments DX = EMM handle DS:SI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The buffer contains map-and-jump entries in the following format: Offset Length Description ──────────────────────────────────────────────────────────────────────── 00H 4 far pointer to jump target 04H 1 number of pages to map before jump 05H 4 far pointer to map list (see below) ──────────────────────────────────────────────────────────────────────── The map list in turn consists of DWORD (32-bit) entries, one per page. The first word of each entry contains the logical page number, and the second word contains the physical page number or segment (depending on the value in register AL) to which it should be mapped. ■ A request to map zero pages and jump is not considered an error; the effect is a simple far jump. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 56H (86) Subfunctions 00H and 01H Map pages and call ──────────────────────────────────────────────────────────────────────────── Alters the expanded memory mapping context and performs a far call to the specified address. When the destination routine executes a far return, the EMM again alters the page-mapping context as instructed and then returns control to the original caller. Call with: AH = 56H AL = subfunction 0 = map using physical page numbers 1 = map using physical page segments DX = EMM handle DS:SI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The format of the buffer containing map and call information is: Offset Length Description ──────────────────────────────────────────────────────────────────────── 00H 4 far pointer to call target 04H 1 number of pages to map before call 05H 4 far pointer to list of pages to map before call (see below) 09H 1 number of pages to map before return 0AH 4 far pointer to list of pages to map before return (see below) 0EH 8 reserved (0) ──────────────────────────────────────────────────────────────────────── Both map lists have the same format and consist of a series of double-word entries, one per page. The first word of each entry contains the logical page number, and the second word contains the physical page number or segment (depending on the value in register AL) to which it should be mapped. ■ A request to map zero pages and call is not an error; the effect is a simple far call. ■ This function uses extra stack space to save information about the mapping context; the amount of stack space required can be determined by calling Int 67H Function 56H Subfunction 02H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 56H (86) Subfunction 02H Get stack space for map page and call ──────────────────────────────────────────────────────────────────────────── Returns the number of bytes of stack space required by Int 67H Function 56H Subfunction 00H or 01H. Call with: AH = 56H AL = 02H Returns: If function successful AH = 00H BX = stack space required (bytes) If function unsuccessful AH = error code ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 57H (87) Subfunction 00H Move memory region ──────────────────────────────────────────────────────────────────────────── Copies a memory region from any location in conventional or expanded memory to any other location without disturbing the current expanded memory mapping context. Call with: AH = 57H AL = 00H DS:SI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The format of the buffer controlling the move operation is: Offset Length Description ──────────────────────────────────────────────────────────────────────── 00H 4 region length in bytes 04H 1 source memory type (0 = conventional, 1 = expanded) 05H 2 source memory handle 07H 2 source memory offset 09H 2 source memory segment or physical page number 0BH 1 destination memory type (0 = conventional, 1 = expanded) 0CH 2 destination memory handle 0EH 2 destination memory offset 10H 2 destination memory segment or physical page number ──────────────────────────────────────────────────────────────────────── ■ A length of zero bytes is not an error. The maximum length of a move is 1 MB. If the length exceeds a single expanded memory page, consecutive expanded memory pages (as many as are required) supply or receive the data. ■ If the source and destination addresses overlap, the move will be performed in such a way that the destination receives an intact copy of the original data, and a nonzero status is returned. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 57H (87) Subfunction 01H Exchange memory regions ──────────────────────────────────────────────────────────────────────────── Exchanges any two memory regions in conventional or expanded memory without disturbing the current expanded memory mapping context. Call with: AH = 57H AL = 01H DS:SI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The format of the buffer controlling the exchange operation is the same as for Int 67H Function 57H Subfunction 00H. ■ An exchange of zero bytes is not an error. The maximum length of an exchange is 1 MB. If the length exceeds a single expanded memory page, consecutive expanded memory pages (as many as are required) supply or receive the data. ■ If the source and destination addresses overlap, the exchange is not performed and an error is returned. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 58H (88) Subfunction 00H Get addresses of mappable pages ──────────────────────────────────────────────────────────────────────────── Returns the segment base address and physical page number for each mappable page in the system. Call with: AH = 58H AL = 00H ES:DI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H CX = number of entries in mappable physical page array and page number/address information in buffer (see Notes) If function unsuccessful AH = error code Notes: ■ Upon return from the function, the buffer contains a series of double-word entries, one per mappable page. The first word of an entry contains the page's segment base address, and the second contains its physical page number. The entries are sorted in order of ascending segment addresses. ■ The size of the buffer required can be calculated with the information returned by Int 67H Function 58H Subfunction 01H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 58H (88) Subfunction 01H Get number of mappable pages ──────────────────────────────────────────────────────────────────────────── Returns the number of mappable physical pages. Call with: AH = 58H AL = 01H Returns: If function successful AH = 00H CX = number of mappable physical pages If function unsuccessful AH = error code Note: ■ The information returned by this function can be used to calculate the size of the buffer that will be needed by Int 67H Function 58H Subfunction 00H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 59H (89) Subfunction 00H Get hardware configuration ──────────────────────────────────────────────────────────────────────────── Returns information about the configuration of the expanded memory hardware. Call with: AH = 59H AL = 00H ES:DI = segment:offset of buffer (see Notes) Returns: If function successful AH = 00H and hardware configuration information in buffer. If function unsuccessful AH = error code Notes: ■ Upon return from the function, the buffer has been filled in with hardware configuration information in the following format: Offset Length Description ──────────────────────────────────────────────────────────────────────── 00H 2 size of raw expanded memory pages (in paragraphs) 02H 2 number of alternate register sets 04H 2 size of mapping-context save area (in bytes) 06H 2 number of register sets that can be assigned to DMA channels 08H 2 DMA operation type (0 = DMA may be used with alternate register sets; 1 = only one DMA register set available) ──────────────────────────────────────────────────────────────────────── ■ The size returned for the mapping-context save area is the same as the size returned by Int 67H Function 4EH Subfunction 03H. ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 59H (89) Subfunction 01H Get number of raw pages ──────────────────────────────────────────────────────────────────────────── Obtains the total number of raw expanded memory pages present in the system and the number of raw pages that are not already allocated. Raw memory pages may have a size other than 16 KB. Call with: AH = 59H AL = 01H Returns: If function successful AH = 00H BX = unallocated raw pages DX = total raw pages If function unsuccessful AH = error code Note: ■ If the Expanded Memory Manager supports only pages of standard size, the values returned by this function are the same as those returned by Int 67H Function 42H. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5AH (90) Subfunction 00H Allocate handle and standard pages ──────────────────────────────────────────────────────────────────────────── Allocates an EMM handle and associates standard (16 KB) expanded memory pages with that handle. Call with: AH = 5AH AL = 00H BX = number of standard pages to allocate Returns: If function successful AH = 00H DX = EMM handle If function unsuccessful AH = error code Note: ■ Unlike Int 67H Function 43H, allocating zero pages with this function is not an error. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5AH (90) Subfunction 01H Allocate handle and raw pages ──────────────────────────────────────────────────────────────────────────── Allocates a raw EMM handle and associates raw expanded memory pages with that handle. Call with: AH = 5AH AL = 01H BX = number of raw pages to allocate Returns: If function successful AH = 00H DX = handle for raw EMM pages If function unsuccessful AH = error code Notes: ■ Raw memory pages may have a size other than 16 KB. ■ Allocation of zero pages is not an error. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 00H Get alternate map registers ──────────────────────────────────────────────────────────────────────────── Returns the number of the active alternate register set or, if no alternate set is active, saves the state of the mapping registers into a buffer and returns its address. Call with: AH = 5BH AL = 00H Returns: If function successful and alternate map register set active AH = 00H BL = current active alternate map register set If function successful and alternate map register set not active AH = 00H BL = 00H ES:DI = segment:offset of alternate map register save area (if BL = 0) If function unsuccessful AH = error code Notes: ■ The address of the save area must have been specified in a previous call to Int 67H Function 5BH Subfunction 01H, and the save area must have been initialized by a previous call to Int 67H Function 4EH Subfunction 00H. If there was no previous call to Int 67H Function 5BH Subfunction 01H, the address returned is zero, and the registers are not saved. ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 01H Set alternate map registers ──────────────────────────────────────────────────────────────────────────── Selects an alternate map register set or (if alternate sets are not supported) restores the mapping context from the specified buffer. Call with: AH = 5BH AL = 01H BL = alternate register set number or 00H ES:DI = segment:offset of map register context restore area (if BL = 0) Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The buffer address specified in this call is returned by subsequent calls to Int 67H Function 5BH Subfunction 00H with BL = 00H. ■ The save area must have been initialized by a previous call to Int 67H Function 4EH Subfunction 00H. ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 02H Get size of alternate map register save area ──────────────────────────────────────────────────────────────────────────── Returns the amount of storage needed by Int 67H Function 5BH Subfunctions 00H and 01H. Call with: AH = 5BH AL = 02H Returns: If function successful AH = 00H DX = size of buffer (bytes) If function unsuccessful AH = error code Note: ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 03H Allocate alternate map register set ──────────────────────────────────────────────────────────────────────────── Allocates an alternate map register set for use with Int 67H Function 5BH Subfunctions 00H and 01H. The contents of the currently active map registers are copied into the newly allocated alternate map registers in order to provide an initial context when they are selected. Call with: AH = 5BH AL = 03H Returns: If function successful AH = 00H BL = alternate map register set number or zero, if no alternate sets are available If function unsuccessful AH = error code Note: ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 04H Deallocate alternate map register set ──────────────────────────────────────────────────────────────────────────── Releases an alternate map register set that was previously allocated with Int 67H Function 5BH Subfunction 03H. Call with: AH = 5BH AL = 04H BL = alternate register set number Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ The current alternate map register set cannot be deallocated. ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 05H Allocate DMA register set ──────────────────────────────────────────────────────────────────────────── Allocates a DMA register set. Call with: AH = 5BH AL = 05H Returns: If function successful AH = 00H BL = DMA register set number (0 = none available) If function unsuccessful AH = error code Note: ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 06H Enable DMA on alternate map register set ──────────────────────────────────────────────────────────────────────────── Associates a DMA channel with an alternate map register set. Call with: AH = 5BH AL = 06H BL = alternate map register set DL = DMA channel number Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ If a DMA channel is not assigned to a specific register set, DMA for that channel will be mapped through the current register set. ■ If zero is specified as the alternate map register set, no special action is taken on DMA accesses for the specified DMA channel. ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 07H Disable DMA on alternate map register set ──────────────────────────────────────────────────────────────────────────── Disables DMA accesses for all DMA channels associated with a specific alternate map register set. Call with: AH = 5BH AL = 07H BL = alternate register set number Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5BH (91) Subfunction 08H Deallocate DMA register set ──────────────────────────────────────────────────────────────────────────── Deallocates a DMA register set that was previously allocated with Int 67H Function 5BH Subfunction 05H. Call with: AH = 5BH AL = 08H BL = DMA register set number Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5CH (92) Prepare Expanded Memory Manager for warm boot ──────────────────────────────────────────────────────────────────────────── Prepares the expanded memory hardware for an impending warm boot. This function affects the current mapping context, the alternate register set in use, and any other expanded memory hardware dependencies that would ordinarily be initialized at system boot time. Call with: AH = 5CH Returns: If function successful AH = 00H If function unsuccessful AH = error code Note: ■ If an application maps expanded memory at addresses below 640 KB, the application must trap all possible conditions that might lead to a warm boot, so that this function can be called first. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5DH (93) Subfunction 00H Enable EMM operating-system functions ──────────────────────────────────────────────────────────────────────────── Enables the operating-system─specific EMM functions (Int 67H Functions 59H, 5BH, and 5DH) for calls by any program or device driver. (This is the default condition.) Call with: AH = 5DH AL = 00H BX:CX = access key (if not first call to function) Returns: If function successful AH = 00H BX:CX = access key (if first call to function) If function unsuccessful AH = error code Notes: ■ An access key is returned in registers BX and CX on the first call to Int 67H Function 5DH Subfunction 00H or 01H. The access key is required for all subsequent calls to either function. ■ This function is intended for use by operating systems only. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5DH (93) Subfunction 01H Disable EMM operating-system functions ──────────────────────────────────────────────────────────────────────────── Disables the operating-system─specific EMM functions (Int 67H Functions 59H, 5BH, and 5DH) for calls by application programs and device drivers, reserving the use of these functions for the operating system. Call with: AH = 5DH AL = 01H BX:CX = access key (if not first call to function) Returns: If function successful AH = 00H BX:CX = access key (if first call to function) If function unsuccessful AH = error code Notes: ■ An access key is returned in registers BX and CX on the first call to Int 67H Function 5DH Subfunction 00H or 01H. The access key is required for all subsequent calls to either function. ■ This function is intended for use by operating systems only. ──────────────────────────────────────────────────────────────────────────── Int 67H [EMS 4.0] Function 5DH (93) Subfunction 02H Release access key ──────────────────────────────────────────────────────────────────────────── Releases the access key obtained by a previous call to Int 67H Function 5DH Subfunction 00H or 01H. Call with: AH = 5DH AL = 02H BX:CX = access key Returns: If function successful AH = 00H If function unsuccessful AH = error code Notes: ■ With respect to the operating-system─specific expanded memory functions, the EMM is returned to the state it had when the system was initialized. A new access key is returned by the next call to Int 67H Function 5DH Subfunction 00H or 01H. ■ This function is intended for use by operating systems only and can be disabled by the operating system at any time. ──────────────────────────────────────────────────────────────────────────── Index References to tables and illustrations are in italics. Special Characters | 298-99 . 187 .. 187-88 ; 60 < 298-99 > 298-99 >> 298-99 @ 60 A Absolute disk read 482-84 Absolute disk write 484-85 adapters, video display 86-87 alarm reset 592 set 591-92 align type 38 Allocate alternate map register set (EMS) 641 Allocate DMA register set (EMS) 642 Allocate handle and pages (EMS) 617-18 Allocate handle and raw pages (EMS) 639 Allocate handle and standard pages (EMS) 638-39 Allocate memory block 438-39 ANSI.SYS device driver, screen control 91 escape sequences used with 92-93 APPEND 490-91 application program interface (API) 320 application programs. See MS-DOS application programs, porting to OS/2; MS-DOS application programs, structure of; MS-DOS application programs, writing compatible arena entries 196 arena headers 196, 201 diagram example 202 ASCII escape code 92-93 ASCII mode 69 character-device drivers in 261-62 ASCII text files 56 ASCIIZ strings 24, 139, 168 .ASM files 45. See also assembly-language programs assembly-language programs 37-42 to access file allocation table 191 BREAK.ASM 75-78 CLEAN.ASM 304-9 DRIVER.ASM 283-91 DUMP.ASM 152-61 HELLO.COM example 27-30, 33-36 program modules 37 program procedures 41-42 program segments 38-41 PROTO.ASM 301-2 SHELL.ASM program 229-38 TALK.ASM 113-26 ZERODIV.ASM 254, 255-58 ASSIGN 489 ASSUME statement 29, 33 attribute byte color text display 98 monochrome text display 97 attribute word, device 264 Auxiliary device (AUX) 12, 106, 298. See also serial port Auxiliary input 344-45 Auxiliary output 345-46 B background, set 508-9 BACKUP command 15 .BAT (batch) files 15 Batch files 15 binary mode 69 character-device drivers in 261-62 output 93-94 BIOS module 12-13, 17 get address of extended, 574 BIOS parameter block (BPB) 181, 189 build 272 structure 269 bit planes 101 blink/intensity bit, toggle 513 block-device drivers 260, 262 check for remoteness 423-24 check removability of 422-23 generic I/O control of 429-32 read control data from 418-19 write control data to 419-20 Boot disk device (block device) 12 boot drive, get 392-93 boot sector, disk 179-82 map of 180 partial disassembly of 182 partial hex dump 181 bootstrap routine 16, 17 border get color 514 get palette and 514 set 508-9 set color 512 BREAK.ASM program 75-78 break flag, get or set 392-93 Buffered keyboard input 351-52 Build BIOS Parameter Block (function 02H) 272 C CALL instructions 41 Cancel device redirection 467-68 cassette motor read 561 turn off 560-61 turn on 560 write 562 .C files 45. See also C language Change sharing retry count 425-26 character blocks, set specifier 520 character-device drivers 260, 261-62 ASCII vs binary mode 261-62 generic I/O control 426-29 read control data from 415-16 write control data to 416-17 character input/output. See also keyboard input; mouse, input; pointing device, input; printer output; serial port Int 21H 44H IOCTL (I/O control) 411-43 Int 21H functions, summary 337-38 (table) processing typical I/O request 281-82 Character input with echo 343 Character input without echo 349-50 Character output 344 CHDIR (CD) command 167 Check if block device is remote 423-24 Check if block device is removable 422-23 Check if handle is remote 424-25 Check input status 353, 420-21 Check output status 421-22 child programs 218 CHKDSK command 15, 174, 222 C language CLEAN.C 309-11 compiler (see C Optimizing Compiler) DUMP.C program 151, 161-63 linking Ctrl-C and Ctrl-Break handlers to programs in 75-80 MOUDEMO.C 82-83 polling mouse and displaying mouse coordinates 82-83 PROTO.C 303 SHELL.C 225-29 TRYBREAK 78-79 tutorials 63 class type 38 CLEAN filter 303-11 assembly source code 304-9 C source code 309-11 clock, set tick count 589-90 CLOCK driver 282 Close file 357-58, 404-5 code page, get or set 474-75 code segment 38 code segment (CS) register 30 Color/Graphics Adapter (CGA) 86, 98, 102 color page state get 517 set 515-16 color register(s) get 516 get block of 516-17 set 514-15 set block of 515 COM1, COM2, COM3 devices 106, 110-12, 298 combine type 38 command code routines, device-driver 267-81 function 00H, Driver initialization 268-69 function 01H, Media Check 270-71 function 02H, Build BIOS Parameter Block (BPB) 272 function 03H, I/O-Control Read 272-73 function 04H, Read 273 function 05H, Nondestructive Read 274 function 06H, Input Status 274 function 07H, Flush Input Buffers 274-75 function 08H, Write 275 function 09H, Write with Verify 276 function 0AH, Output Status 276 function 0BH, Flush Output Buffers 276 function 0CH, I/O-Control Write 276-77 function 0DH, Device Open 277 function 0EH, Device Close 277-78 function 0FH, Removable Media 278 function 10H, Output Until Busy 278-79 function 13H, Generic IOCTL 279-80 function 17H, Get Logical Device 280 function 18H, Set Logical Device 280-81 names of, and MS-DOS version support 267-68 (table) COMMAND.COM file 14-16 load 20 replacing 13 use of EXEC function 218 COMMAND.COM PLUS 13 command processor (shell) 13. See also COMMAND.COM file commands, types of, accepted by COMMAND.COM 14-15 command tail 24, 220-21 Commit file 476-77 compatibility and portability 313-31 degrees of compatibility 314-18 MS-DOS applications 315-17 ROM BIOS and hardware-compatible applications 317-18 OS/2 compatibility 318-31 .COM program file(s) 15, 22, 25-30, 45 assembly-language program transformed into 27-30 vs .EXE files 22, 36 (table) memory allocation for 197-98 memory image of a typical 26 CONFIG.SYS file 12 installing device driver 293 opening 18-19 configuration get equipment 535-36 get information 525 get system environment 573-74 console, direct input/output 347-48. See also video display Console display and keyboard (CON) 12, 298-99 control data read, from block-device driver 418-19 read, from character-device driver 415-16 write, to block-device driver 419-20 write, to character-device driver 416-17 Controller drive diagnostic 551 Controller internal diagnostic 551 Controller RAM diagnostic 550 cooked mode 69 C Optimizing Compiler 44, 48-50 environmental variables 48 version 5.1 switches 49-50 COPY command 14, 58 Country information get extended 470-74 get or set 395-98 CP/M operating system 4, 5 FCB compatibility with 129, 130-31 program segment prefix compatibility with 24, 25 Create directory 398-99 Create file 364-65, 401-2 Create new file 458-59 Create new PSP 378-79 Create temporary file 457-58 CREF utility 44, 56-58 cross-reference listing for HELLO.REF 57 .CRF files 45, 56 Critical-error handler address 481-82 critical-error handlers 24, 145, 147-51 address 481-82 skeleton program example 150-51 stack at entry to 148, 149 cross-reference listing. See CREF utility Ctrl-Break and Ctrl-C handlers 72-80 compatibility issues 317 Ctrl-C handler address 480-81 high-level languages and 75-80 cursor addressing 97 enable/disable emulation 528 get position 502-3 read character and attribute at 506 set position 501-2 set type 501 write character and attribute at 506-7 write character at 507-8 D data segment 38 data segment (DS) register 31, 35 Date and time device (CLOCK$) 12 day count get 592-93 set 593 Deallocate alternate map register set (EMS) 642 Deallocate DMA register set (EMS) 644 .DEF files 45 Delay 568-69 DEL(ETE) command 14 Delete directory 399 Delete file 361-62, 40, sug>8 dependency statements 61 descriptors, memory segment 321 device cancel redirection 467-68 close 565 get device information 412-13 open 564-65 post 572-73 read file or 405-6 redirect 466-67 set device information 414-15 wait 571 write file or 406-7 Device Close (command code function 0EH) 277-78 Device close (MS-DOS function) 565 DEVICE commands 12 device drivers, installable 12-13, 259-96 CLOCK driver 282 command-code routines 267-81 debugging 295-96 chain before/after driver installation 294 chain listing 295 device attribute word 264 error codes 267 MS-DOS type 260-63 processing of typical input/output requests 281-82 structure of MS-DOS 263-67 device header 263-64 interrupt routine 26-67 strategy routine 265 writing and installing 282-95 assembly 283-92 installation 293-95 linking 293 device drivers, resident 12-13 Device Open (command-code function 0DH) 277 Device open (MS-DOS function) 564-65 Device post 572-73 Device wait 571-72 Digital Research 4 DIR command 14, 167, 174 Direct console I/O 347-48 directory 166, 167-73 create 398-99 delete 399 format of a single entry in a disk 184, 185 functions controlling 167-68 get current 437-38 hierarchical (tree) structure 166, 167 moving files 173 root 184-86 searching 168-73 set current 400 directory operations, Int 21H functions summary 339 Disable DMA on alternate map register set (EMS) 643-44 Disable EMM operating system functions (EMS) 645-46 Disable mouse driver 608-9 disk(s) 177-94. See also drive, logical; ESDI Fixed Disk Drive Adapter absolute read 482-84 absolute write 484-85 boot sector 179-82 controller drive diagnostic 551 controller internal diagnostic 551 controller RAM diagnostic 550 file allocation table 182-84 interpreting the 188-92 files area 186-88 fixed-disk partitions 192-94 format 543 format bad track 542 format track 541-42 get change status 552-53 get current 367 get default drive data 368-69 get drive allocation information 394-95 get drive data 370 get drive parameters 543-44 get drive status 549 get type 552 initialize fixed disk characteristics 544-45 map of typical logical volume 179 park heads 554-55 read sector 538-39 read sector buffer 548 read sector long 545-46 recalibrate 550 reserved area 182 reset 354-55 reset fixed disk system 548 root directory 184-86, 187 seek 547 select 355-56 set media type 554 set type 553 set verify flag 387-88 verify sector 540 write sector 539-40 write sector buffer 549 write sector long 546-47 disk bootstrap routine 16 memory location of 17 disk management, Int 21H functions summary 339 disk-related errors 147, 148 (table) Disk reset 354-55 disk system get status 537-38 reset 536-37 disk transfer area (DTA) 25, 130 get 388-89 set 368 display page, set 503-4 Display string 350-51 DOS kernel 12, 18 memory location of 19 double-byte character sets (DBCS), get lead byte table 469-70 drive, logical 166, 16,-73. See also disk(s) get map 433 set map 434 vs volume 174 driver. See device drivers, installable; device drivers, resident DRIVER.ASM program 283-91 Driver Initialization (function 00H) 268-69 DUMP.ASM program 151, 152-61 subroutines 163 DUMP.C program 151, 161-63 Duplicate handle 435 dynamic link library 331 dynamic memory allocation 199, 200, 201 E echo character input with 343 character input without 349-50 unfiltered character input without 348-49 EMS. See Expanded Memory Specification (EMS) Enable/disable cursor emulation 528 Enable/disable default palette loading 526-27 Enable/disable gray-scale summing 527 Enable/disable pointing device 574-75 Enable/disable screen refresh 529 Enable/disable video 527 Enable DMA on alternate map register set (EMS) 643 Enable EMM operating system functions (EMS) 645 Enable mouse driver 609 encapsulation of subroutines 323, 324-25 end of interrupt (EOI) 250 ENDP command 35, 41 ENDS command 29, 38 END statement 30-31, 36, 41 Enhanced Graphics Adapter (EGA) 86, 97, 98, 102 Enter protected mode 570-71 environment block 24, 220, 224-25 dump of a typical 224 three strings contained in 225 EQU statement 33 error codes, device driver 267 error codes, MS-DOS 145-51 critical 145, 147-51 expanded memory 207-9 error information, get/set 453-56 escape sequences, ANSI 92-93 ESDI Fixed Disk Drive Adapter (EP> format drive 555 format periodic interrupt 562-63 Event wait 566-67 Exchange memory regions (EMS) 635-36 EXE2BIN utility 44, 55-56 EXEC function 15, 217-42. See also Int 21H Function 4BH calling convention 222 compatibility in MS-DOS applications 317 environment block 220, 224-25 example programs SHELL.C and SHELL.ASM 225-40 basic flow of both 239-40 internal commands in 239 example use of 223-24 loading overlays with 240, 241-42 making memory availinug for 218-19 reference 441-42 requesting 219-21 returning from 221-24 .EXE (executable) program file(s) 15, 22, 30-36, 45 assembly language program transformed into 33-36 vs .COM files 22, 36 (table) converting, to .COM files (see EXE2BIN utility) header 30 load module contents 33 load module format 32 memory allocation for 198 memory image of 31 use for compatible MS-DOS applications 315 Expanded Memory Manager (EMM) 203-4 checking for 204, 205-6 enable/disable system functions 645-46 error codes 207-9 Expanded Memory Specification (EMS) 201-11 checking for expanded memory 204-6 expanded memory defined 203-4 functions reference (see Section IV) summary 614-15 use of expanded memory 20,-11 skeleton program illustrating 210-11 Extended communications port control 559-60 extended file control block 131 volume-label search using 175 Extended initialize communications port 558-59 extended memory 204, 212-15 moving blocks of data between conventional memory and 213-15 Extended open file 478-80 external (extrinsic) commands 15 external hardware interrupts 247 extra segment (ES) register 31 F FAR attribute 35 vs NEAR 29 faults (internal hardware interrupts) 246, 321 file(s) area, in disks 186-88 close 357-58, 404 commit 476-77 create 364-65, 401-2 create new 458-59 create temporary 457-58 delete 361-62, 407-8 extended open 478-80 find first 358-59, 445-46 find next 360-61, 446-47 get file size 375-76 get/set date and time 450-51 lock/unlock file region 460-61 logical drive 166 moving 123 name and location 166 open 356-57, 402-4 read 405-6 rename 366, 449-50 types 45 write 406-7 file-access skeleton program using FCB functions 134, 135-37 using handle functions 141, 142-43 file allocation table (FAT) 16, 182-84 assembly program to access 191 contents 183 interpreting 188-92 media descriptor bytes 183 file attributes, get or set 410-11 file control blocks (FCBs) 25, 128 default 130, 221 directory searching with 169, 170-71 extended 131, 133-34, 175 file management with FCB functions 129-39 advantages/disadvantages 138-39 file-access skeleton program 134-38 functions listed 132 vs handle functions 128 normal 129, 133-34 before/after open call (Int 21H Function 0FH) 137 restricted use 316, 319 typical operation of 130 file management 127-63 example programs DUMP.ASM and DUMP.C 151-63 FCB functions 128, 129-39 handle functions 128, 139-44 MS-DOS error codes 145-51 filename fully qualified 16 parse 382-83 requesting EXEC function 219 file operations, Int 21H functions summary 338 file pointer, set 408-9 file system 166 structure 167 filters 297-311 building 300-303 CLEAN filter 303-11 operation of 299-300 prototype 301-3 system support for 298-99 Find first file 358-59, 445-46 Find next file 360-61, 44-47 fixed-disk partitions 192-94 font functions 518-24 Format bad track 542 Format drive 543 Format ESDI drive 555-56 Format ESDI drive periodic interrupt 562-63 Format track 541-42 Flush input buffer and then input 353-54 Flush Input Buffers (function 07H) 274-75 Flush Output Buffers (function 0BH) 276 G Generic I/O control for block devices 429-32 Generic I/O control for character devices 426-29 Generic IOCTL (function 13H) 279-80 Get addresses of mappable pages (EMS) 636 Get address of alternate mouse event handler 606 Get address of extended BIOS data area 574 Get all handle names (EMS) 631 Get alternate map registers (EMS) 639-40 Get attribute capability (EMS) 630 Get block of color registers 516-17 Get border color 514 Get button press information 596 Get button release information 597 Get color page state 517 Get color register 516 Get communications port status 558 Get configuration information 525 Get conventional memory size 536 Get current directory 437-38 Get current disk 367 Get cursor position 502-3 Get date 384-85, 591 Get day count 592 Get DBCS lead byte table 469-70 Get default drive data 368-69 Get device inform~on 412-13 Get disk change status 552-53 Get disk system status 537-38 Get disk type 552 Get drive allocation information 394-95 Get drive data 370-71 Get drive parameters 543-44 Get drive status 549 Get DTA address 388-89 Get enhanced keyboard flags 586-87 Get equipment configuration 535-36 Get extended country information 470-74 Get extended error information 453-56 Get extended memory size 570 Get file size 375-76 Get font information 524 Get functionality/state information 531-34 Get handle attribute (EMS) 629 Get handle count (EMS) 621-22 Get handle name (EMS) 630 Get handle pages (EMS) 622 Get hardware configuration (EMS) 637-38 Get interrupt vector 393-94 Get keyboard flags 582 Get keyboard status 582 Get language number 610 Get light pen position 503 Get Logical Device (command-code function) 280 Get logical drive map 433 Get machine name 461-62 Get mouse information 611 Get mouse position and button status 595 Get mouse save state buffer size 603 Get mouse sensitivity 607 Get MS-DOS version number 389-90 Get number of mappable pages (EMS) 637 Get number of pages (EMS) 617 Get number of raw pages (EMS) 638 Get or set allocation strategy 452-53 Get or set break flag, get boot drive 392-93 Get or set code page 474-75 Get or set country information 395-98 Get or set display combination code 530-31 Get or set file Attributes 410-11 Get or set file date and time 450-51 Get page frame address (EMS) 616 Get pages for all handles (EMS) 623 Get palette and border 514 Get palette register 513 Get pointer page 608 Get pointing device type 577 Get printer setup string 463-64 Get printer status 588 Get PSP address 468-69 Get redirection list entry 464-65 Get return code 444-45 Get size of alternate map register save area (EMS) 641 Get size of page map information (EMS) 625 Get size of partial page map information (EMS) 626-27 Get stack space for map page and call (EMS) 634 Get status (EMS) 616 Get system environment 573-74 Get tick count 589 Get time 386, 590 Get total handles (EMS) 632 Get verify flag 448 Get version (EMS) 619 Get video mode 511 Graphics CardPlus 87 graphics mode memory-mapped programming 101-3 gray-scale enable/disable summing 527 get values 517 GROUP directive 39 H handle functions check if handle is remote 424-25 directory searching 169-70, 172-73 DUMP.ASM program 151, 152-62 DUMP.C program 151, 161-63 duplicate handle 435 file/record management with 139-44 advantages/disadvantages 144 vs FCB functions 128 file access skeleton program 141-43 functions listed 140-41 typical operation 139 keyboard input 62, 67-69 redirect handle 436-37 set handle count 475-76 use for compatible MS-DOS applications 316 volume-label search using176 hardware-compatible applications 314-15, 317-18 header(EP> device 263, 264, 269 .EXE program files 30 Hercules Graphics Card 87, 97, 98 HELLO.COM program 27, 28-29, 30 hex dump of 33 map produced by Object Linker during generation of 51 HELLO.EXE program 33, 34-35, 36 HELLO.REF program, cross-reference listing 57 .H files 45 Hide mouse pointer 595 I IBMBIO.COM file 16 disk location 189-92 IBM Corporation, role in MS-DOS development 4-5 IBMDOS.COM file 13, 16 IBM PC 64 PC/AT 64 PS/2 64 regen buffers in memory for various adapters 87 "ill-behaved" applications 315 .INC files 45 In-Color Card 87 Initialize communications port 556-57 Initialize fixed disk characteristics 544-45 Initialize or scroll window down 505-6 Initialize or scroll window up 505 Initialize pointing device interface 577-78 Initialize printer port 587-88 input. See character input/output; keyboard input; mouse, input; pointing device, input; serial port input buffer, flush 353-54 Input/Output (I/O)-Control Read (function 03H) 272-73 Input/Output (I/O)-Control Write (function 0CH) 276-77 input/output (I/O) redirection 67, 298-99 input status, check 353, 420 Input Status (command-code function 06H) 274 INS8250 Asynchronous Communications Controller 112 installable device drivers 12-13 Int 10H, ROM BIOS video driver Function 00H, Set video mode 94, 500 Function 01H, Set cursor type 94, 501 Function 02H, Set cursor position 94, 501 Function 03H, Get cursor position 94, 502 Function 04H, Get light pen position 95, 503 Function 05H, Set display page 95, 503 Function 06H, Initialize or scroll window up 95, 505 Function 07H, Initialize or scroll window down 95, 505 Function 08H, Read character and attribute at cursor 95, 506 Function 09H, Write character and attribute at cursor 94, 506 Function 0AH, Write character at cursor 94, 507 Function 0BH, Set palette, background, or border 95, 508 Function 0CH, Write graphics pixel 95, 509 Function 0DH, Read graphics pixel 95, 510 Function 0EH, Write character in teletype mode 94, 510 Function 0FH, Get video mode 94, 511 Function 10H palette functions Subfunction 00H, Set palette register 511 Subfunction 01H, Set border color 512 Subfunction 02H, Set palette and border 512-13 Subfunction 03H, Toggle blink/intensity bit 513 Subfunction 07H, Get palette register 513 Subfunction 08H, Get border color 514 Subfunction 09H, Get palette and border 514 Subfunction 10H, Set color register 514 Subfunction 12H, Set block of color registers 515 Subfunction 13H, Set color page state 515-16 Subfunction 15H, Get color register 516 Subfunction 17H, Get block of color registers 516 Subfunction 1AH, Get color page state 517 Subfunction 1BH, Set gray-scale values 517 Function 11H, font functions Subfunctions 00H and 10H, Load user font 518 Subfunctions 01H and 11H, Load ROM 8-by-14 font 518 Subfunctions 02H and 12H, Load ROM 8-by-8 font 519 Subfunction 03H, Set block specifier 520 Subfunctions 04H and 14H, Load ROM 8-by-16 font 520 Subfunction 20H, Set Int 1FH font pointer 521 Subfunction 21H, Set Int 43H for user's font 522 Subfunction 22H, Set Int 43H for ROM 8-by-14 font 522 Subfunction 23H, Set Int 43H for ROM 8-by-8 font 523 Subfunction 24H, Set Int 43H for ROM 8-by-16 font 523 Subfunction 30H, Get font information 524 Function 12H Subfunction 10H, Get configuration information 525 Subfunction 20H, Select alternate printscreen 526 Subfunction 30H, Set scan lines 526 Subfunction 31H, Enable/disable default palette loading 526-27 Subfunction 32H, Enable/disable video 527 Subfunction 33H, Enable/disable gray-scale summing 527 Subfunction 34H, Enable/disable cursor emulation 528 Subfunction 35H, Switch active display 528 Subfunction 36H, Enable/disable screen refresh 529 Function 13H, Write string in teletype mode 529 Function 1AH, Get or set display combination code 530 Function 1BH, Get functionality/state information 531 Function 1CH, Save or restore video state 534 Int 11H, Get equipment configuration 535 Int 12H, Get conventional memory size 536 Int 13H, ROM BIOS disk driver 319 Function 00H, Reset disk system 536 Function 01H, Get disk system status 537 Function 02H, Read sector 538 Function 03H, Write sector 539 Function 04H, Verify sector 540 Function 05H, Format track 541 Function 06H, Format bad track 542 Function 07H, Format drive 543 Function 08H, Get drive parameters 543 Function 09H, Initialize fixed disk characteristics 544 Function 0AH, Read sector long 545 Function 0BH, Write sector long 546 Function 0CH, Seek 547 Function 0DH, Reset fixed disk system 548 Function 0EH, Read sector buffer 548 Function 0FH, Write sector buffer 549 Function 10H, Get drive status 549 Function 11H, Recalibrate drive 550 Function 12H, Controller RAM diagnostic 550 Function 13H, Controller drive diagnostic 551 Function 14H, Controller internal diagnostic 551 Function 15H, Get disk type 552 Function 16H, Get disk change status 552 Function 17H, Set disk type 553 Function 18H, Set media type for format 554 Function 19H, Park heads 554 Function 1AH, Format ESDI drive 555 Int 14H, ROM BIOS Serial communications port driver 111 Function 00H, Initialize communications port 556 Function 01H, Write character to communications port 557 Function 02H, Read character from communications port 558 Function 03H, Get communications port status 558 Function 04H, Extended initialize communications port 558 Function 05H, Extended communications port control 559 Int 15H, ROM BIOS I/O Subsystem Extensions Function 00H, Turn on cassette motor 560 Function 01H, Turn off cassette motor 560 Function 02H, Read cassette 561 Function 03H, Write cassette 562 Function 0FH, Format ESDI drive periodic interrupt 562 Function 21H Subfunction 00H, Read POST error log 563 Subfunction 01H, Write POST error log 563 Function 4FH, Keyboard intercept 564 Function 80H, Device open 564 Function 81H, Device close 565 Function 82H, Process termination 566 Function 83H, Event wait 566 Function 84H, Read joystick 567 Function 85H, SysReq key 568 Function 86H, Delay 568 Function 87H, Move extended memory block 569 Function 88H, Get extended memory size 570 Function 89H, Enter protected mode 570 Function 90H, Device wait 571 Function 91H, Device post 572 Function C0H, Get system environment 317, 573 Function C1H, Get address of extended BIOS data area 574 Function C2H Subfunction 00H, Enable/disable pointing device 574 Subfunction 01H, Reset pointing device 575 Subfunction 02H, Set sample rate 576 Subfunction 03H, Set resolution 576 Subfunction 04H, Get pointing device type 577 Subfunction 05H, Initialize pointing device interface 577 Subfunction 06H, Set scaling or get status 578 Subfunction 07H, Set pointing device handler address 579 Function C3H, Set watchdog time-out 580 Function C4H, Programmable option select 580 Int 16H, ROM BIOS keyboard driver 322 Function 00H, Read character from keyboard 581 Function 01H, Get keyboard status 582 Function 02H, Get keyboard flags 582 Function 03H, Set repeat rate 583 Function 04H, Set keyclick 584 Function 05H, Push character and scan code 585 Function 10H, Read character from enhanced keyboard 585 Function 11H, Get enhanced keyboard status 586 Function 12H, Get enhanced keyboard flags 586 Int 17H, ROM BIOS Parallel port printer driver 108-19 Function 00H, Write character to printer 587 Function 01H, Initialize printer port 587 Function 02H, Get printer status 588 Int 18H, ROM BASIC 588 Int 19H, ROM BIOS Reboot system 588 Int 1AH, Real-time (CMOS) Clock Driver Function 00H, Get tick count 589 Function 01H, Set tick count 589 Function 02H, Get time 590 Function 03H, Set time 590 Function 04H, Get date 591 Function 05H, Set date 591 Function 06H, Set alarm 591 Function 07H, Reset alarm 592 Function 0AH, Get day count 592 Function 0BH, Set day count 593 Function 80H, Set sound source 593 Int 20H, Terminate process 341 Int 21H, MS-DOS system functions function execution in a typical I/O request 281-82 function summary by category 337-40 (table) function summary by number 335-37 (table) Function 00H, Terminate process 342 Function 01H, Character input with echo 70, 148, 343 Function 02H, Character output 90, 344 Function 03H, Auxiliary input 110, 344-45 Function 04H, Auxiliary output 110, 345-46 Function 05H, Printer output 107, 346-47 Function 06H, Direct console I/O 70, 73, 90, 347-48 Function 07H, Unfiltered character input without echo 70, 73, 348-49 Function 08H, Character input without echo 70, 349-50 Function 09H, Display string 90, 350-51 Function 0AH, Buffered keyboard input 70-71, 351-52 Function 0BH, Check input status 70, 353 Function 0CH, Flush input buffer and then input 70, 353-54 Function 0DH, Disk reset 354-55 Function 0EH, Select disk 167, 355-56 Function 0FH, Open file 132, 137, 356-57 Function 10H, Close file 132, 357-58 Function 11H, Find first file 358-59 Function 12H, Find next file 360-61 Function 13H, Delete file 132, 361-62 Function 14H, Sequential read 132, 362-63 Function 15H, Sequential write 132, 363-64 Function 16H, Create file 132, 364-65 Function 17H, Rename file 132, 173, 366-67 Function 18H, Reserved 367 Function 19H, Get current disk 167, 168, 367 Function 1AH, Set DTA address 130, 132, 368 Function 1BH, Get default drive data 368-69 Function 1CH, Get drive data 370 Function 1DH, Reserved 371 Function 1EH, Reserved 371 Function 1FH, Reserved 371 Function 20H, Reserved 371 Function 21H, Random read 132, 372-73 Function 22H, Random write 132, 373-75 Function 23H, Get file size 132, 375-76 Function 24H, Set relative record number 132, 376 Function 25H, Set interrupt vector 147, 252, 253, 316, 377-78 Function 26H, Create new PSP 378-79 Function 27H, Random block read 132, 379-80 Function 28H, Random block write 132, 381-82 Function 29H, Parse filename 129, 132, 382 Function 2AH, Get date 384-85 Function 2BH, Set date 385 Function 2CH, Get time 386 Function 2DH, Set time 386-87 Function 2EH, Set verify flag 387-88 Function 2FH, Get DTA address 388-89 Function 30H, Get MS-DOS version number 148, 319, 389 Function 31H, Terminate and stay resident 252, 253, 390-91 Function 32H, Reserved 392 Function 33H, Get or set break flag, get boot drive 392-93 Function 34H, Reserved 393 Function 35H, Get interrupt vector 252, 316, 393-94 Function 36H, Get drive allocation information 394-95 Function 37H, Reserved 395 Function 38H, Get or set country information 395-98 Function 39H, Create directory 167, 398-99 Function 3AH, Delete directory 167, 399 Function 3BH, Set current directory 167, 400 Function 3CH, Create file 140, 401-2 Function 3DH, Open file 107, 110, 140, 204, 402-4 Function 3EH, Close file 140, 204, 404 Function 3FH, Read file or device 67, 69, 71, 109, 110, 141, 298, 300, 322, 405-6 Function 40H, Write file or device 35, 88, 107, 109, 110, 141, 298, 300, 322, 406-7 Function 41H, Delete file 141, 407-8 Function 42H, Set file pointer 141, 408-9 Function 43H, Get or set file attributes 141, 410-11 Function 44H, IOCTL (I/O control) 69, 93-94, 111, 204, 205, 411-34 Subfunction 00H, IOCTL: get device information 412-13 Subfunction 01H, IOCTL: set device information 414-15 Subfunction 02H, IOCTL: read control data from character device driver 415-16 Subfunction 03H, IOCTL: write control data to character device driver 416-17 Subfunction 04H, IOCTL: read control data from block device driver 418-19 Subfunction 05H, IOCTL: write control data to block device driver 419-20 Subfunction 06H, IOCTL: check input status 420-21 Subfunction 07H, IOCTL: check output status 421-22 Subfunction 08H, IOCTL: check if block device is removable 422-23 Subfunction 09H, IOCTL: check if block device is remote 423-24 Subfunction 0AH, IOCTL: check if handle is remote 424-25 Subfunction 0BH, IOCTL: change sharing retry count 425-26 Subfunction 0CH, IOCTL: generic I/O control for character devices 426-29 Subfunction 0DH, IOCTL: generic I/O control for block devices 429-32 Subfunction 0EH, IOCTL: get logical drive map 433 Subfunction 0FH, IOCTL: set logical drive map 434 Function 45H, Duplicate handle 141, 435 Function 46H, Redirect handle 141, 299, 436-37 Function 47H, Get current directory 167, 168, 437-38 Function 48H, Allocate memory block 196, 202, 323, 438-39 Function 49H, Release memory block 196, 323, 439-40 Function 4AH, Resize memory block 196, 198, 202, 219, 239, 322, 440-41 Function 4BH, Execute program (EXEC) 202, 299, 441-42 (see also EXEC function) Function 4CH, Terminate process with return code 26, 31, 35, 317, 443-44 Function 4DH, Get return code 221, 444-45 Function 4EH, Find first file 445-46 Function 4FH, Find next file 446-47 Function 50H, Reserved 447 Function 51H, Reserved 447 Function 52H, Reserved 447 Function 53H, Reserved 448 Function 54H, Get verify flag 448 Function 55H, Reserved 448 Function 56H, Rename file 141, 173, 449-50 Function 57H, Get or set file date and time 141, 450-51 Function 58H, Get or set allocation strategy 452-53 Function 59H, Get extended error information 130, 145, 148, 453-56 Function 5AH, Create temporary file 141, 457-58 Function 5BH, Create new file 141, 458-59 Function 5CH, Lock or unlock file region 141, 460-61 Function 5DH, Reserved 461 Function 5EH, Machine name and printer setup Subfunction 00H, Get machine name 461-62 Subfunction 02H, Set printer setup string 462-63 Subfunction 03H, Get printer setup string 463-64 Function 5FH, Device redirection Subfunction 02H, Get redirection list entry 464-65 Subfunction 03H, Redirect device 466-67 Subfunction 04H, Cancel device redirection 467-68 Function 60H, Reserved 468 Function 61H, Reserved 468 Function 62H, Get PSP address 468-69 Function 63H, Get DBCS lead byte table 469-70 Function 64H, Reserved 470 Function 65H, Get extended country information 470-74 Function 66H, Get or set code page 474-75 Function 67H, Set handle count 141, 475-76 Function 68H, Commit file 141, 476-77 Function 69H, Reserved 477 Function 6AH, Reserved 477 Function 6BH, Reserved 477 Function 6CH, Extended open file 141, 478-80 Int 22H, Terminate handler address 480 Int 23H, Ctrl-C handler address 317, 480-81 Int 24H, Critical-error handler address 147, 317, 481-82 Int 25H, Absolute disk read 482-84 Int 26H, Absolute disk write 319, 484-85 Int 27H, Terminate and stay resident 486-87 Int 28H, Reserved 487 Int 29H, Reserved 487 Int 2AH, Reserved 487 Int 2BH, Reserved 487 Int 2CH, Reserved 487 Int 2DH, Reserved 488 Int 2EH, Reserved 488 Int 2FH, Multiplex interrupt 488 Function 01H, Print spooler 488-89 Function 02H, ASSIGN 489 Function 10H, SHARE 490 Function B7H, APPEND 490-91 Int 33H, Microsoft Mouse driver 593 Function 00H, Reset mouse and get status 80, 594 Function 01H, Show mouse pointer 80, 594 Function 02H, Hide mouse pointer 80, 595 Function 03H, Get mouse position and button status 80, 595 Function 04H, Set mouse pointer position 80, 596 Function 05H, Get button press information 80, 596 Function 06H, Get button release information 80, 597 Function 07H, Set horizontal limits for pointer 80, 597 Function 08H, Set vertical limits for pointer 80, 598 Function 09H, Set graphics pointer shape 80, 598 Function 0AH, Set text pointer type 80, 599 Function 0BH, Read mouse motion counters 80, 599 Function 0CH, Set user-defined mouse event handler 80, 600 Function 0DH, Turn on light pen emulation 80, 601 Function 0EH, Turn off light pen emulation 80, 601 Function 0FH, Set mickeys to pixels ratio 80, 601 Function 10H, Set mouse pointer exclusion area 80, 602 Function 13H, Set double speed threshold 81, 602 Function 14H, Swap user-defined mouse event handlers 81, 603 Function 15H, Get mouse save state buffer size 81, 603 Function 16H, Save mouse driver state 81, 604 Function 17H, Restore mouse driver state 81, 604 Function 18H, Set alternate mouse event handler 81, 604 Function 19H, Get address of alternate mouse event handler 81, 606 Function 1AH, Set mouse sensitivity 81, 606 Function 1BH, Get mouse sensitivity 81, 607 Function 1CH, Set mouse interrupt rate 81, 607 Function 1DH, Select pointer page 81, 608 Function 1EH, Get pointer page 81, 608 Function 1FH, Disable mouse driver 81, 608 Function 20H, Enable mouse driver 81, 609 Function 21H, Reset mouse driver 81, 609 Function 22H, Set language for mouse driver messages 81, 610 Function 23H, Get language number 81, 610 Function 24H, Get mouse information 81, 611 Int 67H, Expanded Memory Manager functions 204, 205, 207 Function 40H, Get status 616 Function 41H, Get page frame address 616 Function 42H, Get number of pages 617 Function 43H, Allocate handle and pages 617 Function 44H, Map expanded memory page 618 Function 45H, Release handle and expanded memory 619 Function 46H, Get version 619 Function 47H, Save page map 620 Function 48H, Restore page map 620 Function 49H, Reserved 621 Function 4AH, Reserved 621 Function 4BH, Get handle count 621 Function 4CH, Get handle pages 622 Function 4DH, Get pages for all handles 623 Function 4EH Subfunction 00H, Save page map 623 Subfunction 01H, Restore page map 624 Subfunction 02H, Save and restore page map 624 Subfunction 03H, Get size of page map information 625 Function 4FH Subfunction 00H, Save partial page map 625 Subfunction 01H, Restore partial page map 626 Subfunction 02H, Get size of partial page map information 626 Function 50H Subfunction 00H, Map multiple pages by number 627 Subfunction 01H, Map multiple pages by address 627 Function 51H, Reallocate pages for handle 628 Function 52H Subfunction 00H, Get handle attribute 629 Subfunction 01H, Set handle attribute 629 Subfunction 02H, Get attribute capability 630 Function 53H Subfunction 00H, Get handle name 630 Subfunction 01H, Set handle name 631 Function 54H Subfunction 00H, Get all handle names 631 Subfunction 01H, Search for handle name 632 Subfunction 02H, Get total handles 632 Function 55H Subfunctions 00H and 01H, Map pages and jump 633 Function 56H Subfunctions 00H and 01H, Map pages and call 633 Subfunction 02H, Get stack space for map page and call 634 Function 57H Subfunction 00H, Move memory region 635 Subfunction 01H, Exchange memory regions 635 Function 58H Subfunction 00H, Get addresses of mappable pages 636 Subfunction 01H, Get number of mappable pages 637 Function 59H Subfunction 00H, Get hardware configuration 637 Subfunction 01H, Get number of raw pages 638 Function 5AH Subfunction 00H, Allocate handle and standard pages 638 Subfunction 01H, Allocate handle and raw pages 639 Function 5BH Subfunction 00H, Get alternate map registers 639 Subfunction 01H, Set alternate map registers 640 Subfunction 02H, Get size of alternate map register save area 641 Subfunction 03H, Allocate alternate map register set 641 Subfunction 04H, Deallocate alternate map register set 642 Subfunction 05H, Allocate DMA register set Subfunction 06H, Enable DMA on alternate map register set 643 Subfunction 07H, Disable DMA on alternate map register set 643 Subfunction 08H, Deallocate DMA register set 644 Function 5CH, Prepare expanded memory manager for warm boot 644 Function 5DH Subfunction 00H, Enable EMM operating system functions 645 Subfunction 01H, Disable EMM operating system functions 645 Subfunction 02H, Release access key 646 Intel 80x86 microprocessor family 4, 8, 38, 64, 203 interrupts and 246-51 Intel 8259A Programmable Interrupt Controller 112, 320 internal hardware interrupts 246 internal (intrinsic) commands 14 interrupt(s) 13, 244-45. See also Int 10H through Int 67H external hardware 247 internal hardware 246 servicing 250-51 software 247-49 types 244 interrupt handlers 16 example (ZERODIV.ASM) 254-58 MS-DOS and 252-53 servicing 250, 251 tasks 245 typical 251 interrupt (intr) routine, device-driver 266-67, 293. See also command code routines interrupt vector 17, 244 get 393-94 set 377-78 interrupt vector table 250 IOCTL (I/O control). See Int 21H, Function 44H IO.SYS file 16, 17 memory location of 18 J Japanese character set 6 joystick, read 567 K kernel. See DOS kernel keyboard get enhanced flags 586-87 get enhanced status 586 get flags 582 get status 582 input with/without echo 70 intercept 564 key repeat rate and delay 583-84 push character and scan code in buffer 585 read character from 581 read character from enhanced 585 set keyclick 584 keyboard input 65-72 buffered 351-52 Ctrl-C and Ctrl-Break handlers 72-80, 317 with handles 66, 67-69 read character from keyboard 581 with ROM BIOS functions 71-72 with traditional calls 69-71 Keyboard input with echo 70 Keyboard input without echo 70 Keyboard intercept 564 Korean character set 6 L .LIB files 44, 45, 58. See also Library Manager (LIB) Library Manager (LIB) 44, 58-60 operations prefix characters 58 table-of-contents listing for SLIBC.LIB 59 light pen get position 503 turn off emulation 601 turn on emulation 601 line printer (PRN) 12, 106, 298 LINK. See Object Linker (LINK) Load ROM 8-by-8 font 519 Load ROM 8-by-14 font 518-19 Load ROM 8-by-16 font 520-21 Load user font 518 Lock or unlock file region 460-61 Lotus/Intel/Microsoft Expanded Memory (LIM EMS). See Expanded Memory Specification (EMS) LPT1, LPT2, LPT3 devices 106, 298 .LST files 45 M machine name, get 461-62 Macro Assembler (MASM) 44, 45-47 command line mode 46 interactive mode 46 levels modules 37 procedures 41-42 segments 38-41 tutorials 63 version 5.1 switches 47 make files 61 MAKE utility 60-61 switches for 61 Map expanded memory page (EMS) 618 .MAP files 45 Map multiple pages by address (EMS) 627-28 Map multiple pages by number (EMS) 627 Map pages and call (EMS) 633-34 MASM. See Macro Assembler (MASM) master boot record 192 Media Check (function 01H) 270-71 memory allocation dynamic, of additional 199-201 shrinking 197-99 conventional 196 moving blocks of data between extended memory and 213-15 expanded (see Expanded Memory Specification (EMS)) image of .COM file 26 image of .EXE file 31 location of disk bootstrap program in 17 location of IO.SYS in 18 location of ROM bootstrap routine in 16 location of SYSINIT, DOS kernel, MSDOS.SYS in 19 making available, for EXEC function 218-19 map after startup 20 RAM 196 memory areas, 196. See also arena entries; arena headers; transient program area (TPA) memory block allocate 438-39 get/set allocation strategy 452-53 move extended 569-60 release 439-40 resize 440-41 memory interlace 203 memory management 195-215 arena headers 201-2 expanded memory 203-11 using 207-11 extended memory 212-15 Int 21H functions summary 339 MS-DOS applications compatibility and 316 using memory-allocation functions 197-202 memory-mapped input/output 86, 96-103 graphics mode 101-3 text mode 96-101 memory models 39 segments, groups, classes for 40 memory segment 321-22 memory size get conventional 536 get extended 570 mickeys, set to pixel ratio 601 Microsoft Mouse driver 593-611 miscellaneous system functions, Int 21H functions summary 340 MKDIR (MD) command 167 Monochrome/Printer Display Adapter (MDA) 86, 97, 98 example dump, regen buffer 98 MOUDEMO.C program 82-83 mouse. See also pointing device disable driver 608-9 driver 593 enable driver 609 get address of alternate event handler 606 get button press information 596 get button release information 597 get information 611 get language number 610 get mouse save state buffer size 603-4 get position and button status 595 get sensitivity 607 hide pointer 595 input 80-83 read motion counters 599-600 reset and get status 594 reset driver 609 save driver state 604 set alternate event handler 604-5 set double speed threshold 602 set graphics pointer shape 598 set interrupt rate 607 set language for driver messages 610 set pointer exclusion area 602 set pointer horizontal limits 597-98 set pointer page 608 set pointer position 596 set pointer vertical limits 598 set sensitivity 606 set text pointer type 599 set user-defined event handler 600-601 show pointer 594-95 summary of function calls 494-99 swap user-defined event handlers 603 Move extended memory block 569-70 Move memory region (EMS) 635 MS-DOS. See also Operating System/2 (OS/2) genealogy 3-9 interrupt handlers and 252-53 loading 16-20 programming tools (see programming tools) structure 12-16 MS-DOS application programs, porting to OS/2 318-31 conversion 326-30 encapsulation 323, 324-25 MS-DOS function calls and OS/2 counterparts 328-29 optimization 330-31 rationalization 322-23 ROM BIOS functions and OS/2 equivalents used in MS-DOS applications 330 segmentation 321-22 MS-DOS application programs, structure of 21-42 assembly-language programs 27-30, 37-42 .COM programs introduced 25-30 creation of 62-63 .EXE programs introduced 30-36 program procedures 41-42 program segment prefix 23-25 MS-DOS application programs, writing compatible 314, 315-17 check host capabilities 316 exception handling 317 input and output 316 memory management 316 process management 317 program structure 315 MS-DOS error codes 145-51 MS-DOS functions 334 conversion of, to OS/2 function calls 326-27 display functions 88-94 binary output mode 93-94 screen control 91-93 EXEC (see EXEC function) file control block (FCB) 129-39 handle 139-44 memory management/allocation 196, 197-202 OS/2 equivalents to 328-29 printer output 107-9 reference (see Section II) serial port 109-12 typical in-line code for call to 324 MSDOS.SYS file 13, 16 memory location of 19 MS-DOS versions 1.0 4-5, 138 1.25 5 2.00 5-6, 174 error codes 145 volume-label search under 175 2.11, 2.25 6 3.0 6-7, 138, 174 error codes 145-46 volume-label search under 176 3.1, 3.2, 3.3, 4.0 7 get number 389-90 support for select command code routines by 267-68 (table) Multi-Color Graphics Array (MCGA) 86, 102 Multiplex interrupt 488 N NAME statement 27, 33 NEAR attribute 27 vs FAR 29 NEAR RETURN 27 network functions, Int 21H functions summary 339 Nondestructive Read (function 05H) 274 non-disk-related errors 147, 148 (table) O Object Linker (LINK) 37, 44, 50-55 map produced by, of HELLO.EXE program 51 switches accepted by 53-55 object modules 37 libraries (see Library Manager (LIB)) linking .COM files from 27, 37. See also Object Linker (LINK) .OBJ files 45 Open file 356-57, 402-4 Operating System/2 (OS/2) 7 code optimization 330-31 compatibility issues 318-20 function calls equivalent to MS-DOS function calls 328-29 function calls equivalent to ROM BIOS function calls 330 porting MS-DOS applications to OS/2 320-31 ORG instruction 29 output. See character input/output; printer output; serial port output status, check 421-22 Output Status (command-code function 0AH) 276 Output Until Busy (function 10H) 278-79 overlays, loading with EXEC 240, 241-42 P PAGE command 27, 33 page frame 203 palette enable/disable default 526-27 get border and 514 get register 513 set 508-9 set border and 512-13 set register 511-12 parallel ports 106 parameter block, requesting EXEC function 220-21 parent programs 218 Park heads 554-55 Parse filename 382-84 partitions, fixed-disk 192-94 Paterson, Tim 4 path 166 PC-DOS version 1.0 4 version 1.1 5 version 2.0 5-6 version 3.0 193-94 piping parameters 24 pixel 101 formula to calculate bit position for 102-3 read graphics 510 set mickeys to pixel ratio 601-2 write graphics 509 pointing device enable/disable 574-75 get device type 577 get scaling or get status 578-79 initialize interface 577-78 input 80-83 reset 575 set handler address 579-80 set resolution 576-77 set sample rate 576 POP instruction 35 portability. See compatibility and portability POST (power-on self-test) read error log 563 write error log 563-64 Prepare expanded memory manager for warm boot (EMS) 644-45 Presentation Manager, OS/2 318 printer 106, 107-9. See also line printer (PRN); standard printer (stdprn) get setup strings 463-64 get status 588 initialize port 587 write character to 587 printer output 106, 107-9, 346-47. See also TALK.ASM program printer setup string get 463-64 set 462-63 printscreen, select alternate 526 Print spooler 488-89 PRN device 12, 106, 298-99 PROC command 29, 35, 41 procedure, declaring beginning/end of 29 process management for compatibility in MS-DOS applications 317 Int 21H functions summary 339 terminate process 566 Process termination 566 Programmable Interrupt Controller (PIC) 247 Programmable option select 580-81 programming tools 43-64 C Optimizing compiler 48-50 CREF utility 56-58 example using 62-63 EXE2BIN utility 55-56 file types 45 Library Manager 58-60 MAKE utility 60-61 MASM 45-47 (see also Macro Assembler (MASM)) Object Linker 50-55 (see also Object Linker (LINK)) resources and references 63-64 program modules, assembly-language 37 program procedures 41-42 program segment prefix (PSP) 15, 23-25 create new 378-79 get address 468-69 structure of 23 program segments, assembly-language 38-41 protected mode, enter 570-71 PROTO.ASM program 301-2 PROTO.C program 303 P-system operating system 5 Push character and scan code 585 PUSH instruction 35 R Random block read 379-80 Random block write 381-82 Random read 372-73 Random write 373-75 rationalizing code 322-23 raw mode 69 Read (function 04H) 273 Read cassette 561 Read character and attribute at cursor 506 Read character from communications port 558 Read character from enhanced keyboard 585 Read character from keyboard 581 Read control data from block-device driver 418-19 Read control data from character device driver 415-16 Read file or device 405-6 Read graphics pixel 510 Read joystick 567 Read mouse motion counters 599-600 Read POST error log 563 Read sector 538-39 Read sector buffer 548 Read sector long 545-46 Reallocate pages for handle (EMS) 628 Reboot system 588-89 Recalibrate drive 550 record(s) set relative number 376-77 using FCB functions 129-39 using handle functions 139-44 record operations, Int 21H functions summary 338-39 Redirect device 466-67 Redirect handle 436-37 redirection, input/output 24, 67, 298-99 cancel 467-68 redirection list entry, get 464-65 .REF files 45, 56 refresh buffer 86 regen buffer 86 example dump of MDA adapter 98 formula to determine offset 102 memory diagram showing location of 87 Release access key (EMS) 646 Release handle and expanded memory (EMS) 619 Release memory block 439-40 Removable Media (function 0FH) 278 REN(AME) command 14 Rename file 366-67, 449-50 request header format 265 command codes for (see command code routines, device-driver) reserved area, disk 182 reserved functions EMS 621 Int 21H functions summary 340 Reset alarm 592 Reset disk system 536-37 Reset fixed disk system 548 Reset mouse and get status 594 Reset mouse driver 609 Reset pointing device 575 resident device drivers 12 Resize memory block 440-41 RESTORE command 15 Restore mouse driver state 604 Restore page map (EMS) 620-21, 624 Restore partial page map (EMS) 626 RET instruction 41 retrace interval 100 return code get 444 terminate process with 443-44 RMDIR (RD) command 167 ROM 8-by-8 font load 519 set Int 43H for 523 ROM 8-by-14 font load 518-19 set Int 43H for 522-23 ROM 8-by-16 font load 520-21 set Int 43H for 523-24 ROM BASIC 588 ROM BIOS display functions 94-96, 330 interrupts of special importance to 247, 248-49 keyboard functions 67 input with 71-72 ROM BIOS compatibility 314-16, 317-18 avoid unstable hardware 318 check host capabilities 317-18 functions of, and OS/2 equivalents 330 ROM BIOS function calls. See also Section III summary 494-99 ROM bootstrap routine 16 root directory 166, 184-86, 187 partial hex dump 186 RS-232 serial-interface standard 106 RS-422 serial-interface standard 106 S Save and restore page map (EMS) 624-25 Save mouse driver state 604 Save or restore video state 534-35 Save page map (EMS) 620, 623 Save partial page map (EMS) 625-26 scan lines, set 526 screen control with MS-DOS functions 91-93 screen refresh, enable/disable 529 Search for handle name (EMS) 632 Seattle Computer Products 4 Seek 547 SEGMENT command 29, 33, 38 segment register 321 Select alternate printscreen 526 Select disk 355-56 selector 321 Select pointer page 608 Sequential read 362-63 Sequential write 363-64 serial port 106, 109-12. See also TALK.ASM program extended initialize port 558-59 extended port control 559-60 get status 558 initialize 556-57 read character from 558 write character to 557 Set alarm 591-92 Set alternate map registers (EMS) 640 Set alternate mouse event handler 604-5 Set block of color registers 515 Set block specifier 520 Set border color 512 Set color page state 515-16 Set color register 514-15 Set current directory 400 Set cursor position 501-2 Set cursor type 501 Set date 385, 591 Set day count 593 Set device information 414-15 Set disk type 553 Set display page 503-4 Set double speed threshold 602 Set DTA address 368 Set file pointer 408-9 Set graphics pointer shape 598 Set gray-scale values 517 Set handle attribute (EMS) 629 Set handle count 475-76 Set handle name (EMS) 631 Set horizontal limits for pointer 597-98 Set Int 1FH font pointer 521 Set Int 43H for ROM 8-by-8 font 523 Set Int 43H for ROM 8-by-14 font 522-23 Set Int 43H for ROM 8-by-16 font 523-24 Set Int 43H for user's font 522 Set interrupt vector 377-78 Set keyclick 584 Set language for mouse driver messages 610 Set Logical Device (function 18H) 280-81 Set logical drive map 434 Set media type for format 554 Set mickeys to pixels ratio 601 Set mouse interrupt rate 607 Set mouse pointer exclusion area 602 Set mouse pointer position 596 Set mouse sensitivity 606 Set palette and border 512-13 Set palette, background, or border 508-9 Set palette register 511-12 Set pointing device handler address 579-80 Set printer setup string 462-63 Set relative record number 376-77 Set repeat rate 583-84 Set resolution 576-77 Set sample rate 576 Set scaling or get status 578-79 Set scan lines 526 Set sound source 593 Set text pointer type 599 Set tick count 589-90 Set time 386-87, 590 Set user-defined mouse event handler 600-601 Set verify flag 387-88 Set vertical limits for pointer 598 Set video mode 500-501 Set watchdog time-out 580 SHARE 490 shell. See COMMAND.COM file; command processor (shell) SHELL.ASM program 229-38 SHELL.C program 225-29 Show mouse pointer 594-95 SLIBC.LIB, table-of-contents listing for 59 Softech company 5 software interrupts, 247-49 sound source, set 593 STACK attribute 31 stack pointer (SP) register 25-26, 31, 35 stack segment 38 stack segment (SS) register 31, 35 standard auxiliary device (stdaux) 20, 323 default device 298 handle 66 standard error device (stderr) 20 default device 298 handle 66 standard input device (stdin) 20 default device 298 handle 66, 67 standard list device 20, 323 standard output device (stdout) 20 default device 298 handle 66 standard printer (stdprn) default device 298 handle 66 strategy (strat) routine, device-driver 265, 293 string(s) display 350-51 Swap user-defined mouse event handlers 603 Switch active display 528-29 switches C Optimizing compiler 49-50 Library Manager 60 Macro Assembler 47 Make utility 61 Object Linker 53-55 SYSINIT module 17, 18, 20 installing device drivers 293 memory location of 19 SysReq key 568 system file table 140-41 T TALK.ASM program 113-26 teletype mode write character in 510-11 write string in 529-30 terminal-emulator program. See TALK.ASM program Terminate and stay resident 390-91, 486-87 Terminate handler address 480 Terminate process 341, 342 Terminate process with return code 443-44 text-mode memory-mapped programming 96-101 threads 331 time and date day count 592, 593 get date 384-85, 591 get time 386, 590 set date 385, 591 set time 386-87, 590 TITLE command 27, 33 Toggle blink/intensity bit 513 transient program 15, 22. See also .COM program file(s); .EXE (executable) program file(s) transient program area (TPA) 15, 196. See also arena entries; arena headers TREE command 174 TRYBREAK.C program 78-79 Turn off cassette motor 560-61 Turn on cassette motor 560 Turn off light pen emulation 601 Turn on light pen emulation 601 U Unfiltered character input without echo 348-49 UNIX/XENIX operating system 66, 128, 139 user font load 518 set Int 1FH pointer 521 set Int 43H for 522 V verify flag, get 448 Verify sector 540 video display 85-103 adapters 86-87 enable/disable 527 get functionality/state information 531-34 get or set combination code 530-31 memory-mapped techniques 96-103 graphics mode 101-3 text mode 96-101 MS-DOS display functions 88-94 binary output mode 93-94 screen control with 91-93 ROM BIOS display functions 94-96 save or restore video state 534-35 support considerations 88 switch active display 528-29 Video Graphics Array (VGA) 86, 97, 98, 102 video mode get 511 set 500-501 VOL command 174 volume labels 174-76 search, using extended file control block 175 W watchdog time-out, set 580 window initialize or scroll down 505-6 initialize or scroll up 505 Windows 7, 318 Write (function 08H) 275 Write cassette 562 Write character and attribute at cursor 506-7 Write character at cursor 507-8 Write character in teletype mode 510-11 Write character to communications port 557 Write character to printer 587 Write control data to block-device driver 419-20 Write control data to character-device driver 416-17 Write File or Device 406-7 Write graphics pixel 509 Write POST error log 563-64 Write screen in teletype mode 529-30 Write sector 539 Write sector buffer 549 Write sector long 546-47 Write with Verify (function 09H) 276 Z ZERODIV.ASM program 254, 255-58 Zilog Z-80 microprocessor 4