🚀 go-pugleaf

Archive-name: msdos-programmer-faq/part3
Last-modified: 15 November 1922


(continued from part 2)         (no warranty on the code or information)

If the posting date is more than six weeks in the past, see instructions
in part 4 of this list for how to get an updated copy.

            Copyright (C) 1992  Stan Brown, Oak Road Systems


section 4.  Disks and files
===========================

Q401. What drive was the PC booted from?

    Under DOS 4.0 or later, load 3305 hex into AX; do an INT 21.  DL is
    returned with an integer indicating the boot drive (1=A:, etc.).

Q402. How can I boot from drive b:?

    Download PD1:<MSDOS.DSKUTL>BOOT_B.ZIP (shareware) from Simtel.  The
    included documentation says it works by writing a new boot sector on
    a disk in your a: drive that redirects the boot to your b: drive.

Q403. Which real and virtual disk drives are valid?

    Use INT 21 function 29 (parse filename).  Point DS:SI at a null-
    terminated ASCII string that contains the drive letter and a colon,
    point ES:DI at a 37-byte dummy FCB buffer, set AX to 2900h, and do
    an INT 21.  On return, AL is FF if the drive is invalid, something
    else if the drive is valid.  RAM disks and SUBSTed drives are
    considered valid.

    Unfortunately, the b: drive is considered valid even on a single-
    diskette system.  You can check that special case by interrogating
    the BIOS equipment byte at 0040:0010.  Bits 7-6 contain the one less
    than the number of diskette drives, so if those bits are zero you
    know that b: is an invalid drive even though function 29 says it's
    valid.

    Following is some code originally posted by Doug Dougherty, with my
    fix for the b: special case, tested only in Borland C++ 2.0 (in
    the small model):

        #include <dos.h>
        void drvlist(void)  {
            char *s = "A:", fcb_buff[37];
            int valid;
            for (   ;  *s<='Z';  (*s)++) {
                _SI = (unsigned) s;
                _DI = (unsigned) fcb_buff;
                _ES = _DS;
                _AX = 0x2900;
                geninterrupt(0x21);
                valid = _AL != 0xFF;
                if (*s == 'B'  &&  valid) {
                    char far *equipbyte = (char far *)0x00400010UL;
                    valid = (*equipbyte & (3 << 6)) != 0;
                }
                printf("Drive '%s' is %sa valid drive.\n",
                        s, valid ? "" : "not ");
            }
        }

Q404. How can I make my single floppy drive both a: and b:?

    Under any DOS since DOS 2.0, you can put the command

        assign b=a

    into your AUTOEXEC.BAT file.  Then, when you type "DIR B:" you'll no
    longer get the annoying prompt to insert diskette B (and the even
    more annoying prompt to insert A the next time you type "DIR A:").

    You may be wondering why anybody would want to do this.  Suppose you
    use two different machines, maybe one at home and one at work.  One
    of them has only a 3.5" diskette drive; the other machine has two
    drives, and b: is the 3.5" one.  You're bound to type "dir b:" on
    the first one, and get the nuisance message

        Insert diskette for drive B: and press any key when ready.

    But if you assign drive b: to point to a:, you avoid this problem.

    Caution:  there are a few commands, such as DISKCOPY, that will not
    work right on ASSIGNed or SUBSTed drives.  See the DOS manual for
    the full list.  Before typing one of those commands, be sure to turn
    off the mapping by typing "assign" without arguments.

    The DOS 5.0 manual says that ASSIGN is obsolete, and recommends the
    equivalent form of SUBST: "subst b: a:\".  Unfortunately, if this
    command is executed when a: doesn't hold a diskette, the command
    fails.  ASSIGN doesn't have this problem, so I must advise you to
    disregard that particular bit of advice in the DOS manual.

Q405. Why won't my C program open a file with a path?

    You've probably got something like the following code:

        char *filename = "c:\foo\bar\mumble.dat";
        . . .  fopen(filename, "r");

    The problem is that \f is a form feed, \b is a backspace, and \m is
    m.  Whenever you want a backslash in a string constant in C, you
    must use two backslashes:

        char *filename = "c:\\foo\\bar\\mumble.dat";

    This is a feature of every C compiler, because Dennis Ritchie
    designed C this way.  It's a problem only on MS-DOS systems, because
    only DOS (and Atari ST/TT running TOS, I'm told) uses the backslash
    in directory paths.  But even in DOS this backslash convention
    applies _only_ to string constants in your source code.  For file
    and keyboard input at run time, \ is just a normal character, so
    users of your program would type in file specs at run time the same
    way as in DOS commands, with single backslashes.

    Another possibility is to code all paths in source programs with /
    rather than \ characters:

        char *filename = "c:/foo/bar/mumble.dat";

    Ralf Brown writes that "All versions of the DOS kernel accept either
    forward or backslashes as directory separators.  I tend to use this
    form more frequently than backslashes since it is easier to type and
    read."  This applies to DOS function calls (and therefore to calls
    to the file library of every programming language), but not to DOS
    commands.

