Document revision date: 30 March 2001

## OpenVMS VAX RTL Mathematics (MTH$) Manual

Previous | Contents | Index

## MTH$HTANH

> The Compute the Hyperbolic Tangent (H-Floating Value) routine returns the hyperbolic tangent of the input value as an H-floating value.

### Format

> MTH$HTANH h-tanh ,floating-point-input-value

### RETURNS

> None.

### Arguments

> #### h-tanh

> OpenVMS usage: | floating_point
> type: | H_floating
> access: | write only
> mechanism: | by reference

> Hyperbolic tangent of the value specified by floating-point-input-value. The h-tanh argument is the address of an H-floating number that is this hyperbolic tangent. MTH$HTANH writes the address of the hyperbolic tangent into h-tanh.

> #### floating-point-input-value

> OpenVMS usage: | floating_point
> type: | H_floating
> access: | read only
> mechanism: | by reference

> The input value. The floating-point-input-value argument is the address of an H-floating number that contains this input value.

### Description

> For MTH$HTANH, the hyperbolic tangent of X is computed using a value of 56 for g and a value of 40 for h. The hyperbolic tangent of X is computed as follows:

> Value of x | Hyperbolic Tangent Returned
> --- | ---
> |X| <= 2 -g | X
> 2 -g < |X| <= 0.25 | zSINH(X)/zCOSH(X)
> 0.25 < |X| < h | (zEXP(2*X) - 1)/(zEXP(2*X) + 1)
> h <= |X| | sign(X) * 1

### Condition Value Signaled

> SS$_ROPRAND | Reserved operand. The MTH$HTANH 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$xIMAG

> The Imaginary Part of a Complex Number routine returns the imaginary part of a complex number.

### Format

> MTH$AIMAG complex-number

> MTH$DIMAG complex-number

> MTH$GIMAG complex-number

> Each of the above formats corresponds to one of the floating-point complex types.

### RETURNS

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

> Imaginary part of the input complex-number. MTH$AIMAG returns an F-floating number. MTH$DIMAG returns a D-floating number. MTH$GIMAG returns a G-floating number.

### Argument

> #### complex-number

> OpenVMS usage: | complex_number
> type: | F_floating complex, D_floating complex, G_floating complex
> access: | read only
> mechanism: | by reference

> The input complex number. The complex-number argument is the address of this floating-point complex number. For MTH$AIMAG, complex-number specifies an F-floating number. For MTH$DIMAG, complex-number specifies a D-floating number. For MTH$GIMAG, complex-number specifies a G-floating number.

### Description

> The MTH$xIMAG routines return the imaginary part of a complex number.

### Condition Value Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xIMAG 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 imaginary part of
    C    a G-floating complex number using MTH$GIMAG
    C    and the Fortran random number generator
    C    RAN.
    C
    C    Declare Z as a complex value and MTH$GIMAG as
    C    a REAL*8 value. MTH$GIMAG will return the imaginary
    C    part of Z:   Z_NEW = MTH$GIMAG(Z).
    C-

            COMPLEX*16 Z
            COMPLEX*16 DCMPLX
            REAL*8 R,I,MTH$GIMAG
            INTEGER M
            M = 1234567

    C+
    C    Generate a random complex number with the
    C    Fortran generic CMPLX.
    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 *, ' It has imaginary part',MTH$GIMAG(Z)
            END

> This Fortran example demonstrates a procedure call to MTH$GIMAG. Because this example 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.8535407185554504,0.2043401598930359)
>     It has imaginary part  0.2043401598930359

## MTH$xLOG

> The Natural Logarithm routine returns the natural (base e) logarithm of the input argument.

### Format

> MTH$ALOG floating-point-input-value

> MTH$DLOG floating-point-input-value

> MTH$GLOG floating-point-input-value

> Each of the above formats accepts one of the floating-point types as input.

> ### Corresponding JSB Entry Points

> MTH$ALOG_R5

> MTH$DLOG_R8

> MTH$GLOG_R8

> 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 natural logarithm of floating-point-input-value. MTH$ALOG returns an F-floating number. MTH$DLOG returns a D-floating number. MTH$GLOG 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 that is this value. For MTH$ALOG, floating-point-input-value specifies an F-floating number. For MTH$DLOG, floating-point-input-value specifies a D-floating number. For MTH$GLOG, floating-point-input-value specifies a G-floating number.

### Description

