HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The LBR$GET_HISTORY routine returns each library update history record to a user-specified action routine.

Format

LBR$GET_HISTORY library_index ,action_routine

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.

action_routine

OpenVMS usage:	procedure
type:	procedure value
access:	modify
mechanism:	by reference

User-supplied routine for processing library update history records. The action_routine argument is the address of the procedure value of this user-supplied routine. The routine is invoked once for each update history record in the library. One argument is passed to the routine, namely, the address of a descriptor pointing to a history record.

Description

This routine retrieves the library update history records written by the routine LBR$PUT_HISTORY.

Condition Values Returned

LBR$_NORMAL	Normal exit from the routine.
LBR$_EMPTYHIST	History empty. This is an informational code, not an error code.
LBR$_INTRNLERR	Internal Librarian routine error occurred.
LBR$_NOHISTORY	No update history. This is an informational code, not an error code.

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]

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

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 (see Section 12.1.2.3).

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 two 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 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 routine must return a value to indicate success or failure. If the 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 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 routine is called for every key in the index. The match_desc argument is valid only for libraries that have ASCII keys.

Description

LBR$GET_INDEX searches through the specified index for a key that matches the argument match_desc. Each time it finds a match, it calls the routine specified by the routine_name argument. If you do not specify the match_desc argument, it calls the routine for every key in the index.

For example, if you call LBR$GET_INDEX 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$GET_RECORD routine returns the next data record in the module associated with a specified key.

Format

LBR$GET_RECORD library_index [,inbufdes] [,outbufdes]

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. The library must be open and LBR$LOOKUP_KEY or LBR$FIND must have been called to find the key associated with the module whose records you want to read.

inbufdes

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

User buffer to receive the record. The inbufdes argument is the address of a string descriptor that points to the buffer that receives the record from LBR$GET_RECORD. This argument is required when the Librarian subroutine record access is set to move mode (which is the default). This argument is not used if the record access mode is set to locate mode. The Description section contains more information about the locate and move modes.

outbufdes

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

String descriptor that receives the actual length and address of the data for the record returned. The outbufdes argument is the address of the string descriptor for the returned record. The length and address fields of the string descriptor are filled in by the LBR$GET_RECORD routine. This parameter must be specified when Librarian subroutine record access is set to locate mode. This parameter is optional if record access mode is set to move mode. The Description section contains more information about the locate and move modes.

Description

Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_KEY or LBR$FIND to set the internal library read context to the record's file address (RFA) of the module header of the module whose records you want to read.

LBR$GET_RECORD uses two record access modes: locate mode and move mode. Move mode is the default. The LBR$SET_LOCATE and LBR$SET_MOVE subroutines set these modes. The record access modes are mutually exclusive; that is, when one is set, the other is turned off. If move mode is set, LBR$GET_RECORD copies the record to the user-specified buffer described by inbufdes. If you have optionally specified the output buffer string descriptor, outbufdes, the Librarian fills it with the actual length and address of the data. If locate mode is set, LBR$GET_RECORD returns the record by way of an internal subroutine buffer, pointing the outbufdes descriptor to the internal buffer. The second parameter, inbufdes, is not used when locate mode is set.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.
LBR$_LKPNOTDON	Requested key lookup not done.
RMS$_EOF	Error. An attempt has been made to read past the logical end of the data in the module.

The LBR$INI_CONTROL routine initializes a control structure, called a library control index, to identify the library for use by other LBR routines.

Format

LBR$INI_CONTROL library_index ,func [,type] [,namblk]

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:	write only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of a longword that is to receive the index.

func

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library function to be performed. The func argument is the address of the longword that contains the library function. Valid functions are LBR$C_CREATE, LBR$C_READ, and LBR$C_UPDATE. Each programming language provides an appropriate mechanism for accessing these symbols.

type

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library type. The type argument is the address of the longword containing the library type. Valid library types include the following:

• LBR$C_TYP_OBJ (VAX object)
• LBR$C_TYP_SHSTB (VAX shareable image)
• LBR$C_TYP_EOBJ (Alpha object)
• LBR$C_TYP_ESHSTB (Alpha shareable image)
• LBR$C_TYP_MLB (macro)
• LBR$C_TYP_HLP (help)
• LBR$C_TYP_TXT (text)
• LBR$C_TYP_UNK (unknown)
• LBR$C_TYP_NCS (NCS library)
• For user-developed libraries, a type in the range of LBR$C_TYP_USRLW through LBR$C_TYP_USRHI.

namblk

OpenVMS usage:	nam
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS RMS name block (NAM). The namblk argument is the address of a variable-length data structure containing an RMS NAM block. The LBR$OPEN routine fills in the information in the NAM block so it can be used later to open the library. If the NAM block has this file identification in it from previous use, the LBR$OPEN routine uses the open-by-NAM block option. This argument is optional and should be used if the library will be opened many times during a single run of the program. For a detailed description of RMS NAM blocks, see the OpenVMS Record Management Services Reference Manual.

Description

Except for the LBR$OUTPUT_HELP routine, you must call LBR$INI_CONTROL before calling any other LBR routine. After you initialize the library control index, you must open the library or create a new one using the LBR$OPEN routine. You can then call other LBR routines that you need. After you finish working with a library, close it with the LBR$CLOSE routine.

LBR$INI_CONTROL initializes a library by filling the longword referenced by the library_index argument with the control index of the library. Upon completion of the call, the index can be used to refer to the current library in all future routine calls. Therefore, your program must not alter this value.

You can have up to 16 libraries open simultaneously in your program.

Condition Values Returned

LBR$_NORMAL	Library control index initialized successfully.
LBR$_ILLFUNC	Requested function not valid.
LBR$_ILLTYP	Specified library type not valid.
LBR$_TOOMNYLIB	Error. An attempt was made to allocate more than 16 control indexes.

The LBR$INSERT_KEY routine inserts a new key in the current library index.

Format

LBR$INSERT_KEY library_index ,key_name ,txtrfa

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.

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.

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

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.

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.

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 (consisting of the virtual block number (VBN) and the byte offset) to the 2-longword array referenced by txtrfa. Note that the RFA is only 6 bytes long.

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.