Google
 

Trailing-Edge - PDP-10 Archives - BB-JF18A-BM - documentation/dyn1f.mem
There are 9 other files named dyn1f.mem in the archive. Click here to see a list.



 












                     Dynamic Library Specification



          Author:   David Dyer-Bennet
                    MRO1-2/L14
                    DTN 231-4076
                    DYER-BENNET AT KL2102, SPAGS::DDB

          Edition:  1.0, 18-Jan-84

          File:     DYN1F.MEM


                     This document exists online as
                KL2137::PS:<DYER-BENNET.PUBLIC>DYN1F.MEM
Dynamic Library Specification                                    Page ii
Issue History                                                  21 May 86


                             Issue History

Issue 0.1   30-Sep-83  Initial entry.  First limited review.

Issue 0.2   14-Oct-83  Signalling details.  development.

Issue 1.0   18-Jan-84  Update with things learned from coding and  using
                       the DYNLIB/RTL.  Currently in development.
Dynamic Library Specification                                 Page iii
Issue History                                                21 May 86


        1.0     PRODUCT SUMMARY  . . . . . . . . . . . . . . . . . . 1
        2.0     TERMINOLOGY AND CONVENTIONS  . . . . . . . . . . . . 1
        3.0     ENVIRONMENT  . . . . . . . . . . . . . . . . . . . . 2
        3.1       Users  . . . . . . . . . . . . . . . . . . . . . . 2
        3.2       Hardware . . . . . . . . . . . . . . . . . . . . . 2
        3.3       Software . . . . . . . . . . . . . . . . . . . . . 3
        3.3.1       Other Software Required For DYNLIB . . . . . . . 3
        3.3.2       Other Software That Requires DYNLIB  . . . . . . 3
        3.4       Services . . . . . . . . . . . . . . . . . . . . . 3
        4.0     SOFTWARE CAPABILITIES  . . . . . . . . . . . . . . . 3
        4.1       Streaming  . . . . . . . . . . . . . . . . . . . . 4
        4.2       The Run-time Library . . . . . . . . . . . . . . . 4
        4.3       Dynamic Invocation Of Libraries  . . . . . . . . . 4
        4.3.1       Calling A Routine In A Dynamic Library . . . . . 4
        4.3.2       Referring To A Galactic Variable . . . . . . . . 5
        4.3.3       Errors Occurring During Dynamic Loading  . . . . 6
        4.4       Memory Allocation  . . . . . . . . . . . . . . . . 7
        4.5       Signalling And Condition Handling  . . . . . . . . 7
        4.5.1       Layered Interrupts . . . . . . . . . . . . . . . 8
        4.5.2       Condition Handling . . . . . . . . . . . . . . . 8
        4.5.2.1       Fixed interrupt channels . . . . . . . . . .  10
        4.5.2.2       APR traps  . . . . . . . . . . . . . . . . .  10
        4.5.2.3       Character interrupts . . . . . . . . . . . .  10
        4.5.3       Performance Considerations . . . . . . . . . .  11
        4.5.3.1       Arithmetic Trap Default Actions  . . . . . .  11
        4.6       Errors And Message Printing  . . . . . . . . . .  12
        4.7       Dynamic Library Contents . . . . . . . . . . . .  12
        4.8       Writing Dynamic Libraries  . . . . . . . . . . .  13
        4.8.1       The Library Definition . . . . . . . . . . . .  13
        4.8.2       The LDLBLK File  . . . . . . . . . . . . . . .  14
        4.8.3       The LDLJCK File  . . . . . . . . . . . . . . .  14
        4.8.4       Master Initialization  . . . . . . . . . . . .  14
        4.8.5       Condition Handling Routines  . . . . . . . . .  15
        4.9       Details Of Data Structures . . . . . . . . . . .  16
        4.9.1       The Dynamic Library Block  . . . . . . . . . .  16
        4.9.2       The Local Dynamic Library Block  . . . . . . .  17
        4.9.3       The Signal Block . . . . . . . . . . . . . . .  18
        4.9.4       The Condition Code . . . . . . . . . . . . . .  19
        4.9.5       The Handler Block  . . . . . . . . . . . . . .  19
        4.10      Details Of Explicit Calls  . . . . . . . . . . .  19
        4.10.1      Return Last DYNLIB Error -- DY_$LER . . . . . .
        20
        4.10.2      Force Loading/Overloading -- DY_$LOD  . . . . .
        20
        4.10.2.1      .DYLOD -- Force loading of library . . . . .  21
        4.10.2.2      .DYOLB -- overload one library onto another   21
        4.10.2.3      .DYOVC -- overload one vector onto another .  22
        4.10.3      Global Master Initialization -- DY_$MIN . . . .
        22
        4.10.4      Allocate Memory Block -- ME_$ALM  . . . . . . .
        22
        4.10.5      Allocate Pages Of Memory -- ME_$ALP . . . . . .
        23
        4.10.6      Create A New Section -- ME_$ALS . . . . . . . .
Dynamic Library Specification                                  Page iv
Issue History                                                21 May 86


        23
        4.10.7      Return Memory Block -- ME_$DLM  . . . . . . . .
        24
        4.10.8      Return Memory Pages -- ME_$DLP  . . . . . . . .
        24
        4.10.9      Destroy A Section -- ME_$DLS  . . . . . . . . .
        25
        4.10.10     Sub-contract Memory Management -- ME_$MEM . . .
        25
        4.10.11     Formatted ASCII Output -- RL_$FAO . . . . . . .
        26
        4.10.12     Allocate An Interrupt Channel -- SG_$ALC  . . .
        27
        4.10.13     Disable Interrupt Characters -- SG_$DIC . . . .
        27
        4.10.14     Return An Interrupt Channel -- SG_$DLC  . . . .
        27
        4.10.15     Deallocate A Signal Chain -- SG_$DLG  . . . . .
        28
        4.10.16     Dump An SG Chain -- SG_$DMG . . . . . . . . . .
        28
        4.10.17     Enable Interrupt Characters -- SG_$EIC  . . . .
        28
        4.10.18     Establish A Condition Handler -- SG_$EST  . . .
        29
        4.10.19     Establish A Handler Locally -- SG_$LES  . . . .
        29
        4.10.20     Remove A Handler Locally -- SG_$LRM . . . . . .
        30
        4.10.21     Make Signal Block For Last Monitor Error -- 
                    SG_$MER . . . . . . . . . . . . . . . . . . . .
        30
        4.10.22     Print Error Messages -- SG_$PEM . . . . . . . .
        30
        4.10.23     Remove A Condition Handler -- SG_$REM . . . . .
        31
        4.10.24     Declare Trap Handler For Section -- SG_$SEC . .
        31
        4.10.25     Signal -- SG_$SIG . . . . . . . . . . . . . . .
        32
        4.11      Details Of Galactic Variables Defined  . . . . .  32
        4.11.1      Signalling Information . . . . . . . . . . . .  32
        4.11.1.1      Enable stack pointer -- SG.ENS . . . . . . .  32
        4.11.2      Last-ditch Handler Parameters  . . . . . . . .  32
        4.11.2.1      Maximum depth -- SG.LEV  . . . . . . . . . .  33
        4.11.2.2      Destination designator -- SG.OUT . . . . . .  33
        4.11.2.3      Prefix table address -- SG.PFX . . . . . . .  33
        4.11.2.4      Suffix table address -- SG.SFX . . . . . . .  33
        4.11.2.5      Default prefix table -- SG.DPX . . . . . . .  33
        4.11.2.6      Default suffix table -- SG.DSX . . . . . . .  33
        4.12      DYNLIB Bootstrap . . . . . . . . . . . . . . . .  33
        5.0     PUBLICATIONS . . . . . . . . . . . . . . . . . . .  34
        6.0     PACKAGING  . . . . . . . . . . . . . . . . . . . .  34
        7.0     INSTALLABILITY . . . . . . . . . . . . . . . . . .  34
Dynamic Library Specification                                   Page v
Issue History                                                21 May 86


        8.0     EASE OF USE  . . . . . . . . . . . . . . . . . . .  34
        9.0     PERFORMANCE  . . . . . . . . . . . . . . . . . . .  34
        10.0    RELIABILITY  . . . . . . . . . . . . . . . . . . .  35
        11.0    MAINTAINABILITY  . . . . . . . . . . . . . . . . .  35
        12.0    MAINTENANCE  . . . . . . . . . . . . . . . . . . .  35
        13.0    COMPATIBILITY  . . . . . . . . . . . . . . . . . .  36
        13.1      Compatibility With Existing Libraries  . . . . .  36
        13.2      Product Compatibility  . . . . . . . . . . . . .  36
        13.2.1      Dependency Issues  . . . . . . . . . . . . . .  36
        13.3      Standards Conformance  . . . . . . . . . . . . .  36
        13.4      Internationalization . . . . . . . . . . . . . .  36
        14.0    EVOLVABILITY . . . . . . . . . . . . . . . . . . .  36
        15.0    COSTS  . . . . . . . . . . . . . . . . . . . . . .  36
        16.0    TIMELINESS . . . . . . . . . . . . . . . . . . . .  37
        17.0    CONSTRAINTS AND TRADES-OFF . . . . . . . . . . . .  37
        18.0    APPROVAL PROCESS . . . . . . . . . . . . . . . . .  37



 
