Document revision date: 30 March 2001

## OpenVMS VAX RTL Mathematics (MTH$) Manual

Previous | 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 2W = 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

Previous | Next | Contents | Index

| privacy and legal statement |
6117PRO_008.HTML