\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:; 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:; 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 to . Port should be a previously unopened port. Procedure ETHERCLOSE(port:Integer) Close previously opened port Procedure ETHERWRITE(port:Integer,Var buf:byte,size:Integer) Transmit a block of data of length starting ad address on port . Function ETHERREAD(port:Integer,Var buf:byte,max:Integer):Integer Suspend program until a block appears on port . Place it in a buffer of length starting at 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}