HP 3000 Manuals HP 3000 Manuals
MANAGING USER SUBPROGRAM LIBRARY FILES (USLs)
A USL is one of the three procedure libraries used in the program
development process. It is the file used for compiler output. Most
frequently, you will use the USL as input for the Segmenter to use in
preparing a program file. However, you may also use it for the following
purposes:
* To share code from another USL or program.
* To solve code management problems which may occur if you exceed the
size limitation established for a USL.
* As an aid in program design and code management. The USL eliminates
time-consuming recompilation when you are testing various versions of
a procedure or changing code storage methods.
* As a basis for constructing relocatable libraries (RLs).
* As a basis for constructing segmented libraries (SLs).
The last two items are discussed later in this section.
Invoking The USL
A command you will use often as you manage USLs with the Segmenter is
-USL filereference
This command identifies the USL specified by filereference as
the "currently-managed", or "currently-referenced", USL. These
interchangeable terms mean the specified USL is the one to which the
Segmenter will apply any commands you give which have USL as a parameter,
and will do so until another -USL command is entered.
Listing The USL
Another command you will frequently use to verify the results of your
code manipulations is
-LISTUSL [segmentname]
With this command you can list all or part of the contents of the
currently managed USL. If you specify a segment name, only that segment
is listed. The output is written on the file designated in the listfile
parameter of the MPE :SEGMENTER command, or on $STDLIST if the listfile
parameter is omitted.
In Figure 2-4, the Segmenter prints information about all segments in the
USL, since we didn't specify a particular segment name. Significant
entries are indicated with item numbers (**number**), which are explained
following the listing. All numbers appearing in the listing are octal
values.
-USL SEARCHUSL **1**
-LISTUSL
USL FILE SEARCHUSL.SEGMENT.SUB3000
WRITESEG **2** *4* *5* *6* *7* *8* *9*
WRITENUMSONLY **3** 16 P A C N R
SEARCHSEG .
SEARCHLINE . 27 P A C N R
SEARCHLINE 27 P I C N R
ASKSEG
ASKFORMAT 15 P I C N R **4** **5**
SEG'
WRITENUMSONLY 16 P I C N R **6** **7**
WRITENUMSONLY 16 P I C N R **8** **9**
OB' 255 OB A C N
ASKCHAR 17 P A C N R
ASKNAME 13 P A C N R
FILE SIZE 2000( 10. 0) **10**
DIR. USED 574( 2.174) **11** INFO USED 1132( 4.132)
DIR. GARB. O( 0. 0) INFO GARB. 0( 0. 0) **12**
DIR. AVAIL. 4( 0. 4) INFO. AVAIL. 46( 0. 46) **13**
Figure 2-4. Using the Segmenter -LISTUSL Command
ITEM NO. MEANING
---------------------------------------------------------------------------------------
1 Name of USL.
2 Segment name.
3 RBMs associated with segment.
4 Size of RBMs in words (octal).
5
Entry point type, where:
P =Procedure primary entry point.
SP =Secondary entry point for procedure.
OB =Outer block primary entry point.
SO =Secondary entry point for outer block.
BD =Block data entry point.
In =Interrupt procedure entry point (n is the interrupt
procedure type, ranging from 0 through 2).
CP =COBOL secondary entry point.
6 Active/Inactive bit.
7 Callable/Uncallable bit.
8 Not privileged/Privileged bit.
9 Reveal/Hide flag.
10 File size: number of words in file (overhead + directory + info)
followed by number of records in file (in parentheses).
11 Directory used + avail. = total directory space in words and in
records (in parentheses).
12 Garbage: unusable portion "used" space in words and in records (in
parentheses).
13 Info used + avail. = total info space in words and in records (in
parentheses).
Figure 2-4. Using the Segmenter -LISTUSL Command (Continued)
Building New USLs With The Segmenter
Although new USLs are usually built automatically by compilers and
managed with the Segmenter, you can use the Segmenter to both build and
manage USLs. You will need this capability when you want to copy RBMs
from another USL using the -COPY command and do not want to place the
copied RBMs into a USL containing other material.
You might also wish to create an empty USL into which you can compile
code after you have exited the Segmenter subsystem. The command
-BUILDUSL MYUSL,200,1
creates a new USL file with space for 200 records and one disc extent.
A new USL built with the Segmenter becomes the currently-managed USL. An
important point is that, unlike compiler-built USL files, those built
with the Segmenter are "job/session-temporary"; that is, they will be
lost when you log off unless you take special action to save them. In
Figure 2-5, we use the Segmenter to build the session-temporary USL
MYUSL, and then use the MPE :SAVE command to make MYUSL permanent.
Copying RBMs
You may often find that you would like to use a subroutine from one of
your programs in another program. With the Segmenter, you can copy RBMs
and segments directly from one USL to another. Without this capability,
you would have to create a source file containing the procedure(s) and
compile it into the desired USL.
To use this capability, specify the source USL (the one you wish to copy
from) with the -AUXUSL command:
-AUXUSL filefrom
The destination USL (the one you wish to copy to) is the
currently-managed USL, which you specify with the -USL command:
-USL fileto
Note that while the destination USL may be one you just created with the
-BUILDUSL command, the source or auxiliary USL must already exist. The
-LISTAUX command, which functions like the -LISTUSL command, allows you
to view the contents of the auxiliary USL so you can select the segments
or RBMs you wish to copy.
Once you have specified a source USL and a destination USL, you can use
the -COPY command to copy a single RBM and all associated entry points,
or all RBMs associated with a particular segment name, from the auxiliary
USL to your currently-managed USL. In Figure 2-6, the -LISTAUX command
used after the transfer shows that the -COPY operation leaves the
auxiliary USL file intact; that is, -COPY transfers a duplicate of the
specified material without moving or altering the original.
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-BUILDUSL MYUSL,100,10
-LISTUSL
USL FILE MYUSL.PUB.SPL
FILE SIZE 31000( 144. 0)
DIR. USED 200( 1. 0) INFO 0( 0. 4)
DIR. GARB. 0( 0. 0) INFO GARB. 0( 0. 0)
DIR. AVAIL. 3000( 14. 0) INFO AVAIL. 25600( 127. 0)
-EXIT
END OF SUBSYSTEM
:SAVE MYUSL
:LISTF MYUSL,2
ACCOUNT= SPL GROUP= PUB
FILENAME CODE ------------LOGICAL RECORD------------ ----SPACE----
SIZE TYP EOF LIMIT R/B SECTORS #X MX
MYUSL USL 128W FB 14 100 1 22 2 10
Figure 2-5. Building a USL with the Segmenter -BUILD Command and
Saving It as a Permanent File
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-USL MYUSL
-AUXUSL SEARCHOLD
-LISTAUX
USL FILE SEARCHOLD.PUB.SPL
SUB
TIMESTWO 16 P A C N R
SEG'
MAIN' 32 P A C N R
SEG2
INPUT 32 P A C N R
GOFOR 16 P A C N R
GOFOR 16 P I C N R
.
.
.
-COPY MAIN' **Copy the RBM MAIN' and the segment
-COPY SEGMENT, SUB SUB from $SEARCHOLD to MYUSL**
-LISTUSL
USL FILE MYUSL.PUB.SPL
SUB
TIMESTWO 16 P A C N R
SEG'
MAIN' 32 P A C N R
-LISTAUX
SUB
TIMESTWO 16 P A C N R
SEG'
MAIN' 32 P A C N R
SEG2
INPUT 32 P A C N R
GOFOR 16 P A C N R
GOFOR 16 P I C N R
.
.
.
Figure 2-6. Using the Segmenter -AUXUSL, and -LISTAUX Commands
Copying An Entire USL
As you are developing your programs, you may receive an error message
stating that the space in the currently-managed USL is exhausted. The
Segmenter may give you the message when, for example, you are copying
RBMs from an auxiliary USL to your currently-managed USL. Compilers have
an equivalent message which they may send when you are compiling code
into a USL.
Two more copy commands, -COPYUSL and -CLEANUSL, are available for you to
use when you need to copy an entire USL to a different file because of
such space problems.
-COPYUSL copies all of the currently-managed USL to a new USL file, while
giving you control over the size of the new USL. Assume that SEARUSL is
the currently-managed USL. With the command
-COPYUSL 100, SEARUSL5
we are instructing the Segmenter to copy all of MYUSL into a new USL
called SEARUSL5, giving SEARUSL5 100% more space than the space needed to
hold SEARUSL5's current contents. For example, if the information in
SEARUSL occupied 400 records, SEARUSL5 would get 400 plus 100% of 400, or
800 total.
If we specify only
-COPYUSL 100
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 USL.
In either case, the new USL becomes the currently-managed USL. Figure 2-7
demonstrates the operation of this command.
The -CLEANUSL command, which calls the CLEANUSL intrinsic, copies only
the active RBMs to a new USL file, cleaning out any inactive entries and
garbage. 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 usable space since the inactive RBMs are not copied.
Assume that SEARUSL is the currently-managed USL. With the command
-CLEANUSL SEARUSL7
the Segmenter will copy the active RBMs from SEARUSL to a new USL called
SEARUSL7, which becomes the currently-managed USL. (See Figure 2-8.)
Note in Figure 2-8 that the segment name ASKSEG, which had no active RBMs
associated with it, is still present. Because of the possibility that
you may inadvertently purge files with these two commands by omitting a
filename for the new USL, you must have Save Files capability to use
them.
Other Methods of Obtaining More USL Space
A USL file with insufficient space cannot simply be FCOPY'd to a
physically larger file to make room for more entries. Look again at the
information provided in the response to the -LISTUSL command in Figure
2-4. Notice that maintenance information (such as the size of the USL
file, the amount of space used, and the amount of space available), which
the Segmenter must have to manage the USL, resides within the USL file
itself. Since FCOPY is not aware of the internal structure of a USL
file, it cannot make any modification to the size or structure of the
file, but can only make a copy identical to the original.
Recompiling into a larger USL is the only other way (besides -CLEANUSL
and -COPYUSL) to obtain more USL space. Within the Segmenter subsystem,
use the -BUILDUSL command to create a larger USL than the one in which
space is exhausted. Then recompile the material from the old USL into
the new, larger USL. Note that this alternative requires you to have your
original source code available. If you don't, you will have to rewrite
it.
Managing USLs: Special Considerations
The -COPY command will allow you to copy both active and inactive RBMs
with the same name as some already in the currently-managed USL. Unlike
the compilers, the Segmenter does not inactivate already-present RBMs of
a particular name when it copies other RBMs of the same name into a USL.
Further, it has no way to distinguish between different RBMs with the
same name. Instead, it indexes all RBMs with the same name as if the
RBMs themselves were the same. (See the discussion of the version
index.) Since the Segmenter can use only one active RBM of a particular
name per preparation, the presence of two active RBMs of the same name
(even though they contain different procedures) will cause a prepare
failure.
To avoid this problem, make your procedure names unique. Then make a
habit of using the -LISTAUX and -LISTUSL commands before you -COPY the
RBMs. If you see potential duplication problems, you will have to change
the procedure's name in your source code and recompile your program.
(All other programs that use the procedure will also have to be
recompiled, and re-prepared as well.)
If you -COPY in another active RBM of the same name which contains
another version of the same procedure, the solution is simpler: use the
Segmenter -CEASE command to inactivate one of the versions before you
prepare your program file.
Another point to be aware of when you are managing USLs is that, 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 MPE file system is concerned with the file
label, while the Segmenter is concerned with contents and does not read
MPE file labels. Further, MPE 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 to manage with
the Segmenter.
-USL TUSL1
-LISTUSL
USL FILE TUSL1.HSU.KSE
.
.
.
FILE SIZE 144000( 620. 0)
DIR. USED 716( 3.116) INFO USED 225( 1. 25)
DIR. GARB. 0( 0. 0) INFO GARB. 0( 0. 0)
DIR. AVAIL. 13462( 56. 62) INFO AVAIL. 127153( 534.153)
-COPYUSL 100,TUSL7 **Segmenter copies all of TUSL1 to new
file TUSL7, giving TUSL7 100% more than the space
presently needed for the contents of TUSL1.**
-LISTUSL
USL FILE TUSL7.HSU.KSE
.
.
.
FILE SIZE 2600( 13. 0)
DIR. USED 716( 3.116) INFO USED 225( 1. 25)
DIR. GARB. 0( 0. 0) INFO GARB. 0( 0. 0)
DIR. AVAIL. 662( 3. 62) INFO AVAIL. 553( 2.153)
USL TUSL1
COPYUSL 0,TUSL8 **Segmenter copies all of TUSL1 to a new file
TUSL8, giving TUSL8 no more than the minimum
amount of space presently needed to hold the
present contents of TUSL1.**
-LISTUSL
USL FILE TUSL8.HSU.KSE
.
.
.
FILE SIZE 1400( 6. 0)
DIR. USED 716( 3.116) INFO USED 225( 1. 25)
DIR. GARB. 0( 0. 0) INFO GARB. 0( 0. 0)
DIR. AVAIL. 62( 0. 62) INFO AVAIL. 153( 0.153)
**Note the difference in the amount of free space in TUSL7 vs. TUSL8.**
Figure 2-7. Using the Segmenter -COPYUSL Command
-USL SEARUSL
-LISTUSL
USL FILE SEARUSL.SEGMENT.SUB3000
SEARCHSEG
SEARCHLINE 27 P A C N R
SEARCHLINE 27 P I C N R
ASKSEG
ASKFORMAT 15 P I C N R
SEG'
WRITENUMSONLY 16 P I C N R
WRITENUMSONLY 16 P I C N R
OB' 255 OB A C N
WRITENUMSONLY 16 P A C N R
ASKCHAR 17 P A C N R
ASKNAME 13 P A C N R
FILE SIZE 2000( 10. 0)
DIR. USED 563( 2.163) INFO USED 1132( 4 .132)
DIR. GARB. 0( 0. 0) INFO GARB. 0( 0 . 0)
DIR. AVAIL. 15( 0. 15) INFO. AVAIL. 46( 0 . 46)
-CLEANUSL SEARUSL7
-LISTUSL
USL FILE SEARUSL7.SEGMENT.SUB3000
SEARCHSEG
SEARCHLINE 27 P A C N R **SEARUSL7, the new file,
ASKSEG contains only the active
SEG' RBMs of SEARUSL. Note
OB' 255 OB A C N R what the segment ASKSEG,
WRITESNUMSONLY 16 P A C N R which contained no active
ASKCHAR 17 P A C N R RBMs in SEARUSL7, is
ASKNAME 13 P A C N R still present.**
FILE SIZE 2000( 10. 0)
DIR. USED 435( 2. 35) INFO USED 1016( 4. 16)
DIR. GARB. 0( 0. 0) INFO GARB 0( 0. 0)
DIR. AVAIL. 143( 0.143) INFO AVAIL. 162( 0.162) **Note that
SEARUSL7, the new USL file, has more free space than SEARUSL.**
Figure 2-8. Using the Segmenter -CLEANUSL Command
Using MPE Intrinsics To Manipulate USL Files
MPE Intrinsics provide you with an alternate means of altering the size
of USLs. Using them, you can perform the following functions
programmatically:
* Initialize a buffer for a USL file to the empty state with the
INITUSLF intrinsic.
* Move the information block in a USL file with the ADJUSTUSLF
intrinsic.
* Change the length of a USL file with the EXPANDUSLF intrinsic.
Note that for each of these intrinsics you must have FOPENed the file so
that yo can provide the file number (the parameter uslf), rather than the
name, of the USL you wish to manipulate. Refer to the MPE V Intrinsics
Manual (32033-90007) for more information.
The above intrinsics are most useful to programmers writing compilers.
As you have seen from the preceding discussion, the Segmenter gives you
powerful tools for controlling USL size and contents. For ordinary
purposes, you will probably prefer to use the Segmenter to manage your
USLs.
INITIALIZING A BUFFER FOR A USL FILE TO AN EMPTY STATE. The INITUSLF
intrinsic initializes an already-existing USL to an empty state. Within
a program, you could write a call to this intrinsic as follows:
ERRNUM:=INITUSLF(uslf, buf);
where uslf is the file number, obtained from the FOPEN intrinsic, of the
file you wish to empty. This intrinsic actually clears the area of the
USL which contains pointers to the remainder can provide the file number
of the material. Once this "roadmap" has been clear the specified USL
appears empty to the compiler, which overlays any existing material in
the USL with your new source code.
Remember that you can use the Segmenter command -BUILDUSL when you need
an empty USL. One situation where you might prefer the intrinsic is with
a system where memory space is so severely limited that re-using files,
rather than building new ones, is efficient and perhaps necessary.
However, this is an unlikely circumstance.
CHANGING THE DIRECTORY BLOCK/INFORMATION BLOCK SIZE IN A USL FILE. In
each USL file, separate areas are reserved for the directory, which keeps
track of which RBMs are in the USL; and for information (the RBMs
themselves).
------------------
|DIR | INFO |
------------------
As long as space is available, compilers expand the directory as
required. Although some compilers (e.g., FORTRAN) also automatically
copy USL material to a new, larger USL file when more information room is
needed, you may receive one of the following messages while you are
manipulating code:
AVAILABLE DIRECTORY SPACE EXHAUSTED
or
AVAILABLE INFO SPACE EXHAUSTED
With the ADJUSTUSLF intrinsic, you can move the information block forward
or backward, thereby increasing or decreasing, respectively, the space
available for the directory block. For example, the ADJUSTUSLF intrinsic
call could be written as follows:
errnum:=ADJUSTUSLF(uslfnum,-80)
In the example below, we are using this intrinsic call to move the
information block backward in the USL file, increasing its space by 80
records and decreasing the directory block space by the same amount.
------------------ ------------------
| DIR | | |DIR| INFO |
------------------ ------------------
BEFORE EXECUTION AFTER EXECUTION
OF INTRINSIC OF INTRINSIC
With the call
errnum:=ADJUSTUSLF(uslfnum,80)
we are moving the information block forward in the USL file, decreasing
its space by 80 records and increasing the directory block space by the
same amount.
----------------- ------------------
| DIR | INFO | | DIR |INFO|
----------------- ------------------
BEFORE EXECUTION AFTER EXECUTION
OF INTRINSIC OF INTRINSIC
CHANGING THE SIZE OF A USL FILE. While ADJUSTUSLF changes the relative
amount of space available for code, the EXPANDUSLF intrinsic changes the
actual size of the USL. The EXPANDUSLF intrinsic call could be written as
follows:
filenum:=EXPANDUSLF(uslfnum,80);
This intrinsic creates a new USL file whose length is 80 records longer
than the USL file specified by the parameter uslf. The specified USL
file is copied to the new USL file with the same file name and the
specified file is deleted. The file number for the new USL is returned
to NEWFNUM.
Remember that three Segmenter commands (-BUILDUSL, -COPYUSL, and
-CLEANUSL) will suit most of your needs for controlling the size of your
USLs as well as or better than the intrinsics.
Preparing A Program File
When you have finished manipulating your USL, you are ready to prepare
the active RBMs residing in it into a program file. You can do this in
two ways:
* With the MPE command
:PREP uslfile, programfile
after exiting the Segmenter subsystem.
* With the Segmenter command
-PREPARE programfile
while still in the Segmenter subsystem.
The operation of the two commands is the same. In the syntax for the
Segmenter -PREPARE command, however, we don't need the USL filename,
since it is already defined: it is the currently-managed USL.
Although most of the time you will probably use the MPE :PREP command to
prepare your program files, the Segmenter -PREPARE command is very
helpful if you want to manipulate a USL file before preparing it.
-PREPARE gives you the freedom to make changes and to experiment with
different segment structures: you can resegment your USL material,
-PREPARE it into a program file, resegment, -PREPARE into another program
file, etc., without exiting the Segmenter subsystem.
With either :PREP or -PREPARE, you can specify a PMAP (which produces the
locations of procedures and their entry points within a given code
segment) or FPMAP (which stores an internal copy of the PMAP information
in the program file). You should always specify FPMAP if you are going
to use APS/3000 or HPToolset. The -SETFPMAP command allows you to invoke
FPMAPing at the system or session level. The -SHOW command displays the
current status of the system and session FPMAP flags. See Appendix G for
further discussion and an example.
Figure 2-9 illustrates the use of -PREPARE. Note that if the program file
is not an already-existing program file, the Segmenter sets up a new
temporary file. Use the MPE :SAVE command before logging off if you want
to keep a temporary program file.
:FORTRAN SEG8,$NEWPASS,$NULL
**** NO ERRORS, NO WARNINGS ****
TOTAL COMPILATION TIME 0:00:01 **Compile source
TOTAL ELAPSED TIME 0:00:03 code into USL
file.**
:SEGMENTER
HP32050A.03.00 SEGMENTER/3000 (C) HEWLETT-PACKARD CO. 1986
-USL $OLDPASS
-LISTUSL
USL FILE $OLDPASS
SEG'
TIMESTWO 16 P A C N R
MAIN' 32 OB A C N
FILE SIZE 377600( 1777. 0)
DIR. USED 270( 1. 70) INFO USED 130( 0.130)
DIR. GARB. 0( 0. 0) INFO GARB. 0( 0. 0)
DIR. AVAIL. 37510( 176.110) INFO AVAIL. 337450( 1576. 50)
-NEWSEG TIMESTWOSEG,TIMESTWO
-LISTUSL
USL FILE $OLDPASS **Optionally reorganize
USL file**
TIMESTWOSEG
TIMESTWO 16 P A C N R
SEG'
MAIN' 32 OB A C N
FILE SIZE 377600( 1777. 0)
DIR. USED 302( 1.102) INFO USED 130( 0.130)
DIR. GARB. 0( 0. 0) INFO GARB 0( 0. 0)
DIR. AVAIL. 37476( 176. 76) INFO AVAIL. 337450( 1576. 50)
-PREPARE SEG243P
-EXIT
END OF SUBSYSTEM **New program file prepared
from currently-referenced USL file.**
:RUN SEG243P
.
.
.
END OF PROGRAM
:SAVE SEG243P **The program file is saved
as a temporary file by the
Segmenter. Here, the MPE
:SAVE command is used to
save it as a permanent file.**
Figure 2-9. Using the Segmenter -PREPARE Command