 |
HP OpenVMS Version 8.2 New Features and
Documentation Overview
LBR$DELETE_KEY
The LBR$DELETE_KEY routine removes a key from the current 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 library routine.
The library_index argument is the address of the
longword that contains 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
|
txtrfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
If present and if the flags argument is not
present, the routine will scan 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:
| 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 is not present or 0 (zero), the type
indicated by flags is deleted. If the
txtrfa specifies a non-zero value, the entry of the
type indicated, with the txtrfa supplied, is removed.
Note that only one type or all types may 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 should first use LBR$DELETE_KEY to delete
all 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$GET_INDEX
The LBR$GET_INDEX routine calls a user-supplied routine for selected
keys in an index.
Format
LBR$GET_INDEX library_index,index_number, routine_name [, match_desc]
[, 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 |
Number of the library index. The index_number argument
is the address of a longword containing the index number. This is the
index number associated with the keys you want to use as input to the
user-supplied routine.
routine_name
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by reference |
User-supplied routine called for each of the specified index keys. The
routine_name argument is the address of the procedure
value for this user-supplied routine.
LBR$GET_INDEX passes three arguments to the routine:
- A key name.
- For libraries with ASCII keys, the key_name
argument is the address of a string descriptor pointing to the key.
Note that the string and the string descriptor passed to the user
routine are valid only for the duration of that call. The string must
be copied privately if you need it again for more processing.
- For libraries with binary keys, the key_name
argument is the address of an unsigned longword containing the key
number.
- The record's file address (RFA) of the module's header for this key
name. The RFA argument is the address of a 2-longword array that
contains the RFA.
- The key's type whose bits are:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 1
|
UNIX-style weak symbol attributes
|
|
LBR$M_SYM_GROUP = 2
|
Group symbol attribute
|
The user routine must return a value to indicate success or failure. If
the user routine returns a false value (low bit = 0), LBR$GET_INDEX
stops searching the index and returns the status value of the
user-specified routine to the calling program.
The user routine cannot contain calls to either LBR$DELETE_KEY or
LBR$INSERT_KEY.
match_desc
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Key matching identifier. The match_desc argument is
the address of a string descriptor pointing to a string used to
identify which keys result in calls to the user-supplied routine.
Wildcard characters are allowed in this string. If you omit this
argument, the user routine is called for every key in the index. The
match_desc argument is valid only for libraries that
have ASCII keys.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
If present and non-zero, specifies the type, or all types, of the key
provided. The flag bits are:
| 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 will be provided the key's type through an additional
third parameter.
Description
LBR$GET_INDEX searches through the specified index for keys that match
the argument match_desc. Each time it finds a match,
it calls the user routine specified by the
routine_name argument. If you do not specify the
match_desc argument, it calls the user routine for
every key in the index.
For example, if you call LBR$GET_INDEX on an object library with
match_desc equal to TR* and
index_number set to 1 (module name table), then
LBR$GET_INDEX calls routine_name for each module whose
name begins with TR.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_ILLIDXNUM
|
Specified index number not valid.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
|
LBR$_NULIDX
|
Specified library empty.
|
LBR$INSERT_KEY
The LBR$INSERT_KEY routine inserts a new key in the current library
index.
Format
LBR$INSERT_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 library routine.
The library_index argument is the address of the
longword that contains the index.
key_name
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Name of the new key you are inserting. If the library uses binary keys,
the key_name argument is the address of an unsigned
longword containing the value of the key.
If the library uses ASCII keys, the key_name argument
is the address of a string descriptor of 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: |
modify |
| mechanism: |
by reference |
The record's file address (RFA) of the module associated with the new
key you are inserting. The txtrfa argument is the
address of a 2-longword array containing the RFA. You can use the RFA
returned by the first call to LBR$PUT_RECORD.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
If present, specifies the key's type. The flag bits are:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 0x1
|
UNIX-style weak symbol attribute
|
|
LBR$M_SYM_GROUP = 0x2
|
Group symbol attribute
|
If this parameter is not present, the normal NonGroup-Global type is
the assumed type.
Description
You cannot call LBR$INSERT_KEY within the user-supplied routine
specified in LBR$SEARCH or LBR$GET_INDEX.
Condition Values Returned
|
LBR$_DUPKEY
|
Index already contains the specified key.
|
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_INVRFA
|
Specified RFA does not point to valid data.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
|
LBR$_UPDURTRAV
|
LBR$INSERT_KEY was called by the user-defined routine specified in
LBR$SEARCH or LBR$GET_INDEX.
|
LBR$LOOKUP_KEY
The LBR$LOOKUP_KEY routine looks up a key in the library's current
index and prepares to access the data in the module associated with the
key.
Format
LBR$LOOKUP_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 the longword
that contains the index.
key_name
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Name of the library key. If the library uses binary keys, the
key_name argument is the address of the unsigned
longword value of the key.
If the library uses ASCII keys, the key_name argument
is the address of a string descriptor for 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: |
write only |
| mechanism: |
by reference |
The record's file address (RFA) of the library module header. The
txtrfa argument is the address of the 2-longword array
that receives the RFA of the module header.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
If present and not zero, receives the type of key returned. The flag
bits are:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 0x1
|
UNIX-style weak symbol attribute
|
|
LBR$M_SYM_GROUP = 0x2
|
Group symbol attribute
|
The key returned is the highest precedent definition type present.
Description
If LBR$LOOKUP_KEY finds the specified key, it initializes internal
tables so you can access the associated data.
This routine returns the RFA to the 2-longword array referenced by
txtrfa.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_INVRFA
|
RFA obtained not valid.
|
|
LBR$_KEYNOTFND
|
Specified key not found.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
LBR$PUT_RECORD
The LBR$PUT_RECORD routine writes a data record beginning at the next
free location in the library.
Format
LBR$PUT_RECORD library_index ,bufdes ,txtrfa [,mod_size]
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.
bufdes
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Record to be written to the library. The bufdes
argument is the address of a string descriptor pointing to the buffer
containing the record. The maximum record size for VAX libraries is
symbolically defined as LBR$C_MAXRECSIZ; for Alpha and I64 libraries,
the symbolic maximum record size is ELBR$_MAXRECSIZ.
txtrfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Record's file address (RFA) of the module header. The
txtrfa argument is the address of a 2-longword array
receiving the RFA of the newly created module header upon the first
call to LBR$PUT_RECORD.
mod_size
| OpenVMS usage: |
byte count |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The value from mod_size is read on the first call to
this routine only and ignored otherwise. This value specifies the size
of the module to be entered so that contiguous space is allocated
within the library for that module. This argument is ignored for
non-ELF object libraries and for data-reduced ELF object libraries. The
LBR$PUT_END routine is still required to terminate the byte stream and
close off the module.
Description
If this is the first call to LBR$PUT_RECORD, this routine first writes
a module header and returns its RFA to the 2-longword array pointed to
by txtrfa. LBR$PUT_RECORD then writes the supplied
data record to the library. On subsequent calls to LBR$PUT_RECORD, this
routine writes the data record beginning at the next free location in
the library (after the previous record). The last record written for
the module should be followed by a call to LBR$PUT_END.
Condition Values Returned
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_LIBNOTOPN
|
Specified library not open.
|
|
