
OpenVMS VAX RTL Mathematics (MTH$) Manual
MTH$HTANH
The Compute the Hyperbolic Tangent (HFloating Value) routine returns
the hyperbolic tangent of the input value as an Hfloating value.
Format
MTH$HTANH htanh ,floatingpointinputvalue
RETURNS
None.
Arguments
htanh
OpenVMS usage: 
floating_point 
type: 
H_floating 
access: 
write only 
mechanism: 
by reference 
Hyperbolic tangent of the value specified by
floatingpointinputvalue. The
htanh argument is the address of an Hfloating number
that is this hyperbolic tangent. MTH$HTANH writes the address of the
hyperbolic tangent into htanh.
floatingpointinputvalue
OpenVMS usage: 
floating_point 
type: 
H_floating 
access: 
read only 
mechanism: 
by reference 
The input value. The floatingpointinputvalue
argument is the address of an Hfloating 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 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$xIMAG
The Imaginary Part of a Complex Number routine returns the imaginary
part of a complex number.
Format
MTH$AIMAG complexnumber
MTH$DIMAG complexnumber
MTH$GIMAG complexnumber
Each of the above formats corresponds to one of the floatingpoint
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 complexnumber. MTH$AIMAG
returns an Ffloating number. MTH$DIMAG returns a Dfloating number.
MTH$GIMAG returns a Gfloating number.
Argument
complexnumber
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 complexnumber argument
is the address of this floatingpoint complex number. For MTH$AIMAG,
complexnumber specifies an Ffloating number. For
MTH$DIMAG, complexnumber specifies a Dfloating
number. For MTH$GIMAG, complexnumber specifies a
Gfloating 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 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 imaginary part of
C a Gfloating 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 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.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 floatingpointinputvalue
MTH$DLOG floatingpointinputvalue
MTH$GLOG floatingpointinputvalue
Each of the above formats accepts one of the floatingpoint 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 floatingpoint
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 floatingpointinputvalue.
MTH$ALOG returns an Ffloating number. MTH$DLOG returns a Dfloating
number. MTH$GLOG 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 that is this value.
For MTH$ALOG, floatingpointinputvalue specifies an
Ffloating number. For MTH$DLOG,
floatingpointinputvalue specifies a Dfloating
number. For MTH$GLOG, floatingpointinputvalue
specifies a Gfloating number.
Description
Computation of the natural logarithm routine is based on the following:
 ln(X*Y) = ln(X) + ln(Y)
 ln(1+X) = X  X^{2}/2 + X^{3}/3  X^{4}/4
...
for X < 1
 ln(X) = ln(A) + 2* (V + V^{3}/3 + V^{5}/5 +
V^{7}/7 ...)
=ln(A) + V*p(V^{2}), where V = (XA)/(X+A),
A > 0, and p(y) = 2 * (1 + y/3 + y^{2}/5 ...) For x =
2^{n}*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 = n1 and
F = 2f If n <= 0, then N = n and F = f From (1)
above it follows that:
 ln(X) = N*ln(2) + ln(F)
Based on the above relationships, zLOG is computed as follows:
 If F1 < 2^{5}, zLOG(X) = N*zLOG(2) + W + W*p(W),
where W = F1.
 Otherwise, zLOG(X) = N*zLOG(2) + zLOG(A) + V*p(V^{2}),
where V = (FA)/(F+A) and A and zLOG(A)
are obtained by table lookup.
See MTH$HLOG for the description of the Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xLOG 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$_LOGZERNEG

Logarithm of zero or negative value. Argument
floatingpointinputvalue is less than or equal to
0.0. LIB$SIGNAL copies the floatingpoint reserved operand to the
mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the
floatingpoint 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 floatingpointinputvalue.
Format
MTH$ALOG2 floatingpointinputvalue
MTH$DLOG2 floatingpointinputvalue
MTH$GLOG2 floatingpointinputvalue
Each of the above formats 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 base 2 logarithm of floatingpointinputvalue.
MTH$ALOG2 returns an Ffloating number. MTH$DLOG2 returns a Dfloating
number. MTH$GLOG2 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 that is this input
value. For MTH$ALOG2, floatingpointinputvalue
specifies an Ffloating number. For MTH$DLOG2,
floatingpointinputvalue specifies a Dfloating
number. For MTH$GLOG2, floatingpointinputvalue
specifies a Gfloating 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 Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xLOG2 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$_LOGZERNEG

Logarithm of zero or negative value. Argument
floatingpointinputvalue is less than or equal to
0.0. LIB$SIGNAL copies the floatingpoint reserved operand to the
mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the
floatingpoint 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 floatingpointinputvalue
MTH$DLOG10 floatingpointinputvalue
MTH$GLOG10 floatingpointinputvalue
Each of the above formats accepts one of the floatingpoint 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 floatingpoint
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 floatingpointinputvalue.
MTH$ALOG10 returns an Ffloating number. MTH$DLOG10 returns a
Dfloating number. MTH$GLOG10 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$ALOG10,
floatingpointinputvalue specifies an Ffloating
number. For MTH$DLOG10, floatingpointinputvalue
specifies a Dfloating number. For MTH$GLOG10,
floatingpointinputvalue specifies a Gfloating
number.
Description
The common logarithm function is computed as follows: zLOG10(X) =
zLOG10(E) * zLOG(X)
See MTH$HLOG10 for the description of the Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xLOG10 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$_LOGZERNEG

Logarithm of zero or negative value. Argument
floatingpointinputvalue is less than or equal to
0.0. LIB$SIGNAL copies the floatingpoint reserved operand to the
mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the
floatingpoint 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 Ffloating random number.
Argument
seed
OpenVMS usage: 
longword_unsigned 
type: 
longword (unsigned) 
access: 
modify 
mechanism: 
by reference 
The integer seed, a 32bit number whose highorder 24 bits are
converted by MTH$RANDOM to an Ffloating 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 floatingpoint 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 2^{32})
Condition Value Signaled
SS$_ROPRAND

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

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 randomnumber
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 complexnumber
MTH$DREAL complexnumber
MTH$GREAL complexnumber
Each of the above formats accepts one of the floatingpoint 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 Ffloating number.
MTH$DREAL returns a Dfloating number. MTH$GREAL returns a Gfloating
number.
Argument
complexnumber
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
complexnumber argument is the address of this
floatingpoint complex number. For MTH$REAL,
complexnumber is an Ffloating complex number. For
MTH$DREAL, complexnumber is a Dfloating complex
number. For MTH$GREAL, complexnumber is a Gfloating
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 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 real
C part of an Ffloating 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

