3 OVERVIEW OF SST APPLICATIONS

 3.1 Producing LATEXDocumentation (PROLAT)
 3.2 Producing Help Libraries (PROHLP)
 3.3 Producing STARLSE Package Definitions (PROPAK)
 3.4 Converting “Old-Style” ADAM/SSE Prologues (PROCVT)
 3.5 Producing Source-Code Statistics (FORSTATS)

3.1 Producing LATEX Documentation (PROLAT)

The SST application PROLAT is provided to facilitate the production of documentation for packages of applications and subroutine libraries. It works by extracting the necessary information from “prologues” (i.e. header comments) within the source-code files which comprise the software, and formatting this information into a LATEX document. The documentation in Appendix A, for example, has been produced by this means.

For PROLAT to work correctly, the prologue information must use the layout generated by the extended Language Sensitive Editor STARLSE (SUN/105), with which a number of the SST applications are designed to integrate. It is also possible to convert some older ADAM/SSE prologue layouts into the required form automatically if required (see §3.4 for details).

To use PROLAT, you should supply a file containing prologue information in the correct format as input, and the resulting output will then be a LATEX document describing the software in the input file (by default this is assumed to be an ADAM application program, otherwise known as an A-task). The document will be written to a file (prolat.tex by default) which can then be processed directly with the LATEX command.

For example, if an application with suitable prologue information resides in the file PROG.FOR, then the following sequence of commands would extract this information and send the derived document to a Canon laser printer:

  ICL> PROLAT PROG.FOR
  ICL> SPAWN LATEX PROLAT
  ICL> $DVICAN PROLAT
  ICL> $PRCN PROLAT.DVI-CAN

When working from ICL, notice how ‘SPAWN’ must be used in front of the LATEX command. This is to overcome problems with the way LATEX writes to the terminal, which can cause ICL to “hang” if a $LATEX command is issued directly. The last three commands are, of course, simply the standard processing sequence for sending a LATEX source file to a Starlink laser printer (see SUN/9, SUN/12 & SUN/34 for further details of LATEX). The entire operation could also be performed from DCL directly.

As with most SST applications, a “wild card” input file may be specified in order to combine a number of program descriptions into a single document. Thus, the following command could be used to document an entire software system if the necessary files resided in the current directory:

  ICL> PROLAT *.FOR

PROLAT has a number of options to tailor its behaviour. For instance, you can specify that you are processing information about a subroutine library (rather than application programs) so as to produce a slightly different documentation format. You can also specify that you want only the descriptive part of the document without any LATEX declarations. This latter option is useful if you are adding the information to a larger document which already contains all the necessary LATEX commands (e.g. as an appendix, such as in the present document).

Note that PROLAT does not attempt to provide a sophisticated text-processing language and does not, therefore, exploit all the layout facilities which LATEX has to offer. Instead, it is simply intended for achieving a close approximation to the final form of a document as quickly and easily as possible. If you want to go further and use fancy LATEX fonts or an extravagant layout in your final document, then you should be prepared to edit the output file from PROLAT to achieve this. By adopting this approach, the prologue layout can be kept relatively simple, so that it can function as the source for other types of documentation (see below), as well as for possible future documentation formats yet to be invented.

3.2 Producing Help Libraries (PROHLP)

The SST application PROHLP functions in a rather similar way to PROLAT (above), except that its output format is not LATEX, but a text file designed for insertion into a help library. By using PROHLP you can therefore make program and subroutine documentation available on-line, as well as simply on paper.

The help file format produced by PROHLP is designed to integrate both with the ADAM help system and also with the STARLSE editor. This means that it is easy to make prologue information available to the person running a program, and also to make subroutine information available to someone using STARLSE (see §3.3 for details of the latter). As before, the initial prologue information must be in the form generated by STARLSE.

To give an example, suppose you have an ADAM application program (an A-task) in the file PROG.FOR, along with suitable prologue information, and you want to make this information available in a help library so that it can be accessed when the program is run. The first step would be to create the library (if you have not already done so), as follows:

  ICL> $LIBRARY/CREATE/HELP MYLIB.HLB

The prologue information is then extracted using PROHLP which, by default, writes it to the file PROHLP.HLP:

  ICL> PROHLP PROG.FOR

The extracted information can then be inserted into the library and the intermediate help file deleted:

  ICL> $LIBRARY/HELP MYLIB.HLB PROHLP.HLP
  ICL> $DELETE PROHLP.HLP;*

You can check that the help library contains the correct information by using the DCL command $HELP with the /LIBRARY qualifier.

This help information can be made available to the application program via the ADAM help system. To do this, the interface (.IFL) file for the application should contain references to the appropriate entries in the help library. Thus, at the start of the interface file, before any parameter definitions, there should be a line such as:

  helplib ’MYDISK::[ME.PROGS]MYLIB’

which identifies the help library to be used. Note that a full directory specification is needed (or an equivalent logical name). Each of the application’s parameters for which help information is available should also have a line in its interface file entry such as:

  helpkey *

