Microsoft KB Archive/81368

{|
 * width="100%"|

Building Static Overlays in an MS-DOS Executable File

 * }

Q81368

-

The information in this article applies to:


 * Microsoft LINK for MS-DOS

-

SUMMARY
In the MS-DOS operating system, an executable file can be as large as 1 MB; an executable file that contains overlays can be as large as 16 MB. Microsoft LINK can create overlays by dividing the application into a resident portion that is loaded when the application begins execution and overlays that are loaded into memory as needed. This method produces one .EXE file. This method reduces the memory required to run the program but increases the time required for overhead processing. The application also requires more disk space because it must contain code for the overlay manager.

For far calls from the resident portion to an overlay or between overlays, LINK substitutes the following sequence of code:

  int     IntNo         ; IntNo specified with /O, default is 3Fh DB     OverlayNum    ; The overlay number DW     OverlayEntry  ; Offset of the entry point The Interrupt instruction passes control to the static overlay manager which determines which overlay is called and if it is already loaded in memory. If the overlay is not in memory, the manager loads the overlay from the executable file.

MORE INFORMATION
To create an overlay using the Static Overlay Manager, surround the names of object modules with parentheses. LINK assigns individual segments to an overlay, not object modules. For example, consider the following LINK command line:

"link main.obj (mod1.obj mod2.obj) (mod3.obj);" The resident portion consists of the segments declared in MAIN.OBJ and any segments that do not have the class 'CODE' in MOD1.OBJ, MOD2.OBJ, and MOD3.OBJ. LINK assigns only segments of class 'CODE' to an overlay. The overlay to which a code segment is assigned is determined by the object module that first defines a segment. For example, of both MAIN.OBJ and MOD1.OBJ define a segment called &quot;ASEG,&quot; the data in ASEG defined in MOD1.OBJ becomes part of the resident portion of the application because ASEG was first defined in MAIN.OBJ.

LINK adds three segments to an overlaid program: OVERLAY_AREA, OVERLAY_DATA, and OVERLAY_END. The overlay manager loads each overlay into OVERLAY_DATA when it is needed. OVERLAY_END immediately follows OVERLAY_AREA to facilitate determining the size of the overlay area (subtract the segment address of OVERLAY_AREA from OVERLAY_END). LINK initializes the OVERLAY_DATA segment with information the overlay manager needs. OVERLAY_DATA is part of DGROUP.

The overlay manager code is stored in the OVLM6L module in the Microsoft language run-time libraries. LINK places this code into the _TEXT segment.

Each overlay in the executable file has an executable file header. The structure of the file created by the command line example above is as follows:

  -- |    .EXE header      |       Overlay 0h --      |                      |       |   Resident portion   | |        and          | |  overlay segments   | |                     |        --       |     .EXE header      |       Overlay 1h --      |                      |       |     Code segments    | |                     |        --       |     .EXE header      |       Overlay 2h --      |                      |       |     Code segments    | |                     |        -- At run time, the resident portion of the application initializes the overlay interrupt vector specified by the linker (by default, Interrupt 3Fh) with the address of the overlay manager. When the interrupt occurs, control transfers to the overlay manager. When the overlay manager loads an overlay, it retrieves the file name from OVERLAY_DATA, locates the overlay using information in the overlay's .EXE header, reads the contents of the overlay into OVERLAY_AREA, and transfers control to the overlay.

The memory image of an executable file that contains overlays is as follows:

 --+-> high memory address |                     |       |     ROOT (data)      | |                     |        --+-> OVERLAY_END |                     |       | OVERLAY AREA (code)  | |                     |        --+-> OVERLAY_AREA |                     |       |     ROOT (code)      | |                     |        --+-> low memory address Note:


 * The names of segments in an overlay must differ from the names of segments in the resident portion. To accomplish this with a Microsoft language product, compile the application for the medium, large, or huge memory model.
 * LINK /INCR[EMENTAL] does not support overlays.
 * The MS-DOS portion of a bound executable file cannot contain overlays.
 * Do not change the name of an executable file that contains overlays if it will run with MS-DOS versions prior to version 3.0.

The information in this article applies only to static overlays. For more information, refer to chapter 15 in the Microsoft C/C++ &quot;Environment and Tools&quot; manual for version 7.0. For information on the Microsoft Overlaid Virtual Environment (MOVE) that provides dynamic overlays, refer to the MOVEAPI.TXT file provided with C/C++ version 7.0.

For Visual C++, refer to either the Comprehensive Index or Books Online for detailed information about overlaid programs using either the Static Overlay Manager or MOVE.