Chapter 12
Programming Standards, Conventions and Tools

 12.1 Language standards
  12.1.1 Fortran
  12.1.2 C
  12.1.3 Fortran/C interface
  12.1.4 Posix interface
 12.2 Prologue standards
 12.3 Software tools
  12.3.1 FORCHECK
  12.3.2 GENERIC
  12.3.3 LIBMAINT
  12.3.4 LIBX
  12.3.5 SPAG
  12.3.6 SST
  12.3.7 STARLSE
  12.3.8 TOOLPACK

The most striking features of the Starlink Software Collection are its size (in March 1990 it contained about 1 million lines of code, half a million comment lines, and another half million blank lines) and the number of programmers who have contributed to it. These are both its strength and its weakness. In particular, it presents a growing maintenance problem. The only hope of keeping it under control is by ‘keeping up standards’. This includes both the sense of ‘better’ rather than ‘worse’, and also ‘this is what BSI, ANSI, ISO …have to say on the subject’.

While nobody wants to stifle a programmer’s creativity, you have to recognise that software constructed using the guidelines discussed here is likely to be a great deal easier to maintain than that written as the spirit moves you. Software which is very personal to its creator is likely to suffer one of two fates: it will not be used by anyone else, or the original programmer will have the task of maintaining it for life.

Software portability has always been regarded by the Starlink Project as important, but has, in fact, been of marginal interest to the majority of users. Now, however, the spread of Starlink to Unix-based systems means that portability is a very real problem for a growing number of users.

The aim of these standards is to achieve software which, while providing the best possible applications, is also portable, maintainable by anyone, and integrates with the other software in the Collection. The software tools provided should make it easier to produce compliant code than not!

12.1 Language standards

12.1.1 Fortran

SGP/16 offers advice on how to write application programs for Starlink, embodied in a set of general rules. As a programmer you should bear in mind the needs of the person who will eventually be responsible for maintaining your code. You are strongly encouraged to read SGP/16 if you have not already done so.

ADAM has a number of special requirements which may mean that one of the general rules has to be reinterpreted — in some cases strengthened, in others relaxed. There are, in addition, several new rules which do not have to be obeyed when writing non-ADAM applications. Here is a summary of the extra rules which apply to ADAM applications, as compared with ordinary free-standing programs:

12.1.2 C

In spite of the first rule (use Fortran) in the Starlink Application Programming Standard, SGP/16, there is a Starlink C Programming Standard — SGP/4. Its general style and philosophy are very similar to the Fortran standard, though obviously many of the rules are only directly relevant to one of the languages.

The suggestions which it contains are made with maintainability, portability and efficiency in mind. Several of them are made because certain code constructs will have different effects in different C implementations. In some cases the ambiguity is resolved by the ANSI standard. However, it may be some time before all C implementations meet the standard, and in any case it is preferable to avoid code which suggests more than one possibility to the human reader.

12.1.3 Fortran/C interface

There are always problems when writing programs in a mixture of Fortran and C. Each vendor offers his own solution, but the problem for Starlink is to try to provide a portable solution. SGP/5 describes two packages to help with this problem:

— is a set of C macros to handle the Fortran/C subroutine linkage.
— is a set of C functions to handle the difference between Fortran and C character strings.

This software is currently available on VAX/VMS systems, Sun SPARC systems, and DEC systems running Ultrix/RISC (typically, DECstations).

12.1.4 Posix interface

You may need to use C simply to call one of its run-time library routines, to allocate memory for example. A Fortran library called PSX has been provided to enable you to avoid doing this (see SUN/121). In many programs, it will remove the need to write any C code at all.

PSX allows you to use the functions provided by the Posix and X/Open libraries.

12.2 Prologue standards

Starlink has defined a number of standard prologues as a starting point for programming. They are important because they provide a minimal level of source-code documentation, and they can also be processed into on-line and off-line documentation by software tools. These prologues are normally accessed through STARLSE (see Section 12.3). However, they are also available as files which you can edit. These can be found in STARLSE_DIR in files with the following names:

— A-task template.
— subroutine template.
— function template.
— block data routine template.
— monolith template.
— interface file template.

As an example of a complete template, here is BLOCK.PRO (blank lines have been removed to save space):

      BLOCK DATA {routine_name}  
*  Name:  
*     {routine_name}  
*  Purpose:  
*     {routine_purpose}  
*  Language:  
*     {routine_language}  
*  Type of Module:  
*     BLOCK DATA  
*  Description:  
*     {routine_description}  
*  Notes:  
*     {routine_notes}...  
*  Side Effects:  
*     {routine_side_effects}...  
*  Implementation Deficiencies:  
*     {routine_deficiencies}...  
*  {machine}-specific features used:  
*     {routine_machine_specifics}...  
*  {DIY_prologue_heading}:  
*     {DIY_prologue_text}  
*  References:  
*     {routine_references}...  
*  Keywords:  
*     {routine_keywords}...  
*  Copyright:  
*     {routine_copyright}  
*  Authors:  
*     {author_identifier}: {authors_name} ({affiliation})  
*     {enter_new_authors_here}  
*  History:  
*     {date} ({author_identifier}):  
*        Original version.  
*     {enter_changes_here}  
*  Bugs:  
*     {note_any_bugs_here}  
*  Type Definitions:  
      IMPLICIT NONE              ! No implicit typing  
*  Global Constants:  
      INCLUDE ’{global_constants_file}’ ! [global_constants_description]  
*  Global Variables:  
      INCLUDE ’{global_variables_file}’ ! [global_variables_description]  
