HP OpenVMS Utility Routines Manual


Previous Contents Index


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


Previous Next Contents Index