THE VAL_ FUNCTIONS

←Prev
PRIMDAT — Processing of Primitive Numerical Data
Next→
TOC ↑

2 THE VAL_ FUNCTIONS

2.1 Applicability & Efficiency
2.2 VAL_ Error Handling
2.3 VAL_ Arithmetic and Mathematical Functions
2.4 VAL_ Type Conversion Functions
2.5 Declaring the VAL_ Functions

The VAL_ functions are a set of Fortran functions which perform arithmetic, mathematical operations and type conversion on single (scalar) values stored using any numerical data type. These functions will handle numerical errors which occur during their evaluation (such as division by zero or overflow) and can also recognise and propagate the standard Starlink bad values.

They are normally invoked by statements of the form:

RESULT = VAL_<name>( BAD, ARG, STATUS )

RESULT = VAL_<name>( BAD, ARG1, ARG2, STATUS )

where $<$ name $>$ specifies the operation to be performed and:

BAD is a logical value specifying whether bad input arguments are to be recognised;
ARG, ARG1 and ARG2 are the input arguments;
STATUS is an integer error status variable.

2.1 Applicability & Efficiency

The VAL_ functions are designed primarily for ease of use and robustness, with efficiency being a secondary consideration. In fact, the overhead involved in invoking many of these functions exceeds the time required to actually perform the calculation. Consequently, VAL_ functions should not be used for processing large arrays of data. Rather, they are best used for relatively small numbers of calculations (up to a few thousand), when they can enhance the robustness and flexibility of applications by handling numerical errors and bad values with the minimum of programming effort.

The VEC_ routines (section 3) should normally be used for processing larger arrays of data.

2.2 VAL_ Error Handling

The error handling strategy used by the VAL_ routines consists of returning a bad function result under the following circumstances:

(1): If STATUS is not set to SAI__OK when the function is invoked.
(2): If the BAD argument is set to .TRUE. and any of the input arguments is bad.
(3): If any numerical error occurs during evaluation of the function — in this latter case an appropriate error code will also be returned via the STATUS argument.

2.3 VAL_ Arithmetic and Mathematical Functions

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

RESULT = VAL_<FUNC><T>( BAD, ARG, STATUS )

RESULT = VAL_<FUNC><T>( BAD, ARG1, ARG2, STATUS )

Here, the VAL_ 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 input arguments (1 or 2) appropriate to each function is also indicated in these latter Tables.

Function Code

$<$ FUNC $>$

Number of

Arguments

Operation performed

ADD

addition: ARG1

+

ARG2

SUB

subtraction: ARG1

-

ARG2

MUL

multiplication: ARG1

*

ARG2

DIV

*(floating) division: ARG1

/

ARG2

IDV

**(integer) division: ARG1

/

ARG2

PWR

raise to power: ARG1

* *

ARG2

NEG

negate (change sign):

-

ARG

SQRT

square root:

\sqrt{ARG}

LOG

natural logarithm:

ln (ARG)

LG10

common logarithm:

{log}_{10} (ARG)

EXP

exponential:

exp (ARG)

ABS

absolute (positive) value:

|ARG|

NINT

nearest integer value to ARG

INT

Fortran AINT (truncation to integer) function

MAX

maximum:

max (ARG1, ARG2)

MIN

minimum:

min (ARG1, ARG2)

DIM

Fortran DIM (positive difference) function

MOD

Fortran MOD (remainder) function

SIGN

Fortran SIGN (transfer of sign) function

Notes:

*Equivalent to NINT(REAL(ARG1)

/

REAL(ARG2)) for non-floating quantities

**Equivalent to AINT(ARG1

/

ARG2) for floating quantities

Table 2: Function codes used in routine names and the operations to which they correspond. The functions shown here are implemented for all the numerical data types (type codes UB, B, UW, W, I, R & D).

Thus, for example, the function VAL_ADDUW adds two unsigned word arguments to produce an unsigned word result, while VAL_SQRTD evaluates the square root of a double precision argument, returning a double precision result.

2.4 VAL_ Type Conversion Functions

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

RESULT = VAL_<T1>TO<T2>( BAD, ARG, STATUS )

Here, the VAL_ function takes an argument of type $<$ T $_{1} >$ and returns a result of type $<$ T $_{2} >$ , having performed type conversion. The data type codes $<$ T $_{1} >$ and $<$ T $_{2} >$ may be any of those specified in Table 1.

Thus, for example, the function VAL_BTOUW converts a byte argument to an unsigned word result, while VAL_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).

Function Code

$<$ FUNC $>$

Number of

Arguments

Operation performed

SIN

*sine function:

sin (ARG)

SIND

**sine function:

sin (ARG)

COS

*cosine function:

cos (ARG)

COSD

**cosine function:

cos (ARG)

TAN

*tangent function:

tan (ARG)

TAND

**tangent function:

tan (ARG)

ASIN

*inverse sine function:

{sin}^{- 1} (ARG)

ASND

**inverse sine function:

{sin}^{- 1} (ARG)

ACOS

*inverse cosine function:

{cos}^{- 1} (ARG)

ACSD

**inverse cosine function:

{cos}^{- 1} (ARG)

ATAN

*inverse tangent function:

{tan}^{- 1} (ARG)

ATND

*inverse tangent function:

{tan}^{- 1} (ARG)

ATN2

*Fortran ATAN2 (inverse tangent) function

AT2D

**VAX Fortran ATAN2D (inverse tangent) function

SINH

hyperbolic sine function:

sinh (ARG)

COSH

hyperbolic cosine function:

cosh (ARG)

TANH

hyperbolic tangent function:

tanh (ARG)

Notes:

*Argument(s)/result in radians

**Argument(s)/result in degrees

Table 3: Function codes used in routine names and the operations to which they correspond. The functions shown here are only implemented for the floating point data types (type codes R & D).

2.5 Declaring the VAL_ Functions

Since the VAL_ functions return a result via the routine name, appropriate declarations of their Fortran type must be made before they are used. Thus, for instance, an application which used the routines VAL_ADDUB and VAL_DTOI would require the declarations:

BYTE VAL_ADDUB
INTEGER VAL_DTOI

A routine suitable for processing by the GENERIC compiler might require equivalent generic declarations:

←Prev
PRIMDAT — Processing of Primitive Numerical Data
Next→
TOC ↑