*        {global_name}[dimensions] = {data_type} ({global_access_mode})  
*           [global_variable_purpose]  
*  Local Constants:  
      {data_type} {constant_name} ! [constant_description]  
      PARAMETER ( {constant_name} = {cons} )  
*  Local Variables:  
      {data_type} {name}[dimensions] ! [local_variable_description]  
*  Global Data:  
      DATA {data_elm} / {data_values}... /  

This contains everything you might need, though many of the items will not always be needed.

12.3 Software tools

Software tools are programs which help you write programs. Of the ones described below, STARLSE and SST are specific to ADAM programs. The others can be used for any type of program.



A Fortran verifier and programming aid installed on the Starlink central facilities computer (STADAT). It checks code for conformance to the ANSI standard X3.9–1978. However, it can also deal with non-standard code and by default accepts VAX Fortran. It:

Automatically composed documentation of this type is an invaluable addition to system documentation. As often as not, it is the only reliable source of information about old programs.

12.3.2 GENERIC


Preprocesses a generic Fortran subroutine — one written so as to apply to several different data types — into one routine per data type, and concatenates them into a file. This can then be compiled to produce an object module.



Simplifies the maintenance of software held as modules in a source/object library pair, and of modules in a Help library. New libraries can be created and modules inserted, extracted, replaced, examined, and printed with simple commands. It ensures that corresponding modules within a source/object library pair do not get out of step with one another, and it can optimise the disk space used by libraries.

12.3.4 LIBX


Contains two tools for use with libraries. The first outputs a list of all modules in a library, and is useful for building more elaborate utility procedures. The second extracts preamble comments from all the modules in a Fortran source library.

To some extent they duplicate facilities in LIBMAINT. The latter is a very powerful system but, unavoidably, is vulnerable to changes in the formats of the reports which the DEC Librarian utility produces. The LIBX facilities, though limited in what they do, use only published interfaces and should survive new VMS releases; they are also fast.

12.3.5 SPAG


SPAG stands for ‘Spaghetti Unscrambler’. It re-orders blocks of Fortran statements in such a way that the structure of the code is improved, while remaining logically equivalent to the original program. The result improves the readability and maintainability of badly-written Fortran programs. On Starlink, it may be used to convert unstructured Fortran 77 into the structured and indented VAX Fortran required by the Starlink Programming Standard. It can also be used to update Fortran 66 code. It is marketed by Polyhedron Software and is available only on the Starlink central facilities machine, STADAT.

12.3.6 SST


The Simple Software Tools package was described in Chapter 4. However, its importance can best be appreciated when programming. In particular, three of the tools — PROHLP, PROLAT, and PROPAK — process prologues in useful ways:

— converts prologues into on-line Help text. Suppose you have source code in file PROG.FOR and you are building up the Help library MYLIB.HLB, then:


will add more material.

— converts prologues to LATEX form, which can be used as either a stand-alone document, or incorporated into another document.
— converts prologues from the code of a subroutine package into a form that STARLSE can use. STARLSE can be ‘taught’ about a subroutine library, so that simply typing the name of a routine (or just the first few characters) followed by ctrl/E will expand it into either a list of routines (if the string entered is not unique), or into a call to that routine ready for its arguments to be filled in. This removes a common source of error.

12.3.7 STARLSE


This is a ‘Starlink Sensitive’ editor based on the VAX Language Sensitive Editor LSE. It helps you write portable Fortran 77 software in a standard Starlink style.

If you normally use a standard screen editor (like EDT), you will probably find that using an LSE-based editor for the first time will slow you down considerably. All those new keys to remember! However, once you get used to it, you will start to realise how much time you used to spend doing simple things like moving the cursor, formatting prologues, indenting lines of code and going to fetch essential documentation — all things which STARLSE can do far more efficiently.

One of the strengths of LSE-based editing is that it allows you to pick and choose — to use the features that you personally find time-saving, while still being able to type directly over anything which you find too fussy. In this respect, STARLSE can be regarded as a sort of interactive ‘Manual of Style’ which provides guidelines on layout and programming standards when you need reminding of them, but lets you work unhindered once you know what you are doing.

Perhaps the most important component of STARLSE is a version of the Fortran 77 programming language called STARLINK_FORTRAN, which defines the style of programming that the editor supports. This language is used by default for files of type .FOR and .GEN.

The language is based on the Starlink Application Programming Standard and contains only a small number of approved extensions to Fortran 77. It is therefore much simpler and easier to use than the VAX Fortran language which comes with ‘native’ LSE (in fact, nearly 80% of VAX Fortran consists of extensions to the Fortran 77 standard!). In STARLINK_FORTRAN, the number of available options and ambiguous abbreviations is greatly reduced, and most of the common language constructs can be produced simply by typing a short token, like ‘DO’ or ‘IF’, followed by ctrl-E.

The most important features of the language are:

For further information, refer to SUN/105 and the DEC LSE User Guide and Reference Manual.



Toolpack/1 (release 2) is a suite of software tools designed to support the Fortran programmer. In this context, a ‘software tool’ is a utility program to assist in the various phases of constructing, analysing, testing, adapting, or maintaining a body of Fortran software. Typically, the input to such a tool is your Fortran source code. The tool processes this and produces output that may have one or both of the following forms:

In some cases the input may be test data, documentation, or a report generated by a previously applied tool. Tools that assist directly in preparing documents are usually called documentation generation aids. These and other tools serving utility functions all have an important role to play and so, even if they do not process a program directly, they are still regarded as programming aids.

Further examples of the software tools provided include:

If you want to know more about TOOLPACK, read the ‘Introductory Guide’ available from your Site Manager.