Click above to get retro games delivered to your door ever month!

Specifying Overlays
-------------------------------------------------------------------------------------

 To use overlays, you must link in the object module containing the runtime
 overlay manager that is supplied on the WarpLink diskette.  To specify which
 object modules or libraries are to be overlaid, place their names in
 parentheses and follow the standard format for using WarpLink. The following
 example show how to specify use of overlays with WarpLink:

 WARPLINK /OP:M NONOVL (OVL1+OVL2) (OVL3) (OVL4) OVLMGR,OVLPROG,,LIB1 (LIB2)

 This example creates the program OVLPROG.EXE from the object modules
 NONOVL.OBJ, OVL1.OBJ, OVL2.OBJ, OVL3.OBJ, OVL4.OBJ and
 OVLMGR.OBJ, and the libraries LIB1.LIB and LIB2.LIB.  All object modules
 except NONOVL and OVLMGR are placed into overlays, along with the LIB2
 library.

 Nonoverlaid code is said to be in the root.  In this example, code from
 NONOVL.OBJ, OVLMGR.OBJ, and LIB1.LIB is in the root.

 Clipper 5 
 Users
 Use the overlay manager object module named C5OVLMGR.OBJ on the
 WarpLink diskette.

 Clarion 2.1 
 Users

 Use the overlay manager object module named CNOVLMGR.OBJ on the
 WarpLink diskette.

 Note

 All other languages, including Clipper Summer '87, require the standard
 OVLMGR.OBJ overlay manager object module when using overlays.  


 Performance Issues

 Using overlays has one drawback.  Programs incur a slight speed penalty 
 when they are used.  Since dynamic overlays are transparent to the 
 executing program, the overlay manager takes extra time to determine
 whether or not a specific overlay is already in memory when it is called. 
 If the overlay has been loaded, then only a slight increase of time is
 required, i.e., a few microseconds for each overlay call.  If the overlay
 is not loaded, however, the delay can be more significant.  The time
 depends upon where the overlay file resides, i.e., a hard disk, a floppy 
 disk, EMS, or XMS.  Overlay size also affects how fast overlays are loaded.
 A fast hard drive,EMS, and XMS usually require loading times of a few 
 milliseconds.  A floppy-based system with moderately large overlays can 
 require a second or more.

 The WarpLink overlay manager is designed to keep those overlays that are 
 used most often in the overlay pool as much as possible in order to reduce
 loading delays. You can reduce delays by stashing overlays in EMS and XMS
 for fast access.  Also try to keep your code modular and place overlaid
 routines in smaller modules.  Large overlays force more overlay swaps in
 the overlay pool and reduce runtime efficiency, as well as require a larger
 overlay pool.  Try to keep your overlaid routines under 20K. (This can be
 checked by looking at segment sizes in the WarpLink map file by using the /m
 or /mx options.) When linking with overlays, WarpLink will print the largest
 segment size when it prints the minimum overlay pool size -- this usually
 corresponds to a module, function, or procedure name.  Object module size 
 is not always a good indicator of overlay size.  With Clipper and Clarion
 code, for example, an object module can contain several segments that each
 go into their own overlay. Each procedure or function is a separate segment.

 Several WarpLink overlay options may be fine-tuned for better program 
 performance when using overlays.  Use the WarpMod utility and the WarpSpeed
 profiler to test overlay performance.  

 Refer to Chapter 6, WarpLink Options; Chapter 8, WarpMod Utility; and
 Chapter 9, WarpSpeed Profiler, for more information.

 Technical
 Notes

 There are several types of code and modules which cannot be overlaid,
 including interrupt-handler routines and self-modifying code.  Refer to
 the Overlay Technical Information section in Chapter 20, Common
 Questions and Answers About WarpLink, for a more detailed discussion
 about the types of code that cannot be overlaid.

 Only subroutines, procedures, and functions that are called and returned
 may be overlaid. (This includes all Clipper-compiled code.)  The overlay
 manager stores return addresses on its internal stack when calling an
 overlay.  Jumps from one overlay to another do not properly restore this
 stack.

 The overlay manager assumes all code segment names end in 'CODE'
 except for Clarion.  (Refer to the /cla option).  If you use another
 segment name for your code, you must use the /oc option.

 Do not place startup code in an overlay.  The overlay manager needs a
 fixed code address to begin program execution.

 If you are using small model code overlays, or your program contains
 overlays that call the root and then are swapped out by overlays called
 from the root, you may need to use the /r option or specify the overlays
 with brackets ([ ]).  Refer to the Small Model Code Overlays and
 Overlay to Root Call Vectoring in Chapter 18, Other WarpLink
 Features, for more details.

 Place the overlay manager (OVLMGR.OBJ, C5OVLMGR.OBJ or
 CNOVLMGR.OBJ) in the root.  It cannot be overlaid.