Liren Large Software Subsidy 5/05.iso/a/a012/1.ddi/README.EXE/OVLRLD2.TXT

Text File | 1991-05-01 | 7.7 KB | 167 lines

              5.0 FOCUS: Memory Management, Overlay Reloading #2
                               By Roger Donnay

Introduction

In the December 1990 Aquarium, I discussed the advantages of using
reloadable overlays to reduce the memory overhead of your application.
Before reading this article, I recommend that you refresh your memory by
referring to the aforementioned article and get re-acquainted with the
RELOAD command and MODULE command, which are undocumented .RTLINK
features.

In the following examples, I will show you how to use the RELOADABLE
OVERLAY feature of .RTLINK to overlay sections of your third-party
libraries.  I will specifically address the dGE and FUNCKy libraries,
which are primarily written in C and Assembler.

Most third-party libraries are written in C, Assembler, and/or
Clipper. It is important when using a third-party library that you
know which modules are written in which language because this
information will make it much easier for you to develop an overlay
strategy.  Third-party documentation usually does not include this
information, so you will be required to figure it out for yourself.
Getting this information is not really very difficult, but it may
require you to invest a bit of time. For example, it took me nearly
five hours to work out an overlay strategy for the FUNCKy library, but
now that the work is done, the same overlay segments can be used in
all FUNCKy applications.


Determining the "Module" Names in a Library

Every .OBJect file placed into a library is also assigned a module name.
This module name is stored in the "COMMENT" record of the object in the
library.  The "module" name of an object is assigned by the compiler of
the object and is usually given the name of the original source code.
For example, let's say we want to place the FUNCKy FINDATTR() function
into an overlay.  First, we must figure out what "module" name was
assigned to the FINDATTR() function.  There are library manager utility
programs which can help you figure this out, but I'm going to show you
how to do it simply with your linker. During VERBOSE linking with RTLINK
or BLINKER, the module name of each object being linked into the program
is displayed on the screen as follows:

   FUNCKY50.LIB(C_MAXCHO)         <- Clipper code
   FUNCKY50.LIB(C_PUTKEY)         <- Clipper code
   FUNCKY15.LIB(findattr.C)       <- "C" code
   FUNCKY15.LIB(finddate.C)       <- "C" code
   FUNCKY15.LIB(findfirs.C)       <- "C" code
   FUNCKY15.LIB(chrfound.ASM)     <- "Assembly" code
   FUNCKY15.LIB(strcente.ASM)     <- "Assembly" code

You must make sure that you insert the command VERBOSE into your link
script file to insure that this information is displayed.  Next, when
you perform the link, make sure to route the dislay output to a file
so you can have the information in text file format:

   RTLINK @MYPROG > MYPROG.TXT

MYPROG.TXT will contain the complete list of modules linked into your
program.  Now we must use this information to develop an overlay
strategy.  The name of each module linked into the program (shown in
parentheses) must be referred to exactly as spelled.  For example,
to place the function FINDATTR() into an overlay, we must first
determine the module name which would contain the FINDATTR() function.
Fortunately, the FUNCKY15 library uses the same prefix name as the
actual function, so in perusing the list of linked objects in MYPROG.TXT
we find a module named "findattr.c".  To place this module in an overlay
section, simply use the command:

   SECTION MODULE findattr.c

When placing modules into overlays, you must use extreme care to not
overlay functions which are either called by interrupts or recursively.
Code which is called by interrupts is called by a direct vector rather
than a real address.  This can cause your computer to lock up if the
code segment is not currently in memory.  Code which is called
recursively would be something like special string handling routines
that might be called from within a DO..WHILE loop.  If this function
were placed in an overlay, you may experience considerably slower
performance and/or disk access.

Many third-party library developers now distribute their product in two
libraries: a resident library and an overlayable library. Most
of the work has already been done for you in determining which modules
can be overlayed.  If the module is part of the resident library, do not
make any attempt to try to overlay it, or you will certainly experience
run-time problems.  Also, do not overlay "Clipper code" because this
code is automatically overlayed into "dynamic-pages" by Rtlink.


Overlaying the dGE Library

dGE consists of a set of graphics functions and screen-drivers. dGE has
different screen-drivers for CGA, EGA, VGA, etc.; yet, this overlay
structure allows all the screen-drivers to be linked into the
application without using any more memory.  The rest of the library is
written in "C" and is broken down into 10 modules, each holding a set of
functions. The screen drivers CANNOT be placed into the same section as
the functions because the currently selected driver cannot be swapped
out of memory at runtime.  The screen driver segment mixes code and data
so if it were swapped out, you would lose your current bit-mapped
screen.

The dGE library was one of the easiest overlay structures to develop.
This one took me less than an hour and appears to work flawlessly. The
link script file shown in the accompanying source code file is used to
create the dGE demonstration program.  Please note the use of another
undocumented feature of RTLINK in this script file:

  @ CLIPPER.LNK

The "@" command in an RTLINK script file is similar to the "#include"
command in your Clipper source.  In this case, we included the overlay
script for the Clipper libraries (editor's note: please refer to
Roger's article in the 12/90 Aquarium for this script).


Overlaying the FUNCKy Library

Developing an overlay strategy for FUNCKy was a larger project simply
due to the large number of functions in this library.  Actually,
determining the name of each module was also a bit of a struggle
because the module names don't always correspond to the function
names.

First, I needed to build a .MAP of the FUCNKy libraries using a
library manager such as LIB.EXE which comes with all the Microsoft
languages.  This will scan a library and produce the following output:

FUNPROTECT........funprote          FUNstack..........funstack
FWRITE............fwrite            FWRITEBYTE........fwriteby
FWRITEINT.........fwritein          FWRITELINE........fwriteli

This kind of map only gives you the "pseudo module name" because it
does not include the source code extension (".C" or ".ASM").  To get
the full module name you must get it during the "verbose" link cycle
as shown earlier in this article.

Link script file #2 in the accompanying source code file is used to
create the VIEW.EXE demonstration program.  You will get a large
number of "warnings" when using this script, because the VIEW.PRG
program does not call all of the modules we have asked RTLINK to
overlay.  You can eliminate the warnings by removing the "warned"
modules from the overlay segments.


Summary

Please review these link script files carefully.  They should help you
in designing strategies for overlaying third-party libraries with
.RTLINK and Clipper 5.0.


About the Author

Roger Donnay is the developer of the dCLIP development platform/runtime
system for Clipper, and the application libraries SOFT.CLIP and TIME-TRAK.
He can be reached at via the Aquarium Message Center, or c/o:

DONNAY Software Designs
1880 Park Newport, #104
Newport Beach, CA 92660
Tel: [phone]
Fax: [phone]
Compuserve: 73227,1225