Developing 16-bit DOS programs

To develop a DOS program you simply use the standard and StonyBrook runtime library modules in your program.  There are no special considerationsfor normal DOS development.


Overlaying is a method of reducing the memory requirements ofa program by allowing different parts of the program to share the same memory space. Only the overlay that is currently executing must be in memory.  The othersare on disk and are read as they are needed.  This saves memory.

Overlaying is supported by the linker, SBLink.  To overlaya program you must include an EXE definition file when linking the program.  TheEXE definition file defines the structure of the overlaid program.

SBLink supports 2 distinct overlay systems, static overlays andvirtual overlays.  These are supported for 16-bit DOS applications ONLY.

With static overlays, overlay code is loaded into designatedAREAs.  This gives the user the ability to designate which module or group ofmodules constitute "overlays" for each AREA.

Virtual overlays require only an overlay buffer and a list ofindividual modules to be overlaid.  The overlay manager will dynamically loadoverlays as required with dynamic buffer management.

Requirements for overlays

All exported procedures from a module included in an overlaymust be called by a far call instruction.  Normally this is done by using theLARGE code model when compiling the module.  

Each object that you place in an overlay must specify the Overlaycompiler option.  This ensures that the generated code is compatible with overlaying.

There is no restriction on the calling of procedures betweenoverlays.  Even overlays in the same area may call each other.  The overlayloader maintains a stack of return addresses so that the caller can always be restoredbefore returning.

Linker definition files

An linker definition file providesadditional information about a program to the linker.

The linker definition file is a free form ASCII file, the sameas a source file.  Tabs and line endings are treated as spaces.

To define a static overlay structure, use two statements in alinker .EXE definition file: an AREA statement and multiple OVERLAY statements. Todefine a static overlay structure, use two statements in a linker .EXE definitionfile: an OVERLAY statement and multiple OVERLAY statements.

Static Overlays

The linker allows up to 255 overlays.  Each overlay is assignedto an AREA, which is a designated region of memory.  All overlays assigned tothe same area share the same memory at runtime, and only one overlay is in memoryin each area at any given time.

Each overlay can contain one or more modules.  Only thecode segments of Modula-2 modules are affected by overlay.  The data is alwaysresident for all modules.  For modules that are not written in Modula-2, anysegment with the class CODE is overlaid when the module is mentioned in an overlaydirective.

The AREA statement

The AREA statement specifies that a new overlay area is started. The first overlay statement must be an AREA statement.  

See the static overlay example for the format of the AREA statement.

The OVERLAY statement

The OVERLAY statement defines a single overlay.  The overlayis defined by listing the modules that are included in it.  The format of theOVERLAY statement is:

OVERLAY ModuleName [ + ModuleName ];

ModuleName is the Modula-2 name of the module to be overlaid. When the linker is assigning object modules to overlays, it actually takesthe name from the object file, treating it as a file name, and compares the filename portion only to the ModuleName on the OVERLAY command.  Any object modulesthat match are placed in this overlay.

Static Overlay example

Virtual Overlays

Virtual Overlays consist of a single module per overlay, withall overlays loaded into an overlay buffer of user defined size.  With thissystem, a larger buffer allows more overlays to reside in simultaneously, thus yieldingfaster overlay performance.  Additionally, EMS memory can be used for overlays.

This overlay manager requires the overlay compiler option setto Yes for all modules in the application that can possibly call a procedure residingin an overlay.

Any code that can call a procedure residing in an overlay cannothave any Near procedure calls, and all called procedures must have a proper stackframe.  This necessitates having an overlay compiler option.  Additionally,system modules and compiler internal helper modules may not be overlaid.  Allother runtime library modules may be overlaid.

Some special features available in this overlay system are:

The VIRTUAL statement


BufSize is the size in bytes of the overlay buffer. The defaultis Zero (0), which means the minimum possible overlay buffer size. If BufSize isnon zero it is rounded up to the next 16k boundary if necessary. For example 24000would be rounded up to 32768.

NOEMS disables EMS memory usage for buffering and execution.Enable EMS usage for buffering and execution is the default.

NOEMSRUN disables execution of overlays in EMS memory. EnableEMS usage for buffering and execution is the default.  See, Advanced Usage ofthe Virtual Overlay Manager if your application uses EMS memory.

FA. FileAttribute is the DOS file attribute used by the overlaymanager when EXE file is opened in order to read the overlays.

attribute is a hexadecimal number. The default value for attributeis 20h, which allows operation over a network by multiple users.  An exampleof setting a FileAttribute of 20h follows:


PROGRAMEMS is an advanced feature which delays EMS usage untilthe application program allows EMS usage.  This is accomplished by calling theoverlay manager"s OVLPROGEMSINIT procedure.  See, VeryAdvanced Virtual Overlays Manager for a complete description.

The Overlay statement


All modules which are overlaid must have a separate OVERLAY statement. Each OVERLAY statement inherits the global values for EMS usage.

ModuleName is the name of the module to be overlaid.

NOEMS and NOEMSRUN have the same meaning and defaults as theirglobal counterparts but apply only to the individual overlay.

PRELOAD specifies that an overlay will be loaded into memoryat initialization time prior to execution of any user code.  Overlays with aPRELOAD specification are loaded from smallest to largest load image size until allPRELOAD overlays are loaded or the overlay manager runs out of memory.  If theoverlay manager runs out of memory during the PRELOAD process, the remaining overlayswill not be preloaded.

EXAMPLE: Virtual Overlaying

Suppose you have a program that contains a seven different calculatormodules (a different one for each day of the week).  You have just added theeight calculator module (holidays) and DOS complained that there is not enough memoryto load the program.  So you decide to overlay the program.

This can be accomplished with the following EXE definition file:


OVERLAY CalcMonday;
OVERLAY CalcTuesday;
OVERLAY CalcWednesday;
OVERLAY CalcThursday;
OVERLAY CalcFriday;
OVERLAY CalcSaturday;
OVERLAY CalcSunday;

You've set the buffer size to 32768 bytes.  NOEMSRUN wasspecified since this is the only known 4 function calculator using EMS memory andthe FileAttribute was set to 20h.  After some thought you decided to PRELOADthe Holiday calculator, since with a job like yours, every day is a Holiday.

Very Advanced Virtual Overlays