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.
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:
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:
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.
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.
Help libraries have two names:
LIB
argument of the HLP_HELP call or following
“@” in the help source file.
It is the job of the user-supplied NAMETR routine to translate the first form into the second.
The call is as follows:
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:
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.
The example application TSTHLP works in the simplest way possible. Most real-life applications will be more sophisticated:
END=
feature of the READ
statement),
followed by simulation of multiple <CR>
responses and ignoring of lines supplied to the output routine, is one way to arrange this.
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:
The length of the MES
string should be at least 50 characters.
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:
On the Unix platforms:
(The above assumes that all Starlink directories have been added to the environment variables PATH
and LD_LIBRARY_PATH
as described in SUN/118.)