 |
HP OpenVMS Utility Routines Manual
LBR$OUTPUT_HELP
The LBR$OUTPUT_HELP routine outputs help text to a user-supplied output
routine. The text is obtained from an explicitly named help library or,
optionally, from user-specified default help libraries. An optional
prompting mode is available that enables LBR$OUTPUT_HELP to interact
with you and continue to provide help information after the initial
help request has been satisfied.
Format
LBR$OUTPUT_HELP output_routine [,output_width] [,line_desc]
[,library_name] [,flags] [,input_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
output_routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
write only |
| mechanism: |
by reference |
Name of a routine that writes help text a line at a time. The
output_routine argument is the address of the
procedure value of the routine to call. You should specify either the
address of LIB$PUT_OUTPUT or a routine of your own that has the same
calling format as LIB$PUT_OUTPUT.
output_width
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Width of the help-text line to be passed to the user-supplied output
routine. The output_width argument is the address of a
longword containing the width of the text line to be passed to the
user-supplied output routine. If you omit output_width
or specify it as 0, the default output width is 80 characters per line.
line_desc
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Contents of the help request line. The line_desc
argument is the address of a string descriptor pointing to a character
string containing one or more help keys defining the help requested,
for example, the HELP command line minus the HELP command and HELP
command qualifiers. The default is a string descriptor for an empty
string.
library_name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the main library. The library_name argument is
the address of a string descriptor pointing to the main library file
specification string. The default is a null string, which means you
should use the default help libraries. If you omit the device and
directory specifications, the default is SYS$HELP. The default file
type is .HLB.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags specifying help output options. Each programming language
provides an appropriate mechanism for accessing these flags. The
flags argument is the address of an unsigned longword
that contains the following flags, when set:
| Flag |
Description |
|
HLP$M_PROMPT
|
Interactive help prompting is in effect.
|
|
HLP$M_PROCESS
|
The process logical name table is searched for default help libraries.
|
|
HLP$M_GROUP
|
The group logical name table is searched for group default help
libraries.
|
|
HLP$M_SYSTEM
|
The system logical name table is searched for system default help
libraries.
|
|
HLP$M_LIBLIST
|
The list of default libraries available is output with the list of
topics available.
|
|
HLP$M_HELP
|
The list of topics available in a help library is preceded by the major
portion of the text on help.
|
If you omit this longword, the default is for prompting and all default
library searching to be enabled, but no library list is generated and
no help text precedes the list of topics.
input_routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by reference |
Routine used for prompting. The input_routine argument
is the address of the procedure value of the prompting routine. You
should specify either the address of LIB$GET_INPUT or a routine of your
own that has the same calling format as LIB$GET_INPUT. This argument
must be supplied when the HELP command is run in prompting mode (that
is, HLP$M_PROMPT is set or defaulted).
Description
The LBR$OUTPUT_HELP routine provides a simple, one-call method to
initiate an interactive help session. Help library bookkeeping
functions, such as LBR$INI_CONTROL and LBR$OPEN, are handled
internally. You should not call LBR$INI_CONTROL or LBR$OPEN before you
issue a call to LBR$OUTPUT_HELP.
LBR$OUTPUT_HELP accepts help keys in the same format as LBR$GET_HELP,
with the following qualifications:
- If the keyword HELP is supplied, help text on HELP is output,
followed by a list of HELP subtopics available.
If no help keys are
provided or if the line_desc argument is 0, a list of
topics available in the root library is output.
- If the line_desc argument contains a list of help
keys, then each key must be separated from its predecessor by a slash
(/) or by one or more spaces.
- The first key can specify a library to replace the main library as
the root library (the first library searched) in which LBR$OUTPUT_HELP
searches for help. A key used for this purpose must have the form
<@filespec>, where filespec is subject to the
same restrictions as the library_name argument. If the
specified library is an enabled user-defined default library, then
filespec can be abbreviated as any unique substring of that
default library's logical name translation.
In default library searches, you can define one or more default
libraries for LBR$OUTPUT_HELP to search for help information not
contained in the root library. Do this by equating logical names
(HLP$LIBRARY, HLP$LIBRARY_1,...,HLP$LIBRARY_999) to the file
specifications of the default help libraries. You can define these
logical names in the process, group, or system logical name table.
If default library searching is enabled by the flags
argument, LBR$OUTPUT_HELP uses those flags to determine which logical
name tables are enabled and then automatically searches any user
default libraries that have been defined in those logical name tables.
The library search order proceeds as follows: root library, main
library (if specified and different from the root library), process
libraries (if enabled), group libraries (if enabled), system libraries
(if enabled). If the requested help information is not found in any of
these libraries, LBR$OUTPUT_HELP returns to the root library and issues
a "help not found" message.
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_MODULE
The LBR$PUT_MODULE routine puts an entire module, with the module's
record file address (RFA), from memory space into the current library.
Format
LBR$PUT_MODULE library_index, mod_addr, mod_len, txtrfa
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.
mod_addr
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit reference |
The address from which the Library service obtains the 64-bit address
of where the module is mapped in memory. The mod_addr
argument is the 32- or 64-bit virtual address of a naturally aligned
quadword containing the virtual address location of the module to write
to the library.
mod_len
| OpenVMS usage: |
byte_count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
The 64-bit virtual address of a naturally aligned quadword containing
the length of the module that the Library service is to write into the
library.
txtrfa
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
The module's record file address (RFA) of the library module header.
The txtrfa argument is the address of the 2-longword
array receiving the RFA of the newly created module header.
Description
The LBR$PUT_MODULE routine puts an entire module, with the module's
record file address (RFA), from memory space into the current library.
LBR$PUT_END is not required when you write an entire module to the
current library.
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 [, mod_size]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
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 output record. The maximum record size for VAX libraries
is symbolically defined as LBR$C_MAXRECSIZ; for I64 and 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.
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 and ignored otherwise. The 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.
|
|
