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

    The LBR$GET_HELP routine retrieves help text from a help library,
    displaying it on SYS$OUTPUT or calling your routine for each
    record returned.

    Format

      LBR$GET_HELP  library_index [,line_width] [,routine] [,data]

                    [,key_1] [,key_2 . . . ,key_10]

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

 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.

 line_width

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference
    Width of the help text line. The line_width argument is the
    address of a longword containing the width of the listing line.
    If you do not supply a line width or if you specify 0, the line
    width defaults to 80 characters per line.

 routine

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Routine called for each line of text you want output. The routine
    argument is the address of the procedure value for this user-
    written routine.

    If you do not supply a routine argument, LBR$GET_HELP calls the
    Run-Time Library procedure LIB$PUT_OUTPUT to send the help text
    lines to the current output device (SYS$OUTPUT). However, if you
    want SYS$OUTPUT for your program to be a disk file rather than
    the terminal, you should supply a routine to output the text.

    If the user-written routine returns an error status with low bit
    clear, the LBR$GET_HELP routine passes this status to the caller.
    If the user-written routine returns a success status with low bit
    set, the LBR$GET_HELP routine returns 1 to the caller.

    The routine you specify is called with an argument list of four
    longwords:

    1. The first argument is the address of a string descriptor for
       the output line.

    2. The second argument is the address of an unsigned longword
       containing flag bits that describe the contents of the text
       being passed. The possible flags are as follows:

       HLP$M_          Specified help text cannot be found.
       NOHLPTXT
       HLP$M_          Text contains key names of the printed text.
       KEYNAMLIN
       HLP$M_          Text is part of the information provided on
       OTHERINFO       additional help available.

       Each programming language provides an appropriate mechanism
       for accessing these flags. Note that, if no flag bit is set,
       help text is passed.

    3. The third argument is the address stipulated in the data
       argument specified in the call to LBR$GET_HELP (or the address
       of a 0 constant if the data argument is zero or was omitted).

    4. The fourth argument is a longword containing the address of
       the current key level.

    The routine you specify must return with success or failure
    status. A failure status (low bit = 0) terminates the current
    call to LBR$GET_HELP.

 data

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Data passed to the routine specified in the routine argument. The
    data argument is the address of data for the routine. The address
    is passed to the routine specified in the routine argument. If
    you omit this argument or specify it as zero, then the argument
    passed in your routine will be the address of a zero constant.

 key_1,key_2, . . . ,key_10

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by descriptor
    Level of the help text to be output. Each key_1,key_2, . . . ,key_
    10 argument is the address of a descriptor pointing to the key
    for that level.

    If the key_1 descriptor is 0 or if it is not present, LBR$GET_
    HELP assumes that the key_1 name is HELP, and it ignores all the
    other keys. For key_2 through key_10, a descriptor address of 0,
    or a length of 0, or a string address of 0 terminates the list.

    The key argument may contain any of the following special
    character strings:

    String  Meaning

    *       Return all level 1 help text in the library.
    KEY . . .Return all help text associated with the specified key
            and its subkeys (valid for level 1 keys only).
    * . . . Return all help text in the library.

3 - Description

    LBR$GET_HELP returns all help text in the same format as the
    output returned by the DCL command HELP; that is, it indents two
    spaces for every key level of text displayed. (Because of this
    formatting, you may want to make your help messages shorter than
    80 characters, so they fit on one line on terminal screens with
    the width set to 80.) If you do not want the help text indented
    to the appropriate help level, you must supply your own routine
    to change the format.

    Note that most application programs use LBR$OUTPUT_HELP instead
    of LBR$GET_HELP.

4 - Condition Values Returned

    LBR$_ILLCTL        Specified library control index not valid.
    LBR$_LIBNOTOPN     Specified library not open.
    LBR$_NOTHLPLIB     Specified library not a help library.