                         IMP Core Environment Standard

                        Section 15: New include Facility
           *** WILL BE SHIFTED OUT OF STANDARD AS OF NEXT EDITION ***

       This section defines the extended include facility now becoming
    available on 3L-IMP compilers.  This section, like the "language
    implications" section, will be removed elsewhere when we have a proper
    place in which IMP language definitions can reside.

    15.1 Availability

    The facilities described in this document are available on all systems
    which use version 9.10 or above of the IMP first pass.  Currently these
    are:

          Imp/Ns          (NS32000 Panos)
          Imp/Ns/SysV     (NS32000 Unix System V, eg Opus5)
          Imp/Mg          (NS32000 Genix)
          Imp/42nix       (NS32000 42nix)

          Imp/PeOs        (PE3200  Os/32)
          Imp/PeUnix      (PE3200  Unix Edition VII)

          Imp/New         (VAX-11  VAX/VMS)
          Imp/New/Unix    (VAX-11  UNIX 4.2BSD)

          Imp/Apollo      (M68000  Aegis)
          Imp/Sun         (M68000  Unix 4.2BSD)

    The extended facilities are neither available or planned for the
    following implementations, which are regarded as obsolescent and will be
    replaced with conforming implementations in due course:

       Vax IMP (version 6 or 8)
       Apollo  (Dewar compiler)
       IBM     (old compiler)

    15.2 Rationale

    These new facilities have been introduced in order to make it easier to
    use include files for all the well-known reasons without making source
    programs system-dependent.

    The existing include statement has the problem that it requires a
    literal file name string.  Inevitably this string becomes
    system-dependent which means that porting the program will necessitate a
    source change.

    The extension to include solves this problem by using symbolic names for
    the files which are to be included.  On particular systems a small
    system-dependent module in the compiler translates these symbolic names
    into the appropriate actual file names.

    15.3 Definition

    IMP include statements come in three forms:

       (i)      "include" string constant [ "list" ] ;
       (ii)     "from" module id "include" item list [ "list" ] ;
       (iii)    "include" item list [ "list" ] ;

    Examples:

    (i)   include "specs.inc" endoflist
          include "SYS$LIBRARY:nasty.inc"

    (ii)  from LL   include COMMON, FIXEDRULES
          from IMP  include ASCII, EBCDIC endoflist

    (iii) include FRED, JIM
          include FORMATS, ROUTE endoflist

    Form (i) is also available in previous implementations.

    Forms (ii) and (iii) are new.  In (ii), "module-id" is an IMP identifier
    and "item-list" is a list of items separated by commas where each item
    is an IMP identifier.  Form (iii) is a version of (ii) where the
    module-id is a private one meaning "in the current place".  This would
    normally be taken to mean the currently selected (default) directory on
    systems which support such a concept.

       Apart from their uses in the include statement the identifiers are
    ignored, in particular they will not clash with other local identifiers.

    15.4 Scope

    The new forms of include statement are considered to have a scope in the
    same way that identifiers have a scope.  This scope is used to inhibit
    the multiple inclusion of files.  An include statement, or part of it,
    will be ignored if a previous include which is still in scope caused the
    inclusion of a file identified by the same module-id and item-id.  Note
    that as the old form of include statement does not include a module-id
    or item-id, they will be included each time they are encountered in the
    source.

    For example assume that the files identified by A, B and C (in a manner
    as yet unspecified) have the following contents:

    File A:   recordformat F(integer x, y, z)
              endoffile

    File B:   include A
              externalroutinespec Print Record(record (F) name R)
              endoffile

    File C:   include A
              externalroutinespec Read Record(record (F) name R)
              endoffile

    The following sample program is then quite valid:

    begin
       routine Process
          include B
          include C   {this will not include A again}
          include B   {this will do nothing}
       end
       routine Analyse
          include B   {this will cause A and the spec of}
                      {Print Record to be included}
       end
    endofprogram

    15.5 Implementation

    The mapping between the pair (module-id, item-id) and the external
    object to which the pair corresponds is implementation defined (DEF0008;
    mapping of include facility).  Note that the external object need not be
    an operating system file; it may, for example, be an element in a text
    library or internal to the compiler itself.  The two module-ids IMP and
    SYSTEM are reserved over all systems to have special meaning.  The
    module-id IMP is reserved for use by the core environment standard.  The
    module-id SYSTEM is reserved for use by individual implementors, for
    example to provide interfaces to operating system facilities.

    15.6 Example

    On the Vax/VMS implementation the following two complete programs would
    be identical.

    begin                        begin
       from IMP include MATHS,      include "IMP_INCLUDE:MATHS.INC"
                        ASCII       include "IMP_INCLUDE:ASCII.INC"
       <text of program>            <text of program>
    end of program               end of program

    For form (ii), the VAX/VMS implementation generates a filename of the

    form:

       module-id _INCLUDE: item-id .INC

    For form (iii), the VAX/VMS implementation generates a filename of the
    form:

       item-id .INC

       The above rule for form (ii) may be overridden by means of an
    environment definition file.  The Lattice installations use this to
    separate the IMP include files for the VAX compiler from those of other
    target implementations.

    15.7 Error Conditions

    For implementation reasons the following two errors could be generated:

            1.      Include files nested too deeply.
                    Currently the limit of nesting of include files is 5.
                    This limitation is imposed by the "old" style of
                    non-nesting OPEN in the VAX run-time system.  This
                    limitation will be lifted when no such run-time systems
                    remain available.

            2.      File <file-id> has not been included.
                    This is caused by an include statement with a list of
                    items where after the processing of one member of the
                    list the scope (textual level) has changed from that of
                    the whole include statement.  This is caused by
                    including files which contain unmatched BEGIN, END or
                    procedure statements.  If this effect is really wanted
                    it can be achieved by splitting the include statement
                    into two or more.
                    That is, instead of writing:

                           from LL include GATEBITS, ROUTEBITS, DRAWBITS

                    write: from LL include GATEBITS
                           from LL include ROUTEBITS
                           from LL include DRAWBITS