HP OpenVMS Utility Routines Manual


Previous Contents Index


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:

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.

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


Previous Next Contents Index