    Array in Expand Memory object For Turbo Pascal 6.0  (Ver. 1.0)

                    Written by Jialong He

                         15-Oct-92

This program allows you to define any array in the Expand Memory and access
the array directly. It is a by-product when I worked on my Ph.D project.
You may freely distribute it or use it for any purpose, provided this notice
is attached with it. I would be very happy if you intend to use it in your
program. Please let me know if you like it.

InterNet:
          jialong@neuro.informatik.uni-ulm.de

1. Introduction
   ------------
 DOS has a 640 Kb memory barrier. When there is a large amount of data,
 a programmer has to process data separately by reading only part of the data
 into memory each time. This makes programming very complicated and
 will degrade the program's performance. Now you can put your data into
 expanded memory by including this unit into your program. By defining an
 array in expanded memory, you can access each element directly similar to
 the way you define an array in the heap memory.

2. What is Expanded Memory?
   ----------------------
 Expanded memory is the memory beyond DOS's 640K-byte limit.  The LIM
 specification supports up to 32M bytes of expanded memory.  Because
 the 8086, 8088, and 80286 (in real mode) microprocessors can
 physically address only 1M byte of memory, they access expanded memory
 through a window in their physical address range.
 Expanded memory is divided into segments called logical pages.  These
 pages are typically 16K-bytes of memory.  Your computer accesses
 logical pages through a physical block of memory called a page frame.
 The page frame contains multiple physical pages, pages that the
 microprocessor can address directly.  Physical pages are also
 typically 16K bytes of memory.

 This page frame serves as a window into expanded memory.  Just as your
 computer screen is a window into a large spreadsheet, so the page
 frame is a window into expanded memory.

 A logical page of expanded memory can be mapped into (made to appear
 in) any one of the physical pages in the page frame.  Thus, a read or
 write to the physical page actually becomes a read or write to the
 associated logical page.  One logical page can be mapped into the page
 frame for each physical page. The page frame is located above 640K
 bytes.  Normally, only video adapters, network cards, and similar
 devices exist between 640K and 1024K.

3. How to use this EMS object in your program
   ------------------------------------------
     (1)  Include EMS unit in your program's USES statement.

     (2)  Define EMS arrays by using EMSArray in Var section similar
          to defining other variables.

           Var
               AnyArray : EMSArray;

     (3)  Determine if EMM is installed by calling the function:

               AnyArray.Ems_Installed

           if it returns TRUE, EMM is installed, otherwise EMM is absent,
           and you cannot put your data into EMS. Of course, if you define
           many EMS arrays, only a single check for the existence of EMM
           is necessary.

     (4)  Determine if there are enough expanded memory pages for your
          application by using the function:

              AnyArray.Pages_Available;

          it will return unallocated page numbers (16 kb block). You
          can only allocate memory less than or equal to this value.


     (5)  Allocate expanded memory pages using the procedure:

              AnyArray.Alloc(PageNum);

           "PageNum" is the numbers of page you need for the defined
           array. This is similar to getting memory from Heap by using
           New() procedure.

     (6) Map a logical pages into a physical page by using the procedure:

              AnyArray.MapIn(LogicalNum, PhysicalNum);

         There are usually 4 physical numbers, so "PhysicalNum" can be
         0, 1, 2, or 3. Suppose you allocate 10 pages (10 * 16 kb in
         size) using AnyArray.Alloc(10), the "LogicalNum" can be any
         value from 0 to 9. Remember, all pages are counted from 0.

       Note: If you intend to map more than one logical page into
          different physical pages, I suggest to map them in reverse
          sequence in order to access them continually.

            For example: map in 4 pages (64 kb)

              AnyArray.MapIn(4, 3);
              AnyArray.MapIn(3, 2);
              AnyArray.MapIn(2, 1);
              AnyArray.MapIn(1, 0);
          In this case, the array index 1 is the first element in
          logical page 1. (You can not access logical page 0 at
          the moment)

     (7)  Read/write the data in expanded memory, just as if it were
          conventional memory.

            For example:

             AnyArray.ByteArry^[ Index ] := 234;    { As Byte Array }
             AnyArray.IntArry^[ Index ]  := 12345;  { As Integer Array }
             AnyArray.RealArry^[ Index ] := 3.5;    { As Real Array }

     (8)  Release array memory when you do not need it any more by using
          procedure

              AnyArray.Release


  You may explore the example program EMSTEST.PAS to learn how to
  use EMS objects.

4. File list
   ---------

     README              { This file }
     EMS.PAS             { Source Code of EMS object }
     EMS.TPU             { Compiled version of EMS object }
     EMSTEST.PAS         { Example program of using EMS object }
     EMSTEST.EXE         { Executable file of EMSTEST.PAS }