Q406. How can I redirect printer output to a file?

    My personal favorite utility for this purpose is PRN2FILE from {PC
    Magazine}, available from Simtel as PD1:<MSDOS.PRINTER>PRN2FILE.ARC,
    or from garbo as prn2file.zip in /pc/printer.  ({PC Magazine} has
    given copies away as part of its utilities disks, so you may already
    have a copy.)

    Check the PD1:<MSDOS.PRINTER> directory at Simtel, or /pc/printer
    at garbo, for lots of other printer-redirection utilities.

Q407. What's the format of an .EXE header?

    See pages 349-350 of {PC Magazine}'s June 30, 1992 issue (xi:12) for
    the old and new formats.  For a more detailed layout, look under INT
    21 function 4B in Ralf Brown's interrupt list.

Q408. What's the format of an .OBJ file?

    I have seen a reference to Intel's document number #121748-001,
    {8086 Relocatable Object Module Formats}, which covers the Intel
    .OBJ format.  However, both Microsoft and Borland formats differ
    from the base Intel format.  If you have specific references, either
    to fpt-able documents or to published works (author, title, order
    number or ISBN), please email them to brown@ncoast.org for inclusion
    in the next edition of this list.

Q409. How can my program open more files than DOS's limit of 20?

    (This is a summary of an article Ralf Brown posted on 8 August 1992.)

    There are separate limits on files and file handles.  For example,
    DOS opens three files but five file handles:  CON (stdin, stdout,
    and stderr), AUX (stdaux), and PRN (stdprn).

    The limit in FILES= in CONFIG.SYS is a system-wide limit on files
    opened by all programs (including the three that DOS opens and any
    opened by TSRs); each process has a limit of 20 handles (including
    the five that DOS opens).  Example:  CONFIG.SYS has FILES=40.  Then
    program #1 will be able to open 15 file handles.  Assuming that the
    program actually does open 15 handles pointing to 15 different
    files, other programs could still open a total of 22 files (40-3-15
    = 22), though no one program could open more than 15 file handles.

    If you're running DOS 3.3 or later, you can increase the per-process
    limit of 20 file handles by a call to INT 21 function 67, Set Handle
    Count.  Your program is still limited by the system-wide limit on
    open files, so you may also need to increase the FILES= value in
    your CONFIG.SYS file (and reboot).  The run-time library that you're
    using may have a fixed-size table of file handles, so you may also
    need to get source code for the module that contains the table,
    increase the table size, and recompile it.

Q410. How can I read, create, change, or delete the volume label?

    You can't do it using the more modern DOS functions (3C, 41, 43),
    but the older FCB-oriented directory functions will do the job.
    Specifically, you need to allocate a 64-byte buffer and a 41-byte
    extended FCB (file control block).  Call INT 21 AH=1A to find out
    whether there is a volume label.  If there is, AL will return 0 and
    you can change the label using DOS function 17 or delete it using
    DOS function 13.  If there is no volume label, function 1A will
    return FF and you can create a label by using function 16.

    The following MSC 7.0 code worked for me, where the parameter is 0
    for the current disk, 1 for a:, 2 for b:, etc.  It doesn't matter
    what your current directory is; these functions always search the
    root directory for volume labels.  This code should work for DOS
    2.0+, though I tested it only under DOS 5.0.  (I don't know what
    happens with networked drives.)

    Important points to notice are that ? wildcards are allowed but *
    are not; the volume label must be space filled not null-terminated.

    void vollabel(unsigned char drivenum) {
        static unsigned char extfcb[41], dta[64], status, *newlabel;
        int chars_got = 0;
        #define DOS(buff,func) __asm { __asm mov dx,offset buff \
            __asm mov ax,seg buff  __asm push ds  __asm mov ds,ax \
            __asm mov ah,func  __asm int 21h  __asm pop ds \
            __asm mov status,al }
        #define getlabel(buff,prompt) newlabel = buff;  \
            memset(newlabel,' ',11);  printf(prompt);   \
            scanf("%11[^\n]%n", newlabel, &chars_got);  \
            if (chars_got < 11) newlabel[chars_got] = ' ';

        // Set up the 64-byte transfer area used by function 1A.
        DOS(dta, 1Ah)
        // Set up an extended FCB and search for the volume label.
        memset(extfcb, 0, sizeof extfcb);
        extfcb[0] = 0xFF;             // denotes extended FCB
        extfcb[6] = 8;                // volume-label attribute bit
        extfcb[7] = drivenum;         // 1=A, 2=B, etc.; 0=current drive
        memset(&extfcb[8], '?', 11);  // wildcard *.*
        DOS(extfcb,11h)
        if (status == 0) {            // DTA contains volume label's FCB
            printf("volume label is %11.11s\n", &dta[8]);
            getlabel(&dta[0x18], "new label (\"delete\" to delete): ");
            if (chars_got == 0)
                printf("label not changed\n");
            else if (strncmp(newlabel,"delete     ",11) == 0) {
                DOS(dta,13h)
                printf(status ? "label failed\n" : "label deleted\n");
            }
            else {                    // user wants to change label
                DOS(dta,17h)
                printf(status ? "label failed\n" : "label changed\n");
            }
        }
        else {                        // no volume label was found
            printf("disk has no volume label.\n");
            getlabel(&extfcb[8], "new label (<Enter> for none): ");
            if (chars_got > 0) {
                DOS(extfcb,16h)
                printf(status ? "label failed\n" : "label created\n");
            }
        }
    }   // end function vollabel

