 |
HP OpenVMS Utility Routines Manual
LBR$REPLACE_KEY
The LBR$REPLACE_KEY routine modifies or inserts a key into the library.
Format
LBR$REPLACE_KEY library_index ,key_name ,oldrfa ,newrfa [, 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.
key_name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
For libraries with ASCII keys, the key_name argument
is the address of a string descriptor for the key.
For libraries with binary keys, the key_name argument
is the address of an unsigned longword value for the key.
oldrfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Old record file address (RFA). The oldrfa argument is
the address of a 2-longword array containing the original RFA (returned
by LBR$LOOKUP_KEY) of the module header associated with the key you are
replacing.
newrfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
New RFA. The newrfa argument is the address of a
2-longword array containing the RFA (returned by LBR$PUT_RECORD) of the
module header associated with the new key.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
If present, the flags argument specifies the type of
key being replaced. The flag bits are as follows:
| Flag Bits |
Description |
|
LBR$SYM_WEAK = 0x1
|
UNIX-style weak symbol attribute
|
|
LBR$SYM_GROUP = 0x2
|
Group symbol attribute
|
If this argument is not present, NonGroup-Global is the assumed type.
In this case, all type lists are searched and the entries removed. The
new symbol is placed in the new NonGroup-Global definition with
newrfa as the defining module.
If this parameter is present, it represents the flags set for the type
of symbol being replaced. The replacement is done in place without
losing its position in the type list. If the symbol does not exist when
the call to this routine is made, the new definition is placed at the
end of the type list for the specified type.
Because there are now different symbol definition types, HP advises
using the LBR$DELETE_KEY routine followed by the LBR$INSERT_KEY routine
when the old key and new key differ in definition type.
Description
If LBR$REPLACE_KEY does not find the key in the current index, it calls
the LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does
find the key, it modifies the key entry in the index so that it points
to the new module header.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_INVRFA
|
Specified RFA not valid.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
LBR$RET_RMSSTV
The LBR$RET_RMSSTV routine returns the status value of the last OpenVMS
RMS function performed by any LBR subroutine.
Format
LBR$RET_RMSSTV
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
None.
Description
The LBR$RET_RMSSTV routine returns, as the status value, the status of
the last RMS operation performed by the Librarian. Each programming
language provides an appropriate mechanism for accessing RMS status
values.
Condition Values Returned1
This routine returns any condition values returned by RMS routines.
LBR$SEARCH
The LBR$SEARCH routine finds index keys that point to specified data.
Format
LBR$SEARCH library_index ,index_number ,rfa_to_find ,routine_name [,
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.
index_number
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Library index number. The index_number argument is the
address of a longword containing the number of the index you want to
search.
rfa_to_find
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Record file address (RFA) of the module whose keys you are searching
for. The rfa_to_find argument is the address of a
2-longword array containing the RFA (returned earlier by LBR$LOOKUP_KEY
or LBR$PUT_RECORD) of the module header.
routine_name
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by reference |
Name of a user-supplied routine to process the keys. The
routine_name argument is the address of the procedure
value of a user-supplied routine to call for each key entry containing
the RFA (in other words, for each key that points to the same module
header).
This user-supplied routine cannot contain any calls to LBR$DELETE_KEY
or LBR$INSERT_KEY.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword unsigned |
| access: |
read only |
| mechanism: |
by reference |
If present and nonzero, the flags argument specifies
the type, or all types, of the key provided. The flag 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
|
The user routine is provided the symbol's type through an additional
third parameter.
Description
The LBR$SEARCH routine searches the library index for symbols with the
given RFA and calls the supplied routine with those symbols.
Use LBR$SEARCH to find index keys that point to the same module header.
Generally, in index number 1 (the module name table), just one key
points to any particular module; thus, you would probably use this
routine only to search library indexes where more than one key points
to a module. For example, you might call LBR$SEARCH to find all the
symbols in the symbol index that are associated with an object module
in an object library.
If LBR$SEARCH finds an index key associated with the specified RFA, it
calls a user-supplied routine with two arguments:
- The key argument, which is the address of either of the following
items:
- A string descriptor for the key name (libraries with ASCII key
names)
- An unsigned longword for the key value (libraries with binary keys)
- The RFA argument, which is the address of a 2-longword array
containing the RFA of the module header
- The key's type, whose flag bits are as follows:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 1
|
UNIX-style weak symbol attribute
|
|
LBR$M_SYM_GROUP = 2
|
Group symbol attribute
|
The user routine must return a value to indicate success or failure. If
the specified user routine returns a false value (low bit = 0), then
the index search terminates.
Note that the key found by LBR$SEARCH is valid only during the call to
the user-supplied routine. If you want to use the key later, you must
copy it.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_ILLIDXNUM
|
Specified library index number not valid.
|
|
LBR$_KEYNOTFND
|
Library routine did not find any keys with the specified RFA.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
LBR$SET_INDEX
The LBR$SET_INDEX routine sets the index number to use when processing
libraries that have more than one index.
Format
LBR$SET_INDEX library_index ,index_number
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.
index_number
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Index number you want to establish as the current index number. The
index_number argument is the address of the longword
that contains the number of the index you want to establish as the
current index. Refer to Section 13.1.2.3.
Description
When you call LBR$INI_CONTROL, the Librarian sets the current library
index to 1 (the module name table, unless the library is a
user-developed library). If you need to process another library index,
you must use LBR$SET_INDEX to change the current library index.
Note that macro, help, and text libraries contain only one index;
therefore, you do not need to call LBR$SET_INDEX. Object libraries
contain two indexes. If you want to access the global symbol table, you
must call the LBR$SET_INDEX routine to set the index number.
User-developed libraries can contain more than one index; therefore,
you may need to call LBR$SET_INDEX to set the index number.
Upon successful completion, LBR$SET_INDEX sets the current library
index to the requested index number. LBR routines number indexes
starting with 1.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_ILLIDXNUM
|
Library index number specified not valid.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
LBR$SET_LOCATE
The LBR$SET_LOCATE routine sets the record access of LBR subroutines to
locate mode.
Format
LBR$SET_LOCATE 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
Librarian record access may be set to move mode (the default set by
LBR$SET_MOVE) or locate mode. The setting affects the operation of the
LBR$GET_RECORD routine.
If move mode is set (the default), LBR$GET_RECORD copies the requested
record to the specified user buffer. If locate mode is set, the record
is not copied. Instead, the outbufdes descriptor is
set to reference the internal LBR subroutine buffer that contains the
record.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
LBR$SET_MODULE
The LBR$SET_MODULE routine reads, and optionally updates, the module
header associated with a given record's file address (RFA).
Format
LBR$SET_MODULE library_index ,rfa [,bufdesc] [,buflen] [,updatedesc]
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.
rfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Record's file address (RFA) associated with the module header. The
rfa argument is the address of a 2-longword array
containing the RFA returned by LBR$PUT_RECORD or LBR$LOOKUP_KEY.
bufdesc
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Buffer that receives the module header. The bufdesc
argument is the address of a string descriptor pointing to the buffer
that receives the module header. The buffer must be the size specified
by the symbol MHD$B_USRDAT plus the value of the CRE$L_UHDMAX create
option. The MHD$ and CRE$ symbols are defined in the modules $MHDDEF
and $CREDEF, which are stored in SYS$LIBRARY:STARLET.MLB.
buflen
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Length of the module header. The buflen argument is
the address of a longword receiving the length of the returned module
header.
updatedesc
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Additional information to be stored with the module header. The
updatedesc argument is the address of a string
descriptor pointing to additional data that the Librarian stores with
the module header. If you include this argument, the Librarian updates
the module header with the additional information.
Description
If you specify bufdesc, the LBR routine returns the
module header into the buffer. If you specify buflen,
the routine also returns the buffer's length. If you specify
updatedesc, the routine updates the header information.
You define the maximum length of the update information (by specifying
a value for CRE$L_UHDMAX) when you create the library. The Librarian
zero-fills the information if it is less than the maximum length or
truncates it if it exceeds the maximum length.
Condition Values Returned
|
LBR$_HDRTRUNC
|
Buffer supplied to hold the module header was too small.
|
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_ILLOP
|
Error. The
updatedesc argument was supplied and the library was a
Version 1.0 library or the library was opened only for read access.
|
|
LBR$_INVRFA
|
Specified RFA does not point to a valid module header.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
|