> Computation of the natural logarithm routine is based on the following:
> 1. ln(X*Y) = ln(X) + ln(Y)
> 2. ln(1+X) = X - X2/2 + X3/3 - X4/4 ...
>    for |X| < 1
> 3. ln(X) = ln(A) + 2* (V + V3/3 + V5/5 + V7/7 ...)
>    =ln(A) + V*p(V2), where V = (X-A)/(X+A),
>    A > 0, and p(y) = 2 * (1 + y/3 + y2/5 ...)
>    For x = 2n*f , where n is an integer and f is in the interval of 0.5 to 1, define the following quantities:
>    If n => 1, then N = n-1 and F = 2f
>    If n <= 0, then N = n and F = f
>    From (1) above it follows that:
> 4. ln(X) = N*ln(2) + ln(F)

> Based on the above relationships, zLOG is computed as follows:

> 1. If |F-1| < 2-5, zLOG(X) = N*zLOG(2) + W + W*p(W),
>    where W = F-1.
> 2. Otherwise, zLOG(X) = N*zLOG(2) + zLOG(A) + V*p(V2),
>    where V = (F-A)/(F+A) and A and zLOG(A)
>    are obtained by table lookup.

> See MTH$HLOG for the description of the H-floating point version of this routine.

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xLOG 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$_LOGZERNEG | Logarithm of zero or negative value. Argument floating-point-input-value is less than or equal to 0.0. LIB$SIGNAL copies the floating-point reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the floating-point reserved operand unless you have written a condition handler to change CHF$L_MCH_SAVR0/R1.

## MTH$xLOG2

> The Base 2 Logarithm routine returns the base 2 logarithm of the input value specified by floating-point-input-value.

### Format

> MTH$ALOG2 floating-point-input-value

> MTH$DLOG2 floating-point-input-value

> MTH$GLOG2 floating-point-input-value

> Each of the above formats 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 base 2 logarithm of floating-point-input-value. MTH$ALOG2 returns an F-floating number. MTH$DLOG2 returns a D-floating number. MTH$GLOG2 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 that is this input value. For MTH$ALOG2, floating-point-input-value specifies an F-floating number. For MTH$DLOG2, floating-point-input-value specifies a D-floating number. For MTH$GLOG2, floating-point-input-value specifies a G-floating number.

### Description

> The base 2 logarithm function is computed as follows:
> zLOG2(X) = zLOG2(E) * zLOG(X)

> See MTH$HLOG2 for the description of the H-floating point version of this routine.

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xLOG2 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$_LOGZERNEG | Logarithm of zero or negative value. Argument floating-point-input-value is less than or equal to 0.0. LIB$SIGNAL copies the floating-point reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the floating-point reserved operand unless you have written a condition handler to change CHF$L_MCH_SAVR0/R1.

## MTH$xLOG10

> The Common Logarithm routine returns the common (base 10) logarithm of the input argument.

### Format

> MTH$ALOG10 floating-point-input-value

> MTH$DLOG10 floating-point-input-value

> MTH$GLOG10 floating-point-input-value

> Each of the above formats accepts one of the floating-point types as input.

> ### Corresponding JSB Entry Points

> MTH$ALOG10_R5

> MTH$DLOG10_R8

> MTH$GLOG10_R8

> 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 common logarithm of floating-point-input-value. MTH$ALOG10 returns an F-floating number. MTH$DLOG10 returns a D-floating number. MTH$GLOG10 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$ALOG10, floating-point-input-value specifies an F-floating number. For MTH$DLOG10, floating-point-input-value specifies a D-floating number. For MTH$GLOG10, floating-point-input-value specifies a G-floating number.

### Description

> The common logarithm function is computed as follows:
> zLOG10(X) = zLOG10(E) * zLOG(X)

> See MTH$HLOG10 for the description of the H-floating point version of this routine.

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xLOG10 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$_LOGZERNEG | Logarithm of zero or negative value. Argument floating-point-input-value is less than or equal to 0.0. LIB$SIGNAL copies the floating-point reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the floating-point reserved operand unless you have written a condition handler to change CHF$L_MCH_SAVR0/R1.

## MTH$RANDOM

> The Random Number Generator, Uniformly Distributed routine is a general random number generator.

### Format

> MTH$RANDOM seed

### RETURNS

> OpenVMS usage: | floating_point
> type: | F_floating
> access: | write only
> mechanism: | by value

> MTH$RANDOM returns an F-floating random number.

### Argument

> #### seed

