ClipXMS version 1.10 (demo version)
===================================


Introduction
------------

Thank you for your interest in ClipXMS, the XMS/EMS memory solution for
Clipper 5!  This file contains all the information you need (and more) to
use the demo version of ClipXMS.

ClipXMS allows real-mode Clipper applications to use XMS (extended) memory,
freeing Clipper from its total dependence on EMS (expanded) memory.  Just
link ClipXMS into your application and end your worries about your user's
computer configuration.  Every memory manager configuration is compatible
with Clipper when using ClipXMS.


Demo Installation
-----------------

All of the functionality of ClipXMS is contained within the CLIPXMS1.OBJ
and CLIPXMS2.OBJ files.  By linking in these .OBJ files, your Clipper 5
program will be able to use XMS as well as EMS memory.  Your program will
also be able to use the ClipXMS() function documented later in this manual.

1. Simply copy the CLIPXMS1.OBJ and CLIPXMS2.OBJ files to a directory on
your hard disk where your linker can find the files at link time.

2. You may also want to copy the other files to a CLIPXMS directory on
your hard disk, but none of the other files are necessary for the operation
of ClipXMS.

That's all that is necessary to install ClipXMS.


Linking
-------

ClipXMS is compatible with Clipper 5.01 and Clipper 5.20.  Just add the
CLIPXMS1.OBJ and CLIPXMS2.OBJ files to your link script.  If you are using
a dynamic overlay linker such as Blinker, the CLIPXMS1.OBJ file must be
linked into the root, but the CLIPXMS2.OBJ file can be overlaid.

The CLIPXMS .OBJ files replace modules found in CLIPPER.LIB.  Therefore, it
is a good idea to list the CLIPXMS .OBJ files near the beginning of your
link script to make sure the linker links them in instead of the modules
they replace in CLIPPER.LIB.

Using RTLink:  RTLINK FILE Main, ClipXMS1, ClipXMS2

An example Blinker link script:

   FILE Main
   FILE ClipXMS1  <-- Non-overlayable ClipXMS .OBJ file
   BEGINAREA
      FILE ClipXMS2  <-- Overlayable ClipXMS .OBJ file
      LIB EXTEND
   ENDAREA

If you are using Clipper 5.01, you might be linking in a file called
EMM501.OBJ which fixes a bug in Clipper 5.01's expanded memory manager.  If
your link script is linking in EMM501.OBJ, then please take it out of your
link script (or comment it out).  ClipXMS fixes the same problem that
EMM501.OBJ fixes and therefore they clash with each other.


More Information on Linking with Blinker
----------------------------------------

If you are using Blinker, you can easily make two mistakes when linking in
ClipXMS.

1) DO NOT list CLIPXMS1.OBJ or CLIPXMS2.OBJ as the first files in your link
script -- this confuses Blinker.  A Clipper compiled .OBJ file should
always be your first file listed in your link script.

2) DO NOT put CLIPXMS1.OBJ in an overlay area, that is, do not list it
between a pair of BEGINAREA/ENDAREA statements in your link script.

Another example Blinker link script:

   BEGINAREA
      FILE Main
      FILE Func1
      FILE Func2
      FILE ClipXMS2  <-- Overlayable ClipXMS .OBJ file
      LIB EXTEND
   ENDAREA
   FILE ClipXMS1  <-- Non-overlayable ClipXMS .OBJ file
   LIB CLIPPER


Internal Errors
---------------

If your Clipper application reports an internal error between 8100 to 8110,
the internal error is due to an internal problem within ClipXMS.  If you
ever get any of these internal errors, please report them to Martin
Technologies immediately.


The 'E' Environment Setting
---------------------------

Under normal Clipper, the 'E' CLIPPER environment setting limits the amount
of EMS memory the Clipper program will allocate at startup.  When you link
in ClipXMS, the 'E' CLIPPER environment setting will limit both EMS and XMS
memory usage.

Example to limit EMS and XMS memory usage to 1024K:
   SET CLIPPER=E:1024


The 'NOEMS' and 'NOXMS' Environment Settings
--------------------------------------------

When you link in ClipXMS, two CLIPPER environment variable settings are
added to your program, 'NOEMS' and 'NOXMS'.  When you specify either of
these settings, ClipXMS will behave as if that memory is not available.
For example, if you specify 'NOEMS', ClipXMS will look only for XMS memory.
If you specify 'NOXMS', ClipXMS will look only for EMS memory.  If you
specify both, ClipXMS will ignore any available EMS and XMS memory causing
Clipper's VM system to swap memory to disk even if EMS or XMS memory is
available.

Example to set files to 99 and disable EMS usage:
   SET CLIPPER=F:99;NOEMS

The only use for these settings is for testing purposes and debugging
purposes if you suspect a problem with the user's EMS or XMS drivers.
Please note that these settings affect the ClipXMS() function.


The ClipXMS() Function
----------------------

ClipXMS includes a function named ClipXMS() that you can call from your
Clipper program.  The ClipXMS() function is modeled somewhat after
Clipper's MEMORY() function.  It takes one numeric parameter indicating
the information requested and returns the information as a numeric.

