next up previous
Next: The Output Subprogram
Up: RETRIEVING HELP TEXT
Previous: RETRIEVING HELP TEXT

The HLP_HELP Subprogram

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:

  1. This routine is similar, but not identical, in its argument list and action to the VAX/VMS routine LBR$OUTPUT_HELP.
  2. 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.
  3. 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.
  4. 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).
  5. 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.
  6. 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.)
  7. The user-supplied NAMETR routine is responsible for translating a help library name into a filename. Details are given in Section 4.4, below.
  8. The status values returned by this routine may be translated into text by means of the routine HLP_ERRMES. See Section 4.6.


next up previous
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