Dynamic Library Specification                                     Page 1
PRODUCT SUMMARY                                                21 May 86


1.0  PRODUCT SUMMARY

A "routine library" (often called simply a "library" in  this  document)
is a group of routines and data which is intended to provide services to
its caller.  Because  the  word  "library"  appears  so  often  in  this
document,  a  routine  library is also sometimes called a "package."  On
TOPS-20, the most familiar form of library is probably the "REL library"
as understood by LINK and MAKLIB.

A "dynamically linked library" (often called simply a "dynamic  library"
in this document) is a library which is merged into a program on request
at execution time.

This document describes a dynamic  library  system  for  TOPS-20.   This
system provides the following benefits as compared to REL libraries:

      o  Provide a discipline for  independently-developed  packages  to
         share  a  process  peacefully  while  providing  access  to the
         resources they need to do their jobs  (resources  that  require
         discipline to share successfully include address space, the APR
         trap system, and the software interrupt system).

      o  Easier  software  updates.   A  new  version   of   a   package
         implemented  as  a  dynamic  library can be introduced into all
         programs calling it by simply placing it on the directory  from
         which dynamic libraries are loaded.  There is no need to relink
         programs using it.

      o  More consistent program behavior.   If  a  facility  is  always
         provided  by  the  same package of code, then it will always be
         provided in the same way.

      o  More efficient use of physical memory and swapping space.  If a
         facility provided by a dynamic library is never called during a
         run of a program, that library will never become part  of  that
         process' address space.  If several programs are using the same
         dynamic library, they will share a single copy  of  its  "pure"
         parts.

      o  Lower cost of engineering other products.   Using  an  existing
         package  to  provide  a  service is much cheaper than having to
         modify it or write one from scratch.


The code to perform dynamic library  invocation  and  related  functions
will  reside  in  a  special  dynamic  library  called the RTL (run-time
library).


2.0  TERMINOLOGY AND CONVENTIONS

This document specifies the "dynamic library mechanism," which we define
as  "that which causes a library to be merged into a program on request,
and performs other functions necessary to make that useful."   To  avoid
Dynamic Library Specification                                     Page 2
TERMINOLOGY AND CONVENTIONS                                    21 May 86


confusion,  I  will from now on call this "DYNLIB."  In the rest of this
document, when I refer to a "dynamic library" I am referring generically
or  specifically  to  some  library  designed  to  be called through the
services provided by DYNLIB.

DYNLIB has associated with it some special facilities for handling traps
and  interrupts, allocating memory, and performing other tasks necessary
to allow many packages to  co-exist  peacefully  in  a  single  process.
These  facilities are also specified in this document.  They are SIG for
signalling  and  condition  handling  (including  interrupt   and   trap
handling), MEM for memory management and section allocation, and RTL for
other utility functions (message formatting and printing, etc.).

Related to DYNLIB are some rules that must be  followed  by  writers  of
libraries to be called through DYNLIB.  These appear in this document in
a paragraph by themselves, beginning with "DYNLIB use rule:".  The  full
set of rules for writing a dynamic library will be documented as part of
the development effort of this project.

A  "OWL/GBP"  is  a  one-word  local/global  byte  pointer,   which   is
interpreted  as  follows:   If  it  has  the  form  of a one-word global
byte-pointer, then it is interpreted as one.  If it has the  form  of  a
local  byte-pointer, then it is interpreted as pointing into the section
of memory from which it is fetched.  This is equivalent to being able to
set  an  "IFIW" bit in the byte pointer word (which is unfortunately not
supported).  The GETBP macro in DYNSYM.UNV performs this operation.


3.0  ENVIRONMENT

3.1  Users

Dynamic libraries  will  be  written  primarily  by  Digital  engineers.
Moderately  sophisticated  customer system programmers may occassionally
be called upon to write  dynamic  libraries,  as  may  Digital  software
specialists.

Dynamic  libraries  will  (eventually)  be  used  implicitly   by   most
higher-level  language  programs,  but this should be transparent to the
users.

Both application and  system  programs  are  likely  to  invoke  dynamic
libraries explicitly.

Digital-written utilities will also use dynamic libraries extensively.


3.2  Hardware

DYNLIB will run on a PDP-10 family processor  with  extended  addressing
(i.e.  KL model B).  KS processors will not be supported.
Dynamic Library Specification                                     Page 3
ENVIRONMENT                                                    21 May 86


No microcode changes will be required for DYNLIB.

As  described  below,  DYNLIB  will  encourage  the  use   of   extended
addressing.   Some  dynamic  libraries  may  require  fixes for extended
addressing bugs.  This will be the responsibility of  the  project  that
produces the dynamic library in question.


3.3  Software

3.3.1  Other Software Required For DYNLIB

DYNLIB requires TOPS-20 release 5.1 or later.

In a future release of the operating system, support for  DYNLIB  should
be  built  in.   This is discussed under Evolvability.  Operating system
support of DYNLIB is not a goal of this project.


3.3.2  Other Software That Requires DYNLIB

DYNLIB is required for Datatrieve-20 V1.0, dynamic  extended  RMS  (V3),
and dynamic callable DBCS (V7) (Dynamic MTHLIB is being produced as part
of the Datatrieve project.)

All other software projects should consider if they would  benefit  from
using  DYNLIB.   Language  systems  should  consider invoking their OTS'
through DYNLIB.  Languages calling SORT, DBCS, and RMS  should  consider
calling them through DYNLIB.


3.4  Services

No special services are required for DYNLIB.


4.0  SOFTWARE CAPABILITIES

The basic capability of DYNLIB is to map in an EXE file containing  some
package  of  code  at  the  time  a  call is made to it.  There are some
additional functions associated with this part of DYNLIB, but  the  bulk
of  the routines described in this section are actually support routines
-- they don't directly assist DYNLIB, but they make it possible to write
packages  of  code  that  will work together without interference in the
DYNLIB environment.

These support routines are the complicated part of the project.   Please
pay  close  attention  to  the  descriptions  of  their capabilities and
restrictions.
Dynamic Library Specification                                     Page 4
SOFTWARE CAPABILITIES                                          21 May 86


4.1  Streaming

"Single-stream" libraries are those like the current SORT which can only
handle  one  stream  of  operations  at  a  time,  but which have a user
interface such that you make more than one call for that  single  stream
(some sort of state information is preserved between calls).

"Non-streamed" libraries are those like, perhaps, the MTHLIB, which  can
only  handle  one stream of operations, but where this doesn't matter to
anybody because there is only one call made to  perform  the  operation.
There is no "state" saved across calls to these libraries.  Note that to
really qualify in this category a library must be fully reentrant.

"Multi-streamed" libraries are  those  like  callable  Datatrieve  which
support  several  concurrent streams of operations.  This classification
can be further divided into "infinitely multi-streamed," where it should
always   be   possible   to   start   another   stream,   and   "limited
multi-streamed," where you could  easily  run  out  of  streams.   Where
"multi-streamed"    is    used    without   qualification,   "infinitely
multi-streamed" should be assumed.

DYNLIB supports non-streamed and  infinitely  multi-streamed  libraries.
If  a  caller  attempts to initialize a new LDLBLK to a library that has
its busy bit set, a  DYNLIB  error  will  be  returned.   If  a  library
receives  a  request to start a stream which it is unable to honor, this
same error should be signalled by the library.


4.2  The Run-time Library

The run-time library (RTL) is a special library that contains the DYNLIB
code and associated facilities (memory management, signalling).  This is
an appropriate place to put generally useful routines  that  aren't  big
enough  to  rate their own library.  The MTHLIB has been included in the
RTL, for example.


4.3  Dynamic Invocation Of Libraries

Most calls for DYNLIB services will be made implicitly, by referring  to
an  address  exported  from  a  dynamic  library (routine entry point or
"galactic variable").


4.3.1  Calling A Routine In A Dynamic Library

To be able to call routines in a dynamic library, you must:

     1.  Be running in a non-zero section

     2.  Have a global-format stack pointer in AC17
Dynamic Library Specification                                     Page 5
SOFTWARE CAPABILITIES                                          21 May 86


     3.  Have declared as EXTERNAL in your  program  the  names  of  the
         routines you wish to call

     4.  Have linked your program with a library-specific REL  file  for
         each  of  the  libraries  you call directly (you do not need to
         consider libraries that may be called by libraries you call)

     5.  Have linked your program with DYNBOO.REL


