Propagation of Bad Data

The handling of numerical errors by the VAL_ and VEC_ routines¹ depends on the generation, recognition and propagation of bad values in the data, and also on the presence of an integer STATUS argument carried by each routine.

Bad values are a set of special numerical constants (one for each data type) which are defined by Starlink to be used for flagging ``bad'' or ``undefined'' data. The philosophy and conventions surrounding their use are described in SGP/38. The Starlink ``bad constants'' which specify these values have symbolic names²of the form:

VAL__BAD$<$T$>$

where $<$T$>$ is one of the data type codes in Table  (also see section ). Bad values may be set explicitly by assigning the value of one of these constants to a variable. They are also set by VAL_ and VEC_ routines when numerical errors occur -- implying that the result of the attempted operation is undefined.

Table: The data type codes used in constants and routine names, and the HDS and VAX Fortran types to which they correspond.

Type Code $<$T$>$	HDS Type		Fortran Type
UB	_UBYTE	(unsigned byte)	BYTE
B	_BYTE	(byte)	BYTE
UW	_UWORD	(unsigned word)	INTEGER$*$2
W	_WORD	(word)	INTEGER$*$2
I	_INTEGER	(integer)	INTEGER
R	_REAL	(real)	REAL
D	_DOUBLE	(double precision)	DOUBLE PRECISION

Recognition of bad values involves comparing them for equality with the appropriate ``bad constant'', and may be used to control subsequent processing. Most frequently, this control takes the form of ``propagation'' -- i.e. the outcome of any operation attempted on a bad operand is itself bad; so that the bad value is ``propagated'' to the result. After a sequence of such operations, the resulting bad values make it possible to identify all those results which have been rendered invalid by errors occurring en route.

The VAL_ and VEC_ routines have the ability to recognise and propagate bad values in this manner (the precise processing rules are described in sections  & ). In some circumstances, however, appreciable amounts of processing time can be saved if it is known in advance that bad values are not present and that their recognition is not necessary. Also, it is occasionally necessary to disable bad value recognition so that the numerical values specified by the ``bad constants'' may themselves be processed as if they were valid data.

Because of this, recognition and propagation of bad values by the VAL_ and VEC_ routines is controlled by a logical value BAD, which appears at the start of each routine's argument list. If BAD is set .TRUE., then bad input arguments are recognised and propagated to the result. Conversely, if BAD is set .FALSE., then input argument values are interpreted literally (there is no bad value recognition), although bad values may still be generated on output if numerical errors occur. Most of the routines execute more efficiently if BAD is .FALSE. (Appendix ).

It is up to the calling routine to ensure that the BAD argument has an appropriate logical value when VAL_ and VEC_ routines are invoked. This value will often depend on whether numerical errors have occurred in previous stages of processing, so each routine also carries a STATUS argument which may be used to detect the occurrence of such errors.