intro.gml

开放源码的编译器open watcom 1.6.0版的源代码

.*
.*
.chap Overview
.*
.*
.np
CauseWay is a 386 DOS extender package for use with &product. C/C++
programs.  It is provided as a stub executable for which can be easily 
linked into DOS extended applications.
.*
.section Introduction
.*
.np
Within the standard DOS, Windows and OS/2 DOS box environments,
CauseWay supports 32-bit memory models for applications on PC
compatibles with an 80386SX processor or above without the need to use
overlays or crude stopgap measures such as EMS/XMS swapping.  To do
this, the DOS extender runs applications in protected mode, rather than
the real mode normally used in the DOS environments.  CauseWay supports
both 16-bit and 32-bit protected mode applications operating under a DOS
environment.  It makes full use of 386-level chip capabilities
including demand paging of code and data, variable-sized segments up to
4GB in length, mixing 16- and 32-bit segments as well as support for flat
(non-segmented) memory addressing models.  The CauseWay implementation
of these powerful capabilities provides all their benefits while being
transparent to the application user.
.np
.ix 'VCPI'
.ix 'DPMI'
Applications created using CauseWay are compatible with the VCPI and
DPMI standards and run equally well on systems with no protected mode
drivers or programs. CauseWay applications work with such diverse
environments as normal DOS, DesqView, Windows 3.0 and above in both
standard and enhanced modes, as well as DOS windows within OS/2 2.0 and
above, Windows 95 and above and Windows NT and later. CauseWay allocates
memory from DPMI, VCPI, XMS, and INT 15H
services, in addition to conventional DOS memory.  This allows CauseWay
applications to allocate memory through the CauseWay DOS extender
without the need to detect or manipulate the various memory handling
schemes.
.np
A primary objective of CauseWay development was to ensure minimal effort
would be needed by programmers to adapt their code to work with the
CauseWay DOS e
tender.  As a result, most &product. C/C++ and many realmode
assembly language programs need no or minor changes to produce a fully
operational CauseWay protected mode application.
.*
.section Minimum System Requirements
.*
.np
CauseWay for &product C/C++ requires a 386SX based
computer or better.  The required operating environment is MS-DOS or
PC-DOS 3.3 or higher, Windows 3.0 or higher, OS/2 2.0 and above,
Windows 95 and above, Windows NT or higher or a
compatible operating system that provides a DPMI or VCPI DOS
environment.
.np
CauseWay is to a large extent compatible with Tenberry Software's DOS/4GW.
Most applications built for DOS/4GW will run with CauseWay without any 
changes.
.*
.section CauseWay Memory Requirements
.*
.np
The recommended minimum amount of total free physical memory for
CauseWay applications is 500KB total.  100-150KB of this memory must be
conventional DOS memory, the remainder may be extended memory.  CauseWay
applications can run in less memory, down to the 300KB range, provided
sufficient virtual (disk-based) memory is available, but application
performance will decline significantly.  More physical memory improves a
program's performance, reducing virtual memory disk access overhead.
.*
.section Operating CauseWay
.*
.np
When using CauseWay, simply follow the standard
edit-compile/assemble-link programming cycle familiar to C and assembly
language programmers.
.np
Users compiling with WCL386 need to add the switch &sw.l=CauseWay
to the command line.
.exam begin
WCL386 &sw.l=CauseWay myprog.c
.exam end
This switch can be automated by adding &sw.l#CauseWay to the 
.ev WCL386
environment variable, making CauseWay the default when compiling via WCL386.
.np
&product. users linking with WLINK should add the statement
.mono system CauseWay
to the link command.  
.exam begin
WLINK system CauseWay file myprog.obj
.exam end
.np
.ix 'conventional memory'
When running the DOS-extended application, DOS first loads the CauseWay
DOS extender in conventional memory.  CauseWay establishes the protected
mode environment, retrieves the application from the executable file &mdash
loading it first into extended memory, then conventional memory if
extended is exhausted, then virtual (disk-based) memory if conventional
is exhausted &mdash sets up the application for execution, and finally
passes control to the application to begin operation.  No additional
files are required to make your application run in 386 protected mode
using the CauseWay DOS extender.
.np
.fi CWSTUB.EXE
will execute stand-alone LE-format files in the same
way as 
.fi DOS4GW.EXE
does if the full file name, including extension, is
listed after CWSTUB, e.g. 
.mono CWSTUB RUNME.EXE. 
CWSTUB will override the extender bound to the application EXE, if any, 
with the CauseWay DOS extender version in 
.fi CWSTUB.EXE.
.*
.section Debugging Using WD
.*
.np
.ix 'WD'
To debug CauseWay programs with the &product. debugger after installing the
CauseWay files, simply use the &sw.tr=cw command line option.
.exam begin
WD &sw.tr=cw myprog
.exam end
This process can be automated by adding 
.mono &sw.tr#cw 
to your 
.ev WD 
environment variable. Use the 
.mono set WD=tr#cw
command.
.np
By default, CauseWay uses a Ctrl-Alt keypress to interrupt the WD
debugger, rather than the Print-Screen key.  This can be changed to any
two, three, or four keypress value by modifying the ASCII file
.fi CWHELP.CFG 
at the BreakKeys line.  See comments in this file for
further detail.  Note that a single keypress value will not work properly.
.*
.section Operational Considerations When Using CauseWay
.*
.np
.ix 'virtual memory'
The 
.ev TEMP
, 
.ev TMP
and 
.ev CAUSEWAY=SWAP 
environment variables are used by
CauseWay to determine where to build its virtual memory swap file when
an application is not operating under Windows or OS/2 (Windows and OS/2
provide their own virtual memory management).  Since CauseWay has integrated
virtual memory, disk space is considered part of total memory.  If you
use the 
.ev TEMP
, 
.ev TMP
or 
.ev SWAP 
environment variable to point to a small RAM
sk or almost full disk, free memory will be affected accordingly.  If
virtual (disk-based) memory is less than physical (installed on machine)
memory, Cause Way turns off virtual memory. On the other hand, if you
have a disk 300MB free, CauseWay will have no problem reporting 300MB
free memory to your program, provided that virtual memory is not
inhibited or limited by the 
.ev CAUSEWAY
environment variable memory settings.
.np
Memory operates differently under Windows and OS/2. With OS/2, the DPMI
setting for the session determines available memory. With Windows,
available memory is the total of physical memory plus the swap file size
less any memory already in use by Windows or another Windows application.
.np
.ix 'swap file'
When creating a VMM swap file at application startup under DOS, CauseWay
builds a list of possible paths in order of priority. CauseWay then works
through the list until one of the entries provides both a valid drive
and path specification and sufficient free space to being operation. The
first entry to succeed becomes the swap file drive with no further
processing of the list. If CauseWay reaches the end of the list without
finding a valid drive, it disables the virtual memory manager. The order
of priority is 
.ev CAUSEWAY=SWAP
, 
.ev TEMP
, 
.ev TMP
and application execution path.
.np
If end users reboot the system or turn off power while executing a
CauseWay application under DOS, a temporary file will be left on the
system by CauseWay. This will usually be a zero length file unless the
application was large enough to exceed physical memory and CauseWay had
started using its virtual memory manager. The temporary file name is
requested using standard DOS functions, meaning the name will vary with
different versions of DOS. It typically is a mixture of letters and
numbers with no extension, although .$$$ extension may be presented when
operating under a network. Make sure you do not delete this temporary
file while the CauseWay application is still active, as improper or
erratic program operation, including lock-ups, may occur.
.np
Application startup times may increase significantly if the free
physical memory is less than the executable size. In such cases, not
only must the executable be loaded into physical memory, but a virtual
memory file of the executable file size must also be built. This file
holds the portions of the executable that do not fit into physical
memory and which have not been recently requested. After startup is
complete, the program will operate normally, paging to and from virtual
memory as necessary.
.np
CauseWay automatically sets aside 32KB of low DOS memory for allocation
and use by developer routines via the GetMemDOS API function. The 32K
memory block is available even if CauseWay needs to use virtual memory
just to load an application. The set-aside amount can be increased by
using the 
.ev CAUSEWAY 
environment variable LOWMEM option, although the
additional set-aside goal is not guaranteed to be reached if too little
conventional memory is left for CauseWay's operating requirements.
.*
.section Environment Variables
.*
.np
CauseWay can make use of three environment variables at runtime:
.ev TEMP
, 
.ev TMP
and 
.ev CAUSEWAY
.*
.beglevel
.*
.section TEMP and TMP Environment Variables
.np
The