5 CONSTANTS

 5.1 Bad Data Values
 5.2 Machine Precision
 5.3 Maximum Data Values
 5.4 Minimum Data Values
 5.5 Data Storage Requirements
 5.6 Smallest Value
 5.7 Character String Sizes

This section describes a set of constants which support the processing facilities in this package by specifying machine-specific quantities associated with each data type. These constants are identified by symbolic names which are defined (using Fortran PARAMETER statements) in the file PRM_PAR. The definitions may be incorporated into an application with the statement:

  INCLUDE ’PRM_PAR’

Here, as elsewhere in this package, a distinction is drawn between values (which may be flagged as bad) and numbers (which are always interpreted literally). The constants accordingly have names with one of the two forms:

  VAL__<const><T>

or

  NUM__<const><T>

where <T > is one of the type codes in Table 1 and <const > specifies the quantity which the constant represents. In most cases, the two forms of the constant are necessarily identical and only the VAL__ form is provided.

The constants are also available in the C include file prm_par.h.

Note that many of these constants may need to change if transported to another machine.4 When writing software which is intended to be portable you should therefore:

A summary of the constants available is given in Table 5. The following sections describe them in more detail.





Constant Type

Quantity represented




VAL__BAD <T > * <T >

Bad value, used for flagging undefined data.

VAL__EPS <T > <T >

Machine precision.

VAL__MAX <T > <T >

Maximum (most positive) non-bad value.

NUM__MAX <T > <T >

Maximum (most positive) number.

VAL__MIN <T > <T >

Minimum (most negative) non-bad value.

NUM__MIN <T > <T >

Minimum (most negative) number.

VAL__NB <T > _INTEGER

Number of basic machine units (bytes) used by a value.

VAL__SML <T > <T >

Smallest positive (non-zero) value.

VAL__SZ <T > _INTEGER

Number of characters required to format a value as a decimal string.




*Type= <T > indicates that the constant’s data type matches the type code <T >.




Table 5: A summary of the constants available, showing their data types and the quantities they represent.

5.1 Bad Data Values

Constants with names of the form VAL__BAD <T > represent the Starlink-defined bad (or “magic”) values to be used for flagging bad or undefined data. The use of these constants is discussed in SGP/38, which also defines the values to be used on VAX machines. These are:





Constant
Type
Value
Hexadecimal Pattern




VAL__BADUB _UBYTE 255 FF
VAL__BADB _BYTE −128 80
VAL__BADUW _UWORD 65535 FFFF
VAL__BADW _WORD −32768 8000
VAL__BADI _INTEGER −2147483648 80000000
VAL__BADR _REAL −1.7014117E+38 FFFFFFFF
VAL__BADD _DOUBLE −1.701411834604923D+38 FFFFFFFFFFFFFFFF




Note that the operations permitted on bad values are restricted to:

Software which aims to be portable may assume that the bad values described by these constants will always lie at the extreme end of the number range which can be represented by each data type. However, no assumptions should be made about which end of the range (upper or lower) this will be — an explicit test should be made if it is necessary to determine this.

5.2 Machine Precision

Constants with names of the form VAL__EPS <T > represent the machine precision when performing calculations using each data type. The machine precision ϵ is the smallest positive value such that (1 + ϵ) can be represented on the machine and is distinguishable from 1 using the data type in question. The data types of these constants match the quantities they describe, as follows:





Constant
Type
Value
Hexadecimal Pattern




VAL__EPSUB _UBYTE 1 01
VAL__EPSB _BYTE 1 01
VAL__EPSUW _UWORD 1 0001
VAL__EPSW _WORD 1 0001
VAL__EPSI _INTEGER 1 00000001
VAL__EPSR _REAL 1.1920929E−7 00003500
VAL__EPSD _DOUBLE 2.7755575615628914E−17 0000000000002500




5.3 Maximum Data Values

Constants with names of the form VAL__MAX <T > represent the maximum (most positive) non-bad values which can be represented on the machine. The data types of these constants match the quantities they describe, as follows:





Constant
Type
Value
Hexadecimal Pattern




