OpenVMS VAX RTL Mathematics (MTH$) Manual

Updated: 12 December 1998

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

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- COMPLEX16 Z,Z_NEW COMPLEX16 DCMPLX REAL8 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

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.

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$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 Digital.

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)

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

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- COMPLEX16 Z,Z_NEW COMPLEX16 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

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

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

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.

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

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

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.

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

Legal

 
6117PRO_008.HTML

OpenVMS usage:	complex_number
type:	D_floating complex, G_floating complex
access:	write only
mechanism:	by reference

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

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

OpenVMS usage:	floating_point
type:	G_floating, D_floating
access:	write only
mechanism:	by value

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 Digital.
MTH$_FLOOVEMAT	Floating-point overflow in Math Library.
MTH$_FLOUNDMAT	Floating-point underflow in Math Library.

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

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 Digital.
MTH$_FLOOVEMAT	Floating-point overflow in Math Library.
MTH$_FLOUNDMAT	Floating-point underflow in Math Library.