*line   1: Unknown output type = 
>$A invert=0; cap=0; capsh=0; und=0; undsh=0







           A P M   I M P   P R O G R A M M E R ' S   G U I D E






This manual describes the implementation of the IMP programming language for the
APM and includes a description of the main library modules which are available
to the programmer.
Definition of Language
______________________

   The IMP language as implemented on the APM is the agreed version for forward
development on the VAX/VMS and M68000 systems.  It is substantially as defined
in the EUCSD Report "The IMP77 Language" (3rd Edition), with the following
exceptions.


Discarded features:
     .   non-decimal constants expressed in IBM style (X'...')
     .   %name %function as alternative to %map
     .   loops with a control clause after as well as before (ie an %until as
         well as a %while or %for)


Modified features:

     .   the declaration of %arrayname parameters requires the specification of
         bounds either as literals or as declared local variables, as
         illustrated in the following examples:
                 %integerarrayname a(1:1000)
                 %realarrayname delta(10:20,1:30)
                 %bytearrayname used(1:%integer xdim,1:%integer ydim)
                 %shortarrayname count(%byte lo:%byte hi)
         in order to match the formal parameter, an actual array must have been
         declared with at least as many dimensions and with identical literals
         where the formal has literals.


Added features
     .   there are a number of additions which make it possible to exercise
         greater control over the way in which variables are allocated and
         parameters are passed; these are not of general utility and are not
         described here.


Variant implementation
     .   the effect of %continue is to pass control to the head of the
         containing loop, where any %while or %for control clause is tested; any
         %until clause at the end of the loop is ignored.
Implementation restrictions
___________________________

            The range of integers handled is the 32-bit signed twos-complement
         range.  Apart from type-checking, the declaration %longinteger is
         treated as equivalent to %integer.
         Both signed and unsigned (%short and %half) 16-bit integers are
         supported, the former slightly more efficiently.
         Both signed and unsigned (%mite and %byte) 8-bit integers are
         supported, the former slightly more efficiently.

            In the present implementation, floating-point numbers are limited to
         32-bits and the operations on them are implemented by software.  Apart
         from type-checking, the declaration %longreal has the same effect as
         %real

            The maximum number of nested textual levels permitted is eight.  In
         this respect, no distinction is made between procedures and %begin/%end
         blocks.

            The maximum number of nested conditionals or loops is fifteen.

            A strict rule of ordering between the declarations and instructions
         in a block is not imposed, but the following restrictions apply:
No declarations are permitted within conditionals or loops;
Only static declarations (%const, %own, %external and procedures)
are permitted to follow instructions which include a forward
jump or procedure call;
The specifications for %external procedures and data objects must appear
in the outermost level or main %begin/%end block.

         Features of IMP77 which are not valid in IMP80 (EMAS IMP) and
         conversely, or which are peculiar to this implementation, are reported
         as 'non-standard' (warning only).  However, this warning is not
         produced for the following widely used IMP77 facilities, even though
         they are not available in IMP80:
        %shortintegers, %predicates, %else %if, operator mod-sign,
        initialisation of dynamic variables to literal values
        (but initialisation to non-literal values is flagged).

!<Calling the Compiler
         The Compiler is invoked by the command IMP.  There is only one
         obligatory parameter and that is the name of the IMP source program to
         be compiled.  There is no default extension for the source file-name.

         Error reports are directed to the terminal.  Line-numbering continues
         through any included files.

         Unless otherwise directed the Compiler generates a code file with the
         same name as the source file and extension MEX (for Motorola executable
         file).  The code file is eligible for execution by citing the name as a
         command verb.  No linkage operation is required.

         For example, the system command IMP MYFIRST calls for the source file
         "MYFIRST" (no extension) to be compiled as an IMP program, creating the
         file "MYFIRST.MOB".  On successful completion of the compilation, the
         command "MYFIRST ...." becomes available as a system command, and
         causes the object program to be loaded and entered.
