HP OpenVMS Systems Documentation

HP OpenVMS Version 8.2 New Features and Documentation Overview

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.

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.

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.

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.

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.