LBR$Output

LBR$Output_Help

Display help text

LBR$Output_Help is used to display help.

Format:

LBR$Output_Help routine {width} {path} {library} {flags} {input}

Returns:

Returns a condition code.

Arguments:

routine

The address of a routine to handle the output of help text. If 0, the service writes the data to sys$output. The routine takes one 64-bit address of a TSRB that contains a pointer to the article text.

width

The address of a 64-bit integer indicating the maximum line width of the output text. If not specified, or 0, the lines are limited based on the output device and the source text. If written to a target with no inherent width (such as a store file) the lines are limited to 80 characters.

path

The address of a TSRB that points to a help path. Generally this is simply the module name of the help text to display, but it can be used to provide a navigation path, with each item in the path indicating a module name, delimited by backslashes (\), which will allow the user to "back up".

If the value begins with an at-sign (@), the text following that is treated as a help library filename that will be used instead of the library argument. If Index or HELP is specified, the index module is used as the initial help text. If there is no Index module, the module displayed may be indeterminate.

library

The address of a TSRB structure that points to the name of the main help library.

flags

The address of a 64-bit integer containing processing flags:

Mnuemonic	Description
HLP_M_PROMPT	If not specified, an input routine must be specified to handle prompting the user.
HLP_M_PROCESS	The process symbol name table is searched for default help.
HLP_M_GROUP	The group symbol name table is searched for default help.
HLP_M_SYSTEM	The system symbol name table is searched for default help.
HLP_M_LIBLIST	A list of default libraries available is displayed for the user to choose from.

Multiple help libraries in addition to the main library can be used by defining HLP$LIBRARY, HLP$LIBRARY_1, HLP$LIBRARY_2, and so forth in the symbol tables, each symbol indicating a help library file name. These are used to resolve any anchor tags that refer to a module that is not in the main help library. If more than one of the HLP_M_PROCESS, HLP_M_GROUP, and/or HLP_M_SYSTEM flags are specified, searches are done in the order: process, group, system.

input

The address of a routine that is called when user input is needed. A 64-bit address is returned by the routine of a TSRB structure that points to the response text. If this is not specified or 0, HLP_M_PROMPT is required. If HLP_M_PROMPT is specified, this argument is ignored.

Description

LBR_Output_Help is used to display help text. A program can leave the entire processing of help to the service by providing no routine or input arguments and specifying HLP_M_PROMPT in the flags. LBR_INI_CONTROL, LBR_OPEN, and LBR_CLOSE are all handled internally.

In non-GUI settings, the default input will prompt the user differently depending on the situation. The default prompt for the user is "Topic?", though this can be changed by the input routine.

The user response to the prompt is handled this way:

User response	Behavior of LBR$OUTPUT_HELP
?	Displays an alphabetic list of all topics (module names) in the help library.
Ctrl-Z	Immediately exit interactive help session.
Enter	Return to previously viewed help module. If there are no previously viewed modules, exit the interactive help session.
name	Any other response is interpreted as a module name to display. If the specified module isn't found, an error is shown and the user is prompted again. The main library is searched first, then the other libraries are searched if the topic isn't found.

Condition Codes Returned:

Code	Meaning
LBR_ILLINROU	Input routine improperly specified or omitted.
LBR_NOHLPLIS	Error. No default help libraries can be opened.
LBR_INVPATH	Part of the path contains invalid characters.
SS_NORMAL	Successful completion.