ClipXMS(1) returns the ClipXMS version number with two implied decimal
points.  Example: version 1.10 returns "110".

ClipXMS(2) returns your ClipXMS serial number.

ClipXMS(3) returns the amount of EMS memory detected at program startup.
The NOEMS switch causes this function to return 0.

ClipXMS(4) returns the amount of XMS memory detected at program startup.
The NOXMS switch causes this function to return 0.

ClipXMS(5) returns 0-3 indicating whether this Clipper application is using
EMS memory [1], XMS memory [2], running in protected mode [3], or not using
any extended memory at all [0].

ClipXMS(6) returns a number greater than 0 if the computer has available
extended memory, but the computer's CONFIG.SYS did not load an XMS or EMS
memory manager.  This number indicates the number of kilobytes (K) of
available unmanaged extended memory.  You can use this function to inform
the user at startup how the Clipper program's performance can be improved
by loading a memory manager.  Please see the example code on the diskette.


XMS and EMS Memory
------------------

All IBM compatible computers except those using the original 8088
microprocessor can have expanded or extended memory.  Clipper 5 is limited
to using only expanded memory, therefore, if a computer is not properly
configured it may have megabytes of extended memory that are not usable by
your Clipper applications.  The result can be very slow program operation
especially in larger applications.

When you link in ClipXMS, as long as the computer's CONFIG.SYS loads a
memory manager such as HIMEM.SYS, QEMM, or 386MAX, your Clipper application
can use any available extended or expanded memory.  If no memory manager is
present, ClipXMS will not be able to use any available extended memory.  In
that case, ClipXMS does include the ClipXMS() function which allows your
program to alert the user if they have extended memory available, but have
not installed a memory manager.  For more information see the documentation
for the ClipXMS() function.

An important side effect of using ClipXMS is that your users no longer have
to configure their computers for EMS (expanded) memory.  This frees up 64K
of high memory allowing your users to load more device drivers and TSRs
into high memory with the LOADHIGH command.


More About XMS and EMS Memory
-----------------------------

ClipXMS will make use of either XMS or EMS memory; ClipXMS cannot use both
types of memory at the same time.  Therefore, when a Clipper program using
ClipXMS is executed on a computer that has both XMS and EMS memory
available, ClipXMS will decide which type to use based on which has the
most memory available.  In truth, ClipXMS will lean slightly towards using
EMS memory because EMS memory is slightly faster than XMS memory on most
computers.

Whether ClipXMS uses XMS or EMS memory doesn't matter on most computers
anyway because most memory managers will "share" XMS and EMS memory by
mapping the exact same extended memory as both XMS and EMS memory,
therefore, allocating one type of memory will also decrease the amount of
free memory of the other type.

A few memory managers such as DOS 5's HIMEM.SYS and EMM386.EXE will carve
out a chunk of XMS memory to use exclusively as EMS memory.  In those
cases, your user might be better off getting rid of EMS memory completely
and leaving it all as XMS memory.  That way, there will be more XMS memory
available that ClipXMS and other applications can use.  If your users are
using DOS 6, QEMM, 386Max, BlueMax, or most of the other commercial memory
managers, you needn't be concerned because they always share XMS and EMS
memory.


Protected and Dual Mode
-----------------------

ClipXMS is compatible with ExoSpace and Blinker 3's protected mode, but
ClipXMS does not benefit protected mode programs because protected mode
programs are able to use extended memory directly by themselves.  If you do
link ClipXMS into a protected mode program, your program will run exactly
as it did without ClipXMS.

Compatibility with protected mode is important if you are using Blinker 3's
dual mode.  When you link ClipXMS into a Blinker 3 dual mode program,
ClipXMS will not interfere when the program runs in protected mode, but
ClipXMS will kick in when the program runs in real mode allowing your real
mode program to use XMS memory directly.


Troubleshooting
---------------

Q.  When I run my application linked with ClipXMS, the program hangs,
reboots, or reports internal error 5320 or 5321.  Why?

A.  If you are using Blinker, you must link CLIPXMS1.OBJ into the root.
Make sure it is not within a BEGINAREA/ENDAREA pair.  Also make sure it is
listed near the beginning of your link script so the linker will link it in
instead of the Clipper modules it replaces.

Q.  When I link in ClipXMS the linker displays a "duplicate symbol"
warning.  Why?

A.  Some versions of Microsoft LINK and some other linkers may exhibit this
behavior.  If the program runs fine, this error can be ignored.  If the
program does not run properly, please call our technical support.  An
update to your linker may get rid of this error.

Q. When I link in ClipXMS (using Blinker), I get the following Blinker
error.  Why?

   BLINKER : 1116 : fixup overflow at offset 006BH in segment _TEXT

A. You have not linked ClipXMS in properly.  You have listed one or both of
the ClipXMS .OBJ files as the first file in your link script.  You MUST
list a Clipper compiled .OBJ file as your first .OBJ file.

