@V7 54 2 -5
@L3 COUK1247
80
@V9 0
@YCHAPTER 21 - MUSS USER MANUAL
@G@RCHAPTER 21 - LIBRARIES@G
@V10 1 9 268
@T% 10
@BIt is clear from the description of MUSS that its
operation is very dependent on the availability, to
every virtual machine, of a substantial collection of
procedures in executable binary form. They are
called the system library. Facilities are also
provided for the user to augment the system library
with private libraries of executable code. This Chapter
is concerned with the structure of these libraries and with
the commands that allow compilers to compile calls of
library procedures and command
language processors to implement interpretive
calls.
@S221.1 LIBRARY SEGMENTS
@BThe compiling system (MUTL) generates
library segments. These may be loadable or
executable binary. We are concerned only
with the latter and they can always be
obtained by loading the former. It may be
relevant to note that binding of calls on other
library procedures occurs when executable binary
is created.
@BA library consists of a directory and the associated
procedure bodies and possibly data segments. In some
implementations these might occupy separate files but the
file name of the directory is always regarded as the name
of the library. A user need not be conscious of the
additional files which constitute a library except that
they will appear in his file store, with names derived
from the name of the library (e.g. library name 0,
library name 1, etc).
A complete library whether it be one or more files contains the following@
@Q 11
@
@Ma list of names for the procedures it contains,
@Ntheir parameter specifications,
@Na list of the names of the user defined
@Ntypes used as parameters,
@Ntheir specifications,
@Na procedure entry table,
@Ninitialisation code,
@Ninitialised data structures,
@Nand the procedure bodies.
@
@
The detail structure is machine dependent and is
only relevant to the procedures described
in this Chapter and to MUTL. However, the
following is always true.@
@V2 10
@
@IThe segment can be recompiled and, providing
it contains the same procedures
in the same order
(in fact it is the order of the procedure
names in the export list of the module heading,
rather than the order of the procedures themselves)
with unchanged specification,
previously bound calls will continue to
operate.
This is still true even if
new procedures are added to the end of the export list.
@V2 0
@S221.2 THE SYSTEM LIBRARY
@BAt the time a MUSS system is
generated, a selection of library segments
are included as the system library.
@BThe content of this library can be
different at different installations, but at least the
commands described in this Manual will normally be provided,
and extensions beyond this set are usually implemented
as private libraries.
@S221.3 PRIVATE LIBRARIES
@BThe commands LIBRARY and RELEASE.LIB were introduced
in Chapter 2 of the User Manual. The first dynamically
extends the set of procedures available,
and the second reduces it, by removing those of the
named library.
@BA library can contain code at the outer module
level, and this is treated as initialisation code
to be executed at the time of opening a library
by means of LIBRARY. Typically this code might
create working segments and initialise data structures.
@BSometimes it is necessary to discover the content
of a compiled library. The following command is intended
for this purpose@
@
@M@JLIST.LIB([C],[C],[I])
@BThe parameter P1 specifies a library name which
must already have been opened (by LIBRARY). P3 indicates
the level of detail required as follows@
@U 4
@
       P3 = 0 procedure names only
       P3 = /= 0 gives procedure names and parameter types
