![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS Utility Routines Manual
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.
- If the root library is the main library and you are not currently
examining HELP for a particular topic, the prompt Topic? is
output.
- 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.
- If you are currently examining HELP for a particular topic (and
subtopics), a prompt of the form <keyword...>subtopic?
is output.
- 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 (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.
|
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. (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.
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)