The MS-DOS Encyclopedia: Section V: System Calls

Archive of outdated Microsoft articles and reference materials


The MS-DOS Encyclopedia

Section V: System Calls

Introduction


    All versions of MS-DOS include operating-system services that provide
    the programmer with hardware-independent tools for handling such tasks
    as file management, device input and output, memory allocation, and
    getting and setting system-management information such as the date and
    time. The majority of these services, collectively called the MS-DOS
    system calls, are invoked through Interrupt 21H. A few others are
    called using Interrupts 20H through 27H and 2FH. This section includes
    descriptions of these system-management services, with details
    relevant to all releases of MS-DOS through version 3.2.

    Use of the Interrupt 21H system calls, rather than hardware-specific
    routines, helps ensure that a program will run on any computer running
    an appropriate version of MS-DOS. Likewise, because new releases of
    MS-DOS attempt to maintain compatibility with earlier versions, use of
    the calls increases the likelihood that a program will remain usable
    for more than a single major or minor release of the operating system.

    The MS-DOS Interrupt 21H system calls are invoked as follows:

    AH                      = function number
    AL                      = subfunction code (if required)
    Other registers         = additional function-specific information
    Execute Interrupt 21H


Version Differences

    With MS-DOS versions 2.0 and later, considerable overlap occurs in the
    way in which many system services, such as file and character device
    I/O, can be carried out. This overlap is a result of the manner in
    which MS-DOS has developed since it was first released.

    The earliest version of MS-DOS, 1.0, included a relatively small set
    of Interrupt 21H system calls designed primarily for CP/M
    compatibility. These calls, numbered 00H through 2DH, relied on the
    use of file control blocks (FCBs) in an application's memory space for
    information on open files. See PROGRAMMING IN THE MS-DOS ENVIRONMENT:
    PROGRAMMING FOR MS-DOS: File and Record Management; Appendix G: File
    Control Block (FCB) Structure. The FCB-based system calls in MS-DOS do
    not support hierarchical file structures, nor do they support
    redirection of input and output. As a result, many of these system
    calls have been superseded in later releases of MS-DOS. The CP/M-style
    calls are no longer recommended and should not be used unless program
    compatibility with versions 1.x is required.

    Beginning with version 2.0, MS-DOS introduced the concept of handles--
    16-bit numbers returned by the operating system after a successful
    open or create call. The handles can subsequently be used by an
    application program to reference an open file or device, eliminating
    redundancy and unnecessary overhead. These handles are also used
    internally by MS-DOS to keep track of open files and devices. The
    operating system keeps all such handle-related information in its own
    memory space. Handles offer full support for the hierarchical file
    system introduced in version 2.0 of MS-DOS and thus allow the
    programmer to access any file stored in any directory or subdirectory
    on a block device. Because of the increased flexibility offered by the
    handle-related system function calls, these services are recommended
    over the earlier FCB-based calls, which perform similar tasks but for
    the current directory only. See PROGRAMMING IN THE MS-DOS
    ENVIRONMENT: PROGRAMMING FOR MS-DOS: File and Record Management.

    Another advantage of using the system calls introduced in versions 2.0
    and later is that these calls set the carry flag when an operational
    error occurs and return an error code in AX that indicates the nature
    of the error; the error can then be investigated further by calling
    Function 59H (Get Extended Error Information). The earlier system
    calls (00H through 2DH) generally simply return 0FFH (255) in AL to
    indicate an error or 00H to indicate that the call was completed
    successfully.


Format of Entries

    Entries in this section are arranged in hexadecimal order, with
    decimal equivalents in parentheses. Each entry is organized as
    follows:

    ■  Hexadecimal interrupt and/or function number (decimal equivalent in
        parentheses)

    ■  Interrupt or function name (similar to, but not always the same as,
        the name used in MS-DOS documentation)

    ■  Version dependencies

    ■  Interrupt or function purpose

    ■  Register contents needed to call

    ■  Register contents on return

    ■  Notes for programmers

    ■  Related functions

    ■  Program example

    The format of these entries is designed to give programmers ready
    reference to specific information, such as register contents, as well
    as more detailed notes on the use and application of each system call.
    For further information on the use of the system calls, see
    PROGRAMMING IN THE MS-DOS ENVIRONMENT.

    The assembly-language examples in this section use the Cmacros
    capability introduced with the Windows Software Development Kit.
    Cmacros, a set of assembly-language macros defined in the file
    CMACROS.INC, are useful because they provide a simplified interface to
    the function and segment conventions of high-level languages such as
    Microsoft C and Microsoft Pascal.

    Advantages to using Cmacros for assembly-language programming include
    transparent support for memory models and symbolic names for function
    arguments and local variables. Cmacros exist for code and data segment
    declarations (sBegin and sEnd), storage allocation (staticX, globalX,
    externX, and labelX), function declarations (cProc, parmX, localX,
    cBegin and cEnd), function calls (cCall, Save, and Arg), special
    definitions (DefX, RegPtr, and FarPtr), and error control (errnz and
    errn$). Of these, only sBegin, sEnd, cProc, parmX, localX, cBegin, and
    cEnd are used in the examples in this section.

    Two additional macros that support functions not found in CMACROS.INC
    are loadCP and loadDP. These macros, included in the file
    CMACROSX.INC listed below, allow pointers previously declared with
    staticX, globalX, parmX, DefX and localX to be loaded into registers
    without regard to the memory model in use--loadCP and loadDP
    generate code to load either the offset portion or the full
    segment:offset of the address, depending on the memory model.

;       CMACROSX.INC
;
;       This file includes supplemental macros for two macros included
;       in CMACROS.INC: parmCP and parmDP. When these macros are used,
;       CMACROS.INC allocates either 1 or 2 words to the variables
;       associated with these macros, depending on the memory model in
;       use. However, parmCP and parmDP provide no support for automatically
;       adjusting for different memory models--additional program code
;       needs to be written to compensate for this. The loadCP and loadDP
;       macros included in this file can be used to provide additional
;       flexibility for overcoming this limit.

;       For example, "parmDP pointer" will make space (1 word in small
;       and middle models and 2 words in compact, large, and huge models)
;       for the data pointer named "pointer". The statement
;       "loadDP ds,bx,pointer" can then be used to dynamically place the
;       value of "pointer" into DS:BX, depending on the memory model.
;       In small-model programs, this macro would generate the instruction
;       "mov dx,pointer" (it is assumed that DS already has the right
;       segment value); in large-model programs, this macro would generate
;       the statements "mov ds,SEG_pointer" and "mov dx,OFF_pointer".

checkDS macro        segmt
        diffcount = 0
        irp d,<ds,DS,Ds,dS>                  ; Allow for all spellings
            ifdif <segmt>,<d>                 ; of "ds".
                diffcount = diffcount+1
            endif
        endm
        if diffcount EQ 4
            it_is_DS = 0
        else
            it_is_DS = 1
        endif
        endm

checkES macro        segmt
        diffcount = 0
        irp d,<es,ES,Es,eS>                  ; Allow for all spellings
            ifdif <segmt>,<d>                 ; of "es".
                diffcount = diffcount+1
            endif
        endm
        if diffcount EQ 4
            it_is_ES = 0
        else
            it_is_ES = 1
        endif
        endm

loadDP  macro        segmt,offst,dptr
        checkDS segmt
        if sizeD                             ; <-- Large data model
            if it_is_DS
                lds  offst,dptr
            else
                checkES segmt
                if it_is_ES
                    les  offst,dptr
                else
                    mov  offst,OFF_&dptr
                    mov  segmt,SEG_&dptr
                endif
            endif
        else
            mov  offst,dptr                   ; <-- Small data model
            if it_is_DS EQ 0
                push ds                        ; If "segmt" is not DS,
                pop  segmt                     ; move ds to segmt.
            endif
        endif
        endm

loadCP  macro        segmt,offst,cptr
        if sizeC                             ; <-- Large code model
            checkDS segmt
            if it_is_DS
                lds offst,cptr
            else
                checkES
                if it_is_ES
                    les  offst,cptr
                else
                    mov  segmt,SEG_&cptr
                    mov  offst,OFF_&cptr
                endif
            endif
        else
            push cs                           ; <-- Small code model
            pop  segmt
            mov  offst,cptr
        endif
        endm

The following example program demonstrates the use of Cmacros in an
assembly-language program:

memS    =       0                ;Small memory model
?PLM    =       0                ;C calling conventions
?WIN    =       0                ;Disable Windows support

include cmacros.inc
include cmacrosx.inc

sBegin  CODE                     ;Start of code segment
assumes CS,CODE                  ;Required by MASM

        ;Microsoft C function syntax:
        ;
        ;     int addnums(firstnum, secondnum)
        ;         int firstnum, secondnum;
        ;
        ;Returns firstnum + secondnum

cProc   addnums,PUBLIC           ;Start of addnums functions
parmW   firstnum                 ;Declare parameters
parmW   secondnum
cBegin
        mov     ax,firstnum
        add     ax,secondnum
cEnd
sEnd    CODE
        end

A simple C program to call this function would be

main()
{
        printf("The sum is %d",addnums(12,33));
}


Contents by Functional Group

    Although distinguishing between FCB-based and handle-based system
    calls provides a broad and very generalized means of categorizing
    these services, the more common and useful approach is to group the
    calls by the type of task they perform. The following list groups the
    Interrupt 21H system calls and Interrupts 20H, 22H through 27H, and
    2FH by type of service.

╓┌───────────────────────┌───────────────────────────────────────────────────╖
    Function           Purpose
    ──────────────────────────────────────────────────────────────────
    Character Input
    01H                Character Input with Echo
    03H                Auxiliary Input
    06H                Direct Console I/O
    07H                Unfiltered Character Input Without Echo
    08H                Character Input Without Echo
    0AH                Buffered Keyboard Input
    0BH                Check Keyboard Status
    0CH                Flush Buffer, Read Keyboard

    ──────────────────────────────────────────────────────────────────
    Character Output
    02H                Character Output
    04H                Auxiliary Output
    05H                Print Character
    06H                Direct Console I/O
    09H                Display String

    ──────────────────────────────────────────────────────────────────
    Disk Management
    0DH                Disk Reset
    0EH                Select Disk
    19H                Get Current Disk
    1BH                Get Default Drive Data
    1CH                Get Drive Data
    2EH                Set/Reset Verify Flag
    36H                Get Disk Free Space
    54H                Get Verify Flag

    ──────────────────────────────────────────────────────────────────
    File Management
    0FH                Open File with FCB
    10H                Close File with FCB
    11H                Find First File
    12H                Find Next File
    13H                Delete File
    16H                Create File with FCB
    17H                Rename File
    1AH                Set DTA Address
    23H                Get File Size
    2FH                Get DTA Address
    3CH                Create File with Handle
    3DH                Open File with Handle
    3EH                Close File
    41H                Delete File
    43H                Get/Set File Attributes
    45H                Duplicate File Handle
    46H                Force Duplicate File Handle
    4EH                Find First File
    4FH                Find Next File
    56H                Rename File
    57H                Get/Set Date/Time of File
    5AH                Create Temporary File
    5BH                Create New File
    5CH                Lock/Unlock File Region

    ──────────────────────────────────────────────────────────────────
    Information Management
    14H                Sequential Read
    15H                Sequential Write
    21H                Random Read
    22H                Random Write
    24H                Set Relative Record
    27H                Random Block Read
    28H                Random Block Write
    3FH                Read File or Device
    40H                Write File or Device
    42H                Move File Pointer
    Interrupt 25H      Absolute Disk Read
    Interrupt 26H      Absolute Disk Write

    ──────────────────────────────────────────────────────────────────
    Directory Management
    39H                Create Directory
    3AH                Remove Directory
    3BH                Change Current Directory
    47H                Get Current Directory

    ──────────────────────────────────────────────────────────────────
    Process Management
    00H                Terminate Process
    31H                Terminate and Stay Resident
    4BH                Load and Execute Program (EXEC)
    4CH                Terminate Process with Return Code
    4DH                Get Return Code of Child Process
    59H                Get Extended Error Information
    Interrupt 20H      Terminate Program
    Interrupt 27H      Terminate and Stay Resident

    ──────────────────────────────────────────────────────────────────
    Memory Management
    48H                Allocate Memory Block
    49H                Free Memory Block
    4AH                Resize Memory Block
    58H                Get/Set Allocation Strategy

    ──────────────────────────────────────────────────────────────────
    Miscellaneous System Management
    25H                Set Interrupt Vector
    26H                Create New Program Segment Prefix
    29H                Parse Filename
    2AH                Get Date
    2BH                Set Date
    2CH                Get Time
    2DH                Set Time
    30H                Get MS-DOS Version Number
    33H                Get/Set Control-C Check Flag
    34H                Return Address of InDOS Flag
    35H                Get Interrupt Vector
    38H                Get/Set Current Country
    44H                IOCTL
    5EH                Network Machine Name/Printer Setup
    5FH                Get/Make Assign List Entry
    62H                Get Program Segment Prefix Address
    63H                Get Lead Byte Table (version 2.25 only)
    Interrupt 22H      Terminate Routine Address
    Interrupt 23H      Control-C Handler Address
    Interrupt 24H      Critical Error Handler Address
    Interrupt 2FH      Multiplex Interrupt




System Call Listings



Interrupt 20H (32)
Terminate Program
1.0 and later


    Interrupt 20H is one of several methods that a program can use to
    perform a final exit. It informs the operating system that the program
    is completely finished and that the memory the program occupied can be
    released.

To Call

    CS   = segment address of program segment prefix (PSP)

Returns

    Nothing

Programmer's Notes

    ■  In response to an Interrupt 20H call, MS-DOS takes the following
        actions:

        -  Restores the termination handler vector (Interrupt 22H) from
        PSP:000AH.

        -  Restores the Control-C vector (Interrupt 23H) from PSP:000EH.

        -  With MS-DOS versions 2.0 and later, restores the critical error
        handler vector (Interrupt 24H) from PSP:0012H.

        -  Flushes the file buffers.

        -  Transfers to the termination handler address.

        The termination handler releases all memory blocks allocated to the
        program, including its environment block and any dynamically
        allocated blocks that were not previously explicitly released;
        closes any files opened with handles that were not previously
        closed; and returns control to the parent process (usually
        COMMAND.COM).

    ■  If the program is returning to COMMAND.COM, control transfers first
        to COMMAND.COM's resident portion, which reloads COMMAND.COM's
        transient portion (if necessary) and passes control to it. If a
        batch file is in progress, the next line of the batch file is then
        fetched and interpreted; otherwise, a prompt is issued for the next
        user command.

    ■  Any files that have been written by the program using FCBs should
        be closed before using Interrupt 20H; otherwise, data may be lost.

    ■  For those programmers who have been with MS-DOS since its earliest
        incarnations, Interrupt 20H is the traditional way to exit from an
        application program. However, under versions 2.0 and later, the
        preferred methods of termination are Interrupt 21H Function 31H
        (Terminate and Stay Resident) and Interrupt 21H Function 4CH
        (Terminate Process with Return Code).

Example

        ;************************************************************;
        ;                                                            ;
        ;                     Perform a final exit.                  ;
        ;                                                            ;
        ;************************************************************;
                int     20H     ; Transfer to MS-DOS.



Interrupt 21H (33) Function 00H (0)
Terminate Process
1.0 and later


    Function 00H flushes all file buffers to disk, terminates the current
    process, and releases the memory used by the process.

To Call

    AH   = 00H
    CS   = segment of program's program segment prefix (PSP)

Returns

    Nothing

Programmer's Notes

    ■  The following interrupt vectors are restored from the PSP of the
        terminated program:

╓┌─────────────────────┌─────────────────────────────────────────────────────╖
        PSP Offset    Vector for Interrupt
        ──────────────────────────────────────────────────────────────────
        0AH           Interrupt 22H (terminate routine)
        0EH           Interrupt 23H (Control-C handler)
        12H           Interrupt 24H (critical error handler)
                    (versions 2.0 and later.)

    ■  All file buffers are written to disk and all handles are closed.
        Control is then transferred to Interrupt 22H (Terminate Routine
        Address).

    ■  Any file that has changed in length and was opened with an FCB
        should be closed before Function 00H is called. If such a file is
        not closed, its length, date, and time are not recorded correctly
        in the directory.

    ■  With versions 3.x of MS-DOS, restoring the default memory-
        allocation strategy used by MS-DOS is advisable if that strategy
        has been changed with Function 58H (Get/Set Allocation Strategy).
        Any global flags, such as the break and verify flags, that affect
        system behavior and that have been changed by the process should
        also be restored to their original values.

    ■  Function 00H performs exactly the same processing as Interrupt 20H
        (Terminate Program).

    ■  Function 00H is obsolete with MS-DOS versions 2.0 and later.
        Function 31H (Terminate and Stay Resident) and Function 4CH
        (Terminate Process with Return Code) are preferred; both enable the
        terminating process to pass a return code to the calling process
        and do not require that CS contain the PSP address.

Related Functions

    31H (Terminate and Stay Resident)
    4CH (Terminate Process with Return Code)

Example

    None



Interrupt 21H (33) Function 01H (1)
Character Input with Echo
1.0 and later


    Function 01H waits for a character from standard input, echoes it to
    standard output, and returns the character in the AL register.

To Call

    AH   = 01H

Returns

    AL   = 8-bit character code

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 01H reads input from the
        keyboard. With versions 2.0 and later, Function 01H reads a
        character from standard input, which defaults to the keyboard but
        can be redirected to another device or to a file. Whether or not
        input has been redirected, the character is echoed to standard
        output.

    ■  Function 01H waits for input if a character is not available. A
        wait can be avoided by calling Function 0BH (Check Keyboard
        Status), which checks whether a character is available from
        standard input, and then calling Function 01H if a character is
        ready.

    ■  On IBM PCs and compatibles, extended characters, such as those
        produced by the Alt-O and F8 keys, are returned as 2 bytes. The
        first byte, 00H, signals an extended character; the second byte
        completes the key code. To read these characters, Function 01H must
        be called twice.

        With MS-DOS versions 2.0 and later, if standard input has been
        redirected, the value 00H can also represent a null character from
        a file and, in that case, might not represent valid data. A program
        can use Function 44H (IOCTL) Subfunction 00H (Get Device Data) to
        determine whether standard input has been redirected.

    ■  The carriage-return character (0DH) echoes a carriage return but
        not a linefeed. Likewise, the linefeed character (0AH) does not
        echo a carriage return.

    ■  With MS-DOS versions 2.0 and later, Function 01H cannot detect an
        end-of-file condition if input has been redirected.

    ■  Interrupt 23H (Control-C Handler Address) is called if Control-C
        (03H) is the input character and (with versions 2.0 and later)
        input is not redirected.

    ■  With MS-DOS versions 2.0 and later, if standard input has been
        redirected to come from a file, Break must be enabled for Interrupt
        23H to be called if Control-C (03H) is the input character.

    ■  Alternative character input functions are 06H (Direct Console I/O),
        07H (Unfiltered Character Input Without Echo), and 08H (Character
        Input Without Echo). The four functions are related as follows:

╓┌─────────────────────┌─────────────────┌────────────┌──────────────────────╖
                    Waits             Echoes to    Acts on
        Function      for Input         Std Output   Control-C
        ──────────────────────────────────────────────────────────────────
        01H           yes               yes          yes
        06H           no                no           no
        07H           yes               no           no
        08H           yes               no           yes

        Depending on whether Control-C needs to be filtered, Function 06H,
        07H, or 08H can be used to handle character display separately from
        character input.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) should be used in preference to Function 01H.

Related Functions

    06H (Direct Console I/O)
    07H (Unfiltered Character Input Without Echo)
    08H (Character Input Without Echo)
    0AH (Buffered Keyboard Input)
    0CH (Flush Buffer, Read Keyboard)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 01H: Character Input with Echo          ;
        ;                                                            ;
        ;           int read_kbd_echo()                              ;
        ;                                                            ;
        ;           Returns a character from standard input          ;
        ;           after sending it to standard output.             ;
        ;                                                            ;
        ;************************************************************;

cProc   read_kbd_echo,PUBLIC
cBegin
        mov     ah,01h          ; Set function code.
        int     21h             ; Wait for character.
        mov     ah,0            ; Character is in AL, so clear high
                                ; byte.
cEnd



Interrupt 21H (33) Function 02H (2)
Character Output
1.0 and later


    Function 02H sends a character to standard output.

To Call

    AH   = 02H
    DL   = 8-bit code for character to be output

Returns

    Nothing

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 02H sends a character to the
        active display. With MS-DOS versions 2.0 and later, Function 02H
        sends the character to standard output. By default, the output is
        sent to the active display, but it can be redirected to another
        device or to a file.

    ■  With all versions of MS-DOS, displaying a backspace (08H) moves the
        cursor back one position but does not erase the character at the
        new position.

    ■  If a Control-C is detected after the character is sent, Interrupt
        23H (Control-C Handler Address) is called.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device) should be used in preference to Function 02H.

Related Functions

    06H (Direct Console I/O)
    09H (Display String)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;                Function 02H: Character Output              ;
        ;                                                            ;
        ;                int disp_ch(c)                              ;
        ;                    char c;                                 ;
        ;                                                            ;
        ;                Returns 0.                                  ;
        ;                                                            ;
        ;************************************************************;


cProc   disp_ch,PUBLIC
parmB   c
cBegin
        mov     dl,c            ; Get character into DL.
        mov     ah,02h          ; Set function code.
        int     21h             ; Send character.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 03H (3)
Auxiliary Input
1.0 and later


    Function 03H waits for a character from the standard auxiliary device
    and returns the character in the AL register.

To Call

    AH   = 03H

Returns

    AL   = 8-bit character code

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 03H reads a character from
        the first serial port. With versions 2.0 and later, Function 03H
        reads from the standard auxiliary device (AUX), which defaults to
        COM1.

    ■  Function 03H waits for input until a character is available from
        the standard auxiliary device.

    ■  Function 03H is not interrupt driven and does not buffer characters
        received from the standard auxiliary device. As a result, it may
        not be fast enough for some telecommunications applications and
        data may be lost.

    ■  A program cannot perform error detection using Function 03H. On IBM
        PCs and compatibles, error detection is available through the ROM
        BIOS Interrupt 14H. Another option is to drive the communications
        controller directly.

    ■  Function 03H does not ensure that auxiliary input is connected and
        working, nor does it perform any error checking or set up the
        auxiliary input device. On IBM PCs and compatibles, the standard
        auxiliary device, normally COM1, is set to 2400 baud, no parity, 1
        stop bit, and 8 databits at startup. These parameters can be
        changed with the MS-DOS MODE command.

    ■  Some auxiliary input devices do not support 8-bit data
        transmission. This transmission parameter is a characteristic of
        the device and the communication parameters to which it is set; it
        is independent of Function 03H.

    ■  If a Control-C is detected at the console, Interrupt 23H
        (Control-C Handler Address) is called.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device), which handles strings as well as single characters, should
        be used in preference to Function 03H.

Related Functions

    04H (Auxiliary Output)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 03H: Auxiliary Input                    ;
        ;                                                            ;
        ;           int aux_in()                                     ;
        ;                                                            ;
        ;           Returns next character from AUX device.          ;
        ;                                                            ;
        ;************************************************************;

cProc   aux_in,PUBLIC
cBegin
        mov     ah,03h          ; Set function code.
        int     21h             ; Wait for character from AUX.
        mov     ah,0            ; Character is in AL
                                ; so clear high byte.
cEnd



Interrupt 21H (33) Function 04H (4)
Auxiliary Output
1.0 and later


    Function 04H sends a character to the standard auxiliary device.

To Call

    AH   = 04H
    DL   = 8-bit code for character to be output

Returns

    Nothing

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 04H sends a character to the
        first serial port. With versions 2.0 and later, Function 04H sends
        the character to the standard auxiliary device (AUX), which
        defaults to COM1.

    ■  Function 04H does not ensure that auxiliary output is connected and
        working, nor does it perform any error checking or set up the
        auxiliary output device. On IBM PCs and compatibles, the standard
        auxiliary device, normally COM1, is set to 2400 baud, no parity, 1
        stop bit, and 8 databits at startup. These parameters can be
        changed with the MS-DOS MODE command.

    ■  Function 04H does not return the status of auxiliary output, nor
        does it return an error code if the auxiliary output device is not
        ready for data. If the device is busy, Function 04H waits until it
        is available.

    ■  Interrupt 23H (Control-C Handler Address) is called if a Control-C
        is detected at the console.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device), which manages strings as well as single characters, should
        be used in preference to Function 04H.

Related Functions

    03H (Auxiliary Input)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;                Function 04H: Auxiliary Output              ;
        ;                                                            ;
        ;                int aux_out(c)                              ;
        ;                    char c;                                 ;
        ;                                                            ;
        ;                Returns 0.                                  ;
        ;                                                            ;
        ;************************************************************;

cProc   aux_out,PUBLIC
parmB   c
cBegin
        mov     dl,c            ; Get character into DL.
        mov     ah,04h          ; Set function code.
        int     21h             ; Write character to AUX.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 05H (5)
Print Character
1.0 and later


    Function 05H sends a character to the standard printer.

To Call

    AH   = 05H
    DL   = 8-bit code for character to be output

Returns

    Nothing

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 05H sends a character to the
        first parallel port (LPT1). With versions 2.0 and later, Function
        05H sends the character to the standard printer (PRN), which
        defaults to LPT1 unless LPT1 has been reassigned with the MS-DOS
        MODE command. If redirection is in effect, calls to this function
        send output to the device currently assigned to LPT1.

    ■  Function 05H does not return the status of the standard printer,
        nor does it return an error code if the standard printer is not
        ready for characters. If the printer is busy or off line, Function
        05H waits until it is available. MS-DOS does, however, perform
        error checking during the print operation and send any error
        messages to the standard error device (normally the display).

    ■  If a Control-C is detected at the console, Interrupt 23H (Control-C
        Handler Address) is called.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device) should be used in preference to Function 05H.

Related Function

    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;                Function 05H: Print Character               ;
        ;                                                            ;
        ;                int print_ch(c)                             ;
        ;                    char c;                                 ;
        ;                                                            ;
        ;                Returns 0.                                  ;
        ;                                                            ;
        ;************************************************************;

cProc   print_ch,PUBLIC
parmB   c
cBegin
        mov     dl,c            ; Get character into DL.
        mov     ah,05h          ; Set function code.
        int     21h             ; Write character to standard printer.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 06H (6)
Direct Console I/O
1.0 and later


    Function 06H reads a character from standard input or writes a
    character to standard output.

To Call

    AH   = 06H

    For character input:

    DL   = FFH

    For character output:

    DL   = 00-FEH (8-bit character code)

Returns

    If DL was 0FFH on call and a character was ready:

    Zero flag is clear.

    AL   = 8-bit character code

    If DL was 0FFH on call and no character was ready:

    Zero flag is set.

Programmer's Notes

    ■  With MS-DOS versions 1.x, Function 06H reads a character from the
        keyboard or sends a character to the display. With versions 2.0 and
        later, input and output can be redirected; Function 06H reads from
        the device currently assigned to standard input or sends to the
        device currently assigned to standard output.

    ■  Function 06H allows all possible characters and control codes with
        values between 00H and 0FEH to be read or written with standard
        input and output and with no filtering by the operating system. The
        rubout character (0FFH, 255 decimal), however, cannot be output
        with Function 06H; Function 02H (Character Output) should be used
        instead.

    ■  On IBM PCs and compatibles, extended characters, such as those
        produced by the Alt-O and F8 keys, are returned as 2 bytes. The
        first byte, 00H, signals an extended character; the second byte
        completes the key code. To read these characters, Function 06H must
        be called twice.

        With MS-DOS versions 2.0 and later, if standard input has been
        redirected, the value 00H can also represent a null character from
        a file and, in that case, might not represent valid data. A program
        can use Function 44H (IOCTL) Subfunction 00H (Get Device Data) to
        determine whether standard input has been redirected.

    ■  If Function 06H is an input request and a Control-C is read, the
        character is returned as any other character would be. Interrupt
        23H (Control-C Handler Address) is not called.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) and Function 40H (Write File or Device) should be used in
        preference to Function 06H.

Related Functions

    01H (Character Input with Echo)
    02H (Character Output)
    07H (Unfiltered Character Input Without Echo)
    08H (Character Input Without Echo)
    09H (Display String)
    0AH (Buffered Keyboard Input)
    0CH (Flush Buffer, Read Keyboard)
    3FH (Read File or Device)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 06H: Direct Console I/O                  ;
        ;                                                            ;
        ;          int con_io(c)                                     ;
        ;              char c;                                       ;
        ;                                                            ;
        ;          Returns meaningless data if c is not 0FFH,        ;
        ;          otherwise returns next character from             ;
        ;          standard input.                                   ;
        ;                                                            ;
        ;************************************************************;

cProc   con_io,PUBLIC
parmB   c
cBegin
        mov     dl,c            ; Get character into DL.
        mov     ah,06h          ; Set function code.
        int     21h             ; This function does NOT wait in
                                ; input case (c = 0FFH)!
        mov     ah,0            ; Return the contents of AL.
cEnd



Interrupt 21H (33) Function 07H (7)
Unfiltered Character Input Without Echo
1.0 and later


    Function 07H waits for a character from standard input. It does not
    echo the character to standard output, and it ignores Control-C
    characters.

To Call

    AH   = 07H

Returns

    AL   = 8-bit character code

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 07H reads input from the
        keyboard. With versions 2.0 and later, Function 07H reads a
        character from standard input. Standard input defaults to the
        keyboard but can be redirected to another device or to a file.

    ■  Function 07H waits for input if a character is not available. A
        wait can be avoided by calling Function 0BH (Check Keyboard
        Status), which checks whether a character is available from
        standard input, and then calling Function 07H if a character is
        ready.

    ■  On IBM PCs and compatibles, extended characters, such as those
        produced by the Alt-O and F8 keys, are returned as 2 bytes. The
        first byte, 00H, signals an extended character; the second byte
        completes the key code. To read these characters, Function 07H must
        be called twice.

        With MS-DOS versions 2.0 and later, if standard input has been
        redirected, the value 00H can also represent a null character from
        a file and, in that case, might not represent valid data. A program
        can use Function 44H (IOCTL) Subfunction 00H (Get Device Data) to
        determine whether standard input has been redirected.

    ■  Interrupt 23H (Control-C Handler Address) is not called if a
        Control-C is read. Function 07H simply passes the character back
        through the AL register. If Control-C checking is required,
        Function 08H (Character Input Without Echo) should be used
        instead.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) should be used in preference to Function 07H.

Related Functions

    01H (Character Input with Echo)
    06H (Direct Console I/O)
    08H (Character Input Without Echo)
    0AH (Buffered Keyboard Input)
    0CH (Flush Buffer, Read Keyboard)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 07H: Unfiltered Character Input           ;
        ;                       Without Echo                         ;
        ;                                                            ;
        ;         int con_in()                                       ;
        ;                                                            ;
        ;         Returns next character from standard input.        ;
        ;                                                            ;
        ;************************************************************;

cProc   con_in,PUBLIC
cBegin
        mov     ah,07h          ; Set function code.
        int     21h             ; Wait for character, no echo.
        mov     ah,0            ; Clear high byte.
cEnd



Interrupt 21H (33) Function 08H (8)
Character Input Without Echo
1.0 and later


    Function 08H waits for a character from standard input. The character
    is not echoed to standard output.

To Call

    AH   = 08H

Returns

    AL   = 8-bit character code

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 08H reads input from the
        keyboard. With versions 2.0 and later, Function 08H reads a
        character from standard input. Standard input defaults to the
        keyboard but can be redirected to another device or to a file.

    ■  Function 08H waits for input if a character is not available. A
        wait can be avoided by calling Function 0BH (Check Keyboard
        Status), which checks whether a character is available, and then
        calling Function 08H if a character is ready.

    ■  On IBM PCs and compatibles, extended characters, such as those
        produced by the Alt-O and F8 keys, are returned as 2 bytes. The
        first byte, 00H, signals an extended character; the second byte
        completes the key code. To read these characters, Function 08H must
        be called twice.

        With MS-DOS versions 2.0 and later, if standard input has been
        redirected, the value 00H can also represent a null character from
        a file and, in that case, might not represent valid data. A process
        can use Function 44H (IOCTL) Subfunction 00H (Get Device Data) to
        determine whether standard input has been redirected.

    ■  If a Control-C is read and (with versions 2.0 and later) input has
        not been redirected, Interrupt 23H (Control-C Handler Address) is
        called. To read the Control-C character as data, Function 07H
        (Unfiltered Character Input Without Echo) should be used.

    ■  Interrupt 23H (Control-C Handler Address) is called if Control-C is
        the input character, Break is enabled, and (with versions 2.0 and
        later) standard input has been redirected to come from a file.

    ■  With MS-DOS versions 2.0 and later, if standard input has been
        redirected to come from a file, Break must be enabled for Interrupt
        23H to be called if Control-C (03H) is the input character.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) should be used in preference to Function 08H.

Related Functions

    01H (Character Input with Echo)
    06H (Direct Console I/O)
    07H (Unfiltered Character Input Without Echo)
    0AH (Buffered Keyboard Input)
    0CH (Flush Buffer, Read Keyboard)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;    Function 08H:  Unfiltered Character Input Without Echo  ;
        ;                                                            ;
        ;    int read_kbd()                                          ;
        ;                                                            ;
        ;    Returns next character from standard input.             ;
        ;                                                            ;
        ;************************************************************;

cProc   read_kbd,PUBLIC
cBegin
        mov     ah,08h          ; Set function code.
        int     21h             ; Wait for character, no echo.
        mov     ah,0            ; Clear high byte.
cEnd



Interrupt 21H (33) Function 09H (9)
Display String
1.0 and later


    Function 09H sends a string of characters to standard output. The
    string must end with the dollar-sign character ($). All characters up
    to, but not including, the $ are displayed.

To Call

    AH      = 09H
    DS:DX   = segment:offset of string to display

Returns

    Nothing

Programmer's Notes

    ■  With MS-DOS versions 1.x, Function 09H sends the string to the
        display. With versions 2.0 and later, the string is written to
        standard output. By default, standard output is sent to the
        display, but it can be redirected to another device or to a
        file.

    ■  The string can include any valid ASCII characters, including
        control codes. Sending a dollar sign with this function, however,
        is not possible.

    ■  Depending on the device currently serving as standard output,
        characters other than the normally displayable ASCII characters
        (20H to 7FH) may or may not be displayed. On IBM PCs and most
        compatibles, extensions to the displayable ASCII character set
        (character codes 80H to FFH) appear as foreign or graphics
        characters.

    ■  Display begins at the current cursor position on standard output.
        After the string is completely displayed, the cursor position is
        updated to the location immediately following the string.

        On IBM PCs and compatibles, if the end of a line is reached before
        the string is completely displayed, a carriage return and linefeed
        are issued and the next character is displayed in the first
        position of the following line. If the cursor reaches the bottom
        right corner of the display before the complete string has been
        sent, the display is scrolled up one line.

    ■  Control characters are often included in the string to be sent. The
        following sample fragment of code contains carriage returns and
        linefeeds:

        msg     db      'Resident part of TSR.COM installed'
                db      0dh, 0ah
                db      'Copyright (c) 19xx Foo Software, Inc.'
                db      0dh, 0ah, 0ah, 0ah
                db      '$'

    ■  If a Control-C is detected, Interrupt 23H (Control-C Handler
        Address) is called.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device) should be used in preference to Function 09H.

Related Functions

    02H (Character Output)
    06H (Direct Console I/O)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;                 Function 09H: Display String               ;
        ;                                                            ;
        ;                 int disp_str(pstr)                         ;
        ;                     char *pstr;                            ;
        ;                                                            ;
        ;                 Returns 0.                                 ;
        ;                                                            ;
        ;************************************************************;

cProc   disp_str,PUBLIC,<ds,di>
parmDP  pstr
cBegin
        loadDP  ds,dx,pstr      ; DS:DX = pointer to string.
        mov     ax,0900h        ; Prepare to write dollar-terminated
                                ; string to standard output, but
                                ; first replace the 0 at the end of
                                ; the string with '$'.
        push    ds              ; Set ES equal to DS.
        pop     es              ; (MS-C does not require ES to be
                                ; saved.)
        mov     di,dx           ; ES:DI points at string.
        mov     cx,0ffffh       ; Allow string to be 64KB long.
        repne   scasb           ; Look for 0 at end of string.
        dec     di              ; Scasb search always goes 1 byte too
                                ; far.
        mov     byte ptr [di],'$' ; Replace 0 with dollar sign.
        int     21h             ; Have MS-DOS print string.
        mov     [di],al         ; Restore 0 terminator.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 0AH (10)
Buffered Keyboard Input
1.0 and later


    Function 0AH collects characters from standard input and places them
    in a user-specified memory buffer. Input is accepted until either a
    carriage return (0DH) is encountered or the buffer is filled to one
    character less than its capacity. The characters are echoed to
    standard output.

To Call

    AH      = 0AH
    DS:DX   = segment:offset of input buffer

Returns

    Nothing

Programmer's Notes

    ■  With MS-DOS versions 1.x, Function 0AH reads a string from the
        keyboard. With versions 2.0 and later, calls to this function read
        a string from standard input, which defaults to the keyboard but
        can be redirected to another device or to a file. The MS-DOS
        editing keys are active during input with this function.

    ■  The buffer pointed to by DS:DX must have the following
        format:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Byte     Contents
        ──────────────────────────────────────────────────────────────────
        0        Maximum number of characters to read (1-255); this
                value must be set by the process before Function 0AH
                is called.

        1        Count of characters read (does not include the carriage
                return); this value is set by Function 0AH before
                returning to the process.

        2-(n+2)  Actual string of characters read, including the carriage
                return; n = number of bytes read.

    ■  The first byte of the buffer must contain the maximum number of
        characters the program will accept, including the carriage return
        at the end. Because the last byte must be a carriage return, the
        maximum number of bytes this function will actually read is 254.
        The carriage return is not included in the character count returned
        by MS-DOS in the second byte of the buffer.

    ■  If the buffer fills to 1 byte less than its capacity, succeeding
        characters are ignored and a beep is sounded for each keypress
        until a carriage return is received.

    ■  If a Control-C is detected and (with versions 2.0 and later) input
        has not been redirected, Interrupt 23H (Control-C Handler Address)
        is called.

    ■  With versions 2.0 and later, if standard input has been redirected
        to come from a file, Break must be enabled for Interrupt 23H
        (Control-C Handler Address) to be called when Control-C is the
        input character.

    ■  With MS-DOS versions 2.0 and later, if input is redirected, an end-
        of-file condition goes undetected by Function 0AH.

Related Functions

    01H (Character Input with Echo)
    06H (Direct Console I/O)
    07H (Unfiltered Character Input Without Echo)
    08H (Character Input Without Echo)
    0CH (Flush Buffer, Read Keyboard)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;        Function 0AH: Buffered Keyboard Input               ;
        ;                                                            ;
        ;        int read_str(pbuf,len)                              ;
        ;            char *pbuf;                                     ;
        ;            int len;                                        ;
        ;                                                            ;
        ;        Returns number of bytes read into buffer.           ;
        ;                                                            ;
        ;        Note: pbuf must be at least len+3 bytes long.       ;
        ;                                                            ;
        ;************************************************************;

cProc   read_str,PUBLIC,<ds,di>
parmDP  pbuf
parmB   len
cBegin
        loadDP  ds,dx,pbuf      ; DS:DX = pointer to buffer.
        mov     al,len          ; AL = len.
        inc     al              ; Add 1 to allow for CR in buf.
        mov     di,dx
        mov     [di],al         ; Store max length into buffer.
        mov     ah,0ah          ; Set function code.
        int     21h             ; Ask MS-DOS to read string.
        mov     al,[di+1]       ; Return number of characters read.
        mov     ah,0
        mov     bx,ax
        mov     [bx+di+2],ah    ; Store 0 at end of buffer.
cEnd



Interrupt 21H (33) Function 0BH (11)
Check Keyboard Status
1.0 and later


    Function 0BH returns a value in AL that indicates whether a character
    is available from standard input.

To Call

    AH   = 0BH

Returns

    AL   = 00H       no character available
        = FFH       one or more characters available

Programmer's Notes

    ■  With MS-DOS versions 1.x, Function 0BH checks the type-ahead buffer
        for a character. With versions 2.0 and later, if input has been
        redirected, Function 0BH checks standard input for a character. If
        input has not been redirected, the function checks the type-ahead
        buffer.

    ■  Function 0BH does not indicate how many characters are available;
        it merely indicates whether at least one character is available.

    ■  If the available character is Control-C, Interrupt 23H (Control-C
        Handler Address) is called.

    ■  Function 0BH does not remove characters from standard input. Thus,
        if a character is present, repeated calls return 0FFH in AL until
        all characters in the buffer are read, either with one of the
        character-input functions (01H, 06H, 07H, 08H, or 0AH) or with
        Function 3FH (Read File or Device) using the handle for standard
        input (0).

Related Functions

    06H (Direct Console I/O)
    44H Subfunction 06H (IOCTL: Check Input Status)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 0BH: Check Keyboard Status            ;
        ;                                                            ;
        ;             int key_ready()                                ;
        ;                                                            ;
        ;             Returns 1 if key is ready, 0 if not.           ;
        ;                                                            ;
    ;************************************************************;

cProc   key_ready,PUBLIC
cBegin
        mov     ah,0bh          ; Set function code.
        int     21h             ; Ask MS-DOS if key is available.
        and     ax,0001h        ; Keep least significant bit only.
cEnd



Interrupt 21H (33) Function 0CH (12)
Flush Buffer, Read Keyboard
1.0 and later


    Function 0CH clears the standard-input buffer and then performs one of
    the other keyboard input functions (01H, 06H, 07H, 08H, 0AH).

To Call

    AH      = 0CH
    AL      = input function number to execute

    If AL is 06H:

    DL      = FFH

    If AL is 0AH:

    DS:DX   = segment:offset of buffer to receive input

Returns

    If AL was 01H, 06H, 07H, or 08H on call:

    AL      = 8-bit ASCII character from standard input

    If AL was 0AH on call:

    Nothing

Programmer's Notes

    ■  With versions 1.x of MS-DOS, Function 0CH empties the type-ahead
        buffer before executing the input function specified in AL. With
        versions 2.0 and later, if input has been redirected to a file,
        Function 0CH does nothing before carrying out the input function
        specified in AL; if input was not redirected, the type-ahead buffer
        is flushed.

    ■  A function number other than 01H, 06H, 07H, 08H, or 0AH in AL
        simply flushes the standard-input buffer and returns control to the
        calling program.

    ■  If AL contains 0AH, DS:DX must point to the buffer in which MS-DOS
        is to place the string read from the keyboard.

    ■  Because the buffer is flushed before the input function is carried
        out, any Control-C characters pending in the buffer are discarded.
        If subsequent input is a Control-C, however, Interrupt 23H
        (Control-C Handler Address) is called.

    ■  This function exists to defeat the type-ahead feature if necessary--
        for example, to obtain input at a critical prompt the user may not
        have anticipated.

Related Functions

    01H (Character Input with Echo)
    06H (Direct Console I/O)
    07H (Unfiltered Character Input Without Echo)
    08H (Character Input Without Echo)
    0AH (Buffered Keyboard Input)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 0CH: Flush Buffer, Read Keyboard         ;
        ;                                                            ;
        ;          int flush_kbd()                                   ;
        ;                                                            ;
        ;          Returns 0.                                        ;
        ;                                                            ;
        ;************************************************************;

cProc   flush_kbd,PUBLIC
cBegin
        mov     ax,0c00h        ; Just flush type-ahead buffer.
        int     21h             ; Call MS-DOS.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 0DH (13)
Disk Reset
1.0 and later


    Function 0DH writes to disk all internal MS-DOS file buffers in memory
    that have been modified since the last write. All buffers are then
    marked as "free."

To Call

    AH   = 0DH

Returns

    Nothing

Programmer's Notes

    ■  Function 0DH ensures that the information stored on disk matches
        changes made by write requests to file buffers in memory.

    ■  Function 0DH does not update the disk directory. The application
        must issue Function 10H (Close File with FCB) or Function 3EH
        (Close File) to update directory information correctly.

    ■  Function 0DH should be part of Control-C interrupt-handling
        routines so that the system is left in a known state when an
        application is terminated.

    ■  Disk Reset calls can be issued after particularly important disk
        write calls, such as transactions in an accounting application.
        Repeated use of this function, however, degrades system performance
        by defeating the MS-DOS buffering scheme.

Related Functions

    10H (Close File with FCB)
    3EH (Close File)

Example

        ;************************************************************;
        ;                                                            ;
        ;                   Function 0DH: Disk Reset                 ;
        ;                                                            ;
        ;                   int reset_disk()                         ;
        ;                                                            ;
        ;                   Returns 0.                               ;
        ;                                                            ;
        ;************************************************************;

cProc   reset_disk,PUBLIC
cBegin
        mov     ah,0dh          ; Set function code.
        int     21h             ; Ask MS-DOS to write all dirty file
                                ; buffers to the disk.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 0EH (14)
Select Disk
1.0 and later


    Function 0EH sets the default disk drive to the drive specified in the
    DL register. The default is the disk drive MS-DOS chooses for file
    access when a filename is specified without a drive designator. A
    successful call to this function returns the number of logical (not
    physical) drives in the system.

To Call

    AH   = 0EH
    DL   = drive number (0 = drive A, 1 = drive B, 2 = drive C, and
            so on)

Returns

    AL   = number of logical drives in the system

Programmer's Notes

    ■  The value used as a drive number is the ASCII value of the
        uppercase drive letter minus the ASCII value of the uppercase
        letter A (41H); thus, 0 = drive A, 1 = drive B, and so on.

    ■  A logical drive is defined as any block-oriented device; this
        category includes floppy-disk drives, RAMdisks, tape devices, fixed
        disks (which can be partitioned into more than one logical drive),
        and network drives.

    ■  The maximum numbers of drive designators available for each MS-DOS
        version are as follows:

╓┌─────────────────────────┌─────────────────────────┌───────────────────────╖
        MS-DOS Version    Number of Designators     Values
        ──────────────────────────────────────────────────────────────────
        1.x               16                        0 through 0FH
        2.x               63                        0 through 3FH
        3.x               26                        0 through 19H

        Drive letters should be limited to A through P (0 through 0FH) to
        ensure that an application runs on all versions of MS-DOS.

    ■  With versions of MS-DOS earlier than 3.0 running on IBM PCs and
        compatibles with one floppy-disk drive, Function 0EH returns 02H as
        the drive count, because the single physical drive is equivalent to
        the two logical drives A and B. MS-DOS versions 3.0 and later
        return a minimum value of 05H in AL.

    ■  On IBM PCs and compatibles, the number of physical floppy-disk
        drives in a system can be obtained from the ROM BIOS with Interrupt
        11H (Equipment Determination).

Related Function

    19H (Get Current Disk)

Example

        ;************************************************************;
        ;                                                            ;
        ;     Function 0EH: Select Disk                              ;
        ;                                                            ;
        ;     int select_drive(drive_ltr)                            ;
        ;         char drive_ltr;                                    ;
        ;                                                            ;
        ;     Returns number of logical drives present in system.    ;
        ;                                                            ;
        ;************************************************************;

cProc   select_drive,PUBLIC
parmB   drive_ltr
cBegin
        mov     dl,drive_ltr    ; Get new drive letter.
        and     dl,not 20h      ; Make sure letter is uppercase.
        sub     dl,'A'          ; Convert drive letter to number,
                                ; 'A' = 0, 'B' = 1, etc.
        mov     ah,0eh          ; Set function code.
        int     21h             ; Ask MS-DOS to set default drive.
        cbw                     ; Clear high byte of return value.
cEnd



Interrupt 21H (33) Function 0FH (15)
Open File with FCB
1.0 and later


    Function 0FH opens the file named in the file control block (FCB)
    pointed to by DS:DX.

To Call

    AH      = 0FH
    DS:DX   = segment:offset of an unopened FCB

Returns

    If function is successful:

    AL      = 00H

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  MS-DOS provides several types of file services: FCB file services,
        which are relatively compatible with the CP/M methods of file
        handling; extended FCB file services, which take advantage of both
        CP/M compatibility and MS-DOS extensions; and handle, or "stream-
        oriented," file services, which are more compatible with UNIX/XENIX
        and support pathnames (MS-DOS versions 2.0 and later).

    ■  Function 0FH does not support pathnames and so is capable of
        opening files only in the current directory of the specified
        drive.

    ■  Function 0FH does not create a new file if the specified file does
        not already exist. Function 16H (Create File with FCB) is used to
        create new files with FCBs.

    ■  Function 0FH must use an unopened FCB--that is, one in which all
        but the drive-designator, filename, and extension fields are zero.
        If the call is successful, the function fills in the file size and
        date fields from the file's directory entry. In MS-DOS versions 2.0
        and later, the function also fills in the time field.

    ■  If the file is opened on the default drive (the drive number in the
        FCB is set to 0), MS-DOS fills in the actual drive code. Thus, at
        some later point in processing, the default drive can be changed
        and MS-DOS will still have the drive number in the FCB for use in
        accessing the file. It will therefore continue to use the correct
        drive.

    ■  If Function 0FH is successful, MS-DOS sets the current-block field
        to 0; that is, the file pointer is at the beginning of the file. It
        also sets the record size to 128 bytes (the system default).

    ■  If a record size other than 128 is needed, the record size field of
        the FCB should be changed after the file is successfully opened and
        before attempting any I/O.

    ■  In a network running under MS-DOS version 3.1 or later, files are
        opened by Function 0FH with the share code set to compatibility
        mode and the access code set to read/write.

    ■  If Function 0FH returns an error code (0FFH) in the AL register,
        the attempt to open the file was not successful. Possible causes
        for the failure are

        - File was not found.

        - File has the hidden or system attribute and a properly formatted
        extended FCB was not used.

        - Filename was improperly specified in the FCB.

        - SHARE is loaded and the file is already open by another process
        in a mode other than compatibility mode.

    ■  With MS-DOS versions 3.0 and later, Function 59H (Get Extended
        Error Information) can be used to determine why the attempt to open
        the file failed.

    ■  MS-DOS passes the first two command-tail parameters into default
        FCBs located at offsets 5CH and 6CH in the program segment prefix
        (PSP). Many applications designed to run as .COM files take
        advantage of one or both of these default FCBs.

    ■  With MS-DOS versions 2.0 and later, Function 3DH (Open File with
        Handle) should be used in preference to Function 0FH.

Related Functions

    10H (Close File with FCB)
    16H (Create File with FCB)
    3CH (Create File with Handle)
    3DH (Open File with Handle)
    3EH (Close File)
    59H (Get Extended Error Information)
    5AH (Create Temporary File)
    5BH (Create New File)

Example

        ;************************************************************;
        ;                                                            ;
        ;        Function 0FH: Open File, FCB-based                  ;
        ;                                                            ;
        ;        int FCB_open(uXFCB,recsize)                         ;
        ;            char *uXFCB;                                    ;
        ;            int recsize;                                    ;
        ;                                                            ;
        ;        Returns 0 if file opened OK, otherwise returns -1.  ;
        ;                                                            ;
        ;        Note: uXFCB must have the drive and filename        ;
        ;        fields (bytes 07H through 12H) and the extension    ;
        ;        flag (byte 00H) set before the call to FCB_open     ;
        ;        (see Function 29H).                                 ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_open,PUBLIC,ds
parmDP  puXFCB
parmW   recsize
cBegin
        loadDP  ds,dx,puXFCB    ; Pointer to unopened extended FCB.
        mov     ah,0fh          ; Ask MS-DOS to open an existing file.
        int     21h
        add     dx,7            ; Advance pointer to start of regular
                                ; FCB.
        mov     bx,dx           ; BX = FCB pointer.
        mov     dx,recsize      ; Get record size parameter.
        mov     [bx+0eh],dx     ; Store record size in FCB.
        xor     dx,dx
        mov     [bx+20h],dl     ; Set current-record
        mov     [bx+21h],dx     ; and relative-record
        mov     [bx+23h],dx     ; fields to 0.
        cbw                     ; Set return value to 0 or -1.
cEnd



Interrupt 21H (33) Function 10H (16)
Close File with FCB
1.0 and later


    Function 10H flushes file-related information to disk, closes the file
    named in the file control block (FCB) pointed to by DS:DX, and updates
    the file's directory entry.

To Call

    AH      = 10H
    DS:DX   = segment:offset of previously opened FCB

Returns

    If function is successful:

    AL      = 00H

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  A successful call to Function 10H flushes to disk all MS-DOS
        internal buffers associated with the file and updates the directory
        entry and file allocation table (FAT). The function thus ensures
        that correct information is contained in the copy of the file on
        disk.

    ■  Because MS-DOS versions 1.x and 2.x do not always detect a disk
        change, an error can occur if the user changes disks between the
        time the file is opened and the time it is closed. In the worst
        case, the FAT and the directory of the newly inserted disk may be
        damaged.

    ■  With MS-DOS versions 2.0 and later, Function 3EH (Close File)
        should be used in preference to Function 10H.

Related Functions

    0FH (Open File with FCB)
    3EH (Close File)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 10H: Close file, FCB-based              ;
        ;                                                            ;
        ;           int FCB_close(oXFCB)                             ;
        ;               char *oXFCB;                                 ;
        ;                                                            ;
        ;           Returns 0 if file closed OK, otherwise           ;
        ;           returns -1.                                      ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_close,PUBLIC,ds
parmDP  poXFCB
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     ah,10h          ; Ask MS-DOS to close file.
        int     21h
        cbw                     ; Set return value to 0 or -1.
cEnd



Interrupt 21H (33) Function 11H (17)
Find First File
1.0 and later


    Function 11H searches the current directory for the first file that
    matches a specified name and extension.

To Call

    AH      = 11H
    DS:DX   = segment:offset of unopened file control block (FCB)

Returns

    If function is successful:

    AL      = 00H

    Disk transfer area (DTA) contains unopened FCB of same type (normal or
    extended) as search FCB.

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  If necessary, Function 1AH (Set DTA Address) should be used before
        Function 11H is called, to set the location of the DTA in which the
        results of the search will be placed.

    ■  With MS-DOS versions 1.0 and later, the wildcard character ? is
        allowed in the filename. With MS-DOS versions 3.0 and later, both
        wildcard characters (? and *) are allowed in filenames. Pathnames
        are not supported.

    ■  With MS-DOS versions 2.0 and later, the attribute field of an
        extended FCB can be used to search for files with the hidden,
        system, subdirectory, or volume-label attributes. In such a search,
        specifying either the normal (00H) or volume-label (08H) attribute
        restricts MS-DOS to files with the given attribute. Specifying any
        combination of the hidden (02H), system (04H), and subdirectory
        (10H) attributes, however, causes MS-DOS to search both for normal
        files and for those that match the specified attributes.

    ■  For a normal FCB, Function 11H places the drive number in the first
        byte of the DTA and fills the succeeding 32 bytes with the
        directory entry.

        For an extended FCB, Function 11H fills in the first 7 bytes of the
        DTA as follows: the first byte contains 0FFH, indicating an
        extended FCB; the second through sixth bytes contain 00H, as
        required by MS-DOS; the seventh byte contains the value of the
        attribute byte in the search FCB. The next 33 bytes contain the
        drive number and directory information, as for a normal FCB.

    ■  As with other FCB functions, the number 0 can be used to indicate
        the default drive. MS-DOS fills in the actual drive number and
        continues to use that drive for calls to Function 12H (Find Next
        File) that use the same FCB, regardless of any subsequent selection
        of a different default drive.

    ■  The FCB with the initial file specifications must remain unmodified
        if Function 12H is used to continue the search.

    ■  Error reporting in Function 11H is incomplete. An error return
        (0FFH in the AL register) does not always mean that the file does
        not exist. Other possibilities include

        - Filename in the FCB was improperly specified.

        - If an extended FCB was used, no files match the attributes
        given.

        With MS-DOS versions 3.0 and later, Function 59H (Get Extended
        Error Information) can be used to obtain additional information
        about the error.

    ■  With MS-DOS versions 2.0 and later, Functions 4EH (Find First File)
        and 4FH (Find Next File) should be used in preference to Functions
        11H and 12H.

Related Functions

    12H (Find Next File)
    1AH (Set DTA Address)
    4EH (Find First File)
    4FH (Find Next File)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 11H: Find First File, FCB-based             ;
        ;                                                            ;
        ;       int FCB_first(puXFCB,attrib)                         ;
        ;           char *puXFCB;                                    ;
        ;           char  attrib;                                    ;
        ;                                                            ;
        ;       Returns 0 if match found, otherwise returns -1.      ;
        ;                                                            ;
        ;       Note: The FCB must have the drive and                ;
        ;       filename fields (bytes 07H through 12H) and          ;
        ;       the extension flag (byte 00H) set before             ;
        ;       the call to FCB_first (see Function 29H).            ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_first,PUBLIC,ds
parmDP  puXFCB
parmB   attrib
cBegin
        loadDP  ds,dx,puXFCB    ; Pointer to unopened extended FCB.
        mov     bx,dx           ; BX points at FCB, too.
        mov     al,attrib       ; Get search attribute.
        mov     [bx+6],al       ; Put attribute into extended FCB
                                ; area.
        mov     byte ptr [bx],0ffh ; Set flag for extended FCB.
        mov     ah,11h          ; Ask MS-DOS to find 1st matching
                                ; file in current directory.
        int     21h             ; If match found, directory entry can
                                ; be found at DTA address.
        cbw                     ; Set return value to 0 or -1.
cEnd



Interrupt 21H (33) Function 12H (18)
Find Next File
1.0 and later


    Function 12H searches the current directory for the next file that
    matches a specified filename and extension. The function assumes a
    previous successful call to Function 11H (Find First File) with the
    same file control block (FCB).

To Call

    AH      = 12H
    DS:DX   = segment:offset of search FCB

Returns

    If function is successful:

    AL      = 00H

    Disk transfer area (DTA) contains unopened FCB of same type (normal or
    extended) as search FCB.

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  Function 12H assumes that a successful call to Function 11H (Find
        First File) has been completed with the same FCB. The FCB specifies
        the search pattern. This function also assumes that the wildcard
        character ? appears at least once in the filename or extension
        specified.

    ■  An error (indicated by 0FFH returned in register AL) does not
        necessarily mean that a file matching the file specification does
        not exist in the current directory. MS-DOS relies on certain
        information that appears in the search FCB initialized by Function
        11H, so it is important not to alter that FCB either between calls
        to Functions 11H and 12H or between subsequent calls to Function
        12H.

    ■  If drive code 0 (the default drive) was used in the call to
        Function 11H, MS-DOS has already filled in the actual drive number
        for the current directory. MS-DOS continues to use that drive for
        all calls to Function 12H that use the same FCB, regardless of the
        default drive in effect at the time of the call.

    ■  With MS-DOS versions 2.0 and later, Functions 4EH (Find First File)
        and 4FH (Find Next File) should be used in preference to Functions
        11H and 12H.

Related Functions

    11H (Find First File)
    1AH (Set DTA Address)
    4EH (Find First File)
    4FH (Find Next File)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 12H: Find Next File, FCB-based              ;
        ;                                                            ;
        ;       int FCB_next(puXFCB)                                 ;
        ;           char *puXFCB;                                    ;
        ;                                                            ;
        ;       Returns 0 if match found, otherwise returns -1.      ;
        ;                                                            ;
        ;       Note: The FCB must have the drive and                ;
        ;       filename fields (bytes 07H through 12H) and          ;
        ;       the extension flag (byte 00H) set before             ;
        ;       the call to FCB_next (see Function 29H).             ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_next,PUBLIC,ds
parmDP  puXFCB
cBegin
        loadDP  ds,dx,puXFCB    ; Pointer to unopened extended FCB.
        mov     ah,12h          ; Ask MS-DOS to find next matching
                                ; file in current directory.
        int     21h             ; If match found, directory entry can
                                ; be found at DTA address.
        cbw                     ; Set return value to 0 or -1.
cEnd



Interrupt 21H (33) Function 13H (19)
Delete File
1.0 and later


    Function 13H deletes all files matching a specified name and extension
    from the current directory.

To Call

    AH      = 13H
    DS:DX   = segment:offset of an unopened file control block (FCB)

Returns

    If function is successful:

    AL      = 00H

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  The wildcard character ? can be used to match any character or
        sequence of characters in specifying the filename and extension.

    ■  Open files must not be deleted.

    ■  Function 13H does not support pathnames.

    ■  An error (indicated by 0FFH returned in register AL) does not
        necessarily mean that the filename specified does not exist in the
        current directory. Other possible causes for an error include

        - Filename in the FCB is improperly specified.

        - File is a read-only, hidden, or system file and an extended FCB
        with the appropriate attribute byte was not used.

        - Program attempted to delete a volume label and the label does not
        exist or a properly formatted extended FCB was not used.

        - In networking environments, file is locked or access rights are
        insufficient for deletion.

    ■  MS-DOS removes file allocation table (FAT) mapping for the file or
        files deleted by this function and flushes the FAT to disk to
        ensure that the disk contains a correct table. The first character
        of the filename in the directory entry is replaced by the value
        0E5H, indicating a deleted file.

    ■  Because the function does not physically erase data, use of
        Function 13H alone is not sufficient in security-critical
        applications that strictly prohibit viewing the data.

    ■  On networks running under MS-DOS versions 3.1 and later, the user
        must have Create access rights to the directory containing the file
        to be deleted.

    ■  Because Function 13H deletes all files matching a given file
        specification, a conservative approach is to use a combination of
        Functions 11H (Find First File) and 12H (Find Next File) to build a
        list of files matching the file specification and then obtain
        confirmation from the user before deleting the files in the list.

    ■  With MS-DOS versions 2.0 and later, Function 41H (Delete File)
        should be used in preference to Function 13H.

Related Function

    41H (Delete File)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 13H: Delete File(s), FCB-based              ;
        ;                                                            ;
        ;       int FCB_delete(uXFCB)                                ;
        ;           char *uXFCB;                                     ;
        ;                                                            ;
        ;       Returns 0 if file(s) were deleted OK, otherwise       ;
        ;       returns -1.                                          ;
        ;                                                            ;
        ;       Note: uXFCB must have the drive and                  ;
        ;       filename fields (bytes 07H through 12H) and          ;
        ;       the extension flag (byte 00H) set before             ;
        ;       the call to FCB_delete (see Function 29H).           ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_delete,PUBLIC,ds
parmDP  puXFCB
cBegin
        loadDP  ds,dx,puXFCB    ; Pointer to unopened extended FCB.
        mov     ah,13h          ; Ask MS-DOS to delete file(s).
        int     21h
        cbw                     ; Return value of 0 or -1.
cEnd



Interrupt 21H (33) Function 14H (20)
Sequential Read
1.0 and later


    Function 14H reads the next sequential block of data from a file and
    places the data in the current disk transfer area (DTA).

To Call

    AH      = 14H
    DS:DX   = segment:offset of a previously opened file control
            block (FCB)

Returns

    AL      = 00H       read successful
            = 01H       end of file encountered; no data in record
            = 02H       DTA too small (segment wrap error); read
                        canceled
            = 03H       end of file; partial record read

    If AL = 00H or 03H:

    DTA contains data read from file.

Programmer's Notes

    ■  If necessary, Function 1AH (Set DTA Address) should be used to set
        the base address of the DTA before Function 14H is called. The
        default DTA is 128 bytes and is located at offset 80H of the
        program segment prefix (PSP). If record sizes larger than 128 bytes
        will be used, the program must change the DTA address to point to a
        buffer of adequate size.

    ■  The read process begins at the current position in the file. When
        the read is complete, Function 14H increments the current-block and
        current-record fields of the FCB.

    ■  The size of the record loaded into the DTA is specified in the
        record size field of the FCB. The default is 128 bytes, set by
        Function 0FH (Open File with FCB) or Function 16H (Create File with
        FCB). If the record size is not 128 bytes, the application must set
        the record size correctly before issuing any reads.

    ■  Function 0FH does not fill in the current-record field of the FCB
        when opening a file, so this field must be explicitly set (usually
        to zero) before the first call to Function 14H. The record pointer,
        which includes the current-block and current-record fields of the
        FCB, is incremented when Function 14H is successfully
        completed.

    ■  Function 14H deals with fixed-length records only. Buffering logic
        must be added to an application if variable-length records are to
        be manipulated.

    ■  The block of data to be read can be chosen by changing the current-
        block and current-record fields of the FCB.

    ■  Partial records read at the end of a file are padded with zeros to
        the requested record length.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Read access rights to the directory containing the file
        to be read.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) should be used in preference to Function 14H.

Related Functions

    15H (Sequential Write)
    1AH (Set DTA Address)
    21H (Random Read)
    27H (Random Block Read)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 14H: Sequential Read, FCB-based         ;
        ;                                                            ;
        ;           int FCB_sread(oXFCB)                             ;
        ;               char *oXFCB;                                 ;
        ;                                                            ;
        ;           Returns 0 if record read OK, otherwise           ;
        ;           returns error code 1, 2, or 3.                   ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_sread,PUBLIC,ds
parmDP  poXFCB
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     ah,14h          ; Ask MS-DOS to read next record,
                                ; placing it at DTA.
        int     21h
        cbw                     ; Clear high byte for return value.
cEnd



Interrupt 21H (33) Function 15H (21)
Sequential Write
1.0 and later


    Function 15H writes the next sequential block of data from the disk
    transfer area (DTA) to a specified file.

To Call

    AH      = 15H
    DS:DX   = segment:offset of a previously opened file control block
            (FCB)

    DTA contains data to write.

Returns

    AL      = 00H       block written successfully
            = 01H       disk full; write canceled
            = 02H       DTA too small (segment wrap error); write
                        canceled

Programmer's Notes

    ■  If necessary, the calling process should set the DTA address with
        Function 1AH (Set DTA Address) to point to the data to be written
        before issuing a call to Function 15H. The default address of the
        DTA is offset 80H in the program segment prefix (PSP).

    ■  The FCB must already have been filled in by a call to Function 0FH
        (Open File with FCB) before Function 15H is called.

    ■  The location of the block to be written is given by the current-
        block and current-record fields of the FCB. If the write is
        successful, Function 15H increments the current-block and current-
        record fields.

    ■  The size of the record written by Function 15H is determined by the
        value in the record size field of the FCB. The default value is
        128, set by Function 0FH (Open File with FCB) or Function 16H
        (Create File with FCB). A process must set the record size in the
        FCB correctly before issuing any writes.

    ■  Function 15H deals with fixed-length records only. Buffering logic
        must be added to an application if variable-length records are to
        be manipulated.

    ■  Function 15H performs a logical, but not necessarily physical,
        write operation. If less than one sector is being written, MS-DOS
        moves the record from the DTA to an appropriate MS-DOS internal
        buffer. When a full sector of data has been buffered, MS-DOS
        flushes the buffer to disk.  Function 0DH (Disk Reset) or Function
        10H (Close File with FCB) can be used to flush data to disk before
        a full sector is buffered.

    ■  On networks running under MS-DOS versions 3.1 and later, the user
        must have Write access to the directory containing the file to be
        written to.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device) should be used in preference to Function 15H.

Related Functions

    14H (Sequential Read)
    1AH (Set DTA Address)
    22H (Random Write)
    28H (Random Block Write)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 15H: Sequential Write, FCB-based         ;
        ;                                                            ;
        ;          int FCB_swrite(oXFCB)                             ;
        ;              char *oXFCB;                                  ;
        ;                                                            ;
        ;          Returns 0 if record read OK, otherwise            ;
        ;          returns error code 1 or 2.                        ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_swrite,PUBLIC,ds
parmDP  poXFCB
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     ah,15h          ; Ask MS-DOS to write next record
                                ; from DTA to disk file.
        int     21h
        cbw                     ; Clear high byte for return value.
cEnd



Interrupt 21H (33) Function 16H (22)
Create File with FCB
1.0 and later


    Function 16H creates a directory entry in the current directory for a
    specified file and opens the file for use. If the file already exists,
    it is opened and truncated to zero length.

To Call

    AH      = 16H
    DS:DX   = segment:offset of an unopened file control block (FCB)

Returns

    If function is successful:

    AL      = 00H

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  Before creating a new directory entry for the specified file,
        Function 16H searches the current directory for a matching
        filename. If a match is found, the existing file is opened, but its
        length is set to 0. In effect, this action erases an existing file
        and replaces it with a new, empty file of the same name.

        If a matching filename is not found and the directory has room for
        a new entry, the file is created and opened, and its length is set
        to 0.

    ■  An extended file control block (FCB) can be used to create a file
        with a special attribute, such as hidden. Before the Create File
        call is issued, the attribute byte must be set appropriately.

    ■  A value of 0FFH returned in the AL register can indicate one of
        several errors:

        - Filename was improperly specified in the FCB.

        - File with the same name exists but is a read-only, hidden,
        system, or (in MS-DOS versions 3.x and networks) locked
        file.

        - Disk is full.

        - Current working directory is the root directory, and it is
        full.

        - User does not have the appropriate access rights to create a file
        in this directory (in MS-DOS versions 3.x and networks).

        With MS-DOS versions 3.0 and later, Function 59H (Get Extended
        Error Information) can be used to obtain additional information
        about an error.

    ■  Upon successful completion of Function 16H, MS-DOS has

        - Created and opened the file specified in the FCB.

        - Filled in the date and time fields of the FCB with the current
        date and time.

        - Set file size to zero.

        All other changes made to the FCB are similar to those made by
        Function 0FH (Open File with FCB).

    ■  Pathnames and wildcard characters (? and *) are not supported by
        Function 16H.

    ■  With MS-DOS versions 2.0 and later, Function 16H has been
        superseded by Functions 3CH (Create File with Handle), 5AH (Create
        Temporary File), and 5BH (Create New File).

Related Functions

    0FH (Open File with FCB)
    3CH (Create File with Handle)
    3DH (Open File with Handle)
    5AH (Create Temporary File)
    5BH (Create New File)

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 16H: Create File, FCB-based               ;
        ;                                                            ;
        ;         int FCB_create(uXFCB,recsize)                      ;
        ;             char *uXFCB;                                   ;
        ;             int recsize;                                   ;
        ;                                                            ;
        ;         Returns 0 if file created OK, otherwise            ;
        ;         returns -1.                                        ;
        ;                                                            ;
        ;         Note: uXFCB must have the drive and filename       ;
        ;         fields (bytes 07H through 12H) and the             ;
        ;         extension flag (byte 00H) set before the           ;
        ;         call to FCB_create (see Function 29H).             ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_create,PUBLIC,ds
parmDP  puXFCB
parmW   recsize
cBegin
        loadDP  ds,dx,puXFCB    ; Pointer to unopened extended FCB.
        mov     ah,16h          ; Ask MS-DOS to create file.
        int     21h
        add     dx,7            ; Advance pointer to start of regular
                                ; FCB.
        mov     bx,dx           ; BX = FCB pointer.
        mov     dx,recsize      ; Get record size parameter.
        mov     [bx+0eh],dx     ; Store record size in FCB.
        xor     dx,dx
        mov     [bx+20h],dl     ; Set current-record
        mov     [bx+21h],dx     ; and relative-record
        mov     [bx+23h],dx     ; fields to 0.
        cbw                     ; Set return value to 0 or -1.
cEnd



Interrupt 21H (33) Function 17H (23)
Rename File
1.0 and later


    Function 17H renames one or more files in the current directory.

To Call

    AH      = 17H
    DS:DX   = segment:offset of modified file control block (FCB)
            in the following nonstandard format:

╓┌─────────────────────────────┌─────────────────────────────────────────────╖
            Byte(s)        Contents
            ───────────────────────────────────────────────────────────
            00H            Drive number
            01-08H         Old filename (padded with blanks, if
                            necessary)
            09-0BH         Old file extension (padded with blanks, if
                            necessary)
            0CH-10H        Zeroed out
            11H-18H        New filename (padded with blanks, if
                            necessary)
            19H-1BH        New file extension (padded with blanks, if
                            necessary)
            11CH-24H       Zeroed out

Returns

    If function is successful:

    AL      = 00H

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  The wildcard character ? can be used in specifying both the old and
        the new filenames, but its meaning differs in each case. A wildcard
        character in the old filename matches any single character or
        sequence of characters in the directory entry. A wildcard character
        in the new filename, however, indicates that the corresponding
        character or characters in the original filename are not to change.

    ■  With MS-DOS versions 2.0 and later, Function 17H views subdirectory
        entries as files. These subdirectory entries can be renamed using
        this function and an extended FCB with the appropriate attribute
        byte.

    ■  A value of 0FFH returned in the AL register can indicate one of
        several errors:

        - Old filename is improperly specified in the FCB.

        - File with the new filename already exists in the current
        directory.

        - Old file is a read-only file.

        - With MS-DOS versions 3.1 and later in a networking environment,
        the user has insufficient access rights to the directory.

        With MS-DOS versions 3.0 and later, Function 59H (Get Extended
        Error Information) can be used to obtain additional information
        about the cause of an error.

    ■  With MS-DOS versions 2.0 and later, Function 56H (Rename File)
        should be used in preference to Function 17H.

Related Function

    56H (Rename File)

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 17H: Rename File(s), FCB-based            ;
        ;                                                            ;
        ;         int FCB_rename(uXFCBold,uXFCBnew)                  ;
        ;             char *uXFCBold,*uXFCBnew;                      ;
        ;                                                            ;
        ;         Returns 0 if file(s) renamed OK, otherwise         ;
        ;         returns -1.                                        ;
        ;                                                            ;
        ;         Note: Both uXFCB's must have the drive and         ;
        ;         filename fields (bytes 07H through 12H) and        ;
        ;         the extension flag (byte 00H) set before           ;
        ;         the call to FCB_rename (see Function 29H).         ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_rename,PUBLIC,<ds,si,di>
parmDP  puXFCBold
parmDP  puXFCBnew
cBegin
        loadDP  es,di,puXFCBold ; ES:DI = Pointer to uXFCBold.
        mov     dx,di           ; Save offset in DX.
        add     di,7            ; Advance pointer to start of regular
                                ; FCBold.
        loadDP  ds,si,puXFCBnew ; DS:SI = Pointer to uXFCBnew.
        add     si,8            ; Advance pointer to filename field
                                ; FCBnew.
                                ; Copy name from FCBnew into FCBold
                                ; at offset 11H:
        add     di,11h          ; DI points 11H bytes into old FCB.
        mov     cx,0bh          ; Copy 0BH bytes, moving new
        rep     movsb           ; name into old FCB.
        push    es              ; Set DS to segment of FCBold.
        pop     ds
        mov     ah,17h          ; Ask MS-DOS to rename old
        int     21h             ; file(s) to new name(s).
        cbw                     ; Set return flag to 0 or -1.
cEnd



Interrupt 21H (33) Function 19H (25)
Get Current Disk
1.0 and later


    Function 19H returns the code for the current disk drive.

To Call

    AH   = 19H

Returns

    AL   = drive code (0 = drive A, 1 = drive B, 2 = drive C, and
            so on)

Programmer's Note

    ■  The drive code returned by Function 19H is zero-based, meaning that
        drive A = 0, drive B = 1, and so on. This value is unlike the drive
        code used in file control blocks (FCBs) and in some other MS-DOS
        functions, such as 1CH (Get Drive Data) and 36H (Get Disk Free
        Space), in which 0 indicates the default rather than the current
        drive.

Related Function

    0EH (Select Disk)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 19H: Get Current Disk                   ;
        ;                                                            ;
        ;           int cur_drive()                                  ;
        ;                                                            ;
        ;           Returns letter of current "logged" disk.         ;
        ;                                                            ;
        ;************************************************************;

cProc   cur_drive,PUBLIC
cBegin
        mov     ah,19h          ; Set function code.
        int     21h             ; Get number of logged disk.
        add     al,'A'          ; Convert number to letter.
        cbw                     ; Clear the high byte of return value.
cEnd



Interrupt 21H (33) Function 1AH (26)
Set DTA Address
1.0 and later


    Function 1AH specifies the location of the disk transfer area (DTA) to
    be used for file control block (FCB) disk I/O operations.

To Call

    AH      = 1AH
    DS:DX   = segment:offset of DTA

Returns

    Nothing

Programmer's Notes

    ■  If an application does not specify a disk transfer area, MS-DOS
        uses a default buffer at offset 80H in the program segment prefix
        (PSP).

    ■  The DTA specified must be large enough to accommodate the amount of
        data to be transferred in a single block. The default record size
        for FCB file operations is 128 bytes; this value can be changed
        after a file is successfully opened or created by altering the
        record size field in the FCB. If the DTA is too small for the
        record size used by the program, other code or data may be damaged.

    ■  The location of the DTA must be far enough from the top of the
        segment that contains it to avoid errors caused by segment wrap
        (data wrapping from the end of the segment to the beginning), which
        will cause the disk transfer to be terminated. Thus, for example,
        if records of 128 bytes are to be read, the highest location
        acceptable for the DTA is DS:FF80H.

    ■  The DTA is used by all FCB-based read and write functions. In
        addition, any application using the following functions must also
        set up a DTA for use as a scratch area in directory searches:

        - 11H (Find First File)

        - 12H (Find Next File)

        - 4EH (Find First File)

        - 4FH (Find Next File)

Related Function

    2FH (Get DTA Address)

Example

        ;************************************************************;
        ;                                                            ;
        ;                Function 1AH: Set DTA Address               ;
        ;                                                            ;
        ;                int set_DTA(pDTAbuffer)                     ;
        ;                    char far *pDTAbuffer;                   ;
        ;                                                            ;
        ;                Returns 0.                                  ;
        ;                                                            ;
        ;************************************************************;

cProc   set_DTA,PUBLIC,ds
parmD   pDTAbuffer
cBegin
        lds     dx,pDTAbuffer   ; DS:DX = pointer to buffer.
        mov     ah,1ah          ; Set function code.
        int     21h             ; Ask MS-DOS to change DTA address.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 1BH (27)
Get Default Drive Data
1.0 and later


    Function 1BH returns information about the disk in the default
    drive.

To Call

    AH      = 1BH

Returns

    If function is successful:

    AL      = number of sectors per cluster (allocation unit)
    CX      = number of bytes per sector
    DX      = number of clusters
    DS:BX   = segment:offset of the file allocation table (FAT)
            identification byte

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  If Function 1BH returns 0FFH in the AL register, the current drive
        was invalid or a disk error occurred. The most likely causes of the
        latter are

        - Drive door was open.

        - Disk was not ready.

        - Medium was bad.

        - Disk was unformatted.

        If any of these situations arises, MS-DOS issues Interrupt 24H
        (critical error). If Interrupt 24H has not been revectored to a
        critical error handler controlled by the program and the user
        responds Ignore to the MS-DOS Abort, Retry, Ignore? message, the
        error code 0FFH is returned to the program. An application should
        check the AL register for a value of 0FFH before assuming it has
        information on the default drive.

    ■  Possible values of the FAT ID byte (for IBM-compatible media) are
        the following:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Value    Medium
        ──────────────────────────────────────────────────────────────────
        0FFH     Double-sided, 8 sectors/track, 40 tracks/side
        0FEH     Single-sided, 8 sectors/track, 40 tracks/side
        0FDH     Double-sided, 9 sectors/track, 40 tracks/side
        0FCH     Single-sided, 9 sectors/track, 40 tracks/side
        0F9H     Double-sided, 15 sectors/track, 40 tracks/side
                or double-sided, 9 sectors/track, 80 tracks/side
        0F8H     Fixed disk
        0F0H     Others

    ■  With MS-DOS versions 1.x, Function 1BH returns a pointer in DS:BX
        for the actual memory image of the FAT. In MS-DOS versions 2.0 and
        later, the function returns a pointer in DS:BX for a copy of the
        FAT identification byte; the contents of memory beyond the
        identification byte are not necessarily the FAT memory image. If
        access to the FAT is necessary, Interrupt 25H (Absolute Disk Read)
        can be used to read it into memory.

    ■  The FAT ID byte is not enough to identify a drive completely in MS-
        DOS versions 2.0 and later. In these versions of MS-DOS, Function
        36H (Get Disk Free Space) should be used in preference to Function
        1BH to avoid the ambiguity caused by the FAT identification
        byte.

    ■  With MS-DOS versions 3.2 and later, additional drive information
        can be obtained by the BIOS parameter block (BPB) obtained with
        Function 44H (IOCTL) Subfunction 0DH (Generic I/O Control for
        Block Devices) minor code 60H (Get Device Parameters).

    ■  With MS-DOS versions 2.0 and later, Function 1CH (Get Drive Data)
        provides the same types of information as Function 1BH, but for a
        disk in a drive other than the default drive.

Related Functions

    1CH (Get Drive Data)
    36H (Get Disk Free Space)
    44H (IOCTL)

Example

    See SYSTEM CALLS: Interrupt 21H: Function 1CH.



Interrupt 21H (33) Function 1CH (28)
Get Drive Data
2.0 and later


    Function 1CH returns information about the disk in a specified
    drive.

To Call

    AH   = 1CH
    DL   = drive code (0 = default drive, 1 = drive A, 2 = drive B,
            3 = drive C, and so on)

Returns

    If function is successful:

    AL      = number of sectors per cluster (allocation unit)
    CX      = number of bytes per sector
    DX      = number of clusters
    DS:BX   = segment:offset of the file allocation table (FAT)
            identification byte

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  Function 1CH is not available with MS-DOS versions 1.x.

    ■  If the function returns 0FFH in the AL register, the drive code was
        invalid or a disk error occurred. The most likely causes of the
        latter are:

        - Drive door was open.

        - Disk was not ready.

        - Medium was bad.

        - Disk was unformatted.

        If any of these situations arises, MS-DOS issues Interrupt 24H
        (critical error). If Interrupt 24H has not been revectored to a
        critical error handler controlled by the program and the user
        responds Ignore to the MS-DOS Abort, Retry, Ignore? message, the
        error code 0FFH is returned to the program. An application should
        check the AL register for a value of 0FFH before assuming it has
        information on the specified drive.

    ■  Possible values of the FAT ID byte (for IBM-compatible media) are
        the following:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Value    Medium
        ──────────────────────────────────────────────────────────────────
        0FFH     Double-sided, 8 sectors/track, 40 tracks/side
        0FEH     Single-sided, 8 sectors/track, 40 tracks/side
        0FDH     Double-sided, 9 sectors/track, 40 tracks/side
        0FCH     Single-sided, 9 sectors/track, 40 tracks/side
        0F9H     Double-sided, 15 sectors/track, 40 tracks/side or double-
                sided, 9 sectors/track, 80 tracks/side
        0F8H     Fixed disk
        0F0H     Others

    ■  The contents of memory beyond the identification byte pointed to by
        DS:BX are not necessarily the FAT memory image. If access to the
        FAT is necessary, Interrupt 25H (Absolute Disk Read) can be used to
        read it into memory.

    ■  The FAT ID byte is not enough to identify a drive completely. To
        avoid the ambiguity caused by the FAT identification byte, Function
        36H (Get Disk Free Space) should be used in preference to Function
        1CH.

    ■  With MS-DOS versions 3.2 and later, additional drive information
        can be obtained by inspecting the BIOS parameter block (BPB)
        obtained with Function 44H (IOCTL) Subfunction 0DH (Generic I/O
        Control for Block Devices) minor code 60H (Get Device
        Parameters).

Related Functions

    1BH (Get Default Drive Data)
    36H (Get Disk Free Space)
    44H (IOCTL)

Example

        ;************************************************************;
        ;                                                            ;
        ;   Function 1CH: Get Drive Data                             ;
        ;                                                            ;
        ;   Get information about the disk in the specified          ;
        ;   drive.  Set drive_ltr to binary 0 for default drive info.;
        ;                                                            ;
        ;   int get_drive_data(drive_ltr,                            ;
        ;          pbytes_per_sector,                                ;
        ;          psectors_per_cluster,                             ;
        ;          pclusters_per_drive)                              ;
        ;        int  drive_ltr;                                     ;
        ;        int *pbytes_per_sector;                             ;
        ;        int *psectors_per_cluster;                          ;
        ;        int *pclusters_per_drive;                           ;
        ;                                                            ;
        ;   Returns -1 for invalid drive, otherwise returns          ;
        ;   the disk's type (from the 1st byte of the FAT).          ;
        ;                                                            ;
        ;************************************************************;

cProc   get_drive_data,PUBLIC,<ds,si>
parmB   drive_ltr
parmDP  pbytes_per_sector
parmDP  psectors_per_cluster
parmDP  pclusters_per_drive
cBegin
        mov     si,ds           ; Save DS in SI to use later.
        mov     dl,drive_ltr    ; Get drive letter.
        or      dl,dl           ; Leave 0 alone.
        jz      gdd
        and     dl,not 20h      ; Convert letter to uppercase.
        sub     dl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
gdd:
        mov     ah,1ch          ; Set function code.
        int     21h             ; Ask MS-DOS for data.
        cbw                     ; Extend AL into AH.
        cmp     al,0ffh         ; Bad drive letter?
        je      gddx            ; If so, exit with error code -1.
        mov     bl,[bx]         ; Get FAT ID byte from DS:BX.
        mov     ds,si           ; Get back original DS.
        loadDP  ds,si,pbytes_per_sector
        mov     [si],cx         ; Return bytes per sector.
        loadDP  ds,si,psectors_per_cluster
        mov     ah,0
        mov     [si],ax         ; Return sectors per cluster.
        loadDP  ds,si,pclusters_per_drive
        mov     [si],dx         ; Return clusters per drive.
        mov     al,bl           ; Return FAT ID byte.
gddx:
cEnd



Interrupt 21H (33) Function 21H (33)
Random Read
1.0 and later


    Function 21H reads a selected record from disk into memory.

To Call

    AH      = 21H
    DS:DX   = segment:offset of previously opened file control block (FCB)

Returns

    AL      = 00H  record read successfully
            = 01H  end of file; no record read
            = 02H  DTA too small (segment wrap error); read canceled
            = 03H  end of file; partial record transferred

    If AL = 00H or 03H:

    DTA contains data read from file.

Programmer's Notes

    ■  Function 21H reads the record into the current disk transfer area
        (DTA). Unless the 128-byte default DTA (at offset 80H in the
        program segment prefix) is adequate, Function 1AH (Set DTA Address)
        should be used to set the DTA address before Function 21H is
        called. The program must ensure that the buffer pointed to by the
        DTA address is large enough to hold the records to be
        transferred.

    ■  The relative-record field in the FCB must be set to the record
        number to be read. Numbering begins with record 00H; thus, the
        value 06H in the relative-record field would indicate the seventh
        record, not the sixth.

    ■  Function 21H sets the current-block and current-record fields to
        match the relative-record field before transferring the data to the
        DTA.

    ■  Unlike Function 27H (Random Block Read), Function 21H does not
        increment the current-block, current-record, or relative-record
        fields.

    ■  The record length read is determined by the record size field of
        the FCB.

    ■  If a partial record is read and the end of file is encountered, the
        remainder of the record is filled out to the requested length with
        zero bytes.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Read access rights to the directory containing the file
        to be read.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) should be used in preference to Function 21H.

Related Functions

    14H (Sequential Read)
    1AH (Set DTA Address)
    22H (Random Write)
    24H (Set Relative Record)
    27H (Random Block Read)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 21H: Random File Read, FCB-based         ;
        ;                                                            ;
        ;          int FCB_rread(oXFCB,recnum)                       ;
        ;              char *oXFCB;                                  ;
        ;              long recnum;                                  ;
        ;                                                            ;
        ;          Returns 0 if record read OK, otherwise            ;
        ;          returns error code 1, 2, or 3.                    ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_rread,PUBLIC,ds
parmDP  poXFCB
parmD   recnum
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     bx,dx           ; BX points at FCB, too.
        mov     ax,word ptr (recnum)    ; Get low 16 bits of record
        mov     [bx+28h],ax             ; number and store in FCB.
        mov     ax,word ptr (recnum+2)  ; Get high 16 bits of record
        mov     [bx+2ah],ax             ; number and store in FCB.
        mov     ah,21h          ; Ask MS-DOS to read recnum'th
                                ; record, placing it at DTA.
        int     21h
        cbw                     ; Clear high byte of return value.
cEnd



Interrupt 21H (33) Function 22H (34)
Random Write
1.0 and later


    Function 22H writes data from the current disk transfer area (DTA) to
    a specified record location in a file.

To Call

    AH      = 22H
    DS:DX   = segment:offset of previously opened file control block (FCB)

    DTA contains data to write.

Returns

    AL      = 00H  record written successfully
            = 01H  disk full
            = 02H  DTA too small (segment wrap error); write canceled

Programmer's Notes

    ■  Before calling Function 22H, the program must set the disk transfer
        area (DTA) address appropriately with a call to Function 1AH (Set
        DTA Address), if necessary, and place the data to be written in the
        DTA.

    ■  The relative-record field in the FCB must be set to the record
        number that is to be written. Numbering begins with record 00H;
        thus, the value 06H in the relative-record field would indicate the
        seventh record, not the sixth.

    ■  Function 22H sets the current-block and current-record fields to
        match the relative-record field before writing the data from the
        DTA.

    ■  Unlike Function 28H (Random Block Write), Function 22H does not
        increment the current-block, current-record, or relative-record
        fields.

    ■  The record size field determines the record length written by the
        function.

    ■  If a record is written beyond the current end of file, the data
        between the old end of file and the beginning of the new record is
        uninitialized.

    ■  The file that is written to cannot have the read-only attribute.

    ■  Information is written logically, but not always physically, to
        disk at the time Function 22H is called. The contents of the DTA
        are written immediately to disk only if they constitute a sector's
        worth of information. If less than a sector is written, it is
        transferred from the DTA to an MS-DOS buffer and is not physically
        written to disk until one of the following occurs:

        - A full sector of information is ready.

        - The file is closed.

        - Function 0DH (Disk Reset) is issued.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Write access rights to the directory containing the file
        to be written to.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device) should be used in preference to Function 22H.

Related Functions

    15H (Sequential Write)
    1AH (Set DTA Address)
    21H (Random Read)
    24H (Set Relative Record)
    28H (Random Block Write)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 22H: Random File Write, FCB-based        ;
        ;                                                            ;
        ;          int FCB_rwrite(oXFCB,recnum)                      ;
        ;              char *oXFCB;                                  ;
        ;              long recnum;                                  ;
        ;                                                            ;
        ;          Returns 0 if record read OK, otherwise            ;
        ;          returns error code 1 or 2.                        ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_rwrite,PUBLIC,ds
parmDP  poXFCB
parmD   recnum
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     bx,dx           ; BX points at FCB, too.
        mov     ax,word ptr (recnum)    ; Get low 16 bits of record
        mov     [bx+28h],ax             ; number and store in FCB.
        mov     ax,word ptr (recnum+2)  ; Get high 16 bits of record
        mov     [bx+2ah],ax             ; number and store in FCB.
        mov     ah,22h          ; Ask MS-DOS to write DTA to
        int     21h             ; recnum'th record of file.
        cbw                     ; Clear high byte for return value.
cEnd



Interrupt 21H (33) Function 23H (35)
Get File Size
1.0 and later


    Function 23H searches the current directory for a specified file and
    returns the size of the file in records.

To Call

    AH      = 23H
    DS:DX   = segment:offset of unopened file control block (FCB) with
            record size field set appropriately

Returns

    If function is successful:

    AL      = 00H

    FCB relative-record field contains number of records, rounded upward
    if necessary.

    If function is not successful:

    AL      = FFH

Programmer's Notes

    ■  The record size field in the FCB can be set to 1 to find the number
        of bytes in the file.

    ■  The number of records is the file size divided by the record size.
        If there is a remainder, the record count is rounded upward. The
        result stored in the relative-record field may, therefore, contain
        a value that is 1 larger than the number of complete records in the
        file.

    ■  Because record numbers are zero based and this function returns the
        number of records in a file in the relative-record field of the
        FCB, Function 23H can be used to position the file pointer to the
        end of file.

    ■  With MS-DOS versions 2.0 and later, Function 42H (Move File
        Pointer) should be used in preference to Function 23H.

Related Function

    42H (Move File Pointer)

Example

        ;************************************************************;
        ;                                                            ;
        ;      Function 23H: Get File Size, FCB-based                ;
        ;                                                            ;
        ;      long FCB_nrecs(uXFCB,recsize)                         ;
        ;           char *uXFCB;                                     ;
        ;           int recsize;                                     ;
        ;                                                            ;
        ;      Returns a long -1 if file not found, otherwise        ;
        ;      returns the number of records of size recsize.        ;
        ;                                                            ;
        ;      Note: uXFCB must have the drive and                   ;
        ;      filename fields (bytes 07H through 12H) and           ;
        ;      the extension flag (byte 00H) set before              ;
        ;      the call to FCB_nrecs (see Function 29H).             ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_nrecs,PUBLIC,ds
parmDP  puXFCB
parmW   recsize
cBegin
        loadDP  ds,dx,puXFCB    ; Pointer to unopened extended FCB.
        mov     bx,dx           ; Copy FCB pointer into BX.
        mov     ax,recsize      ; Get record size
        mov     [bx+15h],ax     ; and store it in FCB.
        mov     ah,23h          ; Ask MS-DOS for file size (in
                                ; records).
        int     21h
        cbw                     ; If AL = 0FFH, set AX to -1.
        cwd                     ; Extend to long.
        or      dx,dx           ; Is DX negative?
        js      nr_exit         ; If so, exit with error flag.
        mov     [bx+2bh],al     ; Only low 24 bits of the relative-
                                ; record field are used, so clear the
                                ; top 8 bits.
        mov     ax,[bx+28h]     ; Return file length in DX:AX.
        mov     dx,[bx+2ah]
nr_exit:
cEnd



Interrupt 21H (33) Function 24H (36)
Set Relative Record
1.0 and later


    Function 24H sets the relative-record field of a file control block
    (FCB) to match the file position indicated by the current-block and
    current-record fields of the same FCB.

To Call

    AH      = 24H
    DS:DX   = segment:offset of previously opened FCB

Returns

    AL      = 00H

    Relative-record field is modified in FCB.

Programmer's Notes

    ■  The AL register is always set to 00H by Function 24H. Thus, any
        preexisting information in the AL register is lost.

    ■  Before Function 24H is called, the program must open the FCB with
        Function 0FH (Open File with FCB) or with Function 16H (Create File
        with FCB).

    ■  The entire relative-record field (4 bytes) of the FCB must be
        initialized to zeros before calling Function 24H. If this is not
        done, any value in the high-order byte of the high-order word
        remaining from previous reads or writes might not be overwritten
        and the resulting relative-record number will be invalid.

    ■  Function 24H is normally used in changing from sequential to random
        I/O. Sequential I/O, performed by Functions 14H (Sequential Read)
        and 15H (Sequential Write), sets the current-block and current-
        record fields of the FCB. Random I/O uses the relative-record
        field, which is set by Function 24H to match the current file
        position as recorded in the current-block and current-record
        fields.

        After the file pointer is set, any of the following functions can
        be used to access data at the record pointed to by the relative-
        record field:

        - 21H (Random Read)

        - 22H (Random Write)

        - 27H (Random Block Read)

        - 28H (Random Block Write)

    ■  With MS-DOS versions 2.0 and later, Function 42H (Move File
        Pointer) should be used in preference to Function 24H.

Related Function

    42H (Move File Pointer)

Example

        ;************************************************************;
        ;                                                            ;
        ;              Function 24H: Set Relative Record             ;
        ;                                                            ;
        ;              int FCB_set_rrec(oXFCB)                       ;
        ;                  char *oXFCB;                              ;
        ;                                                            ;
        ;              Returns 0.                                    ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_set_rrec,PUBLIC,ds
parmDP  poXFCB
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     bx,dx           ; BX points at FCB, too.
        mov     byte ptr [bx+2bh],0 ; Zero high byte of high word of
                                    ; relative-record field.
        mov     ah,24h          ; Ask MS-DOS to set relative record
                                ; to current record.
        int     21h
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 25H (37)
Set Interrupt Vector
1.0 and later


    Function 25H sets an address in the interrupt vector table to point to
    a specified interrupt handler.

To Call

    AH      = 25H
    AL      = interrupt number
    DS:DX   = segment:offset of interrupt handler

Returns

    Nothing

Programmer's Notes

    ■  When Function 25H is called, the 4-byte address in DS:DX is placed
        in the correct position in the interrupt vector table.

    ■  Function 25H is the recommended method for initializing or changing
        an interrupt vector. A vector in the interrupt vector table should
        never be changed directly.

    ■  Before Function 25H is used to change an interrupt vector, the
        address of the current interrupt handler should be read with
        Function 35H (Get Interrupt Vector) and then saved for restoration
        before the program terminates.

Related Function

    35H (Get Interrupt Vector)

Example

        ;************************************************************;
        ;                                                            ;
        ;              Function 25H: Set Interrupt Vector            ;
        ;                                                            ;
        ;              typedef void (far *FCP)();                    ;
        ;              int set_vector(intnum,vector)                 ;
        ;                  int intnum;                               ;
        ;                  FCP vector;                               ;
        ;                                                            ;
        ;              Returns 0.                                    ;
        ;                                                            ;
        ;************************************************************;

cProc   set_vector,PUBLIC,ds
parmB   intnum
parmD   vector
cBegin
        lds     dx,vector       ; Get vector segment:offset into
                                ; DS:DX.
        mov     al,intnum       ; Get interrupt number into AL.
        mov     ah,25h          ; Select "set vector" function.
        int     21h             ; Ask MS-DOS to change vector.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 26H (38)
Create New Program Segment Prefix
1.0 and later


    Function 26H creates a new program segment prefix (PSP) at a specified
    segment address.

To Call

    AH   = 26H
    DX   = segment address of the PSP to create

Returns

    Nothing

Programmer's Notes

    ■  Function 26H copies the current PSP to the address indicated by DX.
        Note that DX contains a segment address, not an absolute
        address.

    ■  After the copy is made, the memory size information located at
        offset 06H in the new PSP is adjusted to match the amount of memory
        available to the new PSP. In addition, the current contents of the
        interrupt vectors for Interrupt 22H (Terminate Routine Address),
        Interrupt 23H (Control-C Handler Address), and Interrupt 24H
        (Critical Error Handler Address) are saved starting at offset 0AH
        of the new PSP.

    ■  A .COM file can be loaded into memory immediately after the new PSP
        and execution can begin at that location. A .EXE file cannot be
        loaded and executed in this manner.

    ■  With MS-DOS versions 2.0 and later, Function 4BH (Load and Execute
        Program) should be used in preference to Function 26H. Function 4BH
        can be used to load .COM files, .EXE files, or overlays.

Related Function

    4BH (Load and Execute Program)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 26H: Create New Program Segment Prefix      ;
        ;                                                            ;
        ;       int create_psp(pspseg)                               ;
        ;           int  pspseg;                                     ;
        ;                                                            ;
        ;       Returns 0.                                           ;
        ;                                                            ;
        ;************************************************************;


cProc   create_psp,PUBLIC
parmW   pspseg
cBegin
        mov     dx,pspseg       ; Get segment address of new PSP.
        mov     ah,26h          ; Set function code.
        int     21h             ; Ask MS-DOS to create new PSP.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 27H (39)
Random Block Read
1.0 and later


    Function 27H reads one or more records into memory, placing the
    records in the current disk transfer area (DTA).

To Call

    AH      = 27H
    CX      = number of records to read
    DS:DX   = segment:offset of previously opened file control block (FCB)

Returns

    AL      = 00H  read successful
            = 01H  end of file; no record read
            = 02H  DTA too small (segment wrap error); no record read
            = 03H  end of file; partial record read

    If AL is 00H or 03H:

    CX      = number of records read

    DTA contains data read from file.

Programmer's Notes

    ■  The DTA address should be set with Function 1AH (Set DTA Address)
        before Function 27H is called. If the DTA address has not been set,
        MS-DOS uses a default 128-byte DTA at offset 80H in the program
        segment prefix (PSP).

    ■  Function 27H reads the number of records specified in CX
        sequentially, starting at the file location indicated by the
        relative-record and record size fields in the FCB. If CX = 0, no
        records are read.

    ■  The record length used by Function 27H is the value in the record
        size field of the FCB. Unless a new value is placed in this field
        after a file is opened or created, MS-DOS uses a default record
        length of 128 bytes.

    ■  Function 27H is similar to Function 21H (Random Read); however,
        Function 27H can read more than one record at a time and updates
        the relative-record field of the FCB after each call. Successive
        calls to this function thus read sequential groups of records from
        a file, whereas successive calls to Function 21H repeatedly read
        the same record.

    ■  Possible alternative causes for end-of-file (01H) errors include:

        - Disk removed from drive since file was opened.

        - Previous open failed.

        With MS-DOS versions 3.0 and later, more detailed information on
        the error can be obtained by calling Function 59H (Get Extended
        Error Information).

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Read access rights to the directory containing the file
        to be read.

    ■  With MS-DOS versions 2.0 and later, Function 3FH (Read File or
        Device) should be used in preference to Function 27H.

Related Functions

    14H (Sequential Read)
    1AH (Set DTA Address)
    21H (Random Read)
    24H (Set Relative Record)
    28H (Random Block Write)
    3FH (Read File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;      Function 27H: Random File Block Read, FCB-based       ;
        ;                                                            ;
        ;      int FCB_rblock(oXFCB,nrequest,nactual,start)          ;
        ;          char *oXFCB;                                      ;
        ;          int   nrequest;                                   ;
        ;          int  *nactual;                                    ;
        ;          long  start;                                      ;
        ;                                                            ;
        ;      Returns read status 0, 1, 2, or 3 and sets            ;
        ;      nactual to number of records actually read.           ;
        ;                                                            ;
        ;      If start is -1, the relative-record field is          ;
        ;      not changed, causing the block to be read starting    ;
        ;      at the current record.                                ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_rblock,PUBLIC,<ds,di>
parmDP  poXFCB
parmW   nrequest
parmDP  pnactual
parmD   start
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     di,dx           ; DI points at FCB, too.
        mov     ax,word ptr (start) ; Get long value of start.
        mov     bx,word ptr (start+2)
        mov     cx,ax           ; Is start = -1?
        and     cx,bx
        inc     cx
        jcxz    rb_skip         ; If so, don't change relative-record
                                ; field.
        mov     [di+28h],ax     ; Otherwise, seek to start record.
        mov     [di+2ah],bx
rb_skip:
        mov     cx,nrequest     ; CX = number of records to read.
        mov     ah,27h          ; Get MS-DOS to read CX records,
        int     21h             ; placing them at DTA.
        loadDP  ds,bx,pnactual  ; DS:BX = address of nactual.
        mov     [bx],cx         ; Return number of records read.
        cbw                     ; Clear high byte.
cEnd



Interrupt 21H (33) Function 28H (40)
Random Block Write
1.0 and later


    Function 28H writes one or more records from the current disk transfer
    area (DTA) to a file.

To Call

    AH      = 28H
    CX      = number of records to write
    DS:DX   = segment:offset of previously opened file control block (FCB)

    DTA contains data to write.

Returns

    AL      = 00H  write successful
            = 01H  disk full
            = 02H  DTA too small (segment wrap error); write canceled

    If AL is 00H or 01H:

    CX      = number of records written

Programmer's Notes

    ■  Data to be written must be placed in the DTA before Function 28H is
        called. Unless the DTA address has been set with Function 1AH (Set
        DTA Address), MS-DOS uses a default 128-byte DTA at offset 80H in
        the program segment prefix (PSP).

    ■  Function 28H writes the number of records indicated in CX,
        beginning at the location specified in the relative-record field of
        the file control block (FCB). If Function 28H is called with CX =
        0, the file is truncated or extended to the size indicated by the
        record-size and relative-record fields of the FCB.

    ■  The record length used by Function 28H is the value in the record
        size field of the FCB. Unless a new value is assigned after a file
        is opened or created, MS-DOS uses a default record length of 128
        bytes.

    ■  Function 28H is similar to Function 22H (Random Write); however,
        Function 28H can write more than one record at a time and updates
        the relative-record field of the FCB after each call. Successive
        calls to this function thus write sequential groups of records to a
        file, whereas successive calls to Function 22H repeatedly write the
        same record.

    ■  Possible alternative causes for disk full (01H) errors include:

        - Disk removed from drive since file was opened.

        - Previous open failed.

        In MS-DOS versions 3.0 and later, more detailed information on the
        error can be obtained by calling Function 59H (Get Extended Error
        Information).

    ■  Information is written logically, but not always physically, to
        disk at the time Function 28H is called. The contents of the DTA
        are written immediately to disk only if they constitute a full
        sector of information. If less than a sector is written, it is
        transferred from the DTA to an MS-DOS buffer and is not physically
        written to disk until one of the following occurs:

        - A full sector of information is ready.

        - The file is closed.

        - Function 0DH (Disk Reset) is issued.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Write access rights to the directory containing the file
        to be written to.

    ■  With MS-DOS versions 2.0 and later, Function 40H (Write File or
        Device) should be used in preference to Function 28H.

Related Functions

    15H (Sequential Write)
    1AH (Set DTA Address)
    22H (Random Write)
    24H (Set Relative Record)
    27H (Random Block Read)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 28H: Random File Block Write, FCB-based     ;
        ;                                                            ;
        ;       int FCB_wblock(oXFCB,nrequest,nactual,start)         ;
        ;           char *oXFCB;                                     ;
        ;           int   nrequest;                                  ;
        ;           int  *nactual;                                   ;
        ;           long  start;                                     ;
        ;                                                            ;
        ;       Returns write status of 0, 1, or 2 and sets          ;
        ;       nactual to number of records actually written.       ;
        ;                                                            ;
        ;       If start is -1, the relative-record field is         ;
        ;       not changed, causing the block to be written         ;
        ;       starting at the current record.                      ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_wblock,PUBLIC,<ds,di>
parmDP  poXFCB
parmW   nrequest
parmDP  pnactual
parmD   start
cBegin
        loadDP  ds,dx,poXFCB    ; Pointer to opened extended FCB.
        mov     di,dx           ; DI points at FCB, too.
        mov     ax,word ptr (start) ; Get long value of start.
        mov     bx,word ptr (start+2)
        mov     cx,ax           ; Is start = -1?
        and     cx,bx
        inc     cx
        jcxz    wb_skip         ; If so, don't change relative-record
                                ; field.
        mov     [di+28h],ax     ; Otherwise, seek to start record.
        mov     [di+2ah],bx
wb_skip:
        mov     cx,nrequest     ; CX = number of records to write.
        mov     ah,28h          ; Get MS-DOS to write CX records
        int     21h             ; from DTA to file.
        loadDP  ds,bx,pnactual  ; DS:BX = address of nactual.
        mov     ds:[bx],cx      ; Return number of records written.
        cbw                     ; Clear high byte.
cEnd



Interrupt 21H (33) Function 29H (41)
Parse Filename
1.0 and later


    Function 29H examines a string for a valid filename in the form
    drive:filename.ext. If the string represents a valid filename,
    the function creates an unopened file control block (FCB) for it.

To Call

    AH      = 29H
    AL      = code to control parsing, as follows (bits 0-3 only):

╓┌──────────────┌──────┌─────────────────────────────────────────────────────╖
        Bit    Value  Meaning
        ──────────────────────────────────────────────────────────────────
        0      0      Stop parsing if file separator is found.

            1      Ignore leading separators (parse off white space).

        1      0      Set drive number field in FCB to 0 (current drive) if
                    string does not include a drive identifier.

            1      Set drive as specified in the string; leave unaltered
                    if string does not include a drive identifier.

        2      0      Set filename field in the FCB to blanks (20H) if
                    string does not include a filename.

            1      Leave filename field unaltered if string does not
                    include a filename.

        3      0      Set extension field in FCB to blanks (20H) if string
                    does not include a filename extension.

            1      Leave extension field unaltered if string does not
                    include a filename extension.

    DS:SI   = segment:offset of string to parse
    ES:DI   = segment:offset of buffer for unopened FCB

Returns

    AL      = 00H  string does not contain wildcard characters
            = 01H  string contains wildcard characters
            = FFH  drive specifier invalid
    DS:SI   = segment:offset of first byte following the parsed string
    ES:DI   = segment:offset of unopened FCB

Programmer's Notes

    ■  Bits 0 through 3 of the byte in the AL register control the way the
        text string is parsed; bits 4 through 7 are not used and must be 0.

    ■  After MS-DOS parses the string, DS:SI points to the first byte
        following the parsed string. If DS:SI points to an earlier byte,
        MS-DOS did not parse the entire string.

    ■  If Function 29H encounters the MS-DOS wildcard character * (match
        all remaining characters) in a filename or extension, the remaining
        bytes in the corresponding FCB field are set to the wildcard
        character ? (match one character). For example, the string DOS*.D*
        would be converted to DOS????? in the filename field and D?? in the
        extension field of the FCB.

    ■  With MS-DOS versions 1.x, the following characters are filename
        separators:

        : . ; , = + space tab / " [ ]

        With MS-DOS versions 2.0 and later, the following characters are
        filename separators:

        : . ; , = + space tab

    ■  The following characters are filename terminators:

        / " [ ] < > |
        All filename separators
        Any control character

    ■  If the string does not contain a valid filename, ES:DI+1 points to
        an ASCII blank character (20H).

    ■  Function 29H cannot parse pathnames.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 29H: Parse Filename into FCB           ;
        ;                                                            ;
        ;            int FCB_parse(uXFCB,name,ctrl)                  ;
        ;                char *uXFCB;                                ;
        ;                char *name;                                 ;
        ;                int ctrl;                                   ;
        ;                                                            ;
        ;            Returns -1 if error,                            ;
        ;                     0 if no wildcards found,               ;
        ;                     1 if wildcards found.                  ;
        ;                                                            ;
        ;************************************************************;

cProc   FCB_parse,PUBLIC,<ds,si,di>
parmDP  puXFCB
parmDP  pname
parmB   ctrl
cBegin
        loadDP  es,di,puXFCB    ; Pointer to unopened extended FCB.
        push    di              ; Save DI.
        xor     ax,ax           ; Fill all 22 (decimal) words of the
                                ; extended FCB with zeros.
        cld                     ; Make sure direction flag says UP.
        mov     cx,22d
        rep     stosw
        pop     di              ; Recover DI.
        mov     byte ptr [di],0ffh ; Set flag byte to mark this as an
                                ; extended FCB.
        add     di,7            ; Advance pointer to start of regular
                                ; FCB.
        loadDP  ds,si,pname     ; Get pointer to filename into DS:SI.
        mov     al,ctrl         ; Get parse control byte.
        mov     ah,29h          ; Parse filename, please.
        int     21h
        cbw                     ; Set return parameter.
cEnd



Interrupt 21H (33) Function 2AH (42)
Get Date
1.0 and later


    Function 2AH returns the current system date--year, month, day, and
    day of the week--in binary form.

To Call

    AH   = 2AH

Returns

    AL   = day of the week (0 = Sunday, 1 = Monday, 2 = Tuesday, and so
            on; MS-DOS versions 1.10 and later)
    CX   = year (1980 through 2099)
    DH   = month (1 through 12)
    DL   = day (1 through 31)

Programmer's Note

    ■  Years outside the range 1980-2099 cannot be returned by Function
        2AH.

Related Functions

    2BH (Set Date)
    2CH (Get Time)
    2DH (Set Time)

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 2AH: Get Date                          ;
        ;                                                            ;
        ;            long get_date(pdow,pmonth,pday,pyear)           ;
        ;                 char *pdow,*pmonth,*pday;                  ;
        ;                 int *pyear;                                ;
        ;                                                            ;
        ;            Returns the date packed into a long:            ;
        ;                 low byte  = day of month                   ;
        ;                 next byte = month                          ;
        ;                 next word = year.                          ;
        ;                                                            ;
        ;************************************************************;

cProc   get_date,PUBLIC,ds
parmDP  pdow
parmDP  pmonth
parmDP  pday
parmDP  pyear
cBegin
        mov     ah,2ah          ; Set function code.
        int     21h             ; Get date info from MS-DOS.
        loadDP  ds,bx,pdow      ; DS:BX = pointer to dow.
        mov     [bx],al         ; Return dow.
        loadDP  ds,bx,pmonth    ; DS:BX = pointer to month.
        mov     [bx],dh         ; Return month.
        loadDP  ds,bx,pday      ; DS:BX = pointer to day.
        mov     [bx],dl         ; Return day.
        loadDP  ds,bx,pyear     ; DS:BX = pointer to year.
        mov     [bx],cx         ; Return year.
        mov     ax,dx           ; Pack day, month, ...
        mov     dx,cx           ; ... and year into return value.
cEnd



Interrupt 21H (33) Function 2BH (43)
Set Date
1.0 and later


    Function 2BH accepts binary values for the year, month, and day of the
    month and stores them in the system's date counter as the number of
    days since January 1, 1980.

To Call

    AH   = 2BH
    CX   = year (1980 through 2099)
    DH   = month (1 through 12)
    DL   = day (1 through 31)

Returns

    AL   = 00H       system date updated
        = FFH       invalid date specified

Programmer's Note

    ■  The year must be a 16-bit value in the range 1980 through 2099.
        Values outside this range are not accepted. In addition, supplying
        only the last two digits of the year causes an error.

Related Functions

    2AH (Get Date)
    2CH (Get Time)
    2DH (Set Time)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 2BH: Set Date                         ;
        ;                                                            ;
        ;             int set_date(month,day,year)                   ;
        ;                 char month,day;                            ;
        ;                 int year;                                  ;
        ;                                                            ;
        ;             Returns 0 if date was OK, -1 if not.           ;
        ;                                                            ;
        ;************************************************************;

cProc   set_date,PUBLIC
parmB   month
parmB   day
parmW   year
cBegin
        mov     dh,month        ; Get new month.
        mov     dl,day          ; Get new day.
        mov     cx,year         ; Get new year.
        mov     ah,2bh          ; Set function code.
        int     21h             ; Ask MS-DOS to change date.
        cbw                     ; Return 0 or -1.
cEnd



Interrupt 21H (33) Function 2CH (44)
Get Time
1.0 and later


    Function 2CH reports the current system time--hours (based on a 24-
    hour clock), minutes, seconds, and hundredths of a second--in binary
    form.

To Call

    AH   = 2CH

Returns

    CH   = hours (0 through 23)
    CL   = minutes (0 through 59)
    DH   = seconds (0 through 59)
    DL   = hundredths of second (0 through 99)

Programmer's Note

    ■  The accuracy of the time returned by Function 2CH depends on the
        accuracy of the system's timekeeping hardware. On systems unable to
        resolve time to the hundredth of a second, the DL register may
        contain either 00H or an approximate value calculated by an MS-DOS
        algorithm.

Related Functions

    2AH (Get Date)
    2BH (Set Date)
    2DH (Set Time)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 2CH: Get Time                         ;
        ;                                                            ;
        ;             long get_time(phour,pmin,psec,phund)           ;
        ;                  char *phour,*pmin,*psec,*phund;           ;
        ;                                                            ;
        ;             Returns the time packed into a long:           ;
        ;                  low byte  = hundredths                    ;
        ;                  next byte = seconds                       ;
        ;                  next byte = minutes                       ;
        ;                  next byte = hours.                        ;
        ;                                                            ;
        ;************************************************************;

cProc   get_time,PUBLIC,ds
parmDP  phour
parmDP  pmin
parmDP  psec
parmDP  phund
cBegin
        mov     ah,2ch          ; Set function code.
        int     21h             ; Get time from MS-DOS.
        loadDP  ds,bx,phour     ; DS:BX = pointer to hour.
        mov     [bx],ch         ; Return hour.
        loadDP  ds,bx,pmin      ; DS:BX = pointer to min.
        mov     [bx],cl         ; Return min.
        loadDP  ds,bx,psec      ; DS:BX = pointer to sec.
        mov     [bx],dh         ; Return sec.
        loadDP  ds,bx,phund     ; DS:BX = pointer to hund.
        mov     [bx],dl         ; Return hund.
        mov     ax,dx           ; Pack seconds, hundredths, ...
        mov     dx,cx           ; ... minutes, and hour into
                                ; return value.
cEnd



Interrupt 21H (33) Function 2DH (45)
Set Time
1.0 and later


    Function 2DH accepts binary values for the hour (based on a 24-hour
    clock), minute, second, and hundredths of a second and stores them in
    the operating system's time counter.

To Call

    AH   = 2DH
    CH   = hours (0 through 23)
    CL   = minutes (0 through 59)
    DH   = seconds (0 through 59)
    DL   = hundredths of second (0 through 99)

Returns

    AL   = 00H       time successfully updated
        = FFH       invalid time specified

Programmer's Note

    ■  On systems that are unable to resolve the time to the hundredth of
        a second, the DL register should be set to 00H before Function 2DH
        is called.

Related Functions

    2AH (Get Date)
    2BH (Set Date)
    2CH (Get Time)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 2DH: Set Time                         ;
        ;                                                            ;
        ;             int set_time(hour,min,sec,hund)                ;
        ;                 char hour,min,sec,hund;                    ;
        ;                                                            ;
        ;             Returns 0 if time was OK, -1 if not.           ;
        ;                                                            ;
        ;************************************************************;

cProc   set_time,PUBLIC
parmB   hour
parmB   min
parmB   sec
parmB   hund
cBegin
        mov     ch,hour         ; Get new hour.
        mov     cl,min          ; Get new minutes.
        mov     dh,sec          ; Get new seconds.
        mov     dl,hund         ; Get new hundredths.
        mov     ah,2dh          ; Set function code.
        int     21h             ; Ask MS-DOS to change time.
        cbw                     ; Return 0 or -1.
cEnd



Interrupt 21H (33) Function 2EH (46)
Set/Reset Verify Flag
1.0 and later


    Function 2EH turns the internal MS-DOS verify flag on or off, thus
    determining whether MS-DOS verifies disk write operations.

To Call

    AH   = 2EH
    AL   = 00H       turn verify off
        = 01H       turn verify on
    DL   = 00H (MS-DOS versions 1.x and 2.x only)

Returns

    Nothing

Programmer's Notes

    ■  If the verify flag is on, MS-DOS requests any block-device driver
        to verify each sector written. If the driver does not support read-
        after-write verification, the verify flag has no effect.

    ■  Function 54H (Get Verify Flag) can be used to check the current
        setting of the verify flag.

    ■  Verifying data slows disk access during write operations. Because
        disk errors are rare, the default setting of the verify flag is
        off.

    ■  Verification can be controlled at the user level with the MS-DOS
        VERIFY command.

Related Function

    54H (Get Verify Flag)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 2EH: Set/Reset Verify Flag            ;
        ;                                                            ;
        ;             int set_verify(newvflag)                       ;
        ;                 char newvflag;                             ;
        ;                                                            ;
        ;             Returns 0.                                     ;
        ;                                                            ;
        ;************************************************************;

cProc   set_verify,PUBLIC
parmB   newvflag
cBegin
        mov     al,newvflag     ; Get new value of verify flag.
        mov     ah,2eh          ; Set function code.
        int     21h             ; Ask MS-DOS to store flag.
        xor     ax,ax           ; Return 0.
cEnd



Interrupt 21H (33) Function 2FH (47)
Get DTA Address
2.0 and later


    Function 2FH returns the current disk transfer area (DTA)
    address.

To Call

    AH      = 2FH

Returns

    ES:BX   = segment:offset of current DTA address

Programmer's Notes

    ■  Function 2FH returns the base address of the current DTA. MS-DOS
        has no way of knowing the size of the buffer at that address; the
        program must ensure that the buffer pointed to by the DTA address
        is large enough to hold any records transferred to it.

    ■  The current DTA address can be set with Function 1AH (Set DTA
        Address). If the DTA address is not set, MS-DOS uses a default
        buffer of 128 bytes located at offset 80H in the program segment
        prefix (PSP).

Related Function

    1AH (Set DTA Address)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 2FH: Get DTA Address                    ;
        ;                                                            ;
        ;           char far *get_DTA()                              ;
        ;                                                            ;
        ;           Returns a far pointer to the DTA buffer.         ;
        ;                                                            ;
        ;************************************************************;

cProc   get_DTA,PUBLIC
cBegin
        mov     ah,2fh          ; Set function code.
        int     21h             ; Ask MS-DOS for current DTA address.
        mov     ax,bx           ; Return offset in AX.
        mov     dx,es           ; Return segment in DX.
cEnd



Interrupt 21H (33) Function 30H (48)
Get MS-DOS Version Number
2.0 and later


    Function 30H returns the major and minor version numbers for MS-DOS
    versions 2.0 and later.

To Call

    AH      = 30H
    AL      = 00H

Returns

    AL      = major version number (for example, 3 for MS-DOS version 3.x)
    AH      = minor version number (for example, 0AH for MS-DOS version
            x.10)
    BH      = original equipment manufacturer's (OEM's) serial number (OEM
            dependent--usually 00H for PC-DOS, 0FFH or other values for
            MS-DOS)
    BL:CX   = 24-bit user serial number (optional; OEM dependent)

Programmer's Notes

    ■  With MS-DOS versions 1.x, Function 30H returns 00H in the AL
        register; the value returned in AH is variable and not
        representative of the actual 1.x minor version number.

    ■  Function 30H supplies the MS-DOS version number to an application
        program that might require features of the operating system that
        are not available in all versions. If an application attempts to
        use such features with the wrong version of MS-DOS, the results are
        unpredictable.

        Applications requiring MS-DOS version 2.0 or later should use
        Function 30H to check for versions 1.x. Because versions 1.x do not
        contain predefined handles for displaying error messages, Function
        02H (Character Output) or Function 09H (Display String) must be
        used with those versions. Similarly, applications running under
        versions 1.x cannot terminate through a call to Function 4CH
        (Terminate Process with Return Code).

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 30H: Get MS-DOS Version Number          ;
        ;                                                            ;
        ;           int DOS_version()                                ;
        ;                                                            ;
        ;           Returns number of MS-DOS version, with           ;
        ;              major version in high byte,                   ;
        ;              minor version in low byte.                    ;
        ;                                                            ;
        ;************************************************************;

cProc   DOS_version,PUBLIC
cBegin
        mov     ax,3000H        ; Set function code and clear AL.
        int     21h             ; Ask MS-DOS for version number.
        xchg    al,ah           ; Swap major and minor numbers.
cEnd



Interrupt 21H (33) Function 31H (49)
Terminate and Stay Resident
2.0 and later


    Function 31H terminates a program and returns control to the parent
    process (usually COMMAND.COM) but keeps the terminated program
    resident in memory.

To Call

    AH   = 31H
    AL   = return code
    DX   = number of paragraphs of memory to be reserved for current
            process

Returns

    Nothing

Programmer's Notes

    ■  The following interrupt vectors are restored from the program
        segment prefix (PSP) of the terminated program:

╓┌─────────────────────┌─────────────────────────────────────────────────────╖
        PSP Offset    Vector for Interrupt
        ──────────────────────────────────────────────────────────────────
        0AH           Interrupt 22H (terminate routine)
        0EH           Interrupt 23H (Control-C handler)
        12H           Interrupt 24H (critical error handler)
                    (versions 2.0 and later.)

    ■  The minimum amount of memory a process can reserve is 6 paragraphs
        (60H bytes), which constitutes the initial portion of the process's
        PSP (including the reserved areas).

    ■  The amount of memory required by the program is not necessarily the
        same as the size of the file that holds the program on disk.
        The program must allow for its PSP and stack in the amount of
        memory reserved; on the other hand,the memory occupied by code and
        data used only during program initialization frequently can be
        discarded as a side effect of the Function 31H call.

        Before Function 31H is called, memory allocated to the terminating
        process's environment block should be released  by loading ES with
        the segment value at offset 2CH in the PSP (the segment address of
        the environment) and calling Function 49H (Free Memory Block).

    ■  The terminating process should return a completion code in the AL
        register. If the program terminates normally, the return code
        should be 00H. A return code of 01H or greater usually indicates
        that termination was caused by an error encountered by the process.

        The parent process can retrieve the return code with Function 4DH
        (Get Return Code of Child Process). If control returns to
        COMMAND.COM, the return code can be tested with an ERRORLEVEL
        statement in a batch file.

    ■  After terminating the current process, MS-DOS attempts to set the
        program's memory allocation to the amount specified in DX.

    ■  Function 31H is most often used for memory-resident utilities and
        subroutine libraries that can be accessed using interrupts.

    ■  This function is preferable to Interrupt 27H (Terminate and Stay
        Resident) because it allows programs that are larger than 64 KB to
        remain resident, allows the terminating program to pass a return
        code to the parent process, and does not require that the CS
        register contain the PSP address.

Related Functions

    48H (Allocate Memory Block)
    49H (Free Memory Block)
    4AH (Resize Memory Block)
    4BH (Load and Execute Program)
    4CH (Terminate Process with Return Code)
    4DH (Get Return Code of Child Process)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 31H: Terminate and Stay Resident         ;
        ;                                                            ;
        ;          void keep_process(exit_code,nparas)               ;
        ;               int exit_code,nparas;                        ;
        ;                                                            ;
        ;          Does NOT return!                                  ;
        ;                                                            ;
        ;************************************************************;

cProc   keep_process,PUBLIC
parmB   exit_code
parmW   nparas
cBegin
        mov     al,exit_code    ; Get return code.
        mov     dx,nparas       ; Set DX to number of paragraphs the
                                ; program wants to keep.
        mov     ah,31h          ; Set function code.
        int     21h             ; Ask MS-DOS to keep process.
cEnd



Interrupt 21H (33) Function 33H (51)
Get/Set Control-C Check Flag

2.0 and later


    Function 33H gets or sets the status of the Control-C check flag.

To Call

    AH   = 33H
    AL   = 00H       get current Control-C check flag
        = 01H       set Control-C check flag to value in DL

    If AL is 01H:

    DL   = 00H       set Control-C check flag to off
        = 01H       set Control-C check flag to on

Returns

    AL   = 00H       flag set successfully
        = FFH       code in AL on call not 00H or 01H

    If AL was 00H on call:

    DL   = 00H       Control-C check flag off
        = 01H       Control-C check flag on

Programmer's Notes

    ■  If the Control-C check flag is off, MS-DOS checks for a Control-C
        entered at the keyboard only during servicing of the character I/O
        functions, 01H through 0CH. If the Control-C check flag is on, MS-
        DOS also checks for user entry of a Control-C during servicing of
        other functions, such as file and record operations.

    ■  The state of the Control-C check flag affects all programs. If a
        program needs to change the state of Control-C checking, it should
        save the original flag and restore it before terminating.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 33H: Get/Set Control-C Check Flag        ;
        ;                                                            ;
        ;          int controlC(func,state)                          ;
        ;              int func,state;                               ;
        ;                                                            ;
        ;          Returns current state of Control-C flag.          ;
        ;                                                            ;
        ;************************************************************;

cProc   controlC,PUBLIC
parmB   func
parmB   state
cBegin
        mov     al,func         ; Get set/reset function.
        mov     dl,state        ; Get new value if present.
        mov     ah,33h          ; MS-DOS ^C check function.
        int     21h             ; Call MS-DOS.
        mov     al,dl           ; Return current state.
        cbw                     ; Clear high byte of return value.
cEnd



Interrupt 21H (33) Function 34H (52)
Return Address of InDOS Flag
2.0 and later


    Function 34H returns the address of the InDOS flag, which reflects the
    current state of Interrupt 21H function processing.

    Note: Microsoft cannot guarantee that the information in
    this entry will be valid for future versions of MS-DOS.

To Call

    AH      = 34H

Returns

    ES:BX   = segment:offset of InDOS flag

Programmer's Notes

    ■  The InDOS flag is a byte within the MS-DOS kernel. The value in
        InDOS is incremented when MS-DOS begins execution of an Interrupt
        21H function and decremented when MS-DOS's processing of that
        function is completed. Thus, the value of InDOS is zero only when
        no Interrupt 21H processing is occurring.

    ■  The InDOS flag is one of the elements used in terminate-and-stay-
        resident (TSR) programs to determine when the TSR can be executed
        safely.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 34H: Get Return Address of InDOS Flag       ;
        ;                                                            ;
        ;       char far *inDOS_ptr()                                ;
        ;                                                            ;
        ;       Returns a far pointer to the MS-DOS inDOS flag.      ;
        ;                                                            ;
        ;***********************************************************;

cProc   inDOS_ptr,PUBLIC
cBegin
        mov     ah,34h          ; InDOS flag function.
        int     21h             ; Call MS-DOS.
        mov     ax,bx           ; Return offset in AX.
        mov     dx,es           ; Return segment in DX.
cEnd



Interrupt 21H (33) Function 35H (53)
Get Interrupt Vector
2.0 and later


    Function 35H returns the address stored in the interrupt vector table
    for the handler associated with the specified interrupt.

To Call

    AH      = 35H
    AL      = interrupt number

Returns

    ES:BX   = segment:offset of handler for interrupt specified in AL

Programmer's Note

    ■  Interrupt vectors should always be read with Function 35H and set
        with Function 25H (Set Interrupt Vector). Programs should never
        attempt to read or change interrupt vectors directly in
        memory.

Related Function

    25H (Set Interrupt Vector)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 35H: Get Interrupt Vector               ;
        ;                                                            ;
        ;           typedef void (far *FCP)();                       ;
        ;           FCP get_vector(intnum)                           ;
        ;               int intnum;                                  ;
        ;                                                            ;
        ;           Returns a far code pointer that is the           ;
        ;           segment:offset of the interrupt vector.          ;
        ;                                                            ;
        ;************************************************************;

cProc   get_vector,PUBLIC
parmB   intnum
cBegin
        mov     al,intnum       ; Get interrupt number into AL.
        mov     ah,35h          ; Select "get vector" function.
        int     21h             ; Call MS-DOS.
        mov     ax,bx           ; Return vector offset.
        mov     dx,es           ; Return vector segment.
cEnd



Interrupt 21H (33) Function 36H (54)
Get Disk Free Space
2.0 and later


    Function 36H returns disk-storage information for the specified drive.

To Call

    AH   = 36H
    DL   = drive specification (0 = default drive, 1 = drive A,
            2 = drive B, and so on)

Returns

    If function is successful:

    AX   = number of sectors per cluster
    BX   = number of clusters available
    CX   = number of bytes per sector
    DX   = number of clusters on drive

    If function is not successful:

    AX   = FFFFH     invalid drive number in DL

Programmer's Notes

    ■  The AX register should be checked for a value of FFFFH (error)
        before information returned by this function is used.

    ■  The number of bytes of free storage remaining on the disk can be
        calculated by multiplying available clusters times sectors per
        cluster times bytes per sector (BX * AX * CX).

    ■  Function 36H regards "lost" clusters (clusters that are allocated
        in the file allocation table [FAT] but do not belong to a file) as
        being in use and subtracts them from the amount of available
        storage, exactly as if they were allocated to a file.

    ■  With MS-DOS versions 2.0 and later, Function 36H should be used in
        preference to the FCB Functions 1BH (Get Default Drive Data) and
        1CH (Get Drive Data).

Related Functions

    1BH (Get Default Drive Data)
    1CH (Get Drive Data)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 36H: Get Disk Free Space              ;
        ;                                                            ;
        ;             long free_space(drive_ltr)                     ;
        ;                 char drive_ltr;                            ;
        ;                                                            ;
        ;             Returns the number of bytes free as            ;
        ;             a long integer.                                ;
        ;                                                            ;
        ;************************************************************;

cProc   free_space,PUBLIC
parmB   drive_ltr
cBegin
        mov     dl,drive_ltr    ; Get drive letter.
        or      dl,dl           ; Leave 0 alone.
        jz      fsp
        and     dl,not 20h      ; Convert letter to uppercase.
        sub     dl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
fsp:
        mov     ah,36h          ; Set function code.
        int     21h             ; Ask MS-DOS to get disk information.
        mul     cx              ; Bytes/sector * sectors/cluster
        mul     bx              ; * free clusters.
cEnd



Interrupt 21H (33) Function 38H (56)
Get/Set Current Country: Get Current Country
2.0 and later


    Function 38H includes two subfunctions that either get or set country
    data, depending on the value in the DX register when the function is
    called.

    With MS-DOS versions 2.0 and later, if DX contains any value other
    than FFFFH, the Get Current Country subfunction is invoked.
    Information on date, currency, and other country-specific formats is
    then returned in a buffer specified by the calling program. The
    country code is usually the same as the country's international
    telephone prefix.

To Call

    AH      = 38H

    With MS-DOS versions 2.x:

    AL      = 00H     current country
    DS:DX   = segment:offset of 32-byte buffer

    With MS-DOS versions 3.x:

    AL      = 00H     current country
            = 01-FEH  country code between 1 and 254
            = FFH     country code of 255 or greater, specified in BX
    BX      = country code if AL = FFH
    DS:DX   = segment:offset of 34-byte buffer

Returns

    If function is successful:

    Carry flag is clear.

    BX      = country code (MS-DOS version 3.x only)
    DS:DX   = segment:offset of buffer containing country information

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 02H     invalid country code

Programmer's Notes

    ■  With MS-DOS versions 2.x, the Get Current Country subfunction
        returns the following information for the current country in the
        32-byte country-data buffer (ASCIIZ format is an ASCII character
        string ending in a zero byte):

╓┌──────────────┌─────────┌──────────────────────────────────────────────────╖
        Offset Type      Description
        ──────────────────────────────────────────────────────────────────
        00H    Word      Date format:
                                0 = United States (m/d/y)
                                1 = Europe (d/m/y)
                                2 = Japan (y/m/d)
        02H    ASCIIZ    Currency symbol
        04H    ASCIIZ    Character used as thousands separator
        06H    ASCIIZ    Character used as decimal separator
        08H    24 bytes  Reserved

    ■  With MS-DOS versions 3.x, the Get Current Country subfunction
        returns the following information for the specified country in the
        34-byte country-data buffer:

╓┌──────────────┌─────────┌──────────────────────────────────────────────────╖
        Offset Type      Description
        ──────────────────────────────────────────────────────────────────
        00H    Word      Date format:
                            0 = United States (m/d/y)
                            1 = Europe (d/m/y)
                            2 = Japan (y/m/d)
        02H    ASCIIZ    Currency symbol (5 bytes, as opposed to 2
                        in versions 2.x of MS-DOS)
        07H    ASCIIZ    Character used as thousands separator
        09H    ASCIIZ    Character used as decimal separator
        0BH    ASCIIZ    Character used as date separator
        0DH    ASCIIZ    Character used as time separator
        0FH    Byte      Position of currency symbol; possible
                        values are:
                                00H   Currency symbol precedes value
                                    with no space
                                01H   Currency symbol follows value
                                    with no space
                                02H   Currency symbol precedes value
                                    with one space
                                03H   Currency symbol follows value
                                    with one space
        10H    Byte      Number of decimal places in currency
        11H    Byte      Time format (00H = 12-hour clock;
                        01H = 24-hour clock)
        12H    Dword     Case-mapping call address (See Programmer's
                        Notes below.)
        16H    ASCIIZ    Character used as separator in data lists
        18H    10 bytes  Reserved

    ■  The case-mapping call address (MS-DOS versions 3.x only) is the
        segment:offset of a FAR procedure that performs country-specific,
        lowercase-to-uppercase mapping on ASCII characters in the range 80H
        through 0FFH. The character to be mapped must be placed in the AL
        register before the call is made. If the character has an uppercase
        value, that value is returned in AL. If the character has no such
        value, AL is unchanged.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    38H (Set Current Country subfunction)

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 38H: Get/Set Current Country Data         ;
        ;                                                            ;
        ;         int country_info(country,pbuffer)                  ;
        ;             char country,*pbuffer;                         ;
        ;                                                            ;
        ;         Returns -1 if the "country" code is invalid.       ;
        ;                                                            ;
        ;************************************************************;

cProc   country_info,PUBLIC,ds
parmB   country
parmDP  pbuffer
cBegin
        mov     al,country      ; Get country code.
        loadDP  ds,dx,pbuffer   ; Get buffer pointer (or -1).
        mov     ah,38h          ; Set function code.
        int     21h             ; Ask MS-DOS to get country
                                ; information.
        jnb     cc_ok           ; Branch if country code OK.
        mov     ax,-1           ; Else return -1.
cc_ok:
cEnd



Interrupt 21H (33) Function 38H (56)
Get/Set Current Country: Set Current Country
3.0 and later


    Function 38H includes two subfunctions that either get or set country
    data, depending on the value in the DX register when the function is
    called.

    With MS-DOS versions 3.0 and later, the Set Current Country
    subfunction is invoked if Function 38H is called with DX = FFFFH (-1).
    This subfunction selects the country for which subsequent calls to Get
    Current Country will return information. The country code used with
    this function is usually the same as the country's international
    telephone prefix.

To Call

    AH   = 38H
    AL   = country code    for a code less than 255
        = FFH             for country code of 255 or greater, specified
                            in BX
    BX   = country code if AL = FFH
    DX   = FFFFH (-1)

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 02H              invalid country code

Programmer's Notes

    ■  MS-DOS normally uses the country code associated with the current
        KEYBxx keyboard driver file, if any. Otherwise, the default country
        code is OEM dependent.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    38H (Get Current Country subfunction)

Example

    See Function 38H Subfunction Get Current Country for example.



Interrupt 21H (33) Function 39H (57)
Create Directory
2.0 and later


    Function 39H creates a subdirectory using the specified path.

To Call

    AH      = 39H
    DS:DX   = segment:offset of ASCIIZ path

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 03H      path not found
            = 05H      access denied

Programmer's Notes

    ■  The path must be a null-terminated ASCII string (ASCIIZ).

    ■  MS-DOS places the current directory (.) and parent directory (..)
        entries in all new directories.

    ■  Function 39H returns error code 05H (access denied) in the
        following cases:

        - File or directory with the same name already exists in the
        specified path.

        - Parent directory is the root directory and the root directory is
        full.

        - Path specifies a device.

        - Program is running on a network under MS-DOS version 3.1 or later
        and the user does not have Create access to the parent
        directory.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    3AH (Remove Directory)
    3BH (Change Current Directory)
    47H (Get Current Directory)

Example

        ;************************************************************;
        ;                                                            ;
        ;              Function 39H: Create Directory                ;
        ;                                                            ;
        ;              int make_dir(pdirpath)                        ;
        ;                  char *pdirpath;                           ;
        ;                                                            ;
        ;              Returns 0 if directory created OK,            ;
        ;              otherwise returns error code.                 ;
        ;                                                            ;
        ;************************************************************;

cProc   make_dir,PUBLIC,ds
parmDP  pdirpath
cBegin
        loadDP  ds,dx,pdirpath  ; Get pointer to pathname.
        mov     ah,39h          ; Set function code.
        int     21h             ; Ask MS-DOS to make new subdirectory.
        jb      md_err          ; Branch on error.
        xor     ax,ax           ; Else return 0.
md_err:
cEnd



Interrupt 21H (33) Function 3AH (58)
Remove Directory
2.0 and later

    Function 3AH removes (deletes) the specified subdirectory.

To Call

    AH      = 3AH
    DS:DX   = segment:offset of ASCIIZ path

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 03H      path not found
            = 05H      access denied
            = 10H      current directory was specified

Programmer's Notes

    ■  The path must be a null-terminated ASCII string (ASCIIZ).

    ■  Function 3AH returns error code 05H (access denied) in the
        following cases:

        - Directory is not empty.

        - Root directory was specified.

        - Current directory was specified.

        - Path does not specify a valid directory.

        - Directory is malformed (. and .. not first two entries).

        - User has insufficient access rights on a network running under
        MS-DOS version 3.1 or later.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    39H (Create Directory)
    3BH (Change Current Directory)
    47H (Get Current Directory)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 3AH: Remove Directory                 ;
        ;                                                            ;
        ;             int remove_dir(pdirpath)                       ;
        ;                 char *pdirpath;                            ;
        ;                                                            ;
        ;             Returns 0 if directory was removed,            ;
        ;             otherwise returns error code.                  ;
        ;                                                            ;
        ;************************************************************;

cProc   remove_dir,PUBLIC,ds
parmDP  pdirpath
cBegin
        loadDP  ds,dx,pdirpath  ; Get pointer to pathname.
        mov     ah,3ah          ; Set function code.
        int     21h             ; Ask MS-DOS to delete subdirectory.
        jb      rd_err          ; Branch on error.
        xor     ax,ax           ; Else return 0.
rd_err:
cEnd



Interrupt 21H (33) Function 3BH (59)
Change Current Directory
2.0 and later


    Function 3BH changes the current directory to the specified path.

To Call

    AH      = 3BH
    DS:DX   = segment:offset of ASCIIZ path

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 03H      path not found

Programmer's Notes

    ■  The path must be a null-terminated ASCII string (ASCIIZ).

    ■  Before a call to Function 3BH, Function 47H (Get Current Directory)
        can be used to determine the current directory so that the original
        directory can be restored later (for example, on termination of the
        program).

    ■  Function 3BH can be used with programs that rely on either FCB-
        based or handle-based calls. It is the only method of changing the
        current directory that is supported by MS-DOS.

    ■  The path string is limited to a total of 64 characters, including
        separators.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    39H (Create Directory)
    3AH (Remove Directory)
    47H (Get Current Directory)

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 3BH: Change Current Directory          ;
        ;                                                            ;
        ;            int change_dir(pdirpath)                        ;
        ;                char *pdirpath;                             ;
        ;                                                            ;
        ;            Returns 0 if directory was changed,             ;
        ;            otherwise returns error code.                   ;
        ;                                                            ;
        ;************************************************************;

cProc   change_dir,PUBLIC,ds
parmDP  pdirpath
cBegin
        loadDP  ds,dx,pdirpath  ; Get pointer to pathname.
        mov     ah,3bh          ; Ask MS-DOS to move to
        int     21h             ; different directory.
        jb      cd_err          ; Branch on error.
        xor     ax,ax           ; Else return 0.
cd_err:
cEnd



Interrupt 21H (33) Function 3CH (60)
Create File with Handle
2.0 and later


    Function 3CH creates a file, assigns it the attributes specified, and
    returns a 16-bit handle for the file. If the named file already
    exists, Function 3CH opens it and truncates it to zero length.

To Call

    AH      = 3CH
    CX      = attribute
    DS:DX   = segment:offset of ASCIIZ pathname

Returns

    If function is successful:

    Carry flag is clear.

    AX      = handle number

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 03H      path not found
            = 04H      too many open files
            = 05H      access denied

Programmer's Notes

    ■  Function 3CH is preferable to Function 16H (Create File with FCB)
        for creating a file because it supports full pathnames. Function
        16H should be used only if compatibility with versions 1.x of MS-
        DOS is required.

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).

    ■  Bits 0 through 2 of the 2-byte file attribute in CX determine
        whether the file is normal, read-only, hidden, or system. The
        attribute codes are

        - 00H = normal file

        - 01H = read-only file

        - 02H = hidden file

        - 04H = system file

        Bits 3 through 5 are associated with volume labels, subdirectories,
        and archive files. The volume and subdirectory bits are invalid for
        Function 3CH and must be set to 0. Bits 6 through 15 should be set
        to 0 to ensure future compatibility.

        Values can be combined to set several file attributes. For example,
        if Function 3CH is called with CX = 0003H, the file created is a
        read-only hidden file.

    ■  Because Function 3CH truncates an existing file to zero length, any
        information previously in the file is lost. Alternative functions
        that protect against such loss include the following:

        - Function 3DH (Open File with Handle) or Function 4EH (Find First
        File), which can be used to check for the previous existence of
        the file before Function 3CH is called

        - Function 5AH (Create Temporary File), which creates a file in the
        specified subdirectory and gives it a unique name assigned by MS-
        DOS

        - Function 5BH (Create New File), which is similar to Function 3CH
        but fails if it finds a file that matches the specified
        pathname

    ■  After creating a file, Function 3CH sets the position of the file
        pointer to 0. Thus, the next read or write operation takes place at
        the beginning of the file.

    ■  Function 3CH returns error code 04H (too many open files) if no
        handle is currently available. With MS-DOS versions 3.2 and
        earlier, a single process can have no more than 20 files open at
        one time, 5 of which are normally assigned to the standard devices.

        Error code 05H (access denied) is returned if the file is to be
        created in the root directory and the root is full or if a read-
        only file with the same name already exists in the specified
        subdirectory.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Create access to the directory containing the file
        specified.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    16H (Create File with FCB)
    43H (Get/Set File Attributes)
    5AH (Create Temporary File)
    5BH (Create New File)

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 3CH: Create File with Handle           ;
        ;                                                            ;
        ;            int create(pfilepath,attr)                      ;
        ;               char *pfilepath;                             ;
        ;            int attr;                                       ;
        ;                                                            ;
        ;            Returns -1 if file was not created,             ;
        ;            otherwise returns file handle.                  ;
        ;                                                            ;
        ;************************************************************;


cProc   create,PUBLIC,ds
parmDP  pfilepath
parmW   attr
cBegin
        loadDP  ds,dx,pfilepath ; Get pointer to pathname.
        mov     cx,attr         ; Get new file's attribute.
        mov     ah,3ch          ; Ask MS-DOS to make a new file.
        int     21h
        jnb     cr_ok           ; Branch if MS-DOS returned handle.
        mov     ax,-1           ; Else return -1.
cr_ok:
cEnd



Interrupt 21H (33) Function 3DH (61)
Open File with Handle
2.0 and later


    Function 3DH opens the specified file and returns a 16-bit handle
    number for subsequent access to the file.

To Call

    AH      = 3DH

    With versions 2.x of MS-DOS:

    AL      = file-access code:

            ───────────────────────────────────────────────────────
            Bits           Value          Meaning
            ───────────────────────────────────────────────────────
            3-7            00000          Reserved
            0-2            000            Read-only access
                            001            Write-only access
                            010            Read/write access

    DS:DX   = segment:offset of ASCIIZ pathname

    With versions 3.x of MS-DOS:

    AL      = file-access, file-sharing, and inheritance codes:

            ───────────────────────────────────────────────────────
            Bits                 Value       Meaning
            ───────────────────────────────────────────────────────
            7(inherit bit)         0         Child process inherits
                                                file
                                    1         Child process does not
                                                inherit file
            4-6 (sharing mode;   000         Compatibility mode
            file access granted  001         Deny read/write access
            to other processes)  010         Deny write access
                                    011         Deny read access
                                    100         Deny none
            3                      0         Reserved
            0-2 (access code;    000         Read-only access
            file usage)          001         Write-only access
                                    010         Read/write access

    DS:DX   = segment:offset of ASCIIZ pathname

Returns

    If function is successful:

    Carry flag is clear.

    AX      = handle number

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 02H      file not found
            = 03H      path not found
            = 04H      too many open files
            = 05H      access denied
            = 0CH      invalid access code

Programmer's Notes

    ■  Function 3DH is preferable to Function 0FH (Open File with FCB)
        because it allows the use of pathnames. Function 0FH should be used
        only if compatibility with versions 1.x of MS-DOS is required.

    ■  Function 3DH opens any file matching the pathname in DS:DX,
        including hidden and system files.

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).

    ■  Function 3DH returns error code 04H (too many open files) if no
        handle is currently available. With MS-DOS versions 3.2 and
        earlier, a single process can have no more than 20 files open at
        one time, 5 of which are normally assigned to the standard devices.

        Function 3DH returns error code 05H (access denied) if the pathname
        specifies a directory or volume label or if read/write access was
        requested for a read-only file.

        Function 3DH returns error code 0CH (invalid access code) if bits
        0-2 in AL contain any value other than 000, 001, or 010.

    ■  With MS-DOS versions 2.x, only bits 0-2 of the byte in AL are
        meaningful; they should contain the type of access allowed for the
        file. Bits 3-7 should always be zero.

        With MS-DOS versions 3.0 and later, networking capabilities require
        bits 4-7, as well as 0-2, to be set. (Bit 3 is reserved and should
        be 0.)

        Bit 7, the inherit bit, should be set to indicate whether child
        processes created by the current process with Function 4BH (Load
        and Execute Program) either can (0) or cannot (1) inherit the file.
        When a process inherits a file, it also inherits the access and
        sharing modes.

        Bits 4-6 are called the "sharing code"; they indicate the type of
        access other users on the network can have to the file. The five
        sharing modes and the conditions under which they pertain are as
        follows:

        - mode 000 (compatibility). Allows other programs running on the
        same machine unlimited access to the file. Programs running on
        other machines cannot access the file across the network unless
        it has the read-only attribute. An attempt to open the file in
        compatibility mode fails if the file has already been opened with
        any other sharing mode.

        - 001 (deny read and write access). Provides exclusive access to
        the file. Any subsequent attempts by others (including the
        current process) to open the file fail. This mode fails if the
        file has already been opened in compatibility mode or for read or
        write access, even by the current process.

        - 010 (deny write access). Allows other processes to open the file
        for read-only access. This mode fails if the file has already
        been opened in compatibility mode or for write access by any
        other process.

        - 011 (deny read access). Allows other processes to open the file
        for write-only access. This mode fails if the file has already
        been opened in compatibility mode or for read access by any other
        process.

        - 100 (deny none). Similar to compatibility mode, but does not
        allow other processes to open the file in compatibility mode.
        This mode fails if the file has already been opened in
        compatibility mode by any other process.

    ■  When the file is opened, the position of the file pointer is set to
        0. Function 42H (Move File Pointer) can be used to change its
        position.

    ■  With MS-DOS versions 3.0 and later, if this function fails because
        of a file-sharing error, the operating system issues an Interrupt
        24H (Critical Error Handler Address) with error code 02H (drive not
        ready). Function 59H (Get Extended Error Information) must be used
        to find the extended error code specifying the type of sharing
        violation that occurred.

Related Functions

    0FH (Open File with FCB)
    3EH (Close File)
    3FH (Read File or Device)
    40H (Write File or Device)
    42H (Move File Pointer)
    43H (Get/Set File Attributes)
    57H (Get/Set Date/Time of File)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 3DH: Open File with Handle            ;
        ;                                                            ;
        ;             int open(pfilepath,mode)                       ;
        ;                 char *pfilepath; int mode;                 ;
        ;                                                            ;
        ;             Modes:                                         ;
        ;                     0: Read                                ;
        ;                     1: Write                               ;
        ;                     2: Read/Write                          ;
        ;                                                            ;
        ;             Returns -1 if file was not opened,             ;
        ;             otherwise returns file handle.                 ;
        ;                                                            ;
        ;************************************************************;

cProc   open,PUBLIC,ds
parmDP  pfilepath
parmB   mode
cBegin
        loadDP  ds,dx,pfilepath ; Get pointer to pathname.
        mov     al,mode         ; Get read/write mode.
        mov     ah,3dh          ; Request MS-DOS to open the
        int     21h             ; existing file.
        jnb     op_ok           ; Branch if MS-DOS returned handle.
        mov     ax,-1           ; Else return -1.
op_ok:
cEnd



Interrupt 21H (33) Function 3EH (62)
Close File
2.0 and later


    Function 3EH closes the file referenced by the specified handle.

To Call

    AH   = 3EH
    BX   = handle number

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 06H      invalid handle number

Programmer's Notes

    ■  The handle in BX must be one that was returned by a successful call
        to one of the following functions:

        - 3CH (Create File with Handle)

        - 3DH (Open File with Handle)

        - 5AH (Create Temporary File)

        - 5BH (Create New File)

    ■  If the file has been modified, truncated, or extended, Function 3EH
        updates the current date, time, and file size in the directory
        entry.

    ■  All internal MS-DOS buffers for the file, including directory and
        file allocation table (FAT) buffers, are flushed to disk.

    ■  With MS-DOS versions 3.0 and later, a program must remove all file
        locks in effect before it closes a file. The result of closing a
        file with active locks is unpredictable.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    10H (Close File with FCB)
    3CH (Create File with Handle)
    3DH (Open File with Handle)
    5AH (Create Temporary File)
    5BH (Create New File)

Example

        ;************************************************************;
        ;                                                            ;
        ;              Function 3EH: Close File                      ;
        ;                                                            ;
        ;              int close(handle)                             ;
        ;                  int handle;                               ;
        ;                                                            ;
        ;              Returns -1 if file was not closed,            ;
        ;              otherwise returns 0.                          ;
        ;                                                            ;
        ;************************************************************;

cProc   close,PUBLIC
parmW   handle
cBegin
        mov     bx,handle       ; Get handle.
        mov     ah,3eh          ; Set function codes.
        int     21h             ; Ask MS-DOS to close handle.
        mov     al,0
        jnb     cl_ok           ; Branch if no error.
        mov     al,-1           ; Else return -1.
cl_ok:
        cbw                     ; Extend result.
cEnd



Interrupt 21H (33) Function 3FH (63)
Read File or Device
2.0 and later


    Function 3FH reads from the file or device referenced by a handle.

To Call

    AH      = 3FH
    BX      = handle number
    CX      = number of bytes to read
    DS:DX   = segment:offset of data buffer

Returns

    If function is successful:

    Carry flag is clear.

    AX      = number of bytes read from file
    DS:DX   = segment:offset of data read from file

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 05H  access denied
            = 06H  invalid handle

Programmer's Notes

    ■  Data is read from the file beginning at the current location of the
        file pointer. After a successful read, the file pointer is updated
        to point to the byte following the last byte read.

    ■  If Function 3FH returns 00H in the AX register, the function
        attempted to read when the file pointer was at the end of the file.
        If AX is less than CX, a partial record at the end of the file was
        read.

    ■  Function 3FH can be used with all handles, including standard input
        (normally the keyboard). When reading from standard input, this
        function normally reads characters only to the first carriage-
        return character. Thus, the number of bytes read in AX will not
        necessarily match the length requested in CX.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Read access to the directory and file containing the
        information to be read.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    40H (Write File or Device)
    42H (Move File Pointer)
    59H (Get Extended Error Information)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 3FH: Read File or Device                ;
        ;                                                            ;
        ;           int read(handle,pbuffer,nbytes)                  ;
        ;               int handle,nbytes;                           ;
        ;               char *pbuffer;                               ;
        ;                                                            ;
        ;           Returns -1 if there was a read error,            ;
        ;           otherwise returns number of bytes read.          ;
        ;                                                            ;
        ;************************************************************;

cProc   read,PUBLIC,ds
parmW   handle
parmDP  pbuffer
parmW   nbytes
cBegin
        mov     bx,handle       ; Get handle.
        loadDP  ds,dx,pbuffer   ; Get pointer to buffer.
        mov     cx,nbytes       ; Get number of bytes to read.
        mov     ah,3fh          ; Set function code.
        int     21h             ; Ask MS-DOS to read CX bytes.
        jnb     rd_ok           ; Branch if read worked.
        mov     ax,-1           ; Else return -1.
rd_ok:
cEnd



Interrupt 21H (33) Function 40H (64)
Write File or Device
2.0 and later


    Function 40H writes the specified number of bytes to a file or device
    referenced by a handle.

To Call

    AH      = 40H
    BX      = handle
    CX      = number of bytes to write
    DS:DX   = segment:offset of data buffer

Returns

    If function is successful:

    Carry flag is clear.

    AX      = number of bytes written to file or device

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 05H      access denied
            = 06H      invalid handle

Programmer's Notes

    ■  Data is written to the file or device beginning at the current
        location of the file pointer. After writing the specified data,
        Function 40H updates the position of the file pointer and returns
        the actual number of bytes written in AX.

    ■  Function 40H returns error code 05H (access denied) if the file was
        opened as read-only with Function 3CH (Create File with Handle),
        3DH (Open File with Handle), 5AH (Create Temporary File), or 5BH
        (Create New File). On networks running under MS-DOS version 3.1 or
        later, access is also denied if the file or record has been locked
        by another process.

    ■  The handle number in BX must be one of the predefined device
        handles (0 through 4) or a handle obtained through a previous call
        to open or create a file (such as Function 3CH, 3DH, 5AH, or 5BH).

    ■  If CX = 0, the file is truncated or extended to the current file
        pointer location. Clusters are allocated or released in the file
        allocation table (FAT) as required to fulfill the request.

    ■  If the handle parameter for Function 40H refers to a disk file and
        the number of bytes written (returned in AX) is less than the
        number requested in CX, the destination disk is full. The carry
        flag is not set in this situation.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    3FH (Read File or Device)
    42H (Move File Pointer)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 40H: Write File or Device                ;
        ;                                                            ;
        ;          int write(handle,pbuffer,nbytes)                  ;
        ;              int handle,nbytes;                            ;
        ;              char *pbuffer;                                ;
        ;                                                            ;
        ;          Returns -1 if there was a write error,            ;
        ;          otherwise returns number of bytes written.        ;
        ;                                                            ;
        ;************************************************************;

cProc   write,PUBLIC,ds
parmW   handle
parmDP  pbuffer
parmW   nbytes
cBegin
        mov     bx,handle       ; Get handle.
        loadDP  ds,dx,pbuffer   ; Get pointer to buffer.
        mov     cx,nbytes       ; Get number of bytes to write.
        mov     ah,40h          ; Set function code.
        int     21h             ; Ask MS-DOS to write CX bytes.
        jnb     wr_ok           ; Branch if write successful.
        mov     ax,-1           ; Else return -1.
wr_ok:
cEnd



Interrupt 21H (33) Function 41H (65)
Delete File
2.0 and later


    Function 41H deletes the directory entry of the specified file.

To Call

    AH      = 41H
    DS:DX   = segment:offset of ASCIIZ pathname

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX         = error code:
                = 02H    file not found
                = 03H    path not found
                = 05H    access denied

Programmer's Notes

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).
        Unlike Function 13H (Delete File), Function 41H does not allow
        wildcard characters in the pathname.

    ■  Because Function 41H supports the use of full pathnames, it is
        preferable to Function 13H.

    ■  Function 41H returns error code 05H (access denied) and fails if
        the file has either a directory or volume attribute or if it is a
        read-only file.

        A directory can be deleted (if it is empty) with Function 3AH
        (Remove Directory). A read-only file can be deleted if its
        attribute is changed to normal with Function 43H (Get/Set File
        Attributes) before Function 41H is called.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Create access to the directory containing the file to be
        deleted.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    3AH (Remove Directory)
    43H (Get/Set File Attributes)

Example

        ;************************************************************;
        ;                                                            ;
        ;                Function 41H: Delete File                   ;
        ;                                                            ;
        ;                int delete(pfilepath)                       ;
        ;                    char *pfilepath;                        ;
        ;                                                            ;
        ;                Returns 0 if file deleted,                  ;
        ;                otherwise returns error code.               ;
        ;                                                            ;
        ;************************************************************;

cProc   delete,PUBLIC,ds
parmDP  pfilepath
cBegin
        loadDP  ds,dx,pfilepath ; Get pointer to pathname.
        mov     ah,41h          ; Set function code.
        int     21h             ; Ask MS-DOS to delete file.
        jb      dl_err          ; Branch if MS-DOS could not delete
                                ; file.
        xor     ax,ax           ; Else return 0.
dl_err:
cEnd



Interrupt 21H (33) Function 42H (66)
Move File Pointer
2.0 and later


    Function 42H sets the position of the file pointer (for the next
    read/write operation) for the file associated with the specified
    handle.

To Call

    AH      = 42H
    AL      = method code:
            = 00H       byte offset from beginning of file
            = 01H       byte offset from current location of file pointer
            = 02H       byte offset from end of file
    BX      = handle number
    CX:DX   = offset value to move pointer:
            = CX        most significant half of a doubleword value
            = DX        least significant half of a doubleword value

Returns

    If function is successful:

    Carry flag is clear.

    DX:AX   = new file pointer position (absolute byte offset from
            beginning of file)

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function (AL not 00H, 01H, or 02H)
            = 06H      invalid handle

Programmer's Notes

    ■  The value in CX:DX is an offset specifying how far the file pointer
        is to be moved. With method code 00H, the value in CX:DX is always
        interpreted as a positive 32-bit integer, meaning the file pointer
        is always set relative to the beginning of the file.

        With method codes 01H and 02H, the value in CX:DX can be either a
        positive or negative 32-bit integer. Thus, method 1 can move the
        file pointer either forward or backward from its current position;
        method 2 can move the file pointer either forward or backward from
        the end of the file.

    ■  Specifying method code 00H with an offset of 0 positions the file
        pointer at the beginning of the file. Similarly, specifying method
        code 02H with an offset of 0 conveniently positions the file
        pointer at the end of the file. With method code 02H offset 0, the
        size of the file can also be determined by examining the pointer
        position returned by the function.

    ■  Depending on the offset specified in CX:DX, methods 1 and 2 may
        move the file pointer to a position before the start of the file.
        Function 42H does not return an error code if this happens, but
        later attempts to read from or write to the file will produce
        unexpected errors.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    3FH (Read File or Device)
    40H (Write File or Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;           Function 42H: Move File Pointer                  ;
        ;                                                            ;
        ;           long seek(handle,distance,mode)                  ;
        ;                int handle,mode;                            ;
        ;                long distance;                              ;
        ;                                                            ;
        ;           Modes:                                           ;
        ;                   0: from beginning of file                ;
        ;                   1: from the current position             ;
        ;                   2: from the end of the file              ;
        ;                                                            ;
        ;           Returns -1 if there was a seek error,            ;
        ;           otherwise returns long pointer position.         ;
        ;                                                            ;
        ;************************************************************;

cProc   seek,PUBLIC
parmW   handle
parmD   distance
parmB   mode
cBegin
        mov     bx,handle       ; Get handle.
        les     dx,distance     ; Get distance into ES:DX.
        mov     cx,es           ; Put high word of distance into CX.
        mov     al,mode         ; Get move method code.
        mov     ah,42h          ; Set function code.
        int     21h             ; Ask MS-DOS to move file pointer.
        jnb     sk_ok           ; Branch if seek successful.
        mov     ax,-1           ; Else return -1.
        cwd
sk_ok:
cEnd



Interrupt 21H (33) Function 43H (67)
Get/Set File Attributes
2.0 and later


    Function 43H gets or sets the attributes of the specified file.

To Call

    AH      = 43H

    To get file attributes:

    AL      = 00H
    DS:DX   = segment:offset of ASCIIZ pathname

    To set file attributes:

    AL      = 01H
    CX      = attributes to set:

╓┌──────────────────────────┌────────────────────────────────────────────────╖
            Bit         Attribute
            ──────────────────────────────────────────────────────────
            0           Read-only file
            1           Hidden file
            2           System file
            5           Archive

    DS:DX   = segment:offset of ASCIIZ pathname

Returns

    If function is successful:

    Carry flag is clear.

    CX      = attribute

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H    invalid function (AL not 00H or 01H)
            = 02H    file not found
            = 03H    path not found
            = 05H    access denied

Programmer's Notes

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).

    ■  Function 43H cannot be used to set or change either a volume-label
        or directory attribute (bits 3 and 4 of the attribute byte). With
        MS-DOS versions 3.x, Function 43H can be used to make a directory
        hidden or read-only.

    ■  On networks running under MS-DOS version 3.1 or later, the user
        must have Create access to the directory containing the file in
        order to change the read-only, hidden, or system attribute. The
        archive bit, however, can be changed regardless of access rights.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 43H: Get/Set File Attributes           ;
        ;                                                            ;
        ;            int file_attr(pfilepath,func,attr)              ;
        ;                char *pfilepath;                            ;
        ;                int func,attr;                              ;
        ;                                                            ;
        ;            Returns -1 for all errors,                      ;
        ;            otherwise returns file attribute.               ;
        ;                                                            ;
        ;************************************************************;

cProc   file_attr,PUBLIC,ds
parmDP  pfilepath
parmB   func
parmW   attr
cBegin
        loadDP  ds,dx,pfilepath ; Get pointer to pathname.
        mov     al,func         ; Get/set flag into AL.
        mov     cx,attr         ; Get new attr (if present).
        mov     ah,43h          ; Set code function.
        int     21h             ; Call MS-DOS.
        jnb     fa_ok           ; Branch if no error.
        mov     cx,-1           ; Else return -1.
fa_ok:
        mov     ax,cx           ; Return this value.

cEnd



Interrupt 21H (33) Function 44H (68)
IOCTL
2.0 and later


    Function 44H is a collection of subfunctions that provide a process a
    direct path of communication with a device driver. As such, this
    function is the most flexible means of gaining access to the full
    capabilities of an installed device.

    An IOCTL subfunction is called with 44H in AH and the value for the
    subfunction in AL. If a subfunction has minor functions, those values
    are specified in CL. Otherwise, the BX, CX, and DX registers are used
    for such information as handles, drive identifiers, buffer addresses,
    and so on.

    The subfunctions and the versions of MS-DOS with which they are
    available are

╓┌─────────────────────┌──────────────────────────────────────┌──────────────╖
                                                            MS-DOS
    Subfunction      Name                                   Version
    ─────────────────────────────────────────────────────────────────────
    00H              Get Device Data                        2.0 and later
    01H              Set Device Data                        2.0 and later
    02H              Receive Control Data from
                    Character Device                       2.0 and later
    03H              Send Control Data to Character
                    Device                                 2.0 and later
    04H              Receive Control Data from Block
                    Device                                 2.0 and later
    05H              Send Control Data to Block Device      2.0 and later
    06H              Check Input Status                     2.0 and later
    07H              Check Output Status                    2.0 and later
    08H              Check If Block Device Is Removable     3.0 and later
    09H              Check If Block Device Is Remote        3.1 and later
    0AH              Check If Handle Is Remote              3.1 and later
    0BH              Change Sharing Retry Count             3.1 and later
    0CH              Generic I/O Control for Handles        3.2
                    Minor Code 45H: Set Iteration Count
                    Minor Code 65H: Get Iteration Count
    0DH              Generic I/O Control for Block Devices  3.2
                    Minor Code 40H: Set Device Parameters
                    Minor Code 60H: Get Device Parameters
                    Minor Code 41H: Write Track on
                                    Logical Drive
                    Minor Code 61H: Read Track on
                                    Logical Drive
                    Minor Code 42H: Format and Verify
                                    Track on Logical
                                    Drive
                    Minor Code 62H: Verify Track on
                                    Logical Drive;
    0EH              Get Logical Drive Map                  3.2
    0FH              Set Logical Drive Map                  3.2

    These subfunctions are documented, either individually or in
    related pairs, in the entries that follow.



Interrupt 21H (33) Function 44H (68) Subfunction 00H
IOCTL: Get Device Data
2.0 and later


    Function 44H Subfunction 00H gets information about a character device
    or file referenced by a handle.

To Call

    AH   = 44H
    AL   = 00H
    BX   = handle number

Returns

    If function is successful:

    Carry flag is clear.

    DX contains information on file or device:

╓┌───────────────┌─────────┌─────────────────────────────────────────────────╖
Bit             Value     Meaning
──────────────────────────────────────────────────────────────────────────
For a file (bit 7 = 0):

8-15            0         Reserved.
7               0         Handle refers to a file.
6               0         File has been written.
0-5                       Drive number (0 = A, 1 = B, 2 = C, and so on).

For a device (bit 7 = 1):

15              0         Reserved.
14              1         Processes control strings transferred by IOCTL
                        Subfunctions 02H (Receive Control Data from
                        Character Device) and 03H (Send Control Data to
                        Character Device), set by MS-DOS.
8-13            0         Reserved.
7               1         Handle refers to a device.
6               0         End of file on input.
5               0         Checks for control characters (cooked mode).
                1         Does not check for control characters (raw mode).
4               0         Reserved.
3               1         Clock device.
2               1         Null device.
1               1         Standard output device.
0               1         Standard input device.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid IOCTL subfunction
        = 05H    access denied
        = 06H    invalid handle

Programmer's Notes

    ■  Bits 8-15 of DX correspond to the upper 8 bits of the device-driver
        attribute word.

    ■  The handle in BX must reference an open device or file.

    ■  Bit 5 of the device data word for character-device handles defines
        whether that handle is in raw mode or cooked mode. In cooked
        mode, MS-DOS checks for Control-C, Control-P, Control-S, and
        Control-Z characters and transfers control to the Control-C
        exception handler (whose address is saved in the vector for
        Interrupt 23H) when a Control-C is detected. In raw mode, MS-DOS
        does not check for such characters when I/O is performed to the
        handle; however, it will still check for a Control-C entered at the
        keyboard on other function calls unless such checking has been
        turned off with Function 33H, the BREAK=OFF directive in
        CONFIG.SYS, or a BREAK OFF command at the MS-DOS prompt.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    33H (Get/Set Control-C Check Flag)
    3CH (Create File with Handle)
    3DH (Open File with Handle)

Example

        ;************************************************************;
        ;                                                            ;
        ;        Function 44H, Subfunctions 00H,01H:                 ;
        ;                      Get/Set IOCTL Device Data             ;
        ;                                                            ;
        ;        int ioctl_char_flags(setflag,handle,newflags)       ;
        ;            int setflag;                                    ;
        ;            int handle;                                     ;
        ;            int newflags;                                   ;
        ;                                                            ;
        ;        Set setflag = 0 to get flags, 1 to set flags.       ;
        ;                                                            ;
        ;        Returns -1 for error, else returns flags.           ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_char_flags,PUBLIC
parmB   setflag
parmW   handle
parmW   newflags
cBegin
        mov     al,setflag      ; Get setflag.
        and     al,1            ; Save only lsb.
        mov     bx,handle       ; Get handle to character device.
        mov     dx,newflags     ; Get new flags (they are used only
                                ; by "set" option).
        mov     ah,44h          ; Set function code.
        int     21h             ; Call MS-DOS.
        mov     ax,dx           ; Assume success - prepare to return
                                ; flags.
        jnc     iocfx           ; Branch if no error.
        mov     ax,-1           ; Else return error flag.
iocfx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 01H
IOCTL: Set Device Data
2.0 and later


    Function 44H Subfunction 01H, the complement of IOCTL Subfunction 00H,
    sets information about a character device--but not a file--referenced
    by a handle.

To Call

    AH   = 44H
    AL   = 01H
    BX   = handle number
    DX   = device data word:

            ──────────────────────────────────────────────────────────────
            Bit       Value      Meaning
            ──────────────────────────────────────────────────────────────
            8-15      0          Reserved.
            7         1          Handle refers to a device.
            6         0          End of file on input.
            5         0          Check for control characters
                                (cooked mode).
                    1          Do not check for control characters
                                (raw mode).
            4         0          Reserved.
            3         1          Clock device.
            2         1          Null device.
            1         1          Standard output device.
            0         1          Standard input device.

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid IOCTL subfunction
        = 05H    access denied
        = 06H    invalid handle

Programmer's Notes

    ■  The handle in BX must reference an open device.

    ■  DH must be 00H. If it is not, the carry flag is set and error code
        01H (invalid function) is returned.

    ■  Bit 5 of the device data word for character-device handles selects
        raw mode or cooked mode for the handle. In cooked mode, MS-DOS
        checks for Control-C, Control-P, Control-S, and Control-Z
        characters and transfers control to the Control-C exception handler
        (whose address is saved in the vector for Interrupt 23H) when a
        Control-C is detected. In raw mode, MS-DOS does not check for such
        characters when I/O is performed to the handle; however, it will
        still check for a Control-C entered at the keyboard on other
        function calls unless such checking has been turned off with
        Function 33H, the BREAK=OFF directive in CONFIG.SYS, or a BREAK OFF
        command at the MS-DOS prompt.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    33H (Get/Set Control-C Check Flag)
    3CH (Create File with Handle)
    3DH (Open File with Handle)

Example

    See SYSTEM CALLS: INTERRUPT 21H: Function 44H Subfunction 00H.



Interrupt 21H (33) Function 44H (68) Subfunctions 02H and 03H
IOCTL: Receive Control Data from Character Device;
Send Control Data to Character Device
2.0 and later


    Function 44H Subfunctions 02H and 03H respectively receive and send
    control strings from and to a character-oriented device driver.

To Call

    AH      = 44H
    AL      = 02H     receive control
            = 03H     send control strings
    BX      = handle number
    CX      = number of bytes to transfer
    DS:DX   = segment:offset of data buffer

Returns

    If function is successful:

    Carry flag is clear.

    AX      = number of bytes transferred

    If AL was 02H on call:

    Buffer at DS:DX contains data read from device driver.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H    invalid function
            = 05H    access denied
            = 06H    invalid handle
            = 0DH    invalid data (bad control string)

Programmer's Notes

    ■  Subfunctions 02H and 03H provide a means of transferring control
        information of any type or length between an application program
        and a character-device driver. They do not necessarily result in
        any input to or output from the physical device itself.

    ■  Subfunction 02H can be used to read control information about such
        features as device status, availability, and current output
        location. Subfunction 03H is often used to configure the driver or
        device for subsequent I/O; for example, it may be used to set the
        baud rate, word length, and parity for a serial communications
        adapter or to initialize a printer for a specific font, page
        length, and so on. The format of the control data passed by these
        subfunctions is driver specific and does not follow any standard.

    ■  Character-device drivers are not required to support IOCTL
        Subfunctions 02H and 03H. Therefore, Subfunction 00H (Get Device
        Data) should be called before either Subfunction 02H or 03H to
        determine whether a device can process control strings. If bit 14
        of the device data word returned by Subfunction 00H is set, the
        device driver supports IOCTL Subfunctions 02H and 03H.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    44H Subfunction 00H (Get Device Data)
    44H Subfunction 04H (Receive Control Data from Block Device)
    44H Subfunction 05H (Send Control Data to Block Device)

Example

        ;************************************************************;
        ;                                                            ;
        ;     Function 44H, Subfunctions 02H,03H:                    ;
        ;                   IOCTL Character Device Control           ;
        ;                                                            ;
        ;     int ioctl_char_ctrl(recvflag,handle,pbuffer,nbytes)    ;
        ;         int   recvflag;                                    ;
        ;         int   handle;                                      ;
        ;         char *pbuffer;                                     ;
        ;         int   nbytes;                                      ;
        ;                                                            ;
        ;     Set recvflag = 0 to receive info, 1 to send.           ;
        ;                                                            ;
        ;     Returns -1 for error, otherwise returns number of      ;
        ;     bytes sent or received.                                ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_char_ctrl,PUBLIC,<ds>
parmB   recvflag
parmW   handle
parmDP  pbuffer
parmW   nbytes
cBegin
        mov     al,recvflag     ; Get recvflag.
        and     al,1            ; Keep only lsb.
        add     al,2            ; AL = 02H for receive, 03H for send.
        mov     bx,handle       ; Get character-device handle.
        mov     cx,nbytes       ; Get number of bytes to receive/send.
        loadDP  ds,dx,pbuffer   ; Get pointer to buffer.
        mov     ah,44h          ; Set function code.
        int     21h             ; Call MS-DOS.
        jnc     iccx            ; Branch if no error.
        mov     ax,-1           ; Return -1 for all errors.
iccx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunctions 04H and 05H
IOCTL: Receive Control Data from Block Device;
Send Control Data to Block Device
2.0 and later


    Function 44H Subfunctions 04H and 05H respectively receive and send
    control strings from and to a block-oriented device driver.

To Call

    AH      = 44H
    AL      = 04H    receive block-device data
            = 05H    send block-device data
    BL      = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)
    CX      = number of bytes to transfer
    DS:DX   = segment:offset of data buffer

Returns

    If function is successful:

    Carry flag is clear.

    AX      = number of bytes transferred

    If AL was 04H on call:

    Buffer at DS:DX contains control data read from device driver.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function
            = 05H      access denied
            = 06H      invalid handle
            = 0DH      invalid data (bad control string)

Programmer's Notes

    ■  Subfunctions 04H and 05H provide a means of transferring control
        information of any type or length between an application program
        and a block-device driver. They do not necessarily result in any
        input to or output from the physical device itself.

    ■  Control strings can be used to request driver operations that are
        not file oriented, such as tape rewind or disk eject (if hardware
        supported). The contents of such control strings are specific to
        individual device drivers and do not follow any standard format.

    ■  Subfunction 04H can be used to obtain a code from the driver
        indicating device availability or status. Block devices that might
        use this subfunction include magnetic tape or tape cassette, CD
        ROM, and Small Computer Standard Interface (SCSI) devices.

    ■  Block-device drivers are not required to support IOCTL Subfunctions
        04H and 05H. If the driver does not support these subfunctions,
        error code 01H (Invalid Function) is returned.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    44H Subfunction 00H (Get Device Data)
    44H Subfunction 02H (Receive Control Data from Character Device)
    44H Subfunction 03H (Send Control Data to Character Device)

Example

        ;*************************************************************;
        ;                                                             ;
        ;   Function 44H, Subfunctions 04H,05H:                       ;
        ;                 IOCTL Block Device Control                  ;
        ;                                                             ;
        ;   int ioctl_block_ctrl(recvflag,drive_ltr,pbuffer,nbytes)   ;
        ;       int   recvflag;                                       ;
        ;       int   drive_ltr;                                      ;
        ;       char *pbuffer;                                        ;
        ;       int   nbytes;                                         ;
        ;                                                             ;
        ;   Set recvflag = 0 to receive info, 1 to send.              ;
        ;                                                             ;
        ;   Returns -1 for error, otherwise returns number of         ;
        ;   bytes sent or received.                                   ;
        ;                                                             ;
        ;*************************************************************;

cProc   ioctl_block_ctrl,PUBLIC,<ds>
parmB   recvflag
parmB   drive_ltr
parmDP  pbuffer
parmW   nbytes
cBegin
        mov     al,recvflag     ; Get recvflag.
        and     al,1            ; Keep only lsb.
        add     al,4            ; AL = 04H for receive, 05H for send.
        mov     bl,drive_ltr    ; Get drive letter.
        or      bl,bl           ; Leave 0 alone.
        jz      ibc
        and     bl,not 20h      ; Convert letter to uppercase.
        sub     bl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
ibc:
        mov     cx,nbytes       ; Get number of bytes to receive/send.
        loadDP  ds,dx,pbuffer   ; Get pointer to buffer.
        mov     ah,44h          ; Set function code.
        int     21h             ; Call MS-DOS.
        jnc     ibcx            ; Branch if no error.
        mov     ax,-1           ; Return -1 for all errors.
ibcx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunctions 06H and 07H
IOCTL: Check Input Status; Check Output Status
2.0 and later


    Function 44H Subfunctions 06H and 07H respectively determine whether a
    device or file associated with a handle is ready for input or output.

To Call

    AH   = 44H
    AL   = 06H    get input status
        = 07H    get output status
    BX   = handle number

Returns

    If function is successful:

    Carry flag is clear.

    AL   = input or output status:
        = 00H    not ready
        = FFH    ready

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H      invalid function
        = 05H      access denied
        = 06H      invalid handle
        = 0DH      invalid data (bad control string)

Programmer's Notes

    ■  The status returned in AL has the following meanings:

╓┌────────────────────┌───────────────┌───────────────────┌──────────────────╖
        Status       Device          Input File          Output File
        ──────────────────────────────────────────────────────────────────
        00H          Not ready       Pointer at EOF      Ready
        0FFH         Ready           Ready               Ready

    ■  Output files always return a ready condition, even if the disk is
        full or no disk is in the drive.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;*************************************************************;
        ;                                                             ;
        ;   Function 44H, Subfunctions 06H,07H:                       ;
        ;                 IOCTL Input/Output Status                   ;
        ;                                                             ;
        ;   int ioctl_char_status(outputflag,handle)                  ;
        ;       int outputflag;                                       ;
        ;       int handle;                                           ;
        ;                                                             ;
        ;   Set outputflag = 0 for input status, 1 for output status. ;
        ;                                                             ;
        ;   Returns -1 for all errors, 0 for not ready,               ;
        ;   and 1 for ready.                                          ;
        ;                                                             ;
        ;*************************************************************;

cProc   ioctl_char_status,PUBLIC
parmB   outputflag
parmW   handle
cBegin
        mov     al,outputflag   ; Get outputflag.
        and     al,1            ; Keep only lsb.
        add     al,6            ; AL = 06H for input status, 07H for output
                                ; status.
        mov     bx,handle       ; Get handle.
        mov     ah,44h          ; Set function code.
        int     21h             ; Call MS-DOS.
        jnc     isnoerr         ; Branch if no error.
        mov     ax,-1           ; Return error code.
        jmp     short isx
isnoerr:
        and     ax,1            ; Keep only lsb for return value.
isx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 08H
IOCTL: Check If Block Device Is Removable
3.0 and later


    Function 44H Subfunction 08H checks whether the specified block device
    contains a removable storage medium, such as a floppy disk.

To Call

    AH   = 44H
    AL   = 08H
    BL   = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)

Returns

    If function is successful:

    Carry flag is clear.

    AX   = 00H    storage medium removable
        = 01H    storage medium not removable

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid function
        = 0FH    invalid drive

Programmer's Notes

    ■  This subfunction exists to allow an application to check for a
        removable disk so that the user can be prompted to change disks if
        a required file is not found.

    ■  When the carry flag is set, error code 01H normally means that MS-
        DOS did not recognize the function call. However, this error can
        also mean that the device driver does not support Subfunction 08H.
        In this case, MS-DOS assumes that the storage medium is not
        removable.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;      Function 44H, Subfunction 08H:                        ;
        ;                    IOCTL Removable Block Device Query      ;
        ;                                                            ;
        ;      int ioctl_block_fixed(drive_ltr)                      ;
        ;          int drive_ltr;                                    ;
        ;                                                            ;
        ;      Returns -1 for all errors, 1 if disk is fixed (not    ;
        ;      removable), 0 if disk is not fixed.                   ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_block_fixed,PUBLIC
parmB   drive_ltr
cBegin
        mov     bl,drive_ltr    ; Get drive letter.
        or      bl,bl           ; Leave 0 alone.
        jz      ibch
        and     bl,not 20h      ; Convert letter to uppercase.
        sub     bl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
ibch:
        mov     ax,4408h        ; Set function code, Subfunction 08H.
        int     21h             ; Call MS-DOS.
        jnc     ibchx           ; Branch if no error, AX = 0 or 1.
        cmp     ax,1            ; Treat error code of 1 as "disk is
                                ; fixed."
        je      ibchx
        mov     ax,-1           ; Return -1 for other errors.
ibchx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 09H
IOCTL: Check If Block Device Is Remote
3.1 and later


    Function 44H Subfunction 09H checks whether the specified block device
    is local (attached to the computer running the program) or remote
    (redirected to a network server).

To Call

    AH   = 44H
    AL   = 09H
    BL   = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)

Returns

    If function is successful:

    Carry flag is clear.

    DX   = device attribute word:
        = bit 12 = 1    drive is remote
        = bit 12 = 0    drive is local

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid function
        = 0FH    invalid drive

Programmer's Notes

    ■  This subfunction should be avoided. Application programs should not
        distinguish between files on local and remote devices.

    ■  When the carry flag is set, error code 01H can mean either that the
        function number is invalid or that the network has not been
        started.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;        Function 44H, Subfunction 09H:                      ;
        ;                      IOCTL Remote Block Device Query       ;
        ;                                                            ;
        ;        int ioctl_block_redir(drive_ltr)                    ;
        ;            int drive_ltr;                                  ;
        ;                                                            ;
        ;        Returns -1 for all errors, 1 if disk is remote      ;
        ;        (redirected), 0 if disk is local.                   ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_block_redir,PUBLIC
parmB   drive_ltr
cBegin
        mov     bl,drive_ltr    ; Get drive letter.
        or      bl,bl           ; Leave 0 alone.
        jz      ibr
        and     bl,not 20h      ; Convert letter to uppercase.
        sub     bl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
ibr:
        mov     ax,4409h        ; Set function code, Subfunction 09H.
        int     21h             ; Call MS-DOS.
        mov     ax,-1           ; Assume error.
        jc      ibrx            ; Branch if error, returning -1.
        inc     ax              ; Set AX = 0.
        test    dh,10h          ; Is bit 12 set?
        jz      ibrx            ; If not, disk is local: Return 0.
        inc     ax              ; Return 1 for remote disk.
ibrx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 0AH
IOCTL: Check If Handle Is Remote
3.1 and later


    Function 44H Subfunction 0AH checks whether the handle in BX refers to
    a file or device that is local (on the computer running the program)
    or remote (redirected to a network server).

To Call

    AH   = 44H
    AL   = 0AH
    BX   = handle

Returns

    If function is successful:

    Carry flag is clear.

    DX   = attribute word for file or device:
        = bit 15 = 1    remote
        = bit 15 = 0    local

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid function
        = 06H    invalid handle

Programmer's Notes

    ■  Application programs should not distinguish between files on local
        and remote devices.

    ■  When the carry flag is set, error code 01H can mean either that the
        function number is invalid or that the network has not been
        started.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;    Function 44H, Subfunction 0AH:                          ;
        ;                  IOCTL Remote Handle Query                 ;
        ;                                                            ;
        ;    int ioctl_char_redir(handle)                            ;
        ;        int handle;                                         ;
        ;                                                            ;
        ;    Returns -1 for all errors, 1 if device/file is remote   ;
        ;    (redirected), 0 if it is local.                         ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_char_redir,PUBLIC
parmW   handle
cBegin
        mov     bx,handle       ; Get handle.
        mov     ax,440ah        ; Set function code, Subfunction 0AH.
        int     21h             ; Call MS-DOS.
        mov     ax,-1           ; Assume error.
        jc      icrx            ; Branch on error, returning -1.
        inc     ax              ; Set AX = 0.
        test    dh,80h          ; Is bit 15 set?
        jz      icrx            ; If not, device/file is local:
                                ; Return 0.
        inc     ax              ; Return 1 for remote.
icrx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 0BH
IOCTL: Change Sharing Retry Count
3.1 and later


    Function 44H Subfunction 0BH sets the number of times MS-DOS retries a
    disk operation after a failure caused by a file-sharing violation
    before it returns an error to the requesting process.

To Call

    AH   = 44H
    AL   = 0BH
    CX   = pause between retries
    DX   = number of retries

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H      invalid function

Programmer's Notes

    ■  The pause between retries is a machine-dependent value determined
        by the CPU and CPU clock speed. MS-DOS performs a delay loop that
        consists of 65,536 machine instructions for each iteration
        specified by the value in CX. The actual code is as follows:

        xor    cx,cx
        loop   $

        The default number of retries is 3, with a pause of one loop
        between retries--equivalent to calling this subfunction with
        DX = 3 and CX = 1.

    ■  When the carry flag is set, error code 01H indicates either that
        the function code is invalid or that file sharing (SHARE.EXE) is
        not loaded.

    ■  Subfunction 0BH can be used to tune the system if file-contention
        problems are likely to arise with shared files but are expected to
        last only a short while.

    ■  If file contention is expected and if some applications will lock
        regions of the file for an appreciable period of time, the user may
        need to be informed. The best procedure is to set an initial small
        number of retries with a short pause period. After notifying the
        user, the application can wait a reasonable amount of time for file
        access by adjusting the retry or pause-period values.

        If a process uses this subfunction, it should restore the original
        default values for the pause and number of retries before
        terminating, to avoid unwanted effects on the behavior of
        subsequent processes.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;     Function 44H, Subfunction 0BH:                         ;
        ;                   IOCTL Change Sharing Retry Count         ;
        ;                                                            ;
        ;     int ioctl_set_retry(num_retries,wait_time)             ;
        ;         int num_retries;                                   ;
        ;         int wait_time;                                     ;
        ;                                                            ;
        ;     Returns 0 for success, otherwise returns error code.   ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_set_retry,PUBLIC,<ds,si>
