5 SOFTWARE SUPPORT GUIDE

This section is intended for support programmers and those interested in the internal workings of the HLP package. It is unlikely to interest application programmers or users.

5.1 Release Contents

The complete HLP system, for all platforms, is stored in a single VAX/VMS directory. The following files are included:

5.2 Portability Issues

The bulk of the system is coded in ANSI-standard Fortran. The only VAX extensions used are the SGP/16-sanctioned INCLUDE, DO WHILE, DO ... END DO and names longer than 6 characters. Full ANSI-compliance would be achieved by including the INCLUDEd text, recoding all the DOs and stripping the prefix “HLP_” from external names.

Specific machine dependencies are as follows. Filenames are given in their uppercase VAX/VMS forms, but are always lowercase on the Unix platforms.

• COMIC – Two versions of this INCLUDE file are supplied. COMIC.FOR is ANSI standard except that underscore, percent and backslash appear in character strings. COMIC.SUN4 has a double backslash to override the “escape” mechanism used by the Fortran compilers found on most Unix platforms.
• FOPR – Two versions are supplied. FOPR.VAX uses the OPEN keyword READONLY to avoid requiring write access to the help library; it is used on the VAX and the DECstation. The PC version uses the OPEN option MODE=’READ’ for the same purpose. The machine-independent version FOPR.IND uses a standard OPEN; this is the version used on the Sun.
• INSUB – Three versions are supplied. The VAX version INSUB.VAX uses the format descriptor $ to suppress the newline after the prompt, and begins each line with a blank to act as a printer control code. The PC version INSUB.PCM is similar, but uses the format descriptor $\setminus$ to suppress the newline. INSUB.SUN4, which works on both the Sun and DECstation, like the VAX version uses $, but does not output a blank. With the machine-independent version INSUB.IND, a newline (unavoidably) follows the prompt.
• CREHLP – Three versions are supplied. CREHLP.VAX is essentially VAX-only, and works in conjunction with the HLIB.COM command procedure. CREHLP.IND works on the PC and may work on other machines; however, it uses explicit I/O unit numbers, which may need to be changed. CREHLP.SUN4 works on the Sun and DECstations and may work on other Unix platforms; however, it uses explicit I/O unit numbers and also the filenames fort.1 and fort.2 (as required by the hlib script).
• LSTHLP – An explicit I/O unit number is used, which may need to be changed on some machines.
• OUTSUB – Two versions are supplied. OUTSUB.IND, which is used on VAX and PC, outputs a blank printer control code. OUTSUB.SUN4 doesn’t, and is used on the Sun and DECstation. In all versions, an explicit I/O unit number is used, which may need to be changed on some machines.
• TSTHLP – An explicit I/O unit number is used, which may need to be changed on some machines.
• UPCASE – The algorithm depends on ASCII coding, in that a–z is assumed to exist and be in the same collating order as A–Z.
• NAMETR – The routine supplied, HLP_NAMETR, either leaves the name unchanged or adds a prefix and suffix. Some other behaviour may be more approriate or convenient.

The VAX, Sun SPARCstation and DECstation versions of the HLP system are supported by the Starlink Project. Versions for other Unix platforms will be produced if and when they are needed and will also be Starlink-supported. The PC version is supported by the author.

5.3 Library Format

A help library file (as opposed to a help source file) consists of three regions:

(1)

The header region, a single record, gives the size of the file, in characters, as a decimal number in I12.12 format.

(2)

The index region, terminated by an empty record.

(3)

The data region, lines of help text interspersed with keyword records. The text region, and the whole file, are terminated by an empty record.

For a more detailed picture, it is best to look at an actual file, and one is listed below. It is the example help source file given in Section 3.1, translated into a help library with the HLIB procedure, and listed using the LSTHLP utility. The first column of the listing is the character address. All records are terminated with the chosen “EOS” character, conventionally the null CHAR(0).

The file begins with the header record, in this case giving the total length of the file as 1937 characters. The records at character 13, 67, … 348 are the index region of the file, terminated by the empty record at character 386. The records at character 387, 411, … 1912 are the data region of the file, terminated by the empty record at character 1936.

The various fields of each index record are separated by spaces. Each record begins with three pointers in I9.9 format. The first pointer indicates the position of the item in the data region of the file. The second pointer indicates the position of the next index entry down the branch of the help tree. The third pointer indicates the position of the next entry of the same level. In this simple library, which does not contain references to other libraries, the three pointers are followed by the level number and the keyword. Where the library refers to another, the name of the referred-to library, prefixed with an “@”, is included prior to the level number; an example of this is given later.

Where a help library includes references to other libraries, index entries like the following one appear:

The corresponding keyword entry in the data region of the file is normal in appearance except that there are no text records.

5.4 The INCLUDE files

The files helpic and comic (on the Unix platforms – HELPIC.FOR and COMIC.FOR on the VAX, HELPIC and COMIC on the PC) contain definitions and COMMON declarations. They are included through “INCLUDE ’helpic’” and “INCLUDE ’comic’” statements, the interpretation of which is machine-dependent. The comic INCLUDE is used only by the “HLP_COMSTR” routine and exists in different forms for different platforms.

5.5 Subprograms

This section is a classified summary of the subprograms which make up the HLP package. For more complete information, including argument data types and character string lengths, it will be necessary to refer to the source code itself.

5.5.1 Supported interfaces

The following three routines, plus the templates described in the next section, constitute the supported interface to the HLP package. Use of any other HLP_ routines, or of the COMMON blocks used by the HLP system, is at the programmer’s own risk.

HLP_ERRMES translates a HLP system error code J into a message string MES. See Section 4.6.