@
@
P2 may be used to select a subset of the procedures. If P2
is non-zero only procedures whose names contain the string
P2 will be listed.
@S221.4 PROCEDURES FOR CONSTRUCTING LIBRARIES
@BThe procedures defined in this section are not normally
used directly. They are the means by which MUTL creates a library.
@
@
1) @JINIT.DIR(II,I)I@
@BThis procedure creates a new empty directory for a library which will
have name P1.
P2 specifies the maximum number of procedures
which are to be added to the library. If P2 = 0 the procedure will
assume that a program rather than a library is to be compiled.
INITDIR returns the segment number of the directory,
and this is used as a parameter of the procedures which add
to the library.
@
@
2) @JADD.PROC(I,[C],[I])I@
@BThis procedure allows the specification of a new library
procedure to be added to the directory, specified by segment
number P1.
P2 gives the name of the procedure and P3
is a list of integers which give the MUTL encoding for each
parameter. It returns a number which relates to the position
of the procedure in the library.
After a call of INIT.DIR the first procedure number
returned will be 1 and it will thereafter increase
by one on each call of ADD.PROC. This number should be
used instead of the MUTLN in type specifiers which are
pointers to the procedure.
@
@
3) @JADD.TYPE(I,[C],[I])I
@BThis procedure allows the specification of a user defined
type to be added to the directory specified by P1. P2 is a
list of integers which give the types of its constituent components in MUTL enco
ding.
The result is a number which relates to the position of the
type definition inside the library.
Like the procedure number, it will
count up from 1 on successive calls, and it must be
used instead of MUTLN's in type specifiers.
@
@
4) @JADD.SEGMENT(I,I,I,I)
@BThis procedure is used to pass into the directory structure
information relating to the code and data segments of a
compiled library.
If the segment exists at the time of the call of
ADD.SEGMENT, and it is to be filed, then@
@Q 6
@
@MP1 specifies the directory segment
@NP2 gives a compile time segment number
@NP3 gives a run time segment number
@NP4 gives the required run time access
@N(as in OPEN.FILE)
@BIf the segment is to be created as a scratch segment
when the library is opened, P1 and P3 should be
set as above, but P2 will be zero and P4 will give
the required segment size.
@BThe first segment added to a library by this command is
assumed to be the principle code segment containing initialisation
code and the procedure entry table.
@
@
2) @JCLOSE.DIR(I)@
@BThis procedure completes the construction of a library directory
and files the directory segment, specified by P1, under the name
given in the call to INIT.DIR.
@BA library directory is typically formed, during compilation, by a call to
INIT.DIR, several calls to ADD.PROC, and possibly ADD.TYPE, and finally by calli
ng CLOSE.DIR.
@
@
6) @JMERGE.DIR(II,II,II)@
@BThis procedure creates a new directory P3 by combining
directories P1 and P2. The code segments of directories
P1 and P2 remain separate.
@S221.5 PROCEDURES FOR IMPLEMENTING CALLS ON LIBRARY PROCEDURES
@BThese procedures are only needed by compilers and command
interpreters.
@
@
1) @JFINDN([C],I)I
@BThis procedure searches the lists of
names associated with both private and system
libraries, for the name specified by P1. P2 indicates
whether the name is the name of a procedure (0) or type (1).
It returns an integer, called a 'library index'.
The value 0 means that the name
is not present in the library.
Normally the 'library index' is only used as
a parameter to other procedures such as FINDP, FINDT and the
TL.PL, and users do not need to know the encoding.
In fact the encoding is machine dependent.
@
@
2) @JFINDP(I,I,I)I
@BThis procedure is given a library index
as P1, an optional procedure number (as returned by ADD.PROC) as P2, and an inte
ger as P3. It returns the
type of parameter P3 of procedure P1(P2) in MUTL encoding.
If P3 = 0 it returns the number of parameters
and if P3 is this number + 1
it returns the result type of the procedure.
If P2 is negative the procedure whose number is encoded
in P1 is assumed otherwise the procedure number in P2 is substituted.
@
@
3) @JFINDF(I,I,I)I
@BThis procedure is the means by which the MUTL types of the
constituent fields of a type are discovered. P1 is a library index as
returned by FINDT. P2 is an optional type number (as returned
by ADD.TYPE) and P3 specifies a field number. As in FINDP, P2
will be ignored if negative, otherwise it will replace the
number in P1. Also if P3 = 0 the number of fields will be
returned.
@
@
4) @JLOOK.UP.N(I,[C],[C])I
@BThe purpose of this procedure is to yield information about
the procedures and types in the library specified by P2. In particular it
yields the library index of the nth name as a result, where
n is specified by P1. It also copies the name
into P3, preceded by a byte which indicates whether it is a
procedure or a type (ms bit = 0/1), and gives the length of the
name (ls 7 bits).
If the library does
not have the specified nth procedure a zero result is returned.@
@
@
5) @JLOOK.UP.LIB(I)@
@BThis procedure returns information concerning whether segment
P1 is a code segment of a currently open library. If this is
so a pointer to the library name (as obtained from the
LIB command) is returned,
otherwise a pointer to a vector of size zero is returned.
@
@
@
6) @JLINK([C],[ADDR PROC])I
@BThis procedure provides for an elementary
form of dynamic linking.  P1 should contain
a list of names separated by spaces or newlines.
P2 must be the adress of a vector of
ADDR PROC elements.  This procedure will
use the FINDN procedure for each
name in P1 and thereby obtain its address
which will be placed in the corresponding
position in P2.  If all the names are
found a zero result will be returned, otherwise
-1 will be returned.
@S221.6 INTERPRETIVE CALLING OF LIBRARY PROCEDURES
@BSometimes it is necessary to interpret user source as
immediate calls on library procedures. This occurs for
example, in the PCS INTERPRETER. Thus it is necessary to
stack a link, stack each parameter and then enter the
procedure. These operations are at too low a level to be
performed by the library procedures, therefore built-in
functions are provided in MUSL.
@F
