$a invert=0; cap=0; capsh=0; und=0; undsh=0
$a line=80; page=0; top=0; bottom=0
$l
                            LIBRARIES
$p The function of libraries is to make available to programmers useful sets
of related definitions and procedures for use in the construction
of programs. In general, it is sensible to use a supported library
where one is available rather than writing ad hoc routines.
$p The main libraries are callable from both IMP and Pascal, with
different include files for the two languages available in the directory
INC -- the IMP versions have file-name extension .IMP and the Pascal
versions have the extension .PAS.
The relevant include file should be consulted for details of the
parameter types in language-specific terms.
$p For details of the pre-defined procedures available in a particular
language, see the documentation for the language concerned.
$b $l1
!<INC:UTIL
$l0
General Utility Procedures: Miscellaneous

Procedure READ LINE(Var S:String)
          Read line from current input stream to string S;
          leading spaces are not skipped;
          the terminating newline is read but not included in the string

Procedure PRINT LINE(S:String[255])
          Print string S followed by a newline on current output stream

Function  MULDIV(a,b,c:Integer):Integer
          Result is A * B Div C   without overflow hazard computing A * B

Function  ITOS(value,places:Integer):String[255]
          Integer to string (arguments as for IMP WRITE)

Function  STOI(S:String[255]):Integer
          String to integer

!PAGE
General Utility Procedures: Miscellaneous (cont)

Procedure TO LOWER(Var s:String)
          Convert all upper-case letters in string S to lower
Procedure TO UPPER(Var s:String)
          Convert all lower-case letters in string S to upper

Function  FREESTORE:Integer
          Amount of stack space currently free (in bytes)
Function  DATE:String[8]
          Current date in form DD/MM/YY
Function  TIME:String[5]
          Current time in form HH:MM

!PAGE
Procedure PHEX1(x:Integer)
          Print X as single hex digit
Procedure PHEX2(x:Integer)
          Print X as 2 hex digits
Procedure PHEX4(x:Integer)
          Print X as 4 hex digits
Procedure PHEX(x:Integer)
          Print X as 8 hex digits

Procedure RHEX(Var x:Integer)
          Read hex number to X, skipping leading spaces and newlines

!PAGE
General Utility Procedures: Heap  (+ NEW,DISPOSE which are pre-defined)

Function HEAPGET(size:Integer):Integer
         Returns address of allocated space of SIZE bytes
Procedure HEAPPUT(address:Integer)
         Dispose of heap storage at ADDRESS
Procedure MARK
Procedure RELEASE

!PAGE
General Utility Procedures: PAM -- Parameter Acquisition Module
$p PAM is a set of procedures which may be called by programs to
set up file-names and option values.
First, the appropriate DEFINE ... PARAM procedure is called for each
individual file-name or option, and then the main procedure PROCESS
PARAMETERS is called to do the assignment of values. Usually the string
provided to PROCESS PARAMETERS will be the one typed by the user in the
command calling the program, available via the string function CLIPARAM.
The first argument to the DEFINE procedures is a text string which is used
as a prompt if the associated program parameter is being acquired
interactively.
$p Further information about PAM is available in a technical note.
$l0

  Flag values for use in defining parameters:-
Const:Integer   PAM NEWGROUP, PAM NODEFAULT, PAM MAJOR, PAM KEEPCASE
                PAM INFILE, PAM OUTFILE

Procedure DEFINE PARAM(text:String[255]; Var variable:String; flags:Integer)
           The routine DEFINE PARAM is used to define a string parameter
            (including an input or output file name)

!PAGE
General Utility Procedures: PAM (cont)

Procedure DEFINE INT PARAM(text:String[255];
                           Var variable:Integer; flags:Integer)
           The routine DEFINE INT PARAM is used to define an integer parameter

Procedure DEFINE ENUM PARAM(text:String[255];
                            Var variable:<enum>; flags:Integer)
           The routine DEFINE ENUM PARAM is used to define an enumeration
           (TEXT should start with a sequence of comma-separated keywords)

Procedure DEFINE BOOLEAN PARAMS(text:String[255];
                                Var variable:<set>; flags:Integer)
           This routine is used to define a group of Boolean parameters
            as a set

Procedure PROCESS PARAMETERS(parm:String[255])
           This routine parses the string PARM (which will usually be
             derived from CLIPARAM) according to the definitions previously
             established by calls on the DEFINE ... PARAM routines,
             and sets up values accordingly.
           It then erases the definitions, that is, it can be called once
             only for any set of definitions.

!PAGE
General Utility Procedures: PAM (cont)

