
OpenVMS RTL General Purpose (OTS$) Manual
OTS$MOVE5
The Move Data with Fill routine moves up to 2^{32}  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 longwordintsourcelength ,sourcearray ,fillvalue
,longwordintdestlength ,destinationarray
Corresponding JSB Entry Point
OTS$MOVE5_R5
RETURNS
None.
Arguments
longwordintsourcelength
OpenVMS usage: 
longword_signed 
type: 
longword (signed) 
access: 
read only 
mechanism: 
by value 
Number of bytes of data to move. The
longwordintsourcelength argument is a signed
longword that contains this number. The value of
longwordintsourcelength may range from 0 to
2,147,483,647.
sourcearray
OpenVMS usage: 
vector_byte_unsigned 
type: 
byte (unsigned) 
access: 
read only 
mechanism: 
by reference, array reference 
Data to be moved by OTS$MOVE5. The sourcearray
argument contains the address of an unsigned byte array that contains
this data.
fillvalue
OpenVMS usage: 
byte_unsigned 
type: 
byte (unsigned) 
access: 
read only 
mechanism: 
by value 
Character used to pad the source data if
longwordintsourcelength is less than
longwordintdestlength. The
fillvalue argument contains the address of an
unsigned byte that is this character.
longwordintdestlength
OpenVMS usage: 
longword_signed 
type: 
longword (signed) 
access: 
read only 
mechanism: 
by value 
Size of the destination area in bytes. The
longwordintdestlength argument is a signed longword
containing this size. The value of
longwordintdestlength may range from 0 through
2,147,483,647.
destinationarray
OpenVMS usage: 
vector_byte_unsigned 
type: 
byte (unsigned) 
access: 
write only 
mechanism: 
by reference, array reference 
Address into which sourcearray is moved. The
destinationarray 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 longwordintsourcelength and
longwordintdestlength 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
OTS$MULCx
The Complex Multiplication routines calculate the complex product of
two complex values.
Format
OTS$MULCD_R3 complexmultiplier ,complexmultiplicand (VAX only)
OTS$MULCG_R3 complexmultiplier ,complexmultiplicand
These formats correspond to the Dfloating and Gfloating 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 Dfloating complex number. OTS$MULCG_R3 returns a Gfloating complex
number.
Arguments
complexmultiplier
OpenVMS usage: 
complex_number 
type: 
D_floating complex, G_floating complex 
access: 
read only 
mechanism: 
by value 
Complex multiplier. The complexmultiplier argument
contains the complex multiplier. For OTS$MULCD_R3,
complexmultiplier is a Dfloating complex number. For
OTS$MULCG_R3, complexmultiplier is a Gfloating
complex number.
complexmultiplicand
OpenVMS usage: 
complex_number 
type: 
D_floating complex, G_floating complex 
access: 
read only 
mechanism: 
by value 
Complex multiplicand. The complexmultiplicand
argument contains the complex multiplicand. For OTS$MULCD_R3,
complexmultiplicand is a Dfloating complex number.
For OTS$MULCG_R3, complexmultiplicand is a Gfloating
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) = (acbd) + /(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 floatingpoint reserved
operand because of incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of zero. Floatingpoint 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 FloatingPoint Exponent routines
raise a complex base to a complex exponent.
Format
OTS$POWCC complexbase ,complexexponentvalue
OTS$POWCDCD_R3 complexbase ,complexexponentvalue (VAX only)
OTS$POWCGCG_R3 complexbase ,complexexponentvalue
Each of these three formats corresponds to one of the three
floatingpoint 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 Ffloating complex number. OTS$POWCDCD_R3 returns a
Dfloating complex number. OTS$POWCGCG_R3 returns a Gfloating complex
number.
Arguments
complexbase
OpenVMS usage: 
complex_number 
type: 
F_floating complex, D_floating complex, G_floating
complex 
access: 
read only 
mechanism: 
by value 
Complex base. The complexbase argument contains the
value of the base. For OTS$POWCC, complexbase is an
Ffloating complex number. For OTS$POWCDCD_R3,
complexbase is a Dfloating complex number. For
OTS$POWCGCG_R3, complexbase is a Gfloating complex
number.
complexexponentvalue
OpenVMS usage: 
complex_number 
type: 
F_floating complex, D_floating complex, G_floating
complex 
access: 
read only 
mechanism: 
by value 
Complex exponent. The complexexponentvalue argument
contains the value of the exponent. For OTS$POWCC,
complexexponentvalue is an Ffloating complex
number. For OTS$POWCDCD_R3, complexexponentvalue is
a Dfloating complex number. For OTS$POWCGCG_R3,
complexexponentvalue is a Gfloating complex number.
Description
OTS$POWCC, OTS$POWCDCD_R3 and OTS$POWCGCG_R3 raise a complex base to a
complex exponent. The American National Standard FORTRAN77 (ANSI
X3.91978) defines complex exponentiation as follows:
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

Floatingpoint 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 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 Ffloating complex base
to an Ffloating 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 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 complexbase ,longwordintegerexponent
OTS$POWCDJ_R3 complexbase ,longwordintegerexponent (VAX only)
OTS$POWCGJ_R3 complexbase ,longwordintegerexponent (VAX only)
Each of these three formats corresponds to one of the three
floatingpoint 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 Ffloating complex number. OTS$POWCDJ_R3 returns a
Dfloating complex number. OTS$POWCGJ_R3 returns a Gfloating complex
number. In each format, the result and base are of the same data type.
Arguments
complexbase
OpenVMS usage: 
complex_number 
type: 
F_floating complex, D_floating complex, G_floating
complex 
access: 
read only 
mechanism: 
by value 
Complex base. The complexbase argument contains the
complex base. For OTS$POWCJ, complexbase is an
Ffloating complex number. For OTS$POWCDJ_R3,
complexbase is a Dfloating complex number. For
OTS$POWCGJ_R3, complexbase is a Gfloating complex
number.
longwordintegerexponent
OpenVMS usage: 
longword_signed 
type: 
longword (signed) 
access: 
read only 
mechanism: 
by value 
Exponent. The longwordintegerexponent 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
^{
i
}
), where
i is each nonzero bit in
longwordintegerexponent.

