For Beginners & Professional Hackers/cd.iso/docum/hadware.doc/chapter.004

Text File | 1992-03-15 | 150.3 KB | 3,718 lines

                                    -72-


   **  Programmer's  Technical    Reference  for    MSDOS  and  the  IBM  PC **
─────────────────────────┤ Registered User Version ├───────────────────────────
             not for public distribution
         Copyright (c) 1987, 1988, 1989 Dave Williams


               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 Guides ............................................ 4**
DOS Registers ......................................................... 4**1
DOS Stacks ............................................................ 4**2
DOS Interrupts ........................................................ 4**3
Interrupt 20h (Terminate) ............................................. 4**4
DOS Services (quick list) ............................................. 4**5
Calling the DOS Services .............................................. 4**6
Version Specific Information .......................................... 4**7
DOS Services in Detail ................................................ 4**8


General Programming Guides ............................................ 4**

 Microsoft recommends avoiding the "old style" (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 Window. Such
environments or OS simulations do not always implement the undocumented calls.

 DOS 2.x lacks many of the enhancements found in later versions. Your
application should check the DOS version if DOS 3.x+ features are required.

 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.

                                    -73-


DOS Registers ......................................................... 4**1

 DOS uses the following registers, pointers, and flags when it executes
interrupts and function calls:

┌───────────────────┬──────────┬───────────────────────────────────────────────┐
│GENERAL REGISTERS  │ register │          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)       │
├───────────────────┼──────────┼───────────────────────────────────────────────┤
│SEGMENT REGISTERS  │ register │          definition               │
│            ├──────────┼───────────────────────────────────────────────┤
│            │     CS    │  code    segment (16 bit)               │
│            │     DS    │  data    segment (16 bit)               │
│            │     SS    │  stack segment (16 bit)               │
│            │     ES    │  extra segment (16 bit)               │
├───────────────────┼──────────┼───────────────────────────────────────────────┤
│INDEX REGISTERS    │ register │          definition               │
│            ├──────────┼───────────────────────────────────────────────┤
│            │     DI    │  destination index (16 bit)               │
│            │     SI    │  source      index (16 bit)               │
├───────────────────┼──────────┼───────────────────────────────────────────────┤
│POINTERS        │ register │          definition               │
│            ├──────────┼───────────────────────────────────────────────┤
│            │     SP    │  stack       pointer (16 bit)               │
│            │     BP    │  base          pointer (16 bit)               │
│            │     IP    │  instruction pointer (16 bit)               │
├───────────────────┴──────────┴───────────────────────────────────────────────┤
│FLAGS             AF, CF, DF, IF, OF, PF, SF, TF, ZF               │
└──────────────────────────────────────────────────────────────────────────────┘

 These registers, pointers, and flags are "lowest common denominator" 8088-8086
CPU oriented. DOS makes no attempt to use any of the special or enhanced
instructions availible 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.

                                    -74-


DOS Stacks ............................................................ 4**2

 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 seems to happen usually on
a network. STACKS=16,256 means allow 16 interrupts to interrupt each other and
allow 256 bytes for each for scratch area. Eight is marginal.

 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.



DOS Interrupts ........................................................ 4**3

 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.

                                    -75-


┌─────────────────────────────────────────────────────────────────────────────┐
│Interrupt 20h    Terminate Current Program                4**4  │
└─────────────────────────────────────────────────────────────────────────────┘
(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.

 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:
    0Ah    Program Terminate
    0Eh    Control-C
    12h    Critical Error
note 1) IBM and Microsoft recommend using int 21 Fn 4Ch. Using int 20 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.



DOS Services (quick list) ............................................. 4**5

┌─────────────────────────────────────────────────────────────────────────────┐
│Interrupt 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

                                    -76-

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

                                    -77-


    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*    network
    5Eh*    network printer
    5Fh*    network redirection
    60h*    parse pathname
    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 Compatibility Box
according to MicroSoft.

                                    -78-


Calling the DOS Services .............................................. 4**6

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

                                    -79-


 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 21 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**7

* 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 availible 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

                                    -80-

DOS Services in Detail ................................................ 4**8


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.

Function  01h      Get Keyboard Input
    Waits for char at STDIN (if nescessary), 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.

                                    -81-


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 ROM BIOS routine (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. 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.


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


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.


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

                                    -82-

Function  07h    Direct Console Input Without Echo    (does not check BREAK)
      Get or wait for char at STDIN, returns char in AL
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.

Function  08h    Console Input Without Echo          (checks BREAK)
      Get or Wait for char at STDIN, return char in AL
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).

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 $ (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.

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 (<Enter> 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.

                                    -83-


     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.


Function  0Bh    Check Standard Input (STDIN) status
      Checks for character availible at STDIN
entry    AH    0Bh
return    AL    0FFh    if a character is availible from STDIN
        00h    if no character is availible 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.


Function  0Ch    Clear Keyboard Buffer & Invoke a Keyboard Function     (FCB)
      Dumps buffer, executes function in AL (01h, 06h, 07h, 08h, 0Ah only)
entry    AH    0Ch
    AL    function number (must be 01h, 06h, 07h, 08h, or 0Ah)
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.


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 Compatibility Box.

                                    -84-

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 nescessarily a valid drive.
     4) For DOS 1.x: 16 logical drives are availible, A-P.
    For DOS 2.x: 63 logical drives are availible. (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
             ie {,], etc.
    For DOS 3.x, 4.x: 26 logical drives are availible, A-Z.
     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 Compatibility Box.

Function  0Fh    Open Disk File                          (FCB)
      Searches current directory for specified filename and place relevant
      information 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+
     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 bug in 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.

                                    -85-


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 4.x.
     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.

                                    -86-


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) Requires Network Access Rights.
     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.


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.

                                    -87-


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.


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.
     5) The two filenames cannot have the same name.
     6) FCB contains new name starting at byte 17h.


Function  18h  Internal to DOS
 *   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 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
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 Compatibility Box.
     7) TOS: $1A SET DISK TRANSFER ADDRESS. Sets up a 44-byte buffer for disk
    operations.

                                    -88-


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.


Function  1Ch    Get File Allocation Table Information for Specific Device
      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.


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.

                                    -89-


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 (undocumented,
    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.

                                    -90-


Function  23h  Get File Size                         (FCB)
     Searches current subdirectory 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+


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
     Sets the address of the code DOS is to perform each time the specified
     interrupt is invoked.
entry    AH    25h
    AL    int 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 Compatibility Box.

                                    -91-


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


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.


Function  28h  Random Block Write to File Specified in FCB
     Similar to 27h (Random Write) except allows multiple files to be read.
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).

                                    -92-