Function  PAM:Var Paminfo
          Result is a reference to the environment information
            relating to command parameters.
          Relevant fields are:
              GROUPSEP: the character chosen as group separator
              KEYFLAG:  the character chosen as keyword flag

!PAGE
General Utility Procedures: File manipulation

Function  INFILENAME:String[255]
Function  OUTFILENAME:String[255]
Function  EXISTS(filename:String[255]):Boolean
Function  FILESIZE(filename:String[255]):Integer
Function  NINFO(filename:String[255]):String[255]
Procedure OPENAPPEND(stream:Integer; filename:String[255])
Procedure CLOSEAPPEND

Procedure CONNECT FILE(fname:String[255];
                       mode:Integer;Var start,len:Integer)
          Connect (in fact read in) the file denoted by FNAME
           to an area of store allocated from the heap
          START:= starting address;  LEN := size of file in bytes
          The parameter MODE should be zero at present

Procedure DELETE(filename:String[255])
Procedure RENAME(oldname,newname:String[255])
Procedure COPY(from,to:String[255])
Procedure PERMIT(filename,perms:String[255])
Procedure QUOTE(pass:String[255])

!PAGE
General Utility Procedures: Terminal control

Function  TESTSYMBOL:Integer
          Result is -1 if no symbol available from terminal;
          otherwise result is the ordinal value of the symbol,
          which is skipped

{Terminal modes:-}
Const:Integer SINGLE     {single character input without buffering},
              NOECHO     {no echoing of input characters},
              NOTERMECHO {no echoing of terminators},
              NOPAGE     {no auto-paging of output},

Procedure SET TERMINAL MODE(m:Integer)
          Set terminal mode as specified by M
           as selection (sum) of flag values given above
          eg SET TERMINAL MODE(SINGLE+NOECHO)

!>
!<INC:MATHS
                    Mathematical procedures and constants

Const:Real  PI, PI2 {PI*2}, PIO2 {PI/2}, PIO4 {PI/4}
            E, DtoR {Degrees to Radians}

*Function SIN(x:Real)      :Real
*Function COS(x:Real)      :Real
 Function TAN(x:Real)      :Real
*Function ARC TAN(x,y:Real):Real   {ARCTAN(y/x)}
 Function ARC SIN(x:Real)  :Real
 Function ARC COS(x:Real)  :Real
*Function LOG(x:Real)      :Real
 Function LOG TEN(x:Real)  :Real
*Function EXP(x:Real)      :Real
 Function SIN H(x:Real)    :Real
 Function COS H(x:Real)    :Real
 Function TAN H(x:Real)    :Real

     * not present in Pascal version, since pre-defined
!>
!<INC:VTLIB
Video Terminal Interface
$p This package provides support for conventional visual display
units in terms of a limited number of screen operations together
with ordinary character input/output (READ, WRITE, etc).
(Floating-point I/O is not included at present).
The package is also available on 2900/EMAS and VAX/VMS.
$p Programs including INC:VTLIB must also include INC:UTIL.
Before calling any of the other procedures, SET VIDEO MODE should be
called to establish the required mode of operation. SET VIDEO MODE is
an extension of SET TERMINAL MODE (see above).
$p Further information about the Video Terminal Interface is available
in a technical note.
$l0
!PAGE

 ASCII characters:
Const:Integer BS, TAB, LF, FF, RT, ESC, DEL

{Additional terminal mode for SET VIDEO MODE:-}
Const:Integer SPECIALPAD {alternative mode for numeric pad}

{Typical video mode for use of interface:-}
Const:Integer SCREENMODE=notermecho+nopage+specialpad

Procedure SET VIDEO MODE(mode:Integer)

