Linking Techniques for Memory Management (Part 2) by Roger Donnay

This section written by Roger Donnay is the third part of CA-Clipper 5.x Memory Management by Roger Donnay & Jud Cole.

Overlaying Library Modules
The MODULE command provides the important capability of overlaying the larger modules of the CA-Clipper libraries or any third-party library. With previous versions of these linkers, the overlaying of libraries was restricted to ALL modules in a library or NO modules in a library. This is ok for libraries which were designed for overlaying, but in most cases it is simply not practical to overlay an entire library due to speed performance problems. There are many modules in the CA-Clipper libraries which can be overlayed without crashing the program, yet runtime performance can be disastrous. Determining the proper "set" of modules and the optimum "overlay pool size" is simply a matter of trial and error. For example, overlaying the MACRO module in one application may have very little affect on speed performance because of the design of the program and it's probably negligible.

The MODULE command is very useful in that it allows your linker to place "modules" from libraries into overlays. You can organize your projects by placing all your C/ASM objects in libraries with a library manager such as Microsoft's LIB.EXE then by using the SECTION MODULE command in your link file you can place any module into any overlay area.

Rtlink:

LIB mylib

BEGINAREA

SECTION MODULE myfileA,myfileB

SECTION MODULE myfileC

SECTION MODULE myfileD

ENDAREA

The MODULE command in RTLINK requires that the exists in one of the declared libraries and that the name is "unique" to that module otherwise the command will be ignored and the module will be linked into the root memory area. This is not a problem with the CA-Clipper libraries because the modules are given unique names.

BLINKER supports the MODULE command differently and, in my opinion, better than RTLINK. Blinker allows you to define a specific module from a specific library to be linked into the application, thus you don't need to worry about the module being unique to one library. For example, if you have two libraries, both containing an ERRORSYS module, you can decide which ERRORSYS you want linked into the program.

Blinker:

LIB mylib

BEGINAREA

LIB grump

MODULE errorsys FROM grump

MODULE myfileA,myfileB

MODULE myfileC

MODULE myfileD

ENDAREA

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 "COMENT" 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. The CA-Clipper compiler assigns the source code file name to the module name however and many other compilers will assign the name of the SOURCE file as the module name including drive letters and directories. 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 the "module" name of each object being linked into the program is displayed on the screen as follows:

FUNCKY50.LIB(C_MAXCHO) <- CA-Clipper code FUNCKY50.LIB(C_PUTKEY) <- CA-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 route the display 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 take this information and use it to develop an overlay strategy. The name of each module linked into the program is shown (in parenthesis) and must be referred to "exactly" as it is 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

BLINKER's MODULE command is more useful than RTLINK's because it searches both the THEADR record and the COMENT record for the name of each module. This means that you don't need to reference the MODULE name as precisely with Blinker as with RTLINK. For example, if the module name in a library is FINDATTR.C, BLINKER will overlay it by with the following command: MODULE FINDATTR, because it will determine that what you are trying to overlay is FINDATTR.OBJ.

Overlaying the CA-Clipper Libraries

Overlaying the CA-Clipper libraries is accomplished quite differently with each linker, therefore I have included examples for each linker.

Overlaying Code with RTLINK

RTLINK uses Static reloadable overlays with and the MODULE command to overlay much of the CA-Clipper libraries and thereby reduce memory usage in your CA-Clipper-5.x applications. The below link script example creates an overlay area for overlaying the larger modules in the CA-Clipper libraries which are not likely to call each other recursively, therefore you will probably notice very little difference in speed performance yet you will get up to 50K more memory overhead depending on how much of the CA-Clipper libraries your application uses.

You may get a "warning" message during link time if your application does not call one of the modules referenced in an overlay area. In the event this happens, simply remove that module from the link file. For example, if you are not using MEMOEDIT() in your application remove the line:

SECTION MODULE D:\CC\EDIT\MEMOEDIT.C

FI

LIB

OUTPUT

RELOAD FAR 200

# Create overlay area 1

BEGINAREA

#1

SECTION MODULE D:\CC\EDIT\MEMOEDIT.C

MODULE D:\CC\MEMO\MEMOTRAN.C

MODULE D:\CC\MEMO\MEMOREAD.C

MODULE D:\CC\MEMO\MEMOWRIT.C

MODULE D:\CC\MEMO\MEMOLINE.C

MODULE D:\CC\MEMO\MLCOUNT.C

MODULE D:\CC\MEMO\MLPOS.C

#2

SECTION MODULE D:\CC\STR\IS.C

MODULE D:\CC\MEMO\HARDCR.C

MODULE D:\CC\STR\PADL.C

MODULE D:\CC\STR\PADC.C

MODULE D:\CC\STR\PADR.C

MODULE D:\CC\ARRAY\ASCAN.C

MODULE D:\CC\ARRAY\ASORT.C

MODULE D:\CC\ARRAY\DIRECTRY.C

MODULE D:\CC\BASE\AEVAL.C

MODULE D:\CC\BASE\ACOPY.C

MODULE D:\CC\BASE\ADEL.C

MODULE D:\CC\BASE\AINS.C

MODULE D:\CC\BASE\ATAIL.C

