LARGE, VIRTUAL AND HUGH ARRAYS Version 1.1
by Graham Robertson


The software enclosed has three parts.

1.  Large Arrays (Arrays up to the size memory allows)
Procedures are written in machine code to allow the use of large arrays in 
a C program. The array can be of any size as long as memory permits.

2.  Virtual Arrays and Hugh Arrays (Arrays up to the size of your DISK or 
    VDISK)
Procedures which include the code from part one but allow many large 
arrays to be accessed. If there is no space left then old arrays will 
cached to the disk or a virtual disk. Several virtual arrays can be used 
to create one hugh array of any size. This restricted version limits the 
number of virtual arrays to sixteen.

3.  Version 1.1 of this software also allows your extended memory to be 
    accessed directly for this system.

---------------------------------------------------------------------

This software is copyright British Software Licensing 1991. The usual 
disclaimers apply.

The number of virtual arrays is restricted to sixteen in the unregistered 
version.

If you use this software please send 6 pounds to British Software 
Licensing.
If you require a version which allows unrestricted virtual arrays please 
register your copy of this software. 
A copy of the source code can be obtained by sending 15 pounds to British 
Software Licensing.

If you use this software in any other Shareware or commercial application 
please contact the author to make arrangements.


----------------------------------------------------------------------
Order Form
-----------------------------------------------------------------------
To  British Software Licensing
    280 (T/L) West Princes Street,
    Woodlands,
    Glasgow
    United Kingdom
    G4 9EU

please supply me with:

an unrestricted copy of the large array manager     [   ]   5 pounds

a copy of the source for the virtual array manager
excluding the extended memory source code           [   ]  15 pounds

a copy of the source for the virtual array manger
including the extended memory source code           [   ]  25 pounds

overseas shipment                                   [   ]  2 pounds
                                                 -------------------
Total payment
                                                 -------------------


Payment type  ACCESS/VISA/MASTERCARD/CHECK(u.k. pounds)/POSTAL ORDER

Name on Card  ____________________________________


Card Number   ____________________________________


Expiry date   ____________________________________


Signature of Cardholder  ___________________________________

------------------------------------------------------------------

You may also purchase this software from:
Graham Robertson on
                             041-339-8855x5021
or on an Answering Machine   041-339-7264
or via Email       Graham.J.S.Robertson@uk.ac.glasgow.vme
or from America    Graham.J.S.Robertson@vme.glasgow.ac.uk
quoting the details required above.


-------------------------------------------------------------------
Files in the package.

LARGEARR.H         - Prototype of procedures used for large arrays

ARRAY.C            - Source code of an example of using a large array
ARRAY.EXE          - Example of using a large array
                   Compiled ARRAY.C linked with VIRIMG.LIB

VIRIMG.LIB         - Software to allow virtual and large arrays 

VIRIMG.H           - Prototypes of procedures for creating virtual arrays

VIRARRAY.C         - Source code of an example of using virtual arrays
VIRARRAY.EXE       - Example of using virtual arrays
                   Compiled VIRARRAY.C linked with VIRIMG.LIB

HUGHARR.C          - Source code of an example of using a hugh array
HUGHARR.EXE        - Example of using a hugh array

XMSARRAY.ZIP       - The same files as above, but using extended memory
                     instead of caching to disk.

-------------------------------------------------------------------
All the code here is compiled using the large data model
-------------------------------------------------------------------

Part 1 Using large arrays
-------------------------

This software is much use by example, so the comments in this document 
mainly explain the procedures that have been developed to enable the use 
of large, hugh and virtual arrays.

---------

There is only one procedure needed for accessing large arrays which adds 
an offset to a void pointer and returns a void pointer. The prototype is 
as follows.

    void *pointer_add (void *ptr,long offset)

The result of this is :- result = ptr+offset.

This routine is written is machine code so is very fast.

As can be seen in the program LARGEARR.C, to access an array, a macro is 
defined as follows.

#define <array in low>(x) ((<data type>*)pointer_add (<array in caps>,x))

    <array in low> := required array name in lower case
    <array in caps> := required array name in upper case
    <data type> := char|int|long| or any other data type

It is also required to define the variable name in the variable list as

    void *<array in caps>

and then to declare the memory to be used by one of the following three 
procedures given below.

    <array in caps>=char_array(<number of bytes>);
or
    <array in caps>=int_array(<number of words>);
or
    <array in caps>=long_array(<number of double words>);

--------------------------------------------------------------
    As many large arrays may be declared as memory allows.
    To access an array parenthesis are used instead of square brackets. 

(However, C++ routines could be used re-define the meaning of the square 
brackets.)

    e.g.      printf ("%d\n", <array in low>(25));
    would print out the 25th element of the array.

--------------------------------------------------------------
Part 2 Using virtual arrays and hugh array
---------------------------------------------------------------

The virtual array procedures are an extension of the above routines.

The routines create a specified number of arrays in memory. If more arrays 
are used than can fit into the memory allocated then the array that has 
not been accessed for the longest is cached to disk or virtual disk.

All the virtual arrays must be of the same size. The array memory must be 
initialised as follows.

initialise_virtual_arrays (<cache filename>,size of file buffer,
              number of arrays to be stored in memory, size of each array,
              maximum number of virtual arrays to be used)

This routine initialises a certain amount of memory depending on the size 
of the array and the number of array buffers in memory. The actual arrays 
do not take up disk space or memory until they are accessed.

To access an array the following procedure will return a pointer to the 
array.

    void *img(<array number>)

(In the restricted version <array number> is between 0 and 15)

If the array is not in memory it will be created, if it does not exist, or 
it will be loaded of disk. This pointer can be passed to a subroutine just 
like a normal array.

    e.g.   
         process (char picture[50][50])
         {
              .
              .
              Some code processing the array normally
              .
              .
         }

         main ()
         {
              .
              .
              process (img(5));
              .
              .
         }

----------------
    More than one array can be passed to a subroutine, but remember the 
limit to the number of arrays, that you have specified, that can be held 

in memory at any one time.

Also remember that if an array has been cached then when it is restored it 
may be restored to a different memory location.

----------------------------------------------------

    Another useful procedure is 

    void *large_array (<array number>,<array index>)

This routine returns a pointer to the ith element of the <array number>.

A macro can then be defined to access a certain array where an array 
number is assigned to an array name.


#define <array name>(x) *((<data type<)large_array(<array number>,x))

-----------------------------------------------------------------------
Hugh Arrays

    One hugh array can be created from a series of virtual images to 
almost any size. An example is given in the file HUGHARR.C

------------------------------------------------------------------------
Please note that the swap file is not deleted when the program terminates, 
so you will need to do that yourself.

------------------------------------------------------------------------
Part 3, Virtual arrays using extended memory
------------------------------------------------------------------------
    The file XMSARRAY.ZIP contains files with the same name as the files 
in the first two sections. By using this version the software operates 
slightly fastest.
    By using extended memory you have direct access to all your computers 
memory quickly and easily from C.
    To use this version of ARRAYS you need to have an extended memory
manager device driver such as HIMEM.SYS installed otherwise it will not 
work.
    In this version all functions are the same except for the 
initialisation of the array memory which no longer needs a file name. The
initialisation function is shown below.

initialise_virtual_arrays (number of arrays to be stored in memory,
              size of each array,
              maximum number of virtual arrays to be used)

--------------------------------------------------------------------------
In the future C++ routines will be devised to allow access to large arrays 
using standard C array addressing which will allow for portability.


Any suggestions for extending the functionality of the code will be 
gratefully received.

