\documentstyle[a4,12pt]{article}
\begin{document}
\author{APM Manual pages}
\title{                            LIBRARIES}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in

\section{Preamble}
\hspace*{0.2 in} 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.

\hspace*{0.2 in} 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.

\hspace*{0.2 in} For details of the pre-defined procedures available in a particular language,
see the documentation for the language concerned.

\section{INC:UTIL}
General Utility Procedures: Miscellaneous

\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 
General Utility Procedures: Miscellaneous (cont)

\small\tt \begin{verbatim}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


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
\end{verbatim}\rm  \normalsize 

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

\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 

General Utility Procedures: PAM -- Parameter Acquisition Module

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.

Further information about PAM is available in a technical note.

Flag values for use in defining parameters:-
Const:Integer \hspace{0.2 in} PAM NEWGROUP, PAM NODEFAULT, PAM MAJOR, PAM KEEPCASE
\\ \hspace*{1.1 in} PAM INFILE, PAM OUTFILE

\small\tt \begin{verbatim}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)
\end{verbatim}\rm  \normalsize 

General Utility Procedures: PAM (cont)

\small\tt \begin{verbatim}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.
\end{verbatim}\rm  \normalsize 

General Utility Procedures: PAM (cont)

\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 

General Utility Procedures: File manipulation

\small\tt \begin{verbatim}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])
\end{verbatim}\rm  \normalsize 

General Utility Procedures: Terminal control

\small\tt \begin{verbatim}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)
\end{verbatim}\rm  \normalsize 

\section{INC:MATHS}
\hspace*{1.3 in} Mathematical procedures and constants

\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 
\hspace*{0.3 in} * not present in Pascal version, since pre-defined

\section{INC:RANDOM}
These Pseudo-random numbers were written by P. Reid. It is not known if
they are genuinely random or not (any offers to verify this?).

\small\tt \begin{verbatim}%routine   INITALISE RANDOM    sets up the random integer SEED
%real %fn  RANDOM REAL (LO,HI) returns uniformly distributed reals
                               between LO and HI inclusive
%short %fn RANDOM INT (LO,HI)  returns uniformly distributed short
                               integers between LO and HI inclusive
\end{verbatim}\rm  \normalsize 
They can be found in inc:random.imp

\section{INC:VTLIB}
Video Terminal Interface

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.

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).

Further information about the Video Terminal Interface is available in a
technical note.


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)

\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 
\section{INC:DICT}
\hspace*{1.7 in} System Symbol Dictionary

\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 

\section{INC:ECCE}

\small\tt \begin{verbatim}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]
\end{verbatim}\rm  \normalsize 
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).

Procedure CONNECT EDFILE(Var f:Edfile)

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. If START1 is non-zero it will be taken as a pointer to an area on the
heap and will be freed - i.e. for normal use this parameter should be initialised
to zero \{jhb\}

Procedure EDI(Var MAIN,SEC:Edfile; MESSAGE:String[255])

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:

\small\tt \begin{verbatim}  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
\end{verbatim}\rm  \normalsize 
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).
FLAG will be negative if the user has abandoned the edit.

Procedure DISCONNECT EDFILE(Var f:Edfile)

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).

\section{INC:FS}
 Ethernet and Filestore communication

Filestore Communication

\small\tt \begin{verbatim}Function  FCOMM(cn:Integer,S:String[255]):Integer
Procedure FCOMMW(cn:Integer, s:String[255],Var buffer:byte,size:Integer)
Function  FCOMMR(cn:Integer,p:String[255],Var b:byte,max:Integer):Integer
%short    USERNO
\end{verbatim}\rm  \normalsize 

Ethernet Communication

See HELP ETHER for a detailed description of these routines and of the
Ethernet.

\small\tt \begin{verbatim}Procedure ETHEROPEN(port,remote:Integer)
          Open port <port> to <remote>. Port should be a previously unopened
          port.

Procedure ETHERCLOSE(port:Integer)
          Close previously opened port <port>

Procedure ETHERWRITE(port:Integer,Var buf:byte,size:Integer)
          Transmit a block of data of length <size> starting ad address <buf>
          on port <port>.

Function  ETHERREAD(port:Integer,Var buf:byte,max:Integer):Integer
          Suspend program until a block appears on port <port>. Place it in a 
          buffer of length <max> starting at <buf> and return the actual number
          of bytes read.

Byte      CYLOCK,FSPORT

%short    STATION

Integer   ERR,DTX,RDY,STX,ACK,NAK

Byte      LDTE,LSAP,RDTE,RSAP

Byte      ETHS

Byte      ETHD

Byte      ETHC

Procedure TWAIT

Procedure DISABLE BROADCASTS

Procedure ENABLE BROADCASTS(channel:Integer)

Function  ETHERSTATION
          Returns the station number of the APM calling it.

Procedure ETHERDTX(port:Integer)
\end{verbatim}\rm  \normalsize 
\vspace{.75in} view:lib printed on 16/02/89 at 20.37

\newpage
\tableofcontents
\end{document}