!>
!<Options
         There are a number of options affecting the way in which the Compiler
         processes the source program.  Modifications to the default choices may
         be selected by including appropriate keywords in the parameter string.
         These are introduced by a dash (minus).

         The main options are given below.  Those not yet implemented are marked
         with an asterisk, and those only partially implemented with a query.
         In the case of the yes/no options, the option is suppressed by
         selecting the keyword prefixed with "NO".

 Source listing control:
      -LIST=<filename>    produce listing to specified file
                          (extension LIS)
      -LIST               produce listing to file with same name
                          as source and extension LIS
      -LIST               produce listing to network printer
      -NOLIST             do not produce listing
      -LOG                output statistics indicating number of statements,
                          atoms per statement, identifiers per statement,
                          time taken, etc.
   Default: -NOLIST-NOLOG

 Object program control:
      -OBJ                produce object file with same name as source
                          and extension MOB
      -OBJ=<filename>     produce object file with specified name
                          (default extension MOB)
      -NOOBJ              do not produce object file
   Default: -OBJ (but only if no errors reported)

 Run-time checks:
  ?   -ASS       include unassigned check on full integers
  ?   -STRASS    include unassigned check on strings
  ?   -SASS      include unassigned check on shorts
  ?   -BASS      include unassigned check on bytes

  ?   -ARR       include array bound checking
  *   -LOOP      include %for loop check
  *   -OVER      include overflow check
  *   -CAP       include capacity checking
  Default: -ASS-STRASS-NOSASS-NOBASS-ARR-LOOP-OVER-CAP
           -NOCHECK has the effect of suppressing all checks


 Run-time diagnostics:
      -DIAG         include line-number updating for diagnostics
      -TRACE        generate code which allows the program to
                    be executed one line at a time under the
                    control of the Software Front Panel
  Default: -NODIAG-NOTRACE

!>
!<Omissions
         Omissions in current release -- to be added:
 .  full diagnostics and %monitor
 .  %begin/%end blocks
 .  procedures as parameters

Variant features [provisional]
 .  %continue by-passes any test on the %repeat at the end of a loop
 .  Array name parameters must have bounds specified in the declaration
    [eg %byteintegerarrayname a(0:31) or %integerarrayname b(1:%integer n)]
    ** In the present compiler only the first form (with literal bounds,
    ** one-dimension) is accepted.  However, actual parameters with the
    ** specified LOWER bound will work irrespective of the actual upper bound.

Omitted features which may be added:
 .  %label declarations

Omitted features which are unlikely to be added:
!>
!>
!<External linkage (May 83)
         The external linkage mechanism provides for the use of program modules
         or libraries containing externally accessible procedures or variables.

         A program module containing external procedures or variables, and
         terminated by %endoffile, is compiled in the ordinary way, eg IMP
         MYLIB.  Before the externals it contains can be accessed, the compiled
         module must be installed by the INSTALL command.  The INSTALL command
         takes as parameter the name of a program file (extension MOB assumed)
         -- or list of names separated by commas.  For example INSTALL MYLIB.
         The effect of installing a program file is to add all the external
         names it contains to the external symbol table; the code of the module
         is not loaded at this stage.  Thereafter (until logoff) these names are
         available for external linking, which is done automatically when a
         program referencing any of the names is loaded.  It is only necessary
         to re-install a program file if a change is made to the external names
         it contains.

         The system command HELP LIB gives information about generally available
         libraries.

!<Restrictions on externals
         The following restrictions apply to the current implementation:-

1.  Names are truncated to 11 characters for purposes of matching as externals.
2.  The type checking is nominal.
3.  External %name variables are not supported.
4.  External specs must all be at the top program level, that is, they may not
    appear within procedures or inner blocks.
5.  An external spec for a procedure may be satisfied by a procedure occurring
    later in the same module, but the same is not true for variables.
6.  Externals may not be combined with a main program (%begin ...
    %endofprogram).

CAUTION: The final form of external linkage will certainly differ from this
    interim form, necessitating re-compilation.
!>
!>
!<Permanent procedures
The permanent procedures listed below are available without specification.
These are generally as provided on Vax, with exceptions and additions noted.
Terminal output is direct, so that there is no need for any TTPUT or FLUSH
OUTPUT procedures.

!<Standard PERM

%integermap      INTEGER(%integer a)
%realmap         REAL(%integer a)
%string(*)%map   STRING(%integer a)
%record(*)%map   RECORD(%integer a)
%bytemap         BYTEINTEGER(%integer a)
%shortmap        SHORTINTEGER(%integer a)
%bytemap         LENGTH(%string(*)%name s)
%bytemap         CHARNO(%string(*)%name s, %integer n)
%integerfn       ADDR(%name n)
!PAGE
%string(1)%fn    TOSTRING(%integer k)
%string(255)%fn  SUBSTRING(%string(255) s, %integer from,to)

