** Programmer's Technical Reference for MSDOS and the IBM PC ** USA copyright TXG 392-616 ALL RIGHTS RESERVED 컴컴컴컴컴컴컴컴컴컴컴컴컴� DOSREF (tm) 쳐컴컴컴컴컴컴컴컴컴컴컴컴컴 ISBN 1-878830-02-3 (disk-based text) Copyright (c) 1987, 1994 Dave Williams 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Shareware Version, 01/20/94 � � Please Register Your Copy � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴� C H A P T E R F O U R DOS INTERRUPTS AND FUNCTION CALLS C O N T E N T S General Programming Guidelines .................................. 4**1 DOS Registers ................................................... 4**2 DOS Stacks ...................................................... 4**3 DOS Interrupts .................................................. 4**4 Interrupt 20h (Terminate) ....................................... 4**5 DOS Services (quick list) ....................................... 4**6 Calling the DOS Services ........................................ 4**7 Version Specific Information .................................... 4**8 Compatibility Problems With DOS 4.0+ ............................ 4**9 PCjr Cartridge Support .......................................... 4**10 eDOS 4.0 ........................................................ 4**11 DOS Services in Detail .......................................... 4**12 General Programming Guidelines .................................. 4**1 Microsoft recommends avoiding the "old style" DOS 1.0 (01h-0Ch and 26h) system calls wherever possible. Programmers are urged to use the "new style" (DOS 2.0+) handle calls instead. Do not use "undocumented" functions unless they are critical to your application and no other reasonable workaround can be found. Remember that your programs may have to run under various versions of DOS, DOS clones such as Digital's DR-DOS, the OS/2 Compatibility Box, or Unix DOS Emulation Window. Such environments or OS simulations do not always implement the undocumented calls. DOS 2.x and 3.x lack many of the enhancements found in later versions. Your application should check the minimum required DOS version when specific features are required. Do not test for a higher version than necessary or you will cause problems for machines running older versions of DOS, such as business machines which are seldom upgraded, laptops with DOS in ROM, etc. Direct disk access via hardware or the BIOS should be avoided unless your program will only be run on specific hardware or under certain circumstances. Some versions of DOS 2.x treat their disks in a manner much like 3.x. Some vendors added multiple DOS partitions or oversize drive support prior to the "official" 3.3 release. Not all these systems work in the same way! New-type SCSI or ESDI hard disk controllers do not always emulate all the standard BIOS calls. DOS Registers ................................................... 4**2 DOS uses the following registers, pointers, and flags when it executes interrupts and function calls: 旼컴컴컴컴컴컴컴컴컫컴컴컴컴쩡컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿒ENERAL REGISTERS 퀁egister� definition � � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � � AX � accumulator (16 bit) � � � AH � accumulator high-order byte ( 8 bit) � � � AL � accumulator low order byte ( 8 bit) � � � BX � base (16 bit) � � � BH � base high-order byte ( 8 bit) � � � BL � base low-order byte ( 8 bit) � � � CX � count (16 bit) � � � CH � count high order byte ( 8 bit) � � � CL � count low order byte ( 8 bit) � � � DX � data (16 bit) � � � DH � date high order byte ( 8 bit) � � � DL � data low order byte ( 8 bit) � 쳐컴컴컴컴컴컴컴컴컵컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿞EGMENT REGISTERS 퀁egister� definition � � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � � CS � code segment (16 bit) � � � DS � data segment (16 bit) � � � SS � stack segment (16 bit) � � � ES � extra segment (16 bit) � 쳐컴컴컴컴컴컴컴컴컵컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿔NDEX REGISTERS 퀁egister� definition � � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � � DI � destination index (16 bit) � � � SI � source index (16 bit) � 쳐컴컴컴컴컴컴컴컴컵컴컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿛OINTERS 퀁egister� definition � � 쳐컴컴컴컵컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴캑 � � SP � stack pointer (16 bit) � � � BP � base pointer (16 bit) � � � IP � instruction pointer (16 bit) � 쳐컴컴컴컴컴컴컴컴컨컴컴컴컴좔컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� 쿑LAGS AF, CF, DF, IF, OF, PF, SF, TF, ZF � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� These registers, pointers, and flags all work on the "lowest common denominator" 8088-8086 CPU. DOS makes no attempt to use any of the special or enhanced instructions available on the later CPUs which will execute 8088 code, such as the 80186, 80286, 80386, or NEC V20, V30, V40, or V50. User registers except AX are preserved unless information is passed back to the register as indicated in specific function calls. For PC-MOS/386 on a 386 CPU, the task switching logic saves the upper half of the 32-bit registers and the complete FS and GS registers. The Intel 8088 processors supplied for the early IBM PCs were defective and did not handle the stack register properly on an INT instruction. DOS 2.1 added extra logic around interrupt calls for stack handling; this is the major difference between 2.0 and 2.1. DOS Stacks ...................................................... 4**3 When DOS takes control after a function call, it switches to an internal stack. Registers which are not used to return information (other than AX) are preserved. The calling program's stack must be large enough to accomodate the interrupt system - at least 128 bytes in addition to other interrupts. DOS actually maintains three stacks - stack 1: 384 bytes (in DOS 3.1) for functions 00h and for 0Dh and up, and for ints 25h and 26h. stack 2: 384 bytes (in DOS 3.1) for function calls 01h through 0Ch. stack 3: 48 bytes (in DOS 3.1) for functions 0Dh and above. This stack is the initial stack used by the int 21h handler before it decides which of the other two to use. It is also used by function 59h (get extended error), and 01h to 0Ch if they are called during an int 24h (critical error) handler. Functions 33h (get/set break flag), 50h (set process ID), 51h (get process ID) and 62h (get PSP address) do not use any DOS stack under DOS 3.x (under 2.x, 50h and 51h use stack number 2). IBM and Microsoft made a change back in DOS 3.0 or 3.1 to reduce the size of DOS. They reduced the space allocated for scratch areas when interrupts are being processed. The default seems to vary with the DOS version and the machine, but 8 stack frames seems to be common. That means that if you get more than 8 interrupts at the same time, clock, disk, printer spooler, keyboard, com port, etc., the system will crash. It usually seems to happen on a network. DOS 3.2 does some different stack switching than previous versions. The interrupts which are switched are 02h, 08h, 09h, 0Ah, 0Bh, 0Ch, 0Dh, 0Eh, 70h, 72h, 73h, 74h, 75h, 76h, and 77h. DOS 3.2 has a special check in the initialization code for a PCjr and don't enable stack switching on that machine. DOS 3.3 was changed so that no stack switching occurs on PC, PC-XT, or the PC Portable, and defaults to 9 stacks of 128 bytes in an AT. Additional stacks can be allocated when DOS loads by using the STACKS= command in CONFIG.SYS. These stacks are in addition to the 3 internal DOS stacks. STACKS=16,256 means allow 16 interrupts to interrupt each other and allow 256 bytes for each for scratch area. DOS Interrupts .................................................. 4**4 Microsoft recommends that a program wishing to examine or set the contents of any interrupt vector use the DOS function calls 35h and 25h provided for those purposes and avoid referencing the interrupt vector locations directly. DOS reserves interrupt numbers 20h to 3Fh for its own use. This means absolute memory locations 80h to 0FFh are reserved by DOS. Interrupt 20h - Terminate Current Program ....................... 4**5 (0:0080h) Issue int 20h to exit from a program. This vector transfers to the logic in DOS to restore the terminate address, the Ctrl-Break address, and the critical error exit address to the values they had on entry to the program. All the file buffers are flushed and all handles are closed. You should close all files changed in length (see function calls 10h and 3Eh) before issuing this interrupt. If the changed file is not closed, its length, time, and date are not recorded correctly in the directory. This call is intended for use with .COM programs only. For a program to pass a completion code or an error code when terminating, it must use either function call 4Ch (Terminate a Process) or 31h (Terminate Process and Stay Resident). These two methods are preferred over using int 20h and the codes returned by them can be interrogated in batch processing. Important: Before you issue an interrupt 20h, your program must ensure that the CS register contains the segment of its Program Segment Prefix. Interrupt 20h DOS - Terminate Program entry no parameters return The following vectors are restored from the Program Segment Prefix: PSP offset interrupt description 0Ah 22h Program Terminate 0Eh 23h Control-C 12h 24h Critical Error note 1) IBM and Microsoft recommend using int 21h Fn 4Ch. Using int 20h is officially frowned upon since the introduction of DOS 2.0. 2) In DOS 3.2 at least, int 20h merely calls int 21h, fn 00h. 3) Supported by PC-MOS/386. DOS Services (quick list) ....................................... 4**6 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 쿔nterrupt 21h Function Call Request � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸 (0:0084h) DOS provides a wide variety of function calls for character device I/O, file management, memory management, date and time functions, execution of other programs, and more. They are grouped as follows: call description 00h program terminate 01h-0Ch character device I/O, CP/M compatibility format 0Dh-24h file management, CP/M compatibility format 25h-26h nondevice functions, CP/M compatibility format 27h-29h file management, CP/M compatibility format 2Ah-2Eh nondevice functions, CP/M compatibility format 2Fh-38h extended functions 39h-3Bh directory group 3Ch-46h extended file management 47h directory group 48h-4Bh extended memory management 54h-57h extended functions 5Eh-5Fh networking 60h-62h extended functions 63h-66h enhanced foreign language support List of DOS services: * = undocumented 00h terminate program 01h get keyboard input 02h display character to STDIO 03h get character from STDAUX 04h output character to STDAUX 05h output character to STDPRN 06h direct console I/O - keyboard to screen 07h get char from std I/O without echo 08h get char from std I/O without echo, checks for ^C 09h display a string to STDOUT 0Ah buffered keyboard input 0Bh check STDIN status 0Ch clear keyboard buffer and invoke keyboard function o 0Dh flush all disk buffers o 0Eh select disk 0Fh open file with File Control Block 10h close file opened with File Control Block 11h search for first matching file entry 12h search for next matching file entry 13h delete file specified by File Control Block 14h sequential read from file specified by File Control Block 15h sequential write to file specified by File Control Block 16h find or create firectory entry for file 17h rename file specified by file control block 18h* unknown o 19h return current disk drive o 1Ah set disk transfer area (DTA) 1Bh get current disk drive FAT 1Ch get disk FAT for any drive 1Dh* unknown 1Eh* unknown 1Fh read DOS disk block, default drive 20h* unknown 21h random read from file specified by FCB 22h random write to file specified by FCB 23h return number of records in file specified by FCB 24h set relative file record size field for file specified by FCB o 25h set interrupt vector 26h create new Program Segment Prefix (PSP) 27h random file block read from file specified by FCB 28h random file block write to file specified by FCB 29h parse the command line for file name o 2Ah get the system date o 2Bh set the system date o 2Ch get the system time o 2Dh set the system time o 2Eh set/clear disk write VERIFY o 2Fh get the Disk Transfer Address (DTA) o 30h get DOS version number 31h TSR, files opened remain open 32h read DOS Disk Block o 33h get or set Ctrl-Break 34h INDOS Critical Section Flag o 35h get segment and offset address for an interrupt o 36h get free disk space 37h* get/set option marking character (SWITCHAR) o 38h return country-dependent information o 39h create subdirectory o 3Ah remove subdirectory o 3Bh change current directory o 3Ch create and return file handle o 3Dh open file and return file handle o 3Eh close file referenced by file handle o 3Fh read from file referenced by file handle o 40h write to file referenced by file handle o 41h delete file o 42h move file pointer (move read-write pointer for file) o 43h set/return file attributes o 44h device IOCTL (I/O control) info o 45h duplicate file handle o 46h force a duplicate file handle o 47h get current directory o 48h allocate memory o 49h release allocated memory o 4Ah modify allocated memory o 4Bh load or execute a program o 4Ch terminate prog and return to DOS o 4Dh get return code of subprocess created by 4Bh o 4Eh find first matching file o 4Fh find next matching file 50h* set new current Program Segment Prefix (PSP) 51h* puts current PSP into BX 52h* pointer to the DOS list of lists 53h* translates BPB (Bios Parameter Block, see below) o 54h get disk verification status (VERIFY) 55h* create PSP: similar to function 26h o 56h rename a file o 57h get/set file date and time 58h get/set allocation strategy (DOS 3.x) o 59h get extended error information o 5Ah create a unique filename o 5Bh create a DOS file o 5Ch lock/unlock file contents 5Dh DOS internal functions 5Eh* network printer 5Fh* network redirection 60h* parse pathname (TRUENAME) 61h* unknown 62h get program segment prefix (PSP) 63h* get lead byte table (DOS 2.25) 64h* unknown 65h get extended country information (DOS 3.3) 66h get/set global code page table (DOS 3.3) 67h set handle count (DOS 3.3) 68h commit file (DOS 3.3) 69h disk serial number (DOS 4.0) 6Ah unknown 6Bh unknown 6Ch extended open/create (DOS 4.0) Items marked with 'o' are explicitly supported in the OS/2 1.x DOS Compatibility Box, according to Microsoft. Most everything is supported in the OS/2 2.0 Virtual DOS Machine, according to IBM. Calling the DOS Services ........................................ 4**7 The DOS services are invoked by placing the number of the desired function in register AH, subfunction in AL, setting the other registers to any specific requirements of the function, and invoking int 21h. When the interrupt is called, all register and flag values are pushed into the stack. Int 21h contains a pointer into an absolute address in the IBMDOS.COM file. This address is the main loop for the DOS command handler. The handler pops the register values, compares them to its list of functions, and executes the function if valid. When the function is complete, it may pass values back to the command handler. The handler will push the values into the stack and then return control to the calling program. Most functions will return an error code; some return more information. Details are contained in the listings for the individual functions. Extended error return codes for most functions may be obtained by calling function 59h. Register settings listed are the ones used by DOS. Some functions will return with garbage values in unused registers. Do not test for values in unspecified registers; your program may exhibit odd behavior. DS:DX pointers are the data segment register (DS) indexed to the DH and DL registers (DX). DX always contains the offset address, DS contains the segment address. The File Control Block services (FCB services) were part of DOS 1.0. Since the release of DOS 2.0, Microsoft has recommended that these services not be used. A set of considerably more enhanced services (handle services) were introduced with DOS 2.0. The handle services provide support for wildcards and subdirectories, and enhanced error detection via function 59h. The FCB calls also do not support the sharing modes or file locking functions of the handle calls, making them unsafe for use with networks or multitaskers. The data for the following calls was compiled from various Intel, Microsoft, IBM, and other publications. There are many subtle differences between MSDOS and PCDOS and between the individual versions. Differences between the versions are noted as they occur. There are various ways of calling the DOS functions. For all methods, the function number is loaded into register AH, subfunctions and/or parameters are loaded into AL or other registers, and call int 21h by one of the following methods: A) call interrupt 21h directly (the recommended procedure) B) perform a long call to offset 50h in the program's PSP. 1) This method will not work under DOS 1.x. 2) Though recommended by Microsoft for DOS 2.0, this method takes more time and is no longer recommended. C) place the function number in CL and perform an intrasegment call to location 05h in the current code segment. This location contains a long call to the DOS function dispatcher. 1) IBM recommends this method be used only when using existing programs written for different calling conventions. (such as converting CP/M programs). This method should be avoided unless you have some specific use for it. 2) AX is always destroyed by this method. 3) This method is valid only for functions 00h-24h. D) PC-MOS/386' virtualization scheme results in 200-400+ clocks per interrupt when run on an 80286 machine since it has to flip in and out of protected mode at CPU ring 0. TSL recommends the following procedure for apps that must run quickly on 286 machines: 1) PUSHF 2) CLI 3) CALL DWORD PTR[vector-contents] This avoids flipping in and out of protected mode and the attendant overhead. However, TSL specifies this technique should not be used with native-mode MOS applications. There are also various ways of exiting from a program. (assuming it is not intended to be a TSR). All methods except call 4Ch must ensure that the segment register contains the segment address of the PSP. A) Interrupt 21h, function 4Ch (Terminate with Result Code). This is the "official" recommended method of returning to DOS. B) Interrupt 21h, function 00h (Exit Program). This is the early style int 21h function call. It simply calls int 20h. C) Interrupt 20h (Exit). D) A JMP instruction to offset 00h (int 20h vector) in the Program Segment Prefix. This is just a roundabout method to call int 20h. This method was set up in DOS 1.0 for ease of conversion for CP/M programs. It is no longer recommended for use. E) A JMP instruction to offset 05h (int 21 vector) in the Program Segment Prefix, with AH set to 00h or 4Ch. This is another CP/M type function. Version Specific Information .................................... 4**8 * Function Calls: DOS 2.x supports function calls 00h to 57h. DOS 2.25 is the only version to support function 63h (foreign keyboard) DOS 3.x has more sophisticated error handling and detection function calls available than 2.x. DOS 3.0 supports function calls 00h to 5Ch and 62h, including new and changed function calls for version 3.0: 3Dh Open File 59h Get Extended Error 5Ah Create Temporary File 5Bh Create New File 5Ch Lock/Unlock File Access 62h Get Program Segment Prefix Address DOS 3.1 supports function calls 00h to 62h, including the new and changed function calls for DOS 3.1: 5E00h Get Machine Name 5E02h Set Printer Setup 5E03h Get Printer Setup 5F02h Get Redirection List Entry 5F03h Redirect Device 5F04h Cancel Redirection DOS 3.2 supports the following new functions: 44h extended IOCTL functions DOS 3.3 supports the following new functions: 44h extended IOCTL functions 65h get extended country information (DOS 3.3) 66h get/set global code page table (DOS 3.3) 67h set handle count (DOS 3.3) 68h commit file (DOS 3.3) DOS 4.0 supports the following new functions: 44h extended IOCTL functions 69h disk serial number 6Ch extended open/create DOS 5.0 supports the following new int 21h functions: 30h sub 00h Get OEM ID number sub 01h Get version flag 33h sub 06h Return "real" DOS version number 44h sub 0Dh/68h, Sense Media Type sub 10h Query IOCTL handle sub 11h Query IOCTL device 4Bh sub 01h load but don't execute (formerly undocumented) sub 05h Enter EXEC State 51h Get Program Segment Prefix (formerly undocumented) 58h sub 02h Get UMB Link Status sub 03h Set UMB Link Status 65h Get Extended Country Information sub 05h Get filename character table sub 20h Convert character sub 21h Convert string sub 22h Convert ASCIIZ string ...and the following other functions: 2Fh sub 1680h MS-DOS Idle Call Task Switcher API DOS 6.0 supports the following new int 21h functions: 44h sub 04h adds DoubleSpace flush PCjr Cartridge Support .......................................... 4**9 ========================== ibm.dos/secrets.2 #1337, from jswitzer, 525 chars, Sat Jul 29 08:48:15 1989 This is a comment to message 1334. -------------------------- The PCJr ROM cartridges have a command table that lists the name of each supported command and its vector in the ROM. It does the ROM match first before the internal command match, actually, so it will execute what it finds there. Now that I think about it, this means that you could burn your own ROMs in the proper format and get your own commands. Neat, I guess. As to it being in command.com, my DOS 3.3 version has some of the code about 1A4C. Do a search with debug for "55 AA" and you'll find the main routine. Read:comment Comment to message number 1337. Enter text. End with '.' > 55 AA, that's right. That's the ID for a valid ROM. I'll fire up > symdeb and poke through COMMAND if I can find my little white cane... ========================== ibm.dos/secrets.2 #1776, from jswitzer, 319 chars, Tue Sep 19 01:33:09 1989 This is a comment to message 1773. -------------------------- Actually, you can NOP all of the PCJr code without problems -- AST and Toshiba both have COMMAND.COM without it, and no major problems. The interesting thing is that PC-DOS 4.0x still has it, and they explicity say that DOS 4 is NOT supported on the PCJr (*they* meaning IBM, of course). What can you figure, huh? Read:comment Comment to message number 1776. Enter text. End with '.' > I sold my PCjr this morning (I swear to Baud!) and therefore can't make >a test to see what would happen with 4.0 on the Jr. If IBM still sells >the PC/JX in Japan that might be the reason for continuing cartridge >support, since the machine is PCjr-based (well, about the way a PS/2 is >PC-based). > I used to run Toshiba DOS 2.11V on the Jr since it was provably faster >on screen updates and disk access than IBM 2.1 (with a Jr, it doesn't take >much to make a noticable difference). The only cartridges I had were >ColorPaint and BASIC, and I can't remember if I used 2.11 with them or >not. > ========================== ibm.dos/secrets.2 #1777, from jswitzer, 251 chars, Tue Sep 19 01:34:24 1989 -------------------------- The PCJr code in COMMAND.COM is ONLY executed on the PCJr and the PCJr doesn't support normal BIOS expansion ROMs, only the expansion cartridges. So, no conflict. If you patch out the check for the PCJr machine ID, though, good luck! John Switzer Read:comment Comment to message number 1777. Enter text. End with '.' > Ummm..... lemme go back and look at the listing again. The way it looked >the first time, it seemed like ALL commands went through the loop. Compatibility Problems With DOS 4.0 ............................. 4**10 Compatibility problems with DOS 4.00 lie mainly in int 2Ah and int 2Fh. While 2Ah was always reserved, some network software uses this interrupt. IBM and Microsoft documentation prior to 4.0 strongly implies that int 2Fh functions not already used by PRINT.COM were open for general use. DOS 4.00 grabs a number of these functions. The difference in disk handling when >32mb partitions are used causes problems with some older software. Most DOS 4.00 external programs (ASSIGN, SUBST, etc) check for files being printed - including LABEL. This is part of the enhanced network support. Almost all DOS 4.00 externals make checks for NETBIOS too. DOS 5.0 ditched most of this peculiar stuff, making for a much more stable product. eDOS 4.0 ........................................................ 4**11 Microsoft had announced their intent to build a multitasking, multiuser version of MSDOS as early as 1982. As mentioned in Chapter 1, the DOS 4.0 issued to selected OEMS in England and Europe in '86/'87 is not the same code that was released here as DOS 4.0 in 1988. Microsoft shipped betas of "DOS 4.0" in the US during the same time period, but the product was never release in the US. The European DOS 4.0 (eDOS?) is a multitasking DOS written by Microsoft, while the US DOS 4.0 is a single tasking DOS written by IBM. eDOS 4.0 was released in Europe after 3.1, but before 3.2. (abstracted from a pre-release document): `Microsoft Multitasking MS-DOS Product Specification' dated April 28, 1986 MS-DOS 4.0 is a multitasking operating system, developed from and compatible with MS-DOS 3.1. It supports true multitasking which gives the user the illusion of and benefits from many independent computers. Further, MS-DOS 4.0 allows most existing MS-DOS 2.x and 3.x applications to run without change in the MS-DOS 4.0 multitasking environment. (end of abstract). Gordon Letwin of Microsoft had this to say about eDOS: (excerpted from "Turning Off The Car To Change Gears" Microsoft Systems Journal, volume 2, number 2. May 1987) "DOS 4 was the first product to result from Microsoft's multitasking DOS effort. We began it even before IBM introduced the PC AT. It was an ambitious project that was originally to include a protected mode with mode switching capabilities so it could run on the 8086 or the 286. A general-purpose multitasking system needs to run in both modes: the unprotected 8086 mode so that we can run existing DOS applications, and the protected 286 mode so that we can multitask arbitrary, unrelated applications. But the architecture of the 286 caused some delays. Although we knew the project would be difficult, it was only after we'd gotten deeply into it that we realized just how difficult it would be. As a result, DOS 4 became too complicated for our schedules. Because of the pressure of customer demand as well as that of previous commitments, we broke the project into two parts. DOS 4 runs only in real mode and provides multitasking only for specialized applications. DOS 5, which has now been released as OS/2, includes the protected mode and other features. DOS 4 was delivered in the last half of 1986 and is being sold in special application environments, primarily in Europe. It is a specialized product that can share the market with OS/2, because it runs on 8086 hardware, while OS/2 requires a 286. The move from DOS 4 to OS/2 was a gradual evolutionary process." (end of excerpt) eDOS 4.0 consisted of one main program (DOS2/3 compatible) and several multitasking (background) programs that had to be written specially. The whole lot was constrained to fit in the single 640k memory map. int 21h functions: (some of these appeared in later versions of DOS) AEXEC Identical to EXEC sub 4. CREATMEM creates a named area of memory which may be accessed by other processes. (shared memory \SHAREMEM\...) CRITENTER, CRITLEAVE (semaphore routines) CRITERR (This is the one that should have been in DOS 3) Enables hard error processing or automatically fails hard errors. CWAIT Waits for return code from asynchronous process. Returns when any child process terminates. Children may also be started as orphans in which case you cannot WAIT for them. EXEC 4Bh (sub function 4) - Start async process. FREEZE Stops a specified process running. GETEXTENDEDERROR - As for DOS3 except it checks version number to specify the level of error handling - you may ask for a pointer to the hard error information packet for the latest hard error. GETMEM obtains access to a shared memory area previously created. GETPID Returns process ID and parents process ID. GET/SET MEMORY PARTITION SIZE foreground memory is used for ordinary apps. Background memory is used for DOS 4 apps that don't use the screen (or only use it through popup functions). Background apps can also use foreground memory but not vice versa. KILL Terminates a process. PBLOCK Block a process until matching PRUN is given. A timeout is also specified. A memory location is passed which must be matched in the PRUN. (semaphore) PIPE Create a pipe. Access it through READ/WRITE/CLOSE (but not LSEEK). PRUN Release a blocked process. (semaphore) RELEASEMEM Release access to shared memory. If the reference count hits zero then the memory is freed. RESUME Thaws a frozen process. SEND SIGNAL Signals were: SIGINTR, SIGTERM, SIGPIPE, SIGUSER1, SIGUSER2. Control C, End of program, Broken pipe, user def, user def. Actions were: Terminate process on receipt, ignore, accept, sender gets error or acknowledge received signal. The last one of these returns to the sender immediately - it is intended for use when processing the signal will take a long time. SETFILETABLE (86h) Install a new file handle table. (more than 20 files, as in DOS 3.3+?) SETPRI Sets process priority (for this process or entire subtree). SET SIGNAL HANDLER SLEEP Suspends the current process for given number of milliseconds. MSC 4.0 had a demo which called 'DOS_sleep' int 21h/fn 89h - does not appear to be implemented in known DOS versions. WAIT As for DOS 3. int 2Fh functions: CHECKPU check for popup package installation POSTPU open/close a popup screen SAVEPU save popup screen RESTOREPU restore popup screen Other useful features: eDOS 4.0 programs used the Windows .EXE format programs may share code segments improved device drivers the serial port had a full set of IOCTL calls (used through a new generic IOCTL call). device drivers could be multi-tasking. They had appropriate support routines to queue multiple requests (just like OS/2 later provided) interrupt driven serial ports sorted disk buffers before writing The following were listed as possible future enhancements: File system protection and (not yet available from MS, permissions though DRI has it) High performance file system (HPFS was delivered in OS/2 1.2) Installable file systems (IFS hook is present in US DOS 4.0, deleted in DOS 5 according to Gordon Letwin of Microsoft) Symbolic links (they don't have these on OS/2 even now do they?) Undelete (added with DOS 5.0) Long names, lowercase names, (OS/2 HPFS, NT NTFS) access/creation date/time, name of app creating file, revision number etc. According to bits of information picked up from BIX, Wang tested an alpha version of eDOS 4.0 for use on a laptop project sometime in 1985 but gave up because the OS was unable to cope with "ill behaved" programs in a reasonable fashion. I talked with one person who had beta-tested it for MS, who commented "the only thing it would run was COMMAND.COM." Microsoft has evidently either squashed eDOS completely or (likely) incorporated it into OS/2. I've been unable to determine if the French post office still uses eDOS, and to the best I can find out Apricot Computer never did much with it. DOSREF user John Dallman contributed the following: (July 1992) "You put a few notes in DOSREF about the multi-tasking MS-DOS 4.0 that was released in Europe during 1986/87. Notably, you wondered if it ever reached any customers. I'm sorry to tell you that the answer is yes - briefly. It was withdrawn owing to serious reliability problems: Apricot and ICL sold it in the UK, and I've had email from someone who bought a retail copy in Hong Kong." Ray Duncan had this to say about eDOS' metamorphosis: (PC Magazine, October 16, 1990 excerpted from Power Programming, page 464) "OS/2 as it exists today is a vastly different system than the protected-mode successor to DOS first envisioned by Microsoft in 1984 and 1985. The earliest version, internally known as DOS 5.0 or 286DOS, was small and relatively fast - it could even be booted from a floppy disk on a 1mb 80286 machine. The 286DOS application program interface (API), which was a proper superset of the DOS Int 21h, Microsoft Mouse Int 33h, and ROM BIOS video Int 10h and keyboard Int 16h interfaces, was small enough to be easily understood and allowed the straightforward porting of any DOS application. 286DOS was not burdened with a built-in graphical user interface; the original plan was to make a protected-mode version of Microsoft Windows available as a separate product that the user could run on top of 286DOS as an option. But somewhere along the torturous path from the original, experimental implementations of 286DOS to the retail product now known as OS/2, things went badly awry..." Microsoft Press' "MSDOS Encyclopedia" shows a reproduction of a late DOS 1.25 OEM brochure. Microsoft was touting future enhancements to 1.25 including Xenix-compatible pipes, process forks, and multitasking, as well as "graphics and cursor positioning, kanji support, multi-user and hard disk support, and networking." Microsoft certainly thought big, but, alas, the forks, multitasking, and multiuser support never came about, at least in US versions of DOS. Oddly, the flyer claims that... "MS-DOS has no practical limit on disk size. MS-DOS uses 4-byte XENIX OS compatible pointers for file and disk capacity up to 4 gigabytes." Umm... yeah. One sort of gets the idea nobody at Microsoft had a hard disk larger than 32 megabytes... For the record they actually delivered: Xenix-compatible pipes DOS 2.0 ("|" operator) process forks, and multitasking eDOS 4.0 (not delivered in the US) multi-user never delivered graphics and cursor positioning DOS 2.0 (ANSI.SYS, more than likely) kanji support DOS 2.01, 2.25 (double-byte char set) hard disk support DOS 2.0 (subdirectories) networking DOS 3.1 (file locking, MS Networks) Early Microsoft ads pumped DOS' Xenix-like features and promised Xenix functionality in future releases. We'll probably never know what the real story was behind eDOS - DOS 4 - DOS 5 - 286DOS - OS/2. Despite Gordon Letwin's acid comments about problems with the 80286 processor, I doubt the '286 was the barrier between users and a multitasking MSDOS. I also doubt there was any shortage of programming talent at Microsoft - Digital Research's Concurrent DOS and Software Link's PC-MOS were developed without undue trouble. Though it's highly unlikely anyone would ever need programming information for eDOS, I find the entire subject fascinating. IBM had not only promised the product, they ran ads for it in 1984-85. Who axed the project? Why? We'll likely never find out. DOS Services in Detail .......................................... 4**12 INT 21H DOS services Function (hex) * Indicates Functions not documented in the IBM DOS Technical Reference. Note some functions have been documented in other Microsoft or licensed OEM documentation. Function 00h Terminate Program Ends program, updates, FAT, flushes buffers, restores registers entry AH 00h CS segment address of PSP return none note 1) Program must place the segment address of the PSP control block in CS before calling this function. 2) The terminate, ctrl-break,and critical error exit addresses (0Ah, 0Eh, 12h) are restored to the values they had on entry to the terminating program, from the values saved in the program segment prefix at locations PSP:000Ah, PSP:000Eh, and PSP:0012h. 3) All file buffers are flushed and the handles opened by the process are closed. 4) Any files that have changed in length and are not closed are not recorded properly in the directory. 5) Control transfers to the terminate address. 6) This call performs exactly the same function as int 20h. 7) All memory used by the program is returned to DOS. DOS just goes up the chain of memory blocks and marks any that are owned by the PSP which is terminating as free. 8) TOS: $00 TERM. Returns system control to the program from which it started. If EXECed from a program, returns to that program. If started from DeskTop, returns to DeskTop. This is important for chaining program segments. 9) Files opened with FCBs are not automatically closed. 10) Supported in PC-MOS/386 compatibility mode, but not available for native MOS 386-mode applications. Function 01h Get Keyboard Input Waits for char at STDIN (if necessary), echoes to STDOUT entry AH 01h return AL ASCII character from STDIN (8 bits) note 1) Checks char for Ctrl-C, if char is Ctrl-C, executes int 23h. 2) For function call 06h, extended ASCII codes require two function calls. The first call returns 00h as an indicator that the next call will be an extended ASCII code. 3) Input and output are redirectable. If redirected, there is no way to detect EOF. 4) TOS: $1 CONIN. Char returns in D0. ASCII code of char in high byte, keyboard scan code in low byte. Will return scancode on keys which have no ASCII value. Function 02h Display Output Outputs char in DL to STDOUT entry AH 02h DL 8 bit data (usually ASCII character) return none note 1) If char is 08 (backspace) the cursor is moved 1 char to the left (nondestructive backspace). 2) If Ctrl-C is detected after input, int 23h is executed. 3) Input and output are redirectable. If redirected, there is no way to detect disk full. 4) TOS: $2 CONOUT. Char must be placed on the stack as the first word. The ASCII value of the char goes in the low byte and the high byte is zero. Chars are output to DEVICE #2, normal console output. Control characters and escape sequences are interpreted normally. 5) Under DOS 1.x, 02h sends a character to the active display. Under DOS 2.x and later, the char goes to STDOUT. Function 03h Auxiliary Input Get (or wait until) character from STDAUX entry AH 03h return AL ASCII char from auxiliary device note 1) AUX, COM1, COM2 is unbuffered and not interrupt driven. 2) This function call does not return status or error codes. For greater control it is recommended that you use the ROM BIOS routines (int 14h) or write an AUX device driver and use IOCTL. 3) At startup, PC-DOS initializes the first auxiliary port (COM1) to 2400 baud, no parity, one stop bit, and an 8-bit word. Versions of MSDOS may differ. 4) If Ctrl-C is has been entered from STDIN, int 23h is executed. 5) TOS: $03 AUXILIARY INPUT. Function returns when the character has been received. Char is returned in the low byte of D0. 6) Under DOS 1.x, the character is read from COM1. Under DOS 2.x and later, it is read from STDAUX. Function 04h Auxiliary Output Write character to STDAUX entry AH 04h DL ASCII char to send to AUX return none note 1) This function call does not return status or error codes. For greater control it is recommended that you use the ROM BIOS routine (int 14h) or write an AUX device driver and use IOCTL. 2) If Ctrl-C is has been entered from STDIN, int 23h is executed. 3) Default is COM1 unless redirected by DOS. 4) If the device is busy, this function will wait until it is ready. 5) TOS: $04 AUXILIARY OUTPUT. High byte should be zero, low byte is ASCII code. 6) Under DOS 1.x, the character is sent to COM1. Under DOS 2.x and later, it goes to STDAUX. Function 05h Printer Output Write character to STDPRN entry AL 05h DL ASCII code for character to send return none note 1) If Ctrl-C is has been entered from STDIN, int 23h is executed. 2) Default is PRN or LPT1 unless redirected with the MODE command. 3) If the printer is busy, this function will wait until it is ready. 5) TOS: $05 PRINTER OUTPUT. High byte of D0 is zero, low byte is character. Returns -1 if character is sent successfully. Times out after 30 seconds and resets D0 to zero. 6) Under DOS 1.x, this function writes to LPT1. Under DOS 2.x and higher it writes to STDPRN. Function 06h Direct Console I/O Get character from STDIN; echo character to STDOUT entry AH 06h DL 0FFh for console input, or 00h-0FEh for console output return ZF set no character available clear character recieved AL ASCII code for character note 1) Extended ASCII codes require two function calls. The first call returns 00h to indicate the next call will return an extended code. 2) If DL is not 0FFh, DL is assumed to have a valid character that is output to STDOUT. 3) This function does not check for Ctrl-C or Ctrl-PrtSc. 4) Does not echo input to screen. 5) If I/O is redirected, EOF or disk full cannot be detected. 6) TOS: $06 RAWCONIO. Get character from keyboard by calling with $FF in D0. ASCII and scan codes are returned as per CONIN. If a value other than $FF is used, it is printed to STDOUT at the current cursor position. This call interprets all control chars and escape sequences. 7) Under DOS 1.x, this call handles the keyboard and display directly. Under DOS 2.x and later, calls are routed to the STDOUT driver. Function 07h Direct Console Input Without Echo Get or wait for char at STDIN, returns char in AL (does not check BREAK) entry AH 07h return AL ASCII character from standard input device note 1) Extended ASCII codes require two function calls. The first call returns 00h to indicate the next call will return an extended code. 2) No checking for Ctrl-C or Ctrl-PrtSc is done. 3) Input is redirectable. 4) TOS: $07 DIRECT CONIN WITHOUT ECHO. Same as function 01h only does not echo character to screen. 5) Under DOS 1.x the keyboard is read directly. Under DOS 2.x and later the STDIN is polled. Function 08h Console Input Without Echo Get or Wait for char at STDIN, return char in AL (checks BREAK) entry AH 08h return AL char from standard input device note 1) Char is checked for ctrl-C. If ctrl-C is detected, executes int 23h. 2) For function call 08h, extended ASCII characters require two function calls. The first call returns 00h to signify an extended ASCII code. The next call returns the actual code. 3) Input is redirectable. If redirected, there is no way to check EOF. 4) TOS: $08 CONIN WITHOUT ECHO. Same as previous call. (no checking for control characters). 5) Under DOS 1.x the keyboard is read directly. Under DOS 2.x and later the STDIN is polled. Function 09h Print String Outputs Characters in the Print String to the STDOUT entry AH 09h DS:DX pointer to the Character String to be displayed return none note 1) The character string in memory must be terminated by a $ character. (ASCII 24h) 2) The $ is not displayed but remains in AL forever unless popped. 3) Output to STDOUT is the same as function call 02h. 4) TOS: $09 PRINT LINE. The address of the ASCIIZ string is placed on the stack as a parameter and is printed at the current cursor position. There is no limit to the size of the string. D0 contains the number of characters to be printed. Control and escape codes are evaluated. 5) Under DOS 1.x, this function writes to the screen. Under DOS 2.x and higher it writes to STDOUT. Function 0Ah Buffered Keyboard Input Reads characters from STDIN and places them in the buffer beginning at the third byte. entry AH 0Ah DS:DX pointer to an input buffer return none note 1) Min buffer size = 1, max = 255. 2) Char is checked for ctrl-C. If ctrl-C is detected, executes int 23h. 3) Format of buffer DX: byte contents 1 Maximum number of chars the buffer will take, including CR. Reading STDIN and filling the buffer continues until a carriage return ( or 0Dh) is read. If the buffer fills to one less than the maximum number the buffer can hold, each additional number read is ignored and ASCII 7 (BEL) is output to the display until a carriage return is read. (you must set this value) 2 Actual number of characters received, excluding the carriage return, which is always the last character. (the function sets this value) 3-n Characters received are placed into the buffer starting here. Buffer must be at least as long as the number in byte 1. n+1 Carriage return character (0Dh). 4) Input is redirectable. If redirected, there is no way to check EOF. 5) The string may be edited with the standard DOS editing commands as it is being entered. 6) Extended ASCII characters are stored as 2 bytes, the first byte being zero. 7) TOS: $0A READLINE. Fetches CR-terminated line from CONIN. The address of the buffer is passed as a parameter. Byte 1 is the maximum length of the line, byte 2 is the number of characters entered, byte 3 is the first character. Escape codes are not interpreted, but the normal editing control characters are. 8) Under DOS 1.x the keyboard is read directly. Under DOS 2.x and later the STDIN is polled. Function 0Bh Check Standard Input (STDIN) status Checks for character available at STDIN entry AH 0Bh return AL 00h if no character is available from STDIN 0FFh if a character is available from STDIN note 1) Checks for Ctrl-C. If Ctrl-C is detected, int 23h is executed. 2) Input can be redirected. 3) Checks for character only, it is not read into the application. 4) IBM reports that this call does not work properly under the DOSSHELL program in DOS 4.00 and 4.01. DOSSHELL will return all zeroes. This function works correctly from the command line or application. 5) TOS: $0B CONSTAT. Checks 64-byte OS input buffer. 6) Under DOS 1.x, the type-ahead buffer is checked. Under DOS 2.x and later, the type-ahead buffer is checked unless STDIN has been redirected. Function 0Ch Clear Keyboard Buffer & Invoke a Keyboard Function Dumps buffer, executes function in AL (FCB) entry AH 0Ch AL function number (must be 01h, 06h, 07h, 08h, or 0Ah) note: the DOS 5.0 TR specifies 0Ah as reserved and "must not be used" return AL 00h buffer was flushed, no other processing performed other any other value has no meaning note 1) Forces system to wait until a character is typed. 2) Flushes all typeahead input, then executes function specified by AL (by moving it to AH and repeating the int 21 call). 3) If AL contains a value not in the list above, (such as 00h) the input buffer is flushed and no other action is taken. Note that this is the STDIN buffer, not the actual keyboard buffer. The keyboard buffer will not be flushed if input is redirected. 4) Under DOS 1.x, the type-ahead buffer is emptied before the function in AL is performed. Function 0Dh Disk Reset Flushes all currently open file buffers to disk entry AH 0Dh return none note 1) Does not close files. Does not update directory entries; files changed in size but not closed are not properly recorded in the directory. 2) Sets DTA address to DS:0080h 3) Should be used before a disk change, Ctrl-C handlers, and to flush the buffers to disk. 4) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 5) IBM TopView saves DTA information during task switches. Function 0Eh Select Disk Sets the drive specified in DL (if valid) as the default drive entry AL 0Eh DL new default drive number (0=A:,1=B:,2=C:,etc.) return AL number of physical drives found unless LASTDRIVE= is included in CONFIG.SYS and specifies a higher number than that of the last physical drive. note 1) For DOS 1.x and 2.x, the minimum value for AL is 2. 2) For DOS 3.x and 4.x, the minimum value for AL is 5. 3) The drive number returned is not necessarily a valid drive. 4) For DOS 1.x: 16 logical drives are available, A-P. (0-0Fh) For DOS 2.x: 63 logical drives are available. (Letters are only used for the first 26 drives. If more than 26 logical drives are used, further drive letters will be other ASCII characters, such as {, ], etc. (0-3Fh) For DOS 3.x, +: 26 logical drives are available, A-Z. (0-19h) 5) TOS: $0E SETDRV. A 16-bit parameter with drivespec is passed to TOS. On exit, D0 contains the number of the drive active before the call. (not the total number of drives) 6) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 7) For DOS 3.3, LASTDRIVE= is not needed when accessing additional hard disk partitions past E:. I haven't done any further checking, but it seems that LASTDRIVE= may be fairly useless to most programs. 6) IBM TopView saves DTA information during task switches. Function 0Fh Open Disk File (FCB) Searches current directory for specified filename and places relevantinformation into the File Control Block. entry AH 0Fh DS:DX pointer to an unopened FCB return AL 00h if file found 0FFh if file not not found note 1) If the drive code was 0 (default drive) it is changed to the actual drive used (1=A:,2=B:,3=C:, etc). This allows changing the default drive without interfering with subsequent operations on this file. 2) The current block field (FCB bytes C-D, offset 0Ch) is set to zero. 3) The size of the record to be worked with (FCB bytes E-F, offset 0Eh) is set to the system default of 80h. The size of the file (offset 10h) and the date (offset 14h) are set from information obtained in the root directory. You can change the default value for the record size (FCB bytes E-F) or set the random record size and/or current record field. Perform these actions after the open but before any disk operations. 4) With DOS 3.x the file is opened in compatibility mode. (network) 5) Microsoft recommends handle function call 3Dh be used instead. 6) This call is also used by the APPEND command in DOS 3.2 and higher. 7) Before performing a sequential disk operation on the file, you must set the Current Record field (offset 20h). Before performing a random disk operation on the file, you must set the Relative Record field (offset 21h). If the default record size of 128 bytes is incorrect, set it to the correct value. Function 10h Close File (FCB) Closes a File After a File Write entry AH 10h DS:DX pointer to an opened FCB return AL 00h if the file is found and closed 0FFh if the file is not found in the current directory note 1) This function call must be done on open files that are no longer needed, and after file writes to insure all directory information is updated. 2) If the file is not found in its correct position in the current directory, it is assumed that the diskette was changed and AL returns 0FFh. This error return is reportedly not completely reliable with DOS version 2.x. 3) If found, the directory is updated to reflect the status in the FCB, the buffers to that file are flushed, and AL returns 00h. 4) There is a subtle but dangerous quirk to this function. If a Close request is issued using a File Control Block that has not been previously activated by a successful Open command, the file's length will be truncated to zero and the clusters previously assigned to the file are left floating. (lost clusters) 5) This function works for files in the current directory only. 6) For DOS 3.1 and later, files opened with this call are set to compatibility mode and the access code is set to read/write. 7) For DOS 3.0 and later, int 21h fn 59h (Get Extended Error Information) may be used to determine errors. Function 11h Search For First Matching Entry (FCB) Searches current disk & directory for first matching filename entry AH 11h DS:DX pointer to address of FCB return AL 00h successful match 0FFh no matching filename found note 1) The FCB may contain the wildcard character ? under DOS 2.x, and ? or * under 3.x and later. 2) The original FCB at DS:DX contains information to continue the search with function 12h, and should not be modified. 3) If a matching filename is found, AL returns 00h and the locations at the Disk Transfer Address are set as follows: a) If the FCB provided for searching was an extended FCB, then the first byte at the disk transfer address is set to 0FFh followed by 5 bytes of zeroes, then the attribute byte from the search FCB, then the drive number used (1=A, 2=B, etc) then the 32 bytes of the directory entry. Thus, the disk transfer address contains a valid unopened FCB with the same search attributes as the search FCB. b) If the FCB provided for searching was a standard FCB, then the first byte is set to the drive number used (1=A, 2=b, etc), and the next 32 bytes contain the matching directory entry. Thus, the disk transfer address contains a valid unopened normal FCB. 4) If an extended FCB is used, the following search pattern is used: a) If the FCB attribute byte is zero, only normal file entries are found. Entries for volume label, subdirectories, hidden or system files, are not returned. b) If the attribute byte is set for hidden or system files, or subdirectory entries, it is to be considered as an inclusive search. All normal file entries plus all entries matching the specified attributes are returned. To look at all directory entries except the volume label, the attribute byte may be set to hidden + system + directory (all 3 bits on). c) If the attribute field is set for the volume label, it is considered an exclusive search, and ONLY the volume label entry is returned. 5) This call is also used by the APPEND command in DOS 3.2+ Function 12h Search For Next Entry Using FCB (FCB) Search for next matching filename entry AH 12h DS:DX pointer to the unopened FCB specified from the previous Search First (11h) or Search Next (12h) return AL 00h if matching filename found 0FFh if matching filename was not found note 1) After a matching filename has been found using function call 11h, function 12h may be called to find the next match to an ambiguous request. For DOS 2.x, ?'s are allowed in the filename. For DOS 3.x and 4.x, global (*) filename characters are allowed. 2) The DTA contains info from the previous Search First or Search Next. 3) Do not perform any disk operations with this FCB between a previous function 11h or 12h call and this one. "Undocumented" fields in the FCB are used to keep information necessary for continuing the search, and some disk operations may overwrite these areas. 4) If the file is found, an FCB is created at the DTA address and set up to open or delete it. Function 13h Delete File Via FCB (FCB) Deletes file specified in FCB from current directory entry AH 13h DS:DX pointer to address of FCB return AL 00h file deleted 0FFh if file not found or was read-only note 1) All matching current directory entries are deleted. The global filename character "?" is allowed in the filename. 2) Will not delete files with read-only attribute set. 3) Close open files before deleting them. 4) For DOS 3.1+, requires network Create rights to the sub- directory. 5) This call supports wildcards and is very fast. The "new" handle call 41h is supposed to replace this one since it knows about subdirectories. Unfortunately, fn 41h doesn't know about wildcards. Function 14h Sequential Disk File Read (FCB) Reads record sequentially from disk via FCB entry AH 14h DS:DX pointer to an opened FCB return AL 00h successful read 01h end of file (no data read) 02h Data Transfer Area too small for record size specified or segment overflow 03h partial record read, EOF found note 1) The record size is set to the value at offset 0Eh in the FCB. 2) The record pointed to by the Current Block (offset 0Ch) and the Current Record (offset 20h) fields is loaded at the DTA, then the Current Block and Current Record fields are incremented. 3) The record is read into memory at the current DTA address as specified by the most recent call to function 1Ah. If the size of the record and location of the DTA are such that a segment overflow or wraparound would occur, the error return is set to AL=02h. 4) If a partial record is read at the end of the file, it is passed to the requested size with zeroes and the error return is set to AL=03h. 5) For DOS 3.1+ networks, requires Read rights to the subdirectory. Function 15h Sequential Disk Write (FCB) Writes record specified by FCB sequentially to disk entry AH 15h DS:DX pointer to address of FCB return AL 00h successful write 01h diskette full, write canceled 02h disk transfer area (DTA) too small or segment wrap note 1) The data to write is obtained from the disk transfer area. 2) The record size is set to the value at offset 0Eh in the FCB. 3) This service cannot write to files set as read-only. 4) The record pointed to by the Current Block (offset 0Ch) and the Current Record (offset 20h) fields is loaded at the DTA, then the Current Block and Current Record fields are incremented. 5) If the record size is less than a sector, the data in the DTA is written to a buffer; the buffer is written to disk when it contains a full sector of data, the file is closed, or a Reset Disk (function 0Dh) is issued. 6) The record is written to disk at the current DTA address as specified by the most recent call to function 1Ah. If the size of the record and location of the DTA are such that a segment overflow or wraparound would occur, the error return is set to AL=02h. 5) For DOS 3.1+ networks, requires Write rights to the subdirectory. Function 16h Create A Disk File (FCB) Search and open or create directory entry for file entry AH 16h DS:DX pointer to an FCB return AL 00h successful creation 0FFh no room in directory note 1) If a matching directory entry is found, the file is truncated to zero bytes. 2) If there is no matching filename, a filename is created. 3) This function calls function 0Fh (Open File) after creating or truncating a file. 4) A hidden file can be created by using an extended FCB with the attribute byte (offset FCB-1) set to 2. 5) The corresponding handle call is 3Ch. 6) For DOS 3.1+ networks, requires Create rights to the sub- directory. 7) For DOS 3.0 and later, int 21h function 59h (Get Extended Error Information) may be used to determine errors. 8) Pathnames and wildcards are not supported. Function 17h Rename File Specified by File Control Block (FCB) Renames file in current directory entry AH 17h DS:DX pointer to an FCB (see note 4) return AL 00h successfully renamed 0FFh file not found or filename already exists note 1) This service cannot rename read-only files. 2) The "?" wildcard may be used. 3) If the "?" wildcard is used in the second filename, the corresponding letters in the filename of the directory entry are not changed. 4) A special modified FCB is used. It must have a drive number, filename, and extension in the usual position, and a second filename starting 6 bytes after the first, at offset 11h. This is normally a "reserved" area. Modified FCB format: bytes contents 00h drive number 01h-08h old filename (blank padded if required) 09h-0Bh old file extension (blank padded if reqired) 0Ch-10h zeroed out 11h-18h new filename (blank padded if required) 19h-1Bh new file extension (blank padded if required) 1Ch-24h zeroed out 5) The two filenames cannot have the same name. 6) FCB contains new name starting at byte 17h. 7) Under DOS 2.0+, subdirectories may be renamed with this call. Function 18h Unknown - reportedly not used entry AH 18h return AL 00h Function 19h Get Current Disk Drive Return designation of current default disk drive entry AH 19h return AL current default drive (0=A, 1=B,etc.) note 1) Some other DOS functions use 0 for default, 1=A, 2=B, etc. 2) This call is explicitly supported in the OS/2 1.x Compatibility Box. 3) TOS: $19 CURRENT DISK. D0 returns number of drive (0=A:) Function 1Ah Set Disk Transfer Area Address (DTA) Sets DTA address to the address specified in DS:DX. Required for functions 4Eh and 4Fh. entry AH 1Ah DS:DX pointer to DTA buffer return none note 1) The default DTA is 128 bytes at offset 80h in the PSP. You may set up your own DTA with any size and location. The DTA should be large enough to handle the largest record you intend to write. 2) Registers are unchanged. 3) No error codes are returned. 4) Disk transfers cannot wrap around from the end of the segment to the beginning or overflow into another segment. 5) DOS uses the DTA for file I/O. (see Chapter 6) 6) This call is explicitly supported in the OS/2 1.x Compatibility Box. 7) TOS: $1A SET DISK TRANSFER ADDRESS. Sets up a 44-byte buffer for disk operations. 8) PC-MOS/386: not supported for native 386 mode MOS applications. Function 1Bh Get Current Drive File Allocation Table Information Returns information from the FAT on the current drive entry AH 1Bh return AL number of sectors per allocation unit (cluster) CX number of bytes per sector DS:BX address of the current drive's media descriptor byte DX number of allocation units (clusters) for default drive note 1) Save DS before calling this function. 2) This call returned a pointer to the FAT in DOS 1.x. Beginning with DOS 2.00, it returns a pointer only to the table's ID byte. 3) IBM recommends programmers avoid this call and use int 25h instead. 4) Offset DS:[BX-1] is the dirty byte for the table: 00=clean, 01=dirty. 5) DOS 2.x+ and above do not keep the FAT in RAM. Do not use this call to access the FAT. Function 36 is preferred. 6) If unsuccessful, AL returns with 0FFh. Function 1Ch Get File Allocation Table Information for Drive Returns information on specified drive entry AH 1Ch DL drive number (1=A, 2=B, 3=C, etc) return AL number of sectors per allocation unit (cluster) 0FFh invalid drive specification DS:BX address of media descriptor byte for drive in DL CX sector size in bytes DX number of allocation units (clusters) note 1) Set DL = 0 for default. 2) Save DS before calling this function. 3) Format of media-descriptor byte: bits: 0 0 (clear) not double sided 1 (set) double sided 1 0 (clear) not 8 sector 1 (set) 8 sector 2 0 (clear) nonremovable device 1 (set) removable device 3-7 always set (1) 4) This call returned a pointer to the FAT in DOS 1.x. Beginning with DOS 2.00, it returns a pointer only to the table's ID byte. 5) IBM recommends programmers avoid this call and use int 25h instead. 6) This function reads the BPB only and is very fast. 7) If unsuccessful, AL returns with 0FFh. 8) PC-MOS/386: native mode should use DS:EBX instead of DS:BX. Function 1Dh Not Documented by Microsoft * Unknown - reportedly not used entry AH 1Dh return AL 00h Function 1Eh Not Documented by Microsoft * Unknown - reportedly not used entry AH 1Eh return AL 00h note Apparently does nothing. Function 1Fh Get Default Drive Parameter Block Same as function call 32h (below), except that the table is accessed from the default drive entry AH 1Fh other registers unknown return AL 00h no error 0FFh error DS:BX pointer to DOS Disk Parameter Block for default drive. note For DOS 2, 3, 4.x, this just invokes function 32h (Read DOS Disk Block) with DL=0. Function 20h Unknown * Internal - does nothing? entry AH 20h return AL 00h Function 21h Random Read from File Specified by File Control Block (FCB) Reads one record as specified in the FCB into the current DTA. entry AH 21h DS:DX address of the opened FCB return AL 00h successful read operation 01h end of file (EOF), no data read 02h DTA too small for the record size specified 03h end of file (EOF), partial data read note 1) The current block and current record fields are set to agree with the random record field. Then the record addressed by these fields is read into memory at the current Disk Transfer Address. 2) The current file pointers are NOT incremented this function. 3) If the DTA is larger than the file, the file is padded to the requested length with zeroes. Function 22h Random Write to File Specified by FCB (FCB) Writes one record as specified in the FCB to the current DTA entry AH 22h DS:DX address of the opened FCB return AL 00h successful write operation 01h disk full; no data written (write was canceled) 02h DTA too small for the record size specified (write was canceled) note 1) This service cannot write to read-only files. 2) The record pointed to by the Current Block (offset 0Ch) and the Current Record (offset 20h) fields is loaded at the DTA, then the Current Block and Current Record fields are incremented. 3) If the record size is less than a sector, the data in the DTA is written to a buffer; the buffer is written to disk when it contains a full sector of data, the file is closed, or a Reset Disk (function 0Dh) is issued. 4) The current file pointers are NOT incremented this function. 5) The record is written to disk at the current DTA address as specified by the most recent call to function 1Ah. If the size of the record and location of the DTA are such that a segment overflow or wraparound would occur, the error return is set to AL=02h. 6) Under networks running DOS 3.1 or later, the user must have Write access rights to the subdirectory. Function 23h Get File Size (FCB) Searches current subdir for matching file, returns size in FCB entry AH 23h DS:DX address of an unopened FCB return AL 00h file found 0FFh file not found note 1) Record size field (offset 0Eh) must be set before invoking this function. 2) The disk directory is searched for the matching entry. If a matching entry is found, the random record field is set to the number of records in the file. If the value of the Record Size field is not an even divisor of the file size, the value set in the relative record field is rounded up. This gives a returned value larger than the actual file size. 3) This call is used by the APPEND command in DOS 3.2+. 4) Record numbers start with zero. Function 24h Set Relative Record Field (FCB) Set random record field specified by an FCB entry AH 24h DS:DX address of an opened FCB return Random Record Field of FCB is set to be same as Current Block and Current Record. note 1) You must invoke this function before performing random file access. 2) The relative record field of FCB (offset 21h) is set to be same as the Current Block (offset 0Ch) and Current Record (offset 20h). 3) No error codes are returned. 4) The FCB must already be opened. Function 25h Set Interrupt Vector entry AH 25h AL interrupt number to reassign the handler to DS:DX address of new interrupt vector return none note 1) Registers are unchanged. 2) No error codes are returned. 3) The interrupt vector table for the interrupt number specified in AL is set to the address contained in DS:DX. Use function 35h (Get Vector) to get the contents of the interrupt vector and save it for later use. 4) When you use function 25 to set an interrupt vector, DOS 3.2 doesn't point the actual interrupt vector to what you requested. Instead, it sets the interrupt vector to point to a routine inside DOS, which does this: 1. Save old stack pointer 2. Switch to new stack pointer allocated from DOS's stack pool 3. Call your routine 4. Restore old stack pointer The purpose for this was to avoid possible stack overflows when there are a large number of active interrupts. IBM was concerned (this was an IBM change, not Microsoft) that on a Token Ring network there would be a lot of interrupts going on, and applications that hadn't allocated very much stack space would get clobbered. 5) This call is explicitly supported in the OS/2 1.x Compatibility Box. 6) This call is used to access the Phar Lap DOS extender's protected mode functions. The Phar Lap function number is placed in AL. Function 26h Create New Program Segment Prefix (PSP) This service copies the current program-segment prefix to a new memory location for the creation of a new program or overlay. Once the new PSP is in place, a DOS program can read a DOS .COM or overlay file into the memory location immediately following the new PSP and pass control to it. entry AH 26h DX segment number for the new PSP return Current PSP is copied to specified segment note 1) Microsoft recommends you use the newer DOS service 4Bh (EXEC) instead. 2) The entire 100h area at location 0 in the current PSP is copied into location 0 of the new PSP. The memory size information at location 6 in the new segment is updated and the current termination, ctrl-break, and critical error addresses from the interrupt vector table entries for ints 22h, 23h, and 24 are saved in the new program segment starting at 0Ah. They are restored from this area when the program terminates. 3) The PSP structure is found in Chapter 6. Function 27h Random Block Read From File Specified by FCB Similar to 21h (Random Read) except allows multiple files to be read. entry AH 27h CX number of records to be read DS:DX address of an opened FCB return AL 00h successful read 01h end of file, no data read 02h DTA too small for record size specified (read canceled) 03h end of file CX actual number of records read (includes partial if AL=03h) note 1) The record size is specified in the FCB. The service updates the Current Block (offset 0Ch) and Current Record (offset 20h) fields to the next record not read. 2) If CX contained 0 on entry, this is a NOP. 3) If the DTA is larger than the file, the file is padded to the requested length with zeroes. 4) This function assumes that the FCB record size field (0Eh) is correctly set. If not set by the user, the default is 128 bytes. 5) The record is written to disk at the current DTA address as specified by the most recent call to function 1Ah. If the size of the record and location of the DTA are such that a segment overflow or wraparound would occur, the error return is set to AL=02h. 6) Under networks running DOS 3.1 or later, the user must have Read access rights to the subdirectory. Function 28h Random Block Write to File Specified in FCB Similar to 27h (Random Write) entry AH 28h CX number of records to write DS:DX address of an opened FCB return AL 00h successful write 01h disk full, no data written 02h DTA too small for record size specified (write canceled) CX number of records written note 1) The record size is specified in the FCB. 2) This service allocates disk clusters as required. 3) This function assumes that the FCB Record Size field (offset 0Eh) is correctly set. If not set by the user, the default is 128 bytes. 4) The record size is specified in the FCB. The service updates the Current Block (offset 0Ch) and Current Record (offset 20h) fields to the next record not read. 5) The record is written to disk at the current DTA address as specified by the most recent call to function 1Ah. If the size of the record and location of the DTA are such that a segment overflow or wraparound would occur, the error return is set to AL=02h. 6) If called with CX=0, no records are written, but the FCB's File Size entry (offset 1Ch) is set to the size specified by the FCB's Relative Record field (offset 21h). 7) Under networks running DOS 3.1 or later, the user must have Write access rights to the subdirectory. Function 29h Parse the Command Line for Filename Parses a text string into the fields of a File Control Block entry AH 29h AL bit mask to control parsing bit 0 0 parsing stops if file seperator found 1 causes service to scan past leading chars such as blanks. Otherwise assumes the filename begins in the first byte 1 0 drive number in FCB set to default (0) if the string contains no drive number 1 drive number in FCB not changed 2 0 filename in FCB set to 8 blanks if no filename in string 1 filename in FCB not changed if string does not contain a filename 3 0 extension in FCB set to 3 blanks if no extension in string 1 extension left unchanged 4-7 must be zero DS:SI pointer to string to parse ES:DI pointer to memory buffer to fill with unopened FCB return AL 00h no wildcards in name or extension 01h wildcards appeared in name or extension 0FFh invalid drive specifier DS:SI pointer to the first byte after the parsed string ES:DI pointer to a buffer filled with the unopened FCB note 1) If the * wildcard characters are found in the command line, this service will replace all subsequent chars in the FCB with question marks. 2) This service uses the characters as filename separators DOS 1 : ; . , + / [ ] = " TAB SPACE DOS 2,3,4 : ; . , + = TAB SPACE 3) This service uses the characters : ; . , + < > | / \ [ ] = " TAB SPACE or any control characters as valid filename separators. 4) A filename cannot contain a filename terminator. If one is encountered, all processing stops. The handle functions will allow use of some of these characters. 5) If no valid filename was found on the command line, ES:DI +1 points to a blank (ASCII 32). 6) This call will not handle pathnames. 7) Parsing is in the form D:FILENAME.EXT. If one is found, a corresponding unopened FCB is built at ES:DI. Function 2Ah Get Date Returns day of the week, year, month, and date entry AH 2Ah return CX year (1980-2099) DH month (1-12) DL day (1-31) AL weekday 00h Sunday 01h Monday 02h Tuesday 03h Wednesday 04h Thursday 05h Friday 06h Saturday note 1) Date is adjusted automatically if clock rolls over to the next day, and takes leap years and number of days in each month into account. 2) Although DOS cannot set an invalid date, it can read one, such as 91/32/80, etc. 3) DESQview's DOS subfunctions also accept CX = 4445h and DX = 5351h, i.e. 'DESQ' as valid. 4) This call is explicitly supported in the OS/2 1.x Compatibility Box. 5) DOS will accept CH=0 (midnight) as a valid time. Through DOS 3.31, if a file's time is set to within 2 seconds of midnight the time will not be displayed by the DIR command. For DOS 4.0+ and DR-DOS the creation time will always be displayed. 6) TOS: $2A GET DATE. Function 2Bh Set Date set current system date entry AH 2Bh CX year (1980-2099) DH month (1-12) DL day (1-31) return AL 00h no error (valid date) 0FFh invalid date specified note 1) On entry, CX:DX must have a valid date in the same format as returned by function call 2Ah. 2) DOS 3.3+ also sets CMOS clock. 3) Under the DESQview system shell, this is the DV_GET_VERSION check: entry AH 2Bh AL 01h DESQ call CX 4445h 'DE' (invalid date used DX 5351h 'SQ' for DesQview ID) return AH major version AL minor version AX 0FFh DESQ not installed (DOS error code) 4) For DESQview 2.00+, installation check entry AH 2Bh AL subfunction (DV v2.00+) 01h Get Version return BX version (BH = major, BL = minor) note Early copies of v2.00 return 0002h. 02h Get Shadow Buffer Info, and Start Shadowing return BH rows in shadow buffer BL columns in shadow buffer DX segment of shadow buffer 04h Get Shadow Buffer Info return BH rows in shadow buffer BL columns in shadow buffer DX segment of shadow buffer 05h Stop Shadowing CX 4445h ('DE') DX 5351h ('SQ') return AL 0FFh if DESQview not installed note In DESQview v1.x, there were no subfunctions; this call only identified whether or not DESQview was loaded. 5) PC-Tools PC-Cache 5.1 (Multisoft cache) installation check. entry CX 4358h ('CX') return AL 00h installed CX 6378h 0FFh not installed 6) This call is explicitly supported in the OS/2 1.x Compatibility Box. 7) TOS: GET DATE. Function 2Ch Get Time Get current system time from CLOCK$ driver entry AH 2Ch return CH hours (0-23) CL minutes (0-59) DH seconds (0-59) DL hundredths of a second (0-99) note 1) Time is updated every 5/100 second. 2) The date and time are in binary format. 3) This call is explicitly supported in the OS/2 1.x Compatibility Box. 4) TOS: GET TIME. Function 2Dh Set Time Sets current system time entry AH 2Dh CH hours (0-23) CL minutes (0-59) DH seconds (0-59) DL hundredths of seconds (0-99) return AL 00h if no error 0FFh if bad value sent to routine note 1) DOS 3.3+ also sets CMOS clock. 2) CX and DX must contain a valid time in binary. 3) This call is explicitly supported in the OS/2 1.x Compatibility Box. 4) TOS: SET TIME. Function 2Eh Set/Reset Verify Switch Set verify flag entry AH 2Eh AL 00 to turn verify off (default) 01 to turn verify on DL 00h (DOS 1.x and 2.x only, according to Microsoft's MS-DOS Encyclopedia. My IBM 2.0 and Intel 2.0 manuals don't show DL being used) return none note 1) This is the call invoked by the DOS VERIFY command. 2) The setting of the Verify switch can be obtained by calling function 54h. 3) This call is not supported on network drives. 4) DOS checks this flag each time it accesses a disk or block device. 5) This call is explicitly supported in the OS/2 1.x Compatibility Box. Function 2Fh Get Disk Transfer Address (DTA) Returns current DTA used by all DOS read/write operations entry AH 2Fh return ES:BX address of DTA note 1) The DTA is set by function call 1Ah 2) Default DTA address is a 128 byte buffer at offset 80h in that program's Program Segment Prefix. 3) See Chapter 6 for a description of the DTA. 4) This call is explicitly supported in the OS/2 1.x Compatibility Box. 5) TOS: GET DTA. Returns segment address of current DTA in D0. Function 30h Get DOS Version Number Return DOS version and/or user number entry AH 30h (5.0+) AL 00h Get OEM ID number 01h Get version flag return AH minor version number (i.e., DOS 2.10 returns AX = 0A02h) (AH undefined for DOS 1.x) AL major version number (0 for DOS 1.x, 02h for 2.x, 05h for 5.x) (DOS 2.0 through 4.01) BH OEM ID number 00h IBM DOS 16h DEC DOS 0FFh MS-DOS (generic) (Also Toshiba DOS 5.0) (DOS 5.0+ called with AL=00h) BH OEM ID number (see above) (DOS 5.0+ called with AL=01h) BH version flag 08h DOS 5.0 or higher running out of ROM (all other bits are reserved and set to zero) BL:CX 24-bit user serial number (optional, OEM dependent. If not used this field returns zeroes) note 1) If AL returns a major version number of zero, the DOS version is below 1.28 for MSDOS and below 2.00 for PCDOS. 2) IBM PC-DOS always returns 0000h in BX and CX, as does DR-DOS. 3) Due to OS/2 returning version numbers over 10 and the fact that some European versions of DOS carried higher version numbers than IBM's DOS, utilities which check for a DOS version should not abort if a higher version than required is found unless some specific problems are known. 4) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 5) TOS: $30 GET VERSION NUMBER. Returns GEMDOS version number in D0. 6) Under PC-MOS/386, if AX=BX=CX=DX, the PC-MOS/386 version number is returned. If all registers to not hold the same value, an MSDOS equivalent version number is returned. The PC-MOS/386 version number is always different from the MSDOS version number. 7) DOS version equivalents: 3.20 PC-MOS/386 v3.0 3.31 Digital Research DR-DOS 3.40, 3.41, 5.0, 6.0 10 OS/2 v1.0 Compatibility Box (major version number) 8) DOS 5.0 adds the AL parameter to the command, but the ID number returned in BL has been available since MSDOS 2.0, as documented by Intel's DOS 2.0 Technical Reference. 9) DOS 5.0's SETVER command can modify the value returned in AX. You must use int 21h/3306h to obtain the true version number. 10) OS/2 1.0's Compatibility Box returns version 10. OS/2 1.1 returns version 10.1, etc. OS/2 2.0 returns version 20. 11) If running in a Microsoft Windows 3.0 or later DOS box, the string "windir" will be in the DOS environment. Note lowercase! 12) It may sometimes be necessary to identify DOS-compatible operating systems or replacement command interpreters. This doesn't appear to be a simple task. COMMAND.COM replacements: 1) 4DOS can be identified with int 2Fh, fn 44DDh. 2) Command Plus (unknown) 3) FlexShell (unknown) DOS replacements: 1) DR-DOS 3.4x has no easy way to be identified, which is a pity. Though it has some MS4.0-like characteristics, it reports 3.31 with the DOS call, though VER will return whatever the DRDOS revision is. To identify DRDOS I've noted the following: The string "OS=" appears in the default environment (unless the user nulls it out) The OS= string is generated by COMMAND.COM and does not appear when the user is running 4DOS as a command interpreter. The internal DOS version call will report 3.31, but the string returned by VER is at minimum 3.4. For DRDOS 3.x: SHARE and FASTOPEN are always loaded. For DRDOS 5 and 6: SHARE and FASTOPEN are NOT always loaded. The DR-DOS Programmer's Reference doesn't show a call to identify DR-DOS specifically. 2) PC-MOS/386: unknown. Fail an API call? 3) Concurrent DOS: unknown. Fail an API call? 4) DR Multiuser DOS inserts the string: OS=DRMDOS into the environment. Since DRMDOS doesn't allow replacement of the command interpreter via the SHELL= statement, OS= will be there unless nulled by the user. Function 31h Terminate Process and Stay Resident (KEEP) entry AH 31h AL exit code DX program memory requirement in 16 byte paragraphs return AX return code (retrieveable by function 4Dh) note 1) Files opened by the application are not closed when this call is made. 2) Memory can be used more efficiently if the block containing the copy of the DOS environment is deallocated before terminating. This can be done by loading ES with the segment contained in 2Ch of the PSP and issuing function call 49h (Free Allocated Memory). 3) Unlike int 27h, more than 64k may be made resident with this call. 4) TOS: $31 KEEP PROCESS. 5) Programs larger than 64k may be made resident with this call. 6) For PC-MOS/386, tasks made resident with this call are subject to being swapped out of memory by the kernel for room to process other applications. If your code needs to poll the keyboard or a port, you need to use a device driver instead. PC-MOS does not swap device drivers. Function 32h Read DOS Disk Parameter Block Retrieve the pointer to the drive parameter block for a drive entry AH 32h DL drive (0=default, 1=A:, etc.). return AL 0FFh if drive is not valid or other error 00h if drive is valid and: DS:BX pointer to DOS Drive Parameter Table. Format of block: 旼컴컴컴컫컴컴컴쩡컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Bytes � Type � Value 쳐컴컴컴컵컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � 00h � byte � Drive: 0=A:, 1=B:, etc. � 01h � byte � Unit within device driver (0, 1, 2, etc.) � 02h-03h� word � Bytes per sector � 04h � byte � Sectors per cluster - 1 � 05h � byte � Sectors per cluster as powers of 2 � 06h-07h� word � First sector containing FAT � 08h � byte � Number of copies of the FAT � 09h-0Ah� word � Number of root directory entries � 0Bh-0Ch� word � First sector of first cluster � 0Dh-0Eh� word � Number of clusters on drive + 1 쳐컴컴컴컨컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � DOS 2.x only � 쳐컴컴컴컫컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � 0Fh � byte � Number of sectors for one copy of the FAT � 10h-11h� word � Number of first sector of root directory � 12h-15h� dword� Address of device driver header for this � � � drive (beginning of device driver) � 16h � byte � Media Descriptor Byte for this drive � 17h � byte � 0FFh indicates block must be rebuilt � 18h-1Bh� dword� address of next DOS Disk Block (0FFFFh � � � means last in chain) � 1Ch � word � starting cluster of current dir (0 = root) � 1Eh �64byts� ASCIIZ current directory path string 쳐컴컴컴컨컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � DOS 3.x � 쳐컴컴컴컫컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � 0Fh � byte � number of sectors in one FAT copy � 10h � word � first sector of root directory � 12h 쿭word � address of device driver for this drive � 16h � byte � media descriptor byte for medium � 17h � byte � 0FFh = block must be rebuilt, 00h � � � indicates block accessed � 18h 쿭word � address of next device block, offset � � � = 0FFFFh indicates last � 1Ch � word � cluster at which to start search for free � � � space when writing � 1Eh � word � number of free clusters on drive, 0FFFFh � � � unknown? 쳐컴컴컴컨컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � DOS 4.0, 5.0 � (from MS 5.0 TR) 쳐컴컴컴컫컴컴컴탠컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � 0Fh � word � number of sectors in one FAT copy � 11h � word � first sector of containing directory � 13h 쿭word � address of device driver for this drive � 17h � byte � media descriptor byte for drive � 18h � byte � 0FFh = block must be rebuilt, 00h � � � indicates block accessed � 19h 쿭word � address of next device block, offset � � � = 0FFFFh indicates last � 1Dh � word � last allocated cluster � 1Fh � word � number of free clusters on drive 읕컴컴컴컨컴컴컴좔컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� note 1) Use [BX+0Dh] to find no. of clusters (>1000h, 16-bit FAT; if not, 12-bit (exact dividing line is probably a little below 1000h to allow for bad sectors, EOF markers, etc.) 2) Short article by C.Petzold, PC Magazine Vol.5, no.8. 3) Some information from the article "Finding Disk Parameters" in the May 1986 issue of PC Tech Journal. 4) This call is mostly supported in OS/2 1.0's DOS Compatibility Box. The dword at 12h will not return the address of the next device driver when in the Compatibility Box. 5) Used by CHKDSK. Function 33h Control-Break Check Get or set control-break checking at CON entry AH 33h AL 00h see if ^C checking is active 01h to set break checking DL 00h to disable break checking 01h to enable break checking 02h internal, called by PRINT.COM (DOS 3.1) 03h unknown 04h unknown - DOS 4.0's CPSW command in CONFIG.SYS calls this function 05h (DOS 4.0+) get boot drive 06h (DOS 5.0+) return "real" DOS version number instead of number returned by SETVER/int 21h fn 30h. return (if AL=00h) break setting DL 00h if break=off 01h if break=on (if AL=05h) boot drive DL 01h A: 02h B: (etc.) (if AL=06h) real DOS version BH major version (05h=DOS5) BL minor version (00h=.00) DH 0Bh DOS is in ROM 10h DOS is in HMA DL DOS subversion number (0-7, VER/R reports as A-G) (all) AL 0FFh error note 1) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 2) When ^C checking is on, DOS checks for ^C after each DOS call. When off, DOS only checks after each DOS character I/O function from 01h to 0Ch. Function 34h Return INDOS Flag Returns ES:BX pointing to Critical Section Flag, byte indicating whether it is safe to interrupt DOS. entry AH 34h return ES:BX points to 1-byte DOS "critical section flag" note 1) If this byte is 0, it is safe to interrupt DOS. 2) Supported OS/2 1.x Compatibility Box. 3) For PC-MOS/386, this flag indicates whether MOS is using its stack or a task's stack. If the flag is 0 it is safe to interrupt MOS. Function 35h Get Interrupt Vector Get interrupt vector entry AH 35h AL interrupt number (hexadecimal) return ES:BX address of interrupt vector note 1) Use function call 25h to set the interrupt vectors. 2) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. Function 36h Get Disk Free Space get information on specified drive entry AH 36h DL drive number (0=default, 1=A:, 2=B:, etc) return AX number of sectors per cluster 0FFFFh means drive specified in DL is invalid BX number of available clusters CX bytes per sector DX clusters per drive note 1) Multiply AX * CX * BX for free space on disk. 2) Multiply AX * CX * DX for total disk space. 3) Function 36h returns an incorrect value after an ASSIGN command. Prior to ASSIGN, the DX register contains 0943h on return, which is the free space in clusters on the HC diskette. After ASSIGN, even with no parameters, 0901h is returned in the DX register; this is an incorrect value. Similar results occur with DD diskettes on a PC-XT or a PC-AT. This occurs only when the disk is not the default drive. Results are as expected when the drive is the default drive. Therefore, the circumvention is to make the desired drive the default drive prior to issuing this function call. 4) This function supercedes functions 1Bh and 1Ch. 5) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 6) TOS: $36 GET DISK FREE SPACE. Function 37h SWITCHAR / AVAILDEV * Get/set option marking character (is usually "/"), and device type entry AH 37h AL 00h read switch character (returns current character in DL) 01h set character in DL as new switch character (DOS 2.x) 02h read device availability (as set by function AL=3) into DL. A 0 means devices that devices must be accessed in file I/O calls by /dev/device. A non-zero value means that devices are accessible at every level of the directory tree (e.g., PRN is the printer and not a file PRN). AL=2 to return flag in DL, AL=3 to set from DL (0 = set, 1 = not set). (DOS 2.x) 03h get device availability, where: DL 00h /dev/ must precede device names 01h /dev/ need not precede device names return DL switch character (if AL=0 or 1) device availability flag (if AL=2 or 3) AL 0FFh the value in AL was not in the range 0-3 note 1) Functions 2 & 3 appear not to be implemented for DOS 3.x. 2) It is documented on page 4.324 of the MS-DOS (version 2) Programmer's Utility Pack (Microsoft - published by Zenith). 3) Works on all versions of IBM PC-DOS from 2.0 through 3.3.1. 4) The SWITCHAR is the character used for "switches" in DOS command arguments (defaults to '/', as in "DIR/P"). '-' is popular to make a system look more like UNIX; if the SWITCHAR is anything other than '/', then '/' may be used instead of '\' for pathnames. 5) Ignored by XCOPY, PKARC, LIST, used by PKZIP, LHARC. 6) SWITCHAR may not be set to any character used in a filename. Legal filename characters vary in DOS 1.x through 6.x. 7) In DOS 3.x you can still read the "AVAILDEV" byte with subfunction 02h but it always returns 0FFh even if you try to change it to 0 with subfunction 03h. 8) AVAILDEV=0 means that devices must be referenced in an imaginary subdirectory "\dev" (similar to UNIX's /dev/*); a filename "PRN.DAT" can be created on disk and manipulated like any other. If AVAILDEV != 0 then device names are recognized anywhere (this is the default): "PRN.DAT" is synonymous with "PRN:". 9) These functions reportedly are not supported in the same fashion in various implementations of DOS. 10) Used in DOS 3.3 by CHKDSK, BASIC, and DEBUG. 11) SWITCHAR is not supported in the OS/2 1.x Compatibility Box. 12) Not supported by the aftermarket 4DOS command interpreter in versions prior to 3.0. 13) The MSDOS Encyclopedia reports: "XENIX used a forward slash as a separator, but versions 1.x of MS-DOS, borrowing from the tradition of DEC operating systems, already used the forward slash for switches on the command line, so Microsoft, at IBM's request, decided to use the backslash as the separator instead." 14) SWITCHAR is not supported in MS-DOS 5.0. Function 38h Return Country-Dependent Information (PCDOS 2.0, 2.1, MSDOS 2.00 only) entry AH 38h AL function code (must be 0 in DOS 2.x) DS:DX pointer to 32 byte memory buffer for returned information return CF set on error AX error code (02h) BX country code DS:DX pointer to buffer filled with country information: bytes 00h,01h date/time format 0000h USA standard H:M:S M-D-Y 0001h European standard H:M:S D/M/Y 0002h Japanese standard H:M:S D:M:Y 02h ASCIIZ string currency symbol 03h byte of zeroes 04h ASCIIZ string thousands separator 05h byte of zeroes 06h ASCIIZ string decimal separator 07h byte of zeroes 24 bytes 08h-1Fh reserved Function 38h Get Country-Dependent Information (PCDOS 3.x+, MSDOS 2.01+) entry AH 38h AL function code 00h to get current country information 01h-0FEh country code to get information for, for countries with codes less than 255 0FFh to get country information for countries with a code greater than 255 BX 16 bit country code if AL=0FFh DS:DX pointer to the memory buffer where the data will be returned DX 0FFFFh if setting country code rather than getting info return CF 0 (clear) function completed 1 (set) error AX error code 02h invalid country code (no table for it) (if DX <> 0FFFFh) BX country code (usually international telephone code) DS:DX pointer to country data buffer bytes 0,1 date/time format 0 USA standard H:M:S M/D/Y 1 European standard H:M:S D/M/Y 2 Japanese standard H:M:S D:M:Y bytes 02h-06h ASCIIZ currency symbol byte 07h ASCIIZ thousands separator byte 08h byte of zeroes byte 09h ASCIIZ decimal separator byte 0Ah byte of zeroes byte 0Bh ASCIIZ date separator byte 0Ch byte of zeroes byte 0Dh ASCIIZ time separator byte 0Eh byte of zeroes byte 0Fh currency format byte bit 0 0 if currency symbol precedes the value 1 if currency symbol is after the value 1 0 no spaces between value and currency symbol 1 one space between value and currency symbol 2 1 if currency symbol replaces decimal point 3-7 not defined by Microsoft byte 10h number of significant decimal digits in currency (number of places to right of decimal point) byte 11h time format byte bit 0 0 12 hour clock 1 24 hour clock 1-7 unknown, probably not used bytes 12h-15h address of case map routine (FAR CALL, AL=char to map) entry AL ASCII code of character to be converted to uppercase return AL ASCII code of the uppercase input character byte 16h data-list separator character byte 17h zeroes bytes 18h-21h 5 words reserved note 1) When an alternate keyboard handler is invoked, the keyboard routine is loaded into user memory starting at the lowest portion of available user memory. The BIOS interrupt vector that services the keyboard is redirected to the memory area where the new routine resides. Each new routine takes up about 1.6K of memory and has lookup tables that return values unique to each language. (KEYBxx in the DOS book) Once the keyboard interrupt vector is changed by the DOS keyboard routine, the new routine services all calls unless the system is returned to the US format by the ctrl-alt-F1 keystroke combination. This does not change the interrupt vector back to the BIOS location; it merely passes the table lookup to the ROM locations. 2) Ctrl-Alt-F1 will only change systems with US ROMS to the US layout. Some systems are delivered with non-US keyboard handler routines in ROM. (Amstrad machines) 3) Case mapping call: the segment/offset of a FAR procedure that performs country-specific lower-to-upper case mapping on ASCII characters 80h to 0FFh. It is called with the character to be mapped in AL. If there is an uppercase code for the letter, it is returned in AL, if there is no code or the function was called with a value of less than 80h AL is returned unchanged. 4) This call is fully implemented in MS-DOS version 2.01 and higher. It is in version 2.00 but not fully implemented (according to Microsoft). 5) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 6) For PC-MOS/386 native mode apps, use DS:EDX instead of DS:DX. Function 38h Set Country Dependent Information entry AH 38h AL code country code to set information for, for countries with codes less than 255 0FFh to set country information for countries with a code greater than 255 BX 16 bit country code if AL=0FFh DX 0FFFFh return CF clear successful set if error AX error code (02h) note 1) Some country codes are: 061 Australia ("International English" in DOS 5.0) 032 Belgium 055 Brazil (DOS 5.0) 002 French-Canadian 042 Czechoslovakia (DOS 5.0) 045 Denmark 358 Finland 033 France 049 Germany 036 Hungary (DOS 5.0) 972 Israel 039 Italy 081 Japan 758 Middle East 031 Netherlands 047 Norway 048 Poland (DOS 5.0) 351 Portugal 003 Latin America 034 Spain 046 Sweden 041 Switzerland 088 Taiwan (MS 4.0+, but not DRDOS 5 or 6) 044 U.K. 001 USA 038 Yugoslavia (DOS 5.0) 2) The country code is the same as the 3-digit international telephone code for that country. 3) The documentation for COUNTRY= will tell you which codes are valid for your particular DOS version. Different OEM implementations of the same DOS version may not support the same countries. 4) TSL offers support for developing special country code drivers for PC-MOS/386. Version 4.10 comes with: 061 Australia 032 Belgium 002 French-Canadian 045 Denmark 358 Finland 033 France 049 Germany 972 Israel 039 Italy 758 Middle East 031 Netherlands 047 Norway 351 Portugal 034 Spain 046 Sweden 041 Switzerland 044 U.K. 001 USA 5) For PC-MOS/386 native mode apps, use DS:EDX instead of DS:DX. Function 39h Create Subdirectory (MKDIR) Makes a subdirectory along the indicated path entry AH 39h DS:DX address of ASCIIZ directory pathname string return flag CF 0 successful 1 error AX error code if any (03h, 05h) (DOS 5.0) (02h, 03h, 05h) note 1) The ASCIIZ string contains the drive and subdirectory. 2) Drive may be any valid drive (not necessarily current drive). 3) The pathname cannot exceed 64 characters. (same with PC-MOS/386) 4) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 5) The characters [, ] , =, and " may not be used in subdirectory names. 6) TOS: $39 MKDIR. 7) For DOS 3.1+ networks, the user must have Create access to the subdirectory. 8) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 3Ah Remove Subdirectory (RMDIR) entry AH 3Ah DS:DX address of ASCIIZ pathname string return CF clear successful set AX error code if any (03h, 05h, 10h) note 1) The ASCIIZ string contains the drive and subdirectory. 2) Drive may be any valid drive (not necessarily current drive). 3) The pathname cannot exceed 64 characters. 4) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 5) TOS: $3A RMDIR. 7) For DOS 3.1+ networks, the user must have Delete access to the subdirectory. 8) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 3Bh Change Current Directory (CHDIR) entry AH 3Bh DS:DX address of ASCIIZ string return flag CF 0 successful 1 error AX error code if any (03h) note 1) The pathname cannot exceed 64 characters including separators. 2) The ASCIIZ string may contain drive and subdirectory. 3) Drive may be any valid drive (not necessarily current drive). This call will not change the current logged drive. 4) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 5) TOS: $3B CHDIR. 6) The pathspec may not contain wildcards. 7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 3Ch Create A File (CREAT) Create a file with handle entry AH 3Ch CX byte, attributes for file 00h normal read/write 01h read only 02h hidden 04h system 08h volume label 20h archive bit DS:DX address of ASCIIZ filename string return CF 0 successful creation 1 error AX 16 bit file handle or error code (03h, 04h, 05h) note 1) The ASCIIZ string may contain drive and subdirectory. 2) Drive may be any valid drive (not necessarily current drive). 3) If the volume label or subdirectory bits are set in CX, they are ignored. 4) The file is opened in read/write mode 5) If the file does not exist, it is created. If one of the same name exists, it is truncated to a length of 0. 6) Good practice is to attempt to open a file with fn 3Dh and jump to an error routine if successful, create file if 3Dh fails. That way an existing file will not be truncated and overwritten. 7) If the application will run only on DOS 3.x or higher, fn 5Bh should be used as it automatically creates the file if it does not exist, preventing problems with networks or multitaskers. 8) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 9) TOS: $3C CREAT. 10) For DOS 3.1+ networks, the user must have Create access to the subdirectory. 11) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 3Dh Open A File Open disk file with handle entry AH 3Dh AL access code byte (DOS 2.x) bits 0-2 file attribute 000 read only 001 write only 010 read/write (default) 3-7 reserved, should be set to zero (DOS 3.x) bits 0-2 file attribute 000 read only 001 write only 010 read/write (default) 3 reserved, should be set to zero 4-6 sharing mode (network) 000 compatibility mode (default) 001 read/write access denied (exclusive) 010 write access denied 011 read access denied 100 full access permitted 7 inheritance flag 0 file inherited by child process 1 file private to child process DS:DX address of ASCIIZ drive/path/filename string return CF set on error AX error code - MS-DOS (01h, 02h, 03h, 04h, 05h, 0Ch) - DR-DOS (02h, 04h, 05h, 0Ch) and MS-DOS 5.0 AX 16 bit DOS file handle note 1) Opens any normal, system, or hidden file. 2) Files that end in a colon are not opened. 3) The read/write pointer is set at the first byte of the file and the record size of the file is 1 byte (the read/write pointer can be changed through function call 42h). The returned file handle must be used for all subsequent input and output to the file. 4) If the file handle was inherited from a parent process or was duplicated by DUP or FORCEDUP, all sharing and access restrictions are also inherited. 5) A file sharing error (error 01h) causes an int 24h to execute with an error code of 02h. 6) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 7) TOS: $3D OPEN. 8) If any process opens a file that denies a level of access, all subsequent requests to open the file at that level of access will fail. 9) Any attempt to open a file with a sharing mode that is already breached by an existing process will always fail. 10) Used by APPEND in DOS 3.2,+. 11) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 3Eh Close A File Handle Close a file and release handle for reuse entry AH 3Eh BX file handle (generated by 3Dh) return flag CF clear successful close set error AX error code if error (06h) note 1) When executed, the file is closed, the directory is updated, and all buffers for that file are flushed. If the file was changed, the time and date stamps are changed to reflect the current time. 2) If called with the handle 00000h, it will close STDIN (normally the keyboard). 3) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 4) TOS: $3E CLOSE. 5) In most versions of DOS only 15 file handles are available for user processes. It is good practice to close a file handle when you are not using it. 6) For DOS 3.1+ networks, all file locks must be removed before the file is closed. Closing a file with active locks is unpredictable. 7) Although closing a file invalidates the corresponding handle, DOS may reuse the handle to identify a file that is subsequently opened or created. You can use int 21h/440Ah (Is File or Device Remote) to tell if a given handle is valid. Function 3Fh Read From A File Or Device Read from file with handle entry AH 3Fh BX file handle CX number of bytes to read DS:DX address of buffer return flag CF clear successful read set error AX 00h pointer was already at end of file or number of bytes read or error code (05h, 06h) note 1) This function attempts to transfer the number of bytes specified in CX to a buffer location. It is not guaranteed that all bytes will be read. 2) If performed from STDIN (file handle 0000), the input can be redirected. 3) If used to read the keyboard, it will only read to the first CR. 4) The file pointer is incremented to the last byte read. 5) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 6) TOS: $3F READ. 7) If AX < CX a partial record was read. 8) For DOS 3.1+ networks, the user must have Read access to the subdirectory. 11) For PC-MOS/386 native mode, use DS:EDX and ECX instead of DS:DX and CX. Function 40h Write To A File Or Device Write to file with handle entry AH 40h BX file handle CX number of bytes to write DS:DX address of buffer return CF clear successful write set error AX number of bytes written or error code (05h, 06h) note 1) This call attempts to transfer the number of bytes indicated in CX from a buffer to a file. If CX and AX do not match after the write, an error has taken place; however no error code will be returned for this problem. This is usually caused by a full disk. 2) If the write is performed to STDOUT (handle 0001), it may be redirected. 3) To truncate the file at the current position of the file pointer, set the number of bytes in CX to zero before calling int 21h. The pointer can be moved to any desired position with function 42h. 4) This function will not write to a file or device marked read-only. 5) May also be used to display strings to CON instead of fn 09h. This function will write CX bytes and stop; fn 09h will continue to write until a '$' character is found. 6) This is the call that DOS actually uses to write to the screen in DOS 2.x and above. 7) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 8) TOS: $40 WRITE. 9) For PC-MOS/386 native mode, use DS:EDX and ECX instead of DS:DX and CX. Function 41h Delete A File From A Specified Subdirectory (UNLINK) entry AH 41h DS:DX pointer to ASCIIZ filespec to delete return CF clear successful set error AX error code if any (02h, 05h) note 1) This function will not work on a file marked read-only. 2) Wildcards are not accepted. 3) For deleting multiple files, function 13h is faster. 4) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 5) TOS: $41 UNLINK. 6) For DOS 3.1+ networks, the user must have Delete access to the subdirectory. 7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 42h Move a File Read/Write Pointer (LSEEK) entry AH 42h AL method code byte 00h offset from beginning of file 01h offset from present location 02h offset from end of file BX file handle CX:DX offset into file (high/low word) in bytes return AX:DX new file pointer (segment/offset) CF set error AX error code (01h, 06h) clear successful move note 1) If pointer is at end of file, reflects file size in bytes. 2) The value in DX:AX is the absolute 32 bit byte offset from the beginning of the file. 3) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 4) TOS: $42 LSEEK. 5) File most be open. 6) For PC-MOS/386 native mode, use ECX instead of CX. Function 43h Get/Set file attributes (CHMOD) entry AH 43h AL 00h get file attributes 01h set file attributes CX file attributes to set bit 0 read only 1 hidden file 2 system file 3 volume label 4 subdirectory 5 written since backup (archive bit) 6,7 not used 8 shareable (Novell NetWare) 9-F not used DS:DX segment/offset pointer to full ASCIIZ file name return CF set if error AX error code - MSDOS (01h, 02h, 03h, 05h) DRDOS (02h, 03h, 05h) CX file attributes on get attributes: 00h normal 01h read only 02h hidden 04h system 08h volume label 10h file is subdirectory 20h archive note 1) This call will not change the volume label or directory bits. 2) Any combination of file attributes may be used. 3) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 4) TOS: $43 CHANGE MODE (CHMOD). 5) For DOS 3.1+ networks, the user must have Create access to the subdirectory. 6) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 44h I/O Control for Devices (IOCTL) provided with full version of DOSREF Function 45h Duplicate a File Handle (DUP) entry AH 45h BX file handle to duplicate return CF clear AX duplicate handle set AX error code (04h, 06h) note 1) If you move the pointer of one handle with 3Fh (Read), 40h (Write), or 42h (Move Pointer) the pointer of the other will also be moved. 2) The handle in BX must be open. 3) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 4) TOS: $45 DUP. 5) This call can be used to update the directory entry of a file without the overhead of opening and closing it. For example, this call followed by fn 3Eh (Close File) with the duplicate file handle will cause DOS to flush its buffers and update the directory entry while the original file remains open in read/ write mode. Function 46h Force Duplicate of a Handle (FORCEDUP or CDUP) Forces handle in CX to refer to the same file at the same position as BX entry AH 46h BX existing open file handle to duplicate CX new file handle return CF clear both handles now refer to existing file set error AX error code (04h, 06h) note 1) If CX was an open file, it is closed first. 2) If you move the pointer of one handle with 3Fh (Read), 40h (Write), or 42h (Move Pointer) the pointer of the other will also be moved. 3) The handle in BX must be open. 4) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 5) TOS $46 FORCE. 6) This call may be used for redirecting input and output. Function 47h Get Current Directory Places full pathname of current directory/drive into a buffer entry AH 47h DL drive (0=default, 1=A:, etc.) DS:SI segment/offset pointer to 64-byte buffer area return CF clear DS:DI pointer to ASCIIZ pathname of the current directory set AX error code (0Fh) note 1) String does not begin with a drive identifier or a backslash. 2) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 3) TOS: $47 GETDIR. 4) For PC-MOS/386 native mode, use DS:ESI instead of DS:SI. Function 48h Allocate Memory (MALLOC) Allocates the requested number of 16-byte paragraphs of memory entry AH 48h BX number of 16-byte paragraphs desired return CF clear AX segment address of allocated space BX maximum number paragraphs available set AX error code (07h, 08h) note 1) BX indicates maximum memory available only if allocation fails. 2) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 3) TOS: $48 MALLOC. 4) Native-mode PC-MOS/386 applications allocate memory via MOS' interrupt 0D4h API function 11h. 5) When in TopView this call is checked to ensure none of the addresses are outside the application's memory partition. Function 49h Free Allocated Memory Frees specified memory blocks entry AH 49h ES segment address of area to be freed return CF clear successful set AX error code (07h, 09h) note 1) This call is only valid when freeing memory obtained by function 48h. 2) A program should not try to release memory not belonging to it. 3) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 4) TOS: $49 MFREE. 5) Native-mode PC-MOS/386 applications allocate memory via MOS' interrupt 0D4h API function 12h. 6) When in TopView this call is checked to ensure none of the addresses are outside the application's memory partition. Function 4Ah Modify Allocated Memory Blocks (SETBLOCK) Expand or shrink memory for a program entry AH 4Ah BX new size in 16 byte paragraphs ES segment address of block to change return CF clear nothing set AX error code (07h, 08h, 09h) or BX maximum number of paragraphs available note 1) Max number paragraphs available is returned only if the call fails. 2) Memory can be expanded only if there is memory available. 3) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 4) TOS: $4A SETBLOCK. 5) Native-mode PC-MOS/386 applications allocate memory via MOS' interrupt 0D4h API function 12h. 6) When in TopView this call is checked to ensure none of the addresses are outside the application's memory partition. Function 4Bh Load or Execute a Program (EXEC) entry AH 4Bh AL 00h load and execute program. A PSP is built for the program the ctrl-break and terminate addresses are set to the new PSP. (DOS 5.0) *01h load but don't execute (internal, DOS 3.x & DESQview) (see note 1) *02h load but do not execute (internal, DOS 2.x only) 03h load overlay (do not create PSP, do not begin execution) *04h start async process (Euro-DOS 4.0 only) (see note 12) (DOS 5.0) 05h EnterExecState API (see note 17) DS:DX segment/offset pointer to the ASCIIZ string with the drive, path, and filename to be loaded ES:BX segment/offset pointer to a parameter block for the load (AL=00h) word segment address of environment string to be passed (0=use current) dword pointer to the command line to be placed at PSP+80h dword pointer to default FCB to be passed at PSP+5Ch dword pointer to default FCB to be passed at PSP+6Ch (*AL=01h) word segment of environment (0 = use current) dword pointer to command line dword pointer to FCB 1 dword pointer to FCB 2 (DOS 3.x+) dword will hold SS:SP on return (DOS 3.x+) dword will hold program entry point (CS:IP) on return (*AL=02h) word segment of environment (0 = use current) dword pointer to command line dword pointer to FCB 1 dword pointer to FCB 2 (AL=03h) word segment address where file will be loaded word relocation factor to be applied to the image return CF set error AX error code (01h - 05h, 08h, 0Ah, 0Bh) CF clear if successful for fn 00h, process ID set to new program's PSP; get with function 62h for fn 01h and DOS 3.x+ or DESQview, process ID set to new program's PSP; get with function 62h for fn 01h and DOS 2.x, new program's initial stack and entry point returned in registers for fn 02h, new program's initial stack and entry point are returned in the registers note 1) If you make this call with AL=1 the program will be loaded as if you made the call with AL=0 except that the program will not be executed. Additionally, with AL=1 the stack segment and pointer along with the program's CS:IP entry point are returned to the program which made the 4B01h call. These values are put in the four words at ES:BX+0Eh. On entry to the call ES:BX points to the environment address, the command line and the two default FCBs. This form of EXEC is used by DEBUG.COM. 2) Application programs may invoke a secondary copy of the command processor (normally COMMAND.COM) by using the EXEC function. Your program may pass a DOS command as a parameter that the secondary command processor will execute as though it had been entered from the standard input device. The procedure is: A. Assure that adequate free memory (17k for 2.x and 3.0, 23k for 3.1) exists to contain the second copy of the command processor and the command it is to execute. This is accomplished by executing function call 4Ah to shrink memory allocated to that of your current requirements. Next, execute function call 48h with BX=0FFFFh. This returns the amount of memory available. B. Build a parameter string for the secondary command processor in the form: 1 byte length of parameter string xx bytes parameter string 1 byte 0Dh (carriage return) For example, the assembly language statement below would build the string to cause execution of the command FOO.EXE: DB 19,"/C C:FOO",13 C. Use the EXEC function call (4Bh), function value 0 to cause execution of the secondary copy of the command processor. (The drive, directory, and name of the command processor can be obtained from the COMSPEC variable in the DOS environment passed to you at PSP+2Ch.) D. Remember to set offset 2 of the EXEC control block to point to the string built above. 3) All open files of a process are duplicated in the newly created process after an EXEC, except for files originally opened with the inheritance bit set to 1. 4) The environment is a copy of the original command processor's environment. Changes to the EXECed environment are not passed back to the original. The environment is followed by a copy of the DS:DX filename passed to the child process. A zero value will cause the child process to inherit the environment of the calling process. The segment address of the environment is placed at offset 2Ch of the PSP of the program being invoked. 5) This function uses the same resident part of COMMAND.COM, but makes a duplicate of the transient part. 6) How EXEC knows where to return to: Basically the vector for int 22h holds the Terminate address for the current process. When a process gets started, the previous contents of int 22h get tucked away in the PSP for that process, then int 22h gets modified. So if Process A EXECs process B, while Process B is running, the vector for int 22h holds the address to return to in Process A, while the save location in Process B's PSP holds the address that process A will return to when *it* terminates. When Process B terminates by one of the usual legal means, the contents of int 22h are (surmising) shoved onto the stack, the old terminate vector contents are copied back to int 22h vector from Process B's PSP, then a RETF or equivalent is executed to return control to process A. 7) To load an overlay file with 4B: first, don't de-allocate the memory that the overlay will load into. With the other 4Bh functions, the opposite is true - you have to free the memory first, with function 4Ah. Second, the "segment address where the file will be loaded" (first item in the parameter block for sub-function 03) should be a paragraph boundary within your currently-allocated memory. Third, if the procedures within the overlay are FAR procs (while they execute, CS will be equal to the segment address of the overlay area), the relocation factor should be set to zero. On the other hand, if the CS register will be different from the overlay area's segment address, the relocation factor should be set to represent the difference. You determine where in memory the overlay file will load by using the segment address mentioned above. Overlay files are .EXEs (containing header, relocation table, and memory image). 8) When function 00h returns, all registers are changed, including the stack. You must resore SS, SP, and any other required registers. 9) PCDOS EXEC function 3 (overlay) lives in the transient piece of COMMAND.COM and gets loaded when needed, thus the requirement for enough free space to load the EXEC loader (about 1.5k). Under MS-DOS the EXEC system call lives in the system space. 10) If you try to overlay an .EXE file with the high/low switch set to load the in the upper end of memory nothing will happen. The high/low switch is only for process creation, not for overlays. 11) DOS 2.x destroys all registers, including SS:SP. 12) (AL=04h) This is DOS 4.0 as released in 1987 to various European OEMs. It is not related to US DOS 4.0. 13) This call is explicitly supported by the OS/2 1.x DOS Compatibility Box. 14) TOS: $4B EXEC. 15) New with DOS 5.0. Sets up for EXEC, including setting the DOS version number returned by SETVER/int 21h,fn 30h. If DOS is installed in the HMA this function turns off the A20 line, making the HMA inaccessible. If your program needs the HMA you must turn it back on before EXECing. DOS normally turns the A20 line back on when called for normal system functions. Your program must call EXEC immediately after this subfunction. You may not call any DOS, BIOS, or system interrupts between this subfunction and loading your program. 15) When in TopView this call is checked to ensure none of the addresses are outside the application's memory partition. 16) This call is documented in the MS 5.0 TR, and in the PC-MOS/386 TR. 17) Some applications use their own EXEC scheme instead of calling this function. Since DOS 5 enhanced the EXEC functions these programs might not work, so Microsoft added a new set of functions called EnterExecState. If a self-EXECing program calls EnterExecState before EXECing, DOS 5 will do various internal fixups to keep things happy. Function 4Ch Terminate a Process (EXIT) Quit with ERRORLEVEL exit code entry AH 4Ch AL exit code in AL when called, if any, is passed to next process return none note 1) Control passes to DOS or calling program. 2) Return code from AL can be retrieved by ERRORLEVEL or function 4Dh. 3) All files opened by this process are closed, buffers are flushed, memory is released, any network file region locks are released, and the disk directory is updated. 4) Restores: Terminate vector from PSP:000Ah Ctrl-C vector from PSP:000Eh Critical Error vector from PSP:0012h 5) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 6) TOS: $4C TERM. Returns 2-byte errorlevel to calling program 7) Under DOS 3.1+ networks, all file locks should be removed before terminating the program. Function 4Dh Get Return Code of a Subprocess (WAIT) Get return from functions 31h and 4Dh (ERRORLEVEL) entry AH 4Dh return AH circumstance which caused termination 00h normal termination 01h control-break or control-C 02h critical device error 03h terminate and stay resident (function 31h) AL exit code of subprogram (functions 31h or 4Ch) note 1) The exit code is only returned once (the first time). 2) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 3) Many programmers have wondered where DOS stores this information, so they might access it multiple times or set it directly. This is a version-dependent area that changes with every release of DOS. Function 4Eh Find First Matching File (FIND FIRST) entry AH 4Eh CX search attributes (see function 43h) DS:DX segment/offset pointer to ASCIIZ filename (with attributes) return CF set AX error code (02h, 03h, 12h) clear data block written at current DTA format of block is: (info from BIX) documented by Micro- |00h 1 byte attribute byte of search soft as "reserved for |01h 1 byte drive letter for search DOS' use on subsquent |02h 11 bytes the search name used Find Next calls" |0Ch 2 bytes word value of last entry function 4Fh |0Fh 4 bytes dword pointer to this DTA |13h 2 bytes word directory start | PC-DOS 3.10 (from INTERRUP.ARC) |00h 1 byte drive letter |01h-0Bh 11 bytes search template |0Ch 1 byte search attributes | DOS 2.x (and DOS 3.x except 3.1?) (from INTERRUP.ARC) |00h 1 byte search attributes |01h 1 byte drive letter |02h-0Ch 11 bytes search template |0Dh-0Eh 2 bytes entry count within directory |0Fh-12h 4 bytes reserved |13h-14h 2 bytes cluster number of parent directory 15h 1 byte file attribute 16h 2 bytes file time, bit mask: 0-4 half-seconds 5-10 minute 11-15 hour 18h 2 bytes file date, bit mask: 0-4 day 5-8 month 9-15 years since 1980 1Ah 2 bytes low word of file size 1Ch 2 bytes high word of file size 1Eh 13 bytes name and extension of file found, plus 1 byte of 0s. All blanks are removed from the name and extension, and if an extension is present it is preceded by a period. note 1) This function does not support network operations. 2) Wildcards are allowed in the filespec. 3) If the attribute is zero, only ordinary files are found. If the volume label bit is set, only volume labels will be found. Any other attribute will return that attribute and all normal files together. 4) To look for everything except the volume label, set the hidden, system, and subdirectory bits all to 1. 5) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 6) TOS: $4E SFIRST. 7) There is a reported anomaly in MS-DOS 2.11. Odd things happen when you give it "C:\" as a file name. FindFirst reports it as a valid file and Open returns a handle. If you read it twice DOS reports an FAT error and aborts. You can demonstrate this by: FIND "whatever" c:\ [twice] Int 21h/AH=044 AL=0 returns the handle as a NUL device which makes a certain amount of sense since C:\ is a null terminated string. The programming solution is to trap 'C:\' before it's used. 8) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. ES:EBX is a pointer to a 43-byte data area used instead of the DTA. Format: 0-20 reserved for MOS 21 attribute 22-23 time of last update 24-25 date of last update 26-29 file size in bytes 30-42 found filename, followed by 00h Function 4Fh Find Next Matching File (FIND NEXT) Find next ASCIIZ file entry AH 4Fh return CF clear data block written at current DTA set AX error code (02h, 12h) note 1) If file found, DTA is formatted as in call 4Eh. 2) Volume label searches using 4Eh/4Fh reportedly aren't 100% reliable under DOS 2.x. The calls sometime report there's a volume label and point to a garbage DTA, and if the volume label is the only item they sometimes won't find it. Most references recommend the use of the older FCB calls for dealing with the volume labels. 3) This function does not support network operations. 4) Use of this call assumes that the original filespec contained wildcards. 5) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 6) TOS: $4F SNEXT. 7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. ES:EBX is a pointer to a 43-byte data area used instead of the DTA. Format: 0-20 reserved for MOS 21 attribute 22-23 time of last update 24-25 date of last update 26-29 file size in bytes 30-42 found filename, followed by 00h Function 50h "Used Internally by DOS" - Set PSP or SetPID * Set new Program Segment Prefix (current Process ID) entry AH 50h BX segment address of new PSP return none - swaps PSPs regarded as current by DOS note 1) By putting the PSP segment value into BX and issuing call 50h DOS stores that value into a variable and uses that value whenever a file call is made. 2) Note that in the PSP (or PDB) is a table of 20 (decimal) open file handles. The table starts at offset 18h into the PSP. If there is an 0FFh in a byte then that handle is not in use. A number in one of the bytes is an index into an internal FB table for that handle. For instance the byte at offset 18h is for handle 0, at offset 19h handle 1, etc. up to 13h. If the high bit is set then the file associated by the handle is not shared by child processes EXEC'd with call 4Bh. 3) Function 50h is dangerous in background operations prior to DOS 3.x as it uses the wrong stack for saving registers. (same as functions 0..0Ch in DOS 2.x). It doesn't use stack in 3.0+, so it is safe to use in later versions of DOS. 4) Under DOS 2.x, this function cannot be invoked inside an int 28h handler without setting the Critical Error flag. 5) Open file information, etc. is stored in the PSP DOS views as current. If a program (eg. a resident program) creates a need for a second PSP, then the second PSP should be set as current to make sure DOS closes that as opposed to the first when the second application finishes. 6) See PC Mag Vol.5, No 9, p.314 for discussion, also used in their BCOPY.ASM utility. 7) Used by DOS 3.3 PRINT & DEBUG, DesQview 2.01, Windows 1.03, SYMDEB from MASM 4.0. 8) This call is available in the OS/2 1.x DOS Compatibility Box. 9) DOS stores the PID in one location, but the actual address is version dependent. The strategy is to find the PID and thereby find its address. If you have its address, you can swap PIDs from the TSR pop-up code by peeking and poking. In the initialization code, use function 51hto get the PID. You know that DOS lives between the interrupt vectors 0:0 - 0:100 and that PID. Other programs might be in there, but DOS is too. Search that memory for a copy of the PID. When you find one, use this function to set a phony PID. If the location where you found the original PID changes to the phony PID, you have found the address of the PID. Don't forget to reset the PID with SetPID after each test. DOS 2.0 and 2.1 maintain the PID in two locations, not one. Function 51h Get Program Segment Prefix (GetPID) Returns the PSP address of currently executing program entry AH 51h return BX address of currently executing program (process ID) note format of PSP: offset size description 00h 2 bytes program exit point 02h word memory size in paragraphs 04h byte unused (0) 05h 5 bytes CP/M style entry point (far call to DOS) 0Ah word terminate address (old int 22h) 0Ch word terminate segment 0Eh word break address (old int 23h) 10h word break segment 12h word error address (old int 24h) 14h word error segment 16h word parent PSP segment 18h 20 bytes DOS 2.0+ open files, 0FFh = unused 2Ch word DOS 2.0+ environment segment 2Eh dword far pointer to process's SS:SP 32h word DOS 3.x+ max open files 34h DOS 3.x+ open file table address 36h dword DOS 3.x+ open file table segment 38h 24 bytes unused by DOS versions before 3.3 50h 3 bytes DOS function dispatcher (FAR routine) 53h 9 bytes unused 55h FCB #1 extension 5Ch 16 bytes FCB #1, filled in from first command line argument 6Ch 20 bytes FCB #2, filled in from second command line argument 80h128 bytes command tail / default DTA buffer note 1) Used in DOS 2.x, 3.x uses 62h. 2) Function 51h is dangerous in background operations prior to DOS 3.x as it uses the wrong stack for saving registers. (same as functions 0..0Ch in DOS 2.x). Doesn't use any DOS stacks in DOS 3.0+. 3) 50h and 51h might be used if you have more than one process in a PC. For instance if you have a resident program that needs to open a file you could first call 50h to get the current ID and then call 50h to set the ID to your PSP. 4) Under DOS 2.x, this function cannot be invoked inside an int 28h handler without setting the Critical Error flag. 5) Formerly "undocumented", now described in MS 5.0 TR. 6) This call is available in the OS/2 1.x DOS Compatibility Box. FUNCTION 52h - see file 52h provided with full version of DOSREF Function 53h "Used Internally by DOS" - Translate BPB * Translates BPB (BIOS Parameter Block, see below) into a DOS Disk Block (see function call 32h). entry AH 53h DS:SI pointer to BPB (BIOS Parameter Block) ES:BP pointer to buffer area for DOS Disk Block Layout of BPB: offset size description 00h-01h word bytes per sector, get from DDB bytes 02h-03h. 02h byte sectors per cluster, get from (DDB byte 4) + 1 03h-04h word reserved sectors, get from DDB bytes 06h-07h 05h byte number of FATs, get from DDB byte 08h 06h-07h word # of root dir entries, get from DDB bytes 09h-0Ah for DOS 3.x: 08h-09h word total number of sectors, get from: ((DDB bytes 0Dh-0Eh) - 1) * (sectors per cluster (BPB byte 2)) + (DDB bytes 0Bh-0Ch) for DOS 4.x: set to zero if partition is larger than 32Mb, set dword at 15h to actual number of sectors 0Ah word media descriptor byte, get from DDB byte 16h 0Bh-0Ch word number of sectors per FAT, get from DDB byte 0Fh for DOS 3.x: 0Dh word number of sectors per track 0Fh word number of heads 11h dword number of hidden sectors 15h 11 bytes reserved for DOS 4.x: 15h dword total number of sectors if word at 08h contains zero return unknown note This function is documented as 'SetDPB' in the Zenith MS-DOS 3.05 TRM. Function 54h Get Verify Setting Get verify flag status entry AH 54h return AL 00h if flag off 01h if flag on note 1) Flag can be set with function 2Eh. 2) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 3) The verify state is off by default. Function 55h "Used Internally by DOS" - Create "Child" PSP * Create PSP: similar to function 26h (which creates a new Program Segment Prefix at segment in DX) except creates a "child" PSP rather than copying the existing one. entry AH 55h DX segment number at which to create new PSP. return unknown note 1) This call is similar to call 26h which creates a PSP except that unlike call 26h the segment address of the parent process is obtained from the current process ID rather than from the CS value on the stack (from the INT 21h call). DX has the new PSP value and SI contains the value to be placed into PSP:2 (top of memory). 2) Function 55 is merely a substitute for function 26h. It will copy the current PSP to the segment address DX with the addition that SI is assumed to hold the new memory top segment. This means that function 26h sets SI to the segment found in the current PSP and then calls function 55h. Function 56h Rename a File entry AH 56h DS:DX pointer to ASCIIZ old pathname ES:DI pointer to ASCIIZ new pathname return CF clear successful rename set AX error code (02h, 03h, 05h, 11h) note 1) Works with files in same logical drive only. 2) Wildcard characters not allowed in filename. 3) The name of a file is its full pathname. The file's full pathname can be changed while leaving the actual FILENAME.EXT unchanged. Changing the pathname allows the file to be "moved" from subdirectory to subdirectory on a logical drive without actually copying the file. 4) DOS 3.x allows renaming of directories. 5) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 6) TOS: $56 RENAME. Similar to MS-DOS 2.x. 7) Under DOS 3.1+ networks, the user must have Read and Create access to the affected directories. 8) For PC-MOS/386 native mode, use DS:EDX and ES:EDI instead of DS:DX and ES:DI. Function 57h Get/Set a File's Date and Time Read or modify time and date stamp on a file's directory entry entry AH 57h AL function code 00h Get Date and Time 01h Set Date and Time CX time to be set DX date to be set 02h unknown (DOS 4.0+) 03h unknown 04h unknown (DOS 4.0+) BX file handle return CF clear CX time of last write (if AL = 0) DX date of last write (if AL = 0) set AX error code (01h, 06h) note 1) Date/time formats are: CX bits 0Bh-0Fh hours (0-23) 05h-0Ah minutes (0-59) 00h-04h #2 sec. incr. (0-29) DX bits 09h-0Fh year (relative to 1980) 05h-08h month (0-12) 00h-04h day of the month (0-31) 2) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 3) TOS: $57 GSDTOF. Function 58h Get/Set Allocation Strategy (DOS 3.0+) entry AH 58h AL 00h Get Current Strategy (see 01h) Used to obtain the current allocation strategy. First Fit is the normal default. 01h Set New Current Strategy BL new strategy 00h First Fit - chooses the lowest block in memory which will fit (this is the default). (use first memory block large enough) 01h Best Fit - chooses the smallest block which will fill the request. 02h Last Fit - chooses the highest block which will fit. (DOS 5.0) 40h FIRST_FIT_HIGHONLY - search upper memory area for the lowest available block (DOS 5.0) 41h BEST_FIT_HIGHONLY - search upper memory area for the smallest block that fits the request (DOS 5.0) 42h LAST_FIT_HIGHONLY - search upper memory area for the highest available block (DOS 5.0) 80h FIRST_FIT_HIGH - search upper memory area for the lowest available block. If no block found, load in conventional memory (DOS 5.0) 81h BEST_FIT_HIGH - seach the upper memory area for the closest match to the requested size. If no match is found, load in convenional memory. (DOS 5.0) 82h LAST_FIT_HIGH - search the upper memory area for the available block at the highest address. If no block is found, load in conventional memory. 02h Get UMB Link State Indicates if high DOS memory arenas are currently part of the conventional DOS memory arena. 03h Set UMB Link State BX 00h Unlink High DOS memory blocks 01h Link High DOS memory blocks note: Adds or removes high memory blocks from the DOS arena. Returns an error if no high arenas exist. return CF clear successful (AL=00) AX strategy code (see 01h) For DOS 5.0+, (AL=02) AL 00h if upper memory area is not linked 01h if the upper memory area is linked set error AX error code (01h) (AL=03) AX 0001h invalid function if DOS was loaded without DOS=UMB 0007h memory arena trashed note 1) A program that changes the allocation strategy or the high DOS link state should ALWAYS restore it to its original condition before exiting, or subsequent programs may fail. 2) The set subfunction accepts any value in BL; 2 or greater means last fit. The get subfunction returns the last value set, so programs should check whether the value is greater than or equal to 2. 3) For discussion of best fit vs. first fit allocation strategies, see Knuth, *Fundamental Algorithms.* Very briefly, Knuth finds that first fit methods are far superior to best fit, which increases both allocation overhead and memory fragmentation. The "last" fit that DOS offers is nothing other than a first fit, starting the search at the other end of the chain (the algorithm still takes the first fitting block that is encountered in the search). 4) For DOS 5+, the default scheme is "allocate high first". This is actually a variant of the previous first/best/last allocation options. When enabled, the high-first strategy causes DOS to begin its free block search at the first UMB. If DOS can't find enough memory in the UMB, it searches from the beginning of conventional memory. As a result, high-first may result in a worse fit than best fit alone if there is a better fit low than high. Function 59h Get Extended Error Code (DOS 3.0+) The Get Extended Error function call (59h) is intended to provide a common set of error codes and to supply more extensive information about the error to the application. The information returned from function call 59h, in addition to the error code, is the error class, the locus, and the recommended action. The error class provides information about the error type (hardware, internal, system, etc.). The locus provides information about the area involved in the failure (serial device, block device, network, or memory). The recommended action provides a default action for programs that do not understand the specific error code. Newly written programs should use the extended error support both from interrupt 24h hard error handlers and after any int 21h function calls. FCB function calls report an error by returning 0FFh in AL. Handle function calls report an error by setting the carry flag and returning the error code in AX. Int 21h handle function calls for DOS 2.x continue to return error codes 0-18. Int 24h handle function calls continue to return error codes 0-12. But the application can obtain any of the error codes used in the extended error codes table by issuing function call 59h. Handle function calls for DOS 3.x can return any of the error codes. However, it is recommended that the function call be followed by function call 59h to obtain the error class, the locus, and the recommended action. The Get Extended Error function (59h) can always be called, regardless of whether the previous DOS call was old style (error code in AL) or new style (carry bit). It can also be used inside an int 24h handler. You can either check AL or the carry bit to see if there was no error, and call function 59h only if there was an error, or take the simple approach of always calling 59h and letting it tell you if there was an error or not. When you call function 59h it will return with AX=0 if the previous DOS call was successful. Various versions of IBM's DOS, MSDOS, OEM customized versions of MSDOS, Digital's DRDOS, and other DOS emulating environments sometimes return different error codes for the same function. Be careful if you are testing for one specific error condition. entry AH 59h BX version code (0000 for DOS 3.0 and 3.1) return AX extended error code: 01h Invalid function number 2.0+ 02h File not found 2.0+ 03h Path not found 2.0+ 04h Too many open files, no file handles left 2.0+ 05h Access denied 2.0+ 06h Invalid handle 2.0+ 07h Memory control blocks destroyed 2.0+ 08h Insufficient memory 2.0+ 09h Invalid memory block address 2.0+ 0Ah Invalid environment 2.0+ 0Bh Invalid format 2.0+ 0Ch Invalid access code 2.0+ 0Dh Invalid data 2.0+ 0Eh Reserved 2.0+ 0Fh Invalid drive was specified 2.0+ 10h Attempt to remove the current directory 2.0+ 11h Not same device 2.0+ 12h No more files 2.0+ 13h Tried to access write-protected diskette 2.0+ 14h Unknown unit 2.0+ 15h Drive not ready 2.0+ 16h Unknown command 2.0+ 17h Bad CRC check 2.0+ 18h Bad request structure length 2.0+ 19h Seek error 2.0+ 1Ah Unknown media type 2.0+ 1Bh Sector not found 2.0+ 1Ch Printer out of paper 2.0+ 1Dh Write fault 2.0+ 1Eh Read fault 2.0+ 1Fh General failure 2.0+ 20h Sharing violation 3.0+ 21h Lock violation 3.0+ 22h Invalid disk change 3.0+ 23h FCB unavailable 3.0+ 24h Sharing buffer overflow 3.3+ 25h Bad code page 4.0+ 26h Handle EOF 4.0+ 27h Handle disk full 4.0+ 28h Reserved 29h " 2Ah " 2Bh " 2Ch " 2Dh " 2Eh " 2Fh " 30h " 31h Reserved 32h Network: request not supported 3.1+ 33h Network: remote computer not listening 3.1+ 34h Network: duplicate name on network 3.3+ 35h Network: name not found 3.3+ 36h Network: busy 3.3+ 37h Network: device no longer exists 3.3+ 38h Network: NETBIOS command limit exceeded 3.3+ 39h Network: adapter hardware error 3.3+ 3Ah Network: incorrect response from network 3.3+ 3Bh Network: unexpected network error 3.3+ 3Ch Network: incompatible remote adapter 3.3+ 3Dh Network: print queue full 3.3+ 3Eh Network: not enough space for print file 3.3+ 3Fh Network: print file was deleted 3.3+ 40h Network: name was deleted 3.3+ 41h Network: access denied 3.3+ 42h Network: device type incorrect 3.3+ 43h Network: name not found 3.3+ 44h Network: name limit exceeded 3.3+ 45h Network: NETBIOS session limit exceeded 3.3+ 46h Network: sharing temporarily paused 3.3+ 47h Network: request not accepted 3.3+ 48h Network: print or disk redirection paused 3.1+ 49h Reserved 4Ah " 4Bh " 4Ch " 4Dh " 4Eh " 4Fh Reserved 50h File exists 3.3+ 51h Reserved 3.3+ 52h Cannot make directory entry 4.0+ 53h Fail on interrupt 24h 3.3+ 54h Network: too many redirections 3.3+ 55h Network: duplicate redirection 3.3+ 56h Invalid password 3.3+ 57h Invalid parameter 3.3+ 58h Network: data fault (write error) 3.3+ 59h Reserved 5Ah Comp not loaded 5.0+ BH class of error: (DOS 5.0 name) 01h Out of resource ERRCLASS_OUTRES (not enough disk space, etc) 02h Temporary situation ERRCLASS_TEMPSIT (not an error, but a temporary situation that is expected to end, such as a locked region in a file) 03h Authorization ERRCLASS_AUTH (denied access - sharing or network) 04h Internal ERRCLASS_INTRN (DOS internal error) 05h Hardware failure ERRCLASS_HRDFAIL (bad floppy or HD controller, etc.) 06h System failure ERRCLASS_SYSFAIL (error not due to executing program, such as missing configuration or data files) 07h Application program error ERRCLASS_APPERR (executing program bombed) 08h Not found ERRCLASS_NOTFND (file or device not found) 09h Bad format ERRCLASS_BADFMT (file or item invalid format or type) 0Ah Locked ERRCLASS_LOCKED (network or SHARE lock) 0Bh Media error ERRCLASS_MEDIA (wrong volume ID, disk failure) 0Ch Already exists ERRCLASS_ALREADY (file or device already exists) 0Dh Unknown ERRCLASS_UNK (Smurfs infesting system board) BL suggested action code: 01h Retry ERRACT_RETRY 02h Delayed retry ERRACT_DLYRET 03h Prompt user ERRACT_USER 04h Abort after cleanup ERRACT_ABORT 05h Immediate abort ERRACT_PANIC 06h Ignore ERRACT_IGNORE 07h Retry after user intervention ERRACT_INTRET CH locus (where error occurred): 01h Unknown or not appropriate ERRLOC_UNK 02h Block device ERRLOC_DISK 03h Network related ERRLOC_NET 04h Serial device ERRLOC_SERDEV 05h Memory related ERRLOC_MEM note 1) Not all DOS functions use the carry flag to indicate an error. Carry should be tested only on those functions which are documented to use it. 2) None of the DOS functions which existed before 2.0 use the carry indicator. Many of them use register AL as an error indication instead, usually by putting 0FFh in AL on an error. Most, but not all, the "new" (2.x, 3.x) functions do use carry, and most, but not all, of the "old" (1.x) functions use AL. 3) On return, CL, DI, DS, DX, ES, BP, and SI are destroyed - save before calling this function if required. 4) DOS 2.x Error Codes: If you are using function calls 38h-57h with DOS 2.x, to check if an error has occurred, check for the following error codes in the AX register: call| error code call| error code call| error code ----|-------------------|--------------------|---------------- 38h | 2 41h | 2,3,5 4Ah | 7,8,9 39h | 3,5 42h | 1,6 4Bh | 1,2,3,5,8,10,11 3Ah | 3,5,15 43h | 1,2,3,5 4Eh | 2,3,18 3Bh | 3 44h | 1,3,5,6 4Fh | 18 3Ch | 3,4,5 45h | 4,6 56h | 2,3,5,17 3Dh | 2,3,4,5,12 46h | 4,6 57h | 1,6 3Eh | 6 47h | 15 3Fh | 5,6 48h | 7,8 40h | 5,6 49h | 7,9 5) Note that extended error codes 13h through 1Fh correspond to error codes 00h through 0Ch returned by int 24h. 6) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. Function 5Ah Create Temporary File Create unique filename (for temporary use) (DOS 3.0+) entry AH 5Ah DS:DX pointer to buffer containing an ASCIIZ directory pathname ending with a backslash (\). The buffer must have at least 13 bytes free following the backslash, as the file name and extension will be written there. CX file attribute (00h, 01h, 02h, 04h, 20h only) return CF clear AX handle DS:DX new ASCIIZ pathname set AX error code (03h, 04h, 05h) note 1) The file created is not truly "temporary". It must be removed by the user. 2) If the filename created already exists in the current directory, this function will call itself again with another unique filename until a truly unique filename is found. 3) The temporary filename usually consists of mixed letters and numbers. No file extension appears to be generated. 4) DOS 3.0-4.01 used mixed letters and numbers. MS DOS 5.0 appears to use letters only. DR DOS 5.0 appears to use numbers only. 5) Under DOS 3.1+ and NETBIOS compatible networks, DOS opens the file in compatibility mode. 6) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 7) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 5Bh Create a New File (DOS 3.0+) entry AH 5Bh DS:DX segment/offset pointer to an ASCIIZ pathname CX file attribute (00h, 01h, 02h, 04h, 20h only) return CF clear AX file handle DS:DX new ASCIIZ pathname set AX error code (03h, 04h, 05h, 50h) note 1) Unlike function 3Ch, function 5Bh will fail if the file already exists. This is useful on networks, since another application might create a file of the same name with 3Ch first, causing the first 3Ch to fail. Use of this call instead of 3Ch is good practice for code that will not need to run under DOS 2.x. 2) Under DOS 3.1+ networks, DOS opens the file in read/write mode. This call will fail if the user does not have Create access. 3) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 4) The MSDOS Encyclopedia suggests this call may be used to implement semaphores in LANs or multitasking environments. A zero-byte marker file could be created to indicate semaphore set. 5) For PC-MOS/386 native mode, use DS:EDX instead of DS:DX. Function 5Ch Lock/Unlock File Access (DOS 3.0+) entry AH 5Ch AL 00h to lock file region 01h to unlock file region BX file handle CX:DX 4-byte starting offset from beginning of file of region to lock SI:DI 4-byte integer, high/low size of region to lock (in bytes) return CF clear successful set AX error code (01h, 06h, 21h, 24h) note 1) Unlock all files before exiting or undefined results may occur. Programs using file locking should trap int 23h (Control-C Handler Address) and int 24h (Critical Error Handler Address) and unlock files before returning to the caller. 2) Programs spawned with EXEC inherit all the parent's file handles but not the file locks. 3) This call is explicitly supported in the OS/2 1.x DOS Compatibility Box. 4) You may lock an entire file, any part of a file, or several parts of the same file. For example, it would be more efficient to lock an area in a database containing a single record than to lock the entire file. If two adjacent sections of a file are locked separately, they must be unlocked separately - you cannot change the lock pointers and use a single unlock call. 5) You should lock only as much of a file as you need and keep the lock only for as long as necessary. Should a file need to be shared and updated often, continual locking and unlocking can slow file access detectably. 6) This call returns error 01h if SHARE is not loaded. 7) Locked files must be unlocked before the program terminates, or the result is undefined. 8) A transaction-oriented algorithm for using locking is recommended. In effect, assert lock, read data, change data, remove lock. An application should release its lock when a transaction is complete. 9) Locking past end-of-file does not cause an error. 10) Locking a portion of a file with fn 5Ch denies all other processes both read and write access to the locked region. 11) For PC-MOS/386 native mode, use ECX and EDX instead of CX:DX. Function 5Dh Multifunction, DOS Internal - partial (DOS 3.x+) entry AH 5Dh AL subfunction 00h Indirect Function Call DS:DX pointer to buffer containing register values AX, BX, CX, DX, SI, DI, DS, ES for a call to int 21h return as appropriate for function being called note Does not check AH. Out of range values will crash the system. 01h SYNC? (DOS 3.1+) parameters unknown note 1) Does something to each disk file in the system. File Table which has been written to. 2) If remote file, calls int 2Fh/fn1107h. 3) Seems to update the time stamp of all open files which have been written to. 02h SHARE.EXE? (DOS 3.1+) note Error unless SHARE is loaded (calls fn 52h+4Ah) 03h SHARE.EXE? (DOS 3.1+) note Error unless SHARE is loaded (calls fn 52h+4Ah) 04h SHARE.EXE functions? (DOS 3.1+) note Error unless SHARE is loaded (calls fn 52h+4Ah) 05h Network functions? (DOS 3.1+) DS:DX pointer to buffer (see AX=0Ah), only fields at offset 12h, 14h used note Error unless SHARE is loaded (calls fn 52h+5Ah) 06h Get Address of Critical Error Flag DS:DX pointer to buffer (see 0Ah), only fields at offset 12h, 14h used return CX unknown value DX unknown value DS:SI pointer to critical error flag notes This call does a lot of other work in addition to returning the pointer. Setting the CritErr flag allows use of functions 50h/51h from int 28h under DOS 2.x by forcing use of correct stack. (LANtastic) 07h Return Redirected Printer mode return DL 00 output is combined 01h output is separated note The current printer mode (either printer output combined or separated) is returned. (LANtastic) 08h Set Redirected Printer Mode DL 00h set redirected output to be combined 01h set redirected output to be separated. (implicitly starts a new print job) return none note 1) The current printer mode (either printer output combined or separated) can be set. 2) may be used by COMMAND.COM (LANtastic) 09h Flush Printer Output return none note 1) Printer output is flushed and a new print job is started. If no output exists to be flushed then this function has no effect. 2) may be used by COMMAND.COM 09h unknown - may be used by COMMAND.COM (DOS 5, doc'd) 0Ah Set Extended Error Information DS:DX address of 11-word error information table: format of error information table: offset size description 00h word value that next call to fn 59h will return in AX 02h word value that next call to fn 59h will return in BX 04h word CX 06h word DX 08h word SI 0Ah word DI 0Ch word DS 0Eh word ES 10h word reserved (set to 0) 12h word user (computer) ID, 0=local 14h word program ID, 0=local program return none return DS:SI (for 06h) pointer to critical error flag note 1) Function 0Ah; DOS 3.1+. 2) Function 06h; setting CritErr flag allows use of functions 50h/51h from int 28h under DOS 2.x by forcing the use of the correct stack. 3) Functions 07h, 08h, 09h are identical in DOS 3.1 and call int 2Fh fn 1125h. Function 5Eh Network Printer DOS 3.1+ with Networks software PC-MOS/386 through 4.1 has limited support for functions 5Eh through 5F04h. The MOS NETBIOS driver must be loaded. A device name is returned for 5E00h and an "end of list" status is returned for other functions. entry AH 5Eh AL 00h Get Machine Name DS:DX pointer to 16-byte buffer for ASCIIZ name return CH 00h if name not defined <>0 name is defined CL 00h name not set <>0 NetBIOS name number DS:DX pointer to ASCIIZ name if CH <>0 CF set on error AX error code (01h) note 1) The ASCIIZ name is a 15 byte string padded to length with zeroes. 2) The NETBIOS number in CL and name at DS:DX are valid only if the value returned in CH is <>0. 01h Set Machine Name CH 00h undefine name <>0 define name CL name number DS:DX pointer to ASCIIZ name 02h Set Printer Control String BX redirection list index CX length of setup string (max 64 bytes) DS:SI pointer to ASCIIZ setup string buffer return: CF set on error AX error code (01h) note 1) Set printer setup sets a setup string to be sent to the network printer whenever a file is queued to the printer. 2) LANtastic LANOS does not process this request since printer setup strings are controlled by the system administrator using the NET_MGR program. The system call does not return an error, however. 03h Get Printer Control String BX redirection list index ES:DI pointer to 64-byte string buffer return CX length of setup string (maximum 64 bytes) return: CF set on error AX error code (01h) note 1) This call will return the setup string set with fn 02h above. 2) LANtastic LANOS does not process this request since printer setup strings are controlled by the system administer using the NET_MGR program. The system call does not return an error, however, and the length of the setup string (CX) is 0. 04h DOS 3.1+ +Microsoft Networks - unknown note Calls int 2F/AX=111Fh with 5E04h on stack. 05h DOS 3.1+ +Microsoft Networks - unknown note Calls int 2F/AX=111Fh with 5E05h on stack. 06h DOS 3.1+ +Microsoft Networks - unknown note Calls int 2F/AX=111Fh with 5E06h on stack. return CF clear successful set error AX error code (01h for all listed subfns) note 1) Used in IBM's & Microsoft's Network programs. 2) Partial documentation in Fall 1985 Byte, in Advanced MS-DOS, in MS-DOS Encyclopedia, LANtastic Programmer's Manual. 3) These services require that the network software be installed. 4) SHARE must be loaded or results can be unpredictable on 00h, or fail with 02h or 03h. 5) The redirection entry index is an index into a table that identifies the printer as a device on the network. Function 5Fh Network Redirection (DOS 3.1+ and Microsoft Networks) entry AH 5Fh AL *00h Unknown *01h Unknown 02h Get Redirection List Entry BX redirection entry index. Index 0 specifies the first entry DS:SI pointer to 16 byte area which will receive the ASCIIZ local device name ES:DI pointer to 128 byte buffer for the ASCIIZ network device name return CF set on error AX error code (01h, 12h) BH device status flag (bit 0=0 if valid) (bit 0=1 if invalid) (bits 1-7 reserved) BL device type 03 printer device 04 drive device (file) CX value stored by fn 03h call. Should be 0 for compatiblity with LAN OS DS:SI pointer to 16 byte ASCIIZ local device name ES:DI pointer to 128 byte ASCIIZ network name note 1) DX and BP are destroyed by this call. 2) This call returns information about a single redirected device (see fn 03h). This fn may be used to scan the list of redirected devices. 03h Redirect Device - Make Assign List Entry Redirects a workstation drive or device to a server directory or device. AX error code if error BL device type 03h printer device 04h file device CX stored parameter value (0 for compatibility with IBM PC Network program and LANtastic) DS:SI pointer to 16-byte ASCIIZ source device name for printer: PRN, LPT1, LPT2, LPT3 ES:DI pointer to destination 128-byte ASCIIZ network path and ASCIIZ password (e.g.,'\\machine_name\path', 0,'password',0) return CF set on error AX error code (01h, 03h, 05h, 08h, 0Fh, 12h) note 1) Redirect device allows you to connect local devices to network paths. For example you can connect your LPT1 to a printer on another node. References to LPT1 are routed to the network. 2) If the password is omitted, the pathname must be followed by two null bytes. 3) For printer redirection, MS-Network intercepts int 17h. When redirection is canceled, all printing is sent to the first local printer. (LPT1) 04h Cancel Redirection Assignment DS:SI pointer to ASCIIZ device name or network path to be canceled return CF set on error AX error code (01h, 03h, 05h, 08h, 0Fh, 12h) note 1) Cancel device redirection allows you to remove a device redirection so that the device is restored to its former state. return CF clear successful set if error AX error code (fn 02h) 01h, 12h (fn 03h) 01h, 03h, 05h, 08h (fn 04h) 01h, 0Fh note 1) Used in IBM's Network program and Microsoft MS-Networks. 2) Partial documentation in Fall 1985 Byte, in Advanced MS-DOS, in the MS-DOS Encyclopedia, LANtastic Programmer's Manual. 3) These services require that the network software be installed. 4) SHARE must be loaded or the call will fail. 5) The network device name requires a password. 6) Only printer and disk devices are supported for redirection. STDAUX, STDIN, STDOUT, and STERR are not supported by the Microsoft/IBM specification. Other companies have managed to do this with various nonstandard additions to the API. Function 60h Parse pathname (TRUENAME) (DOS 3.0+) * Perform name processing on a string (internal to DOS) entry AH 60h DS:SI pointer to ASCIIZ source string (null terminated) ES:DI pointer to destination 80 byte ASCIIZ string buffer return ES:DI buffer filled with qualified name in form (drive):(path) CF set error AX error code (02h, 03h) clear no error note 1) Documented in Zenith 3.05 Technical Reference. 2) All name processing is performed on the input string; string substitution is performed on the components, current drive/ directories are prepended, . and .. are removed. Under most networking software, the drive letter is replaced with the node name, i.e. returns pathname like \\SERVER\UTILS\TEST.TXT instead of F:\UTILS\TEST.TXT. 3) Example: If current drive/directory is C:\TEST, MYFILE.X is translated to C:\TEST\MYFILE.X; ..\SOURCE\SAMPLE.ASM is translated to C:\SOURCE\SAMPLE.ASM. 4) It is the caller's responsibility to make sure DS:SI does not point to a null string. If it does, SI is incremented, a null byte is stored at ES:DI, and the routine returns. 5) Used by CHKDSK, at least in DOS 3.3, and DOS 3.x. 6) If path string is on a JOINed drive, the returned name is the one that would be needed if the drive were not JOINed; similarly for a SUBSTed drive letter. Because of this, it is possible to get a qualified name that is not legal with the current combination of SUBSTs and JOINs. 7) Used by DOS 4.0 SHELLC.EXE. 8) This call has been discovered in DOS versions as early as 2.11. 9) In Novell Netware 2.1x, this call is not supported when the 8th bit (high ASCII) is set on any letter in the file or pathname, and when the file being inquired about is on a remote drive. This causes problems with machines using foreign code pages. 10) You need DPMI services to use this call under MS Windows 3.x. There is an example in PC Magazine, 25 June 1991, p. 389 called TRUENAME.C. Function 61h undocumented - (DOS 3.0) * Internal to DOS - parameters not known entry AH 61h return AL 00h note Supposedly documented in Zenith DOS 3.05 Technical Reference. Function 62h Get Program Segment Prefix (PSP) (DOS 3.0+) entry AH 62h return BX segment address of PSP note Under DOS 3.x+, this function does not use any of DOS' internal stacks and is thus fully reentrant. Function 63h Get Lead Byte Table (MS-DOS 2.25 only) Added in DOS 2.25 for additional foreign character set support. entry AH 63h AL subfunction 00h get system lead byte table address 01h set/clear interim console flag DL 0000h to clear interim console flag 0001h to set interim console flag 02h get interim console flag return DS:SI pointer to lead byte table (AL = 00h) DL interim console flag (AL = 02h) note 1) Function 63h destroys all registers except SS:SP on return. To avoid saving registers repeatedly, a process can copy the table or save the pointer for later use. 2) Works ONLY in MS-DOS 2.25! 3) Note fn 63h does not return errors in AL or CF. 4) Original support was for Kanji (Japanese) and Hanegul (Korean) only. 5) The lead byte table contains pairs of bytes that represent the inclusive boundary values for the lead bytes of the specified alphabet. Because of the way bytes are ordered by the 8086 microprocessor family, the values must be read as byte values, not as word values. 6) If the interim console flag is set (DL=0001h) by a program through a call to fn 63h, the following int 21h functions return interim character information on request: 07h, 08h, 0Bh, 0Ch. Function 64h Undocumented - Used internally by DOS entry AH 64h return unknown note 1) DOS 3.2+ internal function of some type? May be a network function. 2) In DOS 3.31 it seems that when you load AL with a nonzero number, int 28h will get called more often. AL=0 resets back to the default "boot up" state. Function 65h Get Extended Country Information (DOS 3.3+) Returns information about the selected country formats, code pages, and conversion tables entry AH 65h AL information ID code 01h get general internationalization info 02h get pointer to uppercase table (130 bytes max) (maps chars 80h-0FFh to their uppercase equivalents, if any; used mainly to map accented or other vowels to the corresponding plain vowels) 03h unknown 04h get pointer to filename uppercase table (130 bytes max) (similar to table for AL = 02h) (DOS 5.0+) 05h get filename character table - specifies which chars must not be used in filenames. 06h get pointer to collating sequence table (258 bytes max) (maps uppercase, lower, and accented chars together for sorting) 07h get pointer to double-byte character set table (DOS 5.0+) 20h convert character - converts character in DL to uppercase using the current uppercase table (DOS 5.0+) 21h convert string - converts string in DS:DX, length CX to uppercase using current uppercase table, returns in DS:DX (DOS 5.0+) 22h convert ASCIIZ string - converts string in DS:DX to uppercase using current uppercase table, returns in DS:DX BX code page (0FFFFh = current code page) CX amount of information to be returned (minimum 5) DX target country ID (0FFFFh = default current country) ES:DI segment/offset pointer to country information buffer return CF set on error AX error code (02h) otherwise: CX size of country information returned ES:DI pointer to country information: offset length description 00h 1 byte info ID (for all following buffers) If information ID code <> 1: 01h dword pointer to information If information ID code = 1: 01h word length of remainder of buffer (<= 38) 03h word country ID 05h word code page number 07h 34 bytes same as for int 21h function 38h If information ID code = 2: 01h word table size 05h dword pointer to uppercase table 128 bytes uppercase equivalents (if any) of chars 80h-0FFh If information ID code = 4: 01h word table size 05h dword pointer to collating table 256 bytes values used to sort characters 00h-0FFh If information ID code = 6: 01h word table size 05h dword pointer to filename uppercase table. This table starts with a 2-byte length field, then 256 ASCII values placed in order 128 bytes uppercase equivalents (if any) of chars 80h-0FFh If information ID code = 7: (DOS 4.0) unknown note 1) For AL=02h, 04h, or 06h, the first two bytes of the table give its length and then a 128 byte table of uppercase ASCII characters for 02h or 04h and a pointer to the collating sequence for 06h. 2) The country code and code page must match. If not, error 02h is in AX. 3) If more information is provided than was requested by CX, it is truncated without generating an error. 4) Country information: bytes description 01h value of AL (01h) 02h,03h size (max = 38) 04h,05h country code 06h,07h code page 08h,09h date format 0Ah,0Eh currency symbol 0Fh,10h thousands separator 11h,12h decimal separator 13h,14h date separator 15h,16h time separator 17h currency format flags 18h digits in currency 19h time format 20h-22h monocase routine entry point 23h-24h data list separator 25h-29h zeros Function 66h Get/Set Global Code Page Table (DOS 3.3+) Query/reset code page defaults entry AH 66h AL 00h Get Global Code Page 01h Set Global Page BX active code page DX system code page (active page at boot time) return CF clear successful set AX error code (unknown) if 00h BX active code page DX system code page (active page at boot time) note 1) BX = active code page: 437 = US, 860 = Portugal, 863 = Canada (French) 865 = Norway/Denmark, 850 = multilingual 2) MS 5.0 TR shows fns as 01h and 02h. Function 67h Set Handle Count (DOS 3.3+) Supports more than 20 open files per process entry AH 67h BX desired number of handles (20 to 65,535) return CF clear if OK set if error AX error code (unknown) note 1) This function changes the 20-byte handle table pointer in the PSP to point to a new, larger handle table elsewhere in memory. 2) The memory the 67h call allocates is taken from the normal DOS pool, and is reclaimed on process termination, so nothing is lost. 3) When calling this function you must release enough memory for DOS to contain the extended handle list. 4) If the requested number of handles is less than 20 nothing is done. 5) Early versions of PC-MOS/386 v4.1 did not properly deallocate memory when the number of handles was reduced. 6) The error value returned in AX is not documented in the IBM 4.0 DOS Technical Reference, the MSDOS Encyclopedia or the MS 5.0 TR. 7) For PC-MOS/386 4.x, the only error code is 08h (insufficient memory). Function 68h Commit File (DOS 3.3+) Write all buffered data to disk entry AH 68h BX file handle of previously opened file return CF clear successful set on error AX error code (unknown) note 1) Faster and more secure method of closing a file in a network than current close commands. 2) This is effectively the same as DUPing the handle for a file and then closing the new one, except that this call won't fail if the system is out of handles. 3) The file's buffers are flushed and its directory and FAT entries are updated. 4) The error value returned in AX is not documented in the IBM 4.0 DOS Technical Reference, the MSDOS Encyclopedia or the MS 5.0 TR. 5) For PC-MOS/386 4.x, the error codes are 06h (invalid handle) and 22h (wrong disk). Function 69h Disk Serial Number DOS 4.0+ (US versions) Handles "Volume Serial Number" on disks formatted with DOS 4.0+ entry AH 69h Get Volume Serial Number AL 00h get serial number 01h set serial number BL drive (0=default, 1=A, etc) DS:DX pointer to disk information table return CF set on error AX error code clear if successful AH destroyed AL (fn 00h) buffer filled with appropriate values from extended BPB (fn 01h) extended BPB on disk set to values from buffer DS:DX disk information table. Format: offset size description 00h word unknown (zeroes on my system) 02h dword disk serial number (binary) 06h 11 bytes volume label or "NO NAME " if none 11h 8 bytes FAT type - string "FAT12 " or "FAT16 " note 1) The FAT type field refers to the number of bits per directory entry. 2) Does not generate a critical error; all errors are returned in AX. 3) Error 0005h given if no extended BPB on disk. 4) Does not work on network drives (error 0001h). 5) Buffer after first two bytes is exact copy of bytes 27h thru 3Dh of extended BPB on disk. 6) FORMAT (in DOS 5.0) does not call int 21h/fn 69h. (Get/Set Volume Serial Number) For floppy disks, it calls int 21h/fn 440Dh, CH=08, CL=46 [Set Media ID], and passes the serial number. (from dsparks, BIX) Function 6Ah Unknown (DOS 4.0?) Function 6Bh Unknown (DOS 4.0?) Function 6Ch Extended Open/Create DOS 4.0+ (US) Combines functions available with Open, Create, Create New, and Commit File entry AH 6Ch AL 00h reserved [which means there might be other subfunctions?] BX mode format 0WF0 0000 ISSS 0AAA AAA is access code (read, write, read/write) SSS is sharing mode I 0 pass handle to child 1 no inherit [interesting!] F 0 use int 24h for errors 1 disable int 24h for all I/O on this handle; use own error routine W 0 no commit 1 auto commit on all writes CX create attribute bits 0 read only 1 hidden 2 system 3 volume label 4 reserved 5 archive 6-15 reserved DH 00h (reserved) DL action if file exists/does not exists bits 0-3 action if file exists 0000 fail 0001 open 0010 replace/open 4-7 action if file does not exist 0000 fail 0001 create DS:SI pointer to ASCIIZ file name return CF set on error AX error code (unknown) clear AX file handle CX action taken 01h file opened 02h file created/opened 03h file replaced/opened note When APPEND is installed, if DX=xx1x it looks only in current directory, if DX=xx0x it will search the full append path. DX is called the open flag and gives what action to take if the file exists or does not exist. Function 89h undocumented - DOS_Sleep * Not documented by Microsoft entry AH 89h return unknown note 1) Function included in Microsoft C 4.0 startup code MSDOS.INC. 2) Debugging shows that the first instruction on entry to DOS compares AH with 64h (at least in DOS 3.2) and aborts the call if AH > 64. 3) Possibly used in European MSDOS 4.0? Aftermarket Application Installed Function Calls: Novell Netware 2.11: Novell no longer recommends the int 21h method for invoking the Netware functions. Int 21h will be supported indefinitely, but the new net API calls for addressing the software through the Multiplex Interrupt (2Fh). You may address the API through int 2Fh in the same manner as int 21h; only the interrupt number is different. Novell API calls are referenced in Chapter 13. Most functions from 0B6h through 0F9h are preempted by NetWare; if your software uses any of these calls for another purpose it will likely not run under NetWare. NOTE: Novell (and most others') network software and SoftLogic's DoubleDOS conflict on the following int 21h functions 0EAh-0EEh. Netware must use int 2Fh functions instead of 21h functions if DoubleDOS will be used on the network. Functions 0E0h - 0F6h: used by AI Architects/Ergo Computing DOS extender Functions 0E4h - 0EEh: used by DoubleDOS task switcher Function 0FEh Enable Reader v4.0 API Enable Reader is a speech synthesizer interface for the blind. It will save all registers except the flags, where the zero flag will be set if the call was not one of the available Enable Reader 4.0 functions. entry AH 0FEh AL 01h Driver Output DL Character To Output return none note The Driver Output call will output the character in DL through the Enable Reader driver, without turning off the Help Functions. It will be filtered by the ASCII sort routine in the Enable Reader Driver, and if it is punctuation it will be sent according to the level of punctuation selected. entry AH 0FEh AL 02h Direct Output DL ASCII character to output return none note The Direct Output call will send the byte in DL directly to the synthesizer, bypassing the Enable Reader driver and ASCII filter sort routine. entry AH 0FEh AL 03h Message Output DL character to output return none note The Message Output call allows character filtration and punctuation, but turns off the Help functions in the driver. entry AH 0FEh AL 41h (ASCII A) Auto return none note The AUTO call turns the Spell mode on or off. entry AH 0FEh AL 4Eh (ASCII N) Punctuation Levels return none note This call selects one of five Punctuation Character Sets that can be accessed. The fifth level is "Output Punctuation", which allows all ASCII characters to be sent to the synthesizer without being filtered or translated into the Enable Reader 4.0 Punctuation Words. entry AH 0FEh AL 4Fh (ASCII O) Help Word Levels return none note The Help call selects one of four levels of help. By selecting "No Help" at the start of your program, you can use the other Help Functions without having them speak their prompts. entry AH 0FEh AL 51h (ASCII Q) Quit return none note This call will stop the synthesizer from speaking. entry AH 0FEh AL 5Ah (ASCII Z) Letter-to-Word Translator return none note This call turns the Letter-To-Word Translator on or off. For a discussion on the TRANSLATOR Function, read entry AH 0FEh AL 54h (ASCII T) Upper Case Identification return none note This call toggles identification of uppercase letters. entry AH 0FEh AL 56h (ASCII V) Video Output return none note The Video Output call toggles the output to the synthesizer from data that is printed on the video screen. Function 0FFh CED (CJ Dunford's DOS macro and command-line editor) CED installable commands entry AH 0FFh AL 00h Add Installable Command 01h Remove Installable Command 02h Reserved, may be used to test for CED installation BL mode byte bit 0 callable from DOS prompt 1 callable from application 2-7 not used in public domain CED DS:SI pointer to CR-terminated command name ES:DI pointer to far routine entry point return CF set on error AX 01h invalid function 02h command not found (subfunction 1 only) 08h insufficient memory (subfunction 0 only) 0Eh bad data (subfunction 0 only) AH 0FFh if CED not installed note 1) When PCED returns, AX and the flags are changed. Other registers are preserved, except as noted.