Document revision date: 30 March 2001

You can process index entries an entry at a time by invoking LBR$GET_INDEX. The fourth argument specifies a match name for the entry or entries in the index to be processed: you can include the asterisk (*) and percent (%) characters in the match name for generic processing. For example, MOD* means all entries whose names begin with MOD; and MOD% means all entries whose names are four characters and begin with MOD.

The third argument names a user-written routine that is executed once for each index entry specified by the fourth argument. The routine must be a function declared as external that returns a success (odd number) or failure (even number) status. LBR$GET_INDEX processing stops on a return status of failure. Declare the first argument passed to the function as a passed-length character argument; this argument contains the name of the index entry. Declare the second argument as an integer array of two elements.

Example 11-10 obtains a match name from the command line and displays the names of the matching entries from index 1 (the index containing the names of the modules).

Example 11-10 Displaying Index Entries

SUBROUTINE LIST (INDEX) ! Lists modules in the library INTEGER STATUS, ! Return status INDEX, ! Library index CHARACTER*31 MATCHNAME ! Name of module to list INTEGER MATCHNAME_LEN ! Length of match name ! VMS library procedures INTEGER address LBR$GET_INDEX, LIB$LOCC ! Match routine INTEGER MATCH EXTERNAL MATCH ! Get module name and calculate length CALL CLI$GET_VALUE ('LIST', MATCHNAME) MATCHNAME_LEN = LIB$LOCC (' ', MATCHNAME) - 1 ! Call routine to display module names STATUS = LBR$GET_INDEX (INDEX, 1, ! Primary index MATCH, MATCHNAME (1:MATCHNAME_LEN)) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Exit END INTEGER FUNCTION MATCH (MODNAME, RFA) ! Function called for each module matched by MATCHNAME ! Displays the module name INTEGER STATUS_OK, ! Good return status RFA (2) ! RFA of module name in index PARAMETER (STATUS_OK = 1) ! Odd value CHARACTER*(*) MODNAME ! Name of module ! Display the name TYPE *, MODNAME ! Display module name ! Exit MATCH = STATUS_OK END

11.3 LBR Routines

This section describes the individual LBR routines.

The LBR$CLOSE routine closes an open library.

Format

LBR$CLOSE library_index

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.

Argument

library_index

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

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

Description

When you are finished working with a library, you should call LBR$CLOSE to close it. Upon successful completion, LBR$CLOSE closes the open library and deallocates all of the memory used for processing it.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$DELETE_DATA routine deletes the module header and data associated with the specified module.

Format

LBR$DELETE_DATA library_index ,txtrfa

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

library_index

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

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

txtrfa

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

Record's file address (RFA) of the module header for the module you want to delete. The txtrfa argument is the address of the 2-longword array that contains the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_exit KEY or LBR$PUT_RECORD.

Description

If you want to delete a library module, you must first call LBR$DELETE_KEY to delete any keys that point to it. If no library index keys are pointing to the module header, LBR$DELETE_DATA deletes the module header and associated data records; otherwise, this routine returns the error LBR$_STILLKEYS.

Note that other LBR routines may reuse data blocks that contain no data.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_INVRFA	Specified RFA not valid.
LBR$_LIBNOTOPN	Specified library not open.
LBR$_STILLKEYS	Keys in other indexes still point at the module header. Therefore, the specified module was not deleted.

The LBR$DELETE_KEY routine deletes a key from a library index.

Format

LBR$DELETE_KEY library_index ,key_name

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

library_index

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

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of a longword containing the index.

key_name

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

Key to be deleted from the library index. For libraries with binary keys, the key_name argument is the address of an unsigned longword containing the key number.

For libraries with ASCII keys, the key_name argument is the address of the string descriptor pointing to the key with the following argument characteristics:

Argument Characteristics	Entry
OpenVMS usage	char_string
type	character string
access	read only
mechanism	by descriptor

Description

If LBR$DELETE_KEY finds the key specified by key_name in the current index, it deletes the key. Note that, if you want to delete a library module, you should first use LBR$DELETE_KEY to delete any keys that point to it, then use LBR$DELETE_DATA to delete the module's header and associated data.

