 |
HP OpenVMS Utility Routines Manual
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 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 as follows:
| Flag Bits |
Description |
|
LBR$M_SYM_WEAK = 0x1
|
UNIX-style weak symbol attribute
|
|
LBR$M_SYM_GROUP = 0x2
|
Group symbol attribute
|
If this argument is not present, the normal NonGroup-Global type is the
assumed type.
Description
The LBR$INSERT_KEY routine inserts a new key in the current library
index. 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 is 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 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 |
The flags argument, if present and not zero, receives
the type of key returned. 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
|
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$LOOKUP_TYPE
The LBR$LOOK_TYPE routine searches the index for the key from a
particular module (RFA) and returns that key's type for that module.
Format
LBR$LOOKUP_TYPE library_index, key_name, txtrfa, ret_types
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 |
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 module's record file address (RFA) of the library module header.
The txtrfa argument is the address of the 2-longword
array that specifies the RFA of the module header.
ret_types
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The address of a longword to receive the symbol types found for the
specified module (txtrfa). The return type bits are as
follows:
LBR$M_SYM_NGG = 1
LBR$M_SYM_UXWK = 2
LBR$M_SYM_GG = 4
LBR$M_SYM_GUXWK = 8
Description
This routine searches the index for the key from a particular module
(RFA) and returns that key's type for that module, if present.
Otherwise, it returns LBR$_KEYNOTFND.
LBR$MAP_MODULE
The LBR$MAP_MODULE routine maps a module into process P2 space.
Format
LBR$MAP_MODULE library_index, ret_va_addr, ret_mod_len, txtrfa
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.
ret_va_addr
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference |
The 32-bit or 64-bit virtual address of a naturally aligned quadword
into which the routine returns the virtual address at which the routine
mapped the library module.
ret_mod_len
| OpenVMS usage: |
byte_count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The address of a naturally aligned quadword into which the library
routine returns the module length.
txtrfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The module's record file address (RFA) of the library module header.
The txtrfa argument is the address of the 2-longword
array that specifies the RFA of the module header.
Description
This routine maps a module, with the given txtrfa,
into process P2 memory space and returns the virtual address where the
module is mapped and the module size.
Unlike other LBR services that use RMS services, LBR$MAP_MODULE also
uses system services. Because of this, the secondary status for error
returns is placed in LBR$$GL_SUBSTS. Use this secondary status to find
additional status when an error is returned.
LBR$OPEN
The LBR$OPEN routine opens an existing library or creates a new one.
Format
LBR$OPEN library_index [,fns] [,create_options] [,dns] [,rlfna] [,rns]
[,rnslen]
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.
fns
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
File specification of the library. The fns argument is
the address of a string descriptor pointing to the file specification.
Unless the OpenVMS RMS NAM block address was previously supplied in the
LBR$INI_CONTROL routine and contained a file specification, this
argument must be included. Otherwise, the Librarian returns an error
(LBR$_NOFILNAM).
create_options
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Library characteristics. The create_options argument
is the address of an array of 20 longwords that define the
characteristics of the library you are creating. If you are creating a
library with LBR$C_CREATE, you must include the
create_options argument. The following table shows the
entries that the array must contain. Each programming language provides
an appropriate mechanism for accessing the listed symbols.
| Offset in Longwords |
Symbolic Name |
Contents |
|
0
|
CRE$L_TYPE
|
Library type:
|
|
|
LBR$C_TYP_UNK (0)
|
Unknown/unspecified
|
|
|
LBR$C_TYP_OBJ (1)
|
VAX object
|
|
|
LBR$C_TYP_MLB (2)
|
Macro
|
|
|
LBR$C_TYP_HLP (3)
|
Help
|
|
|
LBR$C_TYP_TXT (4)
|
Text
|
|
|
LBR$C_TYP_SHSTB (5)
|
VAX shareable image
|
|
|
LBR$C_TYP_NCS (6)
|
NCS
|
|
|
LBR$C_TYP_EOBJ (7)
|
Alpha object
|
|
|
LBR$C_TYP_ESHSTB (8)
|
Alpha shareable image
|
|
|
(9--127)
|
Reserved by HP
|
|
|
LBR$C_TYP_USRLW (128)
|
User library types --- low end of range
|
|
|
LBR$C_TYP_USRHI (255)
|
User library types --- high end of range
|
|
1
|
CRE$L_KEYLEN
|
Maximum length of ASCII keys or, if 0, indicates 32-bit unsigned keys
(binary keys)
|
|
2
|
CRE$L_ALLOC
|
Initial library file allocation
|
|
3
|
CRE$L_IDXMAX
|
Number of library indexes (maximum of eight)
|
|
4
|
CRE$L_UHDMAX
|
Number of additional bytes to reserve in module header
|
|
5
|
CRE$L_ENTALL
|
Number of index entries to preallocate
|
|
6
|
CRE$L_LUHMAX
|
Maximum number of library update history records to maintain
|
|
7
|
CRE$L_VERTYP
|
Format of library to create:
|
|
|
CRE$C_VMSV2
|
VMS Version 2.0
|
|
|
CRE$C_VMSV3
|
VMS Version 3.0
|
|
8
|
CRE$L_IDXOPT
|
Index key casing option:
|
|
|
CRE$C_HLPCASING
|
Treat character case as it is for help libraries
|
|
|
CRE$C_OBJCASING
|
Treat character case as it is for object libraries
|
|
|
CRE$C_MACTXTCAS
|
Treat character case as it is for macro and text libraries
|
|
9--19
|
|
Reserved by HP
|
The input of uppercase and lowercase characters is treated differently
for help, object, macro, and text libraries. For details, see the
HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.
dns
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Default file specification. The dns argument is the
address of the string descriptor that points to the default file
specification. See the OpenVMS Record Management Services Reference Manual for details about how defaults are
processed.
rlfna
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Related file name. The rlfna argument is the address
of an RMS NAM block pointing to the related file name. You must specify
rlfna for related file name processing to occur. If a
related file name is specified, only the file name, type, and version
fields of the NAM block are used for related name block processing. The
device and directory fields are not used. See the OpenVMS Record Management Services Reference Manual for
details on processing related file names.
rns
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Resultant file specification returned. The rns
argument is the address of a string descriptor pointing to a buffer
that is to receive the resultant file specification string. If an error
occurs during an attempt to open the library, the expanded name string
is returned instead.
rnslen
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Length of the resultant or expanded file name. The
rnslen argument is the address of a longword receiving
the length of the resultant file specification string (or the length of
the expanded name string if there was an error in opening the library).
Description
You can call this routine only after you call LBR$INI_CONTROL and
before you call any other LBR routine except LBR$OUTPUT_HELP.
When the library is successfully opened, the LBR routine reads the
library header into memory and sets the default index to 1.
If the library cannot be opened because it is already open for a write
operation, LBR$OPEN retries the open operation every second for a
maximum of 30 seconds before returning the RMS error, RMS$_FLK, to the
caller.
Condition Values Returned
|
LBR$_ERRCLOSE
|
Error. When the library was last modified while opened for write
access, the write operation was interrupted. This left the library in
an inconsistent state.
|
|
LBR$_ILLCREOPT
|
Requested create options not valid or not supplied.
|
|
LBR$_ILLCTL
|
Specified library control index not valid.
|
|
LBR$_ILLFMT
|
Specified library format not valid.
|
|
LBR$_ILLFUNC
|
Specified library function not valid.
|
|
LBR$_LIBOPN
|
Specified library already open.
|
|
LBR$_NOFILNAM
|
Error. The
fns argument was not supplied or the RMS NAM block was
not filled in.
|
|
LBR$_OLDLIBRARY
|
Success. The specified library has been opened; the library was created
with an old library format.
|
|
LBR$_OLDMISMCH
|
Requested library function conflicts with old library type specified.
|
|
LBR$_TYPMISMCH
|
Library type does not match the requested type.
|
|
