OpenVMS RTL General Purpose (OTS$) Manual

Updated: 11 December 1998

OpenVMS RTL General Purpose (OTS$) Manual

Contents

Index

OTS$MOVE5

The Move Data with Fill routine moves up to 2³² - 1 bytes (2,147,483,647 bytes) from a specified source address to a specified destination address, with separate source and destination lengths, and with fill. Overlap of the source and destination arrays does not affect the result.

Format

OTS$MOVE5 longword-int-source-length ,source-array ,fill-value ,longword-int-dest-length ,destination-array

Corresponding JSB Entry Point

OTS$MOVE5_R5

RETURNS

None.

Arguments

longword-int-source-length

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by value

Number of bytes of data to move. The longword-int-source-length argument is a signed longword that contains this number. The value of longword-int-source-length may range from 0 to 2,147,483,647.
source-array

OpenVMS usage: vector_byte_unsigned

type: byte (unsigned)

access: read only

mechanism: by reference, array reference

Data to be moved by OTS$MOVE5. The source-array argument contains the address of an unsigned byte array that contains this data.
fill-value

OpenVMS usage: byte_unsigned

type: byte (unsigned)

access: read only

mechanism: by value

Character used to pad the source data if longword-int-source-length is less than longword-int-dest-length. The fill-value argument contains the address of an unsigned byte that is this character.

longword-int-dest-length

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by value

Size of the destination area in bytes. The longword-int-dest-length argument is a signed longword containing this size. The value of longword-int-dest-length may range from 0 through 2,147,483,647.
destination-array

OpenVMS usage: vector_byte_unsigned

type: byte (unsigned)

access: write only

mechanism: by reference, array reference

Address into which source-array is moved. The destination-array argument is the address of an unsigned byte array into which OTS$MOVE5 writes the source data.

Description

OTS$MOVE5 performs the same function as the VAX MOVC5 instruction except that the longword-int-source-length and longword-int-dest-length arguments are longword integers rather than word integers. When called from the JSB entry point, the register outputs of OTS$MOVE5_R5 follow the same pattern as those of the MOVC5 instruction:

R0 Number of unmoved bytes remaining in source string

R1 Address of one byte beyond the source string

R2 0

R3 Address of one byte beyond the destination string

R4 0

R5 0

For more information, see the description of the MOVC5 instruction in the VAX Architecture Reference Manual. See also the routine LIB$MOVC5, which is a callable version of the MOVC5 instruction.

Condition Values Returned

None.

OTS$MULCx

The Complex Multiplication routines calculate the complex product of two complex values.

Format

OTS$MULCD_R3 complex-multiplier ,complex-multiplicand (VAX only)

OTS$MULCG_R3 complex-multiplier ,complex-multiplicand

These formats correspond to the D-floating and G-floating complex types.

RETURNS

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: write only

mechanism: by value

Complex result of multiplying two complex numbers. OTS$MULCD_R3 returns a D-floating complex number. OTS$MULCG_R3 returns a G-floating complex number.

Arguments

complex-multiplier

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex multiplier. The complex-multiplier argument contains the complex multiplier. For OTS$MULCD_R3, complex-multiplier is a D-floating complex number. For OTS$MULCG_R3, complex-multiplier is a G-floating complex number.
complex-multiplicand

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex multiplicand. The complex-multiplicand argument contains the complex multiplicand. For OTS$MULCD_R3, complex-multiplicand is a D-floating complex number. For OTS$MULCG_R3, complex-multiplicand is a G-floating complex number.

Description

OTS$MULCD_R3 and OTS$MULCG_R3 calculate the complex product of two complex values.
The complex product is computed as follows:

Let (a,b) represent the complex multiplier.
Let (c,d) represent the complex multiplicand.
Let (r,i) represent the complex product.

The results of this computation are as follows:
____ (a,b) * (c,d) = (ac-bd) + /(-1)(ad+bc) \/ Therefore: r = ac - bd Therefore: i = ad + bc
On Alpha systems, some restrictions apply when linking OTS$MULCG_R3. See Chapter 1 for more information about these restrictions.

Condition Values Signaled

SS$_FLTOVF_F Floating value overflow can occur.

SS$_ROPRAND Reserved operand. OTS$MULCx encountered a floating-point reserved operand because of incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of zero. Floating-point reserved operands are reserved for future use by Digital.

Example


C+ C This Fortran example forms the product of C two complex numbers using OTS$MULCD_R3 C and the Fortran random number generator RAN. C C Declare Z1, Z2, and Z_Q as complex values. OTS$MULCD_R3 C returns the complex product of Z1 times Z2: C Z_Q = Z1 * Z2 C- COMPLEX16 Z1,Z2,Z_Q C+ C Generate a complex number. C- Z1 = (8.0,4.0) C+ C Generate another complex number. C- Z2 = (2.0,3.0) C+ C Compute the complex product of Z1Z2. C- Z_Q = Z1 * Z2 TYPE , ' The complex product of',Z1,' times ',Z2,' is' TYPE , ' ',Z_Q END

C+ 
C    This Fortran example forms the product of 
C    two complex numbers using OTS$MULCD_R3 
C    and the Fortran random number generator RAN. 
C 
C    Declare Z1, Z2, and Z_Q as complex values. OTS$MULCD_R3 
C    returns the complex product of Z1 times Z2: 
C    Z_Q = Z1 * Z2 
C- 
 
        COMPLEX*16 Z1,Z2,Z_Q 
C+ 
C    Generate a complex number. 
C- 
        Z1 = (8.0,4.0) 
C+ 
C    Generate another complex number. 
C- 
        Z2 = (2.0,3.0) 
C+ 
C    Compute the complex product of Z1*Z2. 
C- 
        Z_Q = Z1 * Z2 
        TYPE *, ' The complex product of',Z1,' times ',Z2,' is' 
        TYPE *, '     ',Z_Q 
        END

This Fortran example uses OTS$MULCD_R3 to multiply two complex numbers. The output generated by this program is as follows:
The complex product of (8.000000000000000,4.000000000000000) times (2.000000000000000,3.000000000000000) is (4.000000000000000,32.00000000000000)

OTS$POWCxCx

The Raise a Complex Base to a Complex Floating-Point Exponent routines raise a complex base to a complex exponent.

Format

OTS$POWCC complex-base ,complex-exponent-value

OTS$POWCDCD_R3 complex-base ,complex-exponent-value (VAX only)

OTS$POWCGCG_R3 complex-base ,complex-exponent-value

Each of these three formats corresponds to one of the three floating-point complex types.

RETURNS

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: write only

mechanism: by value

Result of raising a complex base to a complex exponent. OTS$POWCC returns an F-floating complex number. OTS$POWCDCD_R3 returns a D-floating complex number. OTS$POWCGCG_R3 returns a G-floating complex number.

Arguments

complex-base

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex base. The complex-base argument contains the value of the base. For OTS$POWCC, complex-base is an F-floating complex number. For OTS$POWCDCD_R3, complex-base is a D-floating complex number. For OTS$POWCGCG_R3, complex-base is a G-floating complex number.
complex-exponent-value

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex exponent. The complex-exponent-value argument contains the value of the exponent. For OTS$POWCC, complex-exponent-value is an F-floating complex number. For OTS$POWCDCD_R3, complex-exponent-value is a D-floating complex number. For OTS$POWCGCG_R3, complex-exponent-value is a G-floating complex number.

Description

OTS$POWCC, OTS$POWCDCD_R3 and OTS$POWCGCG_R3 raise a complex base to a complex exponent. The American National Standard FORTRAN-77 (ANSI X3.9--1978) defines complex exponentiation as follows:
x^y = exp(y * log(x))
In this example, x and y are type COMPLEX.
On Alpha systems, some restrictions apply when linking OTS$POWCC or OTS$POWCGCG_R3. See Chapter 1 for more information about these restrictions.

Condition Values Signaled

MTH$_INVARGMAT Invalid argument in math library. Base is (0.,0.).

MTH$_FLOOVEMAT Floating-point overflow in math library.

SS$_ROPRAND Reserved operand.

Examples

#1
C+ C This Fortran example raises a complex base to a complex C power using OTS$POWCC. C C Declare Z1, Z2, Z3, and OTS$POWCC as complex values. Then OTS$POWCC C returns the complex result of Z1Z2: Z3 = OTS$POWCC(Z1,Z2), C where Z1 and Z2 are passed by value. C- COMPLEX Z1,Z2,Z3,OTS$POWCC C+ C Generate a complex base. C- Z1 = (2.0,3.0) C+ C Generate a complex power. C- Z2 = (1.0,2.0) C+ C Compute the complex value of Z1Z2. C- Z3 = OTS$POWCC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), + %VAL(REAL(Z2)), %VAL(AIMAG(Z2))) TYPE , ' The value of',Z1,'*',Z2,' is',Z3 END

C+ 
C    This Fortran example raises a complex base to a complex 
C    power using OTS$POWCC. 
C 
C    Declare Z1, Z2, Z3, and OTS$POWCC as complex values. Then OTS$POWCC 
C    returns the complex result of Z1**Z2:   Z3 = OTS$POWCC(Z1,Z2), 
C    where Z1 and Z2 are passed by value. 
C- 
 
        COMPLEX Z1,Z2,Z3,OTS$POWCC 
C+ 
C    Generate a complex base. 
C- 
        Z1 = (2.0,3.0) 
C+ 
C    Generate a complex power. 
C- 
        Z2 = (1.0,2.0) 
C+ 
C    Compute the complex value of Z1**Z2. 
C- 
        Z3 = OTS$POWCC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), 
     +                  %VAL(REAL(Z2)), %VAL(AIMAG(Z2))) 
        TYPE *, ' The value of',Z1,'**',Z2,' is',Z3 
        END

This Fortran example uses OTS$POWCC to raise an F-floating complex base to an F-floating complex exponent.
The output generated by this program is as follows:
The value of (2.000000,3.000000)** (1.000000,2.000000) is (-0.4639565,-0.1995301)

#2
C+ C This Fortran example raises a complex base to a complex C power using OTS$POWCGCG_R3. C C Declare Z1, Z2, and Z3 as complex values. OTS$POWCGCG_R3 C returns the complex result of Z1Z2: Z3 = Z1Z2. C- COMPLEX16 Z1,Z2,Z3 C+ C Generate a complex base. C- Z1 = (2.0,3.0) C+ C Generate a complex power. C- Z2 = (1.0,2.0) C+ C Compute the complex value of Z1Z2. C- Z3 = Z1Z2 TYPE 1,Z1,Z2,Z3 1 FORMAT(' The value of (',F11.8,',',F11.8,')*(',F11.8, + ',',F11.8,') is (',F11.8,',',F11.8,').') END

C+ 
C    This Fortran example raises a complex base to a complex 
C    power using OTS$POWCGCG_R3. 
C 
C    Declare Z1, Z2, and Z3 as complex values. OTS$POWCGCG_R3 
C    returns the complex result of Z1**Z2: Z3 = Z1**Z2. 
C- 
 
        COMPLEX*16 Z1,Z2,Z3 
C+ 
C    Generate a complex base. 
C- 
        Z1 = (2.0,3.0) 
C+ 
C    Generate a complex power. 
C- 
        Z2 = (1.0,2.0) 
C+ 
C    Compute the complex value of Z1**Z2. 
C- 
        Z3 = Z1**Z2 
        TYPE 1,Z1,Z2,Z3 
   1    FORMAT(' The value of (',F11.8,',',F11.8,')**(',F11.8, 
     +  ',',F11.8,') is (',F11.8,',',F11.8,').') 
        END

This Fortran example program shows how to use OTS$POWCGCG_R3. Notice the high precision in the output generated by this program:
The value of ( 2.00000000, 3.00000000)**( 1.00000000, 2.00000000) is (-0.46395650,-0.46395650).

OTS$POWCxJ

The Raise a Complex Base to a Signed Longword Integer Exponent routines return the complex result of raising a complex base to an integer exponent.

Format

OTS$POWCJ complex-base ,longword-integer-exponent

OTS$POWCDJ_R3 complex-base ,longword-integer-exponent (VAX only)

OTS$POWCGJ_R3 complex-base ,longword-integer-exponent (VAX only)

Each of these three formats corresponds to one of the three floating-point complex types.

RETURNS

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: write only

mechanism: by value

Complex result of raising a complex base to an integer exponent. OTS$POWCJ returns an F-floating complex number. OTS$POWCDJ_R3 returns a D-floating complex number. OTS$POWCGJ_R3 returns a G-floating complex number. In each format, the result and base are of the same data type.

Arguments

complex-base

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex base. The complex-base argument contains the complex base. For OTS$POWCJ, complex-base is an F-floating complex number. For OTS$POWCDJ_R3, complex-base is a D-floating complex number. For OTS$POWCGJ_R3, complex-base is a G-floating complex number.
longword-integer-exponent

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by value

Exponent. The longword-integer-exponent argument is a signed longword containing the exponent.

Description

OTS$POWCJ, OTS$POWCDJ_R3, and OTS$POWCGJ_R3 return the complex result of raising a complex base to an integer exponent. The complex result is as follows:

Base Exponent Result

Any > 0 The product of (base**2 ⁱ ), where i is each nonzero bit in longword-integer-exponent.

(0.,0.) <= 0 Undefined exponentiation.

Not (0.,0.) < 0 The product of (base**2 ⁱ ), where i is each nonzero bit in longword-integer-exponent.

Not (0.,0.) 0 (1.0,0.0)

On Alpha systems, some restrictions apply when linking OTS$POWCJ. See Chapter 1 for more information about these restrictions.

Base	Exponent	Result
Any	> 0	The product of (base2 ⁱ ), where i is each nonzero bit in longword-integer-exponent**.
(0.,0.)	<= 0	Undefined exponentiation.
Not (0.,0.)	< 0	The product of (base2 ⁱ ), where i is each nonzero bit in longword-integer-exponent**.
Not (0.,0.)	0	(1.0,0.0)

Condition Values Signaled

SS$_FLTDIV Floating-point division by zero.

SS$_FLTOVF Floating-point overflow.

MTH$_UNDEXP Undefined exponentiation.

Example


C+ C This Fortran example raises a complex base to C a NONNEGATIVE integer power using OTS$POWCJ. C C Declare Z1, Z2, Z3, and OTS$POWCJ as complex values. C Then OTS$POWCJ returns the complex result of C Z1Z2: Z3 = OTS$POWCJ(Z1,Z2), C where Z1 and Z2 are passed by value. C- COMPLEX Z1,Z3,OTS$POWCJ INTEGER Z2 C+ C Generate a complex base. C- Z1 = (2.0,3.0) C+ C Generate an integer power. C- Z2 = 2 C+ C Compute the complex value of Z1Z2. C- Z3 = OTS$POWCJ( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(Z2)) TYPE 1,Z1,Z2,Z3 1 FORMAT(' The value of (',F10.8,',',F11.8,')**',I1,' is + (',F11.8,',',F12.8,').') END

C+ 
C    This Fortran example raises a complex base to 
C    a NONNEGATIVE integer power using OTS$POWCJ. 
C 
C    Declare Z1, Z2, Z3, and OTS$POWCJ as complex values. 
C    Then OTS$POWCJ returns the complex result of 
C    Z1**Z2:   Z3 = OTS$POWCJ(Z1,Z2), 
C    where Z1 and Z2 are passed by value. 
C- 
        COMPLEX Z1,Z3,OTS$POWCJ 
        INTEGER Z2 
C+ 
C    Generate a complex base. 
C- 
        Z1 = (2.0,3.0) 
C+ 
C    Generate an integer power. 
C- 
        Z2 = 2 
 
C+ 
C    Compute the complex value of Z1**Z2. 
C- 
        Z3 = OTS$POWCJ( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(Z2)) 
        TYPE 1,Z1,Z2,Z3 
  1     FORMAT(' The value of (',F10.8,',',F11.8,')**',I1,' is 
     +  (',F11.8,',',F12.8,').') 
        END

The output generated by this Fortran program is as follows:
The value of (2.00000000, 3.00000000)**2 is (-5.00000000, 12.00000000).

OTS$POWDD

The Raise a D-Floating Base to a D-Floating Exponent routine raises a D-floating base to a D-floating exponent.

Format

OTS$POWDD D-floating-point-base ,D-floating-point-exponent

RETURNS

OpenVMS usage: floating_point

type: D_floating

access: write only

mechanism: by value

Result of raising a D-floating base to a D-floating exponent.

Arguments

D-floating-point-base

OpenVMS usage: floating_point

type: D_floating

access: read only

mechanism: by value

Base. The D-floating-point-base argument is a D-floating number containing the base.
D-floating-point-exponent

OpenVMS usage: floating_point

type: D_floating

access: read only

mechanism: by value

Exponent. The D-floating-point-exponent argument is a D-floating number that contains the exponent.

Description

OTS$POWDD raises a D-floating base to a D-floating exponent.
The internal calculations and the floating-point result have the same precision as the base value.
The D-floating result for OTS$POWDD is given by the following:

Base Exponent Result

= 0 > 0 0.0

= 0 = 0 Undefined exponentiation

= 0 < 0 Undefined exponentiation

< 0 Any Undefined exponentiation

> 0 > 0 2 ^{[
exponent*log2(
base)]}

> 0 = 0 1.0

> 0 < 0 2 ^{[
exponent*log2(
base)]}

Floating-point overflow can occur.
Undefined exponentiation occurs if the base is zero and the exponent is zero or negative, or if the base is negative.

Base	Exponent	Result
= 0	> 0	0.0
= 0	= 0	Undefined exponentiation
= 0	< 0	Undefined exponentiation
< 0	Any	Undefined exponentiation
> 0	> 0	2 ^{[ exponent*log2( base)]}
> 0	= 0	1.0
> 0	< 0	2 ^{[ exponent*log2( base)]}

Condition Values Signaled

MTH$_FLOOVEMAT Floating-point overflow in math library.

MTH$_FLOUNDMAT Floating-point underflow in math library.

MTH$_UNDEXP Undefined exponentiation. This error is signaled if D-floating-point-base is zero and D-floating-point-exponent is zero or negative, or if the D-floating-point-base is negative.

Contents

Index

Legal

 
5933PRO_005.HTML

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by value

OpenVMS usage:	vector_byte_unsigned
type:	byte (unsigned)
access:	read only
mechanism:	by reference, array reference

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	read only
mechanism:	by value

R0	Number of unmoved bytes remaining in source string
R1	Address of one byte beyond the source string
R2	0
R3	Address of one byte beyond the destination string
R4	0
R5	0

OpenVMS usage:	complex_number
type:	D_floating complex, G_floating complex
access:	write only
mechanism:	by value

SS$_FLTOVF_F	Floating value overflow can occur.
SS$_ROPRAND	Reserved operand. OTS$MULCx encountered a floating-point reserved operand because of incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of zero. Floating-point reserved operands are reserved for future use by Digital.

MTH$_INVARGMAT	Invalid argument in math library. Base is (0.,0.).
MTH$_FLOOVEMAT	Floating-point overflow in math library.
SS$_ROPRAND	Reserved operand.

SS$_FLTDIV	Floating-point division by zero.
SS$_FLTOVF	Floating-point overflow.
MTH$_UNDEXP	Undefined exponentiation.

OpenVMS usage:	floating_point
type:	D_floating
access:	write only
mechanism:	by value

MTH$_FLOOVEMAT	Floating-point overflow in math library.
MTH$_FLOUNDMAT	Floating-point underflow in math library.
MTH$_UNDEXP	Undefined exponentiation. This error is signaled if D-floating-point-base is zero and D-floating-point-exponent is zero or negative, or if the D-floating-point-base is negative.