parmW   num_retries
parmW   wait_time
cBegin
        mov     dx,num_retries  ; Get parameters.
        mov     cx,wait_time
        mov     ax,440bh        ; Set function code, Subfunction 0BH.
        int     21h             ; Call MS-DOS.
        jc      isrx            ; Branch on error.
        xor     ax,ax
isrx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 0CH
IOCTL: Generic I/O Control for Handles
3.2


    Function 44H Subfunction 0CH sets or gets the output iteration count
    for character-oriented devices. See also APPENDIX A: MS-DOS
    VERSION 3.3.

To Call

    AH      = 44H
    AL      = 0CH
    BX      = handle
    CH      = category code:
            = 05H    printer
    CL      = function (minor) code:
            = 45H    set iteration count
            = 65H    get iteration count
    DS:DX   = segment:offset of 2-byte buffer receiving or containing
            iteration-count word

Returns

    If function is successful:

    Carry flag is clear.

    If CL was 65H on call:

    DS:DX     = segment:offset of iteration-count word

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function
            = 06H      invalid handle

Programmer's Notes

    ■  The iteration count controls the number of times the device driver
        tries to send output to the printer before assuming that the device
        is busy.

    ■  With MS-DOS version 3.2, only category code 05H (printer) is
        supported by this subfunction.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;   Function 44H, Subfunction 0CH:                           ;
        ;                 Generic IOCTL for Handles                  ;
        ;                                                            ;
        ;   int ioctl_char_generic(handle,category,function,pbuffer) ;
        ;       int   handle;                                        ;
        ;       int   category;                                      ;
        ;       int   function;                                      ;
        ;       int  *pbuffer;                                       ;
        ;                                                            ;
        ;   Returns 0 for success, otherwise returns error code.     ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_char_generic,PUBLIC,<ds>
parmW   handle
parmB   category
parmB   function
parmDP  pbuffer
cBegin
        mov     bx,handle       ; Get device handle.
        mov     ch,category     ; Get category
        mov     cl,function     ; and function.
        loadDP  ds,dx,pbuffer   ; Get pointer to data buffer.
        mov     ax,440ch        ; Set function code, Subfunction 0CH.
        int     21h             ; Call MS-DOS.
        jc      icgx            ; Branch on error.
        xor     ax,ax
icgx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 0DH
IOCTL: Generic I/O Control for Block Devices
3.2


    Function 44H Subfunction 0DH includes six input/output tasks, or minor
    functions, related to block-oriented devices. The tasks perform the
    following operations: set or get device parameters; write, read,
    format and verify, or verify tracks on a logical drive.

    This entry covers general information on Subfunction 0DH. Details on
    each minor code are presented in subsequent entries.

To Call

    AH      = 44H
    AL      = 0DH
    BL      = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)
    CH      = category code:
            = 08H    disk drive
    CL      = function (minor) code:
            = 40H    set parameters for block device
            = 41H    write track on logical drive
            = 42H    format and verify track on logical drive
            = 60H    get parameters for block device
            = 61H    read track on logical drive
            = 62H    verify track on logical drive
    DS:DX   = segment:offset of parameter block

Returns

    If function is successful:

    Carry flag is clear.

    If CL was 60H or 61H on call:

    DS:DX    = segment:offset of parameter block

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H  invalid function
            = 02H  invalid drive

Programmer's Notes

    ■  Set Device Parameters (minor code 40H) must be used before an
        attempt to write, read, format, or verify a track on a logical
        drive. In general, the following sequence applies to any of these
        operations:

        1. Get the current parameters (minor code 60H). Examine and save
        them.

        2. Set the new parameters (minor code 40H).

        3. Perform the task.

        4. Retrieve the original parameters and restore them
        (minor code 40H).

    ■  With version 3.2 of MS-DOS, only category code 08H is supported by
        this subfunction.

    ■  Parameter blocks in the data buffer vary with the task being
        performed.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;    Function 44H, Subfunction 0DH:                          ;
        ;                  Generic IOCTL for Block Devices           ;
        ;                                                            ;
        ;    int ioctl_block_generic(drv_ltr,category,func,pbuffer)  ;
        ;        int   drv_ltr;                                      ;
        ;        int   category;                                     ;
        ;        int   func;                                         ;
        ;        char *pbuffer;                                      ;
        ;                                                            ;
        ;    Returns 0 for success, otherwise returns error code.    ;
        ;                                                            ;
        ;************************************************************;

cProc   ioctl_block_generic,PUBLIC,<ds>
parmB   drv_ltr
parmB   category
parmB   func
parmDP  pbuffer
cBegin
        mov     bl,drv_ltr      ; Get drive letter.
        or      bl,bl           ; Leave 0 alone.
        jz      ibg
        and     bl,not 20h      ; Convert letter to uppercase.
        sub     bl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
ibg:
        mov     ch,category     ; Get category
        mov     cl,func         ; and function.
        loadDP  ds,dx,pbuffer   ; Get pointer to data buffer.
        mov     ax,440dh        ; Set function code, Subfunction 0DH.
        int     21h             ; Call MS-DOS.
        jc      ibgx            ; Branch on error.
        xor     ax,ax
ibgx:
cEnd



Interrupt 21H (33) Function 44H (68) Subfunction 0DH Minor Code 40H
IOCTL: Generic I/O Control for Block Devices: Set Device Parameters


    Function 44H Subfunction 0DH minor code 40H sets device parameters in
    the parameter block pointed to by DS:DX.

To Call

    AH      = 44H
    AL      = 0DH
    BL      = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)
    CH      = category code:
            = 08H    disk drive
    CL      = 40H
    DS:DX   = segment:offset of parameter block

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function
            = 02H      invalid drive

Programmer's Notes

    ■  The parameter block is formatted as follows:

        ──────────────────────────────────────────────────────────────────
        Special-functions field: offset 00H, length 1 byte
        ──────────────────────────────────────────────────────────────────
        Bit      Value       Meaning
        ──────────────────────────────────────────────────────────────────
        0        0           Device BIOS parameter block (BPB) field
                            contains a new default BPB.
                1           Use current BPB.
        1        0           Use all fields in parameter block.
                1           Use track layout field only.
        2        0           Sectors in track may be different sizes. (This
                            setting should not be used.)
                1           Sectors in track are all same size; sector
                            numbers range from 1 to the total number of
                            sectors in the track. (This setting should
                            always be used.)
        3-7      0           Reserved.

        ──────────────────────────────────────────────────────────────────
        Device type field: offset 01H, length 1 byte
        ──────────────────────────────────────────────────────────────────
        Value    Meaning
        ──────────────────────────────────────────────────────────────────
        00H      320/360 KB 5.25-inch disk
        01H      1.2 MB 5.25-inch disk
        02H      720 KB 3.5-inch disk
        03H      Single-density 8-inch disk
        04H      Double-density 8-inch disk
        05H      Fixed disk
        06H      Tape drive
        07H      Other type of block device

        ──────────────────────────────────────────────────────────────────
        Device attributes field: offset 02H, length 1 word
        ──────────────────────────────────────────────────────────────────
        Bit      Value       Meaning
        ──────────────────────────────────────────────────────────────────
        0        0           Removable storage medium
                1           Nonremovable storage medium
        1        0           Door lock not supported
                1           Door lock supported
        2-15     0           Reserved

        ──────────────────────────────────────────────────────────────────
        Number of cylinders field: offset 04H, length 1 word
        ──────────────────────────────────────────────────────────────────
        Meaning: Maximum number of cylinders supported; set by
                device driver

        ──────────────────────────────────────────────────────────────────
        Media type field: offset 06H, length 1 byte
        ──────────────────────────────────────────────────────────────────
        Value            Meaning
        ──────────────────────────────────────────────────────────────────
        00H (default)    1.2 MB 5.25-inch disk
        01H              320/360 KB 5.25-inch disk

        ──────────────────────────────────────────────────────────────────
        Device BPB field: offset 07H, length 31 bytes.
        ──────────────────────────────────────────────────────────────────
        Meaning: See Programmer's Note below.
        ──────────────────────────────────────────────────────────────────
        If bit 0 = 0 in special-functions field, this field contains the
        new default BPB for the device.

        If bit 0 = 1 in special-functions field, BPB in this field is
        returned by the device driver in response to subsequent Build BPB
        requests.

        ──────────────────────────────────────────────────────────────────
        Track layout field: offset 26H, variable-length table
        ──────────────────────────────────────────────────────────────────
        Length        Meaning
        ──────────────────────────────────────────────────────────────────
        Word          Number of sectors in track
        Word          Number of first sector in track
        Word          Size of first sector in track
                    .
                    .
                    .
        Word          Number of last sector in track
        Word          Size of last sector in track

    ■  The device BPB field is a 31-byte data structure. Information
        contained in the device BPB field describes the current disk and
        disk control areas. The device BPB field is formatted as follows:

╓┌─────────────────────┌─────────────────────────────────────────────────────╖
        Byte          Meaning
        ──────────────────────────────────────────────────────────────────
        00-01H        Number of bytes per sector
        02H           Number of sectors per allocation unit
        03-04H        Number of sectors reserved, beginning at sector 0
        05H           Number of file allocation tables (FATs)
        06-07H        Maximum number of root-directory entries
        08-09H        Total number of sectors
        0AH           Media descriptor
        0B-0CH        Number of sectors per FAT
        0D-0EH        Number of sectors per track
        0F-10H        Number of heads
        11-14H        Number of hidden sectors
        15-1FH        Reserved

    ■  When Set Device Parameters (minor code 40H) is used, the number of
        cylinders should not be reset--some or all of the volume may become
        inaccessible.

    ■  Subfunction 0DH minor code 60H performs the complementary action,
        Get Device Parameters.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

    None



Interrupt 21H (33) Function 44H (68) Subfunction 0DH Minor Code 60H
IOCTL: Generic I/O Control for Block Devices: Get Device Parameters


    Function 44H Subfunction 0DH minor code 60H gets device parameters in
    the parameter block pointed to by DS:DX.

To Call

    AH      = 44H
    AL      = 0DH
    BL      = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)
    CH      = category code:
            = 08H    disk drive
    CL      = 60H
    DS:DX   = segment:offset of parameter block

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function
            = 02H      invalid drive

Programmer's Notes

    ■  The parameter block is formatted as follows:

        ──────────────────────────────────────────────────────────────────
        Special-functions field: offset 00H, length 1 byte
        ──────────────────────────────────────────────────────────────────
        Bit         Value       Meaning
        ──────────────────────────────────────────────────────────────────
        0           0           Returns default BIOS parameter block (BPB)
                                for the device.
                    1           Returns BPB that the Build BPB device
                                driver call would return.
        1-7         0           Reserved (must be zero).

        ──────────────────────────────────────────────────────────────────
        Device type field: offset 01H, length 1 byte
        ──────────────────────────────────────────────────────────────────
        Value       Meaning
        ──────────────────────────────────────────────────────────────────
        00          320/360 KB 5.25-inch disk
        01          1.2 MB 5.25-inch disk
        02          720 KB 3.5-inch disk
        03          Single-density 8-inch disk
        04          Double-density 8-inch disk
        05          Fixed disk
        06          Tape drive
        07          Other type of block device

        ──────────────────────────────────────────────────────────────────
        Device attributes field: offset 02H, length 1 word
        ──────────────────────────────────────────────────────────────────
        Bit         Value       Meaning
        ──────────────────────────────────────────────────────────────────
        0           0           Removable storage medium
                    1           Nonremovable storage medium
        1           0           Door lock not supported
                    1           Door lock supported
        2-15        0           Reserved

        ──────────────────────────────────────────────────────────────────
        Number of cylinders field: offset 04H, length 1 word
        ──────────────────────────────────────────────────────────────────
        Meaning: Maximum number of cylinders supported; set by device
                driver

        ──────────────────────────────────────────────────────────────────
        Media type field: offset 06H, length 1 byte
        ──────────────────────────────────────────────────────────────────

        Value               Meaning
        ──────────────────────────────────────────────────────────────────
        00H (default)       1.2 MB 5.25-inch disk
        01H                 320/360 KB 5.25-inch disk

        ──────────────────────────────────────────────────────────────────
        Device BPB field: offset 07H, length 31 bytes
        ──────────────────────────────────────────────────────────────────
        Meaning: See Programmer's Note below.
        ──────────────────────────────────────────────────────────────────
        If bit 0 = 0 in special-functions field, this field contains the
        new default BPB for the device.

        If bit 0 = 1 in special-functions field, BPB in this field is
        returned by the device driver in response to subsequent Build BPB
        requests.

        ──────────────────────────────────────────────────────────────────
        Track layout field: offset 26H
        ──────────────────────────────────────────────────────────────────
        Unused
        ──────────────────────────────────────────────────────────────────

    ■  The device BPB field is a 31-byte data structure. Information
        contained in the device BPB field describes the current disk and
        disk control areas. The device BPB field is formatted as follows:

╓┌─────────────────────┌─────────────────────────────────────────────────────╖
        Byte          Meaning
        ──────────────────────────────────────────────────────────────────
        00-01H        Number of bytes per sector
        02H           Number of sectors per allocation unit
        03-04H        Number of sectors reserved, beginning at sector 0
        05H           Number of file allocation tables (FATs)
        06-07H        Maximum number of root-directory entries
        08-09H        Total number of sectors
        0AH           Media descriptor
        0B-0CH        Number of sectors per FAT
        0D-0EH        Number of sectors per track
        0F-10H        Number of heads
        11-14H        Number of hidden sectors
        15-1FH        Reserved


    ■  Subfunction 0DH minor code 40H performs the complementary action,
        Set Device Parameters.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

    None



Interrupt 21H (33) Function 44H (68) Subfunction 0DH Minor Codes 41H and 61H
IOCTL: Generic I/O Control for Block Devices: Write Track on Logical Drive;
Read Track on Logical Drive


    Function 44H Subfunction 0DH minor code 41H writes a track on the
    logical drive specified in BL and minor code 61H reads a track on the
    logical drive specified in BL, using information in the parameter
    block pointed to by DS:DX.

To Call

    AH      = 44H
    AL      = 0DH
    BL      = drive number (0 = default drive, 1 = drive A, 2 = drive B,
            and so on)
    CH      = category code:
            = 08H    disk drive
    CL      = function (minor) code:
            = 41H    write a track
            = 61H    read a track
    DS:DX   = segment:offset of parameter block

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX        = error code:
            = 01H     invalid function
            = 02H     invalid drive

Programmer's Notes

    ■  The parameter block is formatted as follows:

╓┌────────────────┌────────┌─────────────────────────────────────────────────╖
        Offset   Size     Meaning
        ──────────────────────────────────────────────────────────────────
        00H      Byte     Special-functions field; must be 0.

        01H      Word     Head field; contains number of disk head used for
                        read/write.

        03H      Word     Cylinder field; contains number of disk cylinder
                        used for read/write.

        05H      Word     First-sector field; contains number of first
                        sector to read or write (first sector on track
                        = sector 0).

        07H      Word     Number-of-sectors field; contains number of
                        sectors to transfer.

        09H      Dword    Transfer address field; contains address of
                        buffer to use for data transfer.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

    None



Interrupt 21H (33) Function 44H (68) Subfunction 0DH Minor Codes 42H and 62H
IOCTL: Generic I/O Control for Block Devices: Format and Verify Track on
Logical Drive; Verify Track on Logical Drive


    Function 44H Subfunction 0DH minor code 42H formats and verifies a
    track on the specified logical drive and minor code 62H verifies a
    track on the specified logical drive, using information in the
    parameter block pointed to by DS:DX.

To Call

    AH      = 44H
    AL      = 0DH
    BL      = drive number (0 = default drive, 1 = drive A, 2 = drive B,
            and so on)
    CH      = category code:
            = 08H    disk drive
    CL      = function (minor) code:
            = 42H    format and verify
            = 62H    verify
    DS:DX   = segment:offset of parameter block

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function
            = 02H      invalid drive

Programmer's Notes

    ■  The parameter block is formatted as follows:

╓┌────────────────┌────────┌─────────────────────────────────────────────────╖
        Offset   Size     Meaning
        ──────────────────────────────────────────────────────────────────
        00H      Byte     Special-functions field; must be 0.

        01H      Word     Head field; contains number of disk head used for
                        format/verify.

        03H      Word     Cylinder field; contains number of cylinder used
                        for format/verify.

    ■  This driver subfunction allows the writing of generic formatting
        programs that are minimally hardware dependent.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

    None



Interrupt 21H (33) Function 44H (68) Subfunctions 0EH and 0FH
IOCTL: Get Logical Drive Map; Set Logical Drive Map
3.2


    Function 44H Subfunction 0EH allows a process to determine whether
    more than one logical drive is assigned to a block device. Subfunction
    0FH sets the next logical drive number that will be used to reference
    a block device.

To Call

    AH   = 44H
    AL   = 0EH    get logical drive map
        = 0FH    set logical drive map
    BL   = drive number (0 = default drive, 1 = drive A, 2 = drive B,
            and so on)

Returns

    If function is successful:

    Carry flag is clear.

    AL   = mapping code:
        = 00H      only one letter assigned to the block device
        = 01-1AH   logical drive letter (A through Z) mapped to block
                    device

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H      invalid function
        = 0FH      invalid drive

Programmer's Notes

    ■  If a drive has not been assigned a logical mapping with Function
        44H Subfunction 0FH, the logical and physical drive references are
        the same. (The default is that logical drive A and physical drive A
        both refer to physical drive A.)

    ■  If this function is used to map logical drives to physical drives,
        the result is similar to MS-DOS's treatment of a single physical
        drive as both A and B on a system with one floppy-disk drive. With
        MS-DOS version 3.2, however, the installable device driver
        DRIVER.SYS extends this type of physical/logical referencing to
        other drives. Therefore, processes can prompt for disks themselves,
        instead of using the prompt provided by MS-DOS.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;*************************************************************;
        ;                                                             ;
        ;       Function 44H, Subfunctions 0EH, 0FH:                  ;
        ;                     IOCTL Get/Set Logical Drive Map         ;
        ;                                                             ;
        ;       int ioctl_drive_owner(setflag, drv_ltr)               ;
        ;           int setflag;                                      ;
        ;           int drv_ltr;                                      ;
        ;                                                             ;
        ;       Set setflag = 1 to change drive's map, 0 to get       ;
        ;       current map.                                          ;
        ;                                                             ;
        ;       Returns -1 for all errors, otherwise returns          ;
        ;       the block device's current logical drive letter.      ;
        ;                                                             ;
        ;*************************************************************;

cProc   ioctl_drive_owner,PUBLIC
parmB   setflag
parmB   drv_ltr
cBegin
        mov     al,setflag      ; Load setflag.
        and     al,1            ; Keep only lsb.
        add     al,0eh          ; AL = 0EH for get, 0FH for set.
        mov     bl,drv_ltr      ; Get drive letter.
        or      bl,bl           ; Leave 0 alone.
        jz      ido
        and     bl,not 20h      ; Convert letter to uppercase.
        sub     bl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
ido:
        mov     bh,0
        mov     ah,44h          ; Set function code.
        int     21h             ; Call MS-DOS.
        mov     ah,0            ; Clear high byte.
        jnc     idox            ; Branch if no error.
        mov     ax,-1-'A'       ; Return -1 for errors.
idox:
        add     ax,'A'          ; Return drive letter.
cEnd



Interrupt 21H (33) Function 45H (69)
Duplicate File Handle
2.0 and later


    Function 45H obtains an additional handle for a currently open file or
    device.

To Call

    AH   = 45H
    BX   = handle for open file or device

Returns

    If function is successful:

    Carry flag is clear.

    AX   = new handle number

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 04H      too many open files
        = 06H      invalid handle

Programmer's Notes

    ■  The file pointer for the new handle is set to the same position as
        the pointer for the original handle. Any subsequent changes to the
        file are reflected in both handles. Thus, using either handle for a
        read or write operation moves the file pointer associated with
        both.

    ■  Function 45H is often used to duplicate the handle assigned to
        standard input (0) or standard output (1) before a call to Function
        46H (Force Duplicate File Handle). The handle forced by Function
        46H can then be used for redirected input or output from or to a
        file or device.

    ■  Another use for Function 45H is to keep a file open while its
        directory entry is being updated to reflect a change in length. If
        a new handle is obtained with Function 45H and then closed with
        Function 3EH (Close File), the directory and FAT entries for the
        file are updated. At the same time, because the original handle
        remains open, the file need not be reopened for additional read or
        write operations.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    46H (Force Duplicate File Handle)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 45H: Duplicate File Handle            ;
        ;                                                            ;
        ;             int dup_handle(handle)                         ;
        ;                 int handle;                                ;
        ;                                                            ;
        ;             Returns -1 for errors,                         ;
        ;             otherwise returns new handle.                  ;
        ;                                                            ;
        ;************************************************************;

cProc   dup_handle,PUBLIC
parmW   handle
cBegin
        mov     bx,handle       ; Get handle to copy.
        mov     ah,45h          ; Set function code.
        int     21h             ; Ask MS-DOS to duplicate handle.
        jnb     dup_ok          ; Branch if copy was successful.
        mov     ax,-1           ; Else return -1.
dup_ok:
cEnd



Interrupt 21H (33) Function 46H (70)
Force Duplicate File Handle
2.0 and later


    Function 46H forces the open handle specified in CX to track the same
    file or device specified by the handle in BX.

To Call

    AH   = 46H
    BX   = open handle to be duplicated
    CX   = open handle to be forced

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 04H      too many open files
        = 06H      invalid handle

Programmer's Notes

    ■  The handle in BX must refer either to an open file or to any of the
        five standard handles reserved by MS-DOS: standard input, standard
        output, standard error, standard auxiliary, or standard printer.

    ■  If the handle in CX refers to an open file, the file is closed.

    ■  The file pointer for the duplicate handle is set to the same
        position as the pointer for the original handle. Changing the
        position of either file pointer moves the pointer associated with
        the other handle as well.

    ■  When used with Function 45H (Duplicate File Handle), Function 46H
        can be used to redirect input and output as follows:

        1. Duplicate the handle from which input or output will be
        redirected with Function 45H (Duplicate File Handle). Save
        the duplicated handle for later reference (Step 3).

        2. Call Function 46H, with the handle to be redirected from in
        the CX register and the handle to be redirected to in the BX
        register.

        3. To restore I/O redirection to its original state, call
        Function 46H again, with the redirected file handle from
        Step 2 in the CX register and the duplicated file handle from
        Step 1 in the BX register.

    This procedure is normally used to redirect a standard device, but it
    can redirect any device referenced by handles.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    45H (Duplicate File Handle)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 46H: Force Duplicate File Handle         ;
        ;                                                            ;
        ;          int dup_handle2(existhandle,newhandle)            ;
        ;              int existhandle,newhandle;                    ;
        ;                                                            ;
        ;          Returns -1 for errors,                            ;
        ;          otherwise returns newhandle unchanged.            ;
        ;                                                            ;
        ;************************************************************;

cProc   dup_handle2,PUBLIC
parmW   existhandle
parmW   newhandle
cBegin
        mov     bx,existhandle  ; Get handle of existing file.
        mov     cx,newhandle    ; Get handle to copy into.
        mov     ah,46h          ; Close handle CX and then
        int     21h             ; duplicate BX's handle into CX.
        mov     ax,newhandle    ; Prepare return value.
        jnb     dup2_ok         ; Branch if close/copy was successful.
        mov     ax,-1           ; Else return -1.
dup2_ok:
cEnd



Interrupt 21H (33) Function 47H (71)
Get Current Directory
2.0 and later


    Function 47H returns the path, excluding the drive and leading
    backslash, of the current directory for the specified drive.

To Call

    AH      = 47H
    DL      = drive number (0 = default drive, 1 = drive A,
            2 = drive B, and so on)
    DS:SI   = segment:offset of 64-byte buffer

Returns

    If function is successful:

    Carry flag is clear.

    Buffer is filled in with ASCIIZ pathname.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 0FH      invalid drive

Programmer's Notes

    ■  The string representing the pathname is returned as a null-
        terminated ASCII string (ASCIIZ).

    ■  This function does not return an error if the buffer is too small
        or is incorrectly identified. MS-DOS pathnames can be as long as 64
        characters; if the buffer is less than 64 bytes, MS-DOS can
        overwrite sections of memory outside the buffer.

    ■  The path returned by Function 47H starts at the root directory and
        fully specifies the path to the current directory but does not
        include a drive code or a leading backslash (\) character.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    3BH (Change Current Directory)

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 47H: Get Current Directory             ;
        ;                                                            ;
        ;            int get_dir(drive_ltr,pbuffer)                  ;
        ;                int drive_ltr;                              ;
        ;                char *pbuffer;                              ;
        ;                                                            ;
        ;            Returns -1 for bad drive,                       ;
        ;            otherwise returns pointer to pbuffer.           ;
        ;                                                            ;
        ;************************************************************;

cProc   get_dir,PUBLIC,<ds,si>
parmB   drive_ltr
parmDP  pbuffer
cBegin
        loadDP  ds,si,pbuffer   ; Get pointer to buffer.
        mov     dl,drive_ltr    ; Get drive number.
        or      dl,dl           ; Leave 0 alone.
        jz      gdir
        and     dl,not 20h      ; Convert letter to uppercase
        sub     dl,'A'-1        ; Convert to drive number: 'A' = 1,
                                ; 'B' = 2, etc.
gdir:
        mov     ah,47h          ; Set function code.
        int     21h             ; Call MS-DOS.
        mov     ax,si           ; Return pointer to buffer ...
        jnb     gd_ok
        mov     ax,-1           ; ... unless an error occurred.
gd_ok:
cEnd



Interrupt 21H (33) Function 48H (72)
Allocate Memory Block
2.0 and later


    Function 48H allocates a block of memory, in paragraphs (1 paragraph
    = 16 bytes), to the requesting process.

To Call

    AH   = 48H
    BX   = number of paragraphs to allocate

Returns

    If function is successful:

    Carry flag is clear.

    AX   = segment address of base of allocated block

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 07H      memory control blocks damaged
        = 08H      insufficient memory to allocate as requested
    BX   = size of largest available block (paragraphs)

Programmer's Notes

    ■  If the allocation succeeds, the address returned in AX is the
        segment of the base of the block. This address would be copied to a
        segment register (usually DS or ES) to access the memory within the
        block.

    ■  If the amount of memory requested is greater than the amount in any
        available contiguous block of memory, the number of paragraphs in
        the largest available memory block is returned in the BX register.

    ■  The default memory-management strategy in MS-DOS is to choose the
        first contiguous block of memory that fits the request, no matter
        how good the fit. With MS-DOS versions 3.0 and later, however, the
        memory-management strategy can be altered with Function 58H
        (Get/Set Allocation Strategy).

    ■  If a process actively allocates and frees blocks of memory, the
        transient program area (TPA) can become fragmented--that is, small
        blocks of memory can be orphaned because the memory-management
        strategy seeks contiguous blocks of memory.

    ■  If a process writes to memory outside the limits of the allocated
        block, it can destroy control structures for other memory blocks.
        This could result in failure of subsequent memory-management
        functions, and it will cause MS-DOS to print an error message and
        halt when the process terminates.

    ■  Initially, the MS-DOS loader allocates all available memory to .COM
        programs. Function 4AH (Resize Memory Block) can free memory for
        dynamic reallocation by a process or by its children.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    49H (Free Memory Block)
    4AH (Resize Memory Block)
    58H (Get/Set Allocation Strategy)

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 48H: Allocate Memory Block                ;
        ;                                                            ;
        ;         int get_block(nparas,pblocksegp,pmaxparas)         ;
        ;             int nparas,*pblockseg,*pmaxparas;              ;
        ;                                                            ;
        ;         Returns 0 if nparas are allocated OK and           ;
        ;         pblockseg has segment address of block,            ;
        ;         otherwise returns error code with pmaxparas        ;
        ;         set to maximum block size available.               ;
        ;                                                            ;
        ;************************************************************;

cProc   get_block,PUBLIC,ds
parmW   nparas
parmDP  pblockseg
parmDP  pmaxparas
cBegin
        mov     bx,nparas       ; Get size request.
        mov     ah,48h          ; Set function code.
        int     21h             ; Ask MS-DOS for memory.
        mov     cx,bx           ; Save BX.
        loadDP  ds,bx,pmaxparas
        mov     [bx],cx         ; Return result, assuming failure.
        jb      gb_err          ; Exit if error, leaving error code
                                ; in AX.
        loadDP  ds,bx,pblockseg
        mov     [bx],ax         ; No error, so store address of block.
        xor     ax,ax           ; Return 0.
gb_err:
cEnd



Interrupt 21H (33) Function 49H (73)
Free Memory Block
2.0 and later


    Function 49H releases a block of memory previously allocated with
    Function 48H (Allocate Memory Block).

To Call

    AH   = 49H
    ES   = segment address of memory block to release

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 07H    memory control blocks damaged
        = 09H    incorrect memory segment specified

Programmer's Notes

    ■  The memory segment pointed to by ES:0000H must have been allocated
        by Function 48H (Allocate Memory Block).

    ■  If a program has inadvertently damaged any of the system's memory
        control blocks by writing outside an allocated block, an attempt to
        free allocated memory results in error code 07H (memory control
        blocks damaged).

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    48H (Allocate Memory Block)
    4AH (Resize Memory Block)
    58H (Get/Set Allocation Strategy)

Example

        ;************************************************************;
        ;                                                            ;
        ;               Function 49H: Free Memory Block              ;
        ;                                                            ;
        ;               int free_block(blockseg)                     ;
        ;                   int blockseg;                            ;
        ;                                                            ;
        ;               Returns 0 if block freed OK,                 ;
        ;               otherwise returns error code.                ;
        ;                                                            ;
        ;************************************************************;

cProc   free_block,PUBLIC
parmW   blockseg
cBegin
        mov     es,blockseg     ; Get block address.
        mov     ah,49h          ; Set function code.
        int     21h             ; Ask MS-DOS to free memory.
        jb      fb_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if successful.
fb_err:
cEnd



Interrupt 21H (33) Function 4AH (74)
Resize Memory Block
2.0 and later


    Function 4AH adjusts the size of a previously allocated block of
    memory.

To Call

    AH   = 4AH
    BX   = new size of memory block, in paragraphs
    ES   = segment address of previously allocated memory block

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 07H      memory control blocks damaged
        = 08H      insufficient memory to allocate as requested
        = 09H      incorrect memory segment specified
    BX   = maximum number of paragraphs available (if an increase was
            requested)

Programmer's Notes

    ■  Function 4AH can be used to change the size of a memory block
        previously allocated with Function 48H (Allocate Memory Block) or
        to modify the amount of memory originally allocated to a process by
        MS-DOS.

    ■  If a process is denied an increase in the amount of memory it has
        been allocated, MS-DOS places the size of the largest contiguous
        block available in the BX register. The process can then notify the
        user of the problem and exit, or it can continue to operate in a
        reduced memory environment.

    ■  Because the MS-DOS loader allocates all available memory to .COM
        programs, such a program should use Function 4AH immediately (with
        the segment address of its program segment prefix, or PSP) to
        release any memory that is not needed. This is mandatory if the
        .COM program will either allocate memory dynamically or use
        Function 4BH (Load and Execute Program) to load a child process or
        overlay.

        In addition, if Function 4AH is used to adjust the amount of memory
        allocated to a .COM program, the stack pointer must be adjusted so
        that it is within the limits of the program's revised memory
        allocation.

    ■  If this function is used to shrink an allocated block, any memory
        above the new limit is not owned by the process and should never be
        used. If this function is used to expand an allocated block, the
        contents of memory above the old boundary are unpredictable and the
        memory should be initialized before use.

    ■  Although it is not possible to predict how much memory-resident
        software and how many installable device drivers will be used on a
        computer system, Function 4AH can reliably determine the amount of
        memory available to an application.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    48H (Allocate Memory Block)
    49H (Free Memory Block)
    58H (Get/Set Allocation Strategy)

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 4AH: Resize Memory Block                  ;
        ;                                                            ;
        ;         int modify_block(nparas,blockseg,pmaxparas)        ;
        ;             int nparas,blockseg,*pmaxparas;                ;
        ;                                                            ;
        ;         Returns 0 if modification was a success,           ;
        ;         otherwise returns error code with pmaxparas        ;
        ;         set to max number of paragraphs available.         ;
        ;                                                            ;
        ;************************************************************;

cProc   modify_block,PUBLIC,ds
parmW   nparas
parmW   blockseg
parmDP  pmaxparas
cBegin
        mov     es,blockseg     ; Get block address.
        mov     bx,nparas       ; Get nparas.
        mov     ah,4ah          ; Set function code.
        int     21h             ; Ask MS-DOS to change block size.
        mov     cx,bx           ; Save BX.
        loadDP  ds,bx,pmaxparas
        mov     [bx],cx         ; Set pmaxparas, assuming failure.
        jb      mb_exit         ; Branch if size change error.
        xor     ax,ax           ; Return 0 if successful.
mb_exit:
cEnd



Interrupt 21H (33) Function 4BH (75)
Load and Execute Program (EXEC)
2.0 and later


    Function 4BH, often called EXEC, loads a program file into memory and,
    optionally, executes the program. This function can also be used to
    load a program overlay.

To Call

    AH      = 4BH
    AL      = 00H    load and execute program
            = 03H    load overlay
    DS:DX   = segment:offset of ASCIIZ pathname for an executable
            program file
    ES:BX   = segment:offset of parameter block

Returns

    If function is successful:

    Carry flag is clear.

    With MS-DOS versions 2.x, all registers except CS and IP can be
    destroyed; with MS-DOS versions 3.x, registers are preserved.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H    invalid function (AL did not contain 00H or 03H)
            = 02H    file not found
            = 03H    path not found
            = 05H    access denied
            = 08H    insufficient memory
            = 0AH    bad environment
            = 0BH    bad format (AL = 00H only)

Programmer's Notes

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).

    ■  The handles for any files opened by the parent process before the
        call to Function 4BH are inherited by the child process, unless the
        parent specified otherwise in calling Function 3DH (Open File with
        Handle).

        All standard devices also remain open and available to the child
        process. Thus, the parent process can control the files used by the
        child process and control redirection for the child process.

    ■  If AL = 00H, the parameter block is 14 bytes long and formatted in
        four parts, as follows:

╓┌──────────────┌────────────┌───────────────────────────────────────────────╖
        Offset Length       Meaning
        ──────────────────────────────────────────────────────────────────
        00H    Word         Segment address of environment to be passed;
                            00H indicates child program inherits
                            environment of the current process.

        02H    Dword        Segment:offset address of command tail for the
                            new program segment prefix (PSP). Command tail
                            must be 128 bytes or fewer and formatted as a
                            count byte followed by an ASCII string and
                            terminated by a carriage return, as follows:

                            db     7,'a:mydoc',0Dh

                            The carriage return is not included in the
                            count; the command tail is placed at offset
                            80H in the new process's PSP.

        06H    Dword        Segment:offset address of an FCB to be copied
                            to the default FCB position at offset 5CH in
                            the new process's PSP.

        0AH    Dword        Segment:offset address of an FCB to be copied
                            to the default FCB position at offset 6CH in
                            the new process's PSP.

        If AL = 03H, the parameter block is 4 bytes long and formatted in
        two parts, as follows:

╓┌──────────────┌─────────┌──────────────────────────────────────────────────╖
        Offset Length    Meaning
        ──────────────────────────────────────────────────────────────────
        00H    Word      Segment address where the overlay is to be loaded.

        02H    Word      Relocation factor to be applied to the code image
                        (.EXE files only); not needed if the file is a
                        .COM program or is data.

    ■  The first 2 bytes of the parameter block for Function 4BH
        Subfunction 00H contain either the segment address for an
        environment block to be passed to the new process or zero. If the
        value is zero, the child process inherits an exact copy of the
        parent process's environment.

        The environment block must be aligned on a paragraph boundary (a
        multiple of 16 bytes). It can be as large as 32 KB, and it consists
        of a block of ASCIIZ strings, each in the following form:

        parameter=value

        For example:

        db     'VERIFY=ON',0

        The final string in the environment block is followed by a second
        zero byte. With MS-DOS versions 3.0 and later, the second zero is
        followed by a word containing a count and an ASCIIZ string
        containing the drive and pathname of the program file.

        The environment passed to the child process allows the parent
        process to send it messages regarding the system state or control
        parameters. The pathname included with MS-DOS versions 3.0 and
        later enables the child process to determine where it was loaded
        from.

    ■  If AL = 00H, MS-DOS creates a PSP for the new process and sets the
        terminate and Control-C addresses to the instruction in the parent
        process that follows the call to Function 4BH. If AL = 03H, no PSP
        is created.

    ■  Before AL = 00H is used to load and execute a process, the system
        must contain enough free memory to accommodate the new process.
        Function 4AH (Resize Memory Block) should be used, if necessary, to
        reduce the amount of memory allocated to the parent process. If the
        parent is a .COM program, allocated memory must be reduced, because
        a .COM program is given ownership of all available memory when it
        is executed.

        If Function 4BH is called with AL = 03H, free memory is not a
        factor, because MS-DOS assumes the new process is being loaded into
        the calling process's own address space.

    ■  If Function 4BH is called with AL = 00H, the child process remains
        in control until it executes an exit request, such as Function 4CH
        (Terminate Process with Return Code), or until Control-C or
        Control-Break is received or a critical error occurs and the user
        responds Abort to the Abort, Retry, Ignore? message.

    ■  With MS-DOS versions 2.x, SS and SP must be saved in the current
        code segment before Function 4BH is invoked with AL = 00H. When the
        parent process regains control, all registers other than CS:IP and
        the stack will most likely have been changed by loading and
        executing the child process.

    ■  Function 4BH with AL = 03H is useful for loading program overlays
        or for loading data to be used by the parent process (if that data
        requires relocation).

    ■  If the child process that is executed attempts to remain resident
        through either Interrupt 27H or Interrupt 21H Function 31H
        (Terminate and Stay Resident), system memory becomes permanently
        fragmented and subsequent processes can fail because of lack of
        memory.

    ■  The EXEC function (with AL = 00H) is commonly used to load a new
        copy of COMMAND.COM and then execute an MS-DOS command from within
        another program.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    31H (Terminate and Stay Resident)
    4CH (Terminate Process with Return Code)
    4DH (Get Return Code of Child Process)

