HP 3000 Manuals HP 3000 Manuals
MANAGING THE SEGMENTED LIBRARY
The Segmented Library (SL) is the third of the three libraries which may
be part of the program development process. Like the Relocatable Library
(RL), it contains procedures needed for program execution and its use is
optional. The Loader accesses the SL to resolve any external references
still remaining at run time.
General utility routines (with wider applicability than the procedures
stored in RLs) are stored in the SL as prepared code segments. SL
procedures must be non-global, meaning they are so general that they
require no knowledge of the data stack on which they will run. Because
they are so general, SL code segments are completely sharable: every
calling program references the same original code. Since the SL code is
never bound to any program file, the segmentation never changes; thus, an
SL segment can be in use by more than one program at a time.
At run time, the Loader searches one SL at each of three levels: group,
account, and system. The Loader references the requested code segments;
that is, it copies them into main memory from their place on disc rather
than combining them with the program file.
The Loader can only search SLs actually named "SL". Thus, although your
SLs can have any name you wish for storage and manipulation purposes, you
must use the MPE command :RENAME to change the name of each of the SLs
you want the Loader to search at run time.
Invoking the SL
You invoke the desired SL(s) by specifying a library parameter with the
MPE :RUN command or one of the combination commands such as :FORTGO.
Refer to a discussion of the library search order in Section I. If you
don't supply a ;LIB= parameter, the Loader will search only the System
Library. If you're uncertain which SL you have stored a procedure in,
specifying ;LIB=G will instruct the Loader to search all three libraries.
With the ;LMAP parameter as part of the :RUN command, you can obtain a
loader map. This is a listing providing information about the external
references for a loaded program, including the type of segmented library
in which the external procedure resides. See Appendix G for a sample
LMAP listing.
Although the Loader accesses SLs, they are written in a special format
and must therefore be created and managed with the Segmenter. Once an SL
is created, however, it can be referenced by other MPE commands and
intrinsics just like any other standard, formatted file. For example,
you can purge the entire file with the :PURGE command, change its name
with :RENAME, or read it with the FREAD intrinsic.
A command you will use often as you manage SLs with the Segmenter is
-SL filereference
This command identifies the SL specified by filereference as the
currently-managed or currently-referenced SL. These interchangeable terms
mean that the specified SL is the one to which the Segmenter will apply
all SL-modification commands until another -SL filereference command is
entered or until a -BUILDSL command is used, thus effectively superseding
the -SL command.
Listing the SL
Another command you will frequently use verifies the results of your SL
manipulations. The command
[segmentnumber]
-LISTSL [[SEGMENT,]segmentname]
[ENTRY,procedurename]
lists all entry points and external references in the SL segment. If no
segmentname is specified, all segments in the SL are listed. If you
specify a procedure, the segment containing that procedure is listed.
Figure 2-15 is an example of the use of the -LISTSL command and the
output produced. Significant entries are indicated with numbers keyed to
the discussion following. All numbers appearing in the listing are octal
values.
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-USL USL1
-LISTUSL
USL FILE USL1.PUB.TECHPUBS
SEG'
DISP 24 P A C N R
FILE SIZE 377600( 1777. 0)
DIR. USED 42( 0. 46) INFO. USED 24( 0. 24)
DIR. GARB. 0( 0. 0) INFO. GARB 0( 0. 0)
DIR. AVAIL. 37510( 176.110) INFO. AVAIL. 337450( 1576. 50)
-BUILDSL DPSL,100,1
-ADDSL SEG'
-LISTSL **1**
SL FILE DPSL.PUB.TECHPUBS **2**
SEGMENT 0 SEG' LENGTH 30
**3** **4** **5**
ENTRY POINTS CHECK CAL STT ADR
DISP 3 C 1 0
**6** **7** **8** **9** **10**
EXTERNALS CHECK STT ADR
**11** **12** **13** **14**
1 **15**
NUMBER OF SEGMENTS IN SL: 1 DECIMAL
SL FREE SPACE SUMMARY
USED 3574400( 16762. 0) **16**
AVAILABLE 12717400( 53476. 0) **17**
-EXIT
END OF SUBSYSTEM
Figure 2-15. Using the Segmenter -LISTSL Command
ITEM NO. MEANING
---------------------------------------------------------------------------------------
1 Lists the currently-managed SL file.
2 The name of the SL file (filename.groupname.accountname)
3 The logical segment number (relative to this SL).
4 The segment name.
5 The segment length, in words.
6 The entry point name in the segment.
7 The parameter checking-level of the entry point.
8
The callability of the entry point, where
C=Callable
U=Uncallable
9 The Segment Transfer Table (STT) number of the entry point.
10 The entry point address (relative displacement within the segment).
11 External references (blank in this case).
12 The parameter checking-level of external references (blank in this
case).
13 The Segment Transfer Table (STT) number of the external references
(blank in this case).
14 If a number appears in this field, it is a (logical) segment number
and indicates that this reference has been bound to an entry point
within the SL.
15 A bit list of the segments referenced within the SL by this
segment. The left-most bit corresponds to the first (0) logical
segment number. For each bit,
1=Segment referenced.
0=Segment not referenced.
16 The number of words presently used in the SL file.
17 The number of words not used, at present, in the SL file.
Figure 2-15. Using the Segmenter -LISTSL Command (Continued)
With the Segmenter, you can:
* Build SLs.
* Add procedures to an SL.
* Delete entry points or entire segments.
* Copy the SL to a new, larger SL.
* Copy the SL to a new SL, cleaning out fragments of free space in each
of the segments.
* Protect certain entry points within an SL from general use.
Building SLs
The Segmenter creates SLs from RBMs that have previously been compiled
into a User Subprogram Library (USL). With the command
-BUILDSL MYSL.PUB.MYACCT,100,10
we create an account SL named MYSL with room for 100 records and 10
extents. As indicated by the use of the :LISTF,2 command in Figure 2-16,
SLs are always saved as permanent files by the Segmenter; therefore, you
must have SAVE access to the group and account to which you assign the SL
(it is assigned by default to the logon group and account). If your
program references an SL, the SL must reside in the same group and
account as the program file. Remember that the search order of the
libraries is determined by the program file's group and account, not the
logon group and account. An SL residing in some group and account other
than the program file would therefore not be found when the Loader
performed its library search. The SL created with the -BUILDSL command
becomes the currently-managed SL.
-BUILDSL MYSL,100,10 **Builds and initializes SL**
-LISTSL
SL FILE MYSL.CLASS.MAL **SL becomes currently-referenced SL**
**The SL is empty**
USED 37510( 176.110) AVAILABLE 57200( 275. 0)
:END OF SUBSYSTEM
:LISTF MYSL,2 **The new SL is saved as a permanent file by
the Segmenter**
ACCOUNT= MAL GROUP= CLASS
FILENAME CODE ------------LOGICAL RECORD------------ ----SPACE----
SIZE TYP EOF LIMIT R/B SECTORS #X MX
MYSL SL 128W FB 2 100 1 11 1 10
Figure 2-16. Using the Segmenter -BUILDSL Command
The Segmenter initializes each SL file it builds with information it will
need each time it uses the SL. Although you can also create SLs with the
MPE :BUILD command, such SLs will not be properly initialized and you
will therefore be unable to manage them with the Segmenter. They would
be useful only if you planned to use FCOPY with them to make an exact
copy of an already-usable SL. As a general rule, therefore, build your
SLs with the Segmenter to be sure you will be able to manage them
successfully .
Adding Procedures To An SL
Once you have built an SL, you can add procedures to it by preparing the
segment with which the procedures are associated and placing it in the
SL. In Figure 2-17 we have specified PROCUSL as our currently-managed USL
and MYSL as the currently-managed SL. With the command
-ADDSL SUBPROGX',PMAP
we are preparing all procedures associated with the segment SUBPROGX and
adding the prepared code segment to MYSL. We have also requested a PMAP
of the prepared segment (see Appendix G), so we can make a note of the
segment number of our added code for future debugging.
Note that the Segmenter adds prepared code segments, not individual RBMs,
to the SL. The SL code segments are ready for execution, except for their
own external references. These are resolved from other code segments
within the SL or from other SLs.
References in code segments within the same SL are considered resolved.
Although such a reference appears as unresolved in the PMAP for the
single code segment which makes the reference, the -LISTSL output (which
shows all segments in the SL) shows the reference to be resolved. (See
Figure 2-18.)
The -ADDSL command allows you to specify only segment names, not
individual procedure names. The only way you can add a single procedure
is if it resides by itself in a segment. Conversely, you may have a
procedure residing alone which you would like to add to your SL along
with several other procedures. With Segmenter commands you can
manipulate your USL to produce whatever procedure arrangement you wish
before creating the SL. In Figure 2-19, we wish to add a COBOL subprogram
to an SL but we first want to combine the initialization segment and the
procedure division segment before preparing the subprogram.
-USL PROCUSL **Designate PROCUSL file**
-LISTUSL **Display the USL file contents.**
USL FILE PROCUSL.GROUP1.PAYACCT
SUBPROGX
SUBPROGX' 510 P A C N R
SUBPROGX 174 P A C N R
SUBPROGX'S CP A C N R
.
.
.
-SL MYSL **Designate SL**
-ADDSL SUBPROGX,PMAP **Prepare segment and add it to the SL file.
Request a PMAP so you know the segment number
for future debugging.**
SUBPROGX 0 **The segment number.**
NAME STT CODE ENTRY SEG
SUBPROGX' 1 0 0
SUBPROGX 2 510 510
SUBPROGX'S 3 510 701
SEGMENT LENGTH 710
-LISTSL **Display the SL file contents.**
SL FILE MYSL.GROUP1.PAYACCT
SEGMENT 0 SUBPROGX LENGTH 710
ENTRY POINTS CHECK CAL STT ADR
SUBPROGX 2 C 2 510
SUBPROGX'S 1 C 3 701
SUBPROGX' 0 C 1 0
EXTERNALS CHECK STT SEG
1 **No externals referenced.**
**Bit list of segments referenced.**
NUMBER OF SEGMENTS IN SL: 1 DECIMAL
SL FREE SPACE SUMMARY :
USED 3574400( 16762. 0)
AVAILABLE 12717400( 53476. 0)
-EXIT
Figure 2-17. Using the Segmenter -ADDSL Command
-ADDSL SEG', PMAP
SEG' 0
NAME STT CODE ENTRY SEG
TIMESTWO 1 0 0
SEGMENT LENGTH 20
-ADDSL SHOWINTRNL,PMAP **Add code segments to SL file.**
SHOWINTRNL 1
NAME STT CODE ENTRY SEG
TIMESSIX 1 0 0
TIMESTWO 3 ? **TIMESTWO is an unresolved
TIMESTHREE 2 12 12 external for this segment.**
SEGMENT LENGTH 34
-ADDSL SHOWEXTRNL
-LISTSL
SL FILE SL.CLASS.MAL
SEGMENT 0 SEG' LENGTH 20
ENTRY POINTS CHECK CAL STT ADR
TIMESTWO 3 C 1 0
EXTERNALS CHECK STT SEG
100
SEGMENT 1 SHOWINTRNL LENGTH 34
ENTRY POINTS CHECK CAL STT ADR
TIMESTHREE 3 C 2 12
TIMESSIX 3 C 1 0
EXTERNALS CHECK STT SEG
TIMESTWO 3 3 0 **TIMESTWO is a resolved external when
110 we consider the entire SL.**
SEGMENT 2 SHOWEXTRNL LENGTH 20
ENTRY POINTS CHECK CAL STT ADR
TIMESEIGHT 3 C 1 0
EXTERNALS CHECK STT SEG
TIMESFOUR 3 3 ? **TIMESFOUR is an unresolved external:
TIMESTWO 3 2 0 it is not present in any segment in
this SL.
NUMBER OF SEGMENTS IN SL: 3 DECIMAL
SL FREE SPACE SUMMARY :
USED 3574400( 16762. 0)
AVAILABLE 12717400( 53476. 0)
Figure 2-18. External References in an SL
-USL PROCUSL **Designate PROCUSL file.**
-NEWSEG SUBPROGX,SUBPROGX' **Change the segment name associated with
the SUBPROGX' RBM to the segment name
SUBPROGX.**
-LISTUSL
USL FILE PROCUSL.GROUP1.PAYACCT
SUBPROGX'
SUBPROGX
SUBPROGX' 510 P A C N R
SUBPROGX 174 P A C N R
SUBPROGX'S CP A C R
.
.
-PURGERBM SEGMENT, SUBPROGX' **You can delete the SUBPROGX' segment
from the USL with the PURGERBM command.**
-LISTUSL
USL FILE PROCUSL.GROUP1.PAYACCT
SUBPROGX **Now there is only one segment in the USL file.**
SUBPROGX' 510 P A C N R
SUBPROGX 174 P A C N R
SUBPROGX'S CP A C N R
.
.
-SL MYSL **Designate SL**
-ADDSL SUBPROGX,PMAP **Prepare segment and add it to the SL file.
Request a PMAP so you know the segment number
for future debugging.**
SUBPROGX 0 **The segment number.**
NAME STT CODE ENTRY SEG
SUBPROGX' 1 0 0
SUBPROGX 2 510 510
SUBPROGX'S 3 510 701
SEGMENT LENGTH 710
-LISTSL **Display the SL file contents.**
SL FILE MYSL.GROUP1.PAYACCT
SEGMENT 0 SUBPROGX LENGTH 710
ENTRY POINTS CHECK CAL STT ADR
SUBPROGX 2 C 2 510
SUBPROGX'S 1 C 3 701
SUBPROGX' 0 C 1 0
EXTERNALS CHECK STT SEG
1 **Bit list of segments referenced.**
NUMBER OF SEGMENTS IN SL: 131 DECIMAL
SL FREE SPACE SUMMARY :
USED 3574400( 16762. 0)
AVAILABLE 12717400( 53476. 0)
-EXIT
Figure 2-19. Altering Code Segmentation Before Preparation into
an SL
Purging SL Entries
If you no longer use a particular code segment in an SL or would like to
hide an entry point in a code segment, you can do so with the Segmenter
subsystem. The command:
-PURGESL SEGMENT,segmentname
removes a code segment from the SL file. The command:
-PURGESL ENTRY,entrypointname
removes an entry from the directory of the SL file.
When an entry point is removed, it is accessible only to procedures that
reside in the same code segment; programs run with the SL or code
segments added to the SL are unable to find a purged entry point. Note
that if you purge an entry point and it is the only entry point in a
given code segment, the entire code segment is purged from the SL. For
example, the command:
-PURGESL ENTRY, DISP
purges the entry point DISP from the currently managed SL. Since DISP is
the only entry point for this code segment, the entire segment is purged
from the SL (see Figure 2-20).
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-SL DPSL
-LISTSL
SL FILE DPSL.PUB.TECHPUBS
SEGMENT 0 SEG' LENGTH 30
ENTRY POINTS CHECK CAL STT ADR
DISP 3 C 1 0
EXTERNALS CHECK STT SEG
NUMBER OF SEGMENTS IN SL: 131 DECIMAL
SL FREE SPACE SUMMARY :
USED 3574400( 16762. 0)
AVAILABLE 12717400( 53476. 0)
-PURGESL ENTRY,DISP
-LISTSL
SL FILE DPSL.PUB.TECHPUBS
NUMBER OF SEGMENTS IN SL: 131 DECIMAL
SL FREE SPACE SUMMARY :
USED 3574400( 16762. 0)
AVAILABLE 12717400( 53476. 0)
-EXIT
END OF SUBSYSTEM
:
Figure 2-20. Using the Segmenter -PURGESL Command
Recall that purging procedures from a USL "garbages", or renders
unusable, some of the space which the purged code had occupied. (You
could recover the lost space by using either -CLEANUSL or -COPYUSL.) In
contrast, when you use the -PURGESL command, the space becomes reusable
after the Segmenter performs another binding operation (thinks was
performed when the code was put into the SL) to re-establish the links
among segments. This re-binding will occur as soon as you use any of the
following three commands: -EXIT, -LISTSL, -SL.
If you want to remove an entire SL file, rather than selectively deleting
entry points or segments while preserving the space within the file, you
can use the MPE :PURGE command. :PURGE wipes out the file itself as well
as all the material in it.
Copying an Entire SL
If you and other programmers heavily use an SL, you may at some time
receive a message from the Segmenter stating that the space limits
established with the -BUILDSL command have been exhausted. Like RLs, SLs
are not directly expandable: there are no equivalents of the intrinsics
used to adjust the space in the USL. However, for SLs (although not for
RLs!) the Segmenter provides two -COPY commands to help resolve space
problems.
-COPYSL copies all of the currently-managed SL to a new SL file, while
giving you control over the size of the new SL. Assume that MYSL is the
currently managed SL. With the command
-COPYSL 90,NEWSL
we are instructing the Segmenter to copy the contents of MYSL to a new SL
called NEWSL, giving NEWSL 90% more space than the space needed to hold
MYSL's current contents. For example, if MYSL had space for 400 records,
NEWSL would get space for 400 plus 90% of 400, or 760 total.
If we specify only
-COPYSL 90
the Segmenter automatically creates a new file, purges the
currently-managed file after copying the material in it, and gives its
name to the new SL.
In either case, the new SL becomes the currently-managed SL.
The -CLEANSL command copies the contents of the currently-managed SL file
to a new SL file, eliminating any fragments of free space in each of the
segments. Since with this command you have no control over the new
file's size, the new file is the same size as the old file. However, it
has more space since unused areas are not copied.
Assume that MYSL is the currently-managed SL. With the command
-CLEANSL NEATSL
the Segmenter will copy the contents of MYSL to a new SL called NEATSL,
eliminating any fragments of free space in each of MYSL's segments.
There is a possibility that you may inadvertently purge files with these
two commands by omitting a filename for the new SL. To prevent this, be
sure you have SAVE FILES capability.
Protecting SL Entry Points
The Segmenter allows you to selectively protect SL entry points from
general use, making them accessible only to other procedures residing in
the same SL. The -HIDE and -REVEAL commands accomplish this when they are
invoked for RBMs within the currently-managed USL. When the RBMs are
added to an SL, they are hidden or revealed, depending upon which command
you have used.
In addition to the activity bit associated with each entry point in an
RBM, there is also an internal flag that determines whether or not that
entry point will be placed in the SL directory - and thus made available
to other segments within the SL and to general users - when the RBM is
segmented and added to an SL. The -HIDE command sets the flag on; -REVEAL
sets it off. For SPL, the OPTION INTERNAL statement in the declarations
of applicable procedures does an implicit HIDE at compile time.
Since the internal flag must either be set from within your source code
(for SPL) or used on RBMs in the currently-managed USL, changing the flag
from one condition to another involves:
* Purging the procedure from the SL and then rewriting it, recompiling
it, and re-adding the required RBMS (with the flag for each set the
way you want it) into the SL.
* Using the -HIDE or -REVEAL command on the RBM in the USL and then
re-adding it into the SL, skipping the steps of rewriting and
recompiling.
The second is clearly the much simpler option. Note that you must have
saved the USL from which you originally created the SL in order to use
this option.
As an example of how the HIDE/REVEAL facility can be used, suppose you
are writing a complicated utility that you want to add to an SL. You
write the routine as a set of procedures to be placed in the same code
segment, but want only entry points of certain procedures made available
to other users; you do not want them to use the entry points of the
support procedures for the main routine. You can effectively hide these
private entry points from other users (and other segments) by using
OPTION INTERNAL if you are programming within SPL, or by setting the
internal flag on with the -HIDE command.
The HIDE/REVEAL facility can also be useful if you want to keep two
procedures of the same name in an SL. Since only one procedure receives a
directory entry, the Segmenter does not "see" the second and will not
prevent you from adding it to the SL. The main purpose, however, is to
protect entry points from general use.
Managing SLs: Special Considerations
Following are several things you should keep in mind when working with
SLs.
CHANGING CODE STORAGE METHODS. At some point as you are managing your
code libraries, you may decide you would prefer not to store certain code
in an SL. If you have not saved either your source code or your USL, you
will have to rewrite and recompile the code before deciding on another
option for managing the procedure modules which had been in the SL. As is
true of RLs, you cannot simply move code from an SL back to a USL. The
Segmenter is designed for one-way referencing, which means that a library
cannot communicate directly with another library which enters the program
development process earlier. The Segmenter can move code directly from a
USL to an RL or an SL, since that is a case of forward referencing, but
not from an RL back to a USL or from an SL back to a USL. Further, both
RLs and SLs are created from USLs; the Segmenter cannot move material
back and forth between these two types of libraries.
DUPLICATE ENTRY POINTS. Since each name in a library file must be
unique, you cannot have more than one active entry point of a given name
in an SL file. If you try to add a segment containing two active entry
points of the same name to an SL, the Segmenter will disallow the
operation, sending you the following error message: DUPLICATE ACTIVE
ENTRY POINTS.
Nor can you add to an SL a segment containing an active entry point name
which already exists in the SL. In this case, the Segmenter will disallow
the operation and you will receive the following error message: ENTRY
POINT ALREADY DEFINED.
Make a habit of using the -LISTUSL and -LISTSL commands before you try to
move code from a USL to an SL. If you see potential duplication problems,
you can:
* Leave the code in the USL and prepare it from there along with the
rest of your object code. If necessary, use the -AUXUSL and -COPY
commands to transfer the code from the USL it resides in to the one
that contains your object code.
* Rewrite the source code, changing the procedure names, and then move
the newly-named code to the SL.
* Inactivate one of the entry points if it performs the same function
as its duplicate, as well as having the same name.
COPY COMMANDS. Although similar in function, the Segmenter subsystem
-COPY commands work differently than the MPE operating system :FCOPY
commands, and the two types are not compatible. The file system is
concerned with the file label, while the Segmenter is concerned with file
contents and does not read MPE file labels. Further, the MPE file system
creates files of a different size than those built by the Segmenter, so
that the Segmenter could not copy such files even if it could read the
labels.
You can avoid management problems by using only the Segmenter -COPY
commands with files you have built and want to continue managing with the
Segmenter.
REFERENCING ORDER. The Segmenter's forward-referencing design prevents
SL procedures from referencing program file procedures. The Loader would
consider any such calls to be unresolved externals for the code segment
or the SL. It would search the other SLs specified with the RUN command
looking for a procedure of the specified name. If it found one, it would
almost certainly not be the same as the one you intended to use from your
program file. If the Loader found no such procedure, your program would
contain an unresolved external and would be unrunnable.
SL FILE PROTECTION. When you specify an SL as your currently-managed SL,
the Segmenter assumes you are going to modify the SL and unconditionally
FLOCKs the file, protecting its integrity while it is in use. The
Segmenter automatically removes the FLOCK when you access another SL or
when you exit the subsystem. Any other request to access the same SL
waits until the first user is finished and the Segmenter FUNLOCKs the
file.
Any process that executes the RUN command against an FLOCKed SL also
waits until the SL is FUNLOCKed by the Segmenter. This is because the
Loader also FLOCKs SL files to prevent their modification while they are
in use by a particular process. If the file is already FLOCKed by the
Segmenter or by some other process, the Loader suspends until the file is
unlocked and can be locked again for the Loader's purposes. While the
Loader is waiting for the SL to be unlocked, any other processes queued
on the Loader have to wait also. Thus, the Loader as well as the
particular SL are unavailable to users.
A particularly important consequence of this protective mechanism is that
other users may be prevented from normal operation during the time that
you are accessing SL.PUB.SYS. Not only does virtually every program have
at least one external reference which must be resolved from this SL (the
system procedure TERMINATE), but many other system functions also require
access to SL.PUB.SYS. Since you cannot override this protective
mechanism, it is important for you to avoid potential interference with
other users by accessing an SL, particularly SL.PUB.SYS, for as short a
time as possible.
RETAINING SOURCE CODE OR USLs. Note that efficiently solving problems
which may arise as you are managing SLs requires you to have available
the USL or the source code from which you originally constructed the SL.
If you save the USL, you avoid the extra step of recompiling. However,
if you save the source code, you can easily make changes in your code as
well as changing your method of storing shared code. (You cannot alter
code in a USL.)
Make it a habit to retain either USLs or source code, particularly if you
anticipate that you will heavily use the Segmenter to manage code, and if
you foresee heavy SL usage which could:
* Increase the possibility of duplicate segment names and thus the need
to modify code or find an alternate means of storing it.
* Repeatedly exhaust the available CST entries.