Function  29h  Parse the Command Line for Filename
     Parses a text string into the fields of a File Control Block
entry    AH    29h
    DS:SI    pointer to string to parse
    ES:DI    pointer to memory buffer to fill with unopened FCB
    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 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
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 function cannot be used with filespecs which include a path.
     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 also accepts CX = 4445h and DX = 5351h, i.e. 'DESQ' as valid.
     4) This call is explicitly supported in the OS/2 Compatibility Box.
     5) DOS will accept CH=0 (midnight) as a valid time, but if a file's time
    is set to exactly midnight the time will not be displayed by the DIR
    command. (except DR-DOS)
     6) TOS: $2A GET DATE.

                                    -93-


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 (Multisoft cache) installation check.
    entry    CX=4358h
     6) This call is explicitly supported in the OS/2 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 Compatibility Box.
     4) TOS: GET TIME.

                                       -94-


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 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
return    none
note 1) This is the call invoked by the DOS VERIFY command.
     2) Setting of the verify switch can be obtained by calling call 54h.
     3) This call is not supported on network drives.
     4) DOS checks this flag each time it accesses a disk.
     5) This call is explicitly supported in the OS/2 Compatibility Box.


Function  2Fh  Get Disk Transfer Address (DTA)
     Returns current disk transfer address 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 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
return    AH    minor version number  (i.e., DOS 2.10 returns AX = 0A02h)
    AL    major version number  (0 for DOS 1.x)
    BH    OEM ID number
        00h    IBM
        16h    DEC    (others not known)
    BL:CX    24-bit user serial number
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) OS/2 v1.0 Compatibility Box returns a value of 10 for major version.
     4) Due to the OS/2 return and the fact that some European versions of DOS
    carry 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.
     5) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     6) TOS: $30 GET VERSION NUMBER. Returns GEMDOS version number in D0.

                                    -95-


Function  31h  Terminate Process and Stay Resident
     KEEP, or TSR
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.


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    00h    if drive is valid
        0FFh    if drive is not valid
    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 │ largest sector number in cluster (one less than
          │        │      │ sectors per cluster)
          │ 05h    │ byte │ Cluster to sector shift (i.e., how far to shift-
          │        │      │ left the bytes/sector to get bytes/cluster)
          │ 06h-07h│ word │ Number of reserved (boot) sectors
          │ 08h    │ byte │ Number of copies of the FAT
          │ 09h-0Ah│ word │ Number of root directory entries
          │ 0Bh-0Ch│ word │ Sector # of 1st data. Should be same as # of
          │        │      │ sectors/track.
          │ 0Dh-0Eh│ word │ largest possible cluster number (one more than
          │        │      │ the number of data clusters)
          ├────────┴──────┼────────────────────────────────────────────────
          │ 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
          │        │      │ (DOS 3.x) 00h indicates block device has
          │        │      │ been accessed
          │ 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
          │ 22h    │ byte │ Current Working Directory (2.0 only) (64 bytes)
          └────────┴──────┴────────────────────────────────────────────────

                                    -96-

          ┌───────────────┬────────────────────────────────────────────────
          │    DOS 3.x    │
          ├────────┬──────┼────────────────────────────────────────────────
          │ 0Fh    │ byte │ number of sectors in one FAT copy
          │ 10h    │ word │ first sector of root directory
          │ 12h    │dword │ 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    │dword │ address of next device block, offset = 0FFFFh
          │        │      │ indicates last
          │ 1Ch    │ word │ cluster at which to start search for free space
          │        │      │ when writing
          │ 1Ch    │ word │ 00h, probably unused, values left from before
          │ 1Eh    │ word │ 0FFFFh indicates block was built
          ├────────┴──────┼────────────────────────────────────────────────
          │   DOS 4.0     │
          ├────────┬──────┼────────────────────────────────────────────────
          │ 0Fh    │ word │ number of sectors in one FAT copy
          │ 11h    │ word │ first sector of root directory
          │ 13h    │dword │ address of device driver for this drive
          │ 17h    │ byte │ media descriptor byte for medium
          │ 18h    │ byte │ 0FFh = block must be rebuilt, 00h indicates
          │        │      │ block accessed
          │ 19h    │dword │ address of next device block, offset = 0FFFFh
          │        │      │ indicates last
          │ 1Dh    │ word │ cluster at which to start search for free space
          │        │      │ when writing
          │ 1Fh    │ word │ unknown
          └────────┴──────┴────────────────────────────────────────────────
note 1) Use [BX+0D] 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, and the article
    "Finding Disk Parameters" in the May 1986 issue of PC Tech Journal.
     3) 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.
     4) Used by CHKDSK.
     5) Some information from the article "Finding Disk Parameters" in the May
    1986 issue of PC Tech Journal.


Function  33h  Control-Break Check
     Get or set control-break checking at CON
entry    AH    33h
    AL    00h    to test for break checking
        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
        05h    boot drive (DOS 4.0+)
return    DL    break setting (AL=00h)
        00h    if break=off
        01h    if break=on
        (if AL=05h) boot drive, A=1, B=2, etc)
    AL    0FFh    error
note    This call is explicitly supported by the OS/2 DOS Compatibility Box.

                                    -97-


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) The byte at ES:BX+1 is used by the Print program for this same purpose,
    so it's probably safer to check the WORD at ES:BX.
     3) Reportedly, examination of DOS 2.10 code in this area indicates that the
    byte immediately following this "critical section flag" must be 00h to
    permit the PRINT.COM interrupt to be called. For DOS 3.0 and 3.1 (except
    Compaq DOS 3.0), the byte before the "critical section flag" must be
    zero; for Compaq DOS 3.0, the byte 01AAh before it must be zero.
     4) In DOS 3.10 this reportedly changed to word value, with preceding byte.
     5) This call is supported in OS/2 1.0's DOS Compatibility Box.
     6) Gordon Letwin of Microsoft discussed this call on ARPAnet in 1984. He
    stated:
    a) this is not supported under any version of the DOS
    b) it usually works under DOS 2, but there may be circumstances
       when it doesn't (general disclaimer, don't know of a specific
       circumstance)
    c) it will usually not work under DOS 3 and DOS 3.1; the DOS is
       considerably restructured and this flag takes on additional
       meanings and uses
    d) it will fail catastrophically under DOS 4.0 and forward.
    ** Obviously this information is incorrect since the call works fine
       through DOS 3.3. Microsoft glasnost? It also obviously works in US
       DOS 4.0, but it is likely Letwin was referring to what is now known
       as OS/2. Nobody has reported any additional meanings and uses so
       far, though arrangements of bits in the In_DOS byte would be able
       to reflect many more uses.
     7) This call is documented in some Zenith MS-DOS Technical References.
    It was also discussed by Microsoft in their proposed TSR standard
    documentation, so although IBM chose not to support it this call can
    hardly be considered "undocumented."
     8) PC Magazine reports it functions reliably under DOS versions 2.0
    through 3.3. Chris Dunford (of CED fame) and a number of anonymous
    messages on the BBSs indicate it may not be totally reliable.