Examples

        ;************************************************************;
        ;                                                            ;
        ;          Function 4BH: Load and Execute Program            ;
        ;                                                            ;
        ;          int execute(pprogname,pcmdtail)                   ;
        ;              char *pprogname,*pcmdtail;                    ;
        ;                                                            ;
        ;          Returns 0 if program loaded, ran, and             ;
        ;          terminated successfully, otherwise returns        ;
        ;          error code.                                       ;
        ;                                                            ;
        ;************************************************************;

sBegin  data
$cmdlen =     126
$cmd    db    $cmdlen+2 dup (?) ; Make space for command line, plus
                                ; 2 extra bytes for length and
                                ; carriage return.

$fcb    db      0               ; Make dummy FCB.
        db      'dummy   fcb'
        db      0,0,0,0

                                ; Here's the EXEC parameter block:
$epb    dw      0               ; 0 means inherit environment.
        dw      dataOFFSET $cmd ; Pointer to cmd line.
        dw      seg dgroup
        dw      dataOFFSET $fcb ; Pointer to FCB #1.
        dw      seg dgroup
        dw      dataOFFSET $fcb ; Pointer to FCB #2.
        dw      seg dgroup
sEnd    data
sBegin  code

$sp     dw      ?               ; Allocate space in code seg
$ss     dw      ?               ; for saving SS and SP.

Assumes ES,dgroup

cProc   execute,PUBLIC,<ds,si,di>
parmDP  pprogname
parmDP  pcmdtail
cBegin
        mov     cx,$cmdlen      ; Allow command line this long.
        loadDP  ds,si,pcmdtail  ; DS:SI = pointer to cmdtail string.

        mov     ax,seg dgroup:$cmd    ; Set ES = data segment.
        mov     es,ax
        mov     di,dataOFFSET $cmd+1  ; ES:DI = pointer to 2nd byte of
                                    ; our command-line buffer.
copycmd:
        lodsb                   ; Get next character.
        or      al,al           ; Found end of command tail?
        jz      endcopy         ; Exit loop if so.
        stosb                   ; Copy to command buffer.
        loop    copycmd
endcopy:
        mov     al,13
        stosb                   ; Store carriage return at
                                ; end of command.
        neg     cl
        add     cl,$cmdlen      ; CL = length of command tail.
        mov     es:$cmd,cl      ; Store length in command-tail buffer.

        loadDP  ds,dx,pprogname ; DS:DX = pointer to program name.
        mov     bx,dataOFFSET $epb ; ES:BX = pointer to parameter
                                ; block.

        mov     cs:$ss,ss       ; Save current stack SS:SP (because
        mov     cs:$sp,sp       ; EXEC function destroys stack).
        mov     ax,4b00h        ; Set function code.
        int     21h             ; Ask MS-DOS to load and execute
                                ; program.
        cli                     ; Disable interrupts.
        mov     ss,cs:$ss       ; Restore stack.
        mov     sp,cs:$sp
        sti                     ; Enable interrupts.
        jb      ex_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if no error.
ex_err:
cEnd
sEnd    code



        ;************************************************************;
        ;                                                            ;
        ;   Function 4BH: Load an Overlay Program                    ;
        ;                                                            ;
        ;   int load_overlay(pfilename,loadseg)                      ;
        ;       char *pfilename;                                     ;
        ;       int  loadseg;                                        ;
        ;                                                            ;
        ;   Returns 0 if program has been loaded OK,                 ;
        ;   otherwise returns error code.                            ;
        ;                                                            ;
        ;   To call an overlay function after it has been            ;
        ;   loaded by load_overlay(), you can use                    ;
        ;   a far indirect call:                                     ;
        ;                                                            ;
        ;   1. FTYPE (far *ovlptr)();                                ;
        ;   2. *((unsigned *)&ovlptr + 1) = loadseg;                 ;
        ;   3. *((unsigned *)&ovlptr) = offset;                      ;
        ;   4. (*ovlptr)(arg1,arg2,arg3,...);                        ;
        ;                                                            ;
        ;   Line 1 declares a far pointer to a                       ;
        ;   function with return type FTYPE.                         ;
        ;                                                            ;
        ;   Line 2 stores loadseg into the segment                   ;
        ;   portion (high word) of the far pointer.                  ;
        ;                                                            ;
        ;   Line 3 stores offset into the offset                     ;
        ;   portion (low word) of the far pointer.                   ;
        ;                                                            ;
        ;   Line 4 does a far call to offset                         ;
        ;   bytes into the segment loadseg                           ;
        ;   passing the arguments listed.                            ;
        ;                                                            ;
        ;   To return correctly, the overlay  must end with a far    ;
        ;   return instruction.  If the overlay is                   ;
        ;   written in Microsoft C, this can be done by              ;
        ;   declaring the overlay function with the                  ;
        ;   keyword "far".                                           ;
        ;                                                            ;
        ;************************************************************;

sBegin  data
                                ; The overlay parameter block:
$lob    dw      ?               ; space for load segment;
        dw      ?               ; space for fixup segment.
sEnd    data

sBegin  code

cProc   load_overlay,PUBLIC,<ds,si,di>
parmDP  pfilename
parmW   loadseg
cBegin
        loadDP  ds,dx,pfilename ; DS:DX = pointer to program name.
        mov     ax,seg dgroup:$lob ; Set ES = data segment.
        mov     es,ax
        mov     bx,dataOFFSET $lob ; ES:BX = pointer to parameter
                                ; block.
        mov     ax,loadseg      ; Get load segment parameter.
        mov     es:[bx],ax      ; Set both the load and fixup
        mov     es:[bx+2],ax    ; segments to that segment.

        mov     cs:$ss,ss       ; Save current stack SS:SP (because
        mov     cs:$sp,sp       ; EXEC function destroys stack).
        mov     ax,4b03h        ; Set function code.
        int     21h             ; Ask MS-DOS to load the overlay.
        cli                     ; Disable interrupts.

        mov     ss,cs:$ss       ; Restore stack.
        mov     sp,cs:$sp
        sti                     ; Enable interrupts.
        jb      lo_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if no error.
lo_err:
cEnd
sEnd    code



Interrupt 21H (33) Function 4CH (76)
Terminate Process with Return Code
2.0 and later


    Function 4CH terminates the current process with a return code and
    returns control to the calling (parent) process.

To Call

    AH   = 4CH
    AL   = return code

Returns

    Nothing

Programmer's Notes

    ■  When a process is terminated with Function 4CH, MS-DOS restores the
        termination-handler (Interrupt 22H), Control-C handler (Interrupt
        23H), and critical error handler (Interrupt 24H) addresses from the
        program segment prefix, or PSP (offsets 0AH, 0EH, and 12H). MS-DOS
        also flushes the file buffers to disk, updates the disk directory,
        closes all files with open handles belonging to the terminated
        process, and then transfers control to the termination-handler
        address.

    ■  On termination with Function 4CH, all memory owned by the process
        is freed.

    ■  Function 4CH is the recommended method for terminating all
        processes--particularly sizable .EXE files--that do not stay
        resident. This function should be used in preference to the other
        termination methods (Interrupt 20H, Interrupt 21H Function 00H,
        near RET for .COM files, or a jump to PSP:0000H). Memory-resident
        programs should be terminated with Function 31H (Terminate and Stay
        Resident).

    ■  A return code of 00H is customarily used to indicate that the
        process executed successfully; a nonzero return code is used to
        indicate that the process terminated because of an error or lack of
        resources--for example, the file could not be opened, the process
        could not be allocated sufficient memory, and so on.

    ■  If the terminated process was invoked by a command line or batch
        file, ckntrol returns to COMMAND.COM and the transient portion of
        the command interpreter is reloaded, if necessary. If a batch file
        was in progress, execution continues with the next line of the file
        and the return code can be tested with an IF ERRORLEVEL statement.
        Otherwise, the command prompt is issued.

        If the terminated process was loaded by a process other than
        COMMAND.COM, the parent process can retrieve the child's return
        code with Function 4DH (Get Return Code of Child Process).

    ■  In a networking environment running under MS-DOS version 3.1 or
        later, all file locks should be removed by the process before it
        calls Function 4CH to terminate.

Related Functions

    00H (Terminate Process)
    31H (Terminate and Stay Resident)
    4DH (Get Return Code of Child Process)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 4CH: Terminate Process with Return Code     ;
        ;                                                            ;
        ;       int terminate(returncode)                            ;
        ;           int returncode;                                  ;
        ;                                                            ;
        ;       Does NOT return at all!                              ;
        ;                                                            ;
        ;************************************************************;

cProc   terminate,PUBLIC
parmB   returncode
cBegin
        mov     al,returncode   ; Set return code.
        mov     ah,4ch          ; Set function code.
        int     21h             ; Call MS-DOS to terminate process.
cEnd



Interrupt 21H (33) Function 4DH (77)
Get Return Code of Child Process
2.0 and later


    Function 4DH retrieves the return code of a child process that was
    invoked with Function 4BH (Load and Execute Program) and terminated
    with either Function 31H (Terminate and Stay Resident) or Function 4CH
    (Terminate Process with Return Code).

To Call

    AH   = 4DH

Returns

    AH   = termination method:
        = 00H    normal termination (Interrupt 20H, or Interrupt 21H
                Function 00H or Function 4CH)
        = 01H    terminated by entry of Control-C
        = 02H    terminated by critical error handler (for example, user
                responded Abort to Abort, Retry, Ignore? prompt)
        = 03H    terminated and stayed resident (Interrupt 27H or
                Interrupt 21H Function 31H)
    AL   = return code passed by child process

    If terminated with Interrupt 20H, Interrupt 21H Function 00H, or
    Interrupt 27H:

    AL   = 00H

Programmer's Notes

    ■  Function 4DH can be used only once to retrieve the return code of a
        terminated process. Subsequent calls do not yield meaningful
        results.

    ■  Function 4DH does not set the carry flag to indicate an error. If
        no previous child process exists, the information returned in AH
        and AL is undefined.

Related Functions

    31H (Terminate and Stay Resident)
    4CH (Terminate Process with Return Code)

Example

        ;************************************************************;
        ;                                                            ;
        ;        Function 4DH: Get Return Code of Child Process      ;
        ;                                                            ;
        ;        int child_ret_code()                                ;
        ;                                                            ;
        ;        Returns the return code of the last                 ;
        ;        child process.                                      ;
        ;                                                            ;
        ;************************************************************;

cProc   child_ret_code,PUBLIC
cBegin
        mov     ah,4dh          ; Set function code.
        int     21h             ; Ask MS-DOS to return code.
        cbw                     ; Convert AL to a word.
cEnd



Interrupt 21H (33) Function 4EH (78)
Find First File
2.0 and later


    Function 4EH searches the specified directory for the first matching
    entry.

To Call

    AH      = 4EH
    CX      = attribute word
    DS:DX   = segment:offset of ASCIIZ pathname

Returns

    If function is successful:

    Carry flag is clear.

    Current disk transfer area (DTA) contains the following information
    about the file:

╓┌────────────────┌───────────────┌──────────────────────────────────────────╖
    Offset      Length (bytes)  Value
    ──────────────────────────────────────────────────────────────────────
    00H         21              Reserved for use by MS-DOS in subsequent
                                call to Function 4FH (Find Next File)

    15H         1               File attribute

    16H         2               Time of last write

    18H         2               Date of last write

    1AH         2               Low word of file size

    1CH         2               High word of file size

    1EH         13              Filename and extension in ASCIIZ form with
                                blanks removed and period inserted between
                                filename and extension

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 02H    file not found
            = 03H    path not found
            = 12H    no more files; no match found

Programmer's Notes

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).

    ■  The filename and extension portions of the pathname can contain the
        MS-DOS wildcards ? (match any character) and * (match all remaining
        characters).

    ■  The DTA should be set with Function 1AH (Set DTA Address) before
        Function 4EH is called. If no DTA address is set, MS-DOS uses a
        default 128-byte buffer at offset 80H in the program segment prefix
        (PSP).

    ■  The attribute word in CX controls the search as follows:

        - If the attribute word is 00H, only normal files are included in
        the search.

        - If the attribute word has any combination of bits 1, 2, and 4
        (hidden, system, and subdirectory bits) set, the search includes
        normal files as well as files with any of the attributes
        specified.

        - If the attribute word has bit 3 set (volume-label bit), only a
        matching volume label is returned.

        - Bits 0 and 5 (read-only and archive bits) are ignored by
        Function 4EH.

    ■  If Function 4FH (Find Next File) is used in conjunction with
        Function 4EH, the DTA must be preserved, because the first 21 bytes
        contain information needed by Function 4FH.

    ■  The time at which the file was last written is returned as a binary
        value in a word formatted as follows:


╓┌──────────────┌────────────────────────────────────────────────────────────╖
        Bits   Meaning
        ──────────────────────────────────────────────────────────────────
        0-4    Number of seconds divided by 2
        5-10   Minutes (0 through 59)
        11-15  Hours, based on a 24-hour clock (0 through 23)

    ■  The date on which the file was last written is returned as a binary
        value in a word formatted as follows:

╓┌──────────────┌────────────────────────────────────────────────────────────╖
        Bits   Meaning
        ──────────────────────────────────────────────────────────────────
        0-4    Day of the month
        5-8    Month (1 = January, 2 = February, 3 = March, and so on)
        9-15   Number of the year minus 1980

    ■  Function 4EH is preferred to Function 11H (Find First File) because
        it fully supports pathnames.

    ■  Function 59H (Get Extended Error Information ) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    11H (Find First File)
    12H (Find Next File)
    1AH (Set DTA Address)
    4FH (Find Next File)

Example

        ;************************************************************;
        ;                                                            ;
        ;               Function 4EH: Find First File                ;
        ;                                                            ;
        ;               int find_first(ppathname,attr)               ;
        ;                   char *ppathname;                         ;
        ;                   int  attr;                               ;
        ;                                                            ;
        ;               Returns 0 if a match was found,              ;
        ;               otherwise returns error code.                ;
        ;                                                            ;
        ;************************************************************;

cProc   find_first,PUBLIC,ds
parmDP  ppathname
parmW   attr
cBegin
        loadDP  ds,dx,ppathname ; Get pointer to pathname.
        mov     cx,attr         ; Get search attributes.
        mov     ah,4eh          ; Set function code.
        int     21h             ; Ask MS-DOS to look for a match.
        jb      ff_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if no error.
ff_err:
cEnd



Interrupt 21H (33) Function 4FH (79)
Find Next File
2.0 and later


    Function 4FH continues a search initiated by a previously successful
    call to Function 4EH (Find First File). The search is based on the
    pathname and attributes specified in the call to Function 4EH and uses
    information left in the current disk transfer area (DTA) by the call
    to Function 4EH or by a preceding call to Function 4FH.

To Call

    AH   = 4FH

    DTA contains information from prior search with Function 4EH or
    Function 4FH.

Returns

    If function is successful:

    Carry flag is clear.

    DTA is filled in as for a call to Function 4EH:

╓┌───────────────┌─────────────────┌─────────────────────────────────────────╖
    Offset     Length (bytes)    Value
    ─────────────────────────────────────────────────────────────────────
    00H        21                Reserved for use by MS-DOS in subsequent
                                call to Function 4FH
    15H         1                File attribute
    16H         2                Time of last write
    18H         2                Date of last write
    1AH         2                Low word of file size
    1CH         2                High word of file size
    1EH        13                Filename and extension in ASCIIZ form
                                with blanks removed and period inserted
                                between filename and extension

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 12H    no more files, no match found, or no previous call
                to Function 4EH

Programmer's Notes

    ■  If multiple calls to Function 4FH are used to find more than one
        matching file, the DTA setting (Function 1AH) and contents must be
        preserved because they provide information needed for continuing
        the search.

    ■  The time at which the file was last written is returned as a binary
        value in a word formatted as follows:

╓┌──────────────┌────────────────────────────────────────────────────────────╖
        Bits   Meaning
        ──────────────────────────────────────────────────────────────────
        0-4    Number of seconds divided by 2
        5-10   Minutes (0 through 59)
        11-15  Hours, based on a 24-hour clock (0 through 23)

    ■  The date on which the file was last written is returned as a binary
        value in a word formatted as follows:

╓┌──────────────┌────────────────────────────────────────────────────────────╖
        Bits   Meaning
        ──────────────────────────────────────────────────────────────────
        0-4    Day of the month
        5-8    Month (1 = January, 2 = February, 3 = March, and so on)
        9-15   Number of the year minus 1980

    ■  Function 4FH is preferred to Function 12H (Find Next File) because
        it fully supports pathnames.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    11H (Find First File)
    12H (Find Next File)
    1AH (Set DTA Address)
    4EH (Find First File)

Example

        ;************************************************************;
        ;                                                            ;
        ;               Function 4FH: Find Next File                 ;
        ;                                                            ;
        ;               int find_next()                              ;
        ;                                                            ;
        ;               Returns 0 if a match was found,              ;
        ;               otherwise returns error code.                ;
        ;                                                            ;
        ;************************************************************;

cProc   find_next,PUBLIC
cBegin
        mov     ah,4fh          ; Set function code.
        int     21h             ; Ask MS-DOS to look for the next
                                ; matching file.
        jb      fn_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if no error.
fn_err:
cEnd



Interrupt 21H (33) Function 54H (84)
Get Verify Flag
2.0 and later


    Function 54H returns the current value of the MS-DOS verify flag.

To Call

    AH   = 54H

Returns

    AL   = verify flag:
        = 00H    verify off; no read after write operation
        = 01H    verify on; read after write operation

Programmer's Notes

    ■  The default state of the verify flag is 00H (off).

    ■  The state of the verify flag can be changed either through a call
        to Function 2EH (Set/Reset Verify Flag) or by the user with the
        VERIFY ON and VERIFY OFF commands.

Related Function

    Function 2EH (Set/Reset Verify Flag)

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 54H: Get Verify Flag                   ;
        ;                                                            ;
        ;            int get_verify()                                ;
        ;                                                            ;
        ;            Returns current value of verify flag.           ;
        ;                                                            ;
        ;************************************************************;

cProc   get_verify,PUBLIC
cBegin
        mov     ah,54h          ; Set function code.
        int     21h             ; Read flag from MS-DOS.
        cbw                     ; Clear high byte of return value.

cEnd



Interrupt 21H (33) Function 56H (86)
Rename File
2.0 and later


    Function 56H renames a file and/or moves it to a new location in the
    hierarchical directory structure.

To Call

    AH      = 56H
    DS:DX   = segment:offset of existing ASCIIZ pathname for file
    ES:DI   = segment:offset of new ASCIIZ pathname for file

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 02H    file not found
            = 03H    path not found
            = 05H    access denied
            = 11H    not the same device

Programmer's Notes

    ■  The pathnames must be null-terminated ASCII strings (ASCIIZ).

    ■  The directory paths specified in DS:DX and ES:DI need not be
        identical. Thus, specifying different directory paths effectively
        moves a file from one directory to another.

    ■  Function 56H cannot be used to move a file to a different drive.
        Both the existing pathname and the new one must either contain the
        same drive identifier or default to the same drive.

    ■  If Function 56H returns error code 05H, the cause can be any of the
        following:

        - The new pathname would move the file to the root directory, but
        the root directory is full.

        - A file with the new pathname already exists.

        - The user is on a network and has insufficient access to either
        the existing file or the new subdirectory.

    ■  Unlike Function 17H (Rename File), Function 56H does not support
        the use of MS-DOS wildcard characters (? and *).

    ■  Function 56H should not be used to rename open files. An open file
        should be closed with Function 10H (Close File with FCB) or 3EH
        (Close File) before Function 56H is called to rename it.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    17H (Rename File)

Example

        ;************************************************************;
        ;                                                            ;
        ;                Function 56H: Rename File                   ;
        ;                                                            ;
        ;                int rename(poldpath,pnewpath)               ;
        ;                    char *poldpath,*pnewpath;               ;
        ;                                                            ;
        ;                Returns 0 if file moved OK,                 ;
        ;                otherwise returns error code.               ;
        ;                                                            ;
        ;************************************************************;

cProc   rename,PUBLIC,<ds,di>
parmDP  poldpath
parmDP  pnewpath
cBegin
        loadDP  es,di,pnewpath  ; ES:DI = pointer to newpath.
        loadDP  ds,dx,poldpath  ; DS:DX = pointer to oldpath.
        mov     ah,56h          ; Set function code.
        int     21h             ; Ask MS-DOS to rename file.
        jb      rn_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if no error.
rn_err:
cEnd



Interrupt 21H (33) Function 57H (87)
Get/Set Date/Time of File
2.0 and later


    Function 57H retrieves or sets the date and time of a file's directory
    entry.

To Call

    AH   = 57H
    AL   = 00H    get date and time
        = 01H    set date and time
    BX   = handle number

    If AL = 01H:

    CX   = time; binary value formatted as follows:

╓┌──────────────────────┌────────────────────────────────────────────────────╖
            Bits       Meaning
            ──────────────────────────────────────────────────────────────
            0-4        Number of seconds divided by 2
            5-10       Minutes (0 through 59)
            11-15      Hours, based on a 24-hour clock (0 through 23)

    DX   = date; binary value formatted as follows:

╓┌──────────────────────┌────────────────────────────────────────────────────╖
            Bits       Meaning
            ──────────────────────────────────────────────────────────────
            0-4        Day of the month (1 through 31)
            5-8        Month (1 = January, 2 = February, 3 = March,
                    and so on)
            9-15       Year minus 1980

Returns

    If function is successful:

    Carry flag is clear.

    If AL was 00H on call:

    CX   = time file was last modified; format as described above
    DX   = date file was last modified; format as described above

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid function (AL not 00H or 01H)
        = 06H    invalid handle

Programmer's Notes

    ■  Before the date and time in a file's directory entry can be
        retrieved or changed with Function 57H, a handle must be obtained
        by opening or creating the file using one of the following
        functions:

        - 3CH (Create File with Handle)

        - 3DH (Open File with Handle)

        - 5AH (Create Temporary File)

        - 5BH (Create New File)

    ■  Use of Function 57H to retrieve the date and time of a file is
        preferable to examining the fields of an open FCB directly.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    2AH (Get Date)
    2BH (Set Date)
    2CH (Get Time)
    2DH (Set Time)

Example

        ;************************************************************;
        ;                                                            ;
        ;      Function 57H: Get/Set Date/Time of File               ;
        ;                                                            ;
        ;      long file_date_time(handle,func,packdate,packtime)    ;
        ;           int handle,func,packdate,packtime;               ;
        ;                                                            ;
        ;      Returns a long -1 for all errors, otherwise packs     ;
        ;      date and time into a long integer,                    ;
        ;      date in high word, time in low word.                  ;
        ;                                                            ;
        ;************************************************************;

cProc   file_date_time,PUBLIC
parmW   handle
parmB   func
parmW   packdate
parmW   packtime
cBegin
        mov     bx,handle       ; Get handle.
        mov     al,func         ; Get function: 0 = read, 1 = write.
        mov     dx,packdate     ; Get date (if present).
        mov     cx,packtime     ; Get time (if present).
        mov     ah,57h          ; Set function code.
        int     21h             ; Call MS-DOS.

        mov     ax,cx           ; Set DX:AX = date/time, assuming no
                                ; error.
        jnb     dt_ok           ; Branch if no error.
        mov     ax,-1           ; Return -1 for errors.
        cwd                     ; Extend the -1 into DX.
dt_ok:
cEnd



Interrupt 21H (33) Function 58H (88)
Get/Set Allocation Strategy
3.0 and later


    Function 58H retrieves or sets the method MS-DOS uses to allocate
    memory blocks for a process that issues a memory-allocation request.

To Call

    AH   = 58H
    AL   = 00H    get allocation strategy
        = 01H    set allocation strategy

    If AL = 01H:

    BX   = allocation strategy:
        = 00H    use first (lowest available) block that fits
        = 01H    use block that fits best
        = 02H    use last (highest available) block that fits

Returns

    If function is successful:

    Carry flag is clear.

    If AL was 00H on call:

    AX   = allocation-strategy code:
        = 00H    first fit
        = 01H    best fit
        = 02H    last fit

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid function (AL not 00H or 01H)

Programmer's Notes

    ■  Allocation strategies determine how MS-DOS finds and allocates a
        block of memory to an application that issues a memory-allocation
        request with either Function 48H (Allocate Memory Block) or
        Function 4AH (Resize Memory Block).

        The three strategies are carried out as follows:

        - First fit (the default): MS-DOS works upward from the lowest
        available block and allocates the first block it encounters that
        is large enough to satisfy the request for memory. This strategy
        is followed consistently, even if the block allocated is much
        larger than required.

        - Best fit: MS-DOS searches all available memory blocks and then
        allocates the smallest block that satisfies the request,
        regardless of its location in the empty-block chain. This
        strategy maximizes the use of dynamically allocated memory at a
        slight cost in speed of allocation.

        - Last fit (the reverse of first fit): MS-DOS works downward from
        the highest available block and allocates the first block it
        encounters that is large enough to satisfy the request for
        memory. This strategy is followed consistently, even if the block
        allocated is much larger than required.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    48H (Allocate Memory Block)
    4AH (Resize Memory Block)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 58H: Get/Set Allocation Strategy         ;
        ;                                                            ;
        ;          int alloc_strategy(func,strategy)                 ;
        ;              int func,strategy;                            ;
        ;                                                            ;
        ;          Strategies:                                       ;
        ;                  0: First fit                              ;
        ;                  1: Best fit                               ;
        ;                  2: Last fit                               ;
        ;                                                            ;
        ;          Returns -1 for all errors, otherwise              ;
        ;          returns the current strategy.                     ;
        ;                                                            ;
        ;************************************************************;

cProc   alloc_strategy,PUBLIC
parmB   func
parmW   strategy
cBegin
        mov     al,func         ; AL = get/set selector.
        mov     bx,strategy     ; BX = new strategy (for AL = 01H).
        mov     ah,58h          ; Set function code.
        int     21h             ; Call MS-DOS.
        jnb     no_err          ; Branch if no error.
        mov     ax,-1           ; Return -1 for all errors.
no_err:
cEnd



Interrupt 21H (33) Function 59H (89)
Get Extended Error Information
3.0 and later


    Function 59H returns extended error information, including a suggested
    response, for the function call immediately preceding it.

To Call

    AH   = 59H
    BX   = 00H

Returns

    AX   = extended error code:
        = 00H    no error encountered
        = 01H    invalid function number
        = 02H    file not found
        = 03H    path not found
        = 04H    too many files open; no handles available
        = 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 disk drive
        = 10H    attempt to remove current directory
        = 11H    device not the same
        = 12H    no more files
        = 13H    write-protected disk
        = 14H    unknown unit
        = 15H    drive not ready
        = 16H    invalid command
        = 17H    data error based on cyclic redundancy check (CRC)
        = 18H    length of request structure invalid
        = 19H    seek error
        = 1AH    non-MS-DOS disk
        = 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 unavailable
        = 24H    sharing buffer exceeded
        = 25-31H reserved
        = 32H    unsupported network request
        = 33H    remote machine not listening
        = 34H    duplicate name on network
        = 35H    network name not found
        = 36H    network busy
        = 37H    device no longer exists on network
        = 38H    net BIOS command limit exceeded
        = 39H    error in network adapter hardware
        = 3AH    incorrect response from network
        = 3BH    unexpected network error
        = 3CH    remote adapt incompatible
        = 3DH    print queue full
        = 3EH    queue not full
        = 3FH    not enough room for print file
        = 40H    network name deleted
        = 41H    access denied
        = 42H    incorrect network device type
        = 43H    network name not found
        = 44H    network name limit exceeded
        = 45H    net BIOS session limit exceeded
        = 46H    temporary pause
        = 47H    network request not accepted
        = 48H    print or disk redirection paused
        = 49-4FH reserved
        = 50H    file already exists
        = 51H    reserved
        = 52H    cannot make directory
        = 53H    failure on Interrupt 24H (critical error)
        = 54H    out of structures
        = 55H    already assigned
        = 56H    invalid password
        = 57H    invalid parameter
        = 58H    net write fault
    BH   = error class
        = 01H    out of resource (such as storage)
        = 02H    temporary situation, expected to end; not an error
        = 03H    authorization problem
        = 04H    internal error in system software
        = 05H    hardware failure
        = 06H    system-software failure, such as missing or
                incorrect configuration files; not the fault of the
                active process
        = 07H    application-program error
        = 08H    file or item not found
        = 09H    file or item of invalid format or type or otherwise
                unsuitable
        = 0AH    file or item interlocked
        = 0BH    drive contains wrong disk, disk has bad spot, or other
                problem with storage medium
        = 0CH    already exists
        = 0DH    unknown
    BL   = suggested action:
        = 01H    perform a reasonable number of retries before
                prompting user to choose Abort or Ignore in response
                to error message
        = 02H    perform a reasonable number of retries, with pauses
                between, before prompting user to choose Abort or
                Ignore in response to error message
        = 03H    prompt user to enter corrected information, such as
                drive letter or filename
        = 04H    clean up and exit application
        = 05H    exit immediately without cleanup
        = 06H    ignore; informational error
        = 07H    prompt user to remove cause of error (for example,
                change disks) and then retry
    CH   = location of error:
        = 01H    unknown
        = 02H    block device
        = 03H    network
        = 04H    serial device
        = 05H    memory related

Programmer's Notes

    ■  The extended error codes returned by Function 59H correspond to the
        error values returned in AX by functions in MS-DOS versions 2.0 and
        later that set the carry flag on error. Versions 2.x of MS-DOS,
        however, provide a smaller set of error codes (01H through 12H)
        than do later versions.

        Thus, although Function 59H itself is not available in versions of
        MS-DOS earlier than 3.0, the matching of error codes to earlier
        versions helps ensure downward compatibility. Function 59H was also
        designed to be open-ended so that additional error codes could be
        incorporated as needed. As a result, processes should remain
        flexible in their use of this function and should not rely on a
        fixed set of code numbers for error detection.

    ■  Function 59H is useful in the following situations:

        - When MS-DOS encounters a hardware-related error condition and
        shifts control to an Interrupt 24H handler that has been created
        by the programmer

        - When a handle-related function sets the carry flag to indicate an
        error or when an FCB-related function indicates an error by
        returning 0FFH in the AL register

    ■  If a function call results in an error, Function 59H returns
        meaningful information only if it is the next call to MS-DOS. An
        intervening call to another MS-DOS function, whether explicit or
        indirect, causes the error value for the unsuccessful function to
        be lost.

    ■  Unlike most MS-DOS functions, Function 59H alters some registers
        that are not used to return results: CL, DX, SI, DI, ES, and DS.
        These registers must be preserved before a call to Function 59H if
        their contents are needed later.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;         Function 59H: Get Extended Error Information       ;
        ;                                                            ;
        ;         int extended_error(err,class,action,locus)         ;
        ;             int *err;                                      ;
        ;             char *class,*action,*locus;                    ;
        ;                                                            ;
        ;         Return value is same as err.                       ;
        ;                                                            ;
        ;************************************************************;

cProc   extended_error,PUBLIC,<ds,si,di>
parmDP  perr
parmDP  pclass
parmDP  paction
parmDP  plocus
cBegin
        push    ds              ; Save DS.
        xor     bx,bx
        mov     ah,59h          ; Set function code.
        int     21h             ; Request error info from MS-DOS.
        pop     ds              ; Restore DS.
        loadDP  ds,si,perr      ; Get pointer to err.
        mov     [si],ax         ; Store err.
        loadDP  ds,si,pclass    ; Get pointer to class.
        mov     [si],bh         ; Store class.
        loadDP  ds,si,paction   ; Get pointer to action.
        mov     [si],bl         ; Store action.
        loadDP  ds,si,plocus    ; Get pointer to locus.
        mov     [si],ch         ; Store locus.
cEnd



Interrupt 21H (33) Function 5AH (90)
Create Temporary File
3.0 and later


    Function 5AH uses the system clock to create a unique filename,
    appends the filename to the specified path, opens the temporary file,
    and returns a file handle that can be used for subsequent file
    operations.

To Call

    AH      = 5AH
    CX      = file attribute:
            = 00H    normal file
            = 01H    read-only file
            = 02H    hidden file
            = 04H    system file
    DS:DX   = segment:offset of ASCIIZ path, ending with a backslash
            character (\) and followed by 13 bytes of memory (to
            receive the generated filename)

Returns

    If function is successful:

    Carry flag is clear.

    AX      = handle
    DS:DX   = segment:offset of full pathname for temporary file

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 03H    path not found
            = 04H    too many open files; no handle available
            = 05H    access denied

Programmer's Notes

    ■  Only the drive and path to use for the new file should be specified
        in the buffer pointed to by DS:DX. The function appends an eight-
        character filename that is generated from the system time.

    ■  Function 5AH is valuable in such situations as print spooling on a
        network, where temporary files are created by many users.

    ■  The input string representing the path for the temporary file must
        be a null-terminated ASCII string (ASCIIZ).

    ■  In networking environments running under MS-DOS version 3.1 or
        later, MS-DOS opens the temporary file in compatibility mode.

    ■  MS-DOS does not delete temporary files; applications must do this
        for themselves.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    16H (Create File with FCB)
    3CH (Create File with Handle)
    5BH (Create New File)

Example

        ;************************************************************;
        ;                                                            ;
        ;             Function 5AH: Create Temporary File            ;
        ;                                                            ;
        ;             int create_temp(ppathname,attr)                ;
        ;                 char *ppathname;                           ;
        ;                 int attr;                                  ;
        ;                                                            ;
        ;             Returns -1 if file was not created,            ;
        ;             otherwise returns file handle.                 ;
        ;                                                            ;
        ;************************************************************;

cProc   create_temp,PUBLIC,ds
parmDP  ppathname
parmW   attr
cBegin
        loadDP  ds,dx,ppathname ; Get pointer to pathname.
        mov     cx,attr         ; Set function code.
        mov     ah,5ah          ; Ask MS-DOS to make a new file with
                                ; a unique name.
        int     21h             ; Ask MS-DOS to make a tmp file.
        jnb     ct_ok           ; Branch if MS-DOS returned handle.
        mov     ax,-1           ; Else return -1.
ct_ok:
cEnd



Interrupt 21H (33) Function 5BH (91)
Create New File
3.0 and later


    Function 5BH creates a new file with the specified pathname. This
    function operates like Function 3CH (Create File with Handle) but
    fails if the pathname references a file that already exists.

To Call

    AH      = 5BH
    CX      = file attribute:
            = 00H    normal file
            = 01H    read-only file
            = 02H    hidden file
            = 04H    system file
    DS:DX   = segment:offset of ASCIIZ pathname

Returns

    If function is successful:

    Carry flag is clear.

    AX      = handle

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 03H      path not found
            = 04H      too many open files; no handle available
            = 05H      access denied
            = 50H      file already exists

Programmer's Notes

    ■  The pathname must be a null-terminated ASCII string (ASCIIZ).

    ■  In networking environments running under MS-DOS version 3.1 or
        later, the file is opened in compatibility mode. Function 5BH
        fails, however, if the user does not have Create access to the
        directory that is to contain the file.

    ■  Function 5BH can be used to implement semaphores in the form of
        files across a local area network or in a multitasking environment.
        If the function succeeds, the semaphore has been acquired. To
        release the semaphore, the application simply deletes the
        file.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    16H (Create File with FCB)
    3CH (Create File with Handle)
    5AH (Create Temporary File)

Example

        ;************************************************************;
        ;                                                            ;
        ;          Function 5BH: Create New File                     ;
        ;                                                            ;
        ;          int create_new(ppathname,attr)                    ;
        ;              char *ppathname;                              ;
        ;              int attr;                                     ;
        ;                                                            ;
        ;          Returns -2 if file already exists,                ;
        ;                  -1 for all other errors,                  ;
        ;                  otherwise returns file handle.            ;
        ;                                                            ;
        ;************************************************************;

cProc   create_new,PUBLIC,ds
parmDP  ppathname
parmW   attr
cBegin
        loadDP  ds,dx,ppathname ; Get pointer to pathname.
        mov     cx,attr         ; Get new file's attribute.
        mov     ah,5bh          ; Set function code.
        int     21h             ; Ask MS-DOS to make a new file.
        jnb     cn_ok           ; Branch if MS-DOS returned handle.
        mov     bx,-2
        cmp     al,80           ; Did file already exist?
        jz      ae_err          ; Branch if so.
        inc     bx              ; Change -2 to -1.
