HP OpenVMS Systems Documentation

OpenVMS VAX RTL Mathematics (MTH$) Manual

Contents

Index

MTH$CxSIN

The Sine of a Complex Number routine returns the sine of a complex number (r,i).

Format

MTH$CDSIN complex-sine ,complex-number
MTH$CGSIN complex-sine ,complex-number
Each of the above formats accepts one of the floating-point complex types as input.

RETURNS

None.

Arguments

complex-sine

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: write only

mechanism: by reference

Complex sine of the complex number. The complex sine routines with D-floating complex and G-floating complex input values write the complex sine into this complex-sine argument. For MTH$CDSIN, complex-sine specifies a D-floating complex number. For MTH$CGSIN, complex-sine specifies a G-floating complex number.
complex-number

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: read only

mechanism: by reference

A complex number (r,i), where r and i are floating-point numbers. The complex-number argument is the address of this complex number. For MTH$CDSIN, complex-number specifies a D-floating complex number. For MTH$CGSIN, complex-number specifies a G-floating complex number.

Description

The complex sine is computed as follows:
complex-sine = (SIN(r) * COSH(i), COS(r) * SINH(i))

Condition Values Signaled

SS$_ROPRAND Reserved operand. The MTH$CxSIN routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Compaq.

MTH$_FLOOVEMAT Floating-point overflow in Math Library: the absolute value of i is greater than about 88.029 for D-floating values, or greater than about 709.089 for G-floating values.

Example

C+
C    This Fortran example forms the complex sine of a G-floating
C    complex number using MTH$CGSIN and the Fortran random number
C    generator RAN.
C
C    Declare Z and MTH$CGSIN as complex values.  MTH$CGSIN returns
C    the sine value of Z:      CALL MTH$CGSIN(Z_NEW,Z)
C-
        COMPLEX*16 Z,Z_NEW
        COMPLEX*16 DCMPLX
        REAL*8 R,I
        INTEGER M
        M = 1234567
C+
C    Generate a random complex number with the
C    Fortran generic DCMPLX.
C-
        R = RAN(M)
        I = RAN(M)
        Z = DCMPLX(R,I)
C+
C     Z is a complex number (r,i) with real part "r" and
C     imaginary part "i".
C-
        TYPE *, ' The complex number z is',z
        TYPE *, ' '
C+
C    Compute the complex sine value of Z.
C-
        CALL MTH$CGSIN(Z_NEW,Z)
        TYPE *, ' The complex sine value of',z,' is',Z_NEW
        END

This Fortran example demonstrates a procedure call to MTH$CGSIN. Because this program uses G-floating numbers, it must be compiled with the statement "Fortran/G filename".
The output generated by this program is as follows:
The complex number z is (0.853540718555450,0.204340159893036) The complex sine value of (0.853540718555450,0.204340159893036) is (0.769400835484975,0.135253340912255)

MTH$CSQRT

The Complex Square Root (F-Floating Value) routine returns the complex square root of a complex number (r,i).

Format

MTH$CSQRT complex-number

RETURNS

OpenVMS usage: complex_number

type: F_floating complex

access: write only

mechanism: by value

The complex square root of the complex-number argument. MTH$CSQRT returns an F-floating number.

Argument

complex-number

OpenVMS usage: complex_number

type: F_floating complex

access: read only

mechanism: by reference

Complex number (r,i). The complex-number argument contains the address of this complex number. For MTH$CSQRT, complex-number specifies an F-floating number.

Description

The complex square root is computed as follows.
First, calculate ROOT and Q using the following equations:
ROOT = SQRT((ABS(r) + CABS(r,i))/2) Q = i/(2 * ROOT)

Then, the complex result is given as follows:

r i CSQRT((r,i))

=>0 Any (ROOT,Q)

<0 =>0 (Q,ROOT)

<0 <0 (-Q,-ROOT)

See MTH$CxSQRT for the descriptions of the D- and G-floating point versions of this routine.

Condition Values Signaled

SS$_FLTOVF_F Floating point overflow can occur.

SS$_ROPRAND Reserved operand. The MTH$CSQRT routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Compaq.

MTH$CxSQRT

The Complex Square Root routine returns the complex square root of a complex number (r,i).

Format

MTH$CDSQRT complex-square-root ,complex-number
MTH$CGSQRT complex-square-root ,complex-number
Each of the above formats accepts one of the floating-point complex types as input.

RETURNS

None.

Arguments

complex-square-root

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: write only

mechanism: by reference

Complex square root of the complex number specified by complex-number. The complex square root routines that have D-floating complex and G-floating complex input values write the complex square root into complex-square-root. For MTH$CDSQRT, complex-square-root specifies a D-floating complex number. For MTH$CGSQRT, complex-square-root specifies a G-floating complex number.
complex-number

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: read only

mechanism: by reference

Complex number (r,i). The complex-number argument contains the address of this complex number. For MTH$CDSQRT, complex-number specifies a D-floating number. For MTH$CGSQRT, complex-number specifies a G-floating number.

Description

The complex square root is computed as follows.
First, calculate ROOT and Q using the following equations:
ROOT = SQRT((ABS(r) + CABS(r,i))/2) Q = i/(2 * ROOT)

Then, the complex result is given as follows:

r i CSQRT((r,i))

=>0 any (ROOT,Q)

<0 =>0 (Q,ROOT)

<0 <0 (-Q,-ROOT)

Condition Values Signaled

SS$_FLTOVF_F Floating point overflow can occur.

SS$_ROPRAND Reserved operand. The MTH$CxSQRT routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Compaq.

Example

C+
C    This Fortran example forms the complex square root of a D-floating
C    complex number using MTH$CDSQRT and the Fortran random number
C    generator RAN.
C
C    Declare Z and Z_NEW as complex values. MTH$CDSQRT returns the
C    complex square root of Z:   CALL MTH$CDSQRT(Z_NEW,Z).
C-
        COMPLEX*16 Z,Z_NEW
        COMPLEX*16 DCMPLX
        INTEGER M
        M = 1234567
C+
C    Generate a random complex number with the
C    Fortran generic CMPLX.
C-
        Z = DCMPLX(RAN(M),RAN(M))
C+
C    Z is a complex number (r,i) with real part "r" and imaginary
C    part "i".
C-
        TYPE *, ' The complex number z is',z
        TYPE *, ' '
C+
C    Compute the complex complex square root of Z.
C-
        CALL MTH$CDSQRT(Z_NEW,Z)
        TYPE *, ' The complex square root of',z,' is',Z_NEW
       END

This Fortran example program demonstrates a procedure call to MTH$CDSQRT. The output generated by this program is as follows:
The complex number z is (0.8535407185554504,0.2043401598930359) The complex square root of (0.8535407185554504,0.2043401598930359) is (0.9303763973040062,0.1098158554350485)

MTH$CVT_x_x

The Convert One Double-Precision Value routines convert one double-precision value to the destination data type and return the result as a function value. MTH$CVT_D_G converts a D-floating value to G-floating and MTH$CVT_G_D converts a G-floating value to a D-floating value.

Format

MTH$CVT_D_G floating-point-input-val
MTH$CVT_G_D floating-point-input-val

RETURNS

OpenVMS usage: floating_point

type: G_floating, D_floating

access: write only

mechanism: by value

The converted value. MTH$CVT_D_G returns a G-floating value. MTH$CVT_G_D returns a D-floating value.

Argument

floating-point-input-val

OpenVMS usage: floating_point

type: D_floating, G_floating

access: read only

mechanism: by reference

The input value to be converted. The floating-point-input-val argument is the address of this input value. For MTH$CVT_D_G, the floating-point-input-val argument specifies a D-floating number. For MTH$CVT_G_D, the floating-point-input-val argument specifies a G-floating number.

Description

These routines are designed to function as hardware conversion instructions. They fault on reserved operands. If floating-point overflow is detected, an error is signaled. If floating-point underflow is detected and floating-point underflow is enabled, an error is signaled.

Condition Values Signaled

SS$_ROPRAND Reserved operand. The MTH$CVT_x_x routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Compaq.

MTH$_FLOOVEMAT Floating-point overflow in Math Library.

MTH$_FLOUNDMAT Floating-point underflow in Math Library.

MTH$CVT_xA_xA

The Convert an Array of Double-Precision Values routines convert a contiguous array of double-precision values to the destination data type and return the results as an array. MTH$CVT_DA_GA converts D-floating values to G-floating and MTH$CVT_GA_DA converts G-floating values to D-floating.

Format

MTH$CVT_DA_GA floating-point-input-array ,floating-point-dest-array [,array-size]
MTH$CVT_GA_DA floating-point-input-array ,floating-point-dest-array [,array-size]

RETURNS

MTH$CVT_DA_GA and MTH$CVT_GA_DA return the address of the output array to the floating-point-dest-array argument.

Arguments

floating-point-input-array

OpenVMS usage: floating_point

type: D_floating, G_floating

access: read only

mechanism: by reference, array reference

Input array of values to be converted. The floating-point-input-array argument is the address of an array of floating-point numbers. For MTH$CVT_DA_GA, floating-point-input-array specifies an array of D-floating numbers. For MTH$CVT_GA_DA, floating-point-input-array specifies an array of G-floating numbers.
floating-point-dest-array

OpenVMS usage: floating_point

type: G_floating, D_floating

access: write only

mechanism: by reference, array reference

