
OpenVMS VAX RTL Mathematics (MTH$) Manual
MTH$CxSIN
The Sine of a Complex Number routine returns the sine of a complex
number (r,i).
Format
MTH$CDSIN complexsine ,complexnumber
MTH$CGSIN complexsine ,complexnumber
Each of the above formats accepts one of the floatingpoint complex
types as input.
RETURNS
None.
Arguments
complexsine
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
Dfloating complex and Gfloating complex input values write the
complex sine into this complexsine argument. For
MTH$CDSIN, complexsine specifies a Dfloating complex
number. For MTH$CGSIN, complexsine specifies a
Gfloating complex number.
complexnumber
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 floatingpoint numbers. The
complexnumber argument is the address of this complex
number. For MTH$CDSIN, complexnumber specifies a
Dfloating complex number. For MTH$CGSIN,
complexnumber specifies a Gfloating complex number.
Description
The complex sine is computed as follows: complexsine = (SIN(r) *
COSH(i), COS(r) * SINH(i))
Condition Values Signaled
SS$_ROPRAND

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

MTH$_FLOOVEMAT

Floatingpoint overflow in Math Library: the absolute value of
i is greater than about 88.029 for Dfloating values,
or greater than about 709.089 for Gfloating values.

Example

C+
C This Fortran example forms the complex sine of a Gfloating
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 Gfloating 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 (FFloating Value) routine returns the complex
square root of a complex number (r,i).
Format
MTH$CSQRT complexnumber
RETURNS
OpenVMS usage: 
complex_number 
type: 
F_floating complex 
access: 
write only 
mechanism: 
by value 
The complex square root of the complexnumber
argument. MTH$CSQRT returns an Ffloating number.
Argument
complexnumber
OpenVMS usage: 
complex_number 
type: 
F_floating complex 
access: 
read only 
mechanism: 
by reference 
Complex number (r,i). The complexnumber argument
contains the address of this complex number. For MTH$CSQRT,
complexnumber specifies an Ffloating 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 Gfloating 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 floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint 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 complexsquareroot ,complexnumber
MTH$CGSQRT complexsquareroot ,complexnumber
Each of the above formats accepts one of the floatingpoint complex
types as input.
RETURNS
None.
Arguments
complexsquareroot
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
complexnumber. The complex square root routines that
have Dfloating complex and Gfloating complex input values write the
complex square root into complexsquareroot. For
MTH$CDSQRT, complexsquareroot specifies a Dfloating
complex number. For MTH$CGSQRT, complexsquareroot
specifies a Gfloating complex number.
complexnumber
OpenVMS usage: 
complex_number 
type: 
D_floating complex, G_floating complex 
access: 
read only 
mechanism: 
by reference 
Complex number (r,i). The complexnumber argument
contains the address of this complex number. For MTH$CDSQRT,
complexnumber specifies a Dfloating number. For
MTH$CGSQRT, complexnumber specifies a Gfloating
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 floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

Example

C+
C This Fortran example forms the complex square root of a Dfloating
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 DoublePrecision Value routines convert one
doubleprecision value to the destination data type and return the
result as a function value. MTH$CVT_D_G converts a Dfloating value to
Gfloating and MTH$CVT_G_D converts a Gfloating value to a Dfloating
value.
Format
MTH$CVT_D_G floatingpointinputval
MTH$CVT_G_D floatingpointinputval
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 Gfloating value.
MTH$CVT_G_D returns a Dfloating value.
Argument
floatingpointinputval
OpenVMS usage: 
floating_point 
type: 
D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
The input value to be converted. The
floatingpointinputval argument is the address of
this input value. For MTH$CVT_D_G, the
floatingpointinputval argument specifies a
Dfloating number. For MTH$CVT_G_D, the
floatingpointinputval argument specifies a
Gfloating number.
Description
These routines are designed to function as hardware conversion
instructions. They fault on reserved operands. If floatingpoint
overflow is detected, an error is signaled. If floatingpoint underflow
is detected and floatingpoint underflow is enabled, an error is
signaled.
Condition Values Signaled
SS$_ROPRAND

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

