READ.ME  --  Loading Overlays in XMS

Files
-----

Apart from this notice, the following files should be present in this
archive:

OVERXMS.ASM           Source code of XMS overlay support.
OVERXMS.OBJ           Object code of XMS overlay support.
OVERXMS.PAS           Declares OvrInitXMS.

Purpose
-------

This package is for users of Turbo Pascal, version 5.0 or later.
These three files are all you need to add XMS support to overlaying.
If you think you can use it, then I probably don't have to explain
what the benefits are of using XMS memory over EMS memory - or
emulations thereof.  But I will anyway:

-  XMS is found on more machines than EMS.
-  All XMS is addressable as one physical unit, not in chunks of 16 kB
   like EMS.
-  XMS is faster.  How much faster, depends on the kind of system.
   It probably doesn't matter much on 386/486 systems, but the speedup
   is noticable on a 286 with emulated EMS.  Or if you have a typical
   1 MB 286 clone, configured as 640+384, without either board EMS or
   emulated EMS (served by e.g. Quarterdeck's QRAM memory manager),
   then thanks to OVERXMS you'll have fast loading overlays at last.

... and last but not least:
-  OVERXMS is compact.  It adds a mere 425 bytes of code to your .EXE
   file.

Using OVERXMS
-------------

Usage is straightforward.  Just change the "uses" clause, so that it
includes OVERXMS.  Next, spot the line wherein you initialise the
overlay manager.  Add two lines, so that it will run something like:

    OverInit(YourApplication);
    OvrInitXMS;
    If OvrResult <> OvrOk Then
      OvrInitEMS;

That's all.  First, we check whether we can load the overlay into XMS;
if we don't succeed, we resort to EMS allocation and suffer a slight
loss of performance; if no EMS is available, though luck -- continue
with overlays on disk.

Status codes
------------

Possible return codes from OverInitXMS are:
  OvrOk           (0)      ... success
  OvrIOError     (-4)      ... something went wrong whilst reading the