INCLUDE FILES, UNITS and OVERLAYS.
                    ฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿฿

Good economical programming makes use of as much existing material as
possible. With Turbo Pascal, version 3, that existing material was in the
form of Source Code ( i.e. files with extension .PAS ) and this source
code, called the Include File, was included with the user program in the
compilation process.
Include files can still be used, but Units consisting of compiled code are
clearly more attractive with version 6.0 of Turbo Pascal, especially as
they may be associated with Overlays and also with Objects.

Include Files.
ออออออออออออออ
The syntax for an Include File is   {$I filename}

This include directive ensures that the named file is included in the
source code of the main program at that point in the program. The
include file cannot be specified in the middle of a procedure or function,
but can appear at any point in the program between procedures or functions.
It is frequently placed at the end of the declaration part, as shown below:

Program LinFit;         {For a linear fit to given data}

Uses Crt, .....;
Var
   x,y,z     :real;
   ......

{$I FIT.PAS }           {Include the Least Squares curve fitting procedure}

Begin                   {Main program to provide the data, analyse it and}
   ...                  {then display it graphically
   ...
End.

The program FIT.PAS was included in the Turbo Graphics Toolbox, originally
supplied by Borland.

Units.
ออออออ
With Turbo Pascal, version 4 and onwards, the process of using existing
material can be improved still further by the use of Units. A Unit is a
piece of source code that can be compiled as a stand-alone entity. It
contains data and program code and provides an Interface between the
unit's code and data and other programs that will use that unit. Programs
and other units can use units.

The Unit LIMITKEY.PAS which compiles to a Turbo Pascal Unit (.TPU) file is
an example of a unit. It contains a procedure which ensures that only a
selected range of keys will be accepted as the reply to a prompt. The
procedure is:

   Procedure LimitChar(s : string; var Key : char; var Ekey : boolean);

where s is a string such as '1234567Qq' (see program KEYCHECK.PAS)
      Key is the character for a single key press
 and  EKey is a boolean (True of False) indicating whether an Escape
      sequence or an ASCII extended code, employing a key press along
      with either Escape, Shift, Ctrl or Alt is involved.

A Unit differs from an ordinary program in a number of respects:

1. The first line is   'Unit LimitKey'   and not 'Program .....'

2. A Unit has two sections  an Interface  and an Implementation.

   The Interface is a 'header' that makes the procedures and functions
   of the unit available to the program that uses the unit. It contains
   a Uses clause, if other units are used by the unit, and then a list
   of all the procedures and functions with all their parameters, as with
   the procedure LimitChar above. The information in the Interface section
   must be documented and made available to the user of the unit.

   The Implementation section contains all the code to implement the
   procedures and functions of the Interface section. Documentation for
   this section and the source code for a unit is not available to the
   user of the unit. It is therefore protected from external modification.
   Only for educational purposes is the source code provided as with the
   unit LIMITKEY.PAS

   All the procedures and variables declared in the Interface section are
   'public' and can be accessed from outside the unit.
   Any procedures, functions and variables used in the Implementation
   section but not declared in the Interface section are 'private' and
   cannot be accessed from outside the unit.

Writing your own units is described in detail in pages 68-72 of the User's
Guide. The standard units, including System, Crt, Dos, are described on
pages 66-67 of the User's Guide, whilst the 200 or more procedures and
functions contained in these standard units are documented in the Library
Reference, with a sample layout of the documentation given on page 3.

Unit modification dangers.
ออออออออออออออออออออออออออ
There is clearly a danger that the source code for a unit may be modified
at some stage without being recompiled, so that the .TPU file is out-of-
date. There are two ways to make sure that unit files are up-to-date, the
first makes use of the fact that DOS stamps all files with time and date.

The MAKE option tells the compiler to check the date and time of the source
code and the compiled unit file (.TPU), used by the main program. If the
source code was modified since the unit was compiled, the compiler will
recompile the unit to bring it up-to-date.

The BUILD option will recompile the source code of all units used by the
main program, without checking date and time, so making absolutely sure
that they are up-to-date.


Overlays.
อออออออออ
Overlays are parts of a program that share a common memory area, called the
Overlay Buffer, which is located between the Stack Segment and the Heap
(See page 210 of the Programmer's Guide).

Each Overlay consists of a Turbo Pascal Unit, and these overlay units are
controlled by an Overlay Manager, which is initialized by the OvrInit
procedure found in the standard Overlay Unit.

The Overlay Buffer defaults to a size large enough to hold the largest unit
that is overlaid and hence uses a minimum amount of memory, so that the
heap can have a maximum size.

When a program involving overlays is compiled an overlay file (.OVR) is
created along with the normal .EXE file. The .EXE file contains the
non-overlaid parts of the program, whilst the .OVR file contains all the
overlay units that will be swapped in and out of the overlay buffer
during program execution.

An overlay unit is similar to an ordinary unit except in the following
respects:

    1. All overlay units must include a {$O+} compiler directive to
       ensure that the generated code can be overlaid.
    2. The {$F+} compiler directive must be used to ensure that all
       procedures and function use the FAR call model.

       Thus {$O+,F+} should appear at the start of the unit declaration,
       as in the examples OVRDEMO1.PAS and OVRDEMO2.PAS

Programs that use overlays must include the following features:

    1.  The unit 'Overlay' must be declared in the uses clause before
        any other unit.
    2.  Initialize the overlay manager with a call to OvrInit and pass
        the name of the .OVR file, which should be the program name.OVR
    3.  Issue separate {$O unitname} directives for each overlay unit.
    4.  Test OvrResult after OvrInit calls (optional).

Thus the main program OVRDEMO.PAS, which uses the units OVRDEMO1.TPU and
OVRDEMO2.TPU includes the following lines:

{$F+,O+}
program OvrDemo;

uses
  Overlay, Crt, OvrDemo1, OvrDemo2;

{$O OvrDemo1}
{$O OvrDemo2}

  ....
  ....
  OvrInit('OVRDEMO.OVR');       { init overlay system, reserve heap space }
  if OvrResult <> 0 then
  begin
    Writeln('Overlay error: ', OvrResult);
    Halt(1);
  end;
  ....

The main program OVRDEMO.PAS then calls a procedure Write1 from unit
OVRDEMO1.TPU and then a procedure Write2 from unit OVRDEMO2.TPU

This program and these units are Borland's examples, with slight
modifications by Ron Shaw to give an indication as to which unit is in use.



INC&UNIT.TXT
Modified 18.1.93