Processing math: 100%

4 RETRIEVING HELP TEXT

 4.1 The HLP_HELP Subprogram
 4.2 The Output Subprogram
 4.3 The Input Subprogram
 4.4 The Name Translation Subprogram
 4.5 Terminal Handling
 4.6 Error Codes
 4.7 Linking

Once a help library has been created, it can be interrogated by an application program through the HLP_HELP subprogram. The programmer supplies the following four things:

The HLP package includes a demonstration application TSTHLP.FOR, together with subprograms HLP_OUTSUB.FOR, HLP_INSUB.FOR and HLP_NAMETR.FOR.

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

Given:
OUTSUB EXTERNAL user-supplied output subroutine (note 2, below)
LOUT INTEGER maximum record length accepted by OUTSUB
INLINE CHARACTER*(*) string specifying required help text (note 3)
LU INTEGER I/O unit number for reading help library file
LIB CHARACTER*(*) name of help library file (note 4)
JFLAGS INTEGER flags (note 5)
INSUB EXTERNAL user-supplied interactive input routine (note 6)
NAMETR EXTERNAL user-supplied name translation routine (note 7)
Returned:
HLP_HELP INTEGER status: +1= OK
   11= illegal current level
   12= OUTSUB reported error
   13= INSUB reported error
   else = other errors (note 8)

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.

4.2 The Output Subprogram

The user-supplied output routine, which is named OUTSUB in the above example call to HLP_HELP but can have any name, is an integer function subprogram which accepts one argument, the string to be output, and returns a status of +1 if OK. The output routine is responsible for knowing where to write the information, how to handle pagination, and so on.

The HLP package contains a simple example of an output routine. It is called HLP_OUTSUB and is the one used in the TSTHLP demonstration program.

Note that there is no obligation for applications simply to display the lines of text retrieved by the help system. For example, information could be encoded into the help text which allows the application to plot graphs, log usage information, change the display colour etc.

4.3 The Input Subprogram

The user-supplied interactive input routine, which has the name INSUB in the above example call to HLP_HELP but which can have any name, is an integer function subprogram with arguments STRING, PROMPT, L. The argument STRING receives the line input, PROMPT is the string to output prior to reading the line, and L the number of characters input. If the call is successful, a function value of +1 is returned.

The HLP package contains a simple example of an input routine. It is called HLP_INSUB and is the one used in the TSTHLP demonstration program.

4.4 The Name Translation Subprogram

Help libraries have two names:

It is the job of the user-supplied NAMETR routine to translate the first form into the second.

The call is as follows:

  CALL nametr (KMD, INSTR, OUTSTR, JSTAT)

where the arguments are:

Given:
KMD CHARACTER*(*) function number (see below)
INSTR CHARACTER*(*) given string
Returned:
OUTSTR CHARACTER*(*) returned string
JSTAT INTEGER status: 0= OK
  16= a string had to be truncated
  17= other error

The function number KMD is always zero when the NAMETR routine is called by the HLP system, and means “INSTR is a help library name; translate it into a filename OUTSTR”. Non-zero KMD values are available to implementors for their own purposes.

The HLP package contains a suitable NAMETR routine, called HLP_NAMETR. The translation it provides is to enclose the supplied name within a prefix and suffix. This simple transformation adequately supports applications which must run on multiple platforms. The prefix and suffix are originally spaces, which HLP_NAMETR treats as meaning “no translation required”. The full set of options supported by HLP_NAMETR is as follows:

KMD INSTR OUTSTR action
  0 library name filename translate library name to filename
  1 prefix specify prefix
  2 suffix specify suffix
  3 prefix enquire prefix
  4 suffix enquire suffix

This is what the application must do:

          :
  *  Routines used by HLP_HELP
        EXTERNAL ...,hlp_NAMETR
          :
          :
  *  Define prefix and suffix for help name translations
        CALL HLP_NAMETR(1,PREFIX,DUMMY,J)
        IF (J.NE.0) ... error
        CALL HLP_NAMETR(2,SUFFIX,DUMMY,J)
        IF (J.NE.0) ... error
          :
          :
  *  Perform help session
        CALL HLP_HELP(...,HLP_NAMETR)
          :

An example prefix and suffix might be “/star/help/tpoint/” and “.shl” respectively. A library name “model” would then become the filename “/star/help/tpoint/model.shl”.

If this simple prefix+name+suffix model is not adequate, the programmer is free to supply his own translation routine, perhaps using environment variables or an internal table.

4.5 Terminal Handling

The example application TSTHLP works in the simplest way possible. Most real-life applications will be more sophisticated:

4.6 Error Codes

The HLP_CREH routine and all internal subprograms return status information through an integer argument using the following codes:

0= OK
1= Help system in wrong state
2= Help library error on OPEN
3= Help library error on WRITE
4= Help library error on READ
5= Help file error on CLOSE
6= Attempt to WRITE outside HELP library
7= Attempt to READ outside HELP library
8= Help record overflows supplied string
9= Help library creation failure
10= Unused
11= HLP_HELP internal error
12= Line output failure
13= Line input failure
14= Invalid index entry
15= Attempted switch to current library
16= String too small for file name
17= Name translation failed

HLP_HELP returns a function value of +1 rather than 0 to indicate success, for compatibility with the VMS HELP system. HLP_HELP may also return certain of the error values from the above list.

Most of these error conditions can only occur as a result of bugs in the HLP software. The most common one to arise during normal use is “HELP library error on OPEN” – for example where an incorrect library name has been supplied.

A status value J returned by the HLP routines may be translated into a message string MES by means of the HLP_ERRMES routine:

  CALL hlp_ERRMES(J,MES)

The length of the MES string should be at least 50 characters.

4.7 Linking

ADAM tasks will be linked with the HLP library automatically. Other applications which call HLP_HELP, HLP_ERRMES, HLP_CREH, or any other of the other public routines in the HLP package may be linked as follows.

On VAX/VMS:

  $ LINK program, HLP_LINK/OPT

On the Unix platforms:

  % f77 program.o -L/star/lib ‘hlp\_link‘ -o program.out

(The above assumes that all Starlink directories have been added to the environment variables PATH and LD_LIBRARY_PATH as described in SUN/118.)