
OpenVMS RTL General Purpose (OTS$) Manual
OTS$DIVCx
The Complex Division routines return a complex result of a division on
complex numbers.
Format
OTS$DIVC complexdividend ,complexdivisor
OTS$DIVCD_R3 complexdividend ,complexdivisor (VAX only)
OTS$DIVCG_R3 complexdividend ,complexdivisor
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 complex division. OTS$DIVC returns an Ffloating
complex number. OTS$DIVCD_R3 returns a Dfloating complex number.
OTS$DIVCG_R3 returns a Gfloating complex number.
Arguments
complexdividend
OpenVMS usage: 
complex_number 
type: 
F_floating complex, D_floating complex, G_floating
complex 
access: 
read only 
mechanism: 
by value 
Complex dividend. The complexdividend argument
contains a floatingpoint complex value. For OTS$DIVC,
complexdividend is an Ffloating complex number. For
OTS$DIVCD_R3, complexdividend is a Dfloating complex
number. For OTS$DIVCG_R3, complexdividend is a
Gfloating complex number.
complexdivisor
OpenVMS usage: 
complex_number 
type: 
F_floating complex, D_floating complex, G_floating
complex 
access: 
read only 
mechanism: 
by value 
Complex divisor. The complexdivisor argument contains
the value of the divisor. For OTS$DIVC,
complexdivisor is an Ffloating complex number. For
OTS$DIVCD_R3, complexdivisor is a Dfloating complex
number. For OTS$DIVCG_R3, complexdivisor is a
Gfloating complex number.
Description
These routines return a complex result of a division on complex numbers.
The complex result is computed as follows:
 Let (a,b) represent the complex dividend.
 Let (c,d) represent the complex divisor.
 Let (r,i) represent the complex quotient.
The results of this computation are as follows:
r = (ac + bd)/(c^{2} + d^{2})
i = (bc  ad)/(c^{2} + d^{2})

On Alpha systems, some restrictions apply when linking OTS$DIVC or
OTS$DIVCG_R3. See Chapter 1 for more information about these
restrictions.
Condition Values Signaled
SS$_FLTDIV_F

Arithmetic fault. Floatingpoint division by zero.

SS$_FLTOVF_F

Arithmetic fault. Floatingpoint overflow.

Examples
#1 
C+
C This Fortran example forms the complex
C quotient of two complex numbers using
C OTS$DIVC and the Fortran random number
C generator RAN.
C
C Declare Z1, Z2, Z_Q, and OTS$DIVC as complex values.
C OTS$DIVC will return the complex quotient of Z1 divided
C by Z2: Z_Q = OTS$DIVC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1),
C %VAL(REAL(Z2)), %VAL(AIMAG(Z2))
C
COMPLEX Z1,Z2,Z_Q,OTS$DIVC
C+
C Generate a complex number.
C
Z1 = (8.0,4.0)
C+
C Generate another complex number.
C
Z2 = (1.0,1.0)
C+
C Compute the complex quotient of Z1/Z2.
C
Z_Q = OTS$DIVC( %VAL(REAL(Z1)), %VAL(AIMAG(Z1)), %VAL(REAL(Z2)),
+ %VAL(AIMAG(Z2)))
TYPE *, ' The complex quotient of',Z1,' divided by ',Z2,' is'
TYPE *, ' ',Z_Q
END

This Fortran program demonstrates how to call OTS$DIVC. The output
generated by this program is as follows:
The complex quotient of (8.000000,4.000000) divided by (1.000000,1.000000)
is (6.000000,2.000000)

#2 
C+
C This Fortran example forms the complex
C quotient of two complex numbers by using
C OTS$DIVCG_R3 and the Fortran random number
C generator RAN.
C
C Declare Z1, Z2, and Z_Q as complex values. OTS$DIVCG_R3
C will return the complex quotient of Z1 divided by 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 = (1.0,1.0)
C+
C Compute the complex quotient of Z1/Z2.
C
Z_Q = Z1/Z2
TYPE *, ' The complex quotient of',Z1,' divided by ',Z2,' is'
TYPE *, ' ',Z_Q
END

This Fortran example uses the OTS$DIVCG_R3 entry point instead. Notice
the difference in the precision of the output generated:
The complex quotient of (8.000000000000000,4.000000000000000) divided by
(1.000000000000000,1.000000000000000) is
(6.000000000000000,2.000000000000000)

OTS$DIV_PK_LONG
The Packed Decimal Division with Long Divisor routine divides
fixedpoint decimal data, which is stored in packed decimal form, when
precision and scale requirements for the quotient call for multiple
precision division. The divisor must have a precision of 30 or 31
digits.
Format
OTS$DIV_PK_LONG packeddecimaldividend ,packeddecimaldivisor
,divisorprecision ,packeddecimalquotient ,quotientprecision
,precisiondata ,scaledata
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
packeddecimaldividend
OpenVMS usage: 
varying_arg 
type: 
packed decimal string 
access: 
read only 
mechanism: 
by reference 
Dividend. The packeddecimaldividend argument is the
address of a packed decimal string that contains the shifted dividend.
Before being passed as input, the
packeddecimaldividend argument is always multiplied
by 10^{c}, where c is defined as follows:
c = 31  prec(packeddecimaldividend)