Q411. How can I get the disk serial number?

    Use INT 21.  AX=6900 gets the serial number; AX=6901 sets it.  See
    Ralf Brown's interrupt list, or page 496 of the July 1992 {PC
    Magazine}, for details.


section 5. Serial ports (COM ports)
===================================

Q501. How do I set my machine up to use COM3 and COM4?

    Unless your machine is fairly old, it's probably already set up.
    After installing the board that contains the extra COM port(s),
    check the I/O addresses in word 0040:0004 or 0040:0006.  (In DEBUG,
    type "D 40:4 L4" and remember that every word is displayed low
    byte first, so if you see "03 56" the word is 5603.)  If those
    addresses are nonzero, your PC is ready to use the ports and you
    don't need the rest of this answer.

    If the I/O address words in the 0040 segment are zero after you've
    installed the I/O board, you need some code to store these values
    into the BIOS data segment:

        0040:0004  word  I/O address of COM3
        0040:0006  word  I/O address of COM4
        0040:0011  byte (bits 3-1): number of serial ports installed

    The documentation with your I/O board should tell you the port
    addresses.  When you know the proper port addresses, you can add
    code to your program to store them and the number of serial ports
    into the BIOS data area before you open communications.  Or you can
    use DEBUG to create a little program to include in your AUTOEXEC.BAT
    file, using this script:

            n SET_ADDR.COM      <--- or a different name ending in .COM
            a 100
            mov  AX,0040
            mov  DS,AX
            mov  wo [0004],aaaa <--- replace aaaa with COM3 address or 0
            mov  wo [0006],ffff <--- replace ffff with COM4 address or 0
            and  by [0011],f1
            or   by [0011],8    <--- use number of serial ports times 2
            mov  AH,0
            int  21
                                <--- this line must be blank
            rCX
            1f
            rBX
            0
            w
            q