Function  35h  Get 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 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 availible clusters
    CX    bytes per sector
    DX    clusters per drive

                                    -98-

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 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.
     6) SWITCHAR may not be set to any character used in a filename.
     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 support in the OS/2 compatibility box.

                                    -99-


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 currency symbol null terminated
      byte    07h    thousands separator null terminated
      byte    08h    byte of zeroes
      byte    09h    decimal separator null terminated
      byte    0Ah    byte of zeroes
      byte    0Bh    date separator null terminated
      byte    0Ch    byte of zeroes
      byte    0Dh    time separator null terminated
      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    set if currency symbol replaces decimal point
             3-7    not defined by Microsoft

                                    -100-

      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)
            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 availible
    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
     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 DOS Compatibility Box.


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
    039    Italy
    041    Switzerland
    033    France
    351    Portugal
    002    Canada
    758    Middle East
    001    USA
    972    Israel
    046    Sweden
    358    Finland
    047    Norway
    032    Belgium
    003    S. America
    044    U.K.

                                    -101-

    049    Germany
    034    Spain
    045    Denmark
    031    Netherlands
    081    Japan
     2) The documentation for COUNTRY= will tell you which codes are valid
    for your particular DOS version.


Function  39h    Create Subdirectory (MKDIR)
        Makes a subdirectory along the indicated path
entry    AH    39h
    DS:DX    address of ASCIIZ pathname string
return    flag CF 0    successful
        1    error
            AX    error code if any  (03h, 05h)
note 1) The ASCIIZ string contains the drive and subdirectory.
     2) Drive may be any valid drive (not nescessarily current drive).
     3) The pathname cannot exceed 64 characters.
     4) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     5) The characters [, ] , =, and " may not be used in subdirectory names.
     6) TOS: $39 MKDIR.


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  (3, 5, 16)
note 1) The ASCIIZ string contains the drive and subdirectory.
     2) Drive may be any valid drive (not nescessarily current drive).
     3) The pathname cannot exceed 64 characters.
     4) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     5) TOS: $3A RMDIR.


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.
     2) The ASCIIZ string may contain drive and subdirectory.
     3) Drive may be any valid drive (not nescessarily current drive).
     4) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     5) TOS: $3B CHDIR.


Function  3Ch    Create A File (CREAT)
        Create a file with handle
entry    AH    3Ch
    CX    byte, attributes for file
        00h    normal
        01h    read only
        02h    hidden
        03h    system
    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)

                                    -102-

note 1) The ASCIIZ string may contain drive and subdirectory.
     2) Drive may be any valid drive (not nescessarily 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) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     8) TOS: $3C CREAT.


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
        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
        3    reserved, should be set to zero
        4-6    sharing mode (network)
            000    compatibility mode (the way FCBs open files)
            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 pathname string
return    CF set on error
        AX    error code (01h, 02h, 03h, 04h, 05h, 0Ch)
    AX    16 bit file handle
note 1) Opens any normal, system, or hidden file.
     2) Files that end in a colon are not opened.
     3) The rear/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 DOS Compatibility Box.
     7) TOS: $3D OPEN.

                                    -103-

Function  3Eh    Close A File Handle
        Close a file and release handle for reuse
entry    AH    3Eh
    BX    file handle
return    flag CF 0    successful close
        1    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 current.
     2) If called with the handle 00000h, it will close STDIN (normally the
    keyboard).
     3) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     4) TOS: $3E CLOSE.


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 0    successful read
        1    error
    AX    0    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
    If AX < CX a partial record was 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 DOS Compatibility Box.
     6) TOS: $3F READ.


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    flag CF 0    successful write
        1    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 DOS Compatibility Box.
     8) TOS: $40 WRITE.

                                    -104-

Function  41h    Delete A File From A Specified Subdirectory  (UNLINK)
entry    AH    41h
    DS:DX    pointer to ASCIIZ filespec to delete
return    CF    0    successful
        1    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 DOS Compatibility Box.
     5) TOS: $41 UNLINK.


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 in bytes
return    AX:AX    new file pointer
    CF    0    successful move
        1    error
        AX    error code (01h, 06h)
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 DOS Compatibility Box.
     4) TOS: $42 LSEEK.


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    pointer to full ASCIIZ file name
return    CF    set if error
    AX    error code  (01h, 02h, 03h, 05h)
    CX    file attributes on get
        attributes:
        01h    read only
        02h    hidden
        04h    system
        0FFh    archive
note 1) This call will not change the volume label or directory bits. (3&4)
     2) Any combination of file attributes may be used.
     3) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     4) TOS: $43 CHANGE MODE (CHMOD).

                                    -105-

Function  44h    I/O Control for Devices (IOCTL)
        Device driver handler