Procedure CLEAR LINE             {clear rest of current line}
Procedure CLEAR FRAME            {clear all of current frame}
Procedure SCROLL(t,b,n:Integer)  {scroll region bounded by T (top)
                                 { and B (bottom) N lines --
                                 { reverse scroll if N negative}
Procedure VT AT(row,col:Integer) {cursor addressing}
Procedure GOTOXY(x,y:Integer)    {cursor addressing, COL first}

{Frame status:-}
Type WININFO  = Record  top,rows,left,cols,row,col,fun,mode:Byte

Var VDU:Wininfo     {full-screen frame}
Var WIN:Wininfo     {current frame}

{FUNction values defining functionality of frame:}
Const:Integer INTENSE, REVERSE, UNDERLINE, BLINK, GRAPHICAL
Const:Integer FULLSCROLL=64, ANYSCROLL=128

{MODE values for current attributes of frame:-}
Const:Integer NOSCROLL, FREEZE
Procedure     SET MODE(m:Integer)
              Set current frame mode attributes to M
              as selection (sum) of NOSCROLL,FREEZE
Const:Integer INTENSE, REVERSE, UNDERLINE, BLINK, GRAPHICAL
Procedure     SET SHADE(s:Integer)
              Set current frame shade attributes to S
              as selection (sum) of INTENSE etc

Procedure     SET FRAME(top,rows,left,cols:Integer)
              Define dimensions of current frame
              (TOP,LEFT from 0)

Procedure     PUSH FRAME
Procedure     POP FRAME
Procedure     SWOP FRAME
!>
!<INC:DICT
                          System Symbol Dictionary

Type DICTF = record  beg,pos,lim,alt:Integer

Function  DEFNAME(s:String[255]; Var d:Dictf; size:Integer):Integer
     Allocate and return address of SIZE-byte cell
     for name S in dictionary D

Function  REFNAME(s:Integer;Var d:Dictf):Integer
     Result is address of cell associated with name S in dictionary D

Procedure TRANSNAME(ref:Integer;Var s:String)
     Set S to name with which REF is associated

!>
!<INC:ECCE

Type EDFILE = Record START1,LIM1, {part 1}
                     START2,LIM2, {part 2}
                     LIM,         {VMLIM}
                     LBEG,FP,CHANGE,FLAG,
                     LINE  {line number of current pos},
                     DIFF  {diff between LINE and ROW}:Integer;
                     TOP  {top row of sub_window},
                     WIN  {floating top},
                     BOT  {bottom row of sub_window},
                     MIN  {minimum window size},
                     ROW  {last row position},
                     COL  {last col position}:Byte;
                     NAME:String[127]
$b
The record format EDFILE can be used to declare suitable
control blocks which contain the current state of a file in the course of
being edited.  The same format of control block is also used for any secondary
input file, even though parts of it are redundant in that case.
The later fields in the control block are concerned with video usage,
the earlier with the file itself.  The file has to be mapped into store
in its entirety and at all stages it consists of two parts, each part
being a contiguous sequence of bytes.  These parts are delimited by
START1 and LIM1 (first part) and START2 and LIM2 (second part); these
are all pointers (ie absolute store addresses). The LIM ones are
exclusive.  Either or both parts may be empty (LIM=START).
On the APM, part 1 always precedes part 2, with the space in between
free (available for expansion).
$b$l
Procedure CONNECT EDFILE(Var f:Edfile)
$b
This routine is used to connect (ie read into store) a file to be edited.
Before the call, the field NAME should be set to the name of the file,
and the field FLAG should be set to the number of extra bytes to be
allowed for expansion (32k is a typical figure).
On successful return, the file specified will have been read into store
at a system-selected position, the field LIM1 will be equal to START1,
and the fields START2 and LIM2 will delimit the whole of the file.
The fields LINE, CHANGE and FLAG will be zero.
If FLAG is non-zero, this indicates a failure to connect; a report
will already have been made.
$b$l
Procedure EDI(Var MAIN,SEC:Edfile; MESSAGE:String[255])
$b
This is the procedure used to call the editor itself.
MAIN identifies the file being edited and SEC any secondary input file
supplied at the outset (a dummy edfile record set to zero will suffice
if not relevant).  Message provides text to be printed at the bottom
of the screen at the outset.
Apart from the fields set up by CONNECT EDFILE (and subsequently modified by
the editor or, compatibly, by other programs), the following fields are
relevant:
$l0
  FP   : the current position in the file, which must always satisfy
          either START1 <= FP < LIM1
          or     START2 <= FP <= LIM2
  LINE : the line number of the current line (if known)
         If zero, the editor will establish the line number afresh
$b
On return from the editor, any of the pointer values may have changed
and the field CHANGE will identify the earliest position in the file
modified during the last edit.  LIM1 is guaranteed to co-incide with
a line break.  (Programs which cannot cope with a file split in two,
even at a guaranteed line break, are free to consolidate the file
by copying part 1 DOWN to be adjacent to part2 and adjusting all
pointers accordingly).
$b0
FLAG will be negative if the user has abandoned the edit.
$b
Procedure DISCONNECT EDFILE(Var f:Edfile)
$b
This routine is used to close off an edited file.  It is particularly
important to ensure that this procedure is called in all cases, even
if the associated program is being abandoned, since otherwise changes
made to the file are all lost.
On return, NAME will indicate the name under which the file was actually
written (maybe different from that originally specified).
!>
!>