There are two defined types of library-specific REL  file  that  may  be
associated with a dynamic library.  The normal type is called an "LDLBLK
file";   it  contains  simply  the  definition  of  the   LDLBLK.    The
alternative type is called an "LDLJCK file";  it contains definitions of
jacket routines for each routine in the library.  It may also contain an
ordinary LDLBLK with galactic variable information only.

Suppose the dynamic library  EXAMPL  contains  a  routine  RNDNAM.   The
argument-passing  rules for this routine and what registers it preserves
are of no concern to DYNLIB (although they must, of  course,  be  agreed
between the routine and its caller).

To call this routine from MACRO using the LDLBLK file, you must  set  up
the arguments as specified for the routine, and then
     PUSHJ P, @RNDNAM##
This is the normal way of calling a routine in a dynamic library.

To call this routine from MACRO using the LDLJCK file, you must  set  up
the arguments as specified for the routine, and then
     PUSHJ P, RNDNAM##
Note the lack of indirection.  When converting an existing program, or a
program  written  in  a higher-level language, to use dynamic libraries,
this mode can be essential.  There is no reason for preferring this mode
of  call  in a newly-written MACRO program, and some performance reasons
for avoiding it.

You may use any number of levels of indirection in the instruction  that
calls  a  routine in a dynamic library.  It is also perfectly acceptable
for the PUSHJ instruction to be XCT'd from somewhere else.  However, the
EA  calc  should  not  depend  on  the  values in the AC's (so don't use
indexing, and don't indirect through an AC).

Normally, the names for the routines in the LDLJCK file  and  the  names
for  the  transfer vector locations in the LDLBLK file will be the same.
Thus, they cannot both be used in the same  program.   A  technique  for
making  it  possible to use both calling conventions in a single program
is described below.


4.3.2  Referring To A Galactic Variable

To refer to a data location in another library, you must:
Dynamic Library Specification                                     Page 6
SOFTWARE CAPABILITIES                                          21 May 86


     1.  Be running in a non-zero section

     2.  Have declared as EXTERNAL in your  program  the  names  of  the
         galactic variables to which you wish to refer

     3.  Have linked your program with a library-specific REL  file  for
         the  library  which  defines the galactic variable to which you
         wish to refer