entry    AH    44h
    AL    00h    Get Device Information
            BX    file or device handle
            return    CF    set on error
                    AX    error code
                DX    device info word
                    bit 7 set = character device
                    bit 0    console input device
                    1    console output device
                    2    NUL device
                    3    CLOCK$ device
                    4    device is special
                    5    binary (raw) mode
                    6    not EOF
                    12    network device (DOS 3.x)
                    14    can process IOCTL control
                        strings (subfns 2-5)
                    bit 7 clear = file
                    bit 0-5    block device number
                    6    file has not been written
                    12    network device (DOS 3.x)
                    14    unknown        (DOS 3.x)
                    15    file is remote (DOS 3.x)

        01h    Set Device Information
            BX    device handle
            DH    0   (DH must be zero for this call)
            DL    device info to set (bits 0-7 from function 0)
        note    DX bits:
            0    1    console input device
            1    1    console output device
            2    1    null device
            3    1    clock device
            4    1    reserved
            5    0    binary mode - don't check for control chars
                 1    cooked mode - check for control chars
            6    0    EOF - End Of File on input
            7    device is character device if set, if not, EOF
                is 0 if channel has been written, bits 0-5 are
                block device number
            12    network device
            14   1    can process control strings (AL 2-5, can only be
                read, cannot be set)
            15   n    reserved

        02h    Read Character Device Control String
            BX    device handle
            CX    number of bytes to read
            DS:DX    pointer to control string buffer
            return    AX    (no errors) number of bytes read

        03h    Write Character Device Control String
            BX    device handle
            CX    number of bytes to write
            DS:DX    pointer to buffer
            return    AX    (no errors) number of bytes written

        04h    Read From Block Device (drive number in BL)
            BL    drive number (0=default)
            CX    number of bytes to read
            DS:DX    pointer to buffer
            return    AX    (no errors) number of bytes read

                                    -106-

        05h    Write Block Device Control String
            BL    drive number (0=default)
            CX    number of bytes to write
            DS:DX    pointer to buffer
            return    AX    (no errors) number of bytes transfered

        06h    Get Input Handle Status
            BX    file or device handle
            return    AL    0FFh    device ready
                    00h    device not ready

        07h    Get Output Handle Status
            BX    file or device handle
            return    AL    00h    not ready
                    0FFh    ready
            note    For DOS 2.x, files are always ready for output.

        08h    Removable Media Bit                (DOS 3.x+)
            BL    drive number (0=default)
            return    AX    00h    device is removable
                    01h    device is nonremovable
                    0Fh    invalid drive specification

        09h    Test whether Local or Network Device        (DOS 3.x+)
            BL    drive number (0=default)
            return    DX    attribute word, bit 12 set if device is
                    remote

        0Ah    Is Handle in BX Local or Remote?        (DOS 3.x+)
            BX    file handle
            return    DX (attrib word) bit 15 set if file is remote
            note 1) If file is remote, Novell Advanced NetWare 2.0
                returns the number of the file server on which
                the handle is located in CX.

        0Bh    Change Sharing Retry Count to DX        (DOS 3.x+)
            CX     delay (default=1)
            DX     retry count (default=3)

        0Ch    General IOCTL (DOS 3.3 [3.2?]) allows a device driver to
            prepare, select, refresh, and query Code Pages
            BX    device handle
            CH    category code
                00h    unknown (DOS 3.3)
                01h    COMn:    (DOS 3.3)
                03h    CON    (DOS 3.3)
                05h    LPTn:
            CL    function
                45h    set iteration count
                4Ah    select code page
                4Ch    start code-page preparation
                4Dh    end code-page preparation
                65h    get iteration count
                6Ah    query selected code page
                6Bh    query prepare list
            DS:DX    pointer to parameter block. Format:
           (for CL=45h) word    number of times output is attempted
                    driver assumes device is busy
       (for CL=4Ah,4Dh,6Ah) word    length of data
                word    code page ID
           (for CL=4Ch) word    flags
                word    length of remainder of parameter block
                word    number of code pages following
                  n words    code page 1,...,N

                                    -107-

           (for CL=6Bh) word    length of following data
                word    number of hardware code pages
                  n words    hardware code pages 1,...,N
                word    number of prepared code pages
                  n words    prepared code pages 1,...,N

        0Dh    Block Device Request                (DOS 3.3+)
            BL    drive number (0=default, 1=A:, etc.)
            CH    category code
                08h    disk drive
            CL    subfunction
                40h    set device parameters
                41h    write logical device track
                42h    format and verify logical device track
                46h    unknown (DOS 4.0+)
                60h    get device parameters
                61h    read logical device track
                62h    verify logical device track
            DS:DX    pointer to parameter block

         (for fns 40h, 60h) byte    special functions
                    bit 0 set if fn to use current BPB, clear
                      if Device BIOS Parameter Block field
                      contains new default BPB
                    1 set if function to use track layout
                      fields only. Must be clear if CL=60h
                    2 set if all sectors in track same size
                      (should be set)
                      3-7 reserved
                byte    device type
                    00h    320k/360k disk
                    01h    1.2M disk
                    02h    720k disk
                    03h    single-density 8-inch disk
                    04h    double-density 8-inch disk
                    05h    hard disk
                    06h    tape drive
                    07h    other type of block device
                word   device attributes
                   bit 0 set if nonremovable media
                       1 set if door lock supported
                       2-15 reserved
                word   number of cylinders
                byte   media type
                       00h    1.2M disk (default)
                       01h    320k/360k disk
                 31 bytes  device BPB (see function 53h)
                word   # of sectors per track (start of track
                       layout field)
             N word pairs: number,size of each sector in track

                These may be defined in a structure such as:
                DeviceParameters      Struc
                   SpecialFunctions   db      ?
                   DeviceType          db      ?
                   DeviceAttributes   dw      ?
                   NumberCylinders    dw      ?
                   MediaType          db      ?
                   DeviceBPB          A_BPB   <>
                   TrackLayout          A_TrackLayout  <>
                DeviceParameters      EndS

                                    -108-


       (for functions 41h, 61h) byte   reserved, must be zero
                word   number of disk head
                word   number of disk cylinder
                word   number of first sector to read/write
                word   number of sectors
                   dword   transfer address
       (for functions 42h, 62h) byte   reserved, must be zero
                word   number of disk head
                word   number of disk cylinder
            note    DOS 4.01 seems to ignore the high byte of the
                number of directory entries in the BPB for
                diskettes.

        0Eh    Get Logical Device Map                (DOS 3.2+)
            Returns the logical drive letter last used to access
            the block device. Used by SUBST, JOIN, etc.
            BL    drive number (0=default)
            return    AL  0    block device has only one logical drive
                assigned 1..n the last letter used to reference
                the device (1=A:,etc)  (1..26 DOS 3.0+)
            note 1) This is not a network-dependent function.
                 2) This call allows you to determine if more than
                one logical drive is assigned to a block
                device. When this call is issued, a drive
                number is passed in BL as input. If the block
                device has more than one logical drive letter
                assigned to it on output a drive number
                corresponding to the last drive letter that
                was used to reference the device is returned
                in AL. If only one drive letter is assigned to
                the device, 0 is returned in AL by this call.

        0Fh    Set Logical Device Map                (DOS 3.2+)
            BL    physical drive number (0=default)
            return    AL    00h    if only 1 drive letter assigned
                        to block device
                    01h...    1=A:, 2=B:,...
            note    Maps logical drives to physical drives, similar
                to DOS's treatment of a single physical floppy
                drive as both A: and B:

    BL    drive number:  0=default, 1=A:, 2=B:, etc.
    BX    file handle
    CX    number of bytes to read or write
    DS:DX    data or buffer
    DX    data
