
Next: The Output Subprogram
Up: RETRIEVING HELP TEXT
Previous: RETRIEVING HELP TEXT
The HLP_HELP routine takes a line of text containing commands
or keywords and enters an interactive help session, using supplied
application-specific routines to obtain further command and keyword
input and to handle retrieved text. Once the help session is complete,
control passes back to the calling program.
The usual way to generate the initial line of input will be to
interpret the application's own help command and to present the
arguments appropriately formatted. For example, the application may
respond to a command "HELP COMP C" by calling HLP_HELP with
"COMP C" as the initial response string. The HLP_HELP routine
will then search for the subtopic "C" of topic "COMP",
hand back to the application any text it finds, request further lines
of input, and allow the user to explore the help tree before finally
terminating and returning to the application.
The response strings accepted at each stage are given in
Section 2.
The HLP_HELP routine is an integer function subprogram, which
returns the number +1 to indicate successful completion and a
range of negative integers to indicate various error conditions
(see Section 4.6). The call is as follows:
ISTAT = HLP_HELP (OUTSUB, LOUT, INLINE, LU, LIB, JFLAGS, INSUB, NAMETR)
where the arguments are:

Notes:
- This routine is similar, but not identical, in its argument list
and action to the VAX/VMS routine LBR$OUTPUT_HELP.
- The user-supplied OUTSUB routine is responsible for
knowing where to
write the information, how to handle pagination, and so on. Details
are given in Section 4.2, below.
- The INLINE string contains the initial series of help keywords,
separated by spaces. The interactive help session will begin at the
place in the help tree so specified. INLINE may contain leading as well as
embedded and trailing spaces. The command itself, for example
"HELP", is not included in this string, nor any command
qualifiers which the application supports. A maximum of 9 keywords is
accepted; any more are ignored. Keywords longer than 64 characters
are truncated.
- The help library specified by LIB is in a special format, produced by
the HLP_CREH routine
(as described in Section 3.2). The system is not compatible with
VMS .HLB files, though the source form of the library is very
similar (see Section 3.1). The name is subject to environment-dependent
translation at open time through the NAMETR routine (see
section 4.4).
- At present, JFLAGS controls only one option, though more
may be added in the future. JFLAGS=1 means that
interactive help prompting is in effect, while JFLAGS=0
value means that the help text for the topic specified in
INLINE is looked up but no interactive dialogue ensues.
- The user-supplied INSUB routine is responsible for
carrying out a prompted read from the interactive command device.
Details are given in Section 4.3, below. (Note that if JFLAGS=0
INSUB is never called.)
- The user-supplied NAMETR routine is responsible for translating
a help library name into a filename. Details are given in Section 4.4,
below.
- The status values returned by this routine may be translated into
text by means of the routine HLP_ERRMES. See Section 4.6.

Next: The Output Subprogram
Up: RETRIEVING HELP TEXT
Previous: RETRIEVING HELP TEXT
HLP --- Interactive Help System
Starlink User Note 124
P. T. Wallace
13th June 1995
E-mail:ptw@star.rl.ac.uk