To refer to the galactic variable, make an indirect reference through  a
"local  galactic  vector"  (like  a  transfer  vector, but the things it
points to  aren't  routine  entry  points)  which  is  provided  by  the
library-specific REL file mentioned above.

The method of referring to a galactic variable is the same  whether  the
LDLBLK  file  or  the  LDLJCK  file  is used.  There is no provision for
referring to galactic variables in languages that  do  not  support  the
concept of the indirect reference.

In version 1 of DYNLIB, referring to  a  galactic  variable  before  the
library  which  defines it is loaded (either by explicit call to DYNLIB,
or by calling a routine in that library) is an error.


4.3.3  Errors Occurring During Dynamic Loading

There are  three  ways  errors  occurring  during  dynamic  loading  are
handled, depending on the exact conditions.

If the library being loaded is the RTL, an error message is  printed  on
the terminal.  This is done to minimize the size of the DYNBOO bootstrap
routine.  All the code for the fancy error handling described  below  is
contained  in  the  RTL,  which  is  by hypothesis not available in this
situation.

If the instruction which caused dynamic loading is immediately  followed
by an ERJMP or ERCAL instruction, control is transferred to the location
specified.  T1 will contain the address of an SG block chain  describing
the error.  T0 will be trashed.  Other registers will be preserved if so
specified for the routine being called.

or can be determined by calling the DYNLER routine,  which  returns  the
signal block for the last error that occurred.

If the instruction which  caused  dynamic  loading  is  not  immediately
followed by an ERJMP or ERCAL instruction, a signal is generated for the
error.  This may either be handled by a user error handler, or  ignored;
if  it  is  ignored, the last-ditch handler will handle it.  For dynamic
library loading errors, its handling is to print  a  message  describing
the error and abort the program.
Dynamic Library Specification                                     Page 7
SOFTWARE CAPABILITIES                                          21 May 86


4.4  Memory Allocation

The RTL will contain the master section allocator, and  a  basic  memory
manager.   All sections must be allocated through the section allocator.
An allocated section is managed by its allocator.   One  alternative  it
has  is  to manage it itself.  Another is to request that the RTL memory
allocator do so for it.

DYNLIB use rule:  All sections used must  be  allocated  by  the  DYNLIB
section allocator.

DYNLIB use rule:  Memory in a  section  may  not  be  used  without  the
"permission"  of  the  allocator  of that section.  That is, any sort of
cooperative arrangement is fine, but in the absence of  agreement,  keep
your fingers in your own sections!

Signal blocks must be allocated by the RTL  memory  allocator,  so  that
they can be released by the SIG facility.

A future version of  the  RTL  must  support  allocation  of  groups  of
contiguous  sections.   Support  for a user-written section allocator is
also desirable (and seems easy).


4.5  Signalling And Condition Handling

To attain  the  goals  of  a  truly  layered  product  environment,  the
facilities  of the interrupt system and of trapping must be available to
each package called by a process, without  a  package  having  to  worry
about which other packages are being used.

DYNLIB use rule:  user programs may not directly manipulate the APR trap
system  (in  particular,  they  may not use the APR trap function of the
SWTRP% JSYS).  User programs should get APR trapping services  by  using
the  JOV or other JFCL-class instruction after the instruction they wish
to check for overflows, or by handling the condition  generated  in  the
absence of JFCL-class instructions.

DYNLIB use rule:  user  programs  should  not  directly  manipulate  the
software  interrupt (PSI) system except for assigning events to channels
allocated from DYNLIB and handling those interrupts.  They should  never
perform interrupt-specific JSYSes other than DEBRK%.

There are two asynchronous types of activities that must be supported.

One is asynchronous events requiring attention  from  the  package  that
started  them.   These  occur  as  a  normal  part of processing, are of
interest only to the package that initiated the activity,  and  must  be
quite quick.  This mechanism will be called "layered interrupts".

The other is exception (error) conditions generated by the  users'  code
and  requests.  These occur relatively rarely, and quite often result in
an error which is of interest to other packages than the one  generating
the   condition.   The  occurrence  of  these  conditions  need  not  be
Dynamic Library Specification                                     Page 8
SOFTWARE CAPABILITIES                                          21 May 86


blindingly fast.  This mechanism will be called "condition handling."

This facility, and the code making  it  up,  is  referred  to  as  "SIG"
throughout this document.


4.5.1  Layered Interrupts

This mechanism is intended for servicing  of  asynchronous  events  that
belong  to  a  particular  package.  These are handled by user-specified
interrupt handlers at interrupt level.  The  user  allocates  a  channel
from SIG, and attaches conditions to the channel himself.


4.5.2  Condition Handling

This mechanism is intended for information of general hierarchical  use,
particularly for error or exception information.

This mechanism is modeled after  the  signalling  /  condition  handling
facilities in BLISS-36, VAX/VMS, and RSX-11.

Conditions may be signalled by user software by making a call to  a  SIG
routine.   In addition to this use, all events made available by TOPS-20
through APR traps or interrupts will be turned into signals by  the  SIG
facility (APR traps only in V1).

To handle conditions, a  routine  must  identify  its  handler  to  SIG.
Conditions  that  aren't  handled by any level will be dealt with by the
"last-ditch" handler.

SIG will maintain a list of handlers established.  When a  condition  is
signalled,  the  handlers  will  be  called  in order from most recently
established to oldest, until one of  them  handles  the  situation  (see
discussion of handler options below).

There is no facility for a package to  grab  complete  control  of  some
category of signal;  this would violate the hierarchical layering.

Because this facility is based on the existing PSI and SWTRP mechanisms,
there  are  some restrictions on the user handlers.  In particular, some
of them must run at interrupt level.   Here  are  the  types  of  events
signalled,  the  level  at  which  handlers  for  them must run, and the
default actions if they are not handled:

     Description     Level           Default            Continuable
     ----------      -----           -------            -----------

     APR             normal          fixup and signal   Yes
     data error      interrupt       message and exit   Yes
     disk quota      interrupt       message and exit   Yes
     end of file     interrupt       message and exit   Yes
     illegal inst.   normal          message and exit   Restarts instr
     illegal read    normal          message and exit   Restarts instr
Dynamic Library Specification                                     Page 9
SOFTWARE CAPABILITIES                                          21 May 86


     illegal write   normal          message and exit   Restarts instr
     inferior stop   interrupt       continue           Yes
     non-exist. page interrupt       create, continue   Yes
     PDL overflow    normal          message and exit   Yes
     software signal normal          message & continue Yes
                                     or exit (based on
                                     severity)
     system resourc. normal          message and exit   Yes
     character       interrupt       ^C exits,          Yes
                                     others ignored
     terminal        interrupt       ignored            Yes
        (carrier transition, break, input available)

When a handler is entered for a signal, it has  the  following  options:
re-signal  from  current  position, continue interrupted code, unwind to
its establisher's caller.  A handler must also receive the unwind signal
and  do  appropriate things with it (in particular, it must free dynamic
resources that its establisher allocated).  The continue option is  only
available  for  software  signals,  signals  originating  as  traps, and
signals originating as interrupts that are handled at interrupt level.

There are some restrictions on the linkage conventions of routines which
must enable for condition handling:

      o  The routines must be running in a non-zero section at the  time
         they enable, and at any time their handlers are invoked

      o  There must be  a  global-format  stack  pointer  in  AC17  with
         sufficient space available

      o  The routines must be called with PUSHJ 17, adr.

      o  The routines must return a value in AC0.  It is this value that
         may be specified in the unwind call

A routine need not be in a  dynamic  library  to  enable  for  condition
handling.   It can be part of a top-level program or a library called in
some other way.

A signal block (or error block) will have  a  fixed  heading,  including
facility     identification,    condition    identification,    severity
identification, print flags, message text, and pointer  to  next  block.
It will contain a pointer to a block containing condition-specific data.

The normal appearance of a signal is as a chain of these  error  blocks.
The  first  one  in the chain is the most recent, and for most things is
the only one that needs to be  examined.   However,  for  error  message
printing,  and  for  more  detailed analysis of a situation, the earlier
blocks are available.  One of the print flags will indicate that a block
is for computer use only, that no message should be printed.
Dynamic Library Specification                                    Page 10
SOFTWARE CAPABILITIES                                          21 May 86


4.5.2.1  Fixed interrupt channels

Events that are assigned by TOPS-20 to fixed interrupt channels will  be
turned into signals by the SIG facility (not in V1).

Illegal instruction interrupts can result from monitor call errors.  The
interrupt  will only occur if there is not an ERJMP or ERCAL instruction
after the JSYS that failed.  The  signal  block  generated  for  illegal
instruction  interrupts  will  include  as  its  message the text of the
monitor error message for the JSYS failure.


4.5.2.2  APR traps

APR traps will generate signals unless  the  instruction  producing  the
trap  is  followed  by  some  flavor  of  JFCL instruction.  The default
handling of the signal will be to perform  the  MTHTRP  fixup,  print  a
message, and then continue.

An alternative method of handling APR traps (and interrupts  from  fixed
interrupt  channels)  is  discussed  under "Performance Considerations",
below.


4.5.2.3  Character interrupts

General handling of character interrupts won't be provided in the  first
version.   It will probably never be provided.  What will be provided is
likely to be good enough for everybody.

There will be two parts  to  using  character  interrupts:   defining  a
character  as  in  interrupt  (as  opposed  to  a normal) character, and
processing the signal when it comes by.

Receiving character interrupt signals is the same as receiving any other
signals.   There will be a word of signal-specific data giving a mask of
the characters that could have caused this signal  (combining  interrupt
characters  is  discussed directly below, and elsewhere in the document;
briefly, it is often sufficient to a program to know that SOME interrupt
character,  or  some  from a small set, was typed, and by assigning more
than one character to  a  channel  when  possible  the  limited  set  of
channels is conserved).

Characters are defined as interrupt characters by making calls to a  SIG
routine giving bit masks.  Each call defines a group of characters which
you  wish  to  see  treated  as  interrupt  characters.   The  group  of
characters  given in a call will not necessarily be distinguishable from
each other when the signal arrives.

If you ask to distinguish between  characters  that  somebody  else  has
already asked to see combined, you lose (and get a code to that effect).
As a special exception, ^C, ^T, ^A , and ^Y will never be combined  with
anything  else,  although you can request them in combination with other
things.  (The exact list of characters given this special  treatment  is
Dynamic Library Specification                                    Page 11
SOFTWARE CAPABILITIES                                          21 May 86


certainly open to debate.  It has no particular impact on performance or
development time.)

At a future date, the software handling  this  could  be  re-written  to
optimize  assignment  of groups of characters to channels so as to allow
you to see any combination you want,  subject  to  the  availability  of
channels.   This  is  not  a  requirement of any software we know.  This
extension would only be implemented if required by some future software.
Its implementation would be transparent to existing software.


4.5.3  Performance Considerations

There are many packages which get called many times during a  relatively
short  program  run.   For  example,  MTHLIB,  RMS  (once  per  record),
sometimes SORT.  It is important to minimize the  cost  of  an  explicit
layer transition.

Actual exceptions occur relatively rarely, and when they do often result
in program termination or at least user interaction.  Accordingly, it is
not as important for the actual  handling  of  exceptions  to  be  fast.
Trading  off slower exception handling for faster layer transitions is a
desirable thing to do.  (Obviously in an ideal  world  both  would  take
zero  time.   If you know how to achieve this, please come explain it to
me....)

The one possible exception to  this  is  arithmetic  traps.   These  can
sometimes  occur  without indicating a package-level error, and thus may
occur frequently in a single run.  Some packages treat arithmetic  traps
as errors.  For them, signalling the trap is fine.  Some things (written
in MACRO) want to test for errors immediately after the instruction that
produced  them.   For them, we are making the default handling of a trap
include a check for a JFCL-class instruction right after it.  If such an
instruction is present, the trap is ignored.

To ease conversion of existing libraries,  and  improve  performance  of
libraries  depending  extensively  on APR traps, there is a facility for
requesting that all traps originating in a given section be directed  to
a  specified  handler.   This  option,  if  invoked, completely bypasses
MTHTRP fixups, signal generation, and message  printing  for  APR  traps
originating in specified sections.


4.5.3.1  Arithmetic Trap Default Actions

Fixups are as performed by MTHTRP.  Putting a JFCL (of any flavor) after
an  instruction  that  may  cause an overflow will work normally (MTHTRP
looks for them).  In the absence of a JFCL, after determining the  error
and possibly fixing things up MTHTRP generates a signal.  If this signal
isn't intercepted, the last-ditch handler  will  print  the  message  it
describes.
Dynamic Library Specification                                    Page 12
SOFTWARE CAPABILITIES                                          21 May 86


4.6  Errors And Message Printing

The signal block contains information to make printing error messages as
easy  as  possible -- for example, facility names and error messages are
present as text, so no decoding is  necessary.   There  are  also  print
flags  in the blocks, specifying any special aspects of that block (such
as a block which is for computer use  only,  contains  no  message,  and
should not be printed at all).

A routine is provided  for  printing  the  messages  from  some  initial
segment  of  the  signal blocks in a chain in a uniform format.  This is
used by the last-ditch handler, and  is  recommended  for  use  by  user
routines that wish to print messages.


4.7  Dynamic Library Contents

A dynamic library consists of several pieces, including

An EXE file which contains:

      o  A PDV with the  name  "DYNLIB$class-name".   Word  2  (formerly
         called  .PVSTR)  in  the PDV should point to the master dynamic
         library block (DLBLK) for this library.   Word  4,  .PVVER,  by
         convention contains the version number of the library.

      o  The DLBLK for the library.   This  block  describes  the  entry
         points and other exported addresses of the library.

      o  The necessary code and data to perform the library's functions.


A REL file which contains information for the caller to link with.

The normal case (an LDLBLK file):

      o  The local dynamic library block (LDLBLK) for the library.  This
         block  describes  the entry points and other exported addresses
         of the library and contains the address vectors  through  which
         references to the actual library objects are made.


A special case, useful when converting callers of existing libraries  or
making  the  calls  from  higher-level  languages that don't support the
concept of pointers to routines (an LDLJCK file):

      o  The local dynamic library block (LDLBLK) for the library.  This
         block  describes  the entry points and other exported addresses
         of the library and contains the address vectors  through  which
         references to the actual library objects are made.
Dynamic Library Specification                                    Page 13
SOFTWARE CAPABILITIES                                          21 May 86


      o  A jacket routine for each routine in the library.  This routine
         expects  to  be  called  by  a simple PUSHJ.  It then calls the
         routine in the library through the transfer vector.



4.8  Writing Dynamic Libraries

A library is put together from four parts:

     1.  The code and data to perform the library functions
     2.  A definition of the library entry points and characteristics
     3.  A LDLBLK file
     4.  A LDLJCK file


Parts three and four can (and should) be built automatically  from  part
one by using the $DLBLK, $LDLBLK, and $LDLJCK macros from DYNSYM.UNV.

Note that  making  an  existing  library  into  a  dynamic  library  can
sometimes  be  fairly  easy,  requiring only the production of a library
definition.


4.8.1  The Library Definition

The library definition provides one place to put  all  the  declarations
relating  to the dynamic library and its exported addresses.  This makes
for easy reference, and fewer  mistakes  since  all  places  using  this
information get it from the definition.

The definition must specify:

      o  Library name -- must be a valid MACRO name
      o  Library abreviation -- two characters
      o  Library macro name -- must be a valid MACRO name
      o  Library version -- TOPS-20 version number word
      o  Default version matching rule for this library
      o  Service class name -- quoted string
      o  File spec for library EXE file -- quoted string
      o  List of DIGITAL-specified entry point names in their  specified
         order.  Each entry in this list may be either a single name, or
         a sublist as follows:

         1.  Name  for  this  exported  address  (routine  or   galactic
             variable)
         2.  Jacket entry name for routine (defaults to same as  address
             name)
         3.  Condition handling flag (defaults to off)

         All of the entry points defined by DIGITAL must be present,  or
         an error will be issued when you compile the definition.
Dynamic Library Specification                                    Page 14
SOFTWARE CAPABILITIES                                          21 May 86


      o  List of library-specific entry point names.  Same rules as  for
         previous entry
      o  List of DIGITAL-specified  galactic  variable  names  in  their
         specified  order.   All  of  the  galactic variables defined by
         DIGITAL must be present, or an error will be  issued  when  you
         compile the definition.
      o  List of library-specific galactic variable names
      o  Value to statically initialize user word in DLBLK to
      o  Value to statically initialize user word in LDLBLK to
      o  Value to statically initialize flag word in DLBLK to
      o  Value to statically initialize flag word in LDLBLK to



4.8.2  The LDLBLK File

For each library, there must be a source file to build the LDLBLK  file.
Its contents should be as follows:

    SEARCH DYNSYM, library-sym
    $LDLBLK library-macro
    END


4.8.3  The LDLJCK File

For each library, there must be a source file to build the LDLJCK  file.
Its contents should be as follows:

    SEARCH DYNSYM, library-sym
    $LDLJCK library-macro [, just-routine-jacket-flag]
    END

If the just-routine-jacket-flag is set, the  LDLJCK  file  will  contain
only  the  routine  jacket  information and will need to be loaded along
with the LDLBLK file.  Furthermore, in this case you must have specified
alternate  names  for  all  the LDLJCK routine entry points, or else you
will have multiply defined global symbols when you link your program.

(The just-routine-jacket-flag is not supported in V1.)


4.8.4  Master Initialization

The master init routine of a  library  should,  when  called,  set  that
library  to  a clean state.  A freshly master initialized library should
behave exactly as if a clean copy had been loaded.

One of the most important things to  do  in  the  master  initialization
routine  is  to  properly initialize the memory allocation tables.  This
should be done by using a static data structure made  at  the  time  the
library  was  built.   Attempting  to snoop for free pages in the master
initialization routine won't work, since pages used during  a  run  will
not   be   free,   and   yet   should   become  available  after  master
Dynamic Library Specification                                    Page 15
SOFTWARE CAPABILITIES                                          21 May 86


initialization.

The master initialization routine should not do a RESET% JSYS, that will
be done by the top-level program.

The master init routine is called with a PUSHJ 17, adr.   It  may  trash
all registers.

Arguments:  None

Return values:

     1.  Completion status.  0 means OK, anything else means failure.  A
         master  init routine may also signal a condition that indicates
         failure.


Error conditions:  library-dependent


4.8.5  Condition Handling Routines

A condition handler is called with a PUSHJ 17,  adr.   It  may  use  all
registers.

Arguments:

     1.  Address of SIG block for signal to handle.


If the signal is of class SG%UNW, the handler is expected to perform any
necessary cleanup and then exit.  No value is returned in this case.

If the signal is of any other class, the handler is expected  to  decide
what should be done about the condition, and indicate this to SIG by its
return value.

Return values:

     1.  AC0 is the value to be returned by  this  handlers  establisher
         (ONLY IF AC2 CONTAINS .HNUNW)
     2.  AC1 is the signal block to pass upwards (ONLY IF  AC2  CONTAINS
         .HNRES)
     3.  AC2 is the action code describing what action to take:
          o  .HNUNW  --  unwind.   This  causes  a   return   from   the
             establisher   of   this   handler  to  the  caller  of  the
             establisher, passing in AC0 the return value specified  now
             in AC0.
          o  .HNCON --  continue.   This  ends  condition  handling  and
             causes   processing  to  continue  from  after  or  at  the
             instruction that initiated the signal.
Dynamic Library Specification                                    Page 16
SOFTWARE CAPABILITIES                                          21 May 86


          o  .HNRES -- resignal.  This passes the  same  or  a  modified
             condition  on  to  any higher-level condition handlers.  In
             general, a signal block should not be modified  unless  you
             own it;  to resignal a different condition than the one you
             received, make a new signal block containing what you  want
             to  say,  and  set  its  .SGNXT  pointer  to  the block you
             received.




4.9  Details Of Data Structures

4.9.1  The Dynamic Library Block

     1.  .DYCNT -- block word count (must be 9 currently)
     2.  .DYFVN -- Block format version number
     3.  .DYFLG -- Flag word (DIGITAL defined only)
         1.  DY%BSY -- Busy:  library can't start a stream
         2.  DY%VER -- Version  matching  rules.   Version  number  from
             DLBLK  in  this  library  is  compared to version number in
             LDLBLK and this library is accepted if:
             1.  DY%MAG -- major version of library greater  than  major
                 version of LDLBLK
             2.  DY%MAL -- major version  of  library  less  than  major
                 version of LDLBLK
             3.  DY%MIG -- major versions equal  and  minor  version  of
                 DLBLK greater
             4.  DY%MIL -- major versions equal  and  minor  version  of
                 DLBLK less
     4.  .DYUSR -- Library-use word
     5.  .DYVER -- Library version number
     6.  .DYDTV -- IFIW Address of DIGITAL-specified entry-point  vector
         (DTVEC)
     7.  .DYCTV -- IFIW Address of library-specific  entry-point  vector
         (CTVEC)
     8.  .DYDGV -- IFIW Address of DIGITAL-specified  galactic  variable
         vector (DGVEC)
     9.  .DYCGV -- IFIW Address of  library-specific  galactic  variable
         vector (CGVEC)


[The possibility of additional entries is reserved to DIGITAL]

For each of the four classes  of  exported  addresses  described  above,
there is a separate address vector.  Each is a counted vector.

DTVEC:  diglen+1
        IFIW routine entry-point
        . . .
        IFIW routine entry-point

CTVEC:  cuslen+1
        IFIW routine entry-point
Dynamic Library Specification                                    Page 17
SOFTWARE CAPABILITIES                                          21 May 86


        . . .
        IFIW routine entry-point

CGVEC:  cgalen+1
        IFIW address
        . . .
        IFIW address


4.9.2  The Local Dynamic Library Block

This block is linked into a calling program from a library-provided  REL
file.   It  provides  the  section-local  indirect  words  necessary for
referring  to  addresses  in  other  sections.   It  also  provides  the
information  to  identify  and  map  in  the  library  being  called, if
necessary.

     1.  .LDCNT -- Word count (block length) (must be 11 currently)
     2.  .LDFVN -- DYNLIB version  number  for  which  this  LDLBLK  was
         compiled
     3.  .LDFLG -- Flag word (DIGITAL-defined only).  Flags defined are:
         1.  LD%VMA -- Use version match rules from this  LDLBLK  rather
             than from DLBLK
         2.  LD%VER -- Version  matching  rules.   Version  number  from
             DLBLK  in  library  found  is compared to version number in
             this LDLBLK and that library is accepted if:
             1.  LD%MAG -- major version of library greater  than  major
                 version of LDLBLK
             2.  LD%MAL -- major version  of  library  less  than  major
                 version of LDLBLK
             3.  LD%MIG -- major versions equal  and  minor  version  of
                 DLBLK greater
             4.  LD%MIL -- major versions equal  and  minor  version  of
                 DLBLK less
         3.  LD%INI -- Initialized:  library has been loaded and vectors
             updated
     4.  .LDUSR -- User word;  may be set by calling program in any  way
         it wants
     5.  .LDCLS -- OWL/GBP to "service class" string
     6.  .LDSPC -- OWL/GBP to file spec string
     7.  .LDVER -- Library version number
     8.  .LDDTV -- IFIW Address of DIGITAL-specified entry-point  vector
         (LDTVEC)
     9.  .LDCTV -- IFIW Address of library-specific  entry-point  vector
         (LCTVEC)
    10.  .LDDGV -- IFIW Address of DIGITAL-specified galactic vector
    11.  .LDCGV -- IFIW  Address  of  library-specific  galactic  vector
         (LCGVEC)


[The possibility of additional entries is reserved to DIGITAL]
Dynamic Library Specification                                    Page 18
SOFTWARE CAPABILITIES                                          21 May 86


As in the DLBLK, there is a transfer vector for each of the four classes
of exported addresses described above.


4.9.3  The Signal Block

This data structure represents one level of a signal in  progress.   The
top  (most  recently added) level of a signal in progress is supplied to
routines.  Lower levels are available by following the pointer  to  next
block.

All of the pointers are expected to point either into the signal  block,
or into static storage (which need not be released when the signal block
is released).  The pointers may not point into stack  storage,  as  this
may have been released by the time the pointer is used!

Block contents:

     1.  .SGCC -- Condition code
     2.  .SGNXT -- xFIW address of next block
     3.  .SGFAC -- OWL/GBP to ASCIZ facility name
     4.  .SGCND -- OWL/GBP to ASCIZ condition name
     5.  .SGMSG -- OWL/GBP to ASCIZ message
     6.  .SGPC -- PC of source of signal
     7.  .SGCLS -- Class of condition (bit mask)
          o  SG%UNW -- Unwind
          o  SG%APR -- APR trap
          o  SG%DER -- Data error interrupt
          o  SG%QUO -- Disk quota interrupt
          o  SG%EOF -- End of File interrupt
          o  SG%ILI -- Illegal instruction interrupt  (or  monitor  call
             error)
          o  SG%ILR -- Illegal memory read interrupt
          o  SG%ILW -- Illegal memory write interrupt
          o  SG%INS -- Inferior stop interrupt
          o  SG%NXM -- Non-existent page interrupt
          o  SG%PDL -- PDL overflow interrupt (not useful?)
          o  SG%SOF -- Software-originated signal
          o  SG%RES -- System resources interrupt
          o  SG%CHR -- Character interrupt
          o  SG%TRM -- Terminal interrupt
     8.  .SGFLG -- flag word (DIGITAL-defined only)
          o  SG%INT -- At interrupt level
          o  SG%NPR -- Do not print this block (computer use only)
          o  SG%DYN -- This block is dynamic and may be thrown away
     9.  .SGDAT -- xFIW address of signal-specific data, such as:
          o  Character mask for character interrupt
          o  Values involved for APR traps
          o  Page number for nonexistent page traps
          o  Stack pointer for stack overflow traps
          o  User data for software signals
Dynamic Library Specification                                    Page 19
SOFTWARE CAPABILITIES                                          21 May 86


4.9.4  The Condition Code

A condition code is a one-word representation of  the  raw  bones  of  a
condition.  It is essentially the same as a BLISS-36 condition code.

                     SG%FAC                     SG%MSG          SG%SEV

     +---+---------------------------+---------------------------+---+
     |   |                           |                           |   |
     +---+---------------------------+---------------------------+---+

      0 0 0                         1 1                         3 3 3
      0 3 4                         7 8                         2 3 5

Bit 4 (SG%FCD) is set if the  facility  is  customer-defined,  clear  if
DIGITAL-defined.    Bit   18   (SG%MCD)   is   set  if  the  message  is
customer-defined,  set  if  DIGITAL-defined.   SG%ID  covers  the   full
condition ID, bits 4-32.  SG%SUC is the success bit (35).


4.9.5  The Handler Block

A handler block is the set of information describing an establishing  of
a handler.  It is the argument passed to the SIGEST routine.  This block
may be dynamically allocated, but it must remain in  existence  (in  the
same place) throughout the life of the handler it describes.

     1.  .HNHND -- xFIW address of handler
     2.  .HNCLS -- Enable mask (see bit definitions above)
     3.  .HNCIM -- Character interrupt mask
     4.  .HNUDA -- xFIW address of user data
     5.  .HNLEN -- Size of block in words



4.10  Details Of Explicit Calls

There are many functions that the user may request  DYNLIB  and  related
facilities  to perform.  These functions are implemented in the run-time
library;  they are called as any dynamic library routine.

Unless specified otherwise, errors are  reported  by  signalling.   This
signal  can  be  prevented  by  placing  an  ERJMP  or ERCAL instruction
immediately following the potentially offending instruction (and in this
case the address of the signal block is returned in AC1).

The calling sequence for these routines is as follows:  Arguments go  in
sequential  registers  starting with AC1.  Return values go in registers
sequentially following the arguments, unless specified  otherwise  (such
as updated values of input arguments).  The routines should be called as
ordinary routines in a dynamic library -- with PUSHJ P, @routine-name.
Dynamic Library Specification                                    Page 20
SOFTWARE CAPABILITIES                                          21 May 86


Registers 6-17 are preserved unless otherwise specified.


4.10.1  Return Last DYNLIB Error -- DY$LER

(Not in V1)

Returns the address of the signal block (first of chain) describing  the
last  DYNLIB  error,  or  0  if no error has been detected.  This signal
chain is dynamically allocated;  if another DYNLIB error occurs  between
the  time  you  get  the information and the time you use it, it will be
invalid.  You should not attempt to de-allocate this block.

Arguments:  None

Return values:

     1.  Address of signal block (first of chain), or zero if  no  error
         occurred


Error conditions:  None


4.10.2  Force Loading/Overloading -- DY$LOD

(Not in V1)

Force the loading of a dynamic library before a reference to an  address
exported  from  it  occurs.  This could be useful, for example, to cause
the loading of a library containing a  galactic  variable  you  need  to
reference  when  there are no routines in that library, or none that you
want to call.

This call also supports overloading -- deliberately loading  information
about  two  libraries  into one LDLBLK.  This can be useful to replace a
few routines in  a  library  with  private  copies,  without  having  to
duplicate  the  entire library.  These private copies could be debugging
versions of routines not yet ready to be included in the  real  library,
for example.

Arguments:

     1.  Function

         1.  .DYLOD -- Force loading of library.  This  function  cannot
             be applied to the run-time library.
         2.  .DYOLB -- overload one library onto another
         3.  .DYOVC -- overload one vector onto another
Dynamic Library Specification                                    Page 21
SOFTWARE CAPABILITIES                                          21 May 86


Other arguments depend on the function code.

The normal rules for overloading are as follows:


     1.  LTVEC entries not containing their default initial  state  will
         not  be  altered.  The default initial state is "IFIW LDLBLK-1"
         for the user-mode implementation.

     2.  If  an  MTVEC  entry  contains  0  in  its  right   half,   the
         corresponding  LTVEC entry is not altered.  0 in the right half
         covers IFIW 0 and location 0 in any section.

     3.  If the LTVEC is longer than the MTVEC, excess  LTVEC  locations
         are not altered.

     4.  If the MTVEC is longer than the  LTVEC,  the  additional  MTVEC
         entries are ignored.



4.10.2.1  .DYLOD -- Force loading of library

Additional arguments:

     1.  Address of the LDLBLK of the library to load


Error conditions:

      o  Any error possible when implicitly loading a dynamic library



4.10.2.2  .DYOLB -- overload one library onto another

Load one library over another according to the  rules  for  overloading.
Standard  version  checking  is  performed  on  both  DYNLIB and library
versions for both source and destination libraries.

Arguments:

     1.  Address of LDLBLK of source library (need not be already mapped
         in)
     2.  Address of LDLBLK of destination library (need not  be  already
         mapped in)


Error conditions:

      o  Any error possible when implicitly loading a dynamic library
Dynamic Library Specification                                    Page 22
SOFTWARE CAPABILITIES                                          21 May 86


4.10.2.3  .DYOVC -- overload one vector onto another

This function is used to overload  only  one  address  vector  from  one
library  over  another.   Standard version checking is performed on both
source and destination libraries.

Arguments:

     1.  Address of LDLBLK of source library
     2.  Address of source vector
     3.  Address of LDLBLK of destination library
     4.  Address of destination vector


Error conditions:

      o  Any error possible when implicitly loading  a  dynamic  library
         may occur



4.10.3  Global Master Initialization -- DY$MIN

Resets all libraries already mapped in to their uninitialized  state  by
calling the master initialization point in each such library.

All registers are trashed.

Arguments:  None

Error conditions:

      o  Any error condition signalled or returned in the defined manner
         by  any  of the master initialization routines called is passed
         on to the caller of DY$MIN.



4.10.4  Allocate Memory Block -- ME$ALM

Allocate a block of memory without page alignment.

Arguments:

     1.  Chunk identifier
     2.  Block size in words


Return values:

     1.  (in T1) Chunk identifier
Dynamic Library Specification                                    Page 23
SOFTWARE CAPABILITIES                                          21 May 86


     2.  (in T2) Address of block allocated


Error conditions:

      o  No room in chunk specified for block requested
      o  Chunk specified is invalid


The block returned starts  at  the  address  given  and  is  the  length
specified.   The  words  preceeding  and following the block contain RTL
information used when the block is released.  Since  this  word  is  not
part  of  the block given you, it should be no strain to keep your hands
off it!


4.10.5  Allocate Pages Of Memory -- ME$ALP

(Not in V1)

Allocate memory in full, contiguous pages.

Arguments:

     1.  Chunk in which to allocate
     2.  Number of pages to allocate


Return values:

     1.  Address of first page allocated


Error conditions:

      o  Section not under control of RTL
      o  Space requested not available in section requested



4.10.6  Create A New Section -- ME$ALS

(Not in v1)

Allocates  a  free  section  and  creates  it   (the   monitor   doesn't
automatically create a section when you first refer to an address in it,
as it does for individual pages within pre-existing sections).

Optionally, puts the newly-created section under the control of the  RTL
memory manager.
Dynamic Library Specification                                    Page 24
SOFTWARE CAPABILITIES                                          21 May 86


This  is  the  only  valid  way  to  create  a  section  in  the  DYNLIB
environment.   (The section that a new dynamic library is mapped into is
allocated through ME$ALS by DYNLIB.)

This should probably  be  extended  to  allocate  groups  of  contiguous
sections.

Arguments:

     1.  Set if section should be controlled by the RTL memory manager


Return values:

     1.  Number of the section allocated


Error conditions:

      o  No sections available



4.10.7  Return Memory Block -- ME$DLM

Return a block of memory allocated with ME$ALM.

Arguments:

     1.  Address of block to return


Return values:  None

Error conditions:

      o  ME$NAL:  Block wasn't allocated



4.10.8  Return Memory Pages -- ME$DLP

(Not in V1)

Arguments:

     1.  Address of first page
     2.  Number of pages


Return values:  None
Dynamic Library Specification                                    Page 25
SOFTWARE CAPABILITIES                                          21 May 86


Error conditions:

      o  Section not under control of RTL
      o  Some or all of the pages being returned were not allocated



4.10.9  Destroy A Section -- ME$DLS

(Not in V1)

Sections not under the control of the RTL memory manager  are  destroyed
immediately on request.

Sections controlled by the RTL memory manager are "frozen" on this  call
--  no more space will be allocated out of them.  They will be destroyed
when all of the space allocated from them is returned.

This needs support for groups of sections (as in ME$ALS).

Arguments:

     1.  Section number


Return values:  None

Error conditions:

      o  Section is not allocated



4.10.10  Sub-contract Memory Management -- ME$MEM

Create a memory chunk that can be allocated from.

Arguments:

     1.  Address of first word of chunk
     2.  Address of last word of chunk


Return values:

     1.  Chunk ID in T3


Error conditions:

      o  ME$NCA:  No chunk ID available
Dynamic Library Specification                                    Page 26
SOFTWARE CAPABILITIES                                          21 May 86


4.10.11  Formatted ASCII Output -- RL$FAO

Format a message given a model string and  some  arguments  to  fill  in
from.

Arguments:

     1.  Destination string pointer
     2.  Max allowable destination string length
     3.  Model (pattern) string pointer
     4.  Address of first arg (others follow at higher addresses).  Note
         that this may be on the stack, or elsewhere;  FAO doesn't care
     5.  Count of args


Return values:

     1.  Destination pointer is updated in T1
     2.  Count is decremented in T2
     3.  T3-T5 are trashed


The pattern  string  is  a  simple  ASCIZ  string  with  special  escape
sequences  in  it  that  cause  substitution from the list of arguments.
Each argument is used at most once, in the order listed.

All escape codes begin with an exclamation point.  The codes  and  their
meanings are:
                    !/ Put a CRLF into output 
                    !_ Put a TAB into output
                    !! Put an exclamation mark into output
                    !^G Put a BEL into output (ASCII 7, not G)
                    !OW Put next arg to output as octal word
                    !SW Put next arg to output as signed decimal word
                    !OH Put next arg to output as octal halfwords (good
     for PC's)
                    !AA Put 7-bit ASCIZ string at address given by next
     arg to output
                    !AZ Put ASCIZ string pointed to by next arg to
     output
                    !AC Put string pointed to by next arg to output, max
     of next arg
     chars
                    !%S Put capital S to output if last number printed
     was not 1
                    !%s Put lower case s to output if last number
     printed was not 1
                    !JFN Put file spec corresponding to JFN in next arg
     to
     output
                    !VER Put next arg to output interpreted as version
     number
                    !JER Put JSYS error text for error code in next arg
     to
Dynamic Library Specification                                    Page 27
SOFTWARE CAPABILITIES                                          21 May 86


     output


4.10.12  Allocate An Interrupt Channel -- SG$ALC

(Not in V1)

Arguments:  None

Return values:

     1.  Channel assigned


Error conditions:

      o  No interrupt channels available



4.10.13  Disable Interrupt Characters -- SG$DIC

(Not in V1)

Requests that a character be made a non-interrupt character.  Note  that
the  count of enable versus disable requests is what controls the actual
status of a character at any given moment

Arguments:

     1.  Character mask


Error conditions:  None


4.10.14  Return An Interrupt Channel -- SG$DLC

(Not in V1)

Arguments:

     1.  Interrupt channel to return


Return values:  None

Error conditions:

      o  The interrupt channel returned was not allocated
Dynamic Library Specification                                    Page 28
SOFTWARE CAPABILITIES                                          21 May 86


4.10.15  Deallocate A Signal Chain -- SG$DLG

Deallocate all blocks in a signal chain flagged as dynamic.

Arguments:

     1.  Address of first block in chain


Return value:  None

Error conditions:
      o  ME$NAL:  Block not allocated (for any block along the chain)



4.10.16  Dump An SG Chain -- SG$DMG

Print a formatted dump of a chain of SG blocks on the terminal.

Arguments:

     1.  Address of first block in chain


Return Value:  None

Error conditions:  None


4.10.17  Enable Interrupt Characters -- SG$EIC

(Not in V1)

Requests that a set of characters be  made  interrupt  characters.   The
count  of  enable  versus  disable  requests is what controls the actual
status of a character at any given moment.

Arguments:

     1.  Character mask


Return values:  None

Error conditions:

      o  Insufficient interrupt channels available
      o  Cannot isolate characters you want from previous requests
Dynamic Library Specification                                    Page 29
SOFTWARE CAPABILITIES                                          21 May 86


4.10.18  Establish A Condition Handler -- SG$EST

Establish a condition handler for the current routine.  SIGEST  must  be
called before anything is done to the stack within the routine.

For non-macro programs, the technique for  establishing  is  to  make  a
jacket routine that performs this call.  This is done automatically when
you set the "jacket" flag in the library definition  for  this  routine.
(Not in V1)

There are restrictions on  the  linkage  conventions  of  routines  that
establish handlers.

ALL registers are preserved.

Arguments (pushed onto the stack before call):

     1.  Address  of  handler  block  (this  block  may  be  dynamically
         allocated,  but it must remain in existence throughout the life
         of the handler)


Return values:  None

Error conditions:

      o  Invalid handler block
      o  Insufficient room on enable stack



4.10.19  Establish A Handler Locally -- SG$LES

This is a version of SG$EST to be called  from  within  BLISS  routines.
This routine is for use by WIZARDS only!!  In particular, unwinding to a
routine that enables for condition handling this way is almost certainly
a mistake.

Registers 2-16 are preserved.

Arguments:

     1.  Address of handler block


Return Values:  None

Error conditions:  None
Dynamic Library Specification                                    Page 30
SOFTWARE CAPABILITIES                                          21 May 86


4.10.20  Remove A Handler Locally -- SG$LRM

Remove a locally established handler

Registers 2-17 are preserved.

Arguments:

     1.  Address of handler block


Return value:  None

Error conditions:

      o  SG$ROS:  Cannot remove a handler other than the  most  recently
         established



4.10.21  Make Signal Block For Last Monitor Error -- SG$MER

(Not in V1)

Arguments:  None

Return values:

     1.  Address of signal block created


Error conditions:

      o  No monitor error has occurred



4.10.22  Print Error Messages -- SG$PEM

Prints a sequence of error messages  from  a  chain  of  signal  blocks.
Various arguments control depth and format of printing.

Arguments:

     1.  Destination designator
     2.  Address of signal block
     3.  Maximum depth to print messages for
     4.  Address of suffix list
     5.  Address of prefix list
Dynamic Library Specification                                    Page 31
SOFTWARE CAPABILITIES                                          21 May 86


The prefix and suffix lists are vectors of  OWL/GBP  to  ASCIZ  strings,
intended to be indexed by severity.  The strings pointed to are prefixes
and suffixes for messages.

Return values:  None

Error conditions:

      o  Invalid signal block encountered



4.10.23  Remove A Condition Handler -- SG$REM

Remove the condition handler established for the current routine.   This
must be done just before routine exit.

All registers are preserved.

Arguments (push on stack):

     1.  Address of handler block (must be same block passed to SIGEST)


Return values:  None

Error conditions:

      o  The handler being removed is not the most recently  established
         one
      o  Invalid handler block



4.10.24  Declare Trap Handler For Section -- SG$SEC

(Not in V1)

Specify an APR trap and fixed interrupt handler for all events occurring
in  a specified section.  This is provided for convenience in converting
existing libraries with their own trap handlers, and  to  allow  use  of
traps  in  a  library  without  the  overhead  of enabling for condition
handling.

Arguments:

     1.  Section number
     2.  Address of handler block


Return values:  None
Dynamic Library Specification                                    Page 32
SOFTWARE CAPABILITIES                                          21 May 86


Error conditions:

      o  A  handler  has  already  been  established  for  the   section
         specified
      o  The section specified does not exist



4.10.25  Signal -- SG$SIG

Signal a software condition.  Under some conditions, this  routine  does
not  return.  This is determined by whatever handler finally handles the
signal.  If it does return, it returns with all registers preserved.

Arguments:

     1.  Address of signal block


Return values:  None

Error conditions:

      o  Invalid signal block



4.11  Details Of Galactic Variables Defined

The RTL defines some  galactic  variables  to  allow  users  to  control
certain aspects of its operation without having to make calls to special
routines to set internal values.


4.11.1  Signalling Information

SIG makes certain internal information available as galactic variables.


4.11.1.1  Enable stack pointer -- SG.ENS

The stack pointer for the enable stack.  Each frame on the enable  stack
holds  an  establish  block  describing  one  handler  that is currently
established.

This is for use by experts only!  You can cause a lot  of  trouble  with
this, if you want.


4.11.2  Last-ditch Handler Parameters
Dynamic Library Specification                                    Page 33
SOFTWARE CAPABILITIES                                          21 May 86


4.11.2.1  Maximum depth -- SG.LEV

No more than this many levels of messages will be printed (blocks  in  a
signal  chain  for which no message is printed do not count against this
limit).  To print  "all"  levels,  set  this  to  an  outrageously  high
positive value.  Signal chains should never get "too" deep.


4.11.2.2  Destination designator -- SG.OUT

Last-ditch messages may be directed to places other than primary output.
If  attempting  to output to the destination specified fails, it will be
reset to primary output and the message will be printed there.   Setting
this  to  a  byte  pointer has some potential problems -- it doesn't get
copied back to SG.OUT after it's used, so  messages  will  overlay  each
other in the memory area specified.


4.11.2.3  Prefix table address -- SG.PFX

The prefix table is indexed by severity to find the OWL/GBP to an  ASCIZ
string to print before the message.  This is where the "?" before errors
or the "[" before informational messages comes from.


4.11.2.4  Suffix table address -- SG.SFX

Like SG.PFX, but strings go after the message.  This is where the "CRLF"
after errors or the "]CRLF" after informational messages comes from.


4.11.2.5  Default prefix table -- SG.DPX

This is the default prefix table.  By executing
     XMOVEI T0, @SG.DPX
     MOVEM T0, @SG.PFX
you will reset the LDH to use the default prefix table.  You should  not
attempt  to change the contents of the default prefix table -- it may be
in write-protected memory.


4.11.2.6  Default suffix table -- SG.DSX

This is the default suffix table, very similar to SG.DPX.


4.12  DYNLIB Bootstrap

As much of DYNLIB as possible will actually reside in  the  RTL.   Since
DYNLIB  is  used to bring in the RTL, "as much as possible" will be less
than "all".
Dynamic Library Specification                                    Page 34
SOFTWARE CAPABILITIES                                          21 May 86


The subset of DYNLIB necessary to bring in the RTL will be available  in
the  file DYNBOO.  All programs calling dynamic libraries must link with
DYNBOO.


5.0  PUBLICATIONS

DYNLIB development will include the preparation of two  documents,  "How
to  write  a  Dynamic  Library"  and  "How  to  call a dynamic library",
intended respectively for developers of dynamic libraries and  users  of
dynamic libraries.

These documents will be prepared by the engineering staff, there  is  no
funding for technical writers.

There is no plan to distribute these documents outside of Digital.


6.0  PACKAGING

The DYNLIB facility is being developed for Datatrieve.  We want to  make
it  available  to  all  layered  products  in the longer run.  The first
release of DYNLIB will be packaged with Datatrieve-20 version 1.


7.0  INSTALLABILITY

DYNLIB will be installed as part of the installation of Datatrieve-20.


8.0  EASE OF USE

9.0  PERFORMANCE

Since DYNLIB is intended to be widely used as  the  basis  for  building
products  out  of  layers  of  building-blocks,  performance  can  be an
important issue.  We believe, based on the usage of existing  libraries,
that  the  vast  majority  of  the  interactions  between a caller and a
package will be routine calls.

Calling a routine in a dynamic library will be done with a single  PUSHJ
using  one  level  of  indirect  addressing (unless the user writes code
requiring more to get to the  transfer  vector)  after  the  first  call
through any given LDLBLK.

Referring to an exported address  will  simply  require  one  additional
level  of  indirection  relative  to  referring to that address locally.
Since indirection is necessary  to  reference  outside  of  the  current
section  anyway, DYNLIB will cost absolutely nothing on references after
the first.
Dynamic Library Specification                                    Page 35
PERFORMANCE                                                    21 May 86


The first reference to an address exported from a dynamic  library  will
potentially  take  a long time, since a GTJFN% is performed.  This could
potentially require searching through thousands of  file-names,  if  the
logical  names  used  are  defined  wrong.   There is also the matter of
creating a section and  mapping  the  file  into  that  section.   On  a
"reasonably"   heavily  loaded  system,  and  assuming  only  moderately
perverse search lists, it  could  take  5  seconds  to  load  a  dynamic
library.

The other DYNLIB functions  are  very  infrequently  used  and  are  not
performance-critical.

Many of the RTL  functions  have  no  performance  requirements  in  the
Product  Requirements document.  This is because they aren't required in
and  of  themselves,  but  turn  out  to  be  necessary  to  meet  other
requirements.


10.0  RELIABILITY

Because the  first  product  using  dynamic  libraries  to  be  seen  by
customers,  Datatrieve-20,  is  aimed  at  inexperienced  users,  it  is
especially important that dynamic libraries not introduce any mysterious
(from  the  users'  points  of  view) errors.  Ideally, no errors should
occur.  Next best is for errors to explain themselves clearly.

DYNLIB use rule:  all programs which call dynamic libraries should check
for  errors  after  each  call, and present them to the user in a manner
compatible with the other user interactions made by the program.


11.0  MAINTAINABILITY

DYNLIB and its support procedures will be written in MACRO.  I view this
as  an  unfortunate  choice,  but  since  DYNLIB is intended to become a
bundled part of the TOPS-20 operating system eventually,  it  should  be
written   in   a  language  which  purchasers  of  TOPS-20  sources  can
understand.  The tools for building libraries must be in  macro  anyway,
since they must be usable at all customer sites.

Most of the actual DYNLIB code will live in the RTL, with only  a  small
bootstrap  routine  to  load  the  RTL  on  the  first call to a dynamic
library.

DYNLIB will be autopatchable in the field.  (What will it be autopatched
as part of?  At first?  Later?)


12.0  MAINTENANCE

Maintenance of this product will be performed by Software Engineering.
Dynamic Library Specification                                    Page 36
MAINTENANCE                                                    21 May 86


Updates will appear as necessary on the autopatch tapes.


13.0  COMPATIBILITY

13.1  Compatibility With Existing Libraries

An existing library that will run  in  an  arbitrary  non-zero  section,
using  no  traps  or interrupts, can be made a dynamic library simply by
writing a library definition and an  appropriate  master  initialization
routine.

A library using traps and interrupts would be somewhat  more  difficult.
The  degree  of  dificulty  would depend on how the traps and interrupts
were used.  It could still be quite simple, on the order of a day's work
by somebody who already understood dynamic libraries.


13.2  Product Compatibility

13.2.1  Dependency Issues

We  must  come  to  a  consensus  with  the  TOPS-20  monitor  group  on
interpretation of PDV's.

We must come to  a  consensus  with  the  LINK  and  monitor  groups  on
LINK-provided memory maps.


13.3  Standards Conformance

13.4  Internationalization

No requirements in this area.


14.0  EVOLVABILITY

A Monitor DYNLIB facility could be written which would  replace  DYNBOO.
This  would,  I  hope,  be  relatively  simple.   All the rest of DYNLIB
version  would  would  be  preserved,  and  performance  would   improve
somewhat.


15.0  COSTS

DYNLIB is being developed as part of the Datatrieve-20 project.

We hope to limit the development of DYNLIB to  4  man-months  (including
all time spent from writing specification to field-test entry).
Dynamic Library Specification                                    Page 37
TIMELINESS                                                     21 May 86


16.0  TIMELINESS

The  product  must  be  ready  to  field-test  and   ship   along   with
Datatrieve-20.


17.0  CONSTRAINTS AND TRADES-OFF

Ease of conversion of an existing library is more important than keeping
the call overhead of that library within the bounds specified.  However,
new libraries implemented according to the instructions to be  developed
as  part  of  DYNLIB  must  meet the call overhead limits.  There may be
different techniques for defining a new dynamic library  and  a  dynamic
interface to an existing library.


18.0  APPROVAL PROCESS

DYNLIB is being developed within the  Datatrieve-20  project,  but  will
probably be used by many other projects.  The normal approval process as
applied to Datatrieve-20 probably will not give sufficient visibility to
DYNLIB to ensure that necessary feedback from other groups is received.

Special efforts will be made to circulate DYNLIB  documents  to  project
leaders  and  supervisors throughout LSG Software Engineering.  Selected
consultant-level people within the group will be approached individually
for their comments.