4 THE NUM_ FUNCTIONS

 4.1 Applicability & Efficiency
 4.2 NUM_ Arithmetic and Mathematical Functions
 4.3 NUM_ Type Conversion Functions
 4.4 NUM_ Inter-comparison Functions
 4.5 Declaring and Defining the NUM_ Functions
 4.6 NUM Error Handling

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:

  RESULT = NUM_<name>( ARG )

or

  RESULT = NUM_<name>( ARG1, ARG2 )

where <name > specifies the operation to be performed and ARG, ARG1 and ARG2 are input arguments.

4.1 Applicability & Efficiency

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.

4.2 NUM_ Arithmetic and Mathematical Functions

Arithmetic and mathematical operations may be performed on numbers stored using any numerical data type by invoking appropriate NUM_ functions, using statements such as:

  RESULT = NUM_<FUNC><T>( ARG )

or

  RESULT = NUM_<FUNC><T>( ARG1, ARG2 )

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.

4.3 NUM_ Type Conversion Functions

Conversion of numbers between numerical data types may be performed by invoking the appropriate NUM_ type conversion functions, using statements such as:

  RESULT = NUM_<T1>TO<T2>( ARG )

Here, the NUM_ function takes an argument of type <T1 > and returns a result of type <T2 >, having performed type conversion. The data type codes <T1 > and <T2 > 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).

4.4 NUM_ Inter-comparison Functions

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:

  RESULT = NUM_<ROPER><T>( ARG1, ARG2 )

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.




Relational Operation Code
<ROPER >
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



Table 4: The relational operation codes used in the names of NUM_ functions and the inter-comparisons to which they correspond.

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.

4.5 Declaring and Defining the NUM_ Functions

The NUM facility is implemented as a set of Fortran statement functions. To use them, an application must:

(1)
Declare the function names and dummy arguments, specifying their Fortran types;
(2)
Define the functions.

Two files are provided which contain Fortran statements to perform these tasks and they may be included in an application with the statements:

  INCLUDE ’NUM_DEC’
  INCLUDE ’NUM_DEF’

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

  INCLUDE ’NUM_DEC_CVT’
  INCLUDE ’NUM_DEF_CVT’

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:

  INCLUDE ’NUM_DEC_<T>’
  INCLUDE ’NUM_DEF_<T>’

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:

  INCLUDE ’NUM_DEC_CVT’
  INCLUDE ’NUM_DEC_UW’
  INCLUDE ’NUM_DEF_CVT’
  INCLUDE ’NUM_DEF_UW’

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).

4.6 NUM Error Handling

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:

        SUBROUTINE EXAMPL( N, DATA )
  
  *   Declare constants and variables.
        INCLUDE ’SAE_PAR’
        INCLUDE ’PRM_PAR’
        INTEGER N, I
        REAL DATA( N )
  
  *   Declare the condition handler.
        INTEGER NUM_TRAP                            [1]
        EXTERNAL NUM_TRAP
  
  *   Include the NUM_CMN common block definition, which defines
  *   the variable NUM_ERROR.
        INCLUDE ’NUM_CMN’                           [2]
  
  *   Establish the condition handler.
        CALL LIB$ESTABLISH( NUM_TRAP )              [3]
  
  *   Initialise.
        NUM_ERROR = SAI__OK                         [4]
  
  *   Perform the calculations.
        DO 1 I = 1, N
           DATA( I ) = 1.0 / ( DATA( I ) ** 2 )     [5]
  
  *   Check if an error occurred.
           IF( NUM_ERROR .NE. SAI__OK ) THEN        [6]
  
  *   If so, reset the NUM_ERROR flag and define the result.
              NUM_ERROR = SAI__OK                   [7]
              DATA( I ) = VAL__BADR
           ENDIF
      1 CONTINUE
  
  *   Remove the condition handler and exit the routine.
        CALL LIB$REVERT                             [8]
        END

Programming notes:

(1)
The integer function NUM_TRAP is provided as a standard condition handler which traps numerical errors. This routine must be declared in an EXTERNAL statement.
(2)
The common block NUM_CMN is defined using an INCLUDE statement. It contains a single integer variable called NUM_ERROR which communicates with the condition handler.
(3)
The VAX RTL routine LIB$ESTABLISH is called to establish the condition handler. From this point on, numerical errors will not cause the application to crash, but will be intercepted by the NUM_TRAP routine. This behaviour is local to the routine from which LIB$ESTABLISH is called. The behaviour of VAL_ and VEC_ routines and the handling of non-numerical errors is not affected.
(4)
The common block variable NUM_ERROR is initialised to SAI__OK. This is important because numerical errors will not be detected otherwise.
(5)
Calculations are performed which may potentially fail. These may include calls to NUM_ functions and need not be confined to a single expression or statement. In the above example floating point overflow or division by zero could occur, according to the contents of the DATA array.
(6)
After a calculation, the status variable NUM_ERROR is tested. If it is not SAI__OK, then a numerical error has occurred. The value of NUM_ERROR may be used as a status code for reporting the error if required.
(7)
If an error has occurred, suitable action is taken. This must include resetting the numerical error status NUM_ERROR to SAI__OK and defining the result of any calculations which failed. This will usually be done using a flag for later identification (normally one of the Starlink bad values).
(8)
Finally, the condition handler is removed by calling the RTL routine LIB$REVERT. This is strictly only necessary if further calculations which do not require error handling are to be performed in the same routine.

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.