guide.gml

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

.chap Using the flat memory model
.np
.ix 'flat model'
Flat model is a non-segmented memory model that allows accessing data
and executing code anywhere within the 4GB linear address region via a
32-bit offset without the need to use segment registers to point to the
memory.  In many respects, the memory model is identical to the tiny
memory model well-known to DOS C and assembly language programmers, but
supporting a memory region of 4GB rather than 64KB.
.np
.ix 'DPMI host'
When using flat model, all linear addresses directly map to the physical
address specified when an application is running in pure DOS environment.
For example, writing to memory location 0B8000h will
address video memory.  Reading from memory locations in the 0FFF00h
range will access ROM code. Under DPMI there is usually no direct
relationship between linear and physical addresses, the DPMI host will
however emulate access to memory below 1MB as appropriate without
requiring any special considerations on the part of the application writer.
.np
.ix 'near model'
Generally speaking, flat is an improved version of the older near memory
model supported in previous versions of CauseWay.  Unlike near, flat model
supports multiple segments, mixing 16- and 32-bit segments, and direct
linear memory addresses without translation. Flat model
supports all near memory model code without translation, including
automatic handling of near-specific API functions.
.*
.chap Using DLLs with &product. C/C++
.*
.np
.ix 'DLL'
It is recommended that you understand and familiarize yourself with the
basic operation of DLLs (Dynamic Link Libraries) under Windows or OS/2 
before using them with CauseWay under DOS. No attempt is made here to 
explain the fundamentals of DLL architecture and operation.
You should also study the provided DLL example code.
.np
DLL code should be compiled with the &sw.s option to disable stack checking
and the &sw.bd option to generate DLL-suitable code.  Specify a system
type of 
.mono CWDLLR 
for register-based parameter passing or 
.mono CWDLLS
for stack-based parameter passing.
.np
A DLL file is a standard EXE file with the following requirement:  The
program start address should be an initialization and termination
function, rather than a main program entry point.  The entry address
will be called twice:  Once after loading to allow the DLL to perform
initialization and once just prior to the DLL being unloaded from memory
to allow it to clean up for termination.  Entry conditions are: register
EAX=0 for initialization and register EAX=1 for termination.  An
initialization code return value of EAX=0 indicates no errors.  A code
of any other value indicates an error has occurred and loading should be
terminated.  If an error condition is returned, it is up to the DLL to
display an error message, CauseWay will simply report a load error.  The
entry address is a FAR call, so the initialization code should use a
RETF to return control to the calling program.
.np
A minimal DLL startup system is provided in the 
.fi DLLSTRTR.OBJ
(register-based) and the 
.fi DLLSTRTS.OBJ
(stack-based) files. 
.np
CauseWay loads DLLs when the program being loaded has references to
external modules in the DLL.  CauseWay searches the execution path for
any DLL or EXE file (in that order) which has the proper internal module
name.  The module name is not used when searching.  For example, a file
named 
.mono USEME.DLL
contains a module named Spelling_Checker.  The name of
the module (Spelling_Checker) is set by the NAME option in your link
file.  If no NAME is specified, then the module's name will default to
its file name without an extension.  In this example, the module name
would become USEME if no NAME is specified.
.np
Following is an overview of the standard link file commands used to
create DLLs. You may also refer to the &product. Linker documentation for a
description of these commands.
.mbigbox
EXPORT function_name
.embigbox
.synote
.mnote function_name
allows you to make a symbol (function name) available to
other modules.  It must be declared as a public symbol so that the
linker can export it.
.esynote
.np
.mbigbox
IMPORT [local_name] module_name.function_name

