Processing math: 100%
5 THE ADAM SOFTWARE ENVIRONMENT
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:
IF (STATUS.NE.SAI__OK) RETURN
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:
- not be re-prompted for the parameter,
- not be prompted for further parameters, and
- not receive additional error messages merely because the status was not OK.
An abort does not absolve the programmer from ensuring that the application closes down in an
orderly fashion.