MTH$_FLOOVEMAT

Floatingpoint overflow in Math Library.

MTH$_FLOUNDMAT

Floatingpoint underflow in Math Library.

MTH$CVT_xA_xA
The Convert an Array of DoublePrecision Values routines convert a
contiguous array of doubleprecision values to the destination data
type and return the results as an array. MTH$CVT_DA_GA converts
Dfloating values to Gfloating and MTH$CVT_GA_DA converts Gfloating
values to Dfloating.
Format
MTH$CVT_DA_GA floatingpointinputarray ,floatingpointdestarray
[,arraysize]
MTH$CVT_GA_DA floatingpointinputarray ,floatingpointdestarray
[,arraysize]
RETURNS
MTH$CVT_DA_GA and MTH$CVT_GA_DA return the address of the output array
to the floatingpointdestarray argument.
Arguments
floatingpointinputarray
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
floatingpointinputarray argument is the address of
an array of floatingpoint numbers. For MTH$CVT_DA_GA,
floatingpointinputarray specifies an array of
Dfloating numbers. For MTH$CVT_GA_DA,
floatingpointinputarray specifies an array of
Gfloating numbers.
floatingpointdestarray
OpenVMS usage: 
floating_point 
type: 
G_floating, D_floating 
access: 
write only 
mechanism: 
by reference, array reference 
Output array of converted values. The
floatingpointdestarray argument is the address of
an array of floatingpoint numbers. For MTH$CVT_DA_GA,
floatingpointdestarray specifies an array of
Gfloating numbers. For MTH$CVT_GA_DA,
floatingpointdestarray specifies an array of
Dfloating numbers.
arraysize
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
arraysize 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 floatingpoint
overflow is detected, an error is signaled. If floatingpoint underflow
is detected and floatingpoint underflow is enabled, an error is
signaled.
Condition Values Signaled
SS$_ROPRAND

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

MTH$_FLOOVEMAT

Floatingpoint overflow in Math Library.

MTH$_FLOUNDMAT

Floatingpoint underflow in Math Library.

MTH$xEXP
The Exponential routine returns the exponential of the input value.
Format
MTH$EXP floatingpointinputvalue
MTH$DEXP floatingpointinputvalue
MTH$GEXP floatingpointinputvalue
Each of the above formats accepts one of the floatingpoint 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 floatingpoint
types as input.
RETURNS
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
write only 
mechanism: 
by value 
The exponential of floatingpointinputvalue. MTH$EXP
returns an Ffloating number. MTH$DEXP returns a Dfloating number.
MTH$GEXP returns a Gfloating number.
Argument
floatingpointinputvalue
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
The input value. The floatingpointinputvalue
argument is the address of a floatingpoint number. For MTH$EXP,
floatingpointinputvalue specifies an Ffloating
number. For MTH$DEXP, floatingpointinputvalue
specifies a Dfloating number. For MTH$GEXP,
floatingpointinputvalue specifies a Gfloating
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 Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

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

MTH$_FLOOVEMAT

Floatingpoint overflow in Math Library:
floatingpointinputvalue 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$EXP88.029
MTH$DEXP88.029
MTH$GEXP709.089

MTH$_FLOUNDMAT

Floatingpoint underflow in Math Library:
floatingpointinputvalue is less than or equal to
yyy and the caller (CALL or JSB) has set hardware
floatingpoint underflow enable. The result is set to 0.0. If the
caller has not enabled floatingpoint 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.
PROGRAMID. 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.
WORKINGSTORAGE SECTION.
01 FLOAT_PT COMP1.
01 ANSWER_F COMP1.
01 DOUBLE_PT COMP2.
01 ANSWER_D COMP2.
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

