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.