Multiplying packeddecimaldividend by
10^{c} makes packeddecimaldividend
a 31digit number.
packeddecimaldivisor
OpenVMS usage: 
varying_arg 
type: 
packed decimal string 
access: 
read only 
mechanism: 
by reference 
Divisor. The packeddecimaldivisor argument is the
address of a packed decimal string that contains the divisor.
divisorprecision
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Precision of the divisor. The divisorprecision
argument is a signed word that contains the precision of the divisor.
The highorder bits are filled with zeros.
packeddecimalquotient
OpenVMS usage: 
varying_arg 
type: 
packed decimal string 
access: 
write only 
mechanism: 
by reference 
Quotient. The packeddecimalquotient argument is the
address of the packed decimal string into which OTS$DIV_PK_LONG writes
the quotient.
quotientprecision
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Precision of the quotient. The quotientprecision
argument is a signed word that contains the precision of the quotient.
The highorder bits are filled with zeros.
precisiondata
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Additional digits of precision required. The
precisiondata argument is a signed word that contains
the value of the additional digits of precision required.
OTS$DIV_PK_LONG computes the precisiondata argument
as follows:
precisiondata = scale(packeddecimalquotient)
+ scale(packeddecimaldivisor)
 scale(packeddecimaldividend)
 31 + prec(packeddecimaldividend)

scaledata
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Scale factor of the decimal point. The scaledata
argument is a signed word that contains the scale data.
OTS$DIV_PK_LONG defines the scaledata argument as
follows:
scaledata = 31  prec(packeddecimaldivisor)

Description
On VAX systems, before using this routine, you should determine whether
it is best to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the VAX
instruction DIVP. To determine this, you must first calculate
b, where b is defined as follows:
b = scale(packeddecimalquotient)
+ scale(packeddecimaldivisor)
 scale(packeddecimaldividend)
+ prec(packeddecimaldividend)

If b is greater than 31, then OTS$DIV_PK_LONG can be used to
perform the division. If b is less than 31, you could use the
instruction DIVP instead.
When using this routine on an OpenVMS Alpha system or on an OpenVMS VAX
system and you have determined that you cannot use DIVP, you need to
determine whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_SHORT.
To determine this, you must examine the value of
scaledata. If scaledata is less
than or equal to 1, then you should use OTS$DIV_PK_LONG. If
scaledata is greater than 1, you should use
OTS$DIV_PK_SHORT instead.
Condition Value Signaled
SS$_FLTDIV

Fatal error. Division by zero.

Example

1
OPTION &
TYPE = EXPLICIT
!+
! This program uses OTS$DIV_PK_LONG to perform packed decimal
! division.
!
!+
! DECLARATIONS
!
DECLARE DECIMAL (31, 2) NATIONAL_DEBT
DECLARE DECIMAL (30, 3) POPULATION
DECLARE DECIMAL (10, 5) PER_CAPITA_DEBT
EXTERNAL SUB OTS$DIV_PK_LONG (DECIMAL(31,2), DECIMAL (30, 3), &
WORD BY VALUE, DECIMAL(10, 5), WORD BY VALUE, WORD BY VALUE, &
WORD BY VALUE)
!+
! Prompt the user for the required input.
!
INPUT "Enter national debt: ";NATIONAL_DEBT
INPUT "Enter current population: ";POPULATION
!+
! Perform the division and print the result.
!
! scale(divd) = 2
! scale(divr) = 3
! scale(quot) = 5
!
! prec(divd) = 31
! prec(divr) = 30
! prec(quot) = 10
!
! precdata = scale(quot) + scale(divr)  scale(divd)  31 +
! prec(divd)
! precdata = 5 + 3  2  31 + 31
! precdata = 6
!
! b = scale(quot) + scale(divr)  scale(divd) + prec(divd)
! b = 5 + 3  2 + 31
! b = 37
!
! c = 31  prec(divd)
! c = 31  31
! c = 0
!
! scaledata = 31  prec(divr)
! scaledata = 31  30
! scaledata = 1
!
! b is greater than 31, so either OTS$DIV_PK_LONG or
! OTS$DIV_PK_SHORT may be used to perform the division.
! If b is less than or equal to 31, then the DIVP
! instruction may be used.
!
! scaledata is less than or equal to 1, so OTS$DIV_PK_LONG
! should be used instead of OTS$DIV_PK_SHORT.
!
!
CALL OTS$DIV_PK_LONG( NATIONAL_DEBT, POPULATION, '30'W, PER_CAPITA_DEBT, &
'10'W, '6'W, '1'W)
PRINT "The per capita debt is ";PER_CAPITA_DEBT
END

This BASIC example program uses OTS$DIV_PK_LONG to perform packed
decimal division. One example of the output generated by this program
is as follows:
$ RUN DEBT
Enter national debt: ? 12345678
Enter current population: ? 1212
The per capita debt is 10186.20297

