HP OpenVMS Systems Documentation

Content starts here

OpenVMS Utility Routines Manual


Previous Contents Index

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


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

LBR$DELETE_KEY

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.

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


Previous Next Contents Index