where ‘’ specifies that a default set of keywords should be used to access the parameter information in the help library. The library structure which results from using PROHLP is compatible with this set of defaults.

3.3 Producing STARLSE Package Definitions (PROPAK)

If you have developed a subroutine library using STARLSE, with prologue information in the correct form, then the SST application PROPAK can be used to generate an LSE package definition to facilitate future use of the library from within the STARLSE editor. This package definition will define LSE templates for each of the routines in the library. It can then be used to make these templates available within the editor, in the same way that the standard ADAM-subroutine templates are provided within STARLSE.

A package definition can be generated by providing the appropriate source code files (containing prologue information) as input to PROPAK, for instance:

  ICL> PROPAK *.FOR PACK=XYZ

Note that a value for the PACK parameter (the name of the package to be produced) must also be given. It will be prompted for if not supplied on the command line.

By default, the output package definition is written to the file PROPAK.LSE, which can then be used to extend your STARLSE editing environment. To do this, the file should be read into an editing buffer and the LSE command ‘DO’ executed to compile the definition. If you then move to a buffer with a file type of ‘.FOR’ or ‘.GEN’, the routine templates you have just defined will become available for use. Note that LSE allows you to save an extended editing context for future use so that you do not have to repeat this compilation process each time (although the resulting files can be rather large). For details of how to do this the VAXset documentation for LSE should be consulted. Accessing help libraries.  An important feature of PROPAK is its ability to make a package definition refer to a matching help library produced from the same source files using PROHLP. To do so, the HELP parameter should be used with the PROPAK command to specify the (full) name of the help library to which the package should refer. Help library references will then be inserted into the package definition and the associated help information will become available from within STARLSE when the definition is compiled. (To access help on a particular routine, the cursor is placed on the routine name in the editing buffer and the help key GOLD PF2 is used.) Note that the ATASK parameter should be set to FALSE when using PROHLP for this purpose in order to obtain a help library suitable for a subroutine library, rather than a package of applications programs.

3.4 Converting “Old-Style” ADAM/SSE Prologues (PROCVT)

A considerable amount of ADAM software already in existence uses an “old-style” prologue layout based on templates held in the ADAM_PRO directory. Since there has never been a fully satisfactory method of converting such prologue information into documentation, it is doubtful whether many of these older prologues are of a high enough quality to be used for this purpose now. Nevertheless, in a spirit of optimism, the SST application PROCVT has been provided to permit the conversion of these old-style prologues into the new (STARLSE) form required by other SST applications. PROCVT can also be used as a useful first step in upgrading an old-style prologue, even if the information it contains also needs attention before it becomes suitable for documentation purposes.

Normally, PROCVT will be used with both an input and an output file specified, for instance:

  ICL> PROCVT OLD.FOR NEW.FOR

This command will convert the old-style prologue held in the file OLD.FOR into STARLSE format and will write it (together with all the associated source code) to the file NEW.FOR. Be careful not to use PROCVT on a file which already has a suitable prologue layout – you will not be pleased with the result!

Note that perfect results cannot always be expected with PROCVT unless the original old-style prologue template has been followed very carefully. Consequently, it may sometimes be necessary to use STARLSE afterwards to make fine adjustments before adequate documentation can be produced using other SST commands. To facilitate this, PROCVT will insert appropriate STARLSE placeholders into the output file wherever information is missing.

3.5 Producing Source-Code Statistics (FORSTATS)

The SST application FORSTATS is provided as a “quick look” method of inspecting large Fortran 77 software systems, with the aim of assessing the volume of code present and its likely quality. These two factors (code volume and quality) are usually the most important indicators of the amount of work needed to maintain, or change, an existing software package, especially if you are not initially familiar with it.

Counting lines of code is obviously a simple method of measuring software volume, but the measurement of quality is more difficult and subjective. The approach used by FORSTATS depends on the observation that if corners are cut during code development, then the first and most obvious sign (at least on Starlink) is usually the omission of in-code comments and prologue information. Past experience with Starlink software has shown that there is an important correlation between the ease of understanding and supporting a large software package and the overall level of commenting which its original author has provided.

FORSTATS attempts to quantify this by producing a number of simple statistics. These are based on line and character counts derived from the code and comments in each program unit of a Fortran 77 software system. It compares these statistics with a set of expected values, which have been derived experimentally from existing Starlink software, and flags values which lie outside the expected range.

When developing software, FORSTATS can be used to highlight those areas where more attention to in-code commentary would be useful to assist future support programmers. Conversely, when inheriting an existing software package, FORSTATS can be used as an aid to identifying possible problem areas before planning changes, etc. In a large software system, it can also be invaluable simply for listing the program units present and indicating their size.

To run FORSTATS on a software system contained in a set of ‘.FOR’ files, you might use the command:

  ICL> FORSTATS *.FOR

This command will analyse the specified files and write a statistics file (FORSTATS.LIS by default), which can then be printed. When it is first run, FORSTATS will append an explanatory key to the statistics file to help you interpret its contents. You can suppress this key in future by specifying ‘NOKEY’ on the command line.