OpenVMS Utility Routines Manual
The FDL$RELEASE routine deallocates the virtual memory used by the
OpenVMS RMS control blocks created by FDL$PARSE. You must use FDL$PARSE
to populate the control blocks if you plan to deallocate memory later
FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr]
Longword condition value. Most utility routines return a condition
value in R0. Condition values that this routine can return are listed
under Condition Values Returned.
File access block (FAB) to be deallocated using the LIB$FREE_VM
routine. The fab_pointer argument is the address of a
longword containing the address of the FAB. The FAB must be the same
one returned by the FDL$PARSE routine. Any name blocks (NAMs) and
extended attribute blocks (XABs) connected to the FAB are also released.
If you omit this argument or specify it as zero, the FAB (and any
associated NAMs and XABs) is not released.
Record access block (RAB) to be deallocated using the LIB$FREE_VM
system service. The rab_pointer argument is the
address of a longword containing the address of the RAB. The address of
the RAB must be the same one returned by the FDL$PARSE routine. Any
XABs connected to the RAB are also released.
If you omit this argument or specify it as zero, the RAB (and any
associated XABs) is not released.
Flag (or mask) that controls how errors are signaled. The
flags argument is the address of a longword containing
the control flag (or a mask). If you omit this argument or specify it
as zero, no flag is set. The flag is defined as follows:
Signals any error. By default, the status code is returned to the
Deallocates any virtual memory used for a long name access block (NAML)
created by the FDL$PARSE routine.
This flag is valid for OpenVMS Alpha only.
Address of an invalid RMS control block. The
badblk_addr argument is the address of a longword that
receives the address of an invalid control block. If an invalid control
block (a fatal error) is detected, this argument is returned;
otherwise, it is ignored.
Condition Values Returned
Normal successful completion.
Invalid RMS control block at virtual address 'hex-offset'.
Bad block address.
File activity precludes operation.
Record not locked.
Record stream currently active.
Librarian (LBR) Routines
The Librarian (LBR) routines let you create and maintain libraries and
their modules, and use the data stored in library modules. You can also
create and maintain libraries at the DCL level, using the DCL command
LIBRARY. For details, see the OpenVMS DCL Dictionary.
12.1 Introduction to LBR Routines
This section briefly describes the types of libraries you can create
and maintain using LBR routines and how the libraries are structured.
This section also lists and briefly describes the LBR routines.
Section 12.2 provides sample programs showing how to use various LBR
routines. Section 12.3 is a reference section that provides details
about each of the LBR routines.
12.1.1 Types of Libraries
You can use the LBR routines to maintain the following types of
- Object libraries, including Alpha object libraries, which contain
the object modules of frequently called routines. The Linker utility
searches specified object module libraries when it encounters a
reference it cannot resolve in one of its input files. For more
information about how the linker uses libraries, see the description of
the Linker utility in the OpenVMS Linker Utility Manual.
An object library has a
default file type of .OLB and defaults the file type of input files to
- Macro libraries, which contain macro definitions used as input to
the assembler. The assembler searches specified macro libraries when it
encounters a macro that is not defined in the input file. See the
VAX MACRO and Instruction Set Reference Manual for information about defining macros.
library has a default file type of .MLB and defaults the file type of
input files to .MAR.
- Help libraries, which contain modules of help messages that provide
user information about a program. You can retrieve help messages at the
DCL level by executing the DCL command HELP, or in your program by
calling the appropriate LBR routines. For information about creating
help modules for insertion into help libraries, see the description of
the Librarian utility in the OpenVMS Command Definition, Librarian, and Message Utilities Manual.
A help library has a
default file type of .HLB and defaults the file type of input files to
- Text libraries, which contain any sequential record files that you
want to retrieve as data for a program. For example, some compilers can
retrieve program source code from text libraries. Each text file
inserted into the library corresponds to one library module. Your
programs can retrieve text from text libraries by calling the
appropriate LBR routines.
A text library has a default file type of
.TLB and defaults the file type of input files to .TXT.
- Shareable image libraries and Alpha shareable symbol table
libraries which contain the symbol tables of shareable images used as
input to the linker. For information about how to create a shareable
image library, see the descriptions of the Librarian and Linker
utilities in the OpenVMS Command Definition, Librarian, and Message Utilities Manual and the OpenVMS Linker Utility Manual.
image library has a default type of .OLB and defaults the file type of
input files to .EXE.
- National character set (NCS) libraries, which contain definition
modules that define collating sequences and conversion functions. NCS
libraries have the default file type .NLB. For information about how to
create an NCS library, see the OpenVMS National Character Set Utility Manual.1
- User-developed libraries, which have characteristics specified when
you call the LBR$OPEN routine to create a new library. User-developed
libraries allow you to use the LBR routines to create and maintain
libraries that are not structured in the form assigned by default to
the other library types. Note that you cannot use the DCL command
LIBRARY to access user-developed libraries.
12.1.2 Structure of Libraries
You create libraries by executing the DCL command LIBRARY or by calling
the LBR$OPEN routine. When object, macro, text, help, or shareable
image libraries are created, the Librarian utility structures them as
described in Figure 12-1 and Figure 12-2. You can create
user-developed libraries only by calling LBR$OPEN; they are structured
as described in Figure 12-3.
126.96.36.199 Library Headers
Every library contains a library header that describes the contents of
the library, for example, its type, size, version number, creation
date, and number of indexes. You can retrieve data from a library's
header by calling the LBR$GET_HEADER routine.
Each library module consists of a header and data. The data is the
information you inserted into the library; the header associated with
the data is created by the LBR routine and provides information about
the module, including its type, attributes, and date of insertion into
the library. You can read and update a module's header by calling the
188.8.131.52 Indexes and Keys
Libraries contain one or more indexes, which can be thought of as
directories of the library's modules. The entries in each index are
keys, and each key consists of a key name and a module reference. The
module reference is a pointer to the module's header record and is
called that record's file address (RFA). Macro, text, and help
libraries (see Figure 12-1) contain only one index, called the module
name table. The names of the keys in the index are the names of the
modules in the library.
Object and shareable image libraries (see Figure 12-2) contain two
indexes: the module name table and a global symbol table. The global
symbol table consists of all the global symbols defined in the modules
in the library. Each global symbol is a key in the index and points to
the module in which it was defined.
If you need to point to the same module with several keys, you should
create a user-developed library, which can have up to eight indexes
(see Figure 12-3). Each index consists of keys that point to the
The LBR routines differentiate library indexes by numbering them,
starting with 1. For all but user-developed libraries, the module name
table is index number 1 and the global symbol table, if present, is
index number 2. You number the indexes in user-developed libraries.
When you access libraries that contain more than one index, you may
have to call LBR$SET_INDEX to tell the LBR routines which index to use.
Figure 12-1 Structure of a Macro, Text, or Help Library
Figure 12-2 Structure of an Object or Shareable Image
Figure 12-3 Structure of a User-Developed Library
12.1.3 Summary of LBR Routines
All the LBR routines begin with the characters LBR$. Your programs can
call these routines by using the OpenVMS Calling Standard. When you
call an LBR routine, you must provide all required arguments. Upon
completion, the routine returns its completion status as a condition
value. In addition to the listed condition values, some routines may
return the success code SS$_NORMAL as well as various OpenVMS RMS or
system status (SS) error codes.
When you link programs that contain calls to LBR routines, the linker
locates the routines during its default search of SYS$SHARE:LBRSHR.
Table 12-1 lists the routines and summarizes their functions.
Table 12-1 LBR Routines
Closes an open library.
Deletes a specified module's header and data.
Deletes a key from a library index.
Finds a module by using an address returned by a preceding call to
Writes the contents of modified blocks to the library file and returns
the virtual memory that contained those blocks.
Retrieves information from the library header.
Retrieves help text from a specified library.
Retrieves library update history records and calls a user-supplied
routine with each record returned.
Calls a routine to process modules associated with some or all of the
keys in an index.
Reads a data record from the module associated with a specified key.
Initializes a control index that the Librarian uses to identify a
Inserts a new key in the current library index.
Looks up a key in the current index.
Opens an existing library or creates a new one.
Retrieves help text from an explicitly named library or from
user-supplied default libraries, and optionally prompts you for
additional help queries.
Terminates the writing of a sequence of records to a module using the
Inserts a library update history record.
Writes a data record to the module associated with the specified key.
Replaces an existing key in the current library index.
Returns the last RMS status value.
Finds index keys that point to specified data.
Sets the index number to be used during processing of the library.
Sets Librarian subroutine record access to locate mode.
Reads and optionally updates a module header.
Sets Librarian subroutine record access to move mode.
1 This manual has been archived but is
available on the OpenVMS Documentation CD-ROM.
12.2 Using the LBR Routines: Examples
This section provides programming examples that call LBR routines.
Although the examples do not illustrate all the LBR routines, they do
provide an introduction to the various data structures and the calling
The program examples are written in Compaq Pascal and the subroutine
examples are written in Compaq Fortran. The listing of each program
example contains comments and is followed by notes about the program.
The highlighted numbers in the notes are keyed to the highlighted
numbers in the examples.
Each sample program calls the LBR$INI_CONTROL routine and the LBR$OPEN
routine before calling any other routine.
The one exception is that when you call the LBR$OUTPUT_HELP routine,
you need not call the LBR$INI_CONTROL routine and the LBR$OPEN routine.
The sample programs require access to various symbols derived from
definition macros. Use the INHERIT attribute to access these symbols
from definition macros in SYS$LIBRARY:STARLET.PEN.
The LBR$INI_CONTROL routine sets up a control index; do not confuse
this with a library index. The control index is used in subsequent LBR
routine calls to identify the applicable library (because you may want
your program to work with more than one library at a time).
LBR$INI_CONTROL specifies the library function, which can be to either
create and update a new library (LIB$C_CREATE), modify an existing
library (LIB$C_UPDATE), or read an existing library without updating it
Do not alter the control index value.
Upon completion of the LBR$INI_CONTROL routine, call the LBR$OPEN
routine to open the library. Open an existing library, or create and
open a new library, in either the UPDATE or READ mode, checking for an
error status value of RMS$_FNF. If this error occurs, open the library
in CREATE mode.
When you open the library, specify the library type and pass the file
specification or partial file specification of the library file.
If you are creating a new library, pass the create options array. The
CRE symbols identify the significant longwords of the array by their
byte offsets into the array. Convert these values to subscripts for an
array of integers (longwords) by dividing by 4 and adding 1. If you do
not load the significant longwords before calling LBR$INI_CONTROL, the
library may be corrupted upon creation.
Finally, pass any defaults for the file specification. If you omit the
device and directory parts of the file specification, the current
default device and directory are used.
When you finish working with a library, call LBR$CLOSE to close the
library by providing the control index value. You must close a library
explicitly before updates can be posted.
Remember to call LBR$INI_CONTROL again if you want to reopen the
library. LBR$CLOSE deallocates all the memory associated with the
library, including the control index.
The order in which you call the routines between LBR$OPEN and LBR$CLOSE
depends upon the library operations you need to perform. You may want
to call LBR$LOOKUP_KEY or LBR$GET_INDEX to find a key, then perform
some operation on the module associated with the key. You can think of
a module as being both the module itself and its associated keys. To
access a module, you first need to access a key that points to it; to
delete a module, you first need to delete any keys that point to it.
Do not use LBR$INI_CONTROL, LBR$OPEN, and LBR$CLOSE for writing help
text with LBR$OUTPUT_HELP. Simply invoke LBR$OUTPUT_HELP.
12.2.1 Creating, Opening, and Closing a Text Library
Example 12-1 is a sample Compaq Pascal program that creates, opens,
and then closes a text library. The program is summarized in the
- Initialize the library---Call LBR$INI_CONTROL to initialize the
- Open the library---Call LBR$OPEN to open the library.
- Close the library---Call LBR$CLOSE to close the library.
|Example 12-1 Creating a New Library Using
(*This program creates a text library*)
TYPE (*Data type of*)
Create_Array = ARRAY [1..20] OF INTEGER; (*create options array*)
VAR (*Constants and return status error
codes for LBR$_OPEN & LBR$INI_CONTROL.
These are defined in $LBRDEF macro*)
(*Create options array codes. These
are defined in $CREDEF macro*)
CRE$C_VMSV3 : [EXTERNAL]INTEGER;
Lib_Name : VARYING  OF CHAR; (*Name of library to create*)
Options : Create_Array; (*Create options array*)
File_Type : PACKED ARRAY [1..4] (*Character string that is default*)
OF CHAR := '.TLB'; (*file type of created lib file*)
lib_index_ptr : UNSIGNED; (*Value returned in library init*)
status : UNSIGNED; (*Return Status for function calls*)
(*-*-*-*-Function and Procedure Definitions-*-*-*-*)
(*Function that returns library
control index used by Librarian*)
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; (2)
VAR namblk: ARRAY[l..u:INTEGER]
OF INTEGER := %IMMED 0):
(*Function that creates/opens library*)
FUNCTION LBR$OPEN (library_index: UNSIGNED;
fns: [class_s]PACKED ARRAY[l..u:INTEGER] OF CHAR;
dns: [CLASS_S] PACKED ARRAY [l3..u3:INTEGER] OF CHAR;
rlfna: ARRAY [l4..u4:INTEGER] OF INTEGER := %IMMED 0;
rns: [CLASS_S] PACKED ARRAY [l5..u5:INTEGER] OF CHAR :=
VAR rnslen: INTEGER := %IMMED 0):
(*Function that closes library*)
FUNCTION LBR$CLOSE (library_index: UNSIGNED):
(*Error handler to check error codes
if open/create not successful*)
PROCEDURE Open_Error; (3)
WRITELN('Open Not Successful'); (*Now check specific error codes*)
IF status = IADDRESS(LBR$_ILLCREOPT) THEN
WRITELN(' Create Options Not Valid Or Not Supplied');
IF status = IADDRESS(LBR$_ILLCTL) THEN
WRITELN(' Invalid Library Index');
IF status = IADDRESS(LBR$_ILLFMT) THEN
WRITELN(' Library Not In Correct Format');
IF status = IADDRESS(LBR$_NOFILNAM) THEN
WRITELN(' Library Name Not Supplied');
IF status = IADDRESS(LBR$_OLDMISMCH) THEN
WRITELN(' Old Library Conflict');
IF status = IADDRESS(LBR$_TYPMISMCH) THEN
WRITELN(' Library Type Mismatch')
END; (*of procedure Open_Error*)
BEGIN (* *************** DECLARATIONS COMPLETE *************************
*************** MAIN PROGRAM BEGINS HERE ********************** *)
(*Prompt for Library Name*)
WRITE('Library Name: '); READLN(Lib_Name);
(*Fill Create Options Array. Divide
by 4 and add 1 to get proper subscript*)
Options[IADDRESS(CRE$L_TYPE) DIV 4 + 1] := IADDRESS(LBR$C_TYP_TXT);
Options[IADDRESS(CRE$L_KEYLEN) DIV 4 + 1] := 31; (4)
Options[IADDRESS(CRE$L_ALLOC) DIV 4 + 1] := 8;
Options[IADDRESS(CRE$L_IDXMAX) DIV 4 + 1] := 1;
Options[IADDRESS(CRE$L_ENTALL) DIV 4 + 1] := 96;
Options[IADDRESS(CRE$L_LUHMAX) DIV 4 + 1] := 20;
Options[IADDRESS(CRE$L_VERTYP) DIV 4 + 1] := IADDRESS(CRE$C_VMSV3);
Options[IADDRESS(CRE$L_IDXOPT) DIV 4 + 1] := IADDRESS(CRE$C_MACTXTCAS);
(*Initialize library control index*)
status := LBR$INI_CONTROL (lib_index_ptr, (5)
IADDRESS(LBR$C_CREATE), (*Create access*)
IADDRESS(LBR$C_TYP_TXT)); (*Text library*)
IF NOT ODD(status) THEN (*Check return status*)
ELSE (*Initialization was successful*)
BEGIN (*Create and open the library*)
status := LBR$OPEN (lib_index_ptr,
IF NOT ODD(status) THEN (*Check return status*)
Open_Error (*Call error handler*) (7)
ELSE (*Open/create was successful*)
BEGIN (*Close the library*)
status := LBR$CLOSE(lib_index_ptr);
IF NOT ODD(status) THEN (*Check return status*)
WRITELN('Close Not Successful')
END. (*of program creatlib*)
Each item in the following list corresponds to a number highlighted in