ae_err:
        mov     ax,bx           ; Return error code.
cn_ok:
cEnd



Interrupt 21H (33) Function 5CH (92)
Lock/Unlock File Region
3.0 and later


    Function 5CH enables a process running in a networking or multitasking
    environment to lock or unlock a range of bytes in an open file.

To Call

    AH      = 5CH
    AL      = 00H    lock region
            = 01H    unlock region
    BX      = handle
    CX:DX   = 4-byte integer specifying beginning of region to be
            locked or unlocked (offset in bytes from beginning of file)
    SI:DI   = 4-byte integer specifying length of region (measured in
            bytes)

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H    invalid function (AL not 00H or 01H or file sharing
                    not loaded)
            = 06H    invalid handle
            = 21H    lock violation
            = 24H    sharing buffer exceeded

Programmer's Notes

    ■  A process that either closes a file containing a locked region or
        terminates with the file open leaves the file in an undefined
        state. Under either condition, MS-DOS might handle the file
        erratically. If the process can be terminated by Interrupt 23H
        (Control-C) or 24H (critical error), these interrupts should be
        trapped so that any locked regions in files can be unlocked before
        the process terminates.

    ■  Locking a portion of a file with Function 5CH denies all other
        processes both read and write access to the specified region of the
        file. This restriction also applies when open file handles are
        passed to a child process with Function 4BH (Load and Execute
        Program). Duplicate file handles created with Function 45H
        (Duplicate File Handle) and 46H (Force Duplicate File Handle),
        however, are allowed access to locked regions of a file within the
        current process.

    ■  Locking a region that goes beyond the end of a file does not cause
        an error.

    ■  Function 5CH is useful primarily in ensuring that competing
        programs or processes do not interfere while a record is being
        updated. Locking at the file level is provided by the sharing
        parameter in Function 3DH (Open File with Handle).

    ■  Function 5CH can also be used to check the lock status of a file.
        If an attempt to lock a needed portion of a file fails and error
        code 21H is returned in the AX register, the region is already
        locked by another process.

    ■  Any region locked with a call to Function 5CH must also be
        unlocked, and the same 4-byte integer values must be used for each
        operation. Two adjacent regions of a file cannot be locked
        separately and then be unlocked with a single unlock call. If the
        region to unlock does not correspond exactly to a locked region,
        Function 5CH returns error code 21H.

    ■  The length of time needed to hold locks can be minimized with the
        transaction-oriented programming model. This concept requires
        defining and performing an update in a uniform manner: Assert lock,
        read data, change data, remove lock.

    ■  If file sharing is not loaded, an application receives a 01H
        (function number invalid) error status when it attempts to lock a
        file. An immediate call to Function 59H returns the error locus as
        an unknown or a serial device.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    45H (Duplicate File Handle)
    46H (Force Duplicate File Handle)
    4BH (Load and Execute Program) [EXEC]

Example

        ;************************************************************;
        ;                                                            ;
        ;            Function 5CH: Lock/Unlock File Region           ;
        ;                                                            ;
        ;            int locks(handle,onoff,start,length)            ;
        ;                int handle,onoff;                           ;
        ;                long start,length;                          ;
        ;                                                            ;
        ;            Returns 0 if operation was successful,          ;
        ;            otherwise returns error code.                   ;
        ;                                                            ;
        ;************************************************************;

cProc   locks,PUBLIC,<si,di>
parmW   handle
parmB   onoff
parmD   start
parmD   length

cBegin
        mov     al,onoff        ; Get lock/unlock flag.
        mov     bx,handle       ; Get file handle.
        les     dx,start        ; Get low word of start.
        mov     cx,es           ; Get high word of start.
        les     di,length       ; Get low word of length.
        mov     si,es           ; Get high word of length.
        mov     ah,5ch          ; Set function code.
        int     21h             ; Make lock/unlock request.
        jb      lk_err          ; Branch on error.
        xor     ax,ax           ; Return 0 if no error.
lk_err:
cEnd



Interrupt 21H (33) Function 5EH (94) Subfunction 00H
Network Machine Name/Printer Setup: Get Machine Name
3.1 and later


    If Microsoft Networks is running, Function 5EH Subfunction 00H
    retrieves the network name of the local computer.

To Call

    AH      = 5EH
    AL      = 00H
    DS:DX   = segment:offset of 16-byte buffer

Returns

    If function is successful:

    Carry flag is clear.

    CH      = validity of machine name:
            = 00H      invalid
            = nonzero  valid
    CL      = NETBIOS number assigned to machine name
    DS:DX   = segment:offset of ASCIIZ machine name

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function; Microsoft Networks not running

Programmer's Notes

    ■  The NETBIOS number in CL and the name at DS:DX are valid only if
        the value returned in CH is nonzero.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    5FH (Get/Make Assign List Entry)

Example

    None



Interrupt 21H (33) Function 5EH (94) Subfunctions 02H and 03H
Network Machine Name/Printer Setup: Set Printer Setup; Get Printer Setup
3.1 and later


    Function 5EH Subfunctions 02H and 03H respectively set and get the
    setup string that MS-DOS adds to the beginning of a file sent to a
    network printer.

To Call

    AH      = 5EH
    AL      = 02H    set printer setup string
            = 03H    get printer setup string
    BX      = assign-list index number (obtained with Function 5FH
            Subfunction 02H)

    If AL = 02H:

    CX      = length of setup string in bytes (64 bytes maximum)
    DS:SI   = segment:offset of ASCII setup string

    If AL = 03H:

    ES:DI   = segment:offset of 64-byte buffer to receive string

Returns

    If function is successful:

    Carry flag is clear.

    If AL was 03H on call:

    CX      = length of printer setup string in bytes
    ES:DI   = segment:offset of ASCII printer setup string

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid subfunction

Programmer's Notes

    ■  Function 5EH Subfunctions 02H and 03H enable multiple users on a
        network to configure a shared printer as required. The assign-list
        number is an index to a table that identifies the printer as a
        device on the network. A process can determine the assign-list
        number for the printer by using Function 5FH Subfunction 02H (Get
        Assign-List Entry).

    ■  Error code 01H in the AX register may indicate either that
        Microsoft Networks is not running or that an invalid subfunction
        was selected.

    ■  Function 59H (Get Extended Error Information)
        provides further information on any error--in particular, the code,
        class, recommended corrective action, and locus of the error.

Related Function

    5FH (Get/Make Assign-List Entry)

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 5EH Subfunction 02H:                        ;
        ;                     Set Printer Setup                      ;
        ;                                                            ;
        ;       int printer_setup(index,pstring,len)                 ;
        ;           int   index;                                     ;
        ;           char *pstring;                                   ;
        ;           int   len;                                       ;
        ;                                                            ;
        ;       Returns 0, otherwise returns -1 for all errors.      ;
        ;                                                            ;
        ;************************************************************;

cProc   printer_setup,PUBLIC,<ds,si>
parmW   index
parmDP  pstring
parmW   len
cBegin
        mov     bx,index        ; BX = index of a net printer.
        loadDP  ds,si,pstring   ; DS:SI = pointer to string.
        mov     cx,len          ; CX = length of string.
        mov     ax,5e02h        ; Set function code.
        int     21h             ; Set printer prefix string.
        mov     al,0            ; Assume no error.
        jnb     ps_ok           ; Branch if no error,
        mov     al,-1           ; Else return -1.
ps_ok:
        cbw
cEnd



Interrupt 21H (33) Function 5FH (95) Subfunction 02H
Get/Make Assign-List Entry: Get Assign-List Entry
3.1 and later


    Function 5FH Subfunction 02H obtains the local and remote (network)
    names of a device. To find the names, MS-DOS uses the device's user-
    assigned index number (set with Function 5FH Subfunction 03H) to
    search a table of redirected devices on the network. Microsoft
    Networks must be running with file sharing loaded for this subfunction
    to operate successfully.

To Call

    AH      = 5FH
    AL      = 02H
    BX      = assign-list index number
    DS:SI   = segment:offset of 16-byte buffer for local (device) name
    ES:DI   = segment:offset of 128-byte buffer to receive remote
            (network) name

Returns

    If function is successful:

    Carry flag is clear.

    BH      = device status:
            = 00H    valid device
            = 01H    invalid device
    BL      = device type:
            = 03H    printer
            = 04H    drive
    CX      = user data
    DS:SI   = segment:offset of ASCIIZ string representing local
            device name
    ES:DI   = segment:offset of ASCIIZ string representing network
            name

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H    invalid function or Microsoft Networks not running
            = 12H    no more files

Programmer's Notes

    ■  All strings returned by this subfunction are null-terminated ASCII
        strings (ASCIIZ).

    ■  A successful call to this subfunction destroys the contents of the
        DX and BP registers.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    5EH Subfunction 00H (Get Machine Name)

Example

        ;************************************************************;
        ;                                                            ;
        ;    Function 5FH Subfunction 02H:                           ;
        ;                  Get Assign-List Entry                     ;
        ;                                                            ;
        ;    int get_alist_entry(index,                              ;
        ;           plocalname,premotename,                          ;
        ;           puservalue,ptype)                                ;
        ;        int  index;                                         ;
        ;        char *plocalname;                                   ;
        ;        char *premotename;                                  ;
        ;        int  *puservalue;                                   ;
        ;        int  *ptype;                                        ;
        ;                                                            ;
        ;    Returns 0 if the requested assign-list entry is found,  ;
        ;    otherwise returns error code.                           ;
        ;                                                            ;
        ;************************************************************;

cProc   get_alist_entry,PUBLIC,<ds,si,di>
parmW   index
parmDP  plocalname
parmDP  premotename
parmDP  puservalue
parmDP  ptype
cBegin
        mov     bx,index        ; Get list index.
        loadDP  ds,si,plocalname  ; DS:SI = pointer to local name
                                ; buffer.
        loadDP  es,di,premotename ; ES:DI = pointer to remote name
                                ; buffer.
        mov     ax,5f02h        ; Set function code.
        int     21h             ; Get assign-list entry.
        jb      ga_err          ; Exit on error.
        xor     ax,ax           ; Else return 0.
        loadDP  ds,si,puservalue ; Get address of uservalue.
        mov     [si],cx         ; Store user value.
        loadDP  ds,si,ptype     ; Get address of type.
        mov     bh,0
        mov     [si],bx         ; Store device type to type.
ga_err:
cEnd



Interrupt 21H (33) Function 5FH (95) Subfunction 03H
Get/Make Assign-List Entry: Make Assign-List Entry
3.1 and later


    Function 5FH Subfunction 03H redirects a local printer or disk drive
    to a network device and establishes an assign-list index number for
    the redirected device. Microsoft Networks must be running with file
    sharing loaded for this subfunction to operate successfully.

To Call

    AH      = 5FH
    AL      = 03H
    BL      = device type:
            = 03H    printer
            = 04H    drive
    CX      = user data
    DS:SI   = segment:offset of 16-byte ASCIIZ local device name
    ES:DI   = segment:offset of 128-byte ASCIIZ remote (network)
            device name and password in the form

            machine name\pathname,null,password,null

            For example:

            string  db      '\\mymach\wp',0,'blibbet',0

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H    invalid function or Microsoft Networks not running
        = 03H    path not found
        = 05H    access denied
        = 08H    insufficient memory
        = 0FH    redirection paused on server
        = 12H    no more files

Programmer's Notes

    ■  The strings used by this subfunction must be null-terminated ASCII
        strings (ASCIIZ). The ASCIIZ string pointed to by ES:DI (the
        destination, or remote, device) cannot be more than 128 bytes
        including the password, which can be a maximum of 8 characters. If
        the password is omitted, the pathname must be followed by 2 null
        bytes.

    ■  If BL = 03H, the string pointed to by DS:SI must be one of the
        following printer names: PRN, LPT1, LPT2, or LPT3. If the call is
        successful, output is redirected to a network print spooler, which
        must be named in the destination string. For printer redirection,
        MS-NET intercepts Interrupt 17H (BIOS Printer I/O). When
        redirection for a printer is canceled, all printing is sent to the
        first local printer (LPT1).

        If BL = 04H, the string pointed to by DS:SI can be a drive letter
        followed by a colon, such as E:, or it can be a null string. If the
        string represents a valid drive, a successful call redirects drive
        requests to the network directory named in the destination string.
        If DS:SI points to a null string, MS-DOS attempts to provide access
        to the network directory named in the destination string without
        redirecting any device.

    ■  Only printer and disk devices are supported in MS-DOS versions 3.1
        and later. COM1 and COM2 are not supported for network redirection,
        nor are the standard output or standard error devices
        supported.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

    5EH Subfunction 00H (Get Machine Name)

Example

        ;************************************************************;
        ;                                                            ;
        ;    Function 5FH Subfunction 03H:                           ;
        ;                  Make Assign-List Entry                    ;
        ;    int add_alist_entry(psrcname,pdestname,uservalue,type)  ;
        ;        char *psrcname,*pdestname;                          ;
        ;        int  uservalue,type;                                ;
        ;                                                            ;
        ;    Returns 0 if new assign-list entry is made, otherwise   ;
        ;    returns error code.                                     ;
        ;                                                            ;
        ;************************************************************;

cProc   add_alist_entry,PUBLIC,<ds,si,di>
parmDP  psrcname
parmDP  pdestname
parmW   uservalue
parmW   type
cBegin
        mov     bx,type         ; Get device type.
        mov     cx,uservalue    ; Get uservalue.
        loadDP  ds,si,psrcname  ; DS:SI = pointer to source name.
        loadDP  es,di,pdestname ; ES:DI = pointer to destination name.
        mov     ax,5f03h        ; Set function code.
        int     21h             ; Make assign-list entry.
        jb      aa_err          ; Exit if there was some error.
        xor     ax,ax           ; Else return 0.
aa_err:
cEnd



Interrupt 21H (33) Function 5FH (95) Subfunction 04H
Get/Make Assign-List Entry: Cancel Assign-List Entry
3.1 and later


    Function 5FH Subfunction 04H cancels the redirection of a local device
    to a network device previously established with Function 5FH
    Subfunction 03H (Make Assign-List Entry). Microsoft Networks must be
    running with file sharing loaded for this subfunction to operate
    successfully.

To Call

    AH      = 5FH
    AL      = 04H
    DS:SI   = segment:offset of ASCIIZ device name or path

Returns

    If function is successful:

    Carry flag is clear.

    If function is not successful:

    Carry flag is set.

    AX   = error code:
        = 01H      invalid function or Microsoft Networks not running
        = 03H      path not found
        = 05H      access denied
        = 08H      insufficient memory
        = 0FH      redirection paused on server
        = 12H      no more files

Programmer's Notes

    ■  The string pointed to by DS:SI must be a null-terminated ASCII
        string (ASCIIZ). This string can be any one of the following:

        -  The letter, followed by a colon, of a redirected local drive.
        This function restores the drive letter to its original,
        physical meaning.

        -  The name of a redirected printer: PRN, LPT1, LPT2, LPT3, or its
        machine-specific equivalent. This function restores the printer
        name to its original, physical meaning at the local workstation.

        -  A string, beginning with two backslashes (\\) followed by
        the name of a network directory. This function terminates the
        connection between the local workstation and the directory
        specified in the string.

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Function

        5EH Subfunction 00H (Get Machine Name)

Example

        ;************************************************************;
        ;                                                            ;
        ;    Function 5FH Subfunction 04H:                           ;
        ;                  Cancel Assign-List Entry                  ;
        ;                                                            ;
        ;    int cancel_alist_entry(psrcname)                        ;
        ;        char *psrcname;                                     ;
        ;                                                            ;
        ;    Returns 0 if assignment is canceled, otherwise returns  ;
        ;    error code.                                             ;
        ;                                                            ;
        ;************************************************************;

cProc   cancel_alist_entry,PUBLIC,<ds,si>
parmDP  psrcname
cBegin
        loadDP  ds,si,psrcname  ; DS:SI = pointer to source name.
        mov     ax,5f04h        ; Set function code.
        int     21h             ; Cancel assign-list entry.
        jb      ca_err          ; Exit on error.
        xor     ax,ax           ; Else return 0.
ca_err:
cEnd



Interrupt 21H (33) Function 62H (98)
Get Program Segment Prefix Address
3.0 and later


    Function 62H gets the segment address of the program segment prefix
    (PSP) for the current process.

To Call

    AH   = 62H

Returns

    BX   = segment address of PSP for current process

Programmer's Notes

    ■  The PSP is constructed by MS-DOS at the base of the memory
        allocated for a .COM or .EXE program being loaded into memory by
        the EXEC function, 4BH (Load and Execute Program). The PSP is 100H
        bytes and contains information useful to an executing program,
        including

        - The command tail

        - Default file control blocks (FCBs)

        - A pointer to the program's environment block

        - Previous addresses for MS-DOS Control-C, critical error, and
        terminate handlers

    ■  Function 59H (Get Extended Error Information) provides further
        information on any error--in particular, the code, class,
        recommended corrective action, and locus of the error.

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;       Function 62H: Get Program Segment Prefix Address     ;
        ;                                                            ;
        ;       int get_psp()                                        ;
        ;                                                            ;
        ;       Returns PSP segment.                                 ;
        ;                                                            ;
        ;************************************************************;

cProc   get_psp,PUBLIC
cBegin
        mov     ah,62h          ; Set function code.
        int     21h             ; Get PSP address.
        mov     ax,bx           ; Return it in AX.
cEnd



Interrupt 21H (33) Function 63H (99)
Get Lead Byte Table
2.25


    Function 63H, available only in MS-DOS version 2.25, includes three
    subfunctions that support 2-byte-per-character alphabets such as Kanji
    and Hangeul (Japanese and Korean characters sets). Subfunction 00H
    obtains the address of the legal lead byte ranges for the character
    sets; Subfunctions 01H and 02H set or obtain the value of the interim
    console flag, which determines whether interim characters are returned
    by certain console system calls.

To Call

    AH      = 63H
    AL      = 00H    get lead byte table address
            = 01H    set or clear interim console flag
            = 02H    get interim console flag

    If AL = 01H:

    DL      = interim console flag:
            = 00H    clear
            = 01H    set

Returns

    If function is successful:

    Carry flag is clear.

    If AL was 00H on call:

    DS:SI   = segment:offset of lead byte table

    If AL was 02H on call:

    DL      = value of interim console flag

    If function is not successful:

    Carry flag is set.

    AX      = error code:
            = 01H      invalid function

Programmer's Notes

    ■  Function 63H does not necessarily preserve any registers other than
        SS:SP, so register values should be saved before a call to this
        function. To avoid saving registers repeatedly, a process can
        either copy the table or save the pointer to the table for later
        use.

    ■  The lead byte table contains pairs of bytes that represent the
        inclusive boundary values for the lead bytes of the specified
        alphabet. Because of the way bytes are ordered by the 8086
        microprocessor family, the values must be read as byte values, not
        as word values.

    ■  If the interim console flag is set (DL = 01H) by a program through
        a call to Function 63H, the following functions return interim
        character information on request:

        - 07H (Character Input Without Echo)

        - 08H (Unfiltered Character Input Without Echo)

        - 0BH (Check Keyboard Status)

        - 0CH (Flush Buffer, Read Keyboard), if Function 07H or 08H is
        requested in AL

Related Functions

    None

Example

        ;************************************************************;
        ;                                                            ;
        ;   Function 63H: Get Lead Byte Table                        ;
        ;                                                            ;
        ;   char far *get_lead_byte_table()                          ;
        ;                                                            ;
        ;   Returns far pointer to table of lead bytes for multibyte ;
        ;   characters.  Will work only in MS-DOS 2.25!              ;
        ;                                                            ;
        ;************************************************************;

cProc   get_lead_byte_table,PUBLIC,<ds,si>
cBegin
        mov     ax,6300h        ; Set function code.
        int     21h             ; Get lead byte table.
        mov     dx,ds           ; Return far pointer in DX:AX.
        mov     ax,si
cEnd



Interrupt 22H (34)
Terminate Routine Address
1.0 and later


    The machine interrupt vector for Interrupt 22H (memory locations
    0000:0088H through 0000:008BH) contains the address of the routine
    that receives control when the currently executing program terminates
    by means of Interrupt 20H, Interrupt 27H, or Interrupt 21H Function
    00H, 31H, or 4CH.

To Call

    This interrupt should never be issued directly.

Returns

    Nothing

Programmer's Note

    ■  The address in this vector is copied into offsets 0AH through 0DH
        of the program segment prefix (PSP) when a program is loaded but
        before it begins executing. The address is restored from the PSP
        (in case it was modified by the application) as part of MS-DOS's
        termination handling.

Example

    None



Interrupt 23H (35)
Control-C Handler Address
1.0 and later


    The machine interrupt vector for Interrupt 23H (memory locations
    0000:008CH through 0000:008FH) contains the address of the routine
    that receives control when a Control-C (also Control-Break on IBM PC
    compatibles) is detected during any character I/O function and, if the
    Break flag is on, during most other MS-DOS function calls.

To Call

    This interrupt should never be issued directly.

Returns

    Nothing

Programmer's Notes

    ■  The address in this vector is copied into offsets 0EH through 11H
        of the program segment prefix (PSP) when a program is loaded but
        before it begins executing. The address is restored from the PSP
        (in case it was modified by the application) as part of MS-DOS's
        termination handling.

    ■  The initialization code for an application can use Interrupt 21H
        Function 25H (Set Interrupt Vector) to reset the Interrupt 23H
        vector to point to its own routine for Control-C handling. By
        installing its own Control-C handler, the program can avoid being
        terminated as a result of keyboard entry of a Control-C or Control-
        Break.

    ■  When a Control-C is detected and the program's Interrupt 23H
        handler receives control, MS-DOS sets all registers to the original
        values they had when the function call that is being interrupted
        was made. The program's interrupt handler can then do any of the
        following:

        -  Set a local flag for later inspection by the application (or
        take any other appropriate action) and then perform a return
        from interrupt (IRET) to return control to MS-DOS. (All
        registers must be preserved.) The MS-DOS function in progress is
        then restarted and proceeds to completion, and control finally
        returns to the application in the normal manner.

        -  Take appropriate action and then perform a far return (RET FAR)
        to give control back to MS-DOS. MS-DOS uses the state of the
        carry flag to determine what action to take: If the carry flag
        is set, the application is terminated; if the carry flag is
        clear, the application continues in the normal manner.

        -  Retain control by transferring to an error-handling routine
        within the application and then resume execution or take other
        appropriate action, never performing a RET FAR or IRET to end
        the interrupt-handling sequence. This option causes no harm to
        the system.

    ■  Any MS-DOS function call can be used within the body of an
        Interrupt 23H handler.

Example

    None



Interrupt 24H (36)
Critical Error Handler Address
1.0 and later


    The machine interrupt vector for Interrupt 24H (memory locations
    0000:0090H through 0000:0093H) contains the address of the routine
    that receives control when a critical error (usually a hardware error)
    is detected.

To Call

    This interrupt should never be issued directly.

Returns

    Nothing

Programmer's Notes

    ■  The address of this vector is copied into offsets 12H through 15H
        of the program segment prefix (PSP) when a program is loaded but
        before it begins executing. The address is restored from the PSP
        (in case it was modified by the application) as part of MS-DOS's
        termination handling.

    ■  On entry to the critical error interrupt handler, bit 7 of register
        AH is clear (0) if the error was a disk I/O error; otherwise, it is
        set (1). BP:SI contains the address of a device-header control
        block from which additional information can be obtained. Interrupts
        are disabled. MS-DOS sets up the registers for a retry operation
        and one of the following error codes is in the lower byte of the DI
        register (the upper byte is undefined):

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Code     Meaning
        ──────────────────────────────────────────────────────────────────
        00H      Write-protect error
        01H      Unknown unit
        02H      Drive not ready
        03H      Unknown command
        04H      Data error (bad CRC)
        05H      Bad request structure length
        06H      Seek error
        07H      Unknown media type
        08H      Sector not found
        09H      Printer out of paper
        0AH      Write fault
        0BH      Read fault
        0CH      General failure
        0FH      Invalid disk change

        These are the same error codes returned by the device drivers in
        the request header.

    ■  On a disk error, MS-DOS retries the operation three times before
        transferring to the Interrupt 24H handler.

    ■  On entry to the Interrupt 24H handler, the stack is set up as
        follows:


┌───────────────────────┐
│                       │▒
│         Flags         │▒
├───────────────────────┤▒
│                       │▒ Flags and CS:IP pushed on stack
│          CS           │▒  by original Interrupt 21H call
├───────────────────────┤▒
│                       │▒
│          IP           │▒
├───────────────────────┤─ SP on entry to Interrupt 21H handler
│                       │▒
│          ES           │▒
├───────────────────────┤▒
│                       │▒
│          DS           │▒
├───────────────────────┤▒
│                       │▒
│          BP           │▒
├───────────────────────┤▒
│                       │▒
│          DI           │▒
├───────────────────────┤▒
│                       │▒ Registers at point of
│          SI           │▒  original Interrupt 21H call
├───────────────────────┤▒
│                       │▒
│          DX           │▒
├───────────────────────┤▒
│                       │▒
│          CX           │▒
├───────────────────────┤▒
│                       │▒
│          BX           │▒
├───────────────────────┤▒
│                       │▒
│          AX           │▒
├───────────────────────┤
│                       │▒
│         Flags         │▒
├───────────────────────┤▒
│                       │▒ Return address from
│          CS           │▒  Interrupt 24H handler
├───────────────────────┤▒
│                       │▒
│          IP           │▒
└───────────────────────┘─  SP on entry to Interrupt 24H handler


    ■  Interrupt 24H handlers must preserve the SS, SP, DS, ES, BX, CX,
        and DX registers. Only Interrupt 21H Functions 01H through 0CH,
        30H, and 59H can be used by an Interrupt 24H handler; other calls
        will destroy the MS-DOS stack and its ability to retry or ignore an
        error.

    ■  Before issuing a RETURN FROM INTERRUPT (IRET), the Interrupt 24H
        handler should place an action code in AL that will be interpreted
        by MS-DOS as follows:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Code     Meaning
        ──────────────────────────────────────────────────────────────────
        00H      Ignore error.
        01H      Retry operation.
        02H      Terminate program through Interrupt 23H.
        03H      Fail system call in progress (versions 3.1 and later).

    ■  If an Interrupt 24H routine returns to the user program rather than
        to MS-DOS, it must restore the user program's registers, removing
        all but the last three words from the stack, and issue an IRET.
        Control returns to the instruction immediately following the
        Interrupt 21H function call that resulted in an error. This leaves
        MS-DOS in an unstable state until a call is made to an Interrupt
        21H function higher than 0CH.

Example

    None



Interrupt 25H (37)
Absolute Disk Read
1.0 and later


    Interrupt 25H provides direct linkage to the MS-DOS BIOS module to
    read data from a logical disk sector into a specified memory location.

To Call

    AL      = drive number (0 = drive A, 1 = drive B, and so on)
    CX      = number of sectors to read
    DX      = starting relative (logical) sector number
    DS:BX   = segment:offset of disk transfer area (DTA)

Returns

    If operation is successful:

    Carry flag is clear.

    If operation is not successful:

    Carry flag is set.

    AX      = error code

Programmer's Notes

    ■  Interrupt 25H might destroy all registers except the segment
        registers.

    ■  When Interrupt 25H returns, the CPU flags originally pushed onto
        the stack by the INT 25H instruction are still on the stack. The
        stack must be cleared by a POPF or ADD SP,2 instruction to prevent
        uncontrolled stack growth and to make accessible any other values
        that were pushed onto the stack before the call to Interrupt 25H.

    ■  Logical sector numbers are zero based and are obtained by numbering
        each disk sector sequentially from track 0, head 0, sector 1 and
        continuing until the last sector on the disk is counted. The head
        number is incremented before the track number. Because of
        interleaving, logically adjacent sectors might not be physically
        adjacent for some types of disks.

    ■  The lower byte of the error code (AL) is the same error code that
        is returned in the lower byte of DI when an Interrupt 24H is
        issued. The upper byte (AH) contains one of the following codes:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Code     Meaning
        ──────────────────────────────────────────────────────────────────
        80H      Device failed to respond
        40H      Seek operation failure
        20H      Controller failure
        10H      Data error (bad CRC)
        08H      Direct memory access (DMA) failure
        04H      Requested sector not found
        03H      Write-protect fault
        02H      Bad address mark
        01H      Bad command

    ■  Warning: Interrupt 25H bypasses the MS-DOS file system. This
        function must be used with caution to avoid damaging the disk
        structure.

Example

        ;****************************************************************;
        ;                                                                ;
        ;      Interrupt 25H: Absolute Disk Read                         ;
        ;                                                                ;
        ;      Read logical sector 1 of drive A into the memory area     ;
        ;      named buff. (On most MS-DOS floppy disks, this sector     ;
        ;      contains the beginning of the file allocation table.)     ;
        ;                                                                ;
        ;****************************************************************;

        mov     al,0            ; Drive A.
        mov     cx,1            ; Number of sectors.
        mov     dx,1            ; Beginning sector number.
        mov     bx,seg buff     ; Address of buffer.
        mov     ds,bx
        mov     bx,offset buff
        int     25h             ; Request disk read.
        jc      error           ; Jump if read failed.
        add     sp, 2           ; Clear stack.
        .
        .
        .
error:                          ; Error routine goes here.
        .
        .
        .
buff    db      512 dup (?)



Interrupt 26H (38)
Absolute Disk Write
1.0 and later


    Interrupt 26H provides direct linkage to the MS-DOS BIOS module to
    write data from a specified memory buffer to a logical disk sector.

To Call

    AL      = drive number (0 = drive A, 1 = drive B, and so on)
    CX      = number of sectors to write
    DX      = starting relative (logical) sector number
    DS:BX   = segment:offset of disk transfer area (DTA)

Returns

    If operation is successful:

    Carry flag is clear.

    If operation is not successful:

    Carry flag is set.

    AX      = error code

Programmer's Notes

    ■  When Interrupt 26H returns, the CPU flags originally pushed onto
        the stack by the INT 26H instruction are still on the stack. The
        stack must be cleared by a POPF or ADD SP,2 instruction to prevent
        uncontrolled stack growth and to make accessible any other values
        that were pushed on the stack before the call to Interrupt 26H.

    ■  Logical sector numbers are zero based and are obtained by numbering
        each disk sector sequentially from track 0, head 0, sector 1 and
        continuing until the last sector on the disk is counted. The head
        number is incremented before the track number. Because of
        interleaving, logically adjacent sectors might not be physically
        adjacent for some types of disks.

    ■  The lower byte of the error code (AL) is the same error code that
        is returned in the lower byte of DI when an Interrupt 24H is
        issued. The upper byte (AH) contains one of the following codes:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
        Code     Meaning
        ──────────────────────────────────────────────────────────────────
        80H      Device failed to respond
        40H      Seek operation failure
        20H      Controller failure
        10H      Data error (bad CRC)
        08H      Direct memory access (DMA) failure
        04H      Requested sector not found
        03H      Write-protect fault
        02H      Bad address mark
        01H      Bad command

    ■  Warning: Interrupt 26H bypasses the MS-DOS file system. This
        function must be used with caution to avoid damaging the disk
        structure.

Example

        ;****************************************************************;
        ;                                                                ;
        ;       Interrupt 26H: Absolute Disk Write                       ;
        ;                                                                ;
        ;       Write the contents of the memory area named buff         ;
        ;       into logical sector 3 of drive C.                        ;
        ;                                                                ;
        ;       WARNING: Verbatim use of this code could damage          ;
        ;       the file structure of the fixed disk. It is meant        ;
        ;       only as a general guide. There is, unfortunately,        ;
        ;       no way to give a really safe example of this interrupt.  ;
        ;                                                                ;
        ;****************************************************************;

        mov     al,2            ; Drive C.
        mov     cx,1            ; Number of sectors.
        mov     dx,3            ; Beginning sector number.
        mov     bx,seg buff     ; Address of buffer.
        mov     ds,bx
        mov     bx,offset buff
        int     26h             ; Request disk write.
        jc      error           ; Jump if write failed.
        add     sp,2            ; Clear stack.
        .
        .
        .
error:                          ; Error routine goes here.
        .
        .
        .
buff    db      512 dup (?)     ; Data to be written to disk.



Interrupt 27H (39)
Terminate and Stay Resident
1.0 and later


    Interrupt 27H terminates execution of the currently executing program
    but reserves part or all of its memory so that it will not be overlaid
    by the next transient program to be loaded.

To Call

    DX   = offset of last byte plus 1 (relative to the program segment
            prefix, or PSP) of program to be protected
    CS   = segment address of PSP

Returns

    Nothing

Programmer's Notes

    ■  In response to an Interrupt 27H call, MS-DOS takes the following
        actions:

        -  Restores the termination vector (Interrupt 22H) from PSP:000AH.

        -  Restores the Control-C vector (Interrupt 23H) from PSP:000EH.

        -  With MS-DOS versions 2.0 and later, restores the critical error
        handler vector (Interrupt 24H) from PSP:0012H.

        -  Transfers to the termination handler address.

    ■  If the program is returning to COMMAND.COM rather than to another
        program, control transfers first to COMMAND.COM's resident portion,
        which reloads COMMAND.COM's transient portion (if necessary) and
        passes it control. If a batch file is in progress, the next line of
        the file is then fetched and interpreted; otherwise, a prompt is
        issued for the next user command.

    ■  This interrupt is typically used to allow user-written drivers or
        interrupt handlers to be loaded as ordinary .COM or .EXE programs
        and then remain resident. Subsequent entrance to the code is by
        means of a hardware or software interrupt.

    ■  The maximum amount of memory that can be reserved with this
        interrupt is 64 KB. Therefore, Interrupt 27H should be used only
        for applications that must run under MS-DOS versions 1.x.

        With versions 2.0 and later, the preferred method to terminate and
        stay resident is to use Interrupt 21H Function 31H, which allows
        the program to reserve more than 64 KB of memory and does not
        require CS to contain the PSP address.

    ■  Interrupt 27H should not be called by .EXE programs that are loaded
        into the high end of memory (that is, linked with the /HIGH
        switch), because this would reserve the memory that is ordinarily
        used by the transient portion of COMMAND.COM. If COMMAND.COM cannot
        be reloaded, the system will fail.

    ■  Because execution of Interrupt 27H results in the restoration of
        the terminate routine (Interrupt 22H), Control-C (Interrupt 23H),
        and critical error (Interrupt 24H) vectors, it cannot be used to
        permanently install a user-written critical error handler.

    ■  Interrupt 27H does not work correctly when DX contains values in
        the range FFF1H through FFFFH. In this case, MS-DOS discards the
        high bit of the contents of DX, resulting in 32 KB less resident
        memory than was actually requested by the program.

Example

        ;****************************************************************;
        ;                                                                ;
        ;       Interrupt 27H: Terminate and Stay Resident               ;
        ;                                                                ;
        ;       Exit and stay resident, reserving enough memory          ;
        ;       to protect the program's code and data.                  ;
        ;                                                                ;
        ;****************************************************************;

Start:   .
        .
        .
        mov     dx,offset pgm_end  ; DX = bytes to reserve.
        int     27h                ; Terminate, stay resident.
        .
        .
        .
pgm_end  equ     $
        end     start



Interrupt 2FH (47)
Multiplex Interrupt
2.0 and later


    Interrupt 2FH with AH = 01H submits a file to the print spooler,
    removes a file from the print spooler's queue of pending files, or
    obtains the status of the printer. Other values for AH are used by
    various MS-DOS extensions, such as APPEND.

To Call

    AH      = 01H    print spooler call
    AL      = 00H    get installed status
            = 01H    submit file to be printed
            = 02H    remove file from print queue
            = 03H    cancel all files in queue
            = 04H    hold print jobs for status read
            = 05H    end hold for status read

    If AL is 01H:

    DS:DX   = segment:offset of packet address

    If AL is 02H:

    DS:DX   = segment:offset of ASCIIZ file specification

Returns

    If operation is successful:

    Carry flag is clear.

    If AL was 00H on call:

    AL      = status:
            = 00H    not installed, OK to install
            = 01H    not installed, not OK to install
            = FFH    installed

    If AL was 04H on call:

    DX      = error count
    DS:SI   = segment:offset of print queue

    If operation is not successful:

    Carry flag is set.

    AX      = error code:
            = 01       function invalid
            = 02       file not found
            = 03       path not found
            = 04       too many open files
            = 05       access denied
            = 08       queue full
            = 09       spooler busy
            = 0C       name too long
            = 0F       drive invalid

Programmer's Notes

    ■  For Subfunction 01H, the packet consists of 5 bytes. The first byte
        contains the level (must be zero), the next 4 bytes contain the
        doubleword address (segment and offset) of an ASCIIZ file
        specification. (The filename cannot contain wildcard characters.)
        If the file exists, it is added to the end of the print queue.

    ■  For Subfunction 02H, wildcard characters (* and ?) are allowed in
        the file specification, making it possible to delete multiple files
        from the print queue with one call.

    ■  For Subfunction 04H, the address returned for the print queue
        points to a series of filename entries. Each entry in the queue is
        64 bytes and contains an ASCIIZ file specification. The first file
        specification in the queue is the one currently being printed. The
        last slot in the queue has a null (zero) in the first byte.

Example

    None

Return to The MS-DOS Encyclopedia: Contents