Microsoft KB Archive/51416

= How to Use Link Overlays in Basic PDS Versions 7.0 and 7.1 =

Article ID: 51416

Article Last Modified on 8/16/2005

-

APPLIES TO


 * Microsoft BASIC Professional Development System 7.0
 * Microsoft BASIC Professional Development System 7.1

-



This article was previously published under Q51416



SUMMARY
When using the linker (LINK.EXE) to generate code overlays for Microsoft Basic Professional Development System (PDS) version 7.0 or 7.1 under MS-DOS, you must put the modules you want to overlay in parentheses on the LINK command line. The modules that make up one overlay must be compiled with the same switches. Code is the only part of the program that is overlaid. Data is not overlaid. In an overlaid program at run time, all modules not linked inside parentheses stay fixed in one area of memory, and in the remaining area of memory, only one called overlay is resident at a time. Examples and further restrictions for using linker overlays are given below.

Note that link overlays are not needed and not supported under OS/2 protected mode, because OS/2 itself automatically provides a similar feature to support swapping of very large .EXE programs in OS/2 extended and virtual memory.



MORE INFORMATION
The following is an example of how to produce code overlays LINK test1+(test2+test3)+test4+(test5)+(test6),TEST1.EXE,TEST1.MAP; where the following apply:


 * 1) test1 (that is, TEST1.OBJ) is the main module.
 * 2) test2 and test3 (TEST2.OBJ and TEST3.OBJ) are separately compiled modules that make up one overlay. Object modules that call one another frequently can be linked into the same overlay for faster performance. Otherwise, calling a module located in another overlay requires a disk access to swap in the next called overlay.
 * 3) test4 (that is, TEST4.OBJ) stays resident in memory along with the main module test1 at run time and is not swapped out of memory to disk.
 * 4) test5 and test6 (TEST5.OBJ and TEST6.OBJ) are two separate overlays.
 * 5) TEST1.EXE is the executable overlaid program created by this LINK.
 * 6) TEST1.MAP is a text file (created by the above LINK) that tells you the code sizes of all overlays and procedures.

To invoke an overlay, you call a SUB or FUNCTION in a module contained in that overlay, and the Overlay Manager automatically moves the overlay (if it is not already loaded) into the single overlay area. The single overlay area is the MS-DOS memory that remains after the main program, nonoverlaid code, MS-DOS, and resident software (if any) are loaded. Only one overlay can be resident in memory at a time. When called at run time, each called overlay overlays the previous overlay (if any) resident in the overlay area in MS-DOS memory.

You can call any module or overlay from any other module or overlay.

Overlays provide an alternative to CHAINing when a program is too large to fit into memory all at once. An overlaid program is made up of a single .EXE file (which can be an advantage in some cases), unlike CHAINed programs, which are composed of several .EXE files.

Restrictions on Using Overlays
The restrictions on using overlays in Microsoft Basic PDS versions 7.0 and 7.1 for MS-DOS are as follows:


 * Each Microsoft Basic overlay cannot exceed 256K in code (see LINK .MAP for size of each overlay). You can have up to 64 overlays per .EXE program. This means you may be able to make .EXE programs up to 16 MB in code size under MS-DOS.
 * The main module must be the first module in the LINK command line, and it must NOT be specified as an overlay. If you incorrectly make the first module in the LINK command line an overlay, the machine will hang when the program first loads.
 * When you create an overlaid version of a program, make sure that each module contained in the program is compiled with the same options.
 * You cannot use the LINK /PACKCODE or /EXEPACK option when linking a program that uses overlays.
 * You cannot have a stub file as an overlay. Do not specify stub files (NOxxx.OBJ) in the parentheses for link overlays, or the program will hang. Stub files may only be specified outside parentheses in the LINK command line.

Using Expanded Memory with Overlays
386Max (386MAX.SYS) from Qualitas, Inc. is an example of an expanded memory driver that can be used with Basic PDS 7.0 and 7.1. Basic PDS 7.0 and 7.1 require an expanded memory driver that uses the Lotus-Intel-Microsoft (LIM) version 4.0 Expanded Memory Specification (EMS).

If you have loaded an expanded memory driver, and if all the overlays can fit together at one time in expanded memory, and if each overlay has less than 64K of code, then overlays are loaded from expanded memory. Otherwise, overlays are swapped from disk, which is slower than loading from expanded memory.

Assume that the overlaid program satisfies the above conditions for using expanded memory. Note that the overlaid modules are not loaded when the .EXE file is first invoked; they remain on disk until the first overlay is called. When this occurs, all the overlaid modules are loaded at once from disk into expanded memory. From then on, the overlays are swapped from expanded memory into MS-DOS memory, and the disk is no longer used for loading overlays.

The overlay manager in Basic 7.0 and 7.1 requests expanded memory in 16K pages (blocks). The overlay manager only knows the size of the largest overlay, and must make a &quot;best guess&quot; at the size of the smaller overlays. When the overlay manager estimates how many 16K pages are necessary to hold all overlays at once in expanded memory, the estimate could be over or under the actual number of pages needed. If your overlays are all between 16K and 64K in size (according to the LINK .MAP file), and if the estimated or actual size of all overlays together exceeds the available expanded memory, the following initialization error occurs when the first overlay is called at run-time:

Insufficient EMS to load overlays

NOTE: This error is documented on page 656 of the &quot;Microsoft Basic 7.0: Language Reference&quot; manual for versions 7.0 and 7.1. You will never see this error if all your overlays are smaller than 16K each.

If you want to force loading overlays from disk, thus avoiding the possibility of this overlay initialization error in expanded memory, you must link with the stub file NOEMS.OBJ (with no parentheses around NOEMS.OBJ on the LINK command line). Alternatively, you can try reconfiguring expanded memory so more of it is available for Basic overlays. Another alternative is to make overlays similar in size.

MS-DOS Memory Map when Using Overlaid .EXE Program
[Low Memory]


 * MS-DOS
 * Main program and non-overlaid modules
 * Contiguous overlay memory area, equal to the size of biggest overlay
 * DGROUP (default data segment, which is shared by all routines)
 * Far heap (dynamic non-variable-length-string arrays)
 * Basic run-time support module if .EXE not compiled stand-alone (BC /O)

[High Memory]

For more information on using overlays, see the following:

&quot;Microsoft Basic 7.0: Programmer's Guide,&quot; versions 7.0, 7.1, pages 612-614

Additional query words: BasicCom 7.00 7.10

Keywords: KB51416

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.