VAL__MAXUB _UBYTE 254 FE
VAL__MAXB _BYTE 127 7F
VAL__MAXUW _UWORD 65534 FFFE
VAL__MAXW _WORD 32767 7FFF
VAL__MAXI _INTEGER 2147483647 7FFFFFFF
VAL__MAXR _REAL 1.7014117E+38 FFFF7FFF
VAL__MAXD _DOUBLE 1.701411834604923D+38 FFFFFFFFFFFF7FFF




Constants with names of the form NUM__MAX <T > represent the maximum (most positive) numbers which can be represented on the machine. The data types of these constants also match the quantities they describe, as follows:





Constant
Type
Value
Hexadecimal Pattern




NUM__MAXUB _UBYTE 255 FF
NUM__MAXB _BYTE 127 7F
NUM__MAXUW _UWORD 65535 FFFF
NUM__MAXW _WORD 32767 7FFF
NUM__MAXI _INTEGER 2147483647 7FFFFFFF
NUM__MAXR _REAL 1.7014117E+38 FFFF7FFF
NUM__MAXD _DOUBLE 1.701411834604923D+38 FFFFFFFFFFFF7FFF




5.4 Minimum Data Values

Constants with names of the form VAL__MIN <T > represent the minimum (most negative) non-bad values which can be represented on the machine. The data types of these constants match the quantities they describe, as follows:





Constant
Type
Value
Hexadecimal Pattern




VAL__MINUB _UBYTE 0 00
VAL__MINB _BYTE −127 81
VAL__MINUW _UWORD 0 0000
VAL__MINW _WORD −32767 8001
VAL__MINI _INTEGER −2147483647 80000001
VAL__MINR _REAL −1.7014117E+38 FFFEFFFF
VAL__MIND _DOUBLE −1.701411834604923D+38 FFFEFFFFFFFFFFFF




Constants with names of the form NUM__MIN <T > represent the minimum (most negative) numbers which can be represented on the machine. The data types of these constants also match the quantities they describe, as follows:





Constant
Type
Value
Hexadecimal Pattern




NUM__MINUB _UBYTE 0 00
NUM__MINB _BYTE −128 80
NUM__MINUW _UWORD 0 0000
NUM__MINW _WORD −32768 8000
NUM__MINI _INTEGER −2147483648 80000000
NUM__MINR _REAL −1.7014117E+38 FFFFFFFF
NUM__MIND _DOUBLE −1.701411834604923D+38 FFFFFFFFFFFFFFFF




5.5 Data Storage Requirements

Constants with names of the form VAL__NB <T > represent the number of basic machine units (bytes) required to hold one value of each data type. All these constants are of type _INTEGER, with values as follows:




Constant
Type
Value



VAL__NBUB _INTEGER 1
VAL__NBB _INTEGER 1
VAL__NBUW _INTEGER 2
VAL__NBW _INTEGER 2
VAL__NBI _INTEGER 4
VAL__NBR _INTEGER 4
VAL__NBD _INTEGER 8



5.6 Smallest Value

Constants with names of the form VAL__SML <T > represent the smallest positive (non-zero) value which can be represented on the machine. The data types of these constants match the quantities they describe, as follows:





Constant
Type
Value
Hexadecimal Pattern




VAL__SMLUB _UBYTE 1 01
VAL__SMLB _BYTE 1 01
VAL__SMLUW _UWORD 1 0001
VAL__SMLW _WORD 1 0001
VAL__SMLI _INTEGER 1 00000001
VAL__SMLR _REAL 2.9387359E−39 00000080
VAL__SMLD _DOUBLE 2.9387358770557188E−39 0000000000000080




5.7 Character String Sizes

Constants with names of the form VAL__SZ <T > specify the maximum number of characters required to represent each numerical data type when formatted as a decimal string. All these constants are of type _INTEGER and should be used when declaring character variables to hold formatted numerical data. Their values are:




Constant
Type
Value



VAL__SZUB _INTEGER 3
VAL__SZB _INTEGER 4
VAL__SZUW _INTEGER 5
VAL__SZW _INTEGER 6
VAL__SZI _INTEGER 11
VAL__SZR _INTEGER 14
VAL__SZD _INTEGER 22



4The constants given here are appropriate to VAX machines using F- and D-type floating point number representations. Only a simple description of floating point arithmetic is given. Applications requiring a more complete description should use routines from the NAG library, with which the values given here are compatible.