Overlay() - Copyright (C) 1988, Gregory A. Martin

*********************************************************************

Overlay() is a function written in Assembly Language and callable
by other Assembly Language or C programs.

Overlay() allows you to free up virtually ALL of your memory used by
your currently executing application and then EXEC (run) another
LARGE program or shell out to DOS. EXAMPLE: If you write a LARGE
application that requires a full 640K to run and you need to be able
to run another application from it or shell to DOS, then all you need
to do is call Overlay() with the program you want to run and how much
memory you want to free up. Overlay() will see how much memory is
free and if it is not enough, Overlay() will save used memory to a
disk file, free that memory up, run the requested program (or shell
to DOS if requested), and when the requested program is done, Overlay()
will restore the freed up memory from the disk file and continue
execution of your original program!

Think of it! No more worries about memory requirements when calling
other programs. If popular existing software packages used Overlay()
they could shell to DOS with virtually ALL of the computer's memory
FREE!

I want to repeat for emphasis: Overlay() allows you to free up as
much memory as you need to run another program, up to virtually ALL
OF IT. Overlay() can even be called RECURSIVELY. A 512K application
can call a 512K application, which can in turn call another 512K
application, which can call another 512K application, and so on. If
planned properly, Overlay() has only a 5-10K overhead, meaning that
all of your memory can be freed except for the 5-10K per iteration.

Overlay() uses documented DOS function calls to accomplish what it
does. It has been tested under a variety of DOS's and has worked
flawlessly under each and every one. It has not yet been tested
under systems like MicroSoft Windows or IBM's TopView, so if you are
using those types of enviroments, it is recommended that you test it
(and please let me know the results).

This version of Overlay() is limited to being called twice in an
application. The non-demo version can, of course, be used as many
times as required.

*********************************************************************

Overlay() uses the following syntax when called from C:

result = overlay(program, memory, pathname, filename, restoredir)

The overlay function should be declared:

int extern far overlay(char far *program, int memory, char far *pathname, char far *filename, int restoredir)

(The far directive makes Overlay() compatible with any C model.)

program is a far pointer to a string containing the name of the
program you want to run and it's parameters. If it is a zero length
string or a NULL pointer, the function will shell out to COMMAND.COM.

memory is an integer containing the amount of memory in K that you
want to free up. Specify 0 or a number greater than available memory
to free up all the memory possible.

pathname is a far pointer to a string containing a DOS path
specification as to where to place the temporary file produced by
Overlay(). Thus if you have a RAM disk, you can save used memory to
it much faster than writing it to a hard disk. Specifying a zero
length string or a NULL pointer will cause Overlay() to place the
temporary file in the current directory.

filename is a far pointer to a string containing the filename you
wish to use to store used memory. Specifying a zero length string or
a NULL pointer will cause Overlay() to do one of two things: (1) If
DOS 3.x is installed, a temporary file will be created using DOS's
create temporary file function or (2) If DOS before 3.x is installed
a file called OVERLAY.RAM will be created. Thus if you are on a
network and using DOS 3.x, Overlay() can be simultaneously executed
by several users with no problems. If DOS 2.x is being used on a
network, you should specify a unique file name so that only one user
will create the same filename.

restoredir is an integer with the value of TRUE or FALSE (non-zero or
zero respectively). This parameter asks the question: "Should I
restore the current drive and directory when the called program
ends?" Thus if a user shells to DOS or an Overlayed program changes
the current drive and/or directory, Overlay() will automatically
restore it when it returns. Specify 0 if you do not want it to
restore the drive and directory or specify any non-zero number such
as -1 to cause it to restore the drive and directory before it returns.

result is an integer returned by Overlay() specifying whether an
error occurred or not. A return value of 0 means no error occurred.

These are the following error values:
1 = Program plus parameters greater than 124 characters.
2 = Not able to find COMSPEC= in enviroment.
3 = Invalid memory control block encountered.
4 = Not able to create temporary file.
5 = Error saving memory to disk file.

These errors do not return values, but instead abort the program
setting DOS's ERRORLEVEL to:
6 = Error deallocating memory control blocks.
7 = Error reallocating memory control blocks.
8 = Error reading memory back in from disk file.


You can also specify a pathname to store temporary files to with the
enviroment variable TEMP. You can SET TEMP=C:\TEMPFILE to store all
temporary files to the TEMPFILE subdirectory on drive C. Overlay()
will only use the TEMP enviroment variable if you do not specify a
path in the Overlay() call. In other words, specifying a path when
you call Overlay() overrides the enviroment variable.


*********************************************************************

Examples:

result = overlay("", 0, "", "", 0) means shell to DOS freeing up all
available memory using the current default drive and directory to
save memory to and using a temporary file (DOS 3.x) or Overlay.RAM
(DOS 2.x) to save used memory. Do not restore the drive/directory
upon return.

char far *program = 0;
char far *pathname = 0;
char far *filename = 0;
result = overlay(program, 0, pathname, filename, 0) means the same thing as
the previous example, but using NULL pointers instead of zero length
strings to cause Overlay() to use it's defaults.

