Document revision date: 19 July 1999

To enter an interactive help session (after your initial request for help has been satisfied), you must set the HLP$M_PROMPT bit in the flags argument.

You can encounter four different types of prompt in an interactive help session. Each type represents a different level in the hierarchy of help available to you.

1. If the root library is the main library and you are not currently examining HELP for a particular topic, the prompt Topic? is output.
2. If the root library is a library other than the main library and if you are not currently examining HELP for a particular topic, a prompt of the form @<library-spec>Topic? is output.
3. If you are currently examining HELP for a particular topic (and subtopics), a prompt of the form <keyword...>subtopic? is output.
4. A combination of 2 and 3.

When you encounter one of these prompt messages, you can respond in any one of several ways. Each type of response and its effect on LBR$OUTPUT_HELP in each prompting situation is described in the following table:

Response	Action in the Current Prompt Environment1
keyword [...]	(1,2) Search all enabled libraries for these keys.
	(3,4) Search additional help for the current topic (and subtopic) for these keys.
@filespec [keyword[...]]	(1,2) Same as above, except that the root library is the library specified by filespec. If the specified library does not exist, treat @filespec as a normal key.
	(3,4) Same as above; treat @filespec as a normal key.
?	(1,2) Display a list of topics available in the root library.
	(3,4) Display a list of subtopics of the current topic (and subtopics) for which help exists.
Carriage Return	(1) Exit from LBR$OUTPUT_HELP.
	(2) Change root library to main library.
	(3,4) Strip the last keyword from a list of keys defining the current topic (and subtopic) environment.
Ctrl/Z	(1,2,3,4) Exit from LBR$OUTPUT_HELP.

Condition Values Returned

LBR$_ILLINROU	Input routine improperly specified or omitted.
LBR$_ILLOUTROU	Output routine improperly specified or omitted.
LBR$_NOHLPLIS	Error. No default help libraries can be opened.
LBR$_TOOMNYARG	Error. Too many arguments were specified.
LBR$_USRINPERR	Error. An error status was returned by the user-supplied input routine.

The LBR$PUT_END routine marks the end of a sequence of records written to a library by the LBR$PUT_RECORD routine.

Format

LBR$PUT_END library_index

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.

Argument

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.

Description

Call LBR$PUT_END after you write data records to the library with the LBR$PUT_RECORD routine. LBR$PUT_END terminates a module by attaching a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the data.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$PUT_HISTORY routine adds an update history record to the end of the update history list.

Format

LBR$PUT_HISTORY library_index ,record_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.

record_desc

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

Library history record. The record_desc argument is the address of a string descriptor pointing to the record to be added to the library update history.

Description

LBR$PUT_HISTORY writes a new update history record. If the library already contains the maximum number of history records (as specified at creation time by CRE$L_LUHMAX; see LBR$OPEN for details), the oldest history record is deleted before the new record is added.

Condition Values Returned

LBR$_NORMAL	Normal exit from the routine.
LBR$_INTRNLERR	Internal Librarian error.
LBR$_NOHISTORY	No update history. This is an informational code, not an error code.
LBR$_RECLNG	Record length greater than that specified by LBR$C_MAXRECSIZ. The record was not inserted or truncated.

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

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.

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 output record. The maximum record size for VAX libraries is symbolically defined as LBR$C_MAXRECSIZ; for Alpha 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.

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.

The LBR$REPLACE_KEY routine inserts a key in an index by changing the pointer associated with an existing key or by inserting a new key.

Format

LBR$REPLACE_KEY library_index ,key_name ,oldrfa ,newrfa

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:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Library key (for libraries with ASCII keys). The key_name argument is the address of a string descriptor for the key.

key_name

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

Library key (for libraries with binary keys). The key_name argument is the address of an unsigned longword value for the key.

oldrfa

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

Old record file address (RFA). The oldrfa argument is the address of a 2-longword array containing the original RFA (returned by LBR$LOOKUP_KEY) of the module header associated with the key you are replacing.

newrfa

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

New RFA. The newrfa argument is the address of a 2-longword array containing the RFA (returned by LBR$PUT_RECORD) of the module header associated with the new key.

Description

If LBR$REPLACE_KEY does not find the key in the current index, it calls the LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does find the key, it modifies the key entry in the index so that it points to the new module header.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_INVRFA	Specified RFA not valid.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$RET_RMSSTV routine returns the status value of the last OpenVMS RMS function performed by any LBR subroutine.

Format

LBR$RET_RMSSTV

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

None.

Description

The LBR$RET_RMSSTV routine returns, as the status value, the status of the last RMS operation performed by the Librarian. Each programming language provides an appropriate mechanism for accessing RMS status values.

Condition Values Returned

This routine returns any condition values returned by RMS routines.

The LBR$SEARCH routine finds index keys that point to specified data.

Format

LBR$SEARCH library_index ,index_number ,rfa_to_find ,routine_name

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

Library index number. The index_number argument is the address of a longword containing the number of the index you want to search (see Section 11.1.2.3).

rfa_to_find

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Record's file address (RFA) of the module whose keys you are searching for. The rfa_to_find argument is the address of a 2-longword array containing the RFA (returned earlier by LBR$LOOKUP_KEY or LBR$PUT_RECORD) of the module header.

routine_name

OpenVMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by reference

Name of a user-supplied routine to process the keys. The routine_name argument is the address of the procedure value of a user-supplied routine to call for each key entry containing the RFA (in other words, for each key that points to the same module header).

This user-supplied routine cannot contain any calls to LBR$DELETE_KEY or LBR$INSERT_KEY.

Description

Use LBR$SEARCH to find index keys that point to the same module header. Generally, in index number 1 (the module name table), just one key points to any particular module; thus, you would probably use this routine only to search library indexes where more than one key points to a module. For example, you might call LBR$SEARCH to find all the global symbols associated with an object module in an object library.

If LBR$SEARCH finds an index key associated with the specified RFA, it calls a user-supplied routine with two arguments:

• The key argument, which is the address of either of the following:
  • A string descriptor for the key name (libraries with ASCII key names)
  • An unsigned longword for the key value (libraries with binary keys)
• The RFA argument, which is the address of a 2-longword array containing the RFA of the module header

The routine must return a value to indicate success or failure. If the specified routine returns a false value (low bit = 0), then the index search terminates.

Note that the key found by LBR$SEARCH is valid only during the call to the user-supplied routine. If you want to use the key later, you must copy it.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_ILLIDXNUM	Specified library index number not valid.
LBR$_KEYNOTFND	Librarian did not find any keys with the specified RFA.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$SET_INDEX routine sets the index number to use when processing libraries that have more than one index.

Format

LBR$SET_INDEX library_index ,index_number

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

Index number you want to establish as the current index number. The index_number argument is the address of the longword that contains the number of the index you want to establish as the current index. (See Section 11.1.2.3.)

Description

When you call LBR$INI_CONTROL, the Librarian sets the current library index to 1 (the module name table, unless the library is a user-developed library). If you need to process another library index, you must use LBR$SET_INDEX to change the current library index.

Note that macro, help, and text libraries contain only one index; therefore, you do not need to call LBR$SET_INDEX. Object libraries contain two indexes. If you want to access the global symbol table, you must call the LBR$SET_INDEX routine to set the index number. User-developed libraries can contain more than one index; therefore, you may need to call LBR$SET_INDEX to set the index number.

Upon successful completion, LBR$SET_INDEX sets the current library index to the requested index number. LBR routines number indexes starting with 1.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_ILLIDXNUM	Library index number specified not valid.
LBR$_LIBNOTOPN	Specified library not open.

	privacy and legal statement
4493PRO_025.HTML