Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : OVERCL.ZIP
Filename : OVERLAY.DOC

 
Output of file : OVERLAY.DOC contained in archive : OVERCL.ZIP


March 14, 1989

OverLay()tm for Clipper
Copyright (C) 1988-89, Gregory A. Martin
************************************************************


Apology:

This version of OverLay()tm (version 1.8) will not be
supplied with printed documentation. Although OverLay()
has been available to C programmers since November of 1988,
OverLay() has been constantly improved over those months.
In version 2.0, I will yet add support for expanded memory
and the ability to save memory to more than one disk drive.
I am also wanting to hear from users of OverLay() as to any
suggestions they have for version 2.0. Therefore, I have
decided to release version 1.8 (the first version available
to Clipper users) without printed documentation. I will be
releasing version 2.0 with the above mentioned improvements
(as well as suggestions from users of version 1.8) and with
printed documentation as a free update when it is ready. I
feel it is better to release the fully debugged version 1.8
now, rather than wait until OverLay() includes other
enhancements that many Clipper users don't really need at
the present time.

This documentation file contains formfeed characters to
correctly format the printout. When printed out the
documentation requires 12 pages. You can print this
documentation on a printer by simply entering the command:

TYPE OVERLAY.DOC >PRN

As the author of OverLay() I would appreciate hearing from
you. If you would like to give me suggestions or if you
have any problems or if you just want to talk, please feel
free to call me at my home. At the time of this writing, I
live in DuQuoin, Illinois and my home phone number is (618)
542-5360.

You can also send me electronic mail on the following BBS's:

CompuServe: 73707,3450 (Please use CompuServe if you can)
The Source: BFQ359
BIX: gregm
The BOSS, DATA-BASE, Silver Bullet in Texas: Greg Martin

Trademarks of product names mentioned in this documentation:
OverLay() is a trademark of GAMbit Software.
dBase is a trademark of Ashton-Tate.
1-2-3 is a trademark of Lotus Development Corp.
Clipper is a trademark of Nantucket, Inc.
PC-DOS is a trademark of International Business Machines.
MS-DOS and Quick BASIC are trademarks of MicroSoft.
Turbo Pascal is a trademark of Borland International.






What is OverLay()tm?

OverLay()tm is a function written in assembly language and
callable by other programming languages. OverLay() will
overlay another application into the same memory being used
by your current executing program. What this means is that
OverLay() allows you to free up virtually ALL of the memory
used by your currently executing application, then EXEC
(run) another LARGE program or shell out to DOS, and then
return back to your original program where you left off!

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() telling it 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 10K
overhead, meaning that all of your memory can be freed
except for the 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. At the
time of this writing it had 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 us know the results).






Why was OverLay() developed?

OverLay() was written to fill a need of it's author. With
the 640K memory limit of DOS and the increasing memory
requirements of software, a method was needed by the author
to allow a large program to run another large program
within the confines of the 640K barrier.

Obviously, the only solution would be to save used memory
to a disk file, free that used memory up, and run the other
needed program. Then, when the other program was finished,
memory could be restored from the disk file and the program
could continue where it left off.

Yet, all this had to be accomplished using documented DOS
function calls or else it might fail because of the wide
variety of PC/MS-DOS operating systems in use.

After much research and experimenting, OverLay() was
written and subsequently tested and refined by being used
in real applications by a wide variety of customers.

OverLay() was first written for C and Assembler programmers
and then was expanded to include Clipper, Turbo Pascal-tm,
and Quick BASIC-tm programmers. Other interfaces for other
languages will probably follow.

There is much more to the story than this, though. The
author originally wrote a similiar function called Swap!
for Clipper programmers only. Without getting into the
details of why, the author gave up all rights to that
product and no longer supports it or is associated with it
in any way.


What are the operating system requirements?

OverLay() is provided in the form of an .OBJ file and must
be linked into your application. OverLay() is designed to
work under PC-DOS and MS-DOS versions 2.11 and above as
well as MS-DOS compatible operating systems such as PC-MOS.
Unfortunately, DOS 2.00 and 2.10 have a bug in the DOS EXEC
function that causes OverLay() to fail when it returns to
the main program. This bug was corrected in DOS 2.11 and
later versions.






What versions are available?

At the time of this writing versions of OverLay() were
available for: ASSEMBLY LANGUAGE, C, QUICK BASIC, TURBO
PASCAL, and CLIPPER programs.

