5.1 Introduction
 5.2 Rules for programming ADAM applications

5.1 Introduction

Applications running under Starlink’s recommended software environment ADAM should in most respects be programmed according to the rules given so far. However, 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.

Programming standards for ADAM applications written outside Starlink may, of course, differ from those laid down by Starlink.

5.2 Rules for programming ADAM applications

Initialize variables !!! 65
It is essential that variables are initialized. Even the VAX’s initialization to 0 cannot be relied upon as the task may or may not be reloaded between invocations. DATA statements must only be used to initialize data which will not change. (Emphasizes rule 36.)

Use the ADAM standard prologue !! 66
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. For details, see SUN/105 and SUN/110. (Modification of rule 51.)

Output messages via the MSG_ routines !!! 67
Message output must be done using the ADAM message system MSG_ subroutines. The ADAM message system is described in SUN/104. A stand-alone version of the MSG_ package exists. (Supplements rule 18.)

Don’t use $, %, ^ in messages ! 68
The non-Fortran 77 characters $, % and ^ are used as escape characters in the ADAM message system, and special methods have to be employed if they are to be included in messages (see SUN/104). In general, it is better to avoid using them. (Reinforces rule 2.)

Report errors via the ERR_ routines !!! 69
Error reporting must be done using the ADAM error system ERR_ subroutines and the ADAM error strategy should be employed. The ADAM error system is described in SUN/104. A stand-alone version of the ERR_ package exists. (Reinforces rule 43.)

Set STATUS on failure !!! 70
All applications which fail must return to the environment with an error status value set. This is to enable the environment to detect the failure so that users can write procedures which take appropriate action. (Supplements rule 43.)

When setting STATUS, generate a message !! 71
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 (see SUN/104).

Some routines have > 6 character names. 72
Some of the ADAM environment package subroutines have names and prefixes greater than 6 characters. Where it is necessary to call these, rule 1 note 2 must be relaxed.

Get parameters with the PAR_ routines etc. !!! 73
All program parameters must be obtained using the parameter system PAR_ or pkg_ASSOC subroutines. (Reinforces and supplements rule 18.)

Use symbols when testing for bad pixels !!! 74
A REAL or DOUBLE PRECISION variable may be equated to its corresponding bad-pixel value, though explicit bad-pixel values, e.g.  32768, are banned. The parameters VAL__BADx (see SUN/39), where x corresponds to the data type, must be used. (Relaxation of rule 45 for this special case.)

Avoid Fortran input/output !!! 75
Use the environment facility packages MAG, FIO etc. wherever possible. (Reinforces rule 18.)

If it is necessary to use Fortran I/O, obtain and release logical unit numbers using FIO_GUNIT and FIO_PUNIT. (Supplements rule 19.)

Use symbolic names !!! 76
Status values and package constants are given symbolic names such as PAR__NULL and DAT__SZLOC by INCLUDE files for each package. These symbolic names should be used on every occasion that the constant is required. Follow these conventions when developing your own INCLUDE files, and use file names in the INCLUDE statements which conform to the convention fac_err for error codes and fac_par for other symbolic constants, where fac is the facility name. Further advice on INCLUDE statements can be found in Section 5, Writing Portable Programs.

RETURN is permissible when testing status. 77
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 preceeding the END statement. (Relaxation of rule 10.)

In generic routines use only the standard tokens !! 78
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.

PAR__ABORT status (!!) must abort the application !!! 79
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.