Document revision date: 15 July 2002

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 with FDL$RELEASE.

Format

FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

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.

Arguments

fab_pointer

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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.

rab_pointer

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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:

FDL$V_SIGNAL	Signals any error. By default, the status code is returned to the calling image.
FDL$V_LONG_NAMES	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.

badblk_addr

OpenVMS usage:	address
type:	longword (unsigned)
access:	write only
mechanism:	by reference

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

SS$_NORMAL	Normal successful completion.
FDL$_INVBLK	Invalid RMS control block at virtual address 'hex-offset'.
LIB$_BADBLOADR	Bad block address.
RMS$_ACT	File activity precludes operation.
RMS$_RNL	Record not locked.
RMS$_RSA	Record stream currently active.
SS$_ACCVIO	Access violation.

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 libraries:

• 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 .OBJ.
• 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.
  A macro 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 .HLP.
• 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.
  A shareable 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.¹
• 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.

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.

12.1.2.1 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.

12.1.2.2 Modules

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 LBR$SET_MODULE routine.

12.1.2.3 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 library's modules.

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 Library

Figure 12-3 Structure of a User-Developed Library

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

Routine Name	Function
LBR$CLOSE	Closes an open library.
LBR$DELETE_DATA	Deletes a specified module's header and data.
LBR$DELETE_KEY	Deletes a key from a library index.
LBR$FIND	Finds a module by using an address returned by a preceding call to LBR$LOOKUP_KEY.
LBR$FLUSH	Writes the contents of modified blocks to the library file and returns the virtual memory that contained those blocks.
LBR$GET_HEADER	Retrieves information from the library header.
LBR$GET_HELP	Retrieves help text from a specified library.
LBR$GET_HISTORY	Retrieves library update history records and calls a user-supplied routine with each record returned.
LBR$GET_INDEX	Calls a routine to process modules associated with some or all of the keys in an index.
LBR$GET_RECORD	Reads a data record from the module associated with a specified key.
LBR$INI_CONTROL	Initializes a control index that the Librarian uses to identify a library.
LBR$INSERT_KEY	Inserts a new key in the current library index.
LBR$LOOKUP_KEY	Looks up a key in the current index.
LBR$OPEN	Opens an existing library or creates a new one.
LBR$OUTPUT_HELP	Retrieves help text from an explicitly named library or from user-supplied default libraries, and optionally prompts you for additional help queries.
LBR$PUT_END	Terminates the writing of a sequence of records to a module using the LBR$PUT_RECORD routine.
LBR$PUT_HISTORY	Inserts a library update history record.
LBR$PUT_RECORD	Writes a data record to the module associated with the specified key.
LBR$REPLACE_KEY	Replaces an existing key in the current library index.
LBR$RET_RMSSTV	Returns the last RMS status value.
LBR$SEARCH	Finds index keys that point to specified data.
LBR$SET_INDEX	Sets the index number to be used during processing of the library.
LBR$SET_LOCATE	Sets Librarian subroutine record access to locate mode.
LBR$SET_MODULE	Reads and optionally updates a module header.
LBR$SET_MOVE	Sets Librarian subroutine record access to move mode.

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 syntax.

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 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).

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.

Example 12-1 is a sample Compaq Pascal program that creates, opens, and then closes a text library. The program is summarized in the following steps:

1. Initialize the library---Call LBR$INI_CONTROL to initialize the library.
2. Open the library---Call LBR$OPEN to open the library.
3. Close the library---Call LBR$CLOSE to close the library.

Example 12-1 Creating a New Library Using Compaq Pascal

PROGRAM createlib(INPUT,OUTPUT); (*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*) LBR$C_CREATE,LBR$C_TYP_TXT,LBR$_ILLCREOPT,LBR$_ILLCTL, (1) LBR$_ILLFMT,LBR$_NOFILNAM,LBR$_OLDMISMCH,LBR$_TYPMISMCH : [EXTERNAL] INTEGER; (*Create options array codes. These are defined in $CREDEF macro*) CRE$L_TYPE,CRE$L_KEYLEN,CRE$L_ALLOC,CRE$L_IDXMAX,CRE$L_ENTALL, CRE$L_LUHMAX,CRE$L_VERTYP,CRE$L_IDXOPT,CRE$C_MACTXTCAS, CRE$C_VMSV3 : [EXTERNAL]INTEGER; Lib_Name : VARYING [128] 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) func: UNSIGNED; typ: UNSIGNED; VAR namblk: ARRAY[l..u:INTEGER] OF INTEGER := %IMMED 0): INTEGER; EXTERN; (*Function that creates/opens library*) FUNCTION LBR$OPEN (library_index: UNSIGNED; fns: [class_s]PACKED ARRAY[l..u:INTEGER] OF CHAR; create_options: Create_Array; 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 := %IMMED 0; VAR rnslen: INTEGER := %IMMED 0): INTEGER; EXTERN; (*Function that closes library*) FUNCTION LBR$CLOSE (library_index: UNSIGNED): INTEGER; EXTERN; (*Error handler to check error codes if open/create not successful*)

PROCEDURE Open_Error; (3) BEGIN 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*) WRITELN('Initialization Failed') ELSE (*Initialization was successful*) BEGIN (*Create and open the library*) status := LBR$OPEN (lib_index_ptr, Lib_Name, Options, (6) File_Type); 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 END END. (*of program creatlib*)

Each item in the following list corresponds to a number highlighted in Example 12-1:

	privacy and legal statement
4493PRO_025.HTML