The FDL$PARSE routine parses an FDL specification, allocates OpenVMS RMS control blocks (FABs, RABs, or XABs), and fills in the relevant fields.

Format

FDL$PARSE fdl_desc ,fdl_fab_pointer ,fdl_rab_pointer [,flags] [,default_fdl_desc] [,stmnt_num]

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

fdl_desc

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

Name of the FDL file or the actual FDL specification to be parsed. See the description of the fdl_desc argument for the FDL$CREATE routine for details.

fdl_fab_pointer

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

Address of an RMS file access block (FAB). The fdl_fab_pointer argument is the address of a longword that receives the address of the FAB. FDL$PARSE both allocates the FAB and fills in its relevant fields.

fdl_rab_pointer

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

Address of an RMS record access block (for VAX, this is the RAB; for Alpha, it is the RAB64). The fdl_rab_pointer argument is the address of a longword that receives the address of the RAB or RAB64. FDL$PARSE both allocates the RAB or RAB64 and fills in any fields designated in the FDL specification.

For Alpha, the 64-bit record access block (RAB64) consists of the traditional 32-bit RAB followed by some 64-bit fields. The RAB64 is automatically allocated for Alpha users, who can either use it as a RAB64 or overlay it with the 32-bit RAB definition and use it as a traditional 32-bit RAB.

flags

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

Flags (or masks) that control how the default_fdl_desc argument is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags. If you omit this argument or specify it as zero, no flags are set. The flags and their meanings are as follows:

Flag	Function
FDL$V_DEFAULT_STRING	Interprets the default_fdl_desc argument as an FDL specification in string form. By default, the default_fdl_desc argument is interpreted as the file name of an FDL file.
FDL$V_FDL_STRING	Interprets the fdl_desc argument as an FDL specification in string form. By default, the fdl_desc argument is interpreted as the file name of an FDL file.
FDL$V_LONG_NAMES	Allocates and returns a long name access block (NAML) linked to the returned RMS file access block (FAB). The appropriate values are set in the NAML and FAB blocks so that the long file name fields of the NAML block will be used. By default, a name block is not allocated and the file name fields of FAB are used. If the FDL$V_LONG_NAMES flag is set, then the FDL$V_LONG_NAMES bit must also be set in the flags argument to the FDL$RELEASE routine to ensure that memory allocated for the NAML block is deallocated properly. This flag is valid for OpenVMS Alpha only.
FDL$V_SIGNAL	Signals any error. By default, the status code is returned to the calling image.

By default, an error status is returned rather than signaled.

default_fdl_desc

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

The default_fdl_desc argument is the address of a character-string descriptor pointing to either the default FDL file or the default FDL specification. See the description of the fdl_desc argument for the FDL$CREATE routine for details.

This argument allows you to specify default FDL attributes. In other words, FDL$PARSE processes the attributes specified in this argument unless you override them with the attributes you specify in the fdl_desc argument.

You can code the FDL defaults directly into your program, typically with an FDL specification in string form.

stmnt_num

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

FDL statement number. The stmnt_num argument is the address of a longword that receives the FDL statement number. If the routine finishes successfully, the stmnt_num argument is the number of statements in the FDL specification. If the routine does not finish successfully, the stmnt_num argument receives the number of the statement that caused the error. Note that line numbers and statement numbers are not the same and that an FDL specification in string form has no "lines."

By default, an error status is returned rather than signaled.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
LIB$_BADBLOADR	Bad block address.
LIB$_BADBLOSIZ	Bad block size.
LIB$_INSVIRMEM	Insufficient virtual memory.
RMS$_DNF	Directory not found.
RMS$_DNR	Device not ready or not mounted.
RMS$_WCC	Invalid wildcard context (WCC) value.

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 by using the DCL command LIBRARY. For more information, see the HP OpenVMS DCL Dictionary.

13.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 13.2 provides sample programs showing how to use various LBR routines. Section 13.3 is a reference section that provides details about each of the LBR routines.

13.1.1 Types of Libraries

You can use the LBR routines to maintain the following types of libraries:

• Object libraries, including I64 (ELF) object libraries and Alpha object libraries, 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 HP 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 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. For information about defining macros on OpenVMS VAX systems, see the VAX MACRO and Instruction Set Reference Manual. For information on porting VAX MACRO code to an OpenVMS Alpha systems, see the HP OpenVMS MACRO Compiler Porting and User's Guide. For information on porting code to I64 systems, see the Porting Applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers.
  A macro library has a default file type of .MLB and defaults the file type of input files to .MAR.
• Help libraries contain modules of help messages that provide user information about a program. You can retrieve help messages at the DCL level by using 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 HP 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 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, including I64 (ELF) shareable image libraries and Alpha shareable symbol table libraries 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 HP OpenVMS Command Definition, Librarian, and Message Utilities Manual and the HP OpenVMS Linker Utility Manual, respectively.
  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 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 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.

Table 13-1 shows the libraries that are created by the Librarian utility for each OpenVMS platform.

Table 13-1 Libraries Created by OpenVMS Platforms

OpenVMS VAX	OpenVMS Alpha	OpenVMS I64
VAX object	Alpha object	I64 object
VAX shareable image	Alpha shareable image	I64 shareable image
Alpha object 1	VAX object 1
Alpha shareable image 2	VAX shareable image 2
Macro	Macro	Macro
Text	Text	Text
Help	Help	Help

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 13-1 and Figure 13-2. You can create user-developed libraries only by calling LBR$OPEN; they are structured as described in Figure 13-3.

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

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

13.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 13-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 13-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 13-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 13-1 Structure of a Macro, Text, or Help Library

Figure 13-2 Structure of an Object or Shareable Image Library

Figure 13-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 13-2 lists the routines and summarizes their functions.

Table 13-2 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$LOOKUP_TYPE	Searches the index for the key from a particular module (RFA) and returns the key's type for that module.
LBR$MAP_MODULE	I64 only. Maps a module in P2 space.
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_MODULE	(I64 only.) Puts an entire module, with the module's file address (RFA), from memory space into the current library.
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 associated with a given record's file address (RFA).
LBR$SET_MOVE	Sets Librarian subroutine record access to move mode.
LBR$UNMAP_MODULE	(I64 only.) Unmaps a module from process P2 space.