Each version has a differently named .OBJ file:
OVER_CL.OBJ: For CLIPPER programs.
OVER_C.OBJ: For C and ASSEMBLY LANGUAGE programs.
OVER_QB.OBJ: For QUICK BASIC programs.
OVER_TP.OBJ: For TURBO PASCAL programs.

The limited DEMO versions (which allows only two
consecutive calls to the function) are named:
OVERD_CL.OBJ: For CLIPPER programs.
OVERD_C.OBJ: For C and ASSEMBLY LANGUAGE programs.
OVERD_QB.OBJ: For QUICK BASIC programs.
OVERD_TP.OBJ: For TURBO PASCAL programs.

Versions for other languages or compilers will be produced
as the need arises. If you have a particular need, please
contact the author, Greg Martin.






How do you use OverLay() with Clipper?

OverLay() uses the following syntax when called from Clipper:

Result = OverLay(Program, Memory, Prompt, ;
Pathname, Filename, Restoredir)

Program is a string containing the name of the program you
want to run and it's parameters. If it is an empty string,
the function will shell out to DOS.

Memory is 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.

Prompt is a string containing the DOS prompt you want
displayed if your shelling to DOS. Specifying an empty
string will cause OverLay() to use the current DOS prompt.
The setting of the DOS prompt is covered in your DOS
manual under the command PROMPT.

Pathname is 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 an
empty string will cause OverLay() to place the temporary
file in the current directory.

Filename is a string containing the filename you wish to
use to store used memory. Specifying an empty string will
cause OverLay() to do one of two things: (1) If DOS 3.0 or
above is installed, a temporary file will be created using
DOS's create temporary file function or (2) If DOS 2.11 is
installed a file called OVERLAY.RAM will be created. Thus
if you are on a network and using DOS 3.0 or above,
OverLay() can be simultaneously executed by several users
with no problems. If DOS 2.11 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 a logical value of .T. or .F. 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 .F. if you do not want
it to restore the drive and directory or specify .T. 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 = Prompt string greater than 60 characters.
2 = Program plus parameters greater than 124 characters.
3 = Not able to find COMSPEC= in enviroment.
4 = Invalid memory control block encountered.
5 = Too many memory control blocks
(This should NEVER happen with Clipper, but, if it
does, OverLay() can be modified for you).
6 = Not able to create temporary file.
7 = Error saving memory to disk file.
99 = OverLay() was called more than twice (Demo version).

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

If none of these errors occur, but the called program
returns an error code by setting DOS's ERROR LEVEL,
OverLay() will add 100 to the return code and pass it back
to the main program as OverLay()'s return value. Thus if
OverLay() returns a value of 103 the called program
returned an ERROR LEVEL of 3; a return value of 110 means
the called program set DOS's ERROR LEVEL to 10.


Examples:

Result = OverLay("", 0, "Type EXIT to return$_$P$G",;
"", "", .F.)
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.0 or above) or
OVERLAY.RAM (DOS 2.11) to save used memory. Change the DOS
prompt to display the message "Type EXIT to return" with
the current directory on the next line. Do not restore the
drive/directory upon return.

Result = OverLay("123", 0, "", "C:\TEMP", "", .T.)
means to run Lotus 1-2-3tm after freeing up all available
memory. Save used memory to the TEMP directory on drive C
using a temporary file (DOS 3.0 or above) or OVERLAY.RAM
(DOS 2.11). Do not change the DOS prompt. Restore the
current drive/directory upon return (in case 1-2-3tm
changed either).

