A shared library is an executable image of a set of shareable sub-programs which is installed in the :SYS account and is permanently memory resident. A shared library is constructed by LINK in two parts: shareable procedure and static data. The shareable procedure is always biased at octal 700000 or 224K. Since a user's instruction segment is limited to 256K, the procedure portion of a shared library is limited to 32K. The data portion of the shared library is biased at octal 34 and may be as large as is required. When a user's program is linked specifying a shared library (implicitly or
explicitly), the library static data space is allocated first in the user's static data space. All other user static data follows the end of the shared library's data space. The total for the procedure and constant data is prohibited from exceeding 224K.
Link Time Association of Shared Libraries
A shared library can be associated at link time by specifying the SHARELIB option which causes the specified library to be associated with the run unit.
An alternate method is to build an object unit that has the two fields BSOUHEAD.LNAMSIZ and BSOUHEAD.LNAM filled in appropriately with the desired
library name size and text of the name. In this case the linker will automatically associate the specified library from the :SYS account. If multiple library names are specified in the object units making up the program, the linker will associated the library that has the highest precedence. The following is a list of shared libraries in order by precedence (high to low):
:SHARED COMMON - for programs compiled or interpreted by FORTRAN, APL, or BASIC
-:SHARED COBOL - for programs compiled by COBOL :SHARED RPG - for programs compiled by RPG :SHARED SYSTEM - for programs compiled by PL6.
CE62-00 Link Time
Association of Shared Libraries
12-1
Run Time Association of Shared Libraries
When a user's program is linked with a shared library, the user's run unit only contains the space reserved for the library's static data. When the library is associated at run time (by either fetch or a MSALIB monitor
service), the initialized library data will be copied into the space reserved for the library data. At that point, the procedure portion of the shared library will also be mapped in the user's working space. Note that the
procedure portion of the library is shared among all users and that each user has a copy of the data portion.
Building Shared Libraries
In order to build a shared library the SLIB option must be specified on the LINK command. The linker will then produce a run unit that represents the shared library. Since the shared library is a self-contained entity, all external references must be resolved when the library is built.
Since the shared library is a self-contained entity, the user may only refer to the externally known entry points in the library. This ensures that when new versions of the library are made, the user's program does not need to be relinked to interface with the new shared library. The ability to create an invariant interface for the user is made possible with the VECTOR option to LINK when the library is built. This option will cause the linker to
automatically build a transfer vector at the beginning of the shared library.
The ENTRIES sub-option of the VECTOR option allows the builder of the shared library to specify those entry points that are to be included in the transfer vector built by the linker. Once a transfer vector is built, it must be used as the basis for all libraries built thereafter.
The linker performs this task by changing the external entry point name to refer to a location in the transfer vector. It then maps the entry point name concatenated with an underscore to refer to the original entry point. The following example should illustrate the concept of a transfer vector. If a routine that is to be included in the library starts as follows:
ABC
ENTDEF TSXO
ABC
X66 AAUTO
and the following linker options are specified VECTOR(ENTRIES(ABC»
a transfer vector will be built as follows:
ENTDEF ABC ENTDEF ABC ABC TRA ABC-ABC TSXO X66-AAUTO
The RF option informs the linker that the specified rununit file is a shared library and that the transfer vector in it should be used as the starting point in building a new transfer vector. The linker will insure that the virtual address of the external entry points does not change which allows a new library to be associated without requiring the users to relink. Any new entry points will be added to the end of the transfer vector from the
previously built library.
CE62-00 Building Shared Libraries 12-2
The REMOVE SYMDEF and the REMOVE ENTDEF commands cause the linker to build the shared library such that only the legal external entry points (those in the transfer vector) will be available when a user links his program with a shared Library. This automaticalLy keeps a user from accidentalLy referencing either a data location or a procedure entry point that is not necessarily invariant from one version of the library to the next. Using the above example and specifying REMOVE ENTDEF the following represents the resultant library:
ABC ABC
ENTDEF TRA TSXO
ABC ABC
X66-AAUTO
Subroutines Included in Shared Libraries
The reason for packaging subroutines into a shared Library is twofold:
convenience and efficient use of system resources. The convenience can be achieved by packaging the subroutines in a LEMUR library. Thus the principal motive for a shared Library is system efficiency. This manifests itself in several ways:
1. Reduced Linking time
2. Reduced time to fetch a program for execution
3. Reduced use of memory within a system due to sharing of Library procedure.
However, it is important to note that any program which has a shared library associated wiLL have alL of the static data of the shared library in it. Thus subroutines to be included in a shared Library shouLd minimize the amount of static data used in order to maximize the benefit of system efficiency. This factor should also be considered for purposes of possible use of subroutines asynchronousLy, e.g., by break routines.
There are several things which cannot be done by subroutines which are to be in a shared Library:
1. Explicit references to DCBs other that MSUC and MSDO. Others must be acquired at execution time.
2. SYMREFs or ENTREFs to symbols not contained in the shared library.
3. SYMDEFs of data to be referenced in programs linked with the library.
4. Use of the AREADEF or AREAREF compile-time data segment is not allowed.
Also, special attention shouLd be paid to the considerations for DELTA vis-a-vis shared Libraries as specified in Section 15.
CE62-00 Subroutines Included in Shared Libraries 12-3
User Installation of Shared Libraries
A Library may be instaLled as a shared Library temporarily (until system shutdown or crash) via the SPIDER processor. This is done via the INSTALL command of SPIDER, using a type designation of LIB. For further information on the SPIDER processor, see the System Support Reference Manual (CE41).
A Library may be instaLLed as a shared library permanently, via the Boot process. This;s done by incLuding the library on the Labeled portion of the PO tape, via the INCLUDE command of the DEF processor, and by including a MON command, in the TIGR commands of the Boot instructions, specifying the fid of the library and having a fLag designation of LI.
CE62-00 User Installation of Shared Libraries 12-4
Section 13 Library Functions
The term "library services" refers to a set of utility routines which may be used by a PL-6 program to perform common, complex, andlor repetitive tasks in a simple, standardized fashion. Most library services are designed to
simplify the job of getting data into a program (prompting the user, reading input, parsing commands, reporting errors, etc.) or getting data out of a program (formatting data, writing object units, etc.). These services thus provide the PL-6 programmer with the same sort of 1/0 capabilities available to programmers working in other, applications-oriented Languages such as FORTRAN, COBOL, or PASCAL. Most Library services are used extensiveLy by various CP-6 components (e.g. PCL and EDIT) andlor processors (e.g. FORTRAN).
User-written programs which use these library services can be made to resembLe familiar CP-6 products, and can take advantage of future enhancements in the service routines.
"Library services" are simiLar to in severaL fundamentaL respects.
"monitor services"
For exampLe:
in many ways, but differ
• Like monitor services, aLL Library services are supported by HoneyweLL.
STARs may be submitted against Library services, using the subject name
"SHARED SYSTEM".
• Both library and monitor services are accessed via the PL-6 "CALL"
statement. Neither set of services is directly supported by any other CP-6 language.
• Lib r a r y s e r vic e s are t rea ted ass tan dar d P L - 6 sub r 0 uti n e s • Nor maL l y, s.u c h services are accessed from within the standard PL-6 run-time Library known as :SHARED_SYSTEM; however, a user may wish to actuaLly LINK the service routines into a program.
• Library services can interact with the user's program in complex ways;
monitor services cannot. For example, many library service routines accept an optional PL-6 EPTR variable, which holds the ENTADDR of an error-processing routine written by the user; if an error condition is detected by the Library service, the error-processing routine will be CALLed to perform any appropriate action.
Library service routines generaLly have the foLLowing characteristics:
• A copy of each service routine is available in the :SHARED SYSTEM shared Library, which is normally associated with each PL-6 program. By using this shared copy, the programmer may make full use of the routine's capabilities without increasing the size of the program.
• A copy of each routine is available in the :LIB SYSTEM unshared Library.
This library is automatically searched (and the-necessary routine(s) loaded) if a program contains any FORTRAN or COBOL routines (and thus requires use of the :SHARED_COMMON or :SHARED_COBOL libraries).
• A copy of each routine is avaiLable in the :LIBRARY account. These unshared copies may be explicitly LINKed into the user's program as
necessary (if, for example, it is not desirable to associate or search any system Library fi Le).
CE62-QQ Library Functions 13-1
• Each library service has a name beginning with the letter "X". Some library services are named "XSservicename" (e.g. XSPARSE); others are named "XUxSservicename" (e.g. XUUSREAD, XURSGETCMD).
• Library service routines are designed to be called from a PL-6 procedure.
Information is normally passed to/from such routines via PL-6 data structures. These data structures may be generated by copying a PL-6 pre-processor file stored in the :LIBRARY account (by coding an
appropriate XINCLUDE statement), and invoking the appropriate XMACRO.
Library service routines can be classified in three general categories: input services, output services, and miscellaneous utility services. For additional information on many of these services, see the CP-6 Monitor Services Reference Manual, Library Services section.
Input Service.
Services in this class are used to give the programmer the ability to receive data from an external source (timesharing terminal, disk file(s), batch
command stream, etc.) in an easy, standardized fashion.
Service XSPARSE
XURSGETCMD
XUUSREAD
XSASFSF
XUESEVAL
Table 13-1. Input Library Services Description
A general-purpose recursive-descent parser.
Command processing service to fetch a command' from the user, echo it if necessary, parse it, print diagnostics and error messages, give the user HELP information, etc.
A utility to process source, update, and XINCLUDE records on behalf of a CP-6 compiler.
The "fast sequential file" package. This set of routines may be used to read CP-6 keyed and consecutive files in a strictly sequential fashion, at speeds of about twice that of the normal .. SREAD method.
A general-purpose "expression evaluation" routine, which may be used to evaluate arithmetic expressions within commands, and/or to provide an IBEX-like "pre-processing" capability.
Input Services 13-2