Liren Large Software Subsidy 10

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 10 / 10.iso / l / l352 / 1.img / DOC / LITE286.DOC < prev next >

Wrap

Text File | 1992-06-04 | 83.5 KB | 2,155 lines

Borland C++ User's Guide to 286|DOS-Extender Lite Phar Lap Software, Inc. 60 Aberdeen Ave., Cambridge, MA 02138 (617) 661-1510 FAX (617) 876-2972 tech-support@pharlap.com Copyright (c) 1992 Phar Lap Software, Inc. All rights reserved. Printed in the United States of America. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without prior written permission of Phar Lap Software, Inc. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013. Outline of Contents Introduction Chapter 1 A Quick Tour of 286|DOS-Extender Lite Big Malloc Protected Mode C++ Protected Mode MS-DOS BIOS Calls in Protected Mode Compatibility with Industry Standards What's So Protected About Protected Mode? Debugging with TDW Under MS-DOS (with the 286|DOS-Extender Software Development Kit) What About Direct Screen Writes? Summary Chapter 2 Using 286|DOS-Extender Lite with Borland C++ BCC286 Usage in Detail BCC286 Input Files Environment Variable BCC286 Switches -keep -nostub -stack=xxx BCC286 Differences from BCC Using BCC and TLINK BCC Switches .DEF File Statements TLINK Switches and Files Building Floating-Point Programs Chapter 3 Running Protected Mode Applications Under MS-DOS Compatibility LITE286 Requirements Error Messages LITE286 Command Line Options The Phar Lap Application Program Interface (PHAPI) Chapter 4 Run-Time Library Further Reading ------------ Introduction ------------ Welcome to the world beyond 640K! Now, with your FREE 286|DOS-Extender Lite, it's easy to build multi- megabyte Borland C++ programs! 286|DOS-Extender Lite is a special Borland C++ version of Phar Lap Software's award-winning 286|DOS- Extender Software Development Kit (SDK). It enables your program to break the 640K DOS barrier and access up to 2 MB of memory, with no need for overlays or EMS. Your Extended-DOS programs will run under DOS, DESQview and Windows. 286|DOS-Extender Lite includes all the capabilities you need to build and run Extended-DOS programs with Borland C++. However, you may want to purchase Phar Lap's 286|DOS-Extender SDK if you would like the following features: Turbo Debugger support, access to up to 16 MB of memory, Phar Lap's technical support and extensive documentation, and the ability to deliver your Extended-DOS application to customers with Phar Lap's 286|DOS-Extender Run-Time Kit (RTK). The following chart outlines the differences between 286|DOS-Extender Lite and 286|DOS- Extender SDK. To order your SDK, just fill out the following coupon or contact Phar Lap. 286|DOS-Extender SDK is available from: Phar Lap Software, Inc. 60 Aberdeen Avenue FREE PHAR LAP T-SHIRT Cambridge, MA 02138 WITH EVERY ORDER! Phone 617-661-1510 Fax 617-876-2972 286|DOS-EXTENDER LITE VS 286|DOS-EXTENDER SDK 286|DOS-Extender Lite │ 286|DOS-Extender SDK ════════════════════════════════════╪═════════════════════════════════════ No debugging support │ Full support for Turbo Debugger │ Programs can use up to 2 MB memory │ Programs can use up to 16 MB memory │ 50 pages of documentation on disk │ 700+ pages of printed documentation │ Technical support for installation │ Technical support for development │ Cannot deliver Extended-DOS │ Add-on run-time kit available for programs to customers │ delivering Extended-DOS programs │ Several example programs │ Extensive example programs │ No spawn function available │ Supports spawn function to run │ protected mode or real mode .EXEs │ May be used with Borland C++ only │ May be used with other compilers │ Available FREE with Borland C++ │ Available for $495 from Phar Lap 286|DOS-Extender Order Form YES! I would like to order ____ 286|DOS-Extender SDK x $495 each = _______ Mass. customers add 5% sales tax: _______ Shipping: $5 U.S. or Canada, $50 overseas: _______ TOTAL = _______ Shipping Address: (Please provide a street address. No P.O. boxes.) Name:__________________________ Company:_____________________________ Address:_____________________________________________________________ City:__________________________ State/Country:__________ Zip:________ Phone:_________________________ Fax:_________________________________ Method of Payment: (Check one) ____ Check/money order (US$, US bank) ____ P.O.#(Approval required):_______________________________________ ____ MasterCard ____ Visa ____ American Express Credit Card #:__________________________________ Exp. Date:__________ Cardholder's name:___________________________________________________ Return to: Phar Lap Software, Inc. FREE PHAR LAP T-SHIRT 60 Aberdeen Avenue WITH EVERY ORDER! Cambridge, MA 02138 Phone 617-661-1510 Fax 617-876-2972 ------------------------------------- Chapter 1 A Quick Tour of 286|DOS-Extender Lite ------------------------------------- Computers with Intel and Intel-compatible 80286, 80386, or 80486 microprocessors hold a majority share of the IBM PC-compatible marketplace. These machines typically have two or more megabytes of memory. This is in sharp contrast to the situation just a few years ago, when the typical PC had an 8088 and less than a megabyte of memory. But MS-DOS has not kept up with these sweeping changes. While PCs are shipping with more memory and better processors, more DOS applications than ever run out of memory. Many users have found that a 2 MB machine, for example, does not actually give their applications 2 MB of memory: applications are held back by the 640K limitation imposed by MS-DOS. You can add memory to an IBM AT, PS/2, or 386 clone until you're blue in the face, and many DOS applications will nonetheless run out of memory. These machines have untapped resources. 286|DOS-Extender Lite, Phar Lap's 16-bit DOS extender for 80286, 80386, and 80486 PCs, puts all this potential energy to work while fully preserving your investments in MS-DOS and Borland C++. Let's look at an example. Many manuals begin with the "hello world" sample program, but to show the power of 286|DOS-Extender Lite we need a sample program that suffers from the 640K confines of MS- DOS. Such programs are plentiful; almost any DOS program that uses large model, huge model, overlays, expanded memory (EMS), or the eXtended Memory Specification (XMS), is a good example. Any such program is also a likely candidate for using 286|DOS-Extender Lite! But short of including 50,000 lines of code in our manual, how can we provide a quick look at the problem of running old DOS on the new machines? We can simulate some "programming in the large" issues by using a small C program that requires a large amount of memory. The program shown below, BIG.C, attempts to use one megabyte of memory by declaring a 512 x 512 two-dimensional array of longs: /* BIG.C */ #include <stdlib.h> #include <stdio.h> #define SIZE 512 static long huge array[SIZE][SIZE] ; /* one-megabyte array */ main() { int i, j; printf("Using %lu-byte array\n", (long) SIZE * SIZE * sizeof(long)); for (i=0; i<SIZE; i++) { for (j=0; j<SIZE; j++) array[i][j] = (long) i * j; /* touch every element */ printf("%d\r", i); /* display odometer */ } printf("done\n"); return 0; } The Borland C++ command-line compiler, BCC, can be used to compile and link this straightforward C program for plain-vanilla, real mode MS-DOS. The -ml (large model) switch is used in the BCC command line to get the maximum amount of available memory: C:\>bcc -ml big.c While BCC compiles BIG.C without error, the Borland linker, TLINK, refuses to link the program, and produces the following error message: Fatal: Relocation item exceeds 1Meg DOS limit. This isn't a problem with TLINK, because the Microsoft linker has the same limitation (though it doesn't produce as clear an error message as TLINK does). The problem is that real mode MS-DOS really does have a one-megabyte barrier! Even if TLINK did somehow produce BIG.EXE, it wouldn't run properly under real mode MS-DOS. But to run BIG.EXE you don't have to switch to a different operating system. 286|DOS-Extender Lite removes the one-megabyte DOS barrier, while continuing to run under DOS. You get to have your cake and eat it too. To produce a 286|DOS-Extender Lite version of the BIG program, simply compile and link with BCC286, which is one of the programs included with 286|DOS-Extender Lite. BCC286 runs BCC and TLINK, taking care of all the details of producing a protected mode executable. Protected mode executable? Under DOS? That's right: C:\>bcc286 big.c C:\>big Using 1048576-byte array done We just allocated and accessed one megabyte under MS-DOS, in a program whose name we typed on the DOS command line -- just like any other regular DOS program. The source code for the program, as we've seen, used absolutely standard PC constructs: no messing with special interfaces like EMS or XMS, and no overlays. It's as if MS-DOS had been turned into a protected mode operating system, or at least into an operating system that can run protected mode programs! This in fact is exactly what 286|DOS-Extender Lite does. Behind the scenes, when BIG is run from the DOS command line, the program reinvokes itself under 286|DOS-Extender Lite, which resides in a program named LITE286.EXE (which, incidentally, must be somewhere on the path along with another file, called DOSCALLS.DLL). Running BIG is equivalent to running LITE286 BIG. LITE286 puts the machine into protected mode, runs BIG, then puts the machine back into real mode. Clearly, BIG is not a typical real mode DOS program. BCC286 takes advantage of TLINK's ability to produce protected mode Windows programs, using it instead to produce protected mode DOS programs. Chapter 2 of this manual explains precisely how BCC286 runs BCC and TLINK, so that if you prefer, you can run BCC and TLINK yourself (from MAKE, for example) rather than use BCC286. ---------- Big Malloc ---------- The huge array used in BIG.C provides a simple first example of 286|DOS-Extender Lite. In the same way that LITE286 can load a program with large amounts of data, it can also load programs with large amounts of code, so the huge array is a good simulation of a large program. Most C programs do not create huge static arrays, but many DOS programs do contain enormous amounts of code. Such programs often resort to performance-crippling overlays; BIG shows that, on an 80286 or higher machine with extended memory, this workaround is not necessary. BIG.C made life easy for itself by using the "huge" keyword, but due to its often poor performance, "huge" is usually avoided in commercial PC software. (On the other hand, BCC286 automatically uses the BCC -h option for "fast" huge pointers.) More typically, large PC applications dynamically allocate memory via the C malloc() function, via operator new in C++, or directly via the MS-DOS Allocate Memory Block function (INT 21h AH=48h). Our next example program, MEMTEST, does nothing more than run malloc() in a loop and touch every byte of the allocated memory. When malloc() eventually returns NULL, indicating that memory is exhausted, MEMTEST breaks out of the loop. While clearly the program does not do anything useful with the memory it allocates, its insatiable appetite for memory is a very good simulation of a large application: /* MEMTEST.C */ #include <stdlib.h> #include <stdio.h> main() { char *p; unsigned long allocs; for (allocs = 0; ; allocs++) if ((p = malloc(1024)) != 0) /* in 1k blocks */ { memset(p, 0, 1024); /* touch every byte */ *p = 'x'; /* do something, anything with */ p[1023] = 'y'; /* the allocated memory */ if (allocs && (allocs % 1024) == 0) /* odometer */ printf("Allocated %u megabytes\r", allocs >> 10); } else break; printf("Allocated %lu bytes\n", allocs << 10); return 0; } Using Borland C++ 3.1, this program can be compiled for real mode MS-DOS with the following command line: C:\>bcc -ml memtest.c This produces a large model version of MEMTEST.EXE, allowing maximum memory allocation under real mode MS-DOS. On a COMPAQ 386 with 2 MB of memory, MEMTEST should allocate around 2 MB of memory (if you don't think this is what MEMTEST should do, you've been programming in real mode for too long!). But of course, here is what real mode large model MEMTEST does instead: C:\>memtest Allocated 417792 bytes Only 408 KB available on a 2 MB machine?! By making better use of the DOS 5.0 LOADHIGH, DEVICEHIGH, and DOS=HIGH,UMB statements, or by using superb expanded memory managers such as Quarterdeck QEMM or Qualitas 386MAX, we could probably have created a better configuration, in which MEMTEST might get as much as 610 KB or so. But no matter how much we huffed and puffed and fooled with CONFIG.SYS, real mode MEMTEST would never allocate more than one megabyte of memory. Furthermore, even if you do maximize the available DOS memory on one machine, there is no guarantee that all (or even most) of a program's users will have such an "ideal" configuration. By developing for protected mode DOS, you can bypass a lot of these messy user-configuration issues. Now, to produce a version of MEMTEST that behaves more sensibly, the only thing you need to remember is BCC286: C:\>bcc286 memtest.c C:\>memtest Allocated 2193408 bytes We allocated almost 2 MB of memory under MS-DOS! This is dramatically different behavior from the first version of MEMTEST we produced, yet we're using the same source code as before. Simply by recompiling for 286|DOS-Extender Lite, without source code changes, we have a program that runs under DOS yet breaks the 640K barrier, without EMS, overlays, or other workarounds. Simply by using 286|DOS-Extender Lite with Borland C++, you get a version of malloc() that transparently uses extended memory, and functions such as memset(), and pointer dereferences such as *p and p[1023], that transparently access extended memory. ------------------ Protected Mode C++ ------------------ 286|DOS-Extender Lite is not limited to programs written in C; C++ programs can just as easily run under protected mode DOS. For example, the C++ new operator in protected mode DOS works exactly the same as the C malloc() function: instead of halting somewhere around 640K, operator new can be used to allocate up to 2 MB of memory under 286|DOS-Extender Lite. (286|DOS-Extender SDK can allocate up to 16 MB.) Other C++ features, such as the iostream input and output operators and static constructors and destructors, work just the way one would expect from having used C++ in real mode DOS. The next sample program, MEMTEST2.CPP, uses a number of C++ features. The C++ set_new_handler() function is particularly useful; it lets MEMTEST2 install a handler that will automatically be called when operator new fails. This considerably simplifies the program's main loop: /* MEMTEST2.CPP */ #include <stdlib.h> #include <iostream.h> #include <new.h> class msg { public: msg() { cout << "hello from " << __FILE__ << "\n" ; } ~msg() { cout << "bye\n" ; } } ; static msg banner; // test C++ static constructors, destructors static unsigned long bytes = 0; static unsigned long allocs = 0; static unsigned blk_size = 10240; void new_fail(void) { if (blk_size) blk_size >>= 1; // try to allocate a smaller block else { // memory exhausted cout << "Allocated " << bytes << " bytes\n" ; exit(1); } } main() { char *p; set_new_handler(new_fail); // called when new fails for (;;) { p = new char[blk_size]; // allocate memory memset(p, 0, blk_size); // touch every byte *p = 'x'; // do something, anything with p[blk_size-1] = 'y'; // the allocated memory bytes += blk_size; allocs++; if ((allocs % 25) == 0) // odometer cout << "Allocated " << bytes << " bytes\r"; } } We won't even bother showing the real mode version this time, since by now it's pretty obvious how limited real mode is. To compile this C++ program for protected mode DOS, all you need is BCC286: C:\>bcc286 memtest2.cpp C:\>memtest2 hello from memtest2.cpp Allocated 2027520 bytes bye Because 286|DOS-Extender Lite is compatible with the DPMI specification (as well as with every other major memory-management specification, including VCPI, XMS, VDS, and INT 15h), this protected mode C++ program can allocate up to 2 MB of memory under all modes of Windows 3.x: C:\>memtest2 hello from memtest2.cpp Allocated 2027520 bytes bye --------------------- Protected Mode MS-DOS --------------------- What's really happening here? We've seen that 286|DOS-Extender Lite can load programs with huge arrays, or enormous amounts of code, and that protected mode DOS versions of C functions such as malloc(), and of operator new in C++, can dynamically allocate large amounts of memory. How does all this work? While generally used with C or C++ programs, 286|DOS-Extender Lite is not a C or C++ library. 286|DOS-Extender Lite does replace some of the Borland C++ startup code and library functions, but this is simply to make the code protected mode "clean." The real magic occurs at a lower level. In essence, 286|DOS-Extender Lite provides MS-DOS (INT 21h) functions in protected mode. Since your program runs in protected mode, any software interrupts your program generates -- such as DOS calls made by the C run-time library when you call a function such as printf() -- occur in protected mode too, and are caught by 286|DOS- Extender Lite. In most cases, 286|DOS-Extender Lite passes the call down to MS- DOS, which is still running in real mode. DOS file I/O functions are handled this way, for example: the 286|DOS-Extender Lite handler for these functions reissues (or "reflects") the call in real mode. Merely by providing protected mode surrogates for these functions, 286|DOS-Extender Lite allows your program to think that it is running under a protected mode version of MS-DOS. The program can call INT 21h in protected mode without worrying about the fact that its file I/O buffers are probably located in extended memory. 286|DOS- Extender Lite automatically takes care of all the details of transferring data between conventional memory (where real mode DOS can get at it) and extended memory (where your protected mode program probably allocated it). Because 286|DOS-Extender Lite acts as a protected mode "wrapper" around real mode MS-DOS, you have a completely compatible environment. 286|DOS-Extender Lite isn't replacing DOS, so it will work with whatever version of DOS you or your customers already have. Of course, real mode MS-DOS does not know how to do things like run protected mode programs, allocate extended memory, load dynamic link libraries (DLLs), or install protected mode interrupt handlers. Requests such as these are handled by 286|DOS-Extender Lite entirely in protected mode. Memory allocation is a good example. Rather than use C or C++ constructs to allocate memory, the next sample program, DOSMEM.C, goes directly to DOS using INT 21h Function 48h (Allocate Memory Block). Typically, a DOS program finds out how much memory is available by asking this function for 0FFFFh paragraphs (one megabyte). Real mode DOS will naturally fail such a request, but it will also return the actual number of paragraphs available in the largest block of free memory: /* DOSMEM.C */ #include <stdlib.h> #include <stdio.h> #include <dos.h> main() { unsigned segment, avail; char far *fp; _asm mov ah, 48h _asm mov bx, 0FFFFh _asm int 21h _asm jc error _asm mov segment, ax fp = MK_FP(segment, 0); *fp = 'x'; /* make sure it's genuine */ printf("Allocated 0FFFFh paragraphs: %Fp\n", fp); return 0; error: _asm mov avail, bx printf("Only %04Xh paragraphs available\n", avail); return 1; } C:\>bcc dosmem.c C:\>dosmem Only 4FE9 paragraphs available In protected mode, an amazing thing happens: a request for 0FFFFh paragraphs easily succeeds: C:\>bcc286 dosmem.c C:\>dosmem Allocated 0FFFFh paragraphs: 0A3D:0000 Using the exact same INT 21h functional interface as real mode DOS, 286|DOS-Extender Lite provides functionality that DOS alone can't provide. This new functionality is provided to every protected mode program running under 286|DOS-Extender Lite. Thus, 286|DOS- Extender Lite isn't a library, but an extension to the operating system. (That's why it's called a DOS extender.) When protected mode DOSMEM allocates 0FFFFh paragraphs, where does this memory come from? In general, this doesn't matter to the program, because it has asked INT 21h Function 48h for memory, and has received a value back in the AX register which it can use as the basis for a far segment:offset pointer. In DOSMEM.C, note how a far pointer is created with the Borland MK_FP() macro, and poked with the C * dereferencing operator. Thus, we have immediately usable memory; it doesn't really matter where it "comes from," nor for that matter what value INT 21h Function 48h returns in AX. All we need to know is that we can use it. However, the pointer 0A3D:0000 displayed above by DOSMEM in protected mode is a little strange. Paragraph 0A3Dh seems to be too low in memory, for example. But in protected mode the address 0A3D:0000 has nothing whatever to do with absolute memory location 0A3D0h. Instead, 0A3Dh is a protected mode selector that is essentially an index into a table of segment descriptors used by the chip. These descriptors in turn contain the base address, size, and protection "access rights" of the corresponding segment. Thus, memory management in protected mode is somewhat indirect, but all the indirection is managed entirely by the chip, "inside" an instruction such as MOV AX, ES:[BX]. ---------------------------- BIOS Calls in Protected Mode ---------------------------- To create a useful environment for PC software, it is not sufficient merely to provide INT 21h in protected mode. The ROM BIOS calls (INT 10h, INT 16h, and so on) need to be available in protected mode too. Borland C++ run-time library functions such as bioscom(), biosprint(), and bioskey() are available in protected mode. Furthermore, protected mode DOS programs can call BIOS functions from separate .ASM modules assembled with Turbo Assembler (TASM), or using inline assembler, the int86() and int86x() functions, or Borland register pseudovariables. For example, if our MEM sample program did direct screen writes (which we will discuss in more detail later in this chapter), it might include initialization code such as the following, which uses INT 10h Function 0Fh (Get Video Mode): #include <dos.h> #define GET_VIDEO_MODE 0x0F int video_mode(void) { union REGS r; r.h.ah = GET_VIDEO_MODE; int86(0x10, &r, &r); return r.h.al; } or, using inline assembler, something like this: int video_mode(void) { _asm mov ah, GET_VIDEO_MODE _asm int 10h _asm xor ah, ah // 2 byte quantity returned in AX } or, using Borland register pseudovariables: int video_mode(void) { _AH = GET_VIDEO_MODE; geninterrupt(0x10); _AH = 0; // 2 byte quantity returned in AX } All these varieties of the video_mode() function run just fine in protected mode, because 286|DOS-Extender Lite supports INT 10h (BIOS Video) in protected mode. The following list shows all interrupts and functions that are supported in protected mode -- the vast majority of DOS (INT 21h) and BIOS (INT 10h, INT 16h, etc.) calls: INT 10h (BIOS Video) Functions 0 through 1Ch INT 11h (BIOS Equipment Check) INT 12h (Conventional Memory Size) INT 14h (BIOS Communications) Functions 0 through 5 INT 16h (BIOS Keyboard) Functions 0 through 12h INT 17h (BIOS Printer) Functions 0 through 2 INT 1Ah (BIOS Time) Functions 0 through 80h INT 21h (MS-DOS Functions) Functions 0 through 0Eh Functions 19h through 30h Functions 32h through 43h Function 44h (IOCTL) Subfunctions 0, 1, 6, 7, 8, 9, 0Ah, 0Bh, 0Eh, and 0Fh Functions 45h through 63h Because a request to INT 21h Function 48h (Allocate Memory Block) for FFFFh paragraphs can succeed in protected mode, this function should be used only for memory allocation, not to determine the amount of available memory. Use the DosMemAvail() and DosRealAvail() functions instead for this purpose. Functions 66h through 6Ch INT 33h (Microsoft Mouse) ------------------------------------- Compatibility with Industry Standards ------------------------------------- We have seen that 286|DOS-Extender Lite (that is, LITE286.EXE) manages the interface between your protected mode program and real mode MS-DOS. At the DOS command line, when you type the name of a protected mode .EXE file, LITE286 puts the machine into protected mode and launches your program. Whenever your program makes DOS or BIOS calls from protected mode, 286|DOS-Extender Lite handles them and/or passes them down to MS-DOS or the ROM BIOS. When your program exits, 286|DOS-Extender Lite puts the computer back into real mode. But what if the machine wasn't in real mode to begin with? Many 80386 and 80486 computers, for example, will be running software such as Microsoft Windows 3.x (Enhanced mode), Microsoft EMM386, Quarterdeck DESQview/386, or Qualitas 386MAX. When these are loaded, MS-DOS is running not in real mode but in a one-megabyte protected mode that Intel calls "virtual 8086" mode. Furthermore, users may be running programs that use extended memory, such as VDISK, HIMEM, or SMARTDrive. 286|DOS-Extender Lite handles all these situations gracefully. It is compatible with all the PC industry standards for protected mode, expanded memory (EMS), and extended memory (XMS). It supports the Virtual Control Program Interface (VCPI) and DOS Protected Mode Interface (DPMI). VCPI, a specification developed jointly by Quarterdeck Office Systems and Phar Lap Software, allows EMS emulators and DOS extenders to coexist; it is an extension to EMS 4.0. DPMI is a specification whose primary goal is compatibility between DOS extenders and DOS multitasking environments; DPMI was jointly developed by a committee including Microsoft, Intel, IBM, Phar Lap, Quarterdeck, Borland, Lotus, Rational Systems, and other companies. This means that programs developed with 286|DOS-Extender Lite can run in a wide variety of DOS environments. All this compatibility requires no work from you. There is no configuration or "tune" program to run. 286|DOS-Extender Lite automatically configures itself each time it runs. If run under Windows 3.x Enhanced mode, for example, the program will automatically get virtual memory with no additional effort. Or if you switch from HIMEM.SYS to QEMM386.SYS, you don't have to reconfigure 286|DOS-Extender Lite in any way. ----------------------------------------- What's So Protected About Protected Mode? ----------------------------------------- So far we have described the process of compiling for protected mode and running under MS-DOS. The next step in the development cycle is debugging. Returning to the MEM sample program, for example, suppose we forgot to check the return value from malloc(). In the C++ version, we could use set_new_handler() to catch failed memory allocations. But in C, it's simply a mistake to forget to check the return value from malloc(): for (allocs = 0; ; allocs++) { p = malloc(1024); /* BUG: not checking return value from malloc!*/ memset(p, 0, 1024); *p = 'x'; p[1023] = 'y'; } This horrible code runs without complaint in real mode. In a large model program, its probable effect is to repeatedly bash the low-memory interrupt vector table. What happens in protected mode when malloc() fails and we then try to dereference (peek or poke) the resulting NULL pointer? Instead of trashing memory, the program halts with a message like this: Fatal error 286.3330: General protection fault detected. PID=0001 TID=0001 SID=0001 ERRORCODE=0000 AX=0000 BX=0000 CX=0200 DX=0000 SI=056C DI=0000 BP=2DCC CS:IP=014F:0CC5 DS=0157 ES=0000 SS:SP=0157:2DCA FLAGS=3216 The message "General protection fault detected" is an indication that the program has in some way violated the rules of protected mode. These rules prevent writing into code segments, executing data segments, reading or writing past the end of a segment, or using a segment that doesn't belong to you. A general protection violation, or GP fault, shows either a bug in your program, or an area that needs to be converted so that it will work in protected mode. In either case, the CPU signals a GP fault when your program tries to violate protection. This makes protected mode a superb environment for software development: the hardware will help you find bugs and trouble spots. In the case of the buggy version of MEM, the message "General protection fault detected" message alerts us to a bug that the CPU found for us: the program dereferences pointers without checking if malloc() succeeded. If you examine the register dump produced by 286|DOS-Extender Lite, you will note that the ES register is set to zero, suggesting we tried to dereference a NULL pointer. This NULL pointer checking is not inserted by the compiler: the Intel processor takes care of it in hardware, making it just one example of the many checks that the CPU does in protected mode, with no extra work on our part. ---------------------------------------------------- Debugging with TDW Under MS-DOS (with the 286|DOS-Extender Software Development Kit) ---------------------------------------------------- As explained at the beginning of this file, 286|DOS-Extender Lite does not support debugging. The 286|DOS-Extender SDK, however, supports the powerful debugging features in the protected mode Windows version of Turbo Debugger (TDW) that comes with Borland C++. We would like to take this opportunity to illustrate the debugging support available with the 286|DOS-Extender SDK. For an example, let's look at the buggy MEM program. A protected mode symbolic debugger like TDW would let us pinpoint the exact location of the bug in the MEM program (if we didn't already know it). We wouldn't run TDW under Windows, though, or if we did, we'd be running it in a DOS box. We would use 286|DOS-Extender to run TDW under MS-DOS, right from the DOS prompt, without Windows. Just as 286|DOS-Extender runs your protected mode applications under MS-DOS, it can run a protected mode debugger like TDW. (286|DOS-Extender makes this possible through its support for dynamic link libraries (DLLs). This feature is explained in the documentation for the 286|DOS-Extender SDK.) TDW runs under DOS because 286|DOS-Extender supplies Windows-emulation libraries such as KERNEL.DLL, USER.DLL, and WINDEBUG.DLL. But why would we use a Windows debugger to debug DOS programs? Because TDW understands protected mode programs. In fact, 286|DOS- Extender executables use the same standard Microsoft segmented- executable file format used by Windows. This is why TLINK, which knows how to produce Windows executables, can also produce 286|DOS- Extender executables. Why can't we just use the protected mode TD286 debugger? Because TD286 merely runs in protected mode: it doesn't know how to debug protected mode programs. In a way, TD286 is a "cross-development tool": it's a protected mode debugger, used to debug real mode programs. When running under 286|DOS-Extender, TDW is a protected mode DOS debugger, used to debug protected mode DOS programs. To make symbolic information available for TDW under DOS, we would use the Borland C++ -v switch: C:\>bcc286 -v buggymem.c If you happen to be developing 286|DOS-Extender applications with Microsoft C, and want to debug with Borland's Turbo Debugger rather than with Microsoft's CodeView, you would compile with the Microsoft -Zi (CodeView) switch, then run the Borland TDCONVRT utility to prepare your program for TDW. You must use the TDCONVRT -c switch. For example: C:\>cl -Lp -AL -Zi buggymem.c C:\>\borlandc\bin\tdconvrt -c buggymem To debug a protected mode program under DOS, run TDW, together with your program, under 286|DOS-Extender: C:\>RUN286 \borlandc\bin\tdw buggymem You would probably tire of typing this long command line each time you want to debug a protected mode DOS program. The Phar Lap BIND286 utility can be used to create a new executable, TDP.EXE, whose name you would then type on the DOS command line instead of RUN286 TDW. To build TDP.EXE: C:\>bind286 \borlandc\bin\tdw -exe \RUN286\bin\tdp.exe Whether you run TDP or RUN286 TDW, you can do source-level debugging of protected mode DOS programs without having to learn a new debugger. For the remainder of this discussion, we shall refer to TDW running under 286|DOS-Extender as TDP. If you do not already know how to use Turbo Debugger, refer to the Borland documentation or one of several third-party books, such as Tom Swan's Mastering Turbo Debugger (Carmel IN: Hayden Books, 1990, 618 pp., ISBN 0-672-48454-4). TDP displays just a few differences from real mode TD. The major difference is that TDP can debug multimegabyte applications, whereas real mode TD can't. TDP can also be extended using Phar Lap's PMON, which provides the ability to walk the protected mode descriptor tables, display DPMI interrupt and exception vectors, and so on. Inside TDP, you can press F9 to run a program, F8 to step, F7 to trace, F2 to set a breakpoint, CTRL-W to watch an expression, F1 to get help, and so on. Alternatively, you can use the pull-down menus and the mouse. TDP can be run in 25-line or 43/50-line mode. When debugging BUGGYMEM, if you press F9, malloc would eventually run out of memory. TDP would run into our offending code, and place the cursor on the REP STOSW instruction and display this message: Exception 13, error code 0 Sure enough, forgetting to check the return value from malloc() causes an "exception 13" (also known as an INT 0D, a General protection violation, or a GP fault). The CPU window would show that the ES segment register holds a value of zero, indicating that we're trying to do something with a NULL pointer. In real mode, the interpretation of 0:0 as a NULL pointer is an arbitrary convention, because in real mode, 0:0 is a completely legitimate address (it holds the address of the divide-by-zero interrupt handler). Protected mode, however, provides hardware support for the notion of a NULL pointer. Where would we be? By selecting the "Stack" option from the TDP "View" menu, and then navigating the stack view window, we would see that we're somewhere inside the call to memset() inside main(). This is not surprising, given that the call to memset() immediately follows the incorrect use of malloc(). Can you imagine debugging this code without TDW? We hope you will see from this example how much easier protected mode programming can be with the features available in the 286|DOS-Extender SDK. -------------------------------- What About Direct Screen Writes? -------------------------------- So far we have seen that straightforward C or C++ code can be taken and run, without source-code changes, under Phar Lap's 286|DOS- Extender Lite. But while they allocated large amounts of memory, and showed some of the benefits of 286|DOS-Extender Lite and the basic process of developing applications with 286|DOS-Extender Lite, our MEMTEST sample programs are too simple to illustrate all the issues involved in PC software development. The remainder of this chapter quickly examines some of the issues pertinent to Borland C++. Clearly, MEMTEST is not a typical PC program. For example, it uses the portable printf() function to display output. With the exception of programs such as compilers and linkers, however, applications for the PC tend to use direct screen writes or other low-level code. How well do such programs run under 286|DOS-Extender Lite? We saw earlier that DOS (INT 21h) and BIOS calls are supported in protected mode. Thus, low-level PC code runs as is under 286|DOS- Extender Lite. However, the PC programming interface doesn't consist only of DOS and BIOS calls. The ability to peek and poke absolute memory locations is also part of the PC programming interface, and this ability normally assumes that the program is running in real mode. Direct screen writes are a good example, because these assume that absolute memory locations such as B8000h can be addressed through pointers such as B800:0000. When a program is manipulating an address such as B800:0000, it's really interested in absolute memory location B8000h. Similarly, when it manipulates an address such as 0040:006C, it's really interested in absolute memory location 46Ch. In protected mode the equivalence of B8000h and B800:0000 no longer holds. It is precisely because protected mode throws out this equivalence that it can provide more than one megabyte of memory. Besides the tiny video_mode() function we saw in the discussion of DOS and BIOS calls, a program that does direct screen writes probably would also include code such as the following, which puts the paragraph address of the text mode video display memory (0xB000 or 0xB800) into a global variable. This code also uses the MK_FP() macro from DOS.H in Borland C++ to create a far pointer to B000:0000 or to B800:0000: unsigned short get_vid_mem(void) { int vmode = video_mode(); unsigned short seg; if (vmode == 7) /* monochrome */ seg = 0xB000; else if ((vmode == 2) || (vmode == 3)) seg = 0xB800; else return 0; return seg; } static BYTE far *vid_mem; /* use far pointer */ video_init(void) { vid_mem = MK_FP(get_vid_mem(), 0); } #define SCR(y,x) (((y) * 160) + ((x) << 1)) void wrt_str(int y, int x, ATTRIB attr, unsigned char *p) { BYTE far *v = vid_mem + SCR(y, x); while (*p) { *v++ = *p++; *v++ = attr; } } But if we now try to run a program that includes this code under 286|DOS-Extender Lite, we get another one of those "General protection fault detected" messages, just as if our code contained a bug: C:\>bcc286 memtest3.c C:\>memtest3 Fatal error 286.3330: General protection fault detected. PID=0001 TID=0001 SID=0001 ERRORCODE=B800 AX=0041 BX=0098 CX=01ED DX=0000 SI=042E DI=042E BP=0F08 CS:IP=022F:01FD DS=024F ES=024F SS:SP=024F:0F06 FLAGS=3206 Our code doesn't contain a bug. However, ERRORCODE=B800 suggests that simply loading the paragraph address of the video display memory into a segment register such as DS or ES isn't going to work in protected mode. It's extremely simple to get this code working in protected mode. To write directly to video memory from protected mode, you need a function call that "maps" absolute memory locations into the address space of your protected mode program. The only function that needs to be changed is get_vid_mem(), so that instead of returning 0xB000 or 0xB800, it returns a protected mode selector that maps one of these real mode paragraph addresses. To do this, we use the Phar Lap API (PHAPI) function DosMapRealSeg(), whose prototype is in PHAPI.H. #ifdef DOSX286 // symbol DOSX286 automatically defined by BCC286 #include <phapi.h> #endif unsigned short get_vid_mem(void) { int vmode = video_mode(); unsigned seg; if (vmode == 7) seg = 0xB000; else if ((vmode == 2) || (vmode == 3)) seg = 0xB800; else return 0; #ifdef DOSX286 { unsigned short sel; /* DosMapRealSeg() takes a real mode paragraph address and a count of bytes, and gives back a selector that can be used to address the memory from protected mode. Like all PHAPI functions, DosMapRealSeg() returns 0 for success, or a non-zero error code. Any other information (such as the selector we're interested in) is returned via parameters. */ if (DosMapRealSeg(seg, (long) 25*80*2, &sel) == 0) return sel; else return 0; } #endif return seg; } In the larger program from which this code was extracted, this was the only source-code change needed to get the program running under 286|DOS-Extender Lite. All the actual direct screen writes ran in protected mode without modification. Most graphics code can be ported to 286|DOS-Extender Lite in the same way, simply by changing the function that returns the segment number of video memory, to use DosMapRealSeg (0xA000, ...). Since the PHAPI-specific code is inside an #ifdef, the same code can be compiled for real mode with BCC, or compiled for protected mode by compiling with BCC286 (which automatically defines DOSX286). When the program is finished with the selector to video memory, it should free it by calling DosFreeSeg(): DosFreeSeg(FP_SEG(vid_mem)); // segment of far pointer That's all it takes to get direct screen writes working in protected mode. ------- Summary ------- Any given program probably will require only a few PHAPI functions; the vast majority of your DOS code will work "as is" under 286|DOS- Extender Lite. You can preserve your investment and your customer's investment in MS-DOS. 286|DOS-Extender Lite turns Borland C++ into a toolkit for protected mode DOS development. Just by using BCC286 rather than BCC, your Borland C++ programs break the 640K barrier. -------------------------------------------- Chapter 2 Using 286|DOS-Extender Lite with Borland C++ -------------------------------------------- The easiest way to compile and link 286|DOS-Extender Lite programs with Borland C++ is to use BCC286, available with 286|DOS-Extender Lite: C:\TEST>bcc286 memtest.c C:\TEST>memtest C++ programs can also be compiled and linked for 286|DOS-Extender Lite: C:\TEST>bcc286 memtest.cpp C:\TEST>memtest BCC286.EXE will usually be installed in C:\LITE286\BIN, which must be on your path. BCC286 uses Borland's BCC.EXE and TLINK.EXE; these must also be on the path. For example: C:\TEST>set path=c:\LITE286\bin;c:\borlandc\bin;c:\bin 286|DOS-Extender Lite requires TLINK version 4.0 or higher, shipped with Borland C++; it will not work with the earlier Turbo C or Turbo C++ versions of TLINK. 286|DOS-Extender Lite also requires the Borland C++ command-line tools, and will not work with the BC integrated development environment (IDE). BCC286 also uses C0PL.OBJ and PHAPI.LIB, which come with 286|DOS- Extender Lite, and BCL286.LIB, which is built when you install 286|DOS-Extender Lite. These files must be located on the path, or in a directory named in an optional LIB environment variable, or in the library path specified with a BCC286 -L command-line parameter. These files are usually installed in C:\LITE286\BC3\LIB. If you receive a message from BCC286 such as "Cannot find C0PL.OBJ", you need to specify a library search path. For example: C:\TEST>bcc286 -L\LITE286\bc3\lib;\borlandc\lib phoo.c or: C:\TEST>set lib=\LITE286\bc3\lib;\borlandc\lib C:\TEST>bcc286 phoo.c A good place to put switches such as -L and -I (include file path) is inside the Borland C++ TURBOC.CFG file. For example: C:\TEST>type turboc.cfg -L\LITE286\bc3\lib;\borlandc\lib;\borlandc\classlib\lib -I\borlandc\include;\LITE286\inv -G -O BCC286 does a large model compile with BCC and then creates a module-definition (.DEF) file which is passed to TLINK, along with protected mode object modules and libraries, to create a protected mode executable which can be run from the DOS command line. BCC286 places a loader inside each protected mode executable; this loader automatically runs 286|DOS-Extender Lite (LITE286.EXE) each time you start the protected mode executable from the DOS command line. ---------------------- BCC286 Usage in Detail ---------------------- If you run BCC286 without any command-line arguments, it displays the standard BCC options followed by the additional options supplied by BCC286: BCC286 Version 2.1 Copyright (c) 1991 Phar Lap Software, Inc. Borland C++ Version 3.1 Copyright (c) 1991 Borland International Syntax is: BCC [ options ] file[s] * = default; -x- = turn switch x off -1 80186/286 Instructions -2 80286 Protected Mode Inst. -Ax Disable extensions -B Compile via assembly -C Allow nested comments -Dxxx Define macro -Exxx Alternate Assembler name -G Generate for speed -Hxxx Use pre-compiled headers -Ixxx Include files directory -K Default char is unsigned -Lxxx Libraries directory -M Generate link map -N Check stack overflow -Ox Optimizations -P Force C++ compile -Qxxx Memory usage control -S Produce assembly output -Txxx Set assembler option -Uxxx Undefine macro -Vx Virtual table control -Wxxx Create Windows application -X Suppress autodep. output -Yx Overlay control -Z Suppress register reloads -a Generate word alignment -b * Treat enums as integers -c Compile only -d Merge duplicate strings -exxx Executable file name -fxx Floating point options -gN Stop after N warnings -iN Max. identifier length -jN Stop after N errors -k Standard stack frame -lx Set linker option -mx Set Memory Model -nxxx Output file directory -oxxx Object file name -p Pascal calls -r * Register variables -u * Underscores on externs -v Source level debugging -wxxx Warning control -y Produce line number info -zxxx Set segment names BCC286: Phar Lap 286|DOS-Extender driver for Borland C++ produces protected-mode DOS executables usage: bcc286 [options] [filenames] options: any bcc option or: -stack=n set stack size -nostub for smaller file without stub loader -keep keep BCC286's RSP, LNK, and DEF files BCC286 Input Files ------------------ BCC286 accepts the following file types: C source files (default extension .C) C++ source files (default extension .CPP) Assembly-language source files (default extension .ASM) .OBJ object modules .LIB object libraries .DEF module-definition files Pathnames can be specified using either backslashes or forward slashes: C:\TEST>bcc286 \phoo\bar\hello.cpp C:\TEST>bcc286 /phoo/bar/hello.cpp In addition to standard BCC operation (described in the Borland C++ User's Guide) BCC286 handles .DEF and .ASM files in the following way: .DEF files are passed to TLINK, and override the standard BCC286 module-definition file. For example: C:\TEST>bcc286 hello.c hello.def If an .ASM file is the first file passed to BCC286, then no startup code is linked in. For example: C:\TEST>bcc286 hello.asm phoo.c bar.c Like BCC, BCC286 also accepts response files and configuration files, including TURBOC.CFG. For example: C:\TEST>type hello.rsp -v -DDEBUGGING -L\LITE286\bc3\lib;\borlandc\lib hello.c C:\TEST>bcc286 @hello.rsp C:\TEST>type hello.cfg -v -DDEBUGGING -L\LITE286\bc3\lib;\borlandc\lib C:\TEST>bcc286 +hello.cfg hello.c Response and configuration files do not suffer from the 128-byte limitation of the DOS command line. BCC286-specific switches such as -stack should not be placed in configuration files. They can, however, be placed in response files. Environment Variables --------------------- BCC286 switches can also be placed in an optional BCC286 environment variable. Except for BCC286-specific switches such as -stack or -nostub, switches placed in the BCC286 environment variable will also be passed on to BCC. For example: C:\TEST>set bcc286=-v -DDEBUGGING -L\LITE286\bc3\lib;\borlandc\lib C:\TEST>bcc286 phoo.c bar.c As noted earlier, in addition to the BCC -L switch for specifying a library search path, BCC286 will also use an optional LIB environment variable. For example: C:\TEST>set lib=\borlandc\lib;\LITE286\bc3\lib C:\TEST>bcc286 phoo.c bar.c phoobar.lib --------------- BCC286 Switches --------------- BCC286 provides a number of features not found in BCC, including the ability to specify .DEF files on the command line and to set the stack size. Most BCC286 switches, whether specified on the command line, in the BCC286 environment variable, or in a response or configuration file, are passed down to BCC. The following switches are not passed down, and are unique to BCC286: -keep ----- Normally, BCC286 removes the three temporary files it creates: the BCC response file, TMP.RSP; the TLINK response file, TMP.LNK; and the module-definition file, TMP.DEF. If you use the -keep switch, BCC286 won't remove these files; you'll be able to examine, copy, or edit them for your own use with BCC and TLINK. -nostub ------- 286|DOS-Extender Lite programs produced with BCC286 can be run directly from the DOS command line because they include a "real mode stub" called GORUN286.EXE, which reinvokes the program under LITE286.EXE. This GORUN286 stub increases the size of the program by about 10 KB. The BCC286 -nostub switch suppresses the use of this stub, resulting in smaller executable files which, however, can only be run from the DOS command line by explicitly using LITE286; otherwise they produce a confusing message and exit back to DOS. For example: C:\TEST>bcc286 hello.c C:\TEST>hello hello world! C:\TEST>bcc286 -nostub hello.c C:\TEST>hello This program must be run under OS/2. C:\TEST>LITE286 hello hello world! Note, however, that under the full-fledged 286|DOS-Extender,the DosExecPgm() function and the spawn() family of functions in the C run-time library can directly invoke protected mode programs without a real mode stub. If you want to specify a real mode stub other than GORUN286, use a .DEF file. As noted earlier, .DEF files can be specified on the BCC286 command line. For example: C:\TEST>type hello.def PROTMODE STUB 'mystub.exe' EXPORTS BCC286_EXE C:\TEST>bcc286 hello.c hello.def -stack=xxx ---------- This switch can be used to set the stack size of a program. For example: C:\TEST>bcc286 -stack=10240 hello.c Stack size can alternatively be specified inside a .DEF file. For example: C:\TEST>type hello.def PROTMODE STUB 'gorun286.exe' STACKSIZE 10240 EXPORTS BCC286_EXE C:\TEST>bcc286 hello.c hello.def The default stack size defined by BCC286 is 4 KB. If you receive a TLINK "Group DGROUP exceeds 64K" error message, you can try reducing the stack size. --------------------------- BCC286 Differences from BCC --------------------------- BCC286 has the following differences from BCC: The only supported memory model switch is -ml (large model). If you need near or huge data, use the near, far, and huge keywords in your source code to create "mixed model" programs. Because 286|DOS-Extender Lite, like Windows, does not support overlays, the BCC -Yo and TLINK -o overlay switches cannot be used when creating 286|DOS-Extender Lite programs. 286|DOS-Extender Lite does not suffer from the 640K limitations of MS-DOS, so overlays are usually unnecessary. ------------------- Using BCC and TLINK ------------------- If you would prefer to use BCC and TLINK directly to compile and link 286|DOS-Extender Lite programs, instead of using BCC286, there are certain command-line options, object modules, libraries, and module-definition files which you must use. These are normally taken care of automatically by BCC286. For example, to produce a protected mode DOS version of HELLO.EXE, without BCC286: C:\TEST>bcc -c -ml -2 -DDOSX286 -h hello.c C:\TEST>type protmode.def PROTMODE STUB 'gorun286.exe' EXPORTS BCC286_EXE C:\TEST>type hello.lnk \LITE286\BC3\lib\c0pl hello hello nul phapi bcl286 protmode C:\TEST>tlink /L\LITE286\BC3\lib @hello.lnk The following briefly describes each switch, statement, or file. This description is necessary only if you are compiling and linking directly with BCC and TLINK, rather than using BCC286. BCC Switches ------------ -c (compile only): A module-definition (.DEF) file must be specified when using Borland TLINK to produce 286|DOS-Extender Lite programs, but BCC (unlike BCC286) does not accept .DEF files on its command line. Therefore, TLINK must be run as a separate step. -ml (large model): Large model is required when using Borland C++ to produce 286|DOS-Extender Lite programs. The near, far, and huge keywords can be used in source code to produce a "mixed model" program. -2 (80286 protected mode instructions): This switch is usually not necessary, but BCC produces better code when it is used. Since 286|DOS-Extender Lite programs run only on 80286 and higher machines, it makes sense to use this switch. If a user attempts to run a 286|DOS-Extender Lite program on an 8086 or 8088 machine, LITE286 detects the error before your program starts. The -2 switch is necessary if your C or C++ program includes inline assembly-language statements that use 286-based protected mode instructions such as LAR or LSL. -DDOSX286 (define the symbol DOSX286): This symbol is not strictly necessary, but BCC286 automatically defines it, and some of the examples in this manual assume that it has been defined. .DEF File Statements -------------------- A .DEF file provides information to the linker about the contents and system requirements of a protected mode program, including Windows and 286|DOS-Extender Lite programs. A .DEF file is needed to produce a 286|DOS-Extender Lite program with Borland C++. BCC286 automatically produces a standard .DEF file that contains the following statements (the line that begins with a semicolon is a comment): ; protmode.def PROTMODE STUB 'gorun286.exe' EXPORTS BCC286_EXE If you are running BCC and TLINK directly without using BCC286, then you must specify your own .DEF file. You can create one standard PROTMODE.DEF for use with all your programs, or create a separate customized .DEF file for each program. The statements used in the default .DEF file created by BCC286 are explained below: PROTMODE: The PROTMODE statement should almost always be used. Only omit this statement when you are creating a real mode DLL. STUB 'gorun286.exe': The STUB statement embeds the specified real mode DOS executable at the beginning of the protected mode executable. This real mode DOS executable then becomes the "stub" which is run whenever the program is invoked from the DOS command line. GORUN286.EXE is a real mode program which reinvokes 286|DOS- Extender Lite programs under LITE286.EXE, creating the useful illusion that MS-DOS is capable of running protected mode programs. If a different real mode stub is specified, the 286|DOS-Extender Lite program may have to be run from the DOS command line with an explicit LITE286 statement. If the STUB statement is omitted and the 286|DOS-Extender Lite program is run directly from the DOS command line, it will print out the confusing and untrue statement "This program must be run under OS/2." EXPORTS BCC286_EXE: Currently, this is required only for Borland C++ executables that use floating-point math. However, it is safest to include this statement in all Borland C++ executables. TLINK Switches and Files ------------------------ /L\lite286\bc3\lib: The TLINK /L switch specifies a library search path. The libraries PHAPI.LIB and BCL286.LIB, and the C0PL.OBJ startup object module, are usually located in C:\LITE286\BC3\LIB. @hello.lnk: While TLINK can be run with all necessary files and switches named right on the command line, in most genuine programs this will run up against the 128-byte DOS command line limit. For example, even protected mode HELLO requires a long command line if you're not using BCC286: C:\TEST>tlink /L\LITE286\bc3\lib c0pl hello,hello,,bcl286 phapi,protmode The alternative is to put TLINK input in a response file. Newlines are used to delimit fields, and a + sign is used to continue fields across multiple lines. The TLINK fields are obj,exe,map,lib,def. For example: C:\TEST>type hello.lnk c0pl + hello hello nul bcl286 phapi protmode C:\TEST>tlink /L\LITE286\bc3\lib @hello.lnk C0PL.OBJ: This is 286|DOS-Extender Lite protected mode large model startup code for Borland C++. This file is shipped with 286|DOS-Extender Lite SDK and will generally be located in C:\LITE286\BC3\LIB. PHAPI.LIB: This library contains import references for Phar Lap application program interface (PHAPI) functions exported from the 286|DOS-Extender Lite DLLs. BCL286.LIB: This library contains a protected mode compatible version of the Borland C++ run-time library. This file is built during installation of 286|DOS-Extender Lite, from Borland's CL.LIB, and will generally be located in C:\LITE286\BC3\LIB. -------------------------------- Building Floating-Point Programs -------------------------------- By default, BCC286 compiles program with the -f flag, for floating-point emulation. If a program does not in fact require floating-point math, this makes the executable about 16 KB larger than necessary. To generate smaller executables, use the BCC286 -f- (no floating point) option. For example: C:\TEST>bcc286 -f- hello.c If you are using floating-point math, there are several issues which may be important: If you will be running floating-point protected mode applications under Windows Enhanced mode, you must install the virtual device driver PHARLAP.386, included with 286|DOS-Extender Lite. Insert the statement "DEVICE=C:\LITE286\BIN\PHARLAP.386" (or whatever path is appropriate) in the [386Enh] section of the SYSTEM.INI file. BCC286 generates a protected-mode floating-point program when the -f (floating point emulation), -ff (fast emulation), -f87 (8087 hardware) or -f287 (80287 hardware) option is used. When linking such programs directly with TLINK, however, you must specify the correct library modules. For example, if sqrt.exe uses floating- point emulation: C:\TEST>bcc286 -f sqrt.c or: C:\TEST>bcc -c -f -ml -2 -h -DDOSX286 sqrt.c C:\TEST>tlink c0pl sqrt emu286.lib,sqrt,,emu mathl phapi bcl286,protmode If sqrt2.exe uses 80287 floating-point hardware instructions: C:\TEST>bcc286 -f287 sqrt2.c or: C:\TEST>bcc -c -f287 -ml -2 -h -DDOSX286 sqrt2.c C:\TEST>tlink c0pl sqrt fp286.lib,sqrt2,,fp87 mathl phapi bcl286,protmode Note that floating-point emulation requires EMU286.LIB (linked in as an object module) and EMU.LIB, while programs that use floating- point hardware instructions require FP286.LIB (linked in as an object module) and FP87.LIB. If you build floating-point applications without BCC286, you must export the symbol BCC286_EXE. Simply insert the statement "EXPORTS BCC286_EXE" in your module-definition (.DEF) file. For example: C:\TEST>type protmode.def PROTMODE EXPORTS BCC286_EXE If you have a floating point coprocessor, but need to test floating-point emulation, set 87=NO in the DOS environment. ------------------------------------------------ Chapter 3 Running Protected Mode Applications Under MS-DOS ------------------------------------------------ So far we have seen that a program produced by BCC286 can be run directly from the DOS command line simply by typing its name, like any other DOS program. 286|DOS-Extender Lite programs can also be run under DOS without a command line, using any of the many alternatives to COMMAND.COM such as the DOSSHELL in DOS 5. By default, a protected mode program produced by BCC286 includes a real mode "stub" program called GORUN286. When one of these programs is started under DOS, it is actually an embedded copy of GORUN286.EXE which runs initially. GORUN286 is called a stub because its sole job is to restart the program under 286|DOS-Extender Lite, (LITE286.EXE). In other words, if PHOO.C is compiled with: C:\TEST>bcc286 phoo.c then running the program by typing its name: C:\TEST>phoo is equivalent to typing LITE286 followed by the name of the program: C:\TEST>LITE286 phoo This seems like no big deal: after all, we've saved only six letters and a space. However, by eliminating the need to type those seven keystrokes, we have effectively hidden the DOS extender, and created the useful illusion that MS-DOS is an operating system that runs protected mode executables. Though usually hidden, the key components of 286|DOS-Extender Lite are LITE286.EXE, which loads 16-bit protected mode .EXE files under MS-DOS, and DOSCALLS.DLL, a dynamic link library (DLL) which contains some of the functions used by the protected mode Borland C++ startup code and run-time library. The directory containing these files, for example C:\LITE286\BIN, must be located somewhere on the DOS file- search path when you start an executable produced by BCC286. LITE286.EXE puts the computer into protected mode and loads your protected mode program. Whenever your program makes DOS (INT 21h) or BIOS requests from protected mode, the DOS extender quickly and invisibly does the work of sending the requests off to MS-DOS or the ROM BIOS, which are running in real mode. Thus, 286|DOS-Extender Lite is 100% compatible with DOS: it's not an emulation, but literally an extension of DOS. ------------- Compatibility ------------- There is another side to extending MS-DOS. One of the key services of 286|DOS-Extender Lite, in contrast to any "roll your own" approach to protected mode, is compatibility. We've been assuming that the computer is in real mode, that LITE286 switches it into protected mode, installs some interrupt handlers, spawns your protected mode program and, when your program completes, puts the computer back into real mode. But that would involve a simplistic view of the PC world in the 1990s. Most users of 80386 and 80486 machines are employing memory managers such as EMM386, 386MAX and QEMM, or multitasking window systems such as DESQview or Microsoft Windows 3.x. When such programs are running, the computer is not in real mode; it's running in a one-megabyte protected mode called virtual 8086 mode. The assumption that a DOS extender can simply switch the machine from real mode to protected mode does not take into account the fact that many machines won't be in real mode. Furthermore, users may be running programs such as VDISK or HIMEM or SMARTDrive, which use extended memory. LITE286 must be able to run your protected mode program under DOS, yet be highly compatible with any other memory- management software a user might be running. One of the key questions about any protected mode MS-DOS solution is how compatible it is with all this different software. Is it compatible with EMM386, 386MAX, and QEMM? Does it run in a window inside DESQview/386 or Microsoft Windows 3.x Enhanced mode? What if the machine is already running an expanded memory (EMS) or extended memory (XMS) manager? What if there are VDISKs or a SMARTDrive? What if your protected mode program has been spawned from within a 386|DOS-Extender program such as IBM Interleaf Publisher, Mathematica, or AutoCAD/386? 286|DOS-Extender Lite handles all these situations gracefully. It is compatible with all the PC industry standards for protected mode and extended memory. In particular, it supports the Virtual Control Program Interface (VCPI) and DOS Protected Mode Interface (DPMI). VCPI is a specification developed jointly by Quarterdeck Office Systems and Phar Lap Software that allows EMS emulators and DOS extenders to coexist; it is an extension to EMS 4.0. DPMI is a specification whose primary goal is compatibility between DOS extenders and DOS multitasking environments; DPMI was jointly developed by a committee including Microsoft, Intel, IBM, Phar Lap, Quarterdeck, Borland, Lotus, and other companies. For more details on VCPI and DPMI, plus the old INT 15h and XMS standards, we recommend the book Extending DOS, Second Edition, edited by Ray Duncan (Reading MA: Addison-Wesley, 1991, 538 pp., ISBN 0-201-56798-9). To summarize, programs developed with 286|DOS-Extender Lite can run in a wide variety of environments. LITE286 takes care of all the messy details of compatibility. There is no separate configuration or "tune" program to run. -------------------- LITE286 Requirements -------------------- LITE286 does have a few requirements, however: If an expanded memory (EMS) handler is installed, it must follow the EMS 4.0 and VCPI specifications. Almost all EMS managers shipping today are VCPI-compatible; if yours isn't, contact the manufacturer about upgrading to a new version. (The exception is IBM PC-DOS 4.01, which has an EMS manager that is not VCPI- compatible.) Microsoft's EMM386, included with DOS 5.0 and Windows 3.x, is VCPI-compatible, and can therefore be used with 286|DOS-Extender Lite. However, the EMM386 NOEMS switch effectively disables VCPI support, and therefore cannot be used. If an extended memory (XMS) manager such as HIMEM.SYS is installed, we recommend setting a fairly large handle count. For example: DEVICE=C:\WIN30\HIMEM.SYS /NUMHANDLES=127 LITE286 will not run in the DOS compatibility box of OS/2 1.x, because that environment is limited to a maximum of 640K. However, it will run in the DOS compatibility boxes of OS/2 2.0, which provide DPMI support. One important word of warning: Even though you don't have to explicitly type "LITE286" to run an executable produced by BCC286 under MS-DOS, the LITE286.EXE file is necessary. The directory containing both this file and DOSCALLS.DLL (for example C:\LITE286\BIN) must be located somewhere on the DOS file-search path. If GORUN286 cannot find LITE286.EXE, it will display the message: This program requires Phar Lap's 286|DOS-Extender If LITE286.EXE cannot find DOSCALLS.DLL (which should be located in the same directory as LITE286.EXE), it will display the message: Fatal error 286.2190: Load program failed -- File not found -- DOSCALLS.DLL. If you receive either of these messages when trying to run an executable produced by BCC286, ensure that your path is correct. For example: C:\TEST>set path=c:\bin;c:\borlandc\bin;c:\LITE286\bin;c:\dos Note that neither LITE286.EXE nor the 286|DOS-Extender Lite DLLs can be shipped to end-users. In order to prepare programs for redistribution, you must purchase the 286|DOS-Extender Run Time Kit (RTK), which lets you bind 286|DOS-Extender plus any necessary DLLs into your application (an application may consist of multiple executable files, all of which are covered by a single license agreement). With these details out of the way, protected mode programs will run under MS-DOS. -------------- Error Messages -------------- The most common fatal error messages are described briefly in the following sample sessions. C:\TEST>LITE286 phoobar Fatal error 286.2190: Load program failed -- File not found -- phoobar.exe. There is no program named PHOOBAR.EXE. Either you have misspelled the program's name, or it is not located on the path. C:\DOS>LITE286 bad Fatal error 286.3330: General protection fault detected. PID=0001 TID=0001 SID=0001 ERRORCODE=0000 AX=0004 BX=0000 CX=0019 DX=008B SI=00DA DI=00DA BP=0BE2 CS:IP=0237:001D DS=024F ES=0000 SS:SP=024F:0BDE FLAGS=3246 Your program violated a rule of protected mode, causing a General protection fault (GP fault). There is a bug in your program, or a piece of code which must be modified before it can be run in protected mode, or you have unintentionally included real mode code (for example, real mode libraries) in the program. C:\DOS>LITE286 mem Fatal error 286.1000: System does not have an 80286 (or newer) processor. You have attempted to run a 286|DOS-Extender Lite program on a machine which does not have an 80286, 80386, or 80486 processor. C:\DOS>LITE286 mem Fatal error 286.1020: This program requires VCPI or DPMI in V86 mode. A program, probably an expanded-memory manager, has put the computer into virtual 8086 mode, but the program does not support either the Virtual Control Program Interface (VCPI) or the DOS Protected Mode Interface (DPMI). Contact the manufacturer about upgrading to a later version which does support VCPI or DPMI, or remove the program. Some of the expanded memory simulators with which LITE286 works are: QEMM 4.1 or later (Quarterdeck) 386MAX 4.02 or later (Qualitas) CEMM 4.02 or later (COMPAQ) EMM386 (DOS 5.0, Microsoft Windows 3.x versions) ---------------------------- LITE286 Command Line Options ---------------------------- What if you want to run your 286|DOS-Extender Lite program on hardware that is not 100% IBM-compatible? What if you need to reserve a certain amount of extended memory because some other program doesn't adhere to any of the PC industry's standards for extended memory usage? What if your program does a large amount of file I/O and you want LITE286 to use a larger conventional-memory "transfer buffer" for DOS and BIOS calls? LITE286 has a number of command line options which can be used in (frankly, rather rare) situations such as these. If you type LITE286 -help on the DOS command line, a list of these command line options is displayed (the following display is not complete): C:\DOS>LITE286 -help 286|DOS-Extender Lite: 2.5 -- Copyright (C) 1986-92 Phar Lap Software, Inc. LITE286 switch(es) filename -EXTLIMIT n Set max. bytes of extended memory used -EXTLOW addr Set lowest extended memory address used -EXTHIGH addr Set highest extended memory address used -ISTKSIZE n Set size of interrupt stacks (1K blocks) -LDTSIZE n Set number of LDT entries -NISTACK n Set number of interrupt stacks -REALIMIT n Set max. bytes of real memory used -SWITCH name Select mode switch method (AUTO, AT, 386, SURESWITCH, PS2, INBOARD, 6300, ACER, VECTRA, VCPI, or FAST) -SWITCHFILE name Select external switching .BIN file -XFERSIZE n Set size of transfer buffer (1K blocks) Any LITE286 switch can be set on the DOS command line. For example, the following runs MYPROG.EXE with a transfer buffer of 16 KB: C:\TEST>LITE286 -xfersize 16 myprog However, since normally we don't bother typing "LITE286" to run a program produced by BCC286, we need another way to set LITE286 command-line options. For example, the following is equivalent to the LITE286 command line just shown: C:\TEST>set RUN286=-xfersize 16 C:\TEST>myprog Alternatively, if MYPROG should always be run with a LITE286 switch such as -XFERSIZE 16, then the switch can be placed directly inside MYPROG.EXE, using the CFIG286 utility: C:\TEST>cfig286 myprog.exe -xfersize 16 C:\TEST>myprog Note that the RUN286 environment variable affects all 286|DOS- Extender Lite programs. If you have several protected mode executables each requiring different LITE286 switches, you will probably want to use application-specific environment variables. For example, if PHOO.EXE uses the LITE286 -XFERSIZE 16 switch, but BAR.EXE requires -XFERSIZE 32, you could place these switches in separate PHOO and BAR environment variables. LITE286 will use whatever environment variable is specified in an %envvar switch: C:\TEST>cfig286 myprog.exe %myprog C:\TEST>set myprog=-xfersize 16 C:\TEST>myprog or, using the examples of PHOO and BAR: C:\TEST>cfig286 phoo.exe %phoo C:\TEST>cfig286 bar.exe %bar C:\TEST>set phoo=-xfersize 16 C:\TEST>set bar=-xfersize 32 C:\TEST>phoo C:\TEST>bar Of course, you must have sufficient room in your DOS environment. If you receive an "Out of environment space" message, you need a larger DOS environment. Add a line such as the following to your CONFIG.SYS file, and reboot: SHELL=c:\dos\command.com /p /e:512 Note that only LITE286 switches are processed in the LITE286 or application-specific DOS extender environment variables, or in the "configuration block" in an executable. Any command line switches specific to your program must be handled by your program in the usual way. -------------------------------------------------- The Phar Lap Application Program Interface (PHAPI) -------------------------------------------------- The full-blown 286|DOS-Extender SDK comes with extensive support for the Phar Lap Application Program Interface (PHAPI), which provides protected-mode DOS programs with a set of services in the following areas: Creating and changing protected-mode selectors Communication between real and protected mode Dynamic Link Library (DLL) support Interrupt and exception handling DOS memory management 80386 paging functions The following functions are part of PHAPI; prototypes for these functions appear in PHAPI.H: Selector and Memory Management ------------------------------ DosAllocHuge Allocate huge (> 64k) segment DosAllocRealSeg Allocate segment in conventional memory DosAllocSeg Allocate segment DosCreateCSAlias Create code alias to a data segment DosCreateDSAlias Create data alias to a code segment DosFreeSeg Free segment DosGetBIOSSeg Get selector to the BIOS data area DosGetHugeShift Get selector increment for huge segments DosGetPhysAddr Convert selector:offset to physical address DosGetSegDesc Get segment descriptor DosLockSegPages Lock pages of a segment DosMapLinSeg Map linear address DosMapRealSeg Map real mode address into protected mode DosMapPhysSeg Map physical address DosMemAvail Get amount of available extended memory DosRealAvail Get amount of available conventional memory DosReallocHuge Resize a huge segment DosReallocSeg Resize a segment DosSetSegAttrib Set access rights of a segment DosUnlockSegPages Unlock pages of a segment DosVerifyAccess Verify segment for read, write, execute Interrupts and Exceptions ------------------------- DosChainToProtIntr Chain to a protected-mode interrupt handler DosChainToRealIntr Chain to a real-mode interrupt handler DosGetExceptionHandler Get exception (e.g., GP fault) handler DosGetProtVec Get protected-mode interrupt vector DosGetRealProtVec Get real- and protected-mode interrupt vector DosGetRealVec Get real-mode interrupt vector DosIsProtIntr Test if interrupt is from protected mode DosIsRealIntr Test if interrupt is from real mode DosProtIntr Generate a protected-mode interrupt from real mode DosRealIntr Generate a real-mode interrupt from protected mode DosSetExceptionHandler Set exception handler DosSetPassToProtVec Set interrupt vector to go to protected-mode handler DosSetPassToRealVec Set interrupt vector to go to real-mode handler DosSetProtVec Set protected-mode interrupt vector DosSetRealProtVec Set real- and protected-mode interrupt vectors DosSetRealVec Set real-mode interrupt vector DosVProtIntr Generate a protected-mode interrupt from real mode DosVRealIntr Generate a real-mode interrupt from protected mode Mixing Real- and Protected-Mode Code ------------------------------------ DosFreeProtStack Free a protected-mode stack DosFreeRealStack Free a real-mode stack DosProtFarCall Call a protected-mode function from real mode DosProtFarJump Jump to protected mode from real mode DosProtToReal Convert a protected- to a real-mode address DosRealFarCall Call a real-mode function from protected mode DosRealFarJump Jump to real mode from protected mode DosRealToProt Convert a real- to a protected-mode address DosVProtFarCall Call a protected-mode function from real mode DosVProtFarJump Jump to protected mode from real mode DosVRealFarCall Call a real-mode function from protected mode DosVRealFarJump Jump to real mode from protected mode Dynamic Linking --------------- DosEnumMod Enumerate the currently-loaded modules DosEnumProc Enumerate the functions in a DLL DosFreeModule Free a DLL DosGetModHandle Get the module handle of a DLL DosGetModName Get the filename of a DLL DosGetProcAddr Get the selector:offset of a function in a DLL DosGetRealProcAddr Get the real-mode address of a function in a DLL DosLoadModule Load a DLL DosSetProcAddr Set the address of a function in a DLL Miscellaneous ------------- DosExecPgm Start a new protected- or real-mode process DosExit Exit from a program DosExitList Register an exit routine DosGetMachineMode Get processor mode DosIsPharLap Test if running under 286|DOS-Extender DosPTrace Debug a child program ---------------- Chapter 4 Run-Time Library ---------------- Keep in mind the following points when using the Borland C++ run-time library in protected mode: The farmalloc() call in protected-mode is not the same as large- model malloc(). farmalloc() takes an unsigned long parameter, and can be used to allocate huge (> 64 KB segments); consequently, it has additional overhead not present when using plain malloc(). Only use farmalloc() if you really want to allocate huge segments. The biosdisk() function is not supported, because 286|DOS-Extender Lite does not support INT 13h (BIOS disk services) in protected mode. The setvect() function is not supported. setvect() is equivalent to an INT 21h AH=25h (Set Interrupt Vector). While INT 21h AH=25h is fully supported under 286|DOS-Extender Lite, it is almost never what one would want in a protected mode program. All the most- common interrupts, such as Ctrl-C, Ctrl-Break, and Critical Error, require that real mode interrupts be passed on to protected mode. This functionality is provided by the DosSetPassToProtVec() function, available only with the full-fledged 286|DOS-Extender SDK. --------------- Further Reading --------------- Developers using 286|DOS-Extender Lite may be interested in reading the second edition of the book Extending DOS, edited by Ray Duncan. Chapter 4, on 16-bit protected-mode DOS extenders, contains over 70 pages devoted largely to 286|DOS-Extender, including an extensive discussion of how to use Borland C++ with 286|DOS-Extender: Ray Duncan et al., Extending DOS: A Programmer's Guide to Protected- Mode DOS, Second Edition, Reading MA: Addison-Wesley, 1991, 538 pp., ISBN 0-201-56798-9. Other chapters describe 32-bit protected-mode DOS extenders, the VCPI and DPMI specifications, and other topics in protected-mode DOS programming. ---------- Trademarks ---------- 286|DOS-Extender(TM), 286|DOS-Extender Lite(TM) and 386|DOS-Extender(TM) are trademarks, and Phar Lap(R) is a registered trademark of Phar Lap Software, Inc. 386MAX(TM) is a trademark of Qualitas, Inc. AutoCAD(R) is a registered trademark of Autodesk, Inc. TASM(TM) is a trademark, and Borland(R) and Turbo Debugger(R) are registered trademarks of Borland International, Inc. COMPAQ(R) is a registered trademark of Compaq Computer Corporation. DESQview(TM) and QEMM(TM) are trademarks, and DESQ(R) is a registered trademark of Quarterdeck Office Systems. PC/XT(TM) is a trademark, and IBM(R), AT(R), PS/2(R), and OS/2(R) are registered trademarks of International Business Machines Corporation. 287(TM), 386(TM), 387(TM), 486(TM), and i486(TM) are trademarks, and Intel(R) is a registered trademark of Intel Corporation. Interleaf Publisher(R) is a registered trademark of Interleaf, Inc. Lotus(R) is a registered trademark of Lotus Development Corporation. Mathematica(TM) is a trademark of Wolfram Research Inc. Windows(TM) is a trademark, and Microsoft(R), MS(R), MS-DOS(R), and CodeView(R) are registered trademarks of Microsoft Corporation.