return    AX    number of bytes transferred
        or error code (call function 59h for extended error codes)
        or status  00h       not ready
               0FFh    ready
    CF    set if error
note    This call is explicitly supported by the OS/2 DOS Compatibility Box.


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 pointed of one handle, 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 DOS Compatibility Box.
     4) TOS: $45 DUP.

                                    -109-


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 read/write pointer of either file, both will move.
     3) The handle in BX must be open.
     4) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     5) TOS $46 FORCE.


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    pointer to 64-byte buffer area
return    CF    clear    DS:DI    pointer to ASCIIZ pathname of 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 DOS Compatibility Box.
     3) TOS: $47 GETDIR.


Function  48h    Allocate Memory
        Allocates 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 availible only if allocation fails.
     2) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     3) TOS: $48 MALLOC.


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 DOS Compatibility Box.
     4) TOS: $49 MFREE.


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    max number paragraphs available
note 1) Max number paragraphs availible is returned only if the call fails.
     2) Memory can be expanded only if there is memory availible.
     3) This call is explicitly supported by the OS/2 DOS Compatibility Box.
     4) TOS: $4A SETBLOCK.

                                    -110-


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.
           *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)
    DS:DX    points to the ASCIIZ string with the drive, path, and filename
        to be loaded
    ES:BX    points 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, 02h, 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
        up) 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 availible.

                                    -111-


    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 gotten 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 MSDOS
    the EXEC system call lives in system space.
    10) If you try to overlay an .EXE file with the high/low switch set to load
    the in high 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.

                                    -112-

    13) This call is explicitly supported by the OS/2 DOS Compatibility Box.
    14) TOS: $4B EXEC.


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, 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 DOS Compatibility Box.
     6) TOS: $4C TERM. Returns 2-byte errorlevel to calling program


Function  4Dh    Get Return Code of a Subprocess (WAIT)
        Gets return code from functions 31h and 4Dh  (ERRORLEVEL)
entry    AH    4Dh
return    AL    exit code of subprogram (functions 31h or 4Ch)
    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)
note 1)  The exit code is only returned once (the first time).
     2) This call is explicitly supported in the OS/2 DOS Compatibility Box.


Function  4Eh    Find First Matching File (FIND FIRST)
entry    AH    4Eh
    CX    search attributes  (see function 43h)
    DS:DX    pointer to ASCIIZ filename (with attributes)
return    CF    set    AX    error code (02h, 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

                                    -113-

             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 DOS Compatibility Box.
     6) TOS: $4E SFIRST.


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
    often 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 DOS Compatibility Box.
     6) TOS: $4F SNEXT.


Function  50h    "Used Internally by DOS" - Set PSP
 *        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)
     4) Under DOS 2.x, this function cannot be invoked inside an int 28h handler
    without setting the Critical Error flag.

                                    -114-

     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 BCOPY.ASM
     7) Used by DOS 3.3 PRINT & DEBUG, DesQview 2.01, Windows 1.03, SYMDEB
    from MASM 4.0.
     8) This call is availible in the OS/2 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 GetPID
    (0x50) to 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 SetPID (0x51) 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    "Used Internally by DOS" - Get Program Segment Prefix
 *        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 cmdline argument
        6Ch 20 bytes    FCB #2, filled in from second cmdline 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)
     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 51h to save 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) Used by DOS 3.3 PRINT, DEBUG.
     6) This call is availible in the OS/2 DOS Compatibility Box.

                                    -115-

Function  52h    "Used Internally by DOS" - IN-VARS
 *        Returns a FAR pointer to a linked list of DOS data variables
entry    AH    52h
return    ES:BX    pointer to the DOS list of lists, for disk information. Does not
        access the disk, so information in tables might be incorrect if
        disk has been changed. Returns a pointer to the following array
        of longword pointers:
        bytes    value        description
(common)    -2h,    word    segment of first memory control block available
                through MALLOC
        00h    dword    far pointer to first DOS Disk Parameter Block
        04h    dword    far pointer to linked list of DOS open file
                tables. (Open File Table List)
        08h    dword    far pointer to CLOCK$: device driver, whether
                installable or resident
        0Ch    dword    far pointer to actual CON: device driver,
                whether installable or resident

    (DOS 2.x only)
        10h    word    number of logical drives in system
        11h    word    largest logical sector size supported
        13h    dword    far pointer to first disk buffer used by the
                logical drives. The size of each sector buffer
                is equal to the logical sector size plus a 16
                byte header. (Sector Buffer Header) The number
                of these buffers is set by CONFIG.SYS. (Sector
                Buffer Structure)
        17h    ----    beginning (not a pointer. The real beginning!)
                of NUL device driver. This is the first device
                on DOS's linked list of device drivers.

    (DOS 3.x+)
        10h    word    largest logical sector sector size supported
                (most versions of DOS are hardcoded to 200h)
        12h    dword    far pointer to sector buffer structure used by
                the logical drives. (Sector Buffer Structure)
        16h    dword    far pointer to drive path and seek information
                table. (Drive Path Table)
        1Ah    dword    far pointer to a table of FCBs. This table is
                only valid if FCBS=xx was used in CONFIG.SYS
        1Eh    word    size of FCB table
        20h    byte    number of logical drives presently supported
        21h    byte    value of LASTDRIVE= in CONFIG.SYS (default 5)
        22h    ----    beginning (not a pointer-the real beginning!)
                of the NUL device driver. This is the first
                device on DOS's linked list of device drivers.
        34h    (?)    number of JOINed drives?

