HP OpenVMS Utility Routines Manual


Previous Contents Index

13.2.9 Listing and Processing Index Entries

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

13.3 LBR Routines

This section describes the individual LBR routines.


LBR$CLOSE

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.

LBR$DELETE_DATA

The LBR$DELETE_DATA routine deletes module data from the library.

Format

LBR$DELETE_DATA library_index, txtrfa [,flags]


RETURNS


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

Longword condition value. Most utility routines return a condition value. 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_KEY or LBR$PUT_RECORD.

flags


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

The contents of the flag are ignored. The purpose of this argument is to indicate to this routine that the application knows about the new index structure for ELF object and ELF shareable image libraries.

Description

To delete a library module, first call LBR$DELETE_KEY to delete all 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 library routines can 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 to the module header. Therefore, the specified module was not deleted.

LBR$DELETE_KEY

The LBR$DELETE_KEY routine removes a key from the current library index.

Format

LBR$DELETE_KEY library_index, key_name[, txtrfa] [, flags]


RETURNS


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

Longword condition value. Most utility routines return a condition value. 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 that contains the index.

key_name


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

The 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

txtrfa


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

The txtrfa argument is the address of the 2-longword array that contains the record file address (RFA). If present and if the flags argument is not present, the routine scans for all types of the key for the specified txtrfa and delete those entries.

flags


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

If present, this argument indicates that a particular type of the key or all types of the key is to be deleted. The flags bits are as follows:
Flag Bits Description
LBR$M_SYM_WEAK = 0x1 UNIX-style weak symbol attribute
LBR$M_SYM_GROUP = 0x2 Group symbol attribute
LBR$M_SYM_ALL = 0x80000000 All symbols

If the txtrfa argument is not present or if its value is zero, the type indicated by flags is deleted. If txtrfa specifies a nonzero value, the entry of the type indicated, with the txtrfa supplied, is removed. Note that only one type or all types can be specified.


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 must first use LBR$DELETE_KEY to delete all the 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$_UPDIRTRAV Specified index update not valid in a user-supplied routine specified in LBR$SEARCH or LBR$GET_INDEX.

LBR$FIND

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.

LBR$FLUSH

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.

LBR$GET_HEADER

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 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 HP

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.


Previous Next Contents Index