1 INTRODUCTION

This document describes version 1.0 of the PRIMDAT package, which is a collection of Fortran functions and subroutines providing support for “primitive data processing”. Routines from this package may be used to perform arithmetic, mathematical operations, type conversion and inter-comparison of any of the primitive numerical data types supported by the Starlink Hierarchical Data System HDS (SUN/92).

It provides:

• Processing facilities which are not normally available.
  This package provides processing facilities for all the numerical HDS data types. In contrast, standard Fortran 77 only supports the _INTEGER, _REAL and _DOUBLE numerical types and even in VAX Fortran there are no operators for the unsigned types _UWORD and _UBYTE (those for _BYTE are also somewhat restricted).
• A uniform interface.
  A consistent naming scheme is used which facilitates the production of generic routines for processing data of any numerical type (SUN/7 describes the GENERIC compiler and contains further information on this subject).
• Improved portability and efficiency.
  By using this package, applications can process non-standard data types while making minimum explicit use of non-standard Fortran statements. In addition, PRIMDAT routines can exploit machine-specific features to enhance the efficiency of primitive data processing, so applications may take advantage of these features without compromising their own portability.
• Facilities for processing bad data.
  The bad values defined by Starlink for flagging undefined data may be processed and consistently propagated. Recognition of these bad values may easily be disabled when not required in order to save processing time.
• Handling of numerical errors.
  Numerical errors (such as division by zero or numerical overflow) may be handled automatically and converted into appropriate bad values for subsequent recognition. Error codes are returned to allow such occurrences to be reported, or recovery action taken, as desired.
• A set of constants.
  A set of machine-specific symbolic constants is provided to support the processing facilities in this package and to simplify the task of transporting software to other machines which may have different arithmetic capabilities.

Note that only the numerical HDS data types (_BYTE, _UBYTE, _WORD, _UWORD, _INTEGER, _REAL & _DOUBLE) are supported at present. There is currently no provision for the non-numerical _LOGICAL and _CHAR types, nor for any other Fortran (or VAX Fortran) types such as COMPLEX. The CHR facility should be used for processing character data and for converting between character and numerical data types.

Note added March 2004: This manual refers throughout to VAX floats. The package was ported to Unix in 1991, and accordingly most of the values now defined by it are those appropriate for IEEE floats instead; the manual has not been updated to match.

1.1 The VAL, VEC and NUM Facilities

The routines in this package have names of the form $<$fac$>$_$<$name$>$, where $<$fac$>$ is a three character facility name and $<$name$>$ specifies the operation which the routine performs.

The routines are divided into three facilities as follows:

Note that a distinction is drawn between three classes of primitive data, which differ in their interpretation and in the algorithms best suited to processing them:

• Values (VAL facility) are scalar data which may take one of the Starlink-defined bad values (sometimes called “magic” values), whose presence signifies that the affected datum is undefined. Numerical errors which occur while processing values will result in the generation of a bad value as a result. Subsequent recognition of bad values on input may (or may not) occur, depending on the logical setting of the BAD routine argument (section 1.2).
• Vectorised arrays (VEC facility) are 1-dimensional arrays of values (or arrays treated as 1-dimensional) whose elements are processed in the way described above. The routines provided are optimised to perform processing in an efficient manner when the size of the array is large.
• Numbers (NUM facility) are always interpreted literally as scalar numerical quantities (i.e. bad values are not recognised on input and are not explicitly generated on output). Numerical errors which occur while processing numbers will cause the application to terminate (i.e. crash).

Italics are used throughout this document to refer to values, vectorised arrays and numbers when it is important to emphasise the particular meaning (and the implied processing rules) described here.

1.2 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:

where $<$T$>$ is one of the data type codes in Table 1 (also see section 5.1). 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.

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 2.2 & 3.2). 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 A).

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.

1.3 The STATUS Argument

Each VAL_ and VEC_ routine takes a standard integer STATUS variable as its final argument. In normal use, this STATUS variable should be set to SAI__OK when the routine is invoked, otherwise it will return immediately without action.³

On exit, the STATUS value will still be set to SAI__OK unless a numerical error has occurred, in which case it will be set to an appropriate error code (Appendix B). PRIMDAT error codes may be tested to detect when a particular numerical error has occurred, and may also be used to report these errors (using the ADAM ERR_ routines for instance).

Note that routines in this package do not report errors themselves. This is partly an efficiency consideration. In many circumstances, the automatic generation of a bad value will itself be an adequate response to a numerical error and, in such cases, the STATUS variable may simply be reset to SAI__OK and processing can continue.