The NUM_ functions perform arithmetic, mathematical operations, type conversion and inter-comparison on numbers, operating at a rather lower level than the VAL_ or VEC_ routines — in fact many of these latter routines are currently implemented using the NUM facility.
At present, all the NUM_ routines are implemented as Fortran statement functions whose definitions must be incorporated into an application with appropriate INCLUDE statements (section 4.5).
They are normally invoked by statements of the form:
or
where name specifies the operation to be performed and ARG, ARG1 and ARG2 are input arguments.
The NUM_ functions are the most flexible routines in this package. Being implemented as statement functions, they will normally be expanded “in-line” by the VAX Fortran compiler and may therefore be used in any situation without incurring the overhead of an external function call. The expanded function definition can subsequently take part in the compiler’s optimisation process and will therefore result in code which executes very efficiently (although some of the machine-specific features used by VEC_ routines cannot be accessed in this way).
However, the NUM_ functions are also the least robust routines in this package. This is because they incorporate no protection against numerical errors (such as division by zero or overflow), neither do they generate or recognise bad data — which they will always treat as valid. If a numerical error occurs when a NUM_ function is invoked, the application will immediately terminate (i.e. crash).
The robustness of NUM_ functions may be improved by incorporating explicit checks on the numbers being processed and by ensuring that the functions are not invoked if their arguments may be undefined (under error conditions, for instance). Such checks will always degrade the execution efficiency, however, and the equivalent VEC_ routine (section 3) is then likely to be at least as efficient. Consequently, use of the NUM_ functions is generally appropriate only when:
For applications where VAX-specific code is acceptable, the NUM facility also includes a simple VAX condition handler which can be used to recover from numerical errors (section 4.6). This may be used with the NUM_ functions (and Fortran arithmetic expressions) to combine robustness with efficiency and flexibility in cases where other routines from this package are not suitable. However, the programming effort required is relatively high and the resulting applications will not be portable.
Arithmetic and mathematical operations may be performed on numbers stored using any numerical data type by invoking appropriate NUM_ functions, using statements such as:
or
Here, the NUM_ function takes an argument (or arguments) of type T and returns a result which is also of type T, having performed the arithmetic or mathematical operation specified by FUNC. The data type code T may be any of those specified in Table 1 and FUNC may be any of the function codes specified in Tables 2 & 3. The number of function arguments (1 or 2) appropriate to each function is also indicated in these latter Tables.
Thus, for example, the function NUM_ADDUW adds two unsigned word arguments to produce an unsigned word result, while NUM_SQRTD evaluates the square root of a double precision argument, returning a double precision result.
Conversion of numbers between numerical data types may be performed by invoking the appropriate NUM_ type conversion functions, using statements such as:
Here, the NUM_ function takes an argument of type T and returns a result of type T, having performed type conversion. The data type codes T and T may be any of those specified in Table 1.
Thus, for example, the function NUM_BTOUW converts a byte argument to an unsigned word result, while NUM_DTOI converts from double precision to integer.
Note that conversions from floating point types (_REAL or _DOUBLE) to non-floating point types result in rounding of the data (not truncation as would happen with a Fortran assignment statement).
Inter-comparison of numbers stored using any numerical data type, to test for equality or inequality relations, may be performed by invoking the appropriate NUM_ inter-comparison functions, using statements such as:
Here, the NUM_ function takes two arguments of type T and returns a logical result, having compared its arguments according to the relational operation specified by ROPER. The data type code T may be any of those in Table 1 and ROPER may be any of the relational operation codes specified in Table 4.
| Inter-comparison | ||
| EQ | ARG1 .EQ. ARG2 | ||
| NE | ARG1 .NE. ARG2 | ||
| GT | ARG1 .GT. ARG2 | ||
| GE | ARG1 .GE. ARG2 | ||
| LT | ARG1 .LT. ARG2 | ||
| LE | ARG1 .LE. ARG2 | ||
Thus, for example, the logical function NUM_GTUB returns a .TRUE. result if the unsigned byte number ARG1 is greater than the unsigned byte number ARG2, while NUM_LED returns .TRUE. if the double precision number ARG1 is less than or equal to the double precision number ARG2.
Note that equivalent inter-comparison functions are not available in the VAL or VEC facilities.
The NUM facility is implemented as a set of Fortran statement functions. To use them, an application must:
Two files are provided which contain Fortran statements to perform these tasks and they may be included in an application with the statements:
which should appear (in this order) immediately after any local Fortran variables have been declared and before the executable code begins. These statements will declare and define the entire set of NUM_ functions.
In almost all cases, however, compilation time can be considerably reduced by defining only a sub-set of these functions. Files are therefore provided which allow the function definitions to be selected according to the data type of their arguments. When using this option, the following two statements should first be used to declare and define the type conversion functions and their arguments (since these are used by all the other NUM_ functions they must always be present):
If the application only uses the NUM_ functions to perform type conversion, then this is all that is required. However, to additionally declare and define the NUM_ functions which process a particular argument data type, the statements:
should then be used (here, the argument type code T is one of those specified in Table 1). Thus, to give a complete example, the NUM_ functions for processing unsigned word data would be declared and defined using the following four statements:
Note that to comply with Fortran restrictions on statement order, all the type declaration statements (NUM_DEC_ files) have to appear before the function definition statements (NUM_DEF_ files).
Because the NUM_ functions do not have any built-in error handling capability, the NUM facility provides a simple VAX condition handler which may be used to explicitly implement error handling, both for the NUM_ functions and straightforward Fortran arithmetic expressions.
Note that using this capability involves calls to VAX Run Time Library (RTL) routines and will therefore result in applications which are not portable. Such applications will continue to operate, however, if the RTL calls are simply removed, although error handling will not then occur.
The technique is best explained by an example:
Programming notes:
It is important to note that when a calculation fails, more than one numerical error may occur. This is because the (erroneous) result of the first operation to fail can be re-used in subsequent parts of an arithmetic expression and may precipitate further errors. To ensure that NUM_ERROR indicates the true (first) cause of an error in such cases, this variable behaves as a latch; once set, it will not again change in response to an error until it has first been reset to SAI__OK.
Note also, that the result of a calculation which fails (or may have failed) must not be used under any circumstances. It may either contain an erroneous result or an invalid floating point number (a reserved operand) which will cause any application which processes it to crash. Such results must immediately be replaced with a well-defined value.