VMS Help LBR Routines, LBR$OUTPUT_HELP  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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]

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

2 - 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_        The process logical name table is searched for
    PROCESS       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_        The list of default libraries available is output
    LIBLIST       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).

3 - 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:

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

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

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

    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 Environment

    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          (1,2)  Same as above, except that the root
    [keyword[ . . . ]] 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.

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