Q502. How do I find the I/O address of a COM port?

    Look in the four words beginning at 0040:0000 for COM1 through COM4.
    (The DEBUG command "D 40:0 L8" will do this.  Remember that words
    are stored and displayed low byte first, so a word value of 03F8
    will be displayed as F8 03.)  If the value is zero, that COM port is
    not installed (or you've got an old BIOS; see the preceding Q).  If
    the value is nonzero, it is the I/O address of the transmit/receive
    register for the COM port.  Each COM port occupies eight consecutive
    I/O addresses (though only seven are used by many chips).

    Here's some C code to find the I/O address:

        unsigned ptSel(unsigned comport) {
            unsigned io_addr;
            if (comport >= 1  &&  comport <= 4) {
                unsigned far *com_addr = (unsigned far *)0x00400000UL;
                io_addr = com_addr[comport-1];
            }
            else
                io_addr = 0;
            return io_addr;
        }

Q503. But aren't the COM ports always at I/O addresses 3F8, 2F8, 3E8,
      and 2E8?

    The first two are usually right (though not always); the last two
    are different on many machines.

Q504. How do I configure a COM port and use it to transmit data?

    After hearing several recommendations, I looked at Joe Campbell's {C
    Programmer's Guide to Serial Communications}, ISBN 0-672-22584-0,
    and agree that it is excellent.  He gives complete details on how
    serial ports work, along with complete programs for doing polled or
    interrupt-driver I/O.  The book is quite thick, and none of it looks
    like filler.

    If Campbell's book is overkill for you, you'll find a good short
    description of serial I/O in {DOS 5: A Developer's Guide}, ISBN
    1-55851-177-6, by Al Williams.

    You may also want to look at an extended example in Borland's
    TechFax TI445, part of PD1:<MSDOS.TURBO-C> at Simtel.  Though
    written by Borland, much of it is applicable to other forms of C,
    and it should give you ideas for other programming languages.

section 6. Other hardware questions and problems
================================================

Q601. Which 80x86 CPU is running my program?

    According to an article posted by Michael Davidson, Intel's approved
    code for distinguishing among 8086, 80286, 80386, and 80486 and for
    detecting the presence of an 80287 or 80387 is published in the
    Intel's 486SX processor manual (order number 240950-001).  You can
    download David Kirschbaum's improved version of this from Simtel as
    PD1:<MSDOS.SYSUTL>CPUID593.ZIP.

    According to an article posted by its author, WCPU041.ZIP knows the
    differences between DX and SX varieties of 386 and 486 chips, and
    can also detect a math coprocessor.  It's in PD1:<MSDOS.SYSUTL> at
    Simtel.

Q602. How can a C program send control codes to my printer?

    If you just fprintf(stdprn, ...), C will translate some of your
    control codes.  The way around this is to reopen the printer in
    binary mode:

        prn = fopen("PRN", "wb");

    You must use a different file handle because stdprn isn't an lvalue.
    By the way, PRN or LPT1 must not be followed by a colon in DOS 5.0.

    There's one special case, Ctrl-Z (ASCII 26), the DOS end-of-file
    character.  If you try to send an ASCII 26 to your printer, DOS
    simply ignores it.  To get around this, you need to reset the
    printer from "cooked" to "raw" mode.  Microsoft C users must use int
    21 function 44, "get/set device information".  Turbo C and Borland
    C++ users can use ioctl to accomplish the same thing:

        ioctl(fileno(prn), 1, ioctl(fileno(prn),0) & 0xFF | 0x20, 0);

    An alternative approach is simply to write the printer output into a
    disk file, then copy the file to the printer with the /B switch.

    A third approach is to bypass DOS functions entirely and use the
    BIOS printer functions at INT 17.  If you also fprintf(stdprn,...)
    in the same program, you'll need to use fflush( ) to synchronize
    fprintf( )'s buffered output with the BIOS's unbuffered.

    By the way, if you've opened the printer in binary mode from a C
    program, remember that outgoing \n won't be translated to carriage
    return/line feed.  Depending on your printer, you may need to send
    explicit \n\r sequences.

Q603. How can I redirect printer output to a file?

    Please see section 4, "Disks and files", for the answer.

Q604. Which video adapter is installed?

    The technique below should work if your BIOS is not too old.  It
    uses three functions from INT 10, the BIOS video interrupt.  (If
    you're using a Borland language, you may not have to do this the
    hard way.  Look for a function called DetectGraph or something
    similar.)

    Set AH=12h, AL=0, BL=32h; INT 10h.  If AL is 12h, you have a VGA.
    If not, set AH=12h, BL=10h; INT 10h.  If BL is 0,1,2,3, you have an
    EGA with 64,128,192,256K memory.  If not, set AH=0Fh; INT 10h.  If
    AL is 7, you have an MDA (original monochrome adapter) or Hercules;
    if not, you have a CGA.

    I've tested this for my VGA and got the right answer; but I can't
    test it for the other equipment types.  Please let me know by email
    at brown@ncoast.org if your results vary.

Q605. How do I switch to 43- or 50-line mode?

    Download PD1:<MSDOS.SCREEN>VIDMODE.ZIP from Simtel or one of the
    mirror sites.  It contains .COM utilities and .ASM source code.

Q606. How can I find the Microsoft mouse position and button status?

    Use INT 33 function 3, described in Ralf Brown's interrupt list.

    The Windows manual says that the Logitech mouse is compatible with
    the Microsoft one, so I assume the interrupt will work the same.

    Also, see the directory PD1:<MSDOS.MOUSE> at Simtel.

Q607. How can I access a specific address in the PC's memory?

    First check the library that came with your compiler.  Many vendors
    have some variant of peek and poke functions; in Turbo Pascal use
    the pseudo-arrays Mem, MemW, and MemL.  As an alternative, you can
    construct a far pointer:  use Ptr in Turbo Pascal, MK_FP in the
    Turbo C family, and FP_OFF and FP_SEG in Microsoft C.

    Caution:  Turbo C and Turbo C++ also have FP_OFF and FP_SEG macros,
    but they can't be used to construct a pointer.  In Borland C++ those
    macros work the same as in Microsoft C, but MK_FP is easier to use.

    By the way, it's not useful to talk about "portable" ways to do
    this.  Any operation that is tied to a specific memory address is
    not likely to work on another kind of machine.

Q608. How can I read or write my PC's CMOS memory?

    There are a great many public-domain utilities that do this.  These
    were available for download from Simtel as of 31 March 1992:

    PD1:<MSDOS.AT>
    CMOS14.ZIP     5965  920817  Saves/restores CMOS to/from file
    CMOSER11.ZIP  28323  910721  386/286 enhanced CMOS setup program
    CMOSRAM.ZIP   76096  920214  Save AT/386/486 CMOS data to file and restore
    ROM2.ARC      20497  900131  Save AT and 386 CMOS data to file and restore
    SETUP21.ARC   24888  880613  Setup program which modifies CMOS RAM
    VIEWCMOS.ARC  15374  900225  Display contents of AT CMOS RAM, w/C source

    At garbo, /pc/ts/tsutle17.zip contains a CMOS program to check and
    display CMOS memory, but not to write to it.

    I have heard good reports of CMOS299.ZIP, available in the pc.dir
    directory of cantva.canterbury.ac.nz [132.181.30.3].

    Of the above, my only experience is with CMOSRAM, which seems to
    work fine.  It contains an excellent (and witty) .DOC file that
    explains the hardware involved and gives specific recommendations
    for preventing disaster or recovering from it.  It's $5 shareware.

    Robert Jourdain's {Programmer's Problem Solver for the IBM PC, XT,
    and AT} has code for accessing the CMOS RAM, according to an article
    posted in this newsgroup.

Q609. How can I access memory beyond 640K?

    I'm outside my expertise on this one, but in November 1992 Jamshid
    Afshar (jamshid@emx.utexas.edu) kindly supplied the following:

    ...........................(begin quote)............................
    1. Use XMS memory (don't bother with EMS).  There are some libraries
    available at Simtel to access XMS.  The disadvantage is that you
    don't allocate the memory as you would with malloc() (or `new' in
    C++).  I believe it also requires that you lock this memory when in
    use.  This means your code is not easily ported to other (and
    future) operating systems and that your code is more convoluted than
    it would be under a "real" os.  The advantage is that the library
    works with compilers since Turbo C 2.0 (I think) and that your
    program will run on even 286s.

    2. Program under MS Windows.  MS Windows functions as a DOS extender
    (see #3).  Borland/Turbo C++ 3.0 includes EasyWin [and Microsoft
    C/C++ 7.0 has QuickWin --ed.] which is a library that automatically
    lets you compile your current code using C/C++ standard input or
    <conio.h>'s gotoxy() into a MS Windows program so your code can
    immediately allocate many MBs of memory (Windows enhanced mode even
    does virtual memory).  The disadvantage of MS Windows is that any
    one object (e.g., a single malloc( )) is still restricted to 64K
    (unless you want to mess with huge pointers in Windows).

    3. Use a DOS extender.  This is definitely the best solution from
    the programmer's standpoint.  You just allocate as much memory as
    you need using malloc( ) or `new' and you don't have to worry about
    any 64K limits.  It doesn't require source code changes and unlike
    option #1 your code is portable and not obsolete in a few months.
    Your options for this solution are:

    - Buy PharLap's DOS extender (286 or 386 version) that works with
      BC++ 3.0+ (just requires a relink).  Note, the BC++ 3.1 upgrade
      came with PharLap "lite".

    - Get the GNU (free,copylefted) gcc 2.1 compiler/extender that was
      ported to MS-DOS and runs on 386 machines (supports C and C++).
      FTP to barnacle.erc.clarkson.edu and get pub/msdos/djgpp/readme.

    - Wait for Borland's DOS extender package (in BC++ 4.0) that is
      supposed to be released at the end of this year.  I believe MS is
      also doing the same.  Zortech 3.0 comes with a DOS extender, but I
      wouldn't recommend the product.

    4. This option doesn't really count since it's not a solution in
    DOS, but you could switch to a full 32-bit operating system like
    OS/2 2.0 or UNIX (or Win32/NT when it comes out).  Borland is
    putting its OS/2 compiler into beta now.  OS/2 is doing well (and it
    runs DOS or Windows programs).  BC++ for OS/2 should also be a
    success and there should be a good upgrade path from current Borland
    compilers.
    ............................(end quote).............................


section 7. Other software questions and problems
================================================

Q701. How can a program reboot my PC?

    You can generate a "cold" boot or a "warm" boot.  A cold boot is
    the same as turning the power off and on; a warm boot is the same as
    Ctrl-Alt-Del and skips the power-on self test.

    For a warm boot, store the hex value 1234 in the word at 0040:0072.
    For a cold boot, store 0 in that word.  Then, if you want to live
    dangerously, jump to address FFFF:0000.  Here's C code to do it:

        /* WARNING:  data loss possible */
        void bootme(int want_warm)  /* arg 0 = cold boot, 1 = warm */ {
            void (far* boot)(void) = (void (far*)(void))0xFFFF0000UL;
            unsigned far* type = (unsigned far*)0x00400072UL;
            *type = (want_warm ? 0x1234 : 0);
            (*boot)( );
        }

    What's wrong with that method?  It will boot right away, without
    closing files, flushing disk caches, etc.  If you boot without
    flushing a write-behind disk cache (if one is running), you could
    lose data or even trash your hard drive.

    There are two methods of signaling the cache to flush its buffers:
    (1) simulate a keyboard Ctrl-Alt-Del in the keystroke translation
    function of the BIOS (INT 15 function 4F), and (2) issue a disk
    reset (DOS function 0D).  Most disk-cache programs hook one or both
    of those interrupts, so if you use both methods you'll probably be
    safe.

    When user code simulates a Ctrl-Alt-Del, one or more of the programs
    that have hooked INT 15 function 4F can ask that the key be ignored by
    clearing the carry flag.  For example, HyperDisk does this when it
    has started but not finished a cache flush.  So if the carry flag
    comes back cleared, the boot code has to wait a couple of cluck
    ticks and then try again.  (None of this matters on older machines
    whose BIOS can't support 101- or 102-key keyboards; see "What is the
    SysRq key for?" in section 3, "Keyboard".)

    Here's C code that tries to signal the disk cache (if any) to flush:

        #include <dos.h>
        void bootme(int want_warm)  /* arg 0 = cold boot, 1 = warm */ {
            union REGS reg;
            void    (far* boot)(void) = (void (far*)(void))0xFFFF0000UL;
            unsigned far* boottype    =     (unsigned far*)0x00400072UL;
            char     far* shiftstate  =         (char far*)0x00400017UL;
            unsigned      ticks;
            int           time_to_waste;
            /* Simulate reception of Ctrl-Alt-Del: */
            for (;;) {
                *shiftstate |= 0x0C;    /* turn on Ctrl & Alt */
                reg.x.ax = 0x4F53;      /* 0x53 = Del's scan code */
                reg.x.cflag = 1;        /* sentinel for ignoring key */
                int86(0x15, &reg, &reg);
                /* If carry flag is still set, we've finished. */
                if (reg.x.cflag)
                    break;
                /* Else waste some time before trying again: */
                reg.h.ah = 0;
                int86(0x1A, &reg, &reg);/* system time into CX:DX */
                ticks = reg.x.dx;
                for (time_to_waste = 3;  time_to_waste > 0;  ) {
                    reg.h.ah = 0;
                    int86(0x1A, &reg, &reg);
                    if (ticks != reg.x.dx)
                        ticks = reg.x.dx , --time_to_waste;
                }
            }
            /* Issue a DOS disk reset request: */
            reg.h.ah = 0x0D;
            int86(0x21, &reg, &reg);
            /* Set boot type and boot: */
            *boottype = (want_warm ? 0x1234 : 0);
            (*boot)( );
        }

Q702. How can I time events with finer resolution than the system
      clock's 55 ms (about 18 ticks a second)?

    The following files, among others, can be downloaded from Simtel:

    PD1:<MSDOS.AT>
    ATIM.ARC       5946  881126  Precision program timing for AT

    PD1:<MSDOS.C>
    MILLISEC.ZIP  37734  911205  MSC/asm src for millisecond res timing
    MSCHRT3.ZIP   53708  910605  High-res timer toolbox for MSC 5.1
    MSEC_12.ZIP    8484  920320  High-def millisec timer v1.2 (C,ASM)
    ZTIMER11.ZIP  77625  920428  Microsecond timer for C, C++, ASM

    PD1:<MSDOS.TURBO-C>
    TCHRT3.ZIP    53436  910606  High-res timer toolbox for Turbo C 2.0
    TCTIMER.ARC   20087  891030  High-res timing of events for Turbo C

    PD1:<MSDOS.TURBOPAS>
    BONUS507.ARC 150435  900205  [Turbo Pascal source: high-res timing]

    Pascal users can download source code in /pc/turbopas/bonus507.zip
    at garbo.

Q703. How can I find the error level of the previous program?

    First, which previous program are you talking about?  If your
    current program ran another one, when the child program ends its
    error level is available to the program that spawned it.  Most
    high-level languages provide a way to do this; for instance, in
    Turbo Pascal it's Lo(DosExitCode) and the high byte gives the way in
    which the child terminated.  In Microsoft C, the exit code of a
    synchronous child process is the return value of the spawn-type
    function that creates the process.

    If your language doesn't have a function to return the error code
    of a child process, you can use INT 21 function 4D (get return
    code).  By the way, this will tell you the child's exit code and the
    manner of its ending (normal, Ctrl-C, critical error, or TSR).

    It's much trickier if the current program wants to get the error
    level of the program that ran and finished before this one started.
    G.A.Theall has published source and compiled code to do this; you
    can download it from Simtel as PD1:<MSDOS.BATUTL>ERRLVL12.ZIP.  (The
    code uses undocumented features in DOS 3.3 through 5.0.  Theall says
    in the .DOC file that the values returned under 4DOS or other
    replacements won't be right.)

Q704. How can a program set DOS environment variables?

    Program functions that read or write "the environment" typically
    access only the program's copy of the environment.  What this Q
    really wants to do is to modify the active environment, the one that
    is affected by SET commands in batch files or at the DOS prompt.
    You need to do some programming to find the active environment, and
    that programming varies for different versions of DOS.

    A fairly well-written article in {PC Magazine} volume 8 number 20
    (1989 Nov 28), pages 309-314, explains how to find the active
    environment, and includes Pascal source code.  The article hints at
    how to change the environment, and suggests creating paths longer
    than 128 characters as one application.

    In searching Simtel for source code, I found many possibilities.  I
    liked PD1:<MSDOS.SYSUTL>RBSETNV1.ZIP of the ones I looked at (not
    all of them).  It includes some utilities to manipulate the environ-
    ment, with source code in C.

    You can also use a call to INT 2E, Pass Command to Interpreter for
    Execution; see Ralf Brown's interrupt list for details and cautions.

Q705. How can I change the switch character to - from /?

    Under DOS 5.0, you can't -- not completely, anyway.  INT 21 function
    3700, get switch character, always returns a '/' (hex 2F) -- and the
    DOS commands don't even call that function, but hard code '/' as the
    switch character.

    Some history:  DOS used to let you change the switch character by
    using SWITCHAR= in CONFIG.SYS or by calling DOS function 3701.  DOS
    commands and other programs called DOS function 3700 to find out the
    switch character.  If you changed the switch character to '-' (the
    usual choice), you could then type "dir c:/c700 -p" rather than "dir
    c:\c700 /p".  Under DOS 4.0, the DOS commands ignored the switch
    character but functions 3700 and 3701 still worked and could be used
    by other programs.  Under DOS 5.0, even those functions no longer
    work, though all DOS functions still accept '/' or '\' in file
    specs.

    You can reactivate the functions to get and set switchar by using
    programs like SLASH.ZIP or the sample TSR called SWITCHAR in
    AMISL091.ZIP (see "How can I write a TSR?", below.)  DOS commands
    will still use the slash, but non-DOS programs that call DOS func-
    tion 3700 will use your desired switch character.  (DOS replacements
    like 4DOS may honor the switch character for internal commands.)

    Some readers may wonder why this is even an issue.  Making '-' the
    switch character frees up the front slash to separate names in the
    path part of a file spec.  This is easier for the ten-fingered to
    type, and it's one less difference to remember for commuters between
    DOS and Unix.  The switch character is the only issue, since all the
    INT 21 functions accept '/' or '\' to separate directory names.

Q706. Why does my interrupt function behave strangely?

    Interrupt service routines can be tricky, because you have to do
    some things differently from "normal" programs.  If you make a
    mistake, debugging is a pain because the symptoms may not point at
    what's wrong.  Your machine may lock up or behave erratically, or
    just about anything else can happen.  Here are some things to look
    for.  (See the next Q for general help before you have a problem.)

    First, did you fail to set up the registers at the start of your
    routine?  When your routine begins executing, you can count on
    having CS point to your code segment and SS:SP point to some valid
    stack (of unknown length), and that's it.  In particular, an
    interrupt service routine must set DS to DGROUP before accessing any
    data in its data segments.  (If you're writing in a high-level
    language, the compiler may generate this code for you automatically;
    check your compiler manual.  For instance, in Borland and Microsoft
    C, give your function the "interrupt" attribute.)

    Did you remember to turn off stack checking when compiling your
    interrupt server and any functions it calls?  The stack during the
    interrupt is not where the stack-checking code expects it to be.
    (Caution:  Some third-party libraries have stack checking compiled
    in, so you can't call them from your interrupt service routine.)

    Next, are you calling any DOS functions (INT 21, 25, or 26) in your
    routine?  DOS is not re-entrant.  This means that if your interrupt
    happens to be triggered while the CPU is executing a DOS function,
    calling another DOS function will wreak havoc.  (Some DOS functions
    are fully re-entrant, as noted in Ralf Brown's interrupt list.
    Also, your program can test, in a way too complicated to present
    here, when it's safe to call non-re-entrant DOS functions.  See INT
    28 and functions 34, 5D06, 5D0B of INT 21; and consult {Undocumented
    DOS} by Andrew Schulman.  Your program must read both the "InDOS
    flag" and the "critical error flag".)

    Is a function in your language library causing trouble?  Does it
    depend on some initializations done at program startup that is no
    longer available when the interrupt executes?  Does it call DOS (see
    preceding paragraph)?  For example, in both Borland and Microsoft C
    the memory-allocation functions (malloc, etc..) and standard I/O
    functions (scanf, printf) call DOS functions and also depend on
    setups that they can't get at from inside an interrupt.  Many other
    library functions have the same problem, so you can't use them
    inside an interrupt function without special precautions.

    Is your routine simply taking too long?  This can be a problem if
    you're hooking on to the timer interrupt, INT 1C or INT 8.  Since
    that interrupt expects to be called 18.2 times a second, your
    routine -- plus any others hooked to the same interrupts -- must
    execute in less than 55 ms.  If they use even a substantial fraction
    of that time, you'll see significant slowdowns of your foreground
    program.  For a good writeup, download INTSHARE (from ni.funet.fi
    in pub/msdos/simtel20/info or from Simtel in PD1:<MSDOS.INFO>).

    Did you forget to restore all registers at the end of your routine?

    Did you chain improperly to the original interrupt?  You need to
    restore the stack to the way it was upon entry to your routine, then
    do a far jump (not call) to the original interrupt service routine.
    (The process is a little different in high-level languages.)

Q707. How can I write a TSR (terminate-stay-resident) utility?

    Several books can help you with this.

    - Ray Duncan's {Advanced MS-DOS}, ISBN 1-55615-157-8, gives a brief
      checklist intended for experienced programmers.  The ISBN is for
      the second edition, through DOS 4; but check to see whether the
      DOS 5 version is available yet.

    - {DOS 5:  A Developer's Guide} by Al Williams, ISBN 1-55851-177-6,
      goes into a little more detail, 90 pages worth!

    - Pascal programmers might look at {The Ultimate DOS Programmer's
      Manual} by John Mueller and Wallace Wang, ISBN 0-8306-3534-3, for
      an extended example in mixed Pascal and assembler.

    - For a pure assembler treatment, check Steven Holzner's {Advanced
      Assembly Language}, ISBN 0-13-663014-6.  He has a book with the
      same title out from Brady Press, but it's about half as long as
      this one.

    - For C programmers, there's a chapter in Herbert Schildt's {The Art
      of C:  Elegant Programming Solutions}.  I haven't seen the book,
      but a posted article recommended it.

    At Simtel, check PD1:<MSDOS.ASMUTL>AMISL091.ZIP, which contains Ralf
    Brown's assembly-language implementation of the Alternate Multiplex
    Interrupt Specification, with utilities in C.  The spec itself is
    PD1:<MSDOS.INFO>ALTMPX35.ZIP.  Both are also available at CS.CMU.EDU
    [128.2.222.173] in /afs/cs/user/ralf/pub (change directory with a
    single command and use lower-case filenames).

    You might want to download PD1:<MSDOS.ASMUTL>TEMPLATE.ZIP from
    Simtel.  It's Douglas Boling's MASM template for a TSR.

    Finally, there are commercial products, of which TesSeRact (for
    C-language TSRs) is one of the best known.

Q708. How can I write a device driver?

    Many books answer this in detail.  Among them are {Advanced MS-DOS}
    and {DOS 5: A Developer's Guide}, cited in the preceding Q.
    Michael Tischer's {PC System Programming}, ISBN 1-55755-036-0, has
    an extensive treatment, as does Dettman and Kyle's {DOS Programmer's
    Reference: 2d Edition}, ISBN 0-88022-458-4.  For a really in-depth
    treatment, look for a specialized book like Robert Lai's {Writing
    MS-DOS Device Drivers}, ISBN 0-201-13185-4.

Q709. What can I use to manage versions of software?

    In PD1:<MSDOS.PGMUTL> at Simtel you'll find RCS55.ZIP.  I haven't
    used it myself, but I understand this is a port of the Unix RCS
    utility, but is limited to one-character extensions on filenames (no
    .CPP).  A correspondent wrote that he has an RCS port to DOS that is
    not limited to one-character extensions, but he doesn't remember
    where he got it.  Anyone have a verified archive site?

Q710. What's this "null pointer assignment" after my C program executes?

    Somewhere in your program, you assigned a value _through_ a pointer
    without first assigning a value _to_ the pointer.  (This might have
    been something like a strcpy or memcpy with a pointer as its first
    argument, not necessarily an actual assignment statement.)  Your
    program may look like it ran correctly, but if you get this message
    you can be certain that there's a bug somewhere.

    Microsoft and Borland C, as part of their exit code (after a return
    from your main function), check whether the location 0000 in your
    data segment contains a different value from what you started with;
    if so, they infer that you must have used an uninitialized pointer.

    To track down the problem, you can put exit( ) statements at various
    spots in the program and narrow down where the uninitialized pointer
    is being used by seeing which added exit( ) makes the null-pointer
    message disappear.  Or, in the debugger, set a watch at location
    0000 in your data segment, assuming you're in small or medium model.
    (If data pointers are 32 bits, as in the compact and large models, a
    null pointer will overwrite the interrupt vectors at 0000:0000 and
    probably lock up your machine.)

    Under MSC/C++ 7.0, you can declare the undocumented library function

        extern _cdecl _nullcheck(void);

    and then sprinkle calls to _nullcheck( ) through your program at
    regular intervals.

    Borland's TechFax document #TI726 discusses the null pointer
    assignment from a Borland point of view.  Download file BCHELP10.ZIP
    from PD1:<MSDOS.TURBO-C> at Simtel.

(continued in part 4)
-- 
Stan Brown, Oak Road Systems                      brown@Ncoast.ORG
Cleveland, Ohio, USA