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!
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:
It is essential that variables are initialised. Even the VAX’s initialisation to 0 cannot be relied on as the task may or may not be reloaded between invocations. DATA statements must only be used to initialise data which will not change.
ADAM standard prologues differ in some respects from the Starlink standard, allowing less freedom but giving more opportunity for the automatic production of documentation and help files. Standard prologues exist for subroutines and interface files.
Message output must be done using the ADAM Message system (MSG) subroutines.
The non-Fortran 77 characters $, % and are used as escape characters in the ADAM message system.
Error reporting must be done using the ADAM Error system (ERR) subroutines, and the ADAM Error Strategy should be employed.
All programs which fail must return to the environment with an error status value set. This enables the environment to detect the failure so that users can write procedures which take appropriate action.
If a subroutine is entered with STATUS=SAI__OK but, during execution, sets the STATUS (other than by calling another ADAM routine), an appropriate error message must be generated using ERR_REP.
Some of the ADAM environment package subroutines have names and prefixes greater than 6 characters. Where it is necessary to call these, the general rules must be relaxed.
All program parameters must be obtained using the Parameter system PAR or pkg_ASSOC subroutines.
A REAL or DOUBLE PRECISION variable may be equated to its corresponding bad-pixel value, though explicit bad-pixel values, e.g. -32767, are banned. The parameters VAL__BADx, where x corresponds to the data type, must be used.
Use the environment facility packages MAG, FIO etc. wherever possible. If it is necessary to use Fortran I/O, obtain and release logical unit numbers using FIO_GUNIT and FIO_PUNIT.
Status values and package constants are given symbolic names such as PAR__NULL by INCLUDE files for each package. These symbolic names should be used on every occasion that the constant is required.
The RETURN statement is allowed in the form:
as the first executable statement in a subroutine. This avoids an extra, unhelpful IF clause and indentation. Alternatively, use a GO TO n, where line n is a CONTINUE statement immediately preceding the END statement.
The preprocessor for generic routines supports special tokens used by the ASTERIX package (SUN/98), as well as ones for general use. Use only the standard tokens.
An application must terminate if the abort response (!!) is made when a parameter has been requested. Note that this rule does not mean that the application has to test for the abort status after every parameter is obtained; the inherited status will look after that. What matters is the appearance to the user of the application, who should:
An abort does not absolve the programmer from ensuring that the application closes down in an orderly fashion.
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.
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:
This software is currently available on VAX/VMS systems, Sun SPARC systems, and DEC systems running Ultrix/RISC (typically, DECstations).
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.
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:
As an example of a complete template, here is BLOCK.PRO (blank lines have been removed to save space):
This contains everything you might need, though many of the items will not always be needed.
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.
[SUN/73]
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.
[SUN/7]
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.
[SUN/99]
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.
[SUN/8]
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.
[SUN/63]
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.
[SUN/110]
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:
will add more material.
[SUN/105]
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.
[SUN/75]
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.