note 1) This call is not supported in OS/2 1.0's DOS Compatibility Box.
     2) Used by DOS 4.0 MEM.EXE, DOS 3.3 ASSIGN.COM, PRINT.COM, SUBST.EXE.
     3) Article in Dr. Dobbs' Journal, June 1989.
     4) Disk Parameter Block
    offset    size    description
    00h    byte    disk unit number, 0=A, 1=B, etc. If this and the next
            byte are 0FFh this entry is the end of the list and
            is not valid
    01h    byte    disk unit number passed to the block device driver
            responsible for this logical drive
    02h    word    the drive's logical sector size in bytes
    04h    byte    number of sectors per cluster -1. The number of sectors
            per cluster must be a power of 2
    05h    byte    allocation shift. The shift value used to calculate
            the number of sectors from the number of clusters
            without having to use division. Number of sectors =
            number of clusters << allocation shift.

                                    -116-

    06h    word    number of reserved sectors at the beginning of the
            logical drive. May contain partition information.
    08h    byte    number of FATs. Default 2
    09h    word    number of root directory entries
    0Bh    word    first sector containing data (disk files)
    0Dh    word    last cluster number. Number of clusters in data area
            +1. If less than 0FF6h the FAT uses 12-bit directory
            entries, otherwise 16 bit entries
    0Fh    byte    FAT size. Size of one FAT in logical sectors
    10h    word    sector number of first root directory entry
    12h    dword    far pointer to the block device driver
    16h    byte    media descriptor byte (see Chapter 8)
    17h    byte    media flag. If this is 0, the drive has been accessed.
            If it is -1 or set to -1 DOS will rebuild all data
            structures associated with this drive on the next
            access
    18h    dword    far pointer to the next Disk Parameter Block

     5) Open File Table List
    offset    size    description
    00h    dword    far pointer to the next table in the list. If the
            offset of this pointer is 0FFFFh, then the next table
            is the final entry and invalid
    04h    word    number of table entries. Each table entry is 53 bytes
            long. There will be at least one entry in each table
            except the terminal entry
    06h    ---    beginning of the Open File Table entries (note 6)

     6) Open File Table Entry (35h bytes long)
    offset    size    description
    00h    word    number of file handles referring to this file
    02h    byte    access mode (see function 3Dh)
    03h        unknown
    05h    word    device info word (see function 44h/00h)
    06h    dword    far pointer to device info header if this is a char-
            acter device. If block device, this will be a far
            pointer to the Disk Parameter Block
    07h    dword    pointer to device driver header if character device;
            pointer to DOS Device Control Block if block device
            (see fn 32h for format)
    0Bh    word    starting cluster of file
    0Dh    word    file time in packed format
    0Fh    word    file date in packed format
    11h    dword    file size
    15h    dword    current offset in file
    19h    word    unknown
    1Bh    word    last cluster read
    1Dh    word    number of sector containing directory entry
    1Fh    byte    offset of directory entry within sector (byte offset/32)
    20h  11 bytes    filename in FCB format (no path, no period, blank
            padded)
    2Bh   6 bytes    PSP segment of file's owner
    2Dh   3 bytes    unknown - normally 0
    31h    word    PSP segment of file's owner
    33h-34h     unknown - normally 0

     7) Sector Buffer Header:     (DOS 2.x+)
    offset    size    description
    00h    dword    pointer to next disk buffer, FFFFh if last
    04h   4 bytes    unknown
    08h    word    logical sector number
    10h   2 bytes    unknown
    12h    dword    pointer to DOS Device Control Block (see function 32h)

                                    -117-

     8) Sector Buffer Structure, followed by 512 byte buffer
    offset    size    description
    00h    dword    far pointer to the next sector buffer. Buffers are
            filled in the order of their appearance on this
            linked list. The last buffer is valid and has the value
            0FFFFFFFFh
    04h    byte    drive number. This is the drive that the data currently
            in the buffer refers to. 0FFh if never used.
    05h    byte    data type flags. Bit fields which area of the drive
            the buffer refers to.
            bit    description
            0
            1    FAT data
            2    directory or subdirectory data
            3    file data
            4
            5    contents of buffer may be overwritten if set
            6
            7
    06h    word    logical sector number of buffered data
    08h    word    access number
    0Ah    dword    far pointer to Disk Parameter Block (see fn 32h)
    0Eh    word    not used, normally 0

     9) Drive Path Table Entry     (array, one 51h-byte entry per drive):
    offset    size    description
    00h  64 bytes    current default ASCIIZ pathname with drive letter,
            colon, and leading backslash
    44h    byte    flags byte. All valid entries contain a 40h, last
            entry contains 00h.
           bits 15    network drive
            14    physical drive
            13    JOINed, current path is actual path without
                JOIN drive letter in path may differ from
                logical drive name
            12    SUBSTed, current path is actual path without
                SUBST drive letter in path may differ from
                logical drive name
    45h    dword    far pointer to current Disk Parameter Block
    49h    word    current block or track/sector number for this directory
            0 if root dir, -1 if never accessed
    4Bh    dword    unknown. Far pointer to (?). Usually -1
    4Fh    word    offset of '\' in current path field representing root
            directory of logical drive (2 if not SUBSTed or JOINed,
            otherwise number of bytes in SUBST/JOIN path)


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
        08h-09h word  total number of sectors, get from:
                  ((DDB bytes 0Dh-0Eh) - 1) * (sectors per cluster
                  (BPB byte 2)) + (DDB bytes 0Bh-0Ch)

                                    -118-

        0Ah    word  media descriptor byte, get from DDB byte 16h
                  for DOS 4.0+, set to 0 if partition >32Mb, then
                  set dword at 15h to actual number of sectors
        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 DOS Compatibility Box.


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) Global 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 DOS Compatibility Box.
     6) TOS: $56 RENAME. Similar to MS-DOS 2.x.

                                    -119-


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)    DX bits 09h-0Fh year (relative to 1980)
        05h-0Ah minutes (0-59)        05h-08h month (0-12)
        00h-04h #2 sec. incr. (0-29)    00h-04h day of the month (0-31)
     2) This call is explicitly supported in the OS/2 DOS Compatibility Box.
     3) TOS: $57 GSDTOF.


Function  58h    Get/Set Allocation Strategy   (DOS 3.x+)
entry    AH    58h
    AL    00h    Get Current Strategy
        01h    Set New Current Strategy
    BL    new strategy if AH=1
        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.
return    CF    clear    (0)    successful
        set    (1)    error
                AX    error code (01h)
    AX    strategy code (CF=0)
note 1) Documented in Zenith DOS version 3.1, some in Advanced MSDOS.
     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).


Function  59h    Get Extended Error Code (DOS 3.x+)
      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.

                                    -120-

       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.
entry    AH    59h
    BX    version code (0000 for DOS 3.0 and 3.1)