Result = OverLay("dBase", 400, "", "D:\", "Memory", .T.)
means to run dBasetm, but only free up 400K. Save used
memory to the root directory of drive D in a file called
Memory. Do not change the DOS prompt. Restore the
drive/directory upon return from OverLay().




The DOS Enviroment:

You can also specify a pathname to store temporary files to
with the enviroment variable TEMP. Therefore, you can use
the DOS command:

SET TEMP=C:\TEMPFILE

This command will create a DOS enviroment variable TEMP
telling OverLay() to store all temporary files to the
TEMPFILE subdirectory on drive C if a path is not
specified. 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 TEMP.


Other Notes:

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 want to free up as much memory as possible you
should write a STARTUP module that simply calls your main
program and link OVERLAY.OBJ in between them as follows:

LINK Startup+OverD_CL+MainProg etc.
or PLINK86 fi Startup,Over_CL, MainProg etc.
or PLINK86 fi Startup,OverD_CL,MainProg etc. (Demo Ver)

This will give you the maximum available memory if you
specify 0 for the amount of memory to free up. Once the
.EXE is loaded, OverLay() will be as close to the beginning
of memory as possible, thus allowing it to free up as much
memory as possible.


Notes on interrupt handlers:

If you incorporate third party libraries that redirect
interrupt vectors (example: A function that displays a real
time clock on the screen has to redirect the clock
interrupt), you should either turn the function off before
calling OverLay() or use the SaveInts() and RestInts()
functions to save and restore the interrupts. Turning the
functions off is the preferred method.




CurPath() and CD() functions:

Included also is an .OBJ file called OVER_UDF.OBJ. This
.OBJ file contains two functions: CurPath() and CD().
These functions are included to assist you in using
OverLay(). If used they can be linked into your
application just like the OverLay() .OBJ file or if you
have access to the LIB utility you can add it to your
CLIPPER.LIB file.

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

CurPath() is used to return a full drive
letter and path specification for the specified drive or
for the current drive if no drive is specified.

EXAMPLES:

PathString = CurPath()
returns the current drive and path. If you are on drive C
in the CLIPPER directory this function call would return
the string "C:\CLIPPER".

PathString = CurPath("A")
returns the full drive and path specification of drive A.
If the current directory of drive A was TEMP this function
call would return the string "A:\TEMP".

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

CD() changes the current drive and/or path to
the one specified. This function returns .T. if the drive
and/or path specified exists or .F. if DOS returned an
error because the drive or directory doesn't exist.

EXAMPLES:

Result = CD("C:\CLIPPER")
would change the current drive to drive C (if you weren't
already on drive C) and changes the current directory on
drive C to CLIPPER (if it exists). If drive C doesn't
exist or if a CLIPPER directory doesn't exist in the root
directory of drive C the function will return a .F. result
and you will remain in your current drive/directory.

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

These functions can be used to change the current drive and
path before running another program. Let's say you need to
run Lotus 1-2-3 which is on drive C in the 123 directory.
You would use the following commands to run 1-2-3:

CurPath = CurPath() && Get the current drive/directory.
IF CD("C:\123")
OverLay("123") && Notice other parameters are optional.
ELSE
? "Lotus 1-2-3 directory doesn't exist!"
ENDIF
CD(CurPath) && Return to the old drive/directory.






The SaveInts() and RestInts() functions:

Now for two functions that you may never use, yet are
included in case you may need them. Sometimes using
OverLay() to run certain ill-behaved programs can cause
problems because these programs may change interrupt
vectors and not restore them. This is especially true with
programs compiled with old BASIC compilers.

You may use OverLay() to run a program, but when it comes
back your main program may hang mysteriously. This can be
due to the fact that the program you called changed an
interrupt vector, but did not restore it. This is a VERY
RARE problem.

Or if you are using some third party functions (or some of
your own) that change interrupt vectors, it would be nice
to have a function that could save the previous interrupt
vectors and restore them before the call to OverLay(), then
to set them back again after the call to OverLay().

Two functions: SaveInts() and RestInts() will save and
restore interrupts for you. These functions can be
dangerous and should only be used if you understand what
they do. The functions are included for the benefit of
those programmers who have specific uses for them.

This is the Clipper syntax:

Source = CHR(?) + CHR(?) + . . . && Replace ? with numnbers
Dest = SaveInts(Source)
RestInts(Dest)

Source is a character string that contains the numbers of
the interrupt numbers you want to save. These numbers are
character (byte) sized.

SaveInts() returns a character string that contains the
interrupt numbers and their current values. The return
string length will be equal to the length of the Source
string times 5.

Dest = SaveInts(CHR(23)+CHR(24))

The above will save interrupts 23 and 24. There is no
particular reason to save these vectors. This is just
an example.

RestInts() is the opposite of SaveInts(). The interrupt
vectors stored in Dest are restored to the interrupt
numbers contained in Source.

RestInts(Dest)





Can I use OverLay() in an Clipper program that uses
overlays to call another Clipper program that uses overlays?
Can I call OverLay() in the middle of a READ?

MOST CERTAINLY!


In what ways can I change the DOS prompt?

Look in your DOS manual under the PROMPT command. I would
recommend that you use the Clipper GETE() function to get
the current PROMPT setting and prefix it with "Type EXIT to
return$_". This will print the message: "Type EXIT to
return" followed by the current DOS prompt on the next line.
i.e. OverLay("", 0, "Type EXIT to return$_"+GETE("PROMPT"),;
"", "", .t.)


Why would I ever need to specify a filename with OverLay()?

The filename parameter is only needed if your in a
multi-user enviroment using DOS 2.11 or you use OverLay()
recursively under DOS 2.11. Under DOS 3.0 or above DOS
creates it's own temporary file and in a single user
enviroment under DOS 2.11, OverLay() creates a file called
OVERLAY.RAM if a filename is not specified.


Why do I get an "error reallocating memory control blocks"?

That error is almost certainly caused because you have ran
a program that has made part of itself memory resident.
You cannot install memory resident programs with OverLay()
because the memory that a memory resident program captures
was in use by your original Clipper program. Even
functions like Mark and Release that are used to get rid of
memory resident programs may make themselves memory
resident in the process. The moral: Do not run memory
resident programs (TSRs) with OverLay().


I use some third party add-on products within my Clipper
application. When I call OverLay() my computer will
sometimes lock up when some of the other third product
functions are also being used. What should I do?

ALWAYS "turn off" other third party add-on products if they
operate by changing interrupt vectors. A good example is a
clock function that displays a real time clock on the
screen. It changes the clock tick interrupt so that the
computer will call the third party function every second to
update the clock display. If you don't turn the clock off,
once the new program is loaded the interrupt vector will no
longer point to the third party function, but to a unknown
section of the new program. By turning the clock off
temporarily, the interrupt will be restored to it's old
address before the new program is loaded.





OverLay() works GREAT with all kinds of programs, except
that the computer locks up when OverLay() returns from
running this one particular program that I use. Why does
this happen and how can I correct it?

There are a relatively few "misbehaved" programs that
change reserved DOS interrupt vectors and don't restore
them when they are done executing. These "misbehaved"
programs are VERY, VERY FEW, but some old BASIC compilers
do have this problem. Even Clipper's RUN command will
cause the computer to freeze running these programs. You
can use SaveInts() and RestInts() to find which interrupts
were not restored and restore them yourself to correct this
type of problem. Please feel free to contact me for help
if you think this is your problem.


Does OverLay() work properly in a network?

Yes, it was written to work under a network. As long as
DOS 3.0 or above is being used, OverLay() creates unique
filenames to save the memory image. Only if your using DOS
2.11 in a network do you have to specify a filename or if
your using OverLay() to call another Clipper program which,
in turn, uses OverLay(), you need to specify two different
filenames under DOS 2.11.


What is the DOS ERROR LEVEL?

Some programs such as the Clipper compiler and other
language compilers return an ERROR LEVEL if they
encountered an error while compiling. They tell the
program (or .BAT file) that called them that an error
occurred by setting DOS's ERROR LEVEL. Thus if you use
OverLay() within a Clipper application to call a compiler
and the compiler returns an ERROR LEVEL of 1 (meaning an
error has occurred), OverLay() will return a result of 101.
Any OverLay() return value greater than 100 means that the
called program returned an error and you need to subtract
100 to get the true ERROR LEVEL. With that information you
can return a message such as: "An error has occurred while
compiling". Of course, this has other uses than just with
compilers.


What if I use expanded handle tables?

If you use DOS 3.3 or higher and set the DOS enviroment
variable CLIPPER to Fnn (where nn is some number of files
to use) or if you use the public domain HANDLES.OBJ to
allow you to have more than 20 files open at once,
OverLay() will automatically detect this and move the
handle table to a safe location, if it is in danger of being
overwritten by the OverLayed program.






LICENSING AGREEMENT FOR OverLay()


Gregory A. Martin provides the OverLay() .OBJ file and
licenses it's use. By purchasing OverLay() you agree to
abide by the following terms. You (the buyer) are licensed
to use OverLay() in your applications whether they are for
commercial or private use. The copyrights of the OverLay()
.OBJ file, the documentation, and the test program are
owned by Gregory A. Martin.

OverLay() is licensed on a "per site" basis. You may use
OverLay() to develop software on any number of computers at
one location. If you wish to use OverLay() to develop
software at other site(s), you must purchase a license for
each location that OverLay() is used to develop software.

You (the buyer) may not transfer possession of the
OverLay() .OBJ file or any copy, in whole or in part, to
any other individual or organization, nor may it be used in
any marketable product whose function is to provide
software developers the means to free up used memory.
Violation of this licensing agreement will make the
purchaser of this license responsible for lost revenue.

Gregory A. Martin makes no representations or warranties
with respect to the misuse of OverLay(). In no event shall
Gregory A. Martin be liable for any loss of profit or any
commercial damage, including but not limited to special,
incidental, consequential or other damages.

This agreement shall be governed by the laws of the State
of Illinois.


  3 Responses to “Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : OVERCL.ZIP
Filename : OVERLAY.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/