MODULE D:\CC\MISCX\COPYFILE.C

MODULE D:\CC\MISCX\TYPEFILE.C

MODULE D:\CC\TERM\SCROLL.C

MODULE D:\CC\MISCX\GETE.C

MODULE D:\CC\MISCX\DISKSPAC.C

#3

SECTION MODULE D:\CC\SDF\SDF1.C

MODULE D:\CC\SDF\SDF0.C

MODULE D:\CC\SDF\SDFDYN.ASM

MODULE D:\CC\SDF\DLM1.C

MODULE D:\CC\SDF\DLM0.C

MODULE D:\CC\SDF\DELIMDYN.ASM

MODULE D:\CC\EDIT\ACHOICE.C

MODULE D:\CC\DBCMD\DBCREATE.C

MODULE D:\CC\DBCMD\DBJUNCT.C

MODULE D:\CC\DBCMD\DBSTRUCT.C

#4

SECTION MODULE D:\CC\DBF\NET.C

MODULE D:\CC\TERM\ACCEPT.C

MODULE D:\CC\SUPPORT\OSDATE.ASM

#5 SECTION MODULE D:\CC\BASE\FGET.C

MODULE D:\CC\TERM\OLDBOX.C

MODULE D:\CC\TERM\OLDCLEAR.C

MODULE D:\CC\INITEXIT\RUN.C

MODULE D:\CC\BASE\SEND.C

MODULE D:\CC\DBCMD\JOINLIST.C

MODULE D:\CC\NUSASCII\SORTBLOC.C

MODULE D:\CC\DBF\SORTOF.C

ENDAREA

# Create overlay area 2

BEGINAREA

#6

SECTION MODULE D:\CC\EDIT\TBROWSE0.C

#7

SECTION MODULE D:\CC\EDIT\TBROWSE1.C

#8

SECTION MODULE D:\CC\MISCX\EXAMPLEA.ASM

MODULE D:\CC\DBF\DBF0.C

MODULE D:\CC\DBF\DTX0.C

MODULE D:\CC\INITEXIT\INITEXIT.C

MODULE D:\CC\SUPPORT\TXOPEN.C

MODULE D:\CC\TERM\BOX.C

MODULE D:\CC\STR\STRTRAN.C

ENDAREA

When placing modules into overlays, you must use extreme care to not overlay functions which are called by "interrupts" or may be called "recursively". Code which is called by interrupts is called by a direct vector rather than an overlay vector. This can cause computer lockup 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 in a do..while loop. If this function were placed in an overlay, you may experience considerable slowing 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, don't make any attempt to try to overlay it or you will experience runtime problems. Also, don't make an attempt to overlay "CA-Clipper code" because this code is automatically overlayed into "dynamic-pages".

A file named MEM52.LNK is provided on the diskette. This is a standard link-script for Rtlink that can save approximately 50k of conventional memory by just calling it from your existing link-script.

Overlaying Code with BLINKER

Overlaying the CA-Clipper libraries with Blinker is simpler than Rtlink because only one overlay area needs to be defined for all overlayable modules, files and libraries. Like Rtlink, Blinker will automatically overlay any code in any library that is compiled with the CA-Clipper compiler.

BLINKER OVERLAY OPSIZE 50

BLINKER PROCEDURE DEPTH 50

FI

LIB

OUTPUT

BEGINAREA

FILE

ALLOCATE

# Modules from CLIPPER.LIB

MOD accept,acopy,adel,aeval,ains,appinit,atail,box,cmem,date

MOD dbcmd2,dbcmd3,dbcmd4,dbcmd5,dbcreate,dbf0,dbfdyn,dbjunct

MOD dbstruct,dtx0,dtx1,dtxdyn,dynina,errsys0,errsys1,fget

MOD getenv,gets0,gets1,gets2,gx,joinlist,lupdate,memory

MOD mrelease,msave,net,oldbox,oldclear,philes,run,saverest

MOD sdf0,sdf1,seq,setcurs,sortbloc,startsym,tb,txopen,vall

MOD vblock,vdb,vdbg,version,vmacro,vnone,vops,vpict,vterm

MOD workarea,xmacro

ALLOCATE extend

ENDAREA

LIB clipper, terminal ,dbfntx

There are a standard set of link-scripts included with Blinker that make it very simple to overlay the Clipper 5.2 libraries. They are as follows:

CL520MIN.LNK - Used to overlay the smallest portion of the Clipper libraries for maximum speed performance but minimum memory performance.

CL520MID.LNK - Used to overlay a moderate portion of the Clipper libraries for moderate speed performance and moderate memory performance..

CL520MAX.LNK - Used to overlay the maximum allowable portion of the Clipper libraries for minimum speed performance by maximum memory performance.

These are sub link script files that can be simply included in your master link script file like so:

BLINKER OVERLAY OPSIZE 50

BLINKER PROCEDURE DEPTH 50

FI

LIB

OUTPUT

@CL520MAX.LNK

Blinker has become the standard for linking Clipper applications, so much of the third-party community also will include "ready-to-go" link-scripts with their libraries to make it easy to add their library to your application. For example, if you are already using a Blinker link script and decide to add the Six Driver (RDD) to your application, you would simply add one line of code to your link-script: