OpenVMS VAX RTL Mathematics (MTH$) Manual

Updated: 12 December 1998

OpenVMS VAX RTL Mathematics (MTH$) Manual

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

Value of x	Hyperbolic Tangent Returned
\|X\| <= 2 ^-g	X
2 ^-g < \|X\| <= 0.25	zSINH(X)/zCOSH(X)
0.25 < \|X\| < h	(zEXP(2X) - 1)/(zEXP(2X) + 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 Digital.

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

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 REAL8 value. MTH$GIMAG will return the imaginary C part of Z: Z_NEW = MTH$GIMAG(Z). C- COMPLEX16 Z COMPLEX16 DCMPLX REAL8 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

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:

ln(X*Y) = ln(X) + ln(Y)
ln(1+X) = X - X²/2 + X³/3 - X⁴/4 ...
for |X| < 1
ln(X) = ln(A) + 2* (V + V³/3 + V⁵/5 + V⁷/7 ...)
=ln(A) + V*p(V²), where V = (X-A)/(X+A),
A > 0, and p(y) = 2 * (1 + y/3 + y²/5 ...)
For x = 2ⁿ*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:
ln(X) = N*ln(2) + ln(F)

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

If |F-1| < 2^-5, zLOG(X) = N*zLOG(2) + W + W*p(W),
where W = F-1.
Otherwise, zLOG(X) = N*zLOG(2) + zLOG(A) + V*p(V²),
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 Digital.

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

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

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 2³²)

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

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;

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

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 REAL4 value. MTH$REAL will return the real C part of Z: Z_NEW = MTH$REAL(Z). C- COMPLEX Z COMPLEX CMPLX REAL4 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

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

Contents

Index

Legal

 
6117PRO_012.HTML

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

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

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

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

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

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