IMPORT [local_name] module_name.ordinal
.embigbox
.synote
.mnote local_name
is an optional parameter.  It is the symbol which the
importing program references the function by, i.e. the symbol declared
as external.  If no local name is specified, then 
.sy function_name 
is used.
.np
.mnote module_name 
is the name of the module that contains the function.  It
is not the file name.  IMPORT module names are resolved by searching DLL
and EXE files for the correct module name.
.np
.mnote function_name
is the symbol by which the function is known in the
EXPORTing module, i.e. the symbol that is declared as public.
.np
.mnote ordinal_number
functions can also be imported by number.  This is the
entry number in decimal, starting at 1, in the EXPORTing module's export
table to link to.
.sy local_name 
must be specified when using ordinals,
otherwise there is no symbolic reference to internally resolve.
.np
In the DLL calling code, 
.sy local_name
and
.sy function_name 
need to be declared as external.
.esynote
.*
.mbigbox
NAME   module_name
.embigbox
.synote
.mnote module_name
is a symbol by which the module should be identified when
resolving IMPORT records in a calling program.
.np
IMPORTed module names can contain a partial path.  For example,
DLL\spelling_checker would instruct the loader to look in <execution
path>\DLL for a module with a name of spelling_checker.
.np
Notes: 
.np
You must take the responsibility to make sure that the IMPORTed function
or module calling conventions match the calling code.  For example, the
loader will load a 16-bit module to resolve an IMPORT in a 32-bit
program without complaint.  In this case, if the IMPORTing program does
a 16-bit far call, then everything will work correctly, but a 32-bit
call will fail unless the 16-bit DLL module ends with a 32-bit RET
instruction.
.np
Importing by function name may slow program performance if the symbols are
frequently referenced.  In such cases, consider using the ordinal
command to speed up the access times because module name references are
automatically converted to ordinals in an internal list which will only
be processed once at load time.
.esynote
.*
.*
.chap Performance Considerations
.*
.np
There are a few ways to increase the operational efficiency of your
CauseWay applications.
.*
.section Memory Size
.*
.np
Almost without exception, the best way to increase runtime performance
of all CauseWay applications is to ensure that physical memory is large
enough to meet all of the program's needs.  Performance suffers considerably
when CauseWay creates a temporary file for virtual memory, swapping 4KB 
blocks of the program's code and data to and from disk.  Naturally this may 
not be possible in all cases, but it is a worthy goal.  Generally the more
physical memory, even when virtual memory is being used, the better an
application's performance.
.np
When using a disk cache program, be sure not to use too much extended
memory.  Although a disk cache program is beneficial, allocating it too
much memory can deprive CauseWay of required extended memory and can
degrade application performance. However completely disabling disk cache
will usually noticeably decrease performance as well. The optimal cache size 
depends on the particular application and computer system (amount of physical 
memory, disk I/O speed etc.) and there are no generally
applicable "best" settings.
.np
.ix 'virtual memory'
If your program uses virtual memory, CauseWay's VMM creates a temporary
swap file.  If you have more than one disk drive, then you may wish to
direct creation of the swap file to the faster disk drive on your system
using the 
.ev CAUSEWAY=SWAP
,
.ev TEMP
or 
.ev TMP
environment variables.  Do not
create a RAM disk if this will lower your physical memory because this
is less efficient than allowing CauseWay to use physical memory itself.
.np
Remember that virtual memory is part of total memory when using
CauseWay. If your default drive, or the drive pointed to by the 
.ev TEMP
or
.ev TMP
environment variables has little free space, this will be reflected
in total memory available to the CauseWay application.  If disk free
space is less than physical memory, then CauseWay shuts off all use of
virtual memory.  Windows and OS/2 handle virtual memory internally and
supply it through the swap file and DPMI settings for the application.
.*
.section &product. C/C++ kbhit() replacement
.*
.np
.ix 'kbhit()'
Two optimized replacement versions of the &product. C++ runtime library
kbhit() function are provided. The
files are KBHITR.OBJ and KBHITS.OBJ for, respectively, register-based
and stack-based calling conventions.  Simply link in the kbhit()
replacement file appropriate for your compile options.  These
replacement routines bypass the normal INT checking of the keyboard and
directly inspect the keyboard buffer to see if a keypress is pending.
These routines significantly reduce the overhead in tight processing
loops, which perform many kbhit()'s per second, by avoiding the
interrupt call associated with checking for keystrokes.
.np
Be aware that linking in the kbhitr or kbhits module means that the INT
28h idle call will not be made on kbhit() as normally occurs with the
standard runtime library kbhit().  This may impact background processing
in applications which depend on INT 28h idle calls, such as the DOS
PRINT utility which performs printing in the background, as well as 
operation under multitatsking environments.
.*
.section DOS API Buffer Size
.*
.np
If your CauseWay application reads and writes files using large amounts
of data on one read or write pass, you may wish to consider increasing
the size of the internal DOS memory transfer buffer used by CauseWay.
Refer to the SetDOSTrans and GetDOSTrans functions in the CauseWay API
chapter for more information.
.np
Note that the internal 8KB buffer is optimized for file transfers.
Average file transfers of greater than 8KB will not necessarily improve
performance with an increase in the buffer size.  Generally speaking,
the average file transfer must be 32KB or larger to gain any efficiency
with an increased buffer size. Also, if you are using virtual memory,
increasing the buffer size may actually slow down performance due to the
decreased available physical memory.  Test your application with both
the default buffer and the desired new buffer size before permanently
increasing the buffer size beyond the default.
.*
.section API Memory Allocation
.*
.np
Inveterate tweakers may try out the SetMCBMax and GetMCBSize functions
in the CauseWay API.  These functions allow fine-tuning of the threshold
used by CauseWay to allocate memory via a memory pool using memory
control blocks (MCBs) rather than via normal DPMI functions.  Since DPMI
allocates memory in multiples of 4KB, setting the MCB threshold too low
may result in a good deal of wasted memory and subsequent performance
degradation.
.*
.*
.chap Rules For Protected Mode Operation
.*
.np
The following information covers additional restrictions for protected
mode compatible code that are not present when writing real mode
compatible code.
.np
Using protected mode rather than real mode requires following a few new
programming rules to prevent processor faults from being generated,
terminating the CauseWay application.  These processor faults occur when
an application breaks a protected mode programming rule.
.np
Use the following rules for programming in protected mode:
.autonote
.note
A selector value (referred to as a segment value in real mode)
loaded into a segment register references an area of memory that may
occur anywhere within the machine's physical address space. The
operating system can dynamically move this area of memory.  Therefore,
when dealing with selector values:
.begbull
.bull
Never use segment registers as general purpose registers
that can be loaded with arbitrary values.  Every time a segment register
is loaded with a value the processor checks the validity of the selector
value and generates a fault if it is invalid.
.bull
Never perform segment arithmetic on a selector value.
Segment arithmetic is usually performed in real mode code to either
normalize a pointer, access a new paragraph of memory without changing
an offset, or to access a single area of memory that is greater than 64KB
in size. Since a selector value is an index into a table which contains
the actual memory addresses, addition or subtraction of different
selector values is meaningless and gives no useful results.  (There
exist special cases where contiguous selector values can be added or