Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

.! Body of Dynamic Library Requirements document
.page size 58, 72
#
.subtitle
.first title
.flag quote `
.flag capitalize
.flag index
.flag period
.set paragraph 0, 1, 3
.autoparagraph
.style headers 5, 1, 4
.title TOPS-20 Dynamic Library Requirements
.number page 1

.page

.! See the Software Policies and Procedures manual for more detail

.hl 1 Product Summary

  A "routine library" (often called simply a "library") is a group of
routines and data which is intended to provide services to its caller.
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.  In this form of library,
the association between addresses exported from the library (such as
routine entry points) and references to those addresses in the caller
(for example, routine calls) is made by the linker, at link time.

  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.  The assocation between exported
addresses and references is made dynamically at that time.

  This document states the requirements for a dynamic library facility
for TOPS-20.  This facility will include code to support the dynamic
linking functions described above, support facilities such as .UNV
files and .L36 files to simplify use of the functions, documentation,
and rules for use.

  The dynamic library facility described in this document should, if
implemented, provide the following benefits compared to continued use
of REL libraries in the current style:

.list 1, "o"
.le;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).

.le;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.

.le;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.  

.le;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.

.le;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.
.end list

.hl 1 Terminology and conventions

  This document exists primarily to specify requirements for 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 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.  

  A requirement of DYNLIB will always appear in a paragraph by itself,
and will begin with "REQUIREMENT:".  

  Goals of DYNLIB of lower priority than a requirement will be listed
in the same format as requirements, substituting "GOAL:" for
"REQUIREMENT:". 

  Sometimes, due to our experience with the DYNLIB prototype or for
other reasons, we may think that a goal or requirement is not fully
attainable.  A paragraph beginning "RESTRICTION:" will describe parts
of requirements or goals that may not be attainable.  The purpose of
this is to give a realistic set of requirements which can be met.

.NOTE
A restriction is not a requirement.  That is, the presence
of a restriction in this document is ^&not a demand\& that that
restriction be placed in the final product.  Rather, it is a statement
that that restriction ^&is acceptable\& in the final product ^&if it is
found to be necessary\& during phases 1 and 2.
.END NOTE

  Related to the DYNLIB requirements 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:".  Many more rules than appear here will be
necessary; only the ones following directly from these requirements
are included here.  The full set of rules for writing a dynamic
library will be documented as part of the development effort of this
project. 

.hl 1 Environment

.hl 2 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.

  GOAL: Dynamic libraries will (eventually) be used implicitly by most
higher-level language programs, but this must be transparent to
customers using those languages.

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

  Digital-written utilities will also use dynamic libraries
extensively.

.hl 2 Hardware

  REQUIREMENT: DYNLIB must run on a PDP-10 family processor with
extended addressing (i.e.  KL model B).  KS processors need not be
supported.

  REQUIREMENT:  DYNLIB must run on microcode version 326 and later.

As described below, DYNLIB will encourage the use of extended
addressing.  Some dynamic libraries may discover microcode and monitor
bugs relating to extended addressing.  Anticipating and fixing these
bugs is not part of the development of DYNLIB.

.hl 2 Software

.HL 3 Other software required for DYNLIB

  REQUIREMENT: DYNLIB must run on TOPS-20 release 5.1 and 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.

.HL 3 Other software that requires DYNLIB

  DYNLIB is required for Datatrieve-20 V1.0, dynamic extended RMS
(V3), and dynamic callable DBCS (V7).

  All other software projects should consider if they would benefit
from using DYNLIB.  In particular...

  EXTERNAL REQUIREMENT: Projects implementing RMS access for the first
time should call RMS as a dynamic library.

.hl 2 Services

  No special services are required for DYNLIB.  

.hl 1 Software Capabilities

.hl 2 DYNLIB Capabilities

  In any library, the addresses of some objects in the library must be
made available for use outside the library.  Routine entry point
addresses and, more rarely, addresses of data locations must be
"exported" from the library.  In REL libraries, this is done using
global symbols.  In VAX/VMS sharable images, this is done using what
they call "universal" symbols (more global than global symbols).

  REQUIREMENT:  It must be possible to export the addresses of routine
entry points and data locations from a dynamic library to its caller.

  REQUIREMENT: It must be possible to call a dynamic library from a
non-zero section.

  REQUIREMENT: It must be possible to call a dynamic library from
section 0.  This is provided ONLY to ease conversion of existing
programs to use of dynamic libraries.  See Performance, below

  RESTRICTION: From section 0, it need not be possible to refer to
addresses exported from a dynamic library in any manner other than a
routine call.

  REQUIREMENT: It dynamic libraries must work in non-zero sections.

  RESTRICTION: It is not necessary for dynamic libraries to work in
section 0.

  REQUIREMENT:  The contents of a dynamic library must not be part of
the address space of its caller until a reference is made to an
address exported from that library.  (This requirement simply insists
that a dynamic library be in fact ^&dynamic\&.)

  REQUIREMENT:  Using an address exported from a dynamic library must
be as similar as possible to using an address exported from a REL
library.  

  RESTRICTION: Since DYNLIB must support extended addressing, and since the
location in memory of a dynamic library may not be known at link time,
it is acceptable to require that references to addresses exported from
dynamic libraries be indirect through a pointer supplied by the
dynamic library or DYNLIB.

  RESTRICTION:  It is not necessary for DYNLIB to work in execute-only
programs or with execute-only libraries.  Because DYNLIB will work by
merging EXE files into the running program, it will not work with the
current implementation of execute-only.  

.hl 2 Writing a dynamic library

  It would be nice to be able to write dynamic libraries in any
language.  There are several reasons why this cannot reasonably be
made a requirement:
.list 1, "o"
.le;Many languages do not produce code that will run in a
non-zero section.
.le;Most language OTS's will not run in a non-zero section.
.le;Most language OTS's think they own the entire process they reside
in.  If dynamic libraries were written in these languages, the OTS in
one dynamic library would quite probably conflict with the OTS in
another dynamic library, even if they were written in the same
language.  Memory management, the software interrupt system, and APR
trapping are likely areas of conflict.
.end list

  REQUIREMENT: it must be easy to write dynamic libraries in BLISS
and MACRO.

.hl 3 Passing Control and Returning

  REQUIREMENT: Invoking a dynamic library must be made as
transparent as possible (invoking the dynamic library should look as
much as possible like invoking a routine from a REL library).  No
special subroutine call may be required to load a dynamic library.
The library must be loaded as a side-effect of referring to an address
exported from it.

  RESTRICTION:  Before monitor support for DYNLIB is implemented, it is
acceptable to require that a routine in any given dynamic library be
called before referring to an address exported from that library by
any method other than a routine call.  This restriction is necessary
if products using DYNLIB are to ship before the next major monitor
release.

  RESTRICTION:  It is acceptable to require that calls to routines in
dynamic libraries be made with the PUSHJ instruction and that the
routines return with the POPJ instruction.

  It is not acceptable for a dynamic library to insist that it be
mapped in at a fixed address.  If it were done, there is every
possibility that two dynamic libraries requiring the same address
would be called from the same program.  (Consider the problems already
encountered in sharing section zero between a user program, DDT,
PA1050, FOROTS, COBOTS, and RMS.)  Since one of the goals of DYNLIB is
to encourage using dynamic libraries as building blocks when
constructing a program, this is unacceptable.

  On a PDP-10, the hardware makes no good provision for writing
position independent code.  However, it is easy to write section
independent code that will run happily in any non-zero section.

  RESTRICTION: It is acceptable to assign an entire section to each
dynamic library invoked.  On a KL, this limits a program to using at
most 30 dynamic libraries.

.HL 3 Memory allocation

  Memory is a resource that must be obtainable dynamically by all of
the parts of a program, including all dynamic libraries which that
program calls.

  REQUIREMENT: DYNLIB must own the entire address space of any process
which calls dynamic libraries.  DYNLIB must provide facilities for
dynamic libraries and main programs to allocate address space in units
of whole sections, pages, and words.

  RESTRICTION: If, as suggested above, DYNLIB assigns each dynamic
library its own section, DYNLIB need supply only a section allocator
and a rule saying that the memory in each section must be managed by
the program or library which created it or was placed into it by
DYNLIB.

  GOAL: There should be some user control of section allocation.

  EXTERNAL REQUIREMENT: The TOPS-20 monitor must not create sections
automatically when pages in nonexistent sections are written to.
Creating these sections automatically would mask errors in section
allocation or data reference.

.hl 3 PSI and Trap management

    The APR trap system and the software interrupt (PSI) system are
unique resources that must somehow be shared among all the packages of
code making up a program.  For example, Datatrieve wants to trap all
arithmetic exceptions occurring while it executes, and issue
appropriate messages to the user.  When Datatrieve calls MTHLIB,
however, MTHLIB wants to trap the overflows itself and perform fixups.
This sort of layered use of these unique resources must be possible.

  Some channels of the PSI system have fixed meanings.  These are
essentially the same as traps.  Some  events, such as characters
typed at the terminal, can be assigned to any available PSI channel.
These  events are also similar to traps.  These events are potentially
of global interest, so the ability to detect them should be considered
a resource, and this resource must be made sharable.

  On the other hand, receipt of a decnet or IPCF message is not an
event of general interest.  The ability to detect these message is a
resource, but not one that needs to be sharable since only the package
waiting for the message really cares.  However, the PSI channels used
to capture such events are resources, and must be allocated centrally
to avoid conflicts.

  For the purposes of this document, any of the following will be
referred to as the occurrence of a "condition":  occurrence of an APR
trap, an interrupt on a fixed channel, an interrupt on a channel
assigned to character interrupts.  Possibly, conditions could also be
initiated by software, perhaps by a call to a DYNLIB routine.  This is
very similar to the VMS concept of condition.

  For a routine in a program (or library) to "handle" a condition
means for that routine to be informed of that condition, and take
whatever action is appropriate and possible.

  For DYNLIB to "handle" a condition means for DYNLIB to route the
condition to appropriate user-supplied routines for handling.  Every
routine in the chain of calls from the top-level program to the
routine within which the condition occurred should have the right to
specify ("enable") a condition handling routine.  We refer to this as
"hierarchical handling" of the condition because the condition is
called to the attention of a hierarchy of handling routines.

  REQUIREMENT: DYNLIB must provide rules and facilities for
hierarchical handling of: APR traps, character interrupts, interrupts
on PSI channels with fixed meanings.  These facilities must be
available anywhere within any program using DYNLIB, not just from
within dynamic libraries.

  REQUIREMENT: A routine in a program using DYNLIB must have the
option of "enabling for condition handling" by specifying to DYNLIB a
routine which will handle any conditions occurring in the enabling
routine or beneath it which are not handled by handlers enabled lower
down.  The handler routine enabled must then be called for each
condition it is eligible to handle.  When the routine that enabled the
handler exits, the handler must be disabled.

  RESTRICTION:  It is allowable to require that routines which enable
a handler must make a  DYNLIB call to disable the handler before they
exit.

  REQUIREMENT: A condition handler routine must have at least the
following options when called for a condition: pass the same condition
on to the next higher handler, ignore the condition and continue from
the point where the condition occurred, and unwind the stack causing a
return from the handler's establisher with a  return value specified by
the handler.

  RESTRICTION:  It is acceptable to require routines which enable a
condition handler to be called with some restricted set of linkages.

  GOAL: Handling character interrupts should use as few channels as
possible.

  REQUIREMENT:  DYNLIB must provide rules and facilities for
allocating the assignable PSI channels.

  REQUIREMENT: DYNLIB must provide hierarchical handling of
software-originated conditions.  This facility does not need to
interact with BLISS signalling.  This facility must, however, coexist
with BLISS signalling in the same routines, modules, and programs.

  As a grafted-on facility, it is not expected that DYNLIB condition
handling will perform as well as built-in facilities such as BLISS
condition handling or VMS condition handling.  It is not expected that
DYNLIB condition handling will be the primary means of handling
exception conditions in most programs.  However, these performance
problems appear unavoidable given the major goal of facilitating
sharing of unique resources such as the trap and PSI systems.

  REQUIREMENT:  Meeting the goals in this section must not impose any
additional overhead on routines not enabling for any of these
conditions.

  GOAL:  Routines enabling for these conditions should not incur more
than 20 additional instructions and 10 words of additional data.

.hl 3 Error Handling

  Although it is desirable that only a single piece of code be written
to supply any given service, the interface presented to the user of a
program must be controllable by the top-level program.  In particular,
packages called as subroutines shouldn't do any terminal I/O unless
specifically requested to by the top level.

  REQUIREMENT:  DYNLIB must provide rules and/or facilities allowing
packages called through DYNLIB to report errors back to their callers
without loss of important information.  

.hl 3 Initialization

  With TOPS-20 release 6, DIGITAL is shipping the multi-forking EXEC
as the standard version to the field.  Since many products take
significant amounts of time to initialize (due to finding and mapping
in dynamic libraries, processing initialization files, opening log
files, or whatever), many users will probably form the habit of
keeping around the forks which contain their more commonly used
utilities.  This makes it more important than ever that utilities be
written to be restartable.

  REQUIREMENT: Instructions must be provided on how to write dynamic
libraries and main programs so that the resulting programs are
restartable.  It is not acceptable to require that dynamic libraries
be found and mapped in again on a restart.

.hl 3 Debugging

  REQUIREMENT:  There must be good support for debugging dynamic
libraries.  The standard debugger used for debugging programs written
in any language must work for debugging dynamic libraries written in
that language before we can claim that dynamic libraries can be
written in that language.

  RESTRICTION:  It is acceptable to require that BLISS-36 programs be
debugged using DDT rather than SIX12.

.hl 2 De-linking

  Earlier work on monitor support for dynamically linked libraries has
specified special monitor actions when saving a memory image of a
program which used dynamic libraries.  Some of those actions are not
compatible with the requirements for DYNLIB.

  EXTERNAL REQUIREMENT: it must be possible to save a memory image of
a program that called dynamic libraries that includes all the
libraries that it had mapped in up to the time of the save, and their
internal states excepting AC's and open files.

  RESTRICTION:  it need not be possible to save a program, after
running it, in such a way that running the saved image will call in
new copies of any dynamic libraries used.

.hl 2 "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.

  REQUIREMENT: DYNLIB must work with non-streamed and infinitely
multi-streamed libraries.

.hl 2 Library version checking

  When a library is called using DYNLIB, the association between the
call and the particular version of the library obtained is made at
run-time.  Libraries must be allowed to evolve and improve, which will
result in some cases in changes to the addresses exported from a
library.  It is necessary to provide some way to check whether the
version of a library actually found is compatible with the version the
caller was built to call.

  REQUIREMENT: Dynamic libraries must have version numbers associated
with them.  These numbers must be stored as part of the library.  A
program which calls dynamic libraries must contain the version of each
library it calls that it was built for.

  REQUIREMENT:  When DYNLIB finds and maps in a dynamic library, it
must compare the version number of the library against the version
number expected by the caller and return an error if the version found
is not acceptable.  Which versions are acceptable must be definable by
the library or the caller.

.hl 2 DYNLIB version checking

  To allow for the possibility of major improvements to DYNLIB, DYNLIB
should be assigned a version number; the version should be checked
whenever DYNLIB is invoked.

  REQUIREMENT:  DYNLIB must be assigned a version number.  DYNLIB
must know at run-time what version number it is.

  REQUIREMENT: Callers and dynamic libraries should contain the number
of the version of DYNLIB they are built for.  When DYNLIB performs a
service for a caller, it should first check if the version of DYNLIB
actually in use is acceptable to the caller and, if one is involved,
the dynamic library.  Acceptability of versions of DYNLIB should be
defined in DYNLIB.  If the version of DYNLIB in use is not acceptable
to the caller or to the callee, the DYNLIB function requested must
return an error indication as described below.

.hl 1 Publications

  REQUIREMENT:  There must be documentation aimed at users of dynamic
libraries. 

  REQUIREMENT:  There must be documentation aimed at writers of
dynamic libraries.

  There will probably be many more people calling dynamic libraries
than there will be writing dynamic libraries.

  GOAL:  The "user" and "writer" documentation should be separate.

  GOAL:  The DYNLIB documentation should be published manuals.

  REQUIREMENT: For any languages in which we wish to claim that it is
possible to write dynamic libraries, there must be language-specific
documentation on how to do so.  Such documentation must be produced
for at least MACRO and BLISS.

  GOAL:  For at least the major higher-level languages (FORTRAN,
COBOL, PASCAL), there should be documentation on how to call dynamic
libraries from the language.

  RESTRICTION: Since DYNLIB is not a utility directly used by users,
there need not be any HELP files associated with DYNLIB.

.hl 1 Packaging

  The DYNLIB facility is being developed for Datatrieve.  We want to
make it available to all layered products in the longer run.

  REQUIREMENT: There must be a plan to ship all DYNLIB pieces
necessary to write, debug, and use dynamic libraries to all TOPS-20
customers.

  RESTRICTION:  DYNLIB may ship with individual products that need it
before shipment to all sites is achieved.

.hl 1 Installability

  DYNLIB may ship either alone or with other products.  If DYNLIB
ships with other products, then installability is the responsibility
of those other products' teams.

  REQUIREMENT: DYNLIB shipped alone must include an installation
verification procedure.

  REQUIREMENT: DYNLIB shipped alone must be installable in under 1
hour including unpacking, reading instructions, performing the
installation, and performing the installation verification procedure.

.hl 1 Ease of Use

  The requirements in this section also appear elsewhere in this
document, they are collected here for convenience.

  REQUIREMENT:  Using an address exported from a dynamic library must
be as similar as possible to using an address exported from a REL
library.  

  REQUIREMENT: Invoking a dynamic library must be made as
transparent as possible (invoking the dynamic library should look as
much as possible like invoking a routine from a REL library).  No
special subroutine call may be required to load a dynamic library.
The library must be loaded as a side-effect of referring to an address
exported from it.

.hl 1 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.

  REQUIREMENT: Calling a routine in a dynamic library must not
normally require more than 3 machine instructions (not considering any
page-fault handling).

  REQUIREMENT:  Referring to an exported address in some manner other
than a routine call must not take longer or be harder to code than
making an indirect reference through an in-section pointer to an
out-of-section location.

  RESTRICTION: Performance of the first reference to any address
exported from a library may be much slower, up to several seconds on a
loaded system.

  RESTRICTION: Calling a dynamic library from section 0 is not subject
to the above performance constraints.  The capability of calling a
dynamic library from section 0 is provided only as an aid to
incremental conversion of existing software.

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

.hl 1 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.

  REQUIREMENT: DYNLIB will not ship with any known first or second
priority problems (the number of allowable lower priority problems
will be decided by the project team at that time).  Problem priorities
are as defined for QAR's, and are included in an appendix of this
document.

  REQUIREMENT: No patches may be required to the shipped version
before use.

  REQUIREMENT: In the event of being unable to satisfy a dynamic
loading request, DYNLIB must be capable of returning an error
indication to the caller if the caller is set up to handle it.  The
information made available must include at least the following:
.s 1.list 0, "o"
.le;Identification of the library it was trying to load, including the
file specification where it expected to find that library 
.le;A description of the error
.le;If the error was a failing monitor call, the monitor error message
describing that failure
.le;The PC in the user's code of the call which invoked DYNLIB
.le;If applicable (if a DYNLIB bug seems possible), the PC in
DYNLIB at which the failure took place
.end list

  DYNLIB use rule: It is recommended that all programs which call
dynamic libraries be written to accept this error information and
present it to the user in a manner compatible with the other user
interactions made by the program.

  If a program chooses not to take advantage of this facility, DYNLIB
should present the error information directly to the user.  This
violates one of the prime rules of layering (it does terminal IO other
than at the request of the top level), which can result in (for
example) screen formatting errors, but we consider this better than
not reporting the error at all.

  REQUIREMENT: If no provision has been made by the calling program to
handle a DYNLIB error, DYNLIB must print an error message on the
terminal which is as clear and descriptive as possible.  It must
include at least the information listed as required for the error
return above.

  We will consider DYNLIB to be adequately reliable if, during the
first 12 months after FRS, unique error rates average less than 1 per
month total in priorities 1 and 2, less than 3 per month in priorities
3-5.  Problem report rates may be up to 5 times this (i.e.  an average
of 5 submissions of each problem).

.hl 1 Maintainability

  DYNLIB will be designed and written with ease of maintainability in
mind.

  REQUIREMENT:  Maintainability must be taken into account when
choosing a language in which to implement DYNLIB.

  RESTRICTION:  Because of the high level of interaction probably
required between DYNLIB and the monitor and hardware, portions or all
of DYNLIB may be written in MACRO.

  REQUIREMENT: Any software necessary for defining libraries must be
normally available at all supported TOPS-20 sites.  In particular,
BLISS must not be necessary to define a library.

  REQUIREMENT: All project documents must be formally inspected and
the problems found corrected.

  GOAL:  As much as possible of DYNLIB will be housed in a dynamic
library.  This makes it possible to update DYNLIB itself without
requiring users to re-link all programs using DYNLIB.

  RESTRICTION:  Due to the time constraints on this project, it is not
necessary to produce an additional document describing the internals
of DYNLIB.  However, the functional and design specs must be updated
to reflect the status of the code.

  REQUIREMENT: DYNLIB will be autopatchable in the field.

  REQUIREMENT: DYNLIB must not prevent dynamic libraries from being
autopatchable in the field.

  SUCCESS CRITERION: The patch/update rate for the first 12 months
will be not more than 120% of the unique problem rate during that
period.

.hl 1 Maintenance

  Maintenance of this product will be performed by Software
Engineering.

  REQUIREMENT: Updates must appear as necessary on the regular
autopatch tapes.

.hl 1 Compatibility

.HL 2 Compatibility with existing libraries

  There are a lot of existing REL libraries or other kinds of packages
of code.  Many of them would be very useful as dynamic libraries --
consider SORT, DBCS, RMS, MTHLIB.

  REQUIREMENT: It must be possible to take an existing REL library
that does not require trapping or interrupts and turn it into a
dynamic library with minimal changes to existing programs, in whatever
language, that call routines in the library.

  RESTRICTION: Conversion of an existing REL library or other kind of
package may require considerable effort since dynamic libraries are
required to run in non-zero sections.  Most existing packages do not
have this capability, but using the additional address space available
through extended addressing is basic to the goals of DYNLIB.

  REQUIREMENT: Any systematic changes required in converting existing
packages into dynamic libraries must be documented in the manual on
writing dynamic libraries.

  REQUIREMENT: There must be some tool in DYNLIB for interfacing
programs running in section zero to dynamic libraries called into
non-zero sections (note that most existing programs run in section
zero).

.hl 2 Product Compatibility

  Dynamic libraries are not particularly compatible with any previous
method of calling libraries (either linking in section zero, or GET%
at runtime into fixed addresses in section 0).

  GOAL: Major languages should  consider invoking their OTS
routines as a dynamic library.  This would be a large step towards
making mixed language programming work. (If the OTS libraries were
made to conform to the interrupt and trap rules, a mixed
language environment would be achieved.)+  This would make it possible
for dynamic libraries to be written in higher level languages and
called from other higher level languages -- for example, a dynamic
library of graphics routines could be written in FORTRAN.

.hl 3 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.

  We must come to a consensus with the DDT, LINK, and monitor groups
on symbol table pointers in PDV's and elsewhere.

.hl 2 Standards Conformance

  No known relevant standards.

.hl 2 Internationalization

  There are no requirements in this area.  This product interacts with
the end-user only in "last-ditch" error messages which should never be
seen from a program designed according to our recommendations.  There
is therefore no need for foreign language versions of the product.

  There is no benefit to making DYNLIB documentation available in
foreign languages unless policy is changed and ^&all\& LCG
documentation starts becoming available in foreign languages.  This is
not anticipated.

  REQUIREMENT:  DYNLIB must not preclude use of 8-bit ASCII codes in
dynamic libraries or programs which call them.

.hl 1 Evolvability

  REQUIREMENT: user-mode DYNLIB, if implemented, must be designed with
an eye to eventual conversion to monitor-mode DYNLIB.  The maximum
amount of effort for converting programs and dynamic libraries from
user-mode DYNLIB to monitor-mode DYNLIB must not exceed: recompile the
library definitions using the new version of DYNLIB, and relink any
programs calling the libraries.

  Customers should not be allowed to change any of the basic data
structures; however, they may need to store information relating to
the libraries which naturally seems to belong in our data structures.
Similarly, individual libraries may have special data storage
requirements that could best be served this way.

  REQUIREMENT: At least a word in each DYNLIB data structure that
resides in program address space must be set aside for the use of
customers.  A word must also be set aside for the use of the specific
library that this data structure relates to, if it relates to a
specific library.

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

.hl 1 Timeliness

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

.hl 1 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.

.hl 1 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.

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

.appendix Problem Priorities

  (From the QAR form instructions)

  Refer to the following code in establishing a priority for 
your problem:

.list 1
.le;Most production work cannot be run; e.g. functions/jobs which are not 
usable and are a major use of the system, such as system will not
BOOT, necessary peripherals are out of service.
  
.le;Some production work cannot be run; e.g. certain functions/jobs are 
not usable, performance degradation, installation has insufficient
excess capacity.
  
.le;All production work can be run with some impact on user; e.g. 
significant manual intervention required, extra procedures,
performance degradation, but installation has excess capacity.
  
.le;All production work can be run with no significant impact on users; 
e.g. problems can be easily patched, simple bypass procedure exists.
  
.le;No system modifications needed to return to normal production; e.g. 
suggestion, consultation, documentation error.
.end list