 |
OpenVMS Utility Routines Manual
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.
|
|
