HP OpenVMS Systems Documentation

OpenVMS RTL General Purpose (OTS$) Manual

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

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-

        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

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)

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.

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

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