> OpenVMS usage: | longword_unsigned
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> The integer seed, a 32-bit number whose high-order 24 bits are converted by MTH$RANDOM to an F-floating random number. The seed argument is the address of an unsigned longword that contains this integer seed. The seed is modified by each call to MTH$RANDOM.

### Description

> This routine must be called again to obtain the next pseudorandom number. The seed is updated automatically.

> The result is a floating-point number that is uniformly distributed between 0.0 inclusively and 1.0 exclusively.

> There are no restrictions on the seed, although it should be initialized to different values on separate runs in order to obtain different random sequences. MTH$RANDOM uses the following method to update the seed passed as the argument:
> SEED = (69069 * SEED + 1) (modulo 232)

### Condition Value Signaled

> SS$_ROPRAND | Reserved operand. The MTH$RANDOM 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

    RAND:   PROCEDURE OPTIONS (MAIN);
    DECLARE FOR$SECNDS ENTRY (FLOAT BINARY (24))
                    RETURNS (FLOAT BINARY (24));
    DECLARE MTH$RANDOM ENTRY (FIXED BINARY (31))
                    RETURNS (FLOAT BINARY (24));
    DECLARE TIME FLOAT BINARY (24);
    DECLARE SEED FIXED BINARY (31);
    DECLARE I FIXED BINARY (7);
    DECLARE RESULT FIXED DECIMAL (2);
            /* Get floating random time value       */
    TIME = FOR$SECNDS (0E0);
            /* Convert to fixed                     */
    SEED = TIME;
            /* Generate 100 random numbers between 1 and 10 */
    DO I = 1 TO 100;
            RESULT = 1 + FIXED ( (10E0 * MTH$RANDOM (SEED) ),31 );
            PUT LIST (RESULT);
            END;
    END RAND;

> This PL/I program demonstrates the use of MTH$RANDOM. The value returned by FOR$SECNDS is used as the seed for the random-number generator to ensure a different sequence each time the program is run. The random value returned is scaled so as to represent values between 1 and 10.

> Because this program generates random numbers, the output generated will be different each time the program is executed. One example of the outut generated by this program is as follows:

>     7     4     6     5     9    10     5     5     3     8     8     1    3     1     3     2
>     4     4     2     4     4     8     3     8     9     1     7     1    8     6     9    10
>     1    10    10     6     7     3     2     2     1     2     6     6    3     9     5     8
>     6     2     3     6    10     8     5     5     4     2     8     5    9     6     4     2
>     8     5     4     9     8     7     6     6     8    10     9     5    9     4     5     7
>     1     2     2     3     6     5     2     3     4     4     8     9    2     8     5     5
>     3     8     1     5

## MTH$xREAL

> The Real Part of a Complex Number routine returns the real part of a complex number.

### Format

> MTH$REAL complex-number

> MTH$DREAL complex-number

> MTH$GREAL complex-number

> Each of the above formats accepts one of the floating-point complex types as input.

### RETURNS

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

> Real part of the complex number. MTH$REAL returns an F-floating number. MTH$DREAL returns a D-floating number. MTH$GREAL returns a G-floating number.

### Argument

> #### complex-number

> OpenVMS usage: | complex_number
> type: | F_floating complex, D_floating complex, G_floating complex
> access: | read only
> mechanism: | by reference

> The complex number whose real part is returned by MTH$xREAL. The complex-number argument is the address of this floating-point complex number. For MTH$REAL, complex-number is an F-floating complex number. For MTH$DREAL, complex-number is a D-floating complex number. For MTH$GREAL, complex-number is a G-floating complex number.

### Description

> The MTH$xREAL routines return the real part of a complex number.

### Condition Value Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xREAL 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 real
    C    part of an F-floating complex number using
    C    MTH$REAL and the Fortran random number
    C    generator RAN.
    C
    C    Declare Z as a complex value and MTH$REAL as a
    C    REAL*4 value.  MTH$REAL will return the real
    C    part of Z:   Z_NEW = MTH$REAL(Z).
    C-

            COMPLEX Z
            COMPLEX CMPLX
            REAL*4 MTH$REAL
            INTEGER M
            M = 1234567

    C+
    C    Generate a random complex number with the Fortran
    C    generic CMPLX.
    C-

            Z = CMPLX(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 *, ' It has real part',MTH$REAL(Z)
            END

> This Fortran example demonstrates the use of MTH$REAL. The output of this program is as follows:

>     The complex number z is (0.8535407,0.2043402)
>     It has real part  0.8535407

Previous | Next | Contents | Index

| privacy and legal statement |
6117PRO_012.HTML