%integerfn       REM(%integer a,b)

%integerfn       INTPT(%real x)
%integerfn       INT(%real x)
%realfn          FRACPT(%real x)
%realfn          SQRT(%real x)

%string(8)%fn    DATE
%string(5)%fn    TIME
%integerfn       CPUTIME  
                 !in milliseconds (actually elapsed time at present)

%record(*)       NIL
%recordformat    EVENTFM(%integer event,sub,extra,pc,
                 %string(255) message,%integerarray r(0:15))
                 !PC and R are APM-specific extensions
%record(eventfm) EVENT
!PAGE
%constinteger    NL
%integerfn       NEXTSYMBOL
%routine         READSYMBOL(%name n)
%routine         PRINTSYMBOL(%integer k)
%routine         SKIPSYMBOL
%routine         PRINTSTRING(%string(255) s)
%routine         READ(%name n)
%routine         WRITE(%integer m, n)
%routine         PRINT(%real x, %integer n,m)
%routine         PRINTFL(%real x, %integer n)
%routine         NEWLINE
%routine         NEWLINES(%integer i)
%routine         SPACE
%routine         SPACES(%integer i)
%routine         SELECTINPUT(%integer n)
%routine         SELECTOUTPUT(%integer n)
%routine         RESET INPUT
%routine         RESET OUTPUT
%routine         CLOSE INPUT
%routine         CLOSE OUTPUT
!PAGE
%integerfn       INSTREAM
%integerfn       OUTSTREAM
%routine         OPEN INPUT(%integer n, %string(31) S)
                 !*selects N at present*
%routine         OPEN OUTPUT(%integer n, %string(31) S)
                 !*selects N at present*
%routine         PROMPT(%string(31) S)
%integerfn       TESTSYMBOL
                 !*APM specific*
                 !value is -1 if no symbol available from terminal
                 !otherwise value is the symbol, which is skipped

%constinteger    NOECHO,NOTERMECHO,SINGLE,NOPAGE
%routine         SET TERMINAL MODE(%integer m)
                 !*APM specific*
                 !set terminal mode as specified by M (sum of flags)
!>
!>
!<Compiler limits
The following limits apply in the current release:

1. The maximum length of a source line including continuation lines
   is 512 characters (lines following comma-terminated lines do not
   count as continuation lines).
2. The depth of textual nesting of procedures is limited to between
   three and six levels, depending on what the procedures get up to.
3. The number of parameters to a procedure may not exceed five
   numeric values and four non-numeric value or name parameters.
4. The total size of the static data area (for owns/externals) is
   limited to 16k bytes.
5. The size of the code area (for program and constants) is limited
   to 64k bytes.  In addition, there is no escape from the machine
   limited reach of +-32k bytes for accesses to constants.
   The compiler does automatically cater for procedure calls which
   would otherwise run into this limitation, but this does not apply
   to calls made from the main program block.
!>
!<Known Defects
Compiler bugs:

Statements like "%if COND %then %result = EXP1 %else %result = EXP2" are liable
to be mis-compiled.  Fix: change "%else" to ";".

The use of certain compound expressions as argument to one of the store-mapping
functions causes mis-compilation and the error report "Faulty operand" or
"Internal error".
Fix: assign the expression to a simple variable and use that.

Run-time deficiencies:

The general level of checking for run-time errors is fairly low in this release,
since the main priority is to permit already developed programs to be moved
across to the APM.
The unassigned variable check is not foolproof and may allow certain unassigned
variable references to slip through.
The array bound check is applied only to arrays with dynamic (or very large)
bounds.
There is no run-time check on the validity of %for loops.
There is no run-time capacity checking.


Please report any difficulties by Mail (not Notify) to HMD, giving the name of
the source file (which should be permitted) and a brief indication of the nature
of the trouble (eg 'Address error at compile-time' or 'Spurious Event 8 at
run-time').

Note that object code conventions are provisional and the source of all programs
should be retained in case they require to be re-compiled.


Program stopped