[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS RTL General Purpose (OTS$) Manual


Previous Contents Index


OTS$MOVE5

The Move Data with Fill routine moves up to 232 - 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:

  1. Let (a,b) represent the complex multiplier.
  2. Let (c,d) represent the complex multiplicand.
  3. 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- 
 
        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:


          xy = 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 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 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 i ), where i is each nonzero bit in longword-integer-exponent.
(0.,0.) <= 0 Undefined exponentiation.
Not (0.,0.) < 0 The product of (base**2 i ), 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.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5933PRO_005.HTML