$a include=template_file

$n$lm
IMP Core Environment Standard
$b2$lm
Section 15: New %include Facility
$a sectno=15; pageno=1
$a indent=0

$lm
*** WILL BE SHIFTED OUT OF STANDARD AS OF NEXT EDITION ***

$p 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.




$b4$v5$l
15.1 Availability
$b 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:
$b$v5$l0
      Imp/Ns          (NS32000 Panos)
      Imp/Ns/SysV     (NS32000 Unix System V, eg Opus5)
      Imp/Mg          (NS32000 Genix)
      Imp/42nix       (NS32000 42nix)
$b0

$b$v5$l0
      Imp/PeOs        (PE3200  Os/32)
      Imp/PeUnix      (PE3200  Unix Edition VII)
$b0

$b$v5$l0
      Imp/New         (VAX-11  VAX/VMS)
      Imp/New/Unix    (VAX-11  UNIX 4.2BSD)
$b0

$b$v5$l0
      Imp/Apollo      (M68000  Aegis)
      Imp/Sun         (M68000  Unix 4.2BSD)
$b0


$b 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:

$b$v5$l0i
   Vax IMP (version 6 or 8)
   Apollo  (Dewar compiler)
   IBM     (old compiler)
$b0

$b4$v5$l
15.2 Rationale
$b 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.

$b 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.

$b 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.

$b4$v5$l
15.3 Definition
$b IMP include statements come in three forms:
$l0i

   (i)      "_i_n_c_l_u_d_e" string constant [ "_l_i_s_t" ] ;
   (ii)     "_f_r_o_m" module id "_i_n_c_l_u_d_e" item list [ "_l_i_s_t" ] ;
   (iii)    "_i_n_c_l_u_d_e" item list [ "_l_i_s_t" ] ;

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

$v8
$b Form (i) is also available in previous implementations.
$b 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.

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




$b4$v5$l
15.4 Scope
$b 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.

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

$l0

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

$v15
$b The following sample program is then quite valid:

$l0i

%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
$b0




$b4$v5$l
15.5 Implementation
$b 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.




$b4$v5$l
15.6 Example
$b On the Vax/VMS implementation the following two complete
programs would be identical.

$l0

%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

$b For form (ii), the VAX/VMS implementation generates a filename of the form:
$l0i

   module-id $_INCLUDE: item-id .INC

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

   item-id .INC
$b0

$p 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.




$b4$v5$l
15.7 Error Conditions

$b For implementation reasons the following two errors could be generated:

$a indent=2
$b$t1 1. $t2 Include files nested too deeply.
$b0 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.

$b$t1 2. $t2 File <file-id> has not been included.
$b0 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.
$v9
That is, instead of writing:

$l0i

       %from LL %include GATEBITS, ROUTEBITS, DRAWBITS

write: %from LL %include GATEBITS
       %from LL %include ROUTEBITS
       %from LL %include DRAWBITS
$b0