Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

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.

1Keyed to the prompt in the preceding list.

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

## LBR$PUT_END

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

## LBR$PUT_HISTORY

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

## LBR$PUT_RECORD

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

## LBR$REPLACE_KEY

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

## LBR$RET_RMSSTV

> 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

1

> This routine returns any condition values returned by RMS routines.

## LBR$SEARCH

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

## LBR$SET_INDEX

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

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_025.HTML