You cannot call LBR$DELETE_KEY from within the user-supplied routine specified in LBR$SEARCH or LBR$GET_INDEX.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_KEYNOTFND	Specified key not found.
LBR$_LIBNOTOPN	Specified library not open.
LBR$_UPDURTRAV	Specified index update not valid in a user-supplied routine specified in LBR$SEARCH or LBR$GET_INDEX.

The LBR$FIND routine sets the current internal read context for the library to the library module specified.

Format

LBR$FIND library_index ,txtrfa

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

library_index

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

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

txtrfa

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

Record's file address (RFA) of the module header for the module you want to access. The txtrfa argument is the address of a 2-longword array containing the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_KEY or LBR$PUT_RECORD.

Description

Use the LBR$FIND routine to access a module that you had accessed earlier in your program. For example, if you look up several keys with LBR$LOOKUP_KEY, you can save the RFAs returned by LBR$LOOKUP_KEY and later use LBR$FIND to reaccess the modules. Thus, you do not have to look up the module header's key every time you want to access the module. If the specified RFA is valid, LBR$FIND initializes internal tables so you can read the associated data.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_INVRFA	Specified RFA not valid.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$FLUSH routine writes modified blocks back to the library file and frees the virtual memory the blocks had been using.

Format

LBR$FLUSH library_index ,block_type

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

library_index

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

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

block_type

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by value

Extent of the flush operation. The block_type argument contains the longword value that indicates how the flush operation proceeds. If you specify LBR$C_FLUSHDATA, the data blocks are flushed. If you specify LBR$C_FLUSHALL, first the data blocks and then the current library index are flushed.

Each programming language provides an appropriate mechanism for accessing these symbols.

Description

LBR$FLUSH cannot be called from other LBR routines that reference cache addresses or by routines called by LBR routines.

Condition Values Returned

LBR$_NORMAL	Operation completed successfully.
LBR$_BADPARAM	Error. A value passed to the LBR$FLUSH routine was either out of range or an illegal value.
LBR$_WRITERR	Error. An error occurred during the writing of the cached update blocks to the library file.

The LBR$GET_HEADER routine returns information from the library's header to the caller.

Format

LBR$GET_HEADER library_index ,retary

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

library_index

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

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

retary

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

Array of 128 longwords that receives the library header. The retary argument is the address of the array that contains the header information. The information returned in the array is listed in the following table. Each programming language provides an appropriate mechanism for accessing this information.

Offset in Longwords	Symbolic Name	Contents
0	LHI$L_TYPE	Library type (see LBR$OPEN for possible values)
1	LHI$L_NINDEX	Number of indexes
2	LHI$L_MAJORID	Library format major identification
3	LHI$L_MINORID	Library format minor identification
4	LHI$T_LBRVER	ASCIC version of Librarian
12	LHI$L_CREDAT	Creation date/time
14	LHI$L_UPDTIM	Date/time of last update
16	LHI$L_UPDHIS	Virtual block number (VBN) of start of update history
17	LHI$L_FREEVBN	First logically deleted block
18	LHI$L_FREEBLK	Number of deleted blocks
19	LHI$B_NEXTRFA	Record's file address (RFA) of end of library
21	LHI$L_NEXTVBN	Next VBN to allocate at end of file
22	LHI$L_FREIDXBLK	Number of free preallocated index blocks
23	LHI$L_FREEIDX	List head for preallocated index blocks
24	LHI$L_HIPREAL	VBN of highest preallocated block
25	LHI$L_IDXBLKS	Number of index blocks in use
26	LHI$L_IDXCNT	Number of index entries (total)
27	LHI$L_MODCNT	Number of entries in index 1 (module names)
28	LHI$L_MHDUSZ	Number of bytes of additional information reserved in module header
29	LHI$L_MAXLUHREC	Maximum number of library update history records maintained
30	LHI$L_NUMLUHREC	Number of library update history records in history
31	LHI$L_LIBSTATUS	Library status (false if there was an error closing the library)
32-128		Reserved by Compaq

Description

On successful completion, LBR$GET_HEADER places the library header information into the array of 128 longwords.

Note that the offset is the byte offset of the value into the header structure. You can convert the offset to a longword subscript by dividing the offset by 4 and adding 1 (assuming that subscripts in your programming language begin with 1).

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.

	privacy and legal statement
4493PRO_022.HTML