HLP_CREH translates a file of help source SOURCE, on I/O unit LUIN, into a help library LIB, subject to name translation by the routine NAMETR, on I/O unit LUOUT. Any error messages go to I/O unit LUERR. EOS is the end-of-string character, conventionally CHAR(0). JSTAT is the status. See Section 3.2.

HLP_HELP is the main interface between an application and the HLP system, and carries out a complete interactive help session. Full details are given in Section 4.1.

5.5.2 Templates

This implementation of the user-supplied name translation routine is suitable for use in a multiple-platform environment. It forms each filename by sandwiching the library name within a prefix and a suffix. HLP_NAMETR, or a user-supplied equivalent, is called by the HLP system prior to opening any help library, always with KMD=0. The library name to be translated is supplied in INSTR, and the filename is returned in OUTSTR ready for use in a Fortran OPEN statement. See Section 4.4 for further details of the HLP_NAMETR routine supplied, which uses other KMD values to set and enquire the prefix and suffix strings.

This is a simple example of the user-supplied input routine which is to be called by the HLP_HELP routine each time an interactive response is required. STRING is the response received. PROMPT is the prompt string, output before STRING is solicited. L is the length of STRING, excluding any trailing spaces. The function returns the value $+1$ to indicate success. Note that the order of the arguments does not comply with Starlink standards (see SGP/16), a consequence of maintaining a family-resemblance with VMS Help. See Section 4.3. As well as being a template, HLP_INSUB is used in the LSTHLP and TSTHLP programs.

This is a simple example of the user-supplied output routine which is to be called by the HLP_HELP routine each time a line of help text is to be output. STRING is the string to be output. The function returns the value $+1$ to indicate success. See Section 4.2. As well as being a template, HLP_OUTSUB is called in the LSTHLP and TSTHLP programs.

5.5.3 String handling

The following routines overlap in function with ones found in other Starlink packages, but are included in the HLP package for independence.

HLP_COMSTR compares two keywords for agreement, under the HLP package’s rules for abbreviation (see Section 2). FULSTR is the full keyword read from the HLP library; STR is the abbreviated string, including wildcards etc, supplied by the user. A .TRUE. response is returned if the two strings match.

HLP_DEC decodes a decimal integer NUM from a string STRING, starting at position IPTR. The pointer IPTR is incremented ready for the next call.

The HLP_LENGTH function returns the length of a string STRING excluding any trailing spaces. An all-blank string is length 1. The routine is optimized for speed in the case where the string is mostly trailing spaces.

HLP_SPLIT splits up a sentence into words. STRING consists of words separated by spaces. Starting at character position ISTART, this routine locates the beginning and end of the next word IFROM and ITO.

HLP_UPCASE converts a string STRING to uppercase, in place.

5.5.4 Variable-length random-access file package

help libraries are standard Fortran direct-access files, which have a fixed record length, on which the system implements a variable-length record scheme. The following routines manage these files. They communicate in part through labelled COMMON.

HLP_HCLOSE closes the current help library. JSTAT is the status return.

HLP_HDREAD performs a direct-access read from the current help library. IADR is the character address from which the read is to begin. STRING is the record that is found there, and NC its length. JSTAT is the status.

HLP_HDWRIT performs a direct-access write to the current help library. IADR is the character address from which the write is to begin. STRING is the record to be written. JSTAT is the status.

HLP_HINIT initializes the HLP system labelled COMMON blocks. LU is the I/O unit number to be used for accessing the help library file. FNAME is the initial help library name. EOS is the special character that will signify end-of-string, conventionally CHAR(0).

HLP_HOPENR opens or re-opens the current help library for reading, with the assistance of the library name to filename translation routine NAMETR. JSTAT is the status.

HLP_HOPENW opens the current help library for writing, with the assistance of the library name to filename translation routine NAMETR. NCHARS is the length of the file, which must be known before the call. JSTAT is the status.

5.5.5 Indexed-sequential package

The HLP system uses its variable-length direct-access file system, described above, to implement the indexed-sequential structure described in Section 5.3. The file has an index region and a data region. The index region contains three sets of pointers, to the data, to the next index entry down the branch, and the next index entry at the same level in the current branch.

HLP_HREADD performs a sequential-access read from the data region of the help library. The returned string STRING has length NC. JSTAT is the status.

HLP_HREADX reads the help library index, leaving the sequential-access addresses pointing to the indexed record. If it is necessary to translate a library name into a filename, the routine NAMETR will be called. NAVIG controls which track through the library is required – down the branch or along a level. STRING is the record input and NC its length. JSTAT is the status.

HLP_HSEEKX positions the index of the help library FNAME for a sequential access (using the HLP_HREADX routine) starting at character address IADRX. The caller also supplies LOGLEV, the logical level, which specifies the hierarchical level, on this occasion, of the help subtree contained in the library.

HLP_HTELLX inquires the help library’s current name, index address and logical level.

5.5.6 Internal

The following are highly specialized internal routines, with no significant potential use outside the HLP system (and which are in any case inaccessible to users of the shareable libraries on VMS). For further details, see the source code.

5.6 Rebuilding the System

On the VAX, the DCL command procedure CREATE.COM in the release directory rebuilds the object library, compiles and links the executable programs, generates the demonstration help library from source, and produces the Unix release. The latter consists of an archive file, a makefile, and a script mk which sets up environment variables and then runs make. For details about the targets supported, execute mk help.

5.7 VAX/VMS Logical Names

On VAX/VMS, in order to run applications using HLP the following logical names must be assigned:

In order to link a non-ADAM application with the shared library, the following additional assignment is required: