HP 3000 Manuals HP 3000 Manuals
MANAGING RELOCATABLE LIBRARY FILES (RLs)
The Relocatable Library is the second of the three libraries which may be
part of the program development process. It contains procedures, in RBM
form, that are needed for program execution, and its use is optional.
The Segmenter accesses the RL at preparation time to resolve references
within the code it is preparing.
Procedures that are likely to be used with some frequency by more than
one programmer can be stored in an RL. RBMs in any USL may reference the
RBMs in an RL. At preparation time, the Segmenter searches the specified
RL (one per preparation) and resolves the references by copying the
appropriate RBMs and binding them to the program file as a single
segment, referred to as the RL segment. Although the RBMs in the RL are
sharable, the RL segment is unique; that is, not sharable by any other
program.
Note that each of your programs can reference RBMs residing in only one
RL, since the Segmenter will search only one RL during a particular
preparation. References to any additional RLs would remain unresolved,
and your program would be unrunnable.
Invoking The RL
You can invoke the desired RL by including its name with the ;RL=
parameter in either the Segmenter -PREPARE command or the MPE :PREPARE
command.
A command you will use often as you manage RLs with the Segmenter is
-RL filereference
This command identifies the RL specified by filereference as the
currently-managed or currently-referenced RL. These interchangeable terms
mean that the specified RL is the one to which the Segmenter will apply
any RL modification commands until another -RL filereference command is
entered or until a -BUILDRL command creates a new RL, thus effectively
superseding the first -RL filereference command.
Listing The RL
Another command you will frequently use verifies the results of your RL
manipulations. It is
-LISTRL
This command lists all procedure entry points and external references
within the currently-managed RL. Figure 2-10 is an example of the use of
the -LISTRL command and the output produced. Significant entries are
indicated with item numbers keyed to the discussion following. All
numbers appearing on the listing are octal values.
Because RLs are written in a special format, Segmenter commands are
required to create and change them. Once an RL 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 :PURGE, rename it with :RENAME, or read it with the FREAD
intrinsic.
Besides its role in accessing the RL at preparation time, the Segmenter
allows you to directly manage your RLs. Using it, you can:
* Build RLs.
* Add RBMs to an RL.
* Purge RBMs within an RL.
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-LISTRL
RL FILE RLPROC.PUB.WILBUR **1**
ENTRY POINTS CHECK ADR LOC NUM CODE INFO
**4** **6** **8**
START **2** 3 54 400 1 577 677
**3** **5** **7**
EXTERNALS CHECK ADR LOC
TFORM' 0
FMTINIT' 0
II0' 0
SI0 0
**9** **10** **11** **12**
USED 1500 AVAILABLE 27300
**13** **14**
-EXIT
END OF SUBSYSTEM
Figure 2-10. Using the Segmenter -LISTRL Command
ITEM NO. MEANING
---------------------------------------------------------------------------------------
1 The name of the RL file (filename.groupname.accountname).
2 The procedure entry point name.
3 The parameter checking-level for the entry point.
4 The entry point address (relative displacement within the code
module).
5 The RL file address of the procedure information block.
6 The number of entry-points in the procedure. (If this field is
blank, the entry point field (Item 2) names a secondary entry point
If this field contains a number, the entry point name field
contains a primary entry point name.
7 The length of the code module, in words. (If this field is blank,
the entry point name field names a secondary entry point. If this
field contains a number, the entry point name field contains a
primary entry point name.)
8 The length of the procedure information block, in words. (If this
field is blank, the entry-Point name field names a secondary entry
point. If this field contains a number, the entry point name field
contains a primary entry point name.
9 The names of the external references.
10 The parameter checking-level for the external reference.
11 The entry point address of the external procedure. If this field
is blank, the procedure is external to the RL. If this field
contains a number, the procedure is not external to the RL but is
called by (and thus external to) some other procedure in the RL.
12 The RL file address of the procedure information block. If this
field is blank, the procedure is external to the RL. If this field
contains a number, the procedure is not external to the RL but is
called by (and thus external to) some other procedure in the RL.
13 The number of words presently used in the RL file.
14 The number of words presently available in the RL file.
Figure 2-10. Using the Segmenter -LISTRL Command (Continued)
Building RLs
The Segmenter creates RLs from RBMs that have previously been compiled
into a User Subprogram Library (USL). With the Segmenter command
-BUILDRL MYRL.MYGROUP.MYACCOUNT,100,10
we create an RL named MYRL with 100 records and 10 extents. As indicated
by the use of our :LISTF,2 command in Figure 2-11, RLs are always saved
as permanent files by the Segmenter. Therefore, you must have SAVE
access to the group to which you assign the RL (it is assigned by default
to the logon group and account). The RL created with the -BUILDRL
command automatically becomes the currently-managed RL. The Segmenter
initializes the RL files it builds with information it will need each
time it uses the RL. Although you can also create RLs with the MPE :BUILD
command, such RLs 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 RL. As a general rule, therefore, build your RLs with the
Segmenter to be sure you will be able to manage them successfully.
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-BUILDRL MYRL,100,10 **Builds and initializes RL**
-LISTRL
RL FILE MYRL.CLASS.MAL **RL becomes currently-referenced RL**
ENTRY POINTS **The RL is empty**
EXTERNALS
USED 400 AVAILABLE 30400
-EXIT
END OF SUBSYSTEM
:LISTF MYRL,2 **The new RL 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
MYRL RL 128W FB 2 100 1 11 1 10
Figure 2-11. Using the Segmenter -BUILDRL Command
Adding Procedures To An RL
Once you have built an RL, you can add a procedure to it by copying the
RBM containing the procedure from the currently-managed USL to the RL.
You must have WRITE access to the designated RL. Suppose we have
specified USL1 as our currently-managed USL and MYRL (the empty RL which
we created in Figure 2-11) as our currently-managed RL. With the command
-ADDRL START (2)
we are copying the second-latest version of the RBM START from USL1 to
MYRL. Figure 2-12 illustrates the use of the command and of -LISTRL to
verify the results.
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-USL USL1
-LISTUSL
USL FILE USL1.CLASS.MAL
SEG1
START 577 P I C N R
START 577 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)
-RL MYRL
-ADDRL START (2)
-LISTRL
RL FILE MYRL.CLASS.MAL
ENTRY POINTS CHECK ADR LOC NUM CODE INFO
START 3 54 400 1 577 674
EXTERNALS CHECK ADR LOC
TFORM' 0
FMTINIT' 0
IIO' 0
SIO' 0
USED 1500 AVAILABLE 27300
Figure 2-12. Using the Segmenter -ADDRL Command
Purging RL Entries
You may find that you no longer use a particular RBM, or that you would
like to modify it by removing an entry point within it. You can deal
with either of these situations without exiting the Segmenter subsystem
or rewriting and recompiling the procedure from which the RBM was
created. With the command
-PURGERL ENTRY,TIMESTWO
we delete the entry point TIMESTWO from the RBM in which it resides. If
we specify
-PURGERL UNIT,TIMESTHREE
the Segmenter will delete the entire RBM whose primary entry point name
is TIMESTHREE and any secondary entry points within TIMESTHREE.
When we delete the last, or only, entry point from an RBM, the entire RBM
is deleted. In Figure 2-13, we would have deleted the entire RBM named
TIMESFOUR even if we had specified
-PURGERL ENTRY,TIMESFOUR
Since there is only one entry point (the primary entry point which gives
TIMESFOUR its name), deleting it deletes the entire RBM.
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-RL MYRL
-LISTRL
ENTRY POINTS CHECK ADR LOC NUM CODE INFO
TIMESFOUR 3 0 500 1 16 30
EXTERNALS CHECK ADR LOC
USED 1340 AVAILABLE 27440
-PURGERL TIMESFOUR
-LISTRL
RL FILE MYRL.CLASS.MAL
ENTRY POINTS CHECK ADR LOC NUM CODE INFO
EXTERNALS CHECK ADR LOC
USED 400 AVAILABLE 28380
Figure 2-13. Using the Segmenter -PURGERL 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 -PURGERL command, the space becomes
immediately reusable.
If you want to delete an entire RL, rather than selectively deleting
entry points or RBMs within the RL you can use the MPE :PURGE command.
:PURGE wipes out the file itself as well as all the material within it.
See the MPE V Commands Reference Manual (32033-90006).
Managing RLs: Special Considerations
Following are several things you should keep in mind when working with
RLs.
PREPARATION. As mentioned previously, the Segmenter will search only one
RL per preparation. You must be careful when you are writing a program
or adding material to a USL to include references to only one RL.
Otherwise, unresolved external references will remain after preparation
and loading, and the program will be unrunnable.
RL SIZE. Unlike USLs, RLs are not directly expandable: there are no
commands or intrinsics to increase the size of an RL. Further, there are
no commands to move RBMs, either individually or collectively, from one
RL to another. The only way to obtain more RL space is to build another,
larger RL and place the same material in it. You can do this easily with
the -ADDRL command if you have available the USL from which you
originally built the RL. Otherwise, you would have to recompile (and
possibly also rewrite!) your original source code.
CODE SEGMENT SIZE. Since all requested RLs are placed in a single
segment for addition to the program file at preparation time, that
segment may become larger than the configured maximum size for code
segments. You have two options when this happens:
* Increase the configured code segment size.
* Reduce the number of RBMs referenced.
The first option is not the best one because it increases the demands on
disc storage and, more importantly, on main memory.
You can implement the second option in several ways, each of which
involves modification of your code on some level. You cannot simply move
RBMs from an RL back to a USL because the Segmenter is designed for
one-way transfer only. This means that a library cannot communicate
directly with another library which enters the program development
process earlier. Figure 2-14 illustrates the point at which the three
procedure libraries enter the program development process. It indicates
that the Segmenter can move material directly from a USL to an RL or an
SL, since that is a case of forward referencing, but not from a USL back
to an RL, from an SL back to a USL, or between an RL and an SL.
One way to reduce the RL RBMs is to rewrite your source code to eliminate
references to RL RBMs, and then recompile it.
Another choice is to move the RBMs in question to the USL being prepared.
You can do this easily if you took the RL RBMs from a USL which is still
available. You can designate that original USL as the auxiliary USL and
move the desired RBMs to your currently-managed USL, making references to
the RL unnecessary.
If the USL from which you originally built the RL is not available but
you do have your source code, you can recompile it into a USL and use
that USL to prepare your program, skipping the intermediate step of
moving the RBMs to an RL. You could move the RBMs to an SL, so that they
will not need to be added to the program file in a code segment but
instead will be resolved by the Loader at run time. Remember that both
RLs and SLs are built from USLs; the Segmenter cannot move material
directly between these two types of libraries. If you have available the
USL from which you originally built the RL, you can make this change
easily using the -ADDSL (and perhaps also the -BUILDSL) commands. If
not, you will have to rewrite your source code (if you have not saved
it), recompile it into a USL, and then place in an SL the RBMs you
originally had in the RL.
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 RL file. Therefore, you cannot add to an RL an RBM containing
active entry point names which already exist in the RL. The Segmenter
will disallow such duplication, sending you the following error message:
ENTRY POINT ALREADY DEFINED.
Make a habit of using the -LISTUSL and -LISTRL commands before you try to
move RBMs from a USL to an RL. If you see potential duplication problems,
you can:
* Leave the RBMs in the USL and prepare them from there (as part of
your object code).
* Place the RBMs into an SL instead of the intended RL.
* Rewrite the source code, changing the procedure name, and then move
the newly-named RBM into the RL.
* Inactivate one of the entry points if it performs the same function
as its duplicate, as well as having the same name.
REFERENCING ORDER. Because the Segmenter is designed for forward
referencing only, procedures in an RL cannot reference procedures in a
program file. Functionally and chronologically, the program file enters
the program development process before the RL does: the USL material is
prepared into the program file, and then the specified RL is searched to
satisfy external references within the program file. Therefore, a
reference from an RL to a program file would be a backward reference (see
Figure 2-14). For example, if subroutine A in the RL calls subroutine B
in the program file, B is considered an unresolved external for A when
the RL segment is added to the program file. The Segmenter has already
dealt with the program file and will not look at it again. At run time,
the Loader will search the Segmented Libraries (SLs) looking for a
routine called B. If it found one, it would almost certainly not be the
same as the B in the program file which you intended to use.
RL FILE PROTECTION. Whenever you specify an RL as your currently-managed
RL, the Segmenter assumes you are going to modify it and automatically
calls the FLOCK intrinsic to unconditionally lock the file, protecting
its integrity while it is in use. Any other -PREPARE (or :PREPARE)
request specifying that RL will result in a -PREPARE (or :PREPARE)
failure, and any other request to access the RL for management purposes
waits until the first user is finished and the Segmenter removes the
FLOCK, which it does automatically when you access another RL or when you
exit the subsystem.
This protective mechanism cannot be overridden. However, unless you have
many programmers heavily using the same RLs, locking is unlikely to cause
any inconvenience for you. A good general rule
![[]](../../pic3k/M010176/F02143c50.gif)
Figure 2-14. Procedure Library Access Order
is to access an RL for as short a time as possible to avoid interfering
with its use by another programmer.
RETAINING SOURCE CODE OR USLs. Efficiently solving problems which may
arise as you are managing RLs requires you to have available the USL or
the source code from which you originally constructed the RL. 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:
* Writing programs that will include many RL references, making it
likely that your RL segment will exceed the allowable code segment
size.
* Heavy usage of a particular RL by yourself and other programmers,
making it likely that at some point you will exceed the size
limitations established when you built the RL and need to build
another, larger one.
* Heavy RL usage which could result in duplicate entry point names and
thus the need to modify code or find an alternate means of storing
and referencing it.