(0.,0.)

<= 0

Undefined exponentiation.

Not (0.,0.)

< 0

The product of (base**2
^{
i
}
), where
i is each nonzero bit in
longwordintegerexponent.

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

Floatingpoint division by zero.

SS$_FLTOVF

Floatingpoint 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 DFloating Base to a DFloating Exponent routine raises a
Dfloating base to a Dfloating exponent.
Format
OTS$POWDD Dfloatingpointbase ,Dfloatingpointexponent
RETURNS
OpenVMS usage: 
floating_point 
type: 
D_floating 
access: 
write only 
mechanism: 
by value 
Result of raising a Dfloating base to a Dfloating exponent.
Arguments
Dfloatingpointbase
OpenVMS usage: 
floating_point 
type: 
D_floating 
access: 
read only 
mechanism: 
by value 
Base. The Dfloatingpointbase argument is a
Dfloating number containing the base.
Dfloatingpointexponent
OpenVMS usage: 
floating_point 
type: 
D_floating 
access: 
read only 
mechanism: 
by value 
Exponent. The Dfloatingpointexponent argument is a
Dfloating number that contains the exponent.
Description
OTS$POWDD raises a Dfloating base to a Dfloating exponent.
The internal calculations and the floatingpoint result have the same
precision as the base value.
The Dfloating 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)]
}

Floatingpoint 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

Floatingpoint overflow in math library.

MTH$_FLOUNDMAT

Floatingpoint underflow in math library.

MTH$_UNDEXP

Undefined exponentiation. This error is signaled if
Dfloatingpointbase is zero and
Dfloatingpointexponent is zero or negative, or if
the
Dfloatingpointbase is negative.