return    AX    extended error code:
        01h    Invalid function number
        02h    File not found
        03h    Path not found
        04h    Too many open files, no file handles left
        05h    Access denied
        06h    Invalid handle
        07h    Memory control blocks destroyed
        08h    Insufficient memory
        09h    Invalid memory block address
        0Ah    Invalid environment
        0Bh    Invalid format
        0Ch    Invalid access code
        0Dh    Invalid data
        0Eh    Reserved
        0Fh    Invalid drive was specified
        10h    Attempt to remove the current directory
        11h    Not same device
        12h    No more files
        13h    Attempt to write on write-protected diskette
        14h    Unknown unit
        15h    Drive not ready
        16h    Unknown command
        17h    Bad CRC check
        18h    Bad request structure length
        19h    Seek error
        1Ah    Unknown media type
        1Bh    Sector not found
        1Ch    Printer out of paper
        1Dh    Write fault
        1Eh    Read fault
        1Fh    General Failure
        20h    Sharing violation
        21h    Lock violation
        22h    Invalid disk change
        23h    FCB unavailible
        24h    Sharing buffer overflow
        25h    Reserved
        26h       "
        27h       "
        28h       "
        29h       "

                                    -121-

        2Ah       "
        2Bh       "
        2Ch       "
        2Dh       "
        2Eh       "
        2Fh       "
        30h       "
        31h    Reserved
        32h    Network: request not supported (DOS 3.1 + MS Networks)
        33h    Remote computer not listening
        34h    Duplicate name on network
        35h    Network: name not found
        36h    Network: busy
        37h    Network: device no longer exists
        38h    NETBIOS command limit exceeded
        39h    Network: adapter hardware error
        3Ah    Incorrect response from network
        3Bh    Unexpected network error
        3Ch    Incompatible remote adapter
        3Dh    Print queue full
        3Eh    Not enough space for print file
        3Fh    Print file was deleted
        40h    Network: name was deleted
        41h    Network: Access denied
        42h    Network: device type incorrect
        43h    Network: name not found
        44h    Network: name limit exceeded
        45h    NETBIOS session limit exceeded
        46h    Temporarily paused
        47h    Network: request not accepted
        48h    Print or disk redirection paused (DOS 3.1 + MS Networks)
        49h    Reserved
        4Ah       "
        4Bh       "
        4Ch       "
        4Dh       "
        4Eh       "
        4Fh    Reserved
        50h    File exists
        51h    Reserved
        52h    Cannot make directory entry
        53h    Fail on interrupt 24h
        54h    Too many redirections
        55h    Duplicate redirection
        56h    Invalid password
        57h    Invalid parameter
        58h    Network: device fault
    BH    class of error:
        01h    Out of resource
        02h    Temporary situation
        03h    Authorization (denied access)
        04h    Internal
        05h    Hardware failure
        06h    System failure
        07h    Application program error
        08h    Not found
        09h    Bad format
        0Ah    Locked
        0Bh    Media error (wrong volume ID, disk failure)
        0Ch    Already exists
        0Dh    Unknown

                                    -122-

    BL    suggested action code:
        01h    Retry
        02h    Delayed retry
        03h    Prompt user
        04h    Abort after cleanup
        05h    Immediate abort
        06h    Ignore
        07h    Retry after user intervention
    CH    locus (where error occurred):
        01h    Unknown or not appropriate
        02h    Block device
        03h    Network related
        04h    Serial device
        05h    Memory related
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 DOS Compatibility Box.




Function  5Ah    Create Temporary File
        Create unique filename (for temporary use) (DOS 3.x+)
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
return    CF    clear    DS:DX    new ASCIIZ pathname
            AX    handle
        set    AX    error code (03h, 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 unique filename is found.
     3) The temporary filename usually consists of mixed letters and numbers.
    No file extension appears to be generated.
     4) This call is explicitly supported in the OS/2 DOS Compatibility Box.

                                    -123-


Function  5Bh    Create a New File   (DOS 3.x+)
entry    AH    5Bh
    DS:DX    pointer to an ASCIIZ pathname
    CX    file attribute
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.
     2) The new file is opened in read/write mode.
     3) This call is explicitly supported in the OS/2 DOS Compatibility Box.


Function  5Ch    Lock/Unlock File Access   (DOS 3.x+)
entry    AH    5Ch
    AL    00h    To lock file region
        01h    To unlock file region
    BX    file handle
    CX:DX    starting offset of region to lock
    SI:DI    size of region    to lock
return    CF    clear    successful
        set    AX    error code (01h, 06h, 21h)
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 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.
     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.


Function  5Dh    undocumented - 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-05h Network functions? (DOS 3.1+)
            parameters unknown
            note    Error unless network is loaded.
        06h    Get Address of Critical Error Flag
            return    CX    unknown value
                DX    unknown value
                DS:SI    pointer to critical error flag

                                    -124-

    (LANtastic) 07h    Return redirected printer mode
            return    DL    00    output is being combined
                    01h    output is being separated
            note    The current printer mode (either printer output
                combined or separated) is returned.
    (LANtastic) 08h    Set redirected printer mode (either printer output
            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 flush
                then this function has no effect.
                 2) may be used by COMMAND.COM
        09h    unknown - may be used by COMMAND.COM
        0Ah    Set Error Info (Error, Class, Action, and Locus)
            DS:DX    address of 11-word error information table
                words 0 to 7: values of AX,BX,CX,DX,SI,DI,DS,
                          ES that function 59h will return
                words 8 to 10: zero (reserved)
return    CX    unknown value
    DX    unknown value
    DS:SI    (for 06h) pointer to critical error flag
note 1) This call seems to have many different functions.
     2) Function 0Ah; DOS 3.1+.
     3) 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.
     4) Functions 07h, 08h, 09h are identical in DOS 3.1 and call int 2Fh
    fn1125h.



Function  5Eh    Network Printer  (Partially documented by Microsoft)
        DOS 3.1+ with Networks software
entry    AH    5Eh
    AL    00h    Get Machine Name
            DS:DX    pointer to 16-byte buffer for ASCIIZ name
            return    CH    0    if name not defined
                CL    NETBIOS name number if CH <> 0
                DS:DX    pointer to identifier if CH <> 0
            note    The ASCIIZ name is a 15 byte string padded
                to length with zeroes.
        01h    Set Machine Name
            DS:DX    pointer to ASCIIZ name
            CH    unknown, must be nonzero
            CL    name number
        02h    Set Printer Control String
            BX    redirection list index
            CX    length of setup string (max 64 bytes)
            DS:SI    pointer to string buffer
        03h    Get Printer Control String
            BX    redirection list index
            ES:DI    pointer to 64-byte string buffer
            return    CX    length of setup string (max 64 bytes)