OTS$DIV_PK_SHORT
The Packed Decimal Division with Short Divisor routine divides
fixedpoint decimal data when precision and scale requirements for the
quotient call for multipleprecision division.
Format
OTS$DIV_PK_SHORT packeddecimaldividend ,packeddecimaldivisor
,divisorprecision ,packeddecimalquotient ,quotientprecision
,precisiondata
RETURNS
OpenVMS usage: 
cond_value 
type: 
longword (unsigned) 
access: 
write only 
mechanism: 
by value 
Arguments
packeddecimaldividend
OpenVMS usage: 
varying_arg 
type: 
packed decimal string 
access: 
read only 
mechanism: 
by reference 
Dividend. The packeddecimaldividend argument is the
address of a packed decimal string that contains the shifted dividend.
Before being passed as input, the
packeddecimaldividend argument is always multiplied
by 10^{c}, where c is defined as follows:
c = 31  prec(packeddecimaldividend)

Multiplying packeddecimaldividend by
10^{c} makes packeddecimaldividend
a 31digit number.
packeddecimaldivisor
OpenVMS usage: 
varying_arg 
type: 
packed decimal string 
access: 
read only 
mechanism: 
by reference 
Divisor. The packeddecimaldivisor argument is the
address of a packed decimal string that contains the divisor.
divisorprecision
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Precision of the divisor. The divisorprecision
argument is a signed word integer that contains the precision of the
divisor; highorder bits are filled with zeros.
packeddecimalquotient
OpenVMS usage: 
varying_arg 
type: 
packed decimal string 
access: 
write only 
mechanism: 
by reference 
Quotient. The packeddecimalquotient argument is the
address of a packed decimal string into which OTS$DIV_PK_SHORT writes
the quotient.
quotientprecision
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Precision of the quotient. The quotientprecision
argument is a signed word that contains the precision of the quotient;
highorder bits are filled with zeros.
precisiondata
OpenVMS usage: 
word_signed 
type: 
word (signed) 
access: 
read only 
mechanism: 
by value 
Additional digits of precision required. The
precisiondata argument is a signed word that contains
the value of the additional digits of precision required.
OTS$DIV_PK_SHORT computes the precisiondata argument
as follows:
precisiondata = scale(packeddecimalquotient)
+ scale(packeddecimaldivisor)
 scale(packeddecimaldividend)
 31 + prec(packeddecimaldividend)

Description
On VAX systems, before using this routine, you should determine whether
it is best to use OTS$DIV_PK_LONG, OTS$DIV_PK_SHORT, or the VAX
instruction DIVP. To determine this, you must first calculate
b, where b is defined as follows:
b = scale(packeddecimalquotient) + scale(packeddecimaldivisor) 
scale(packeddecimaldividend) + prec(packeddecimaldividend)

If b is greater than 31, then OTS$DIV_PK_SHORT can be used to
perform the division. If b is less than 31, you could use the
VAX instruction DIVP instead.
When using this routine on an OpenVMS Alpha system or on an OpenVMS VAX
system and you have determined that you cannot use DIVP, you need to
determine whether you should use OTS$DIV_PK_LONG or OTS$DIV_PK_SHORT.
To determine this, you must examine the value of
scaledata. If scaledata is less
than or equal to 1, then you should use OTS$DIV_PK_LONG. If
scaledata is greater than 1, you should use
OTS$DIV_PK_SHORT instead.
Condition Value Signaled
SS$_FLTDIV

Fatal error. Division by zero.

OTS$MOVE3
The Move Data Without Fill routine moves up to 2^{32}  1 bytes
(2,147,483,647 bytes) from a specified source address to a specified
destination address.
Format
OTS$MOVE3 lengthvalue ,sourcearray ,destinationarray
Corresponding JSB Entry Point
OTS$MOVE3_R5
RETURNS
None.
Arguments
lengthvalue
OpenVMS usage: 
longword_signed 
type: 
longword (signed) 
access: 
read only 
mechanism: 
by value 
Number of bytes of data to move. The lengthvalue
argument is a signed longword that contains the number of bytes to
move. The value of lengthvalue may range from 0 to
2,147,483,647 bytes.
sourcearray
OpenVMS usage: 
vector_byte_unsigned 
type: 
byte (unsigned) 
access: 
read only 
mechanism: 
by reference, array reference 
Data to be moved by OTS$MOVE3. The sourcearray
argument contains the address of an unsigned byte array that contains
this data.
destinationarray
OpenVMS usage: 
vector_byte_unsigned 
type: 
byte (unsigned) 
access: 
write only 
mechanism: 
by reference, array reference 
Address into which sourcearray will be moved. The
destinationarray argument is the address of an
unsigned byte array into which OTS$MOVE3 writes the source data.
Description
OTS$MOVE3 performs the same function as the VAX MOVC3 instruction
except that the lengthvalue is a longword integer
rather than a word integer. When called from the JSB entry point, the
register outputs of OTS$MOVE3_R5 follow the same pattern as those of
the MOVC3 instruction:
R0

0

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 MOVC3 instruction in
the VAX Architecture Reference Manual. See also the routine LIB$MOVC3, which is a callable
version of the MOVC3 instruction.
Condition Values Returned