Output array of converted values. The floating-point-dest-array argument is the address of an array of floating-point numbers. For MTH$CVT_DA_GA, floating-point-dest-array specifies an array of G-floating numbers. For MTH$CVT_GA_DA, floating-point-dest-array specifies an array of D-floating numbers.
array-size

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Number of array elements to be converted. The default value is 1. The array-size argument is the address of a longword containing this number of elements.

Description

These routines are designed to function as hardware conversion instructions. They fault on reserved operands. If floating-point overflow is detected, an error is signaled. If floating-point underflow is detected and floating-point underflow is enabled, an error is signaled.

Condition Values Signaled

SS$_ROPRAND Reserved operand. The MTH$CVT_xA_xA routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Compaq.

MTH$_FLOOVEMAT Floating-point overflow in Math Library.

MTH$_FLOUNDMAT Floating-point underflow in Math Library.

MTH$xEXP

The Exponential routine returns the exponential of the input value.

Format

MTH$EXP floating-point-input-value
MTH$DEXP floating-point-input-value
MTH$GEXP floating-point-input-value
Each of the above formats accepts one of the floating-point types as input.
Corresponding JSB Entry Points
MTH$EXP_R4
MTH$DEXP_R6
MTH$GEXP_R6
Each of the above JSB entry points accepts one of the floating-point types as input.

RETURNS

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: write only

mechanism: by value

The exponential of floating-point-input-value. MTH$EXP returns an F-floating number. MTH$DEXP returns a D-floating number. MTH$GEXP returns a G-floating number.

Argument

floating-point-input-value

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: read only

mechanism: by reference

The input value. The floating-point-input-value argument is the address of a floating-point number. For MTH$EXP, floating-point-input-value specifies an F-floating number. For MTH$DEXP, floating-point-input-value specifies a D-floating number. For MTH$GEXP, floating-point-input-value specifies a G-floating number.

Description

The exponential of x is computed as:

Value of x Value Returned

X > c(z) Overflow occurs

X <= -c(z) 0

|X| < 2 ^-(f+1) 1

Otherwise 2 ^Y * 2 ^U * 2 ^W

where: Y = INTEGER(x*ln2(E)) V = FRAC(x*ln2(E)) * 16 U = INTEGER(V)/16 W = FRAC(V)/16 2^W = polynomial approximation of degree 4, 8, or 8 for z = F, D, or G.
See also MTH$xCOSH for definitions of f and c(z).
See MTH$HEXP for the description of the H-floating point version of this routine.

Condition Values Signaled

SS$_ROPRAND Reserved operand. The MTH$xEXP routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Compaq.

MTH$_FLOOVEMAT Floating-point overflow in Math Library: floating-point-input-value is greater than yyy; LIB$SIGNAL copies the reserved operand to the signal mechanism vector. The result is the reserved operand -0.0 unless a condition handler changes the signal mechanism vector.
The values of yyy are approximately:
MTH$EXP---88.029
MTH$DEXP---88.029
MTH$GEXP---709.089

MTH$_FLOUNDMAT Floating-point underflow in Math Library: floating-point-input-value is less than or equal to yyy and the caller (CALL or JSB) has set hardware floating-point underflow enable. The result is set to 0.0. If the caller has not enabled floating-point underflow (the default), a result of 0.0 is returned but no error is signaled.
The values of yyy are approximately:
MTH$EXP--- -- 88.722
MTH$DEXP--- -- 88.722
MTH$GEXP--- -- 709.774

Example

IDENTIFICATION DIVISION.
PROGRAM-ID.    FLOATING_POINT.
*
*  Calls MTH$EXP using a Floating Point data type.
*  Calls MTH$DEXP using a Double Floating Point data type.
*
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FLOAT_PT     COMP-1.
01 ANSWER_F     COMP-1.
01 DOUBLE_PT    COMP-2.
01 ANSWER_D     COMP-2.
PROCEDURE DIVISION.
P0.
        MOVE 12.34 TO FLOAT_PT.
        MOVE 3.456 TO DOUBLE_PT.

        CALL "MTH$EXP" USING BY REFERENCE FLOAT_PT GIVING ANSWER_F.
        DISPLAY " MTH$EXP of ", FLOAT_PT CONVERSION, " is ",
                                               ANSWER_F CONVERSION.

        CALL "MTH$DEXP" USING BY REFERENCE DOUBLE_PT GIVING ANSWER_D.
        DISPLAY " MTH$DEXP of ", DOUBLE_PT CONVERSION, " is ",
                                               ANSWER_D CONVERSION .
        STOP RUN.

This sample program demonstrates calls to MTH$EXP and MTH$DEXP from COBOL.
The output generated by this program is as follows:
MTH$EXP of 1.234000E+01 is 2.286620E+05 MTH$DEXP of 3.456000000000000E+00 is 3.168996280537917E+01

Contents

Index