result = overlay("123", 0, "C:\TEMP", "", 1) means to run Lotus 1-2-3
after freeing up all available memory. Save used memory to the TEMP
directory on drive C using a temporary file (DOS 3.x) or Overlay.RAM
(DOS 2.x). Restore the current drive/directory upon return (in case
1-2-3 changed it).

result = overlay("DBASE", 400, "D:\", "Memory", 1) means to run
dBase, but only free up 400K. Save used memory to the root directory
of drive D in a file called Memory. Restore the drive/directory upon
return from Overlay().

*********************************************************************

To call Overlay() from Assembly Language:

EXTRN _overlay:FAR
.
.
.
movax,restoredir; 0 or 1 to restore directory
pushax
movax,seg Filename; push the segment address
pushax; then the offset of Filename,
movax,offset Filename; push two 0's for default
pushax
movax,seg Pathname; push the segment address
pushax; then the offset of Pathname,
movax,offset Pathname; push two 0's for default
pushax
movax,Memory; in KB, 0 for all
pushax
movax,seg Program; push the segment address
pushax; then the offset of Program,
movax,offset Program; push two 0's for DOS.
pushax
call_overlay; underscore is C convention
addsp,14; pop off parameters
movResult, ax; result is in ax

See above description of parameters.

*********************************************************************

When Overlay() frees up memory it starts at the top of memory and
works it's way down freeing up what it needs to free up. It stops
though when it encounters it's own location in memory. This location
mirrors it's location in the LINK list.

Thus if you are using MicroSoft C you should write a startup module

that simply calls your MAIN() procedure and link Overlay.OBJ in
between them as follows: LINK Startup Overlay MainProc etc. This
will give you the maximum available memory. See the LINK_MC.BAT file
for an example.

For Turbo C (medium model): TLINK c0m Startup Overlay MainProc etc.
See the LINK_TC.BAT file for an example.

Once loaded OVERLAY will be as close to the beginning of memory as
possible, thus allowing it to free up as much memory as possible.

*********************************************************************

Technical Info:

Overlay() uses standard C convention in it's structure. It consists
of one segment called Overlay_TEXT (BYTE aligned) that is classed as
'CODE'. All local data is grouped within that segment (in other
words, it does not contain a DATA segment). Although written in
Assembler, the function follows C parameter passing conventions. You
just need to make sure that Overlay() and it's string parameters are
declared as or default to type FAR when called from C.

*********************************************************************

Example program:

Included is an example C program to call Overlay() as well as a
LINK_MC.BAT file for MicroSoft C and a LINK_TC.BAT file for Turbo C
to link the .OBJ files.

*********************************************************************

Interrupt Handlers:

If you have written an interrupt handler that is incorporated within
your C or Assembler application and you call Overlay() asking it to
free up all available memory, you should either restore the interrupts
before calling Overlay() or place the .OBJ files that contain the
interrupt handlers in front of OVERLAY.OBJ in the link list as in:

If you are using MicroSoft C -
LINK Startup Handler Overlay MainProc ...

If you are using Turbo C (medium model) -
TLINK c0m Startup Handler Overlay MainProc ...

This way if the interrupt occurs while the Overlayed application is
running the handler will still be in memory to service it.

Also if you are using expanded file handle tables this newest version
of Overlay() will detect if the new expanded file handle table could
be overwritten by the overlayed program and moves the handle table
temporarily to a location within Overlay.OBJ while the overlayed
program is running.

One company uses Overlay() from a C program that was EXECed with the
execl() function. This caused the enviroment block of the C program
to be located at the highest memory location possible. Overlay() was
freeing this memory up thus causing the enviroment block to be
overwritten. This has now been corrected. Overlay() will detect if
the enviroment block has been located to high memory and will not
deallocate that block if it has.

*********************************************************************

Overlay() works fine with overlayed programs using Plink86. It can
probably be written to be called from compiled BASIC, PASCAL, FORTRAN,
and other languages that allow calls to external functions. If you
have an need to call Overlay() from these or other languages, please
contact me and I'll work with you to write an interface for another
language for a small extra charge.

*********************************************************************

License Pricing:

After much thought I came up with a licensing arrangement that I feel
is fair both to myself and software developers.

If you wish to use Overlay() for your own use (whether you are a
company or an individual) or if you are an independent programmer who
contracts out his services to develop software for others (as long as
the software is not sold commercially), I am asking just $53.00
($50.00 plus $3.00 shipping and handling charge) for a licensing
agreement.

If you will be using Overlay() in commercial applications that are
resold to others I do ask $198.00 ($195.00 plus $3.00 shipping and
handling charge) for a licensing agreement. I do not want to appear
greedy, but Overlay() can greatly enhance commercial applications and
I do ask for a somewhat corresponding compensation.

I do realize that most large software developers would require the
source code before they incorporate something like this in their
software, therefore, I will make the source code available under a
non-disclosure agreement which specifies that it can ONLY be used to
modify the function of Overlay(). This agreement prohibits the use
of the source code to produce a product to compete with Overlay() or
a product to provide software developers with a method of freeing up
used memory. I will license the commented source code for $500.00
after an agreement has been signed.

To order please send a check or money order to:

Gregory A. Martin
PO Box 77
DuQuoin, IL. 62832

or call: (618) 542-5360.

I am also interested in speaking with anyone who would like to include
Overlay() in their own third-party libraries.

*********************************************************************