return    CF    clear    successful
        set    error
            AX    error code (01h for all listed subfunctions)

                                    -125-

note 1) Used in IBM's & Microsoft's Network programs.
     2) Partial documentation in Fall 1985 Byte.
     3) These services require that the network software be installed.
     4) Partial documentation in Advanced MS-DOS.
     5) SHARE must be loaded or results can be unpredictable on 00h, or fail
    with 02h or 03h.


Function  5Fh    Network Redirection
        (DOS 3.1 + Microsoft Networks)
entry    AH    5Fh
    AL     *00h    Unknown
           *01h    Unknown
        02h    Get Redirection List Entry
            BX    redirection list index (zero based)
            DS:SI    pointer to 16 byte buffer for local device name
            ES:DI    pointer to 128 byte buffer for network name
            return    BH    device status flag (bit 0=0 if valid)
                               (bit 0=1 if invalid)
                BL    device type
                    03    printer device
                    04    drive device (file)
                CX    stored parameter value (user data)
                DS:SI    pointer to 16 byte local device name
                ES:DI    pointer to 128 byte network name
            note    DX and BP are destroyed by this call.
        03h    Redirect Device - Make Assign List Entry
            Redirects a workstation drive or device to a server
            directory or device.
            BL    device type
                03    printer device
                04    file device
            CX    stored parameter value (0 for compatibility
                with IBM PC Network program)
            DS:SI    pointer to 16-byte ASCIIZ source device name
            ES:DI    pointer to destination 128-byte ASCIIZ network
                path and ASCIIZ password
                (e.g.,'\\machine_name\path',0,'password',0)
        04h    Cancel Redirection Assignment
            DS:SI    pointer to ASCIIZ device name or network path
                to be canceled
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.
     2) Partial documentation in Fall 1985 Byte.
     3) These services require that the network software be installed.
     4) Partial documentation in Advanced MS-DOS.
     5) SHARE must be loaded or the call will fail.
     6) The network device name requires a password.


Function  60h    undocumented - Parse pathname (DOS 3.x+)
 *        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 67 byte (?) ASCIIZ string buffer
return    ES:DI    buffer filled with qualified name in form (drive):(path)
    CF    0    no error
        1    error
            AX    error code (unknown)

                                    -126-

note 1) Documented in Zenith 3.05 Tech Ref.
     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.
     3) Example: If current drive/directory is c:\test,  myfile.x is translated
    to c:\test\myfile.x; ..\source\sample.asm is tranlated 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.


Function  61h    undocumented - (DOS 3.x)
 *        Internal to DOS - parameters not known
entry    AH    61h
return    AL    00h
note    Supposedly documented in Zenith DOS 3.05 Tech Ref.


Function  62h    Get Program Segment Prefix (PSP) (DOS 3.x+)
entry    AH    62h
return    BX    segment address of PSP


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.
     2) Not supported in DOS 3.x or 4.x.
     3) Note fn 63h does not return errors in AL or CF.


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

                                    -127-

        03h    unknown
        04h    get pointer to filename uppercase table (130 bytes max)
            (similar to table for AL = 02h)
        05h    unknown
        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
    BX    code page (0FFFFh = global code page)
    CX    size of buffer (>=5)
    DX    country ID (0FFFFh = current country)
    ES:DI    pointer to country information buffer
return    CF    set on error
        AX    error code (unknown)
            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 info ID <> 1:
        01h    dword  pointer to information
    If info ID = 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 info ID = 2:
        01h    dword    pointer to uppercase table
        05h    word    table size
        128 bytes uppercase equivalents (if any) of chars 80h-0FFh
    If info ID = 4:
        01h    dword    pointer to collating table
        05h    word    table size
        256 bytes    values used to sort characters 00h-0FFh
    If info ID = 6:
        01h    dword    pointer to filename uppercase table
        05h    word    table size
        128 bytes    uppercase equivalents (if any) of chars 80h-0FFh
    If info ID = 7: (DOS 4.0)
        unknown
note    For AL=02h, 04h, or 06h, the first two bytes of the table give its
    length and the rest is the table itself.


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    BX = active code page: 437 = US, 860 = Portugal, 863 = Canada (French)
                   865 = Norway/Denmark, 850 = multilingual


Function  67h    Set Handle Count  (DOS 3.3+)
        Supports more than 20 open files per process
entry    AH    67h
    BX    desired number of handles (max 65,535)
return    CF    clear if OK
    CF    set if error
        AX    error code (unknown)

                                    -128-

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.


Function  68h    Commit File (DOS 3.3+)
        Write all buffered data to disk
entry    AH    68h
    BX    file handle
return    CF    set    AX    error code
        clear    successful
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) If BX <= 20, no action is taken.
     4) The file's buffers are flushed and its directory and FAT entries are
    updated.


Function  69h    Disk Serial Number  DOS 4.0+ (US versions)
        Handles "Volume Serial Number" on disks formatted with 4.0+
entry    AH    69h    Get Volume Serial Number
    DS:DX    pointer to table
return    DS:DX    data table. Format:
        word     unknown (zeroes on my system)
        dword     disk serial number (binary)
         11 bytes     volume label or "NO NAME    " if none
          8 bytes     FAT type - string "FAT12   " or "FAT16   "
note    The FAT type field refers to the number of bits per directory entry.


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

                                    -129-

    CX    create attribute
    DL    action if file exists/does not exists
       bits 7-4    action if file does not exist
            0000    fail
            0001    create
        3-0    action if file exists
            0000    fail
            0001    open
            0010    replace/open
    DH    00h
    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 exits 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
    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.


Function  0E4h    DoubleDOS - Get active flag
entry    AX    0E4h
return    AL    00h    if DoubleDOS not active
        <>0    DoubleDOS is active


Function  0EAh    DoubleDOS - Turn off task switching
entry    AX    0EAh
return    none
note    Task switching turned off.

                                    -130-


Function  0EBh    DoubleDOS - Turn on task switching
entry    AH    0EBh
return    none
note    Task switching turned on.


Function  0ECh    DoubleDOS -  Get virtual screen address
entry    AH    0ECh
return    ES    segment of virtual screen
note    Screen address can change if task switching is on!


Function  0EEh    DoubleDOS - Release Timeslice
        Give away time to other tasks
entry    AH    0EEh
    AL    number of 55ms time slices to give away
return    none
note    Returns after giving away time slices.


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