OpenVMS RTL General Purpose (OTS$) Manual

Updated: 11 December 1998

OpenVMS RTL General Purpose (OTS$) Manual

Contents

Index

OTS$DIVCx

The Complex Division routines return a complex result of a division on complex numbers.

Format

OTS$DIVC complex-dividend ,complex-divisor

OTS$DIVCD_R3 complex-dividend ,complex-divisor (VAX only)

OTS$DIVCG_R3 complex-dividend ,complex-divisor

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 complex division. OTS$DIVC returns an F-floating complex number. OTS$DIVCD_R3 returns a D-floating complex number. OTS$DIVCG_R3 returns a G-floating complex number.

Arguments

complex-dividend

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex dividend. The complex-dividend argument contains a floating-point complex value. For OTS$DIVC, complex-dividend is an F-floating complex number. For OTS$DIVCD_R3, complex-dividend is a D-floating complex number. For OTS$DIVCG_R3, complex-dividend is a G-floating complex number.
complex-divisor

OpenVMS usage: complex_number

type: F_floating complex, D_floating complex, G_floating complex

access: read only

mechanism: by value

Complex divisor. The complex-divisor argument contains the value of the divisor. For OTS$DIVC, complex-divisor is an F-floating complex number. For OTS$DIVCD_R3, complex-divisor is a D-floating complex number. For OTS$DIVCG_R3, complex-divisor is a G-floating 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² + d²) i = (bc - ad)/(c² + d²)
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. Floating-point division by zero.

SS$_FLTOVF_F Arithmetic fault. Floating-point 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

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- 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 = (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

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 fixed-point 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 packed-decimal-dividend ,packed-decimal-divisor ,divisor-precision ,packed-decimal-quotient ,quotient-precision ,precision-data ,scale-data

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

packed-decimal-dividend

OpenVMS usage: varying_arg

type: packed decimal string

access: read only

mechanism: by reference

Dividend. The packed-decimal-dividend argument is the address of a packed decimal string that contains the shifted dividend.
Before being passed as input, the packed-decimal-dividend argument is always multiplied by 10^c, where c is defined as follows:
c = 31 - prec(packed-decimal-dividend)
Multiplying packed-decimal-dividend by 10^c makes packed-decimal-dividend a 31-digit number.
packed-decimal-divisor

OpenVMS usage: varying_arg

type: packed decimal string

access: read only

mechanism: by reference

Divisor. The packed-decimal-divisor argument is the address of a packed decimal string that contains the divisor.
divisor-precision

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Precision of the divisor. The divisor-precision argument is a signed word that contains the precision of the divisor. The high-order bits are filled with zeros.
packed-decimal-quotient

OpenVMS usage: varying_arg

type: packed decimal string

access: write only

mechanism: by reference

Quotient. The packed-decimal-quotient argument is the address of the packed decimal string into which OTS$DIV_PK_LONG writes the quotient.
quotient-precision

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Precision of the quotient. The quotient-precision argument is a signed word that contains the precision of the quotient. The high-order bits are filled with zeros.
precision-data

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Additional digits of precision required. The precision-data argument is a signed word that contains the value of the additional digits of precision required.
OTS$DIV_PK_LONG computes the precision-data argument as follows:
precision-data = scale(packed-decimal-quotient) + scale(packed-decimal-divisor) - scale(packed-decimal-dividend) - 31 + prec(packed-decimal-dividend)
scale-data

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Scale factor of the decimal point. The scale-data argument is a signed word that contains the scale data.
OTS$DIV_PK_LONG defines the scale-data argument as follows:
scale-data = 31 - prec(packed-decimal-divisor)

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(packed-decimal-quotient) + scale(packed-decimal-divisor) - scale(packed-decimal-dividend) + prec(packed-decimal-dividend)
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 scale-data. If scale-data is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If scale-data 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 ! ! prec-data = scale(quot) + scale(divr) - scale(divd) - 31 + ! prec(divd) ! prec-data = 5 + 3 - 2 - 31 + 31 ! prec-data = 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 ! ! scale-data = 31 - prec(divr) ! scale-data = 31 - 30 ! scale-data = 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. ! ! scale-data 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

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 
    ! 
    !   prec-data  = scale(quot) + scale(divr) - scale(divd) - 31 + 
    !                prec(divd) 
    !   prec-data  =   5      +   3      -     2    - 31 +   31 
    !   prec-data  = 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 
    ! 
    !   scale-data = 31 - prec(divr) 
    !   scale-data = 31 -   30 
    !   scale-data = 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. 
    ! 
    !   scale-data 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 fixed-point decimal data when precision and scale requirements for the quotient call for multiple-precision division.

Format

OTS$DIV_PK_SHORT packed-decimal-dividend ,packed-decimal-divisor ,divisor-precision ,packed-decimal-quotient ,quotient-precision ,precision-data

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

packed-decimal-dividend

OpenVMS usage: varying_arg

type: packed decimal string

access: read only

mechanism: by reference

Dividend. The packed-decimal-dividend argument is the address of a packed decimal string that contains the shifted dividend.
Before being passed as input, the packed-decimal-dividend argument is always multiplied by 10^c, where c is defined as follows:
c = 31 - prec(packed-decimal-dividend)
Multiplying packed-decimal-dividend by 10^c makes packed-decimal-dividend a 31-digit number.
packed-decimal-divisor

OpenVMS usage: varying_arg

type: packed decimal string

access: read only

mechanism: by reference

Divisor. The packed-decimal-divisor argument is the address of a packed decimal string that contains the divisor.
divisor-precision

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Precision of the divisor. The divisor-precision argument is a signed word integer that contains the precision of the divisor; high-order bits are filled with zeros.
packed-decimal-quotient

OpenVMS usage: varying_arg

type: packed decimal string

access: write only

mechanism: by reference

Quotient. The packed-decimal-quotient argument is the address of a packed decimal string into which OTS$DIV_PK_SHORT writes the quotient.
quotient-precision

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Precision of the quotient. The quotient-precision argument is a signed word that contains the precision of the quotient; high-order bits are filled with zeros.
precision-data

OpenVMS usage: word_signed

type: word (signed)

access: read only

mechanism: by value

Additional digits of precision required. The precision-data argument is a signed word that contains the value of the additional digits of precision required.
OTS$DIV_PK_SHORT computes the precision-data argument as follows:
precision-data = scale(packed-decimal-quotient) + scale(packed-decimal-divisor) - scale(packed-decimal-dividend) - 31 + prec(packed-decimal-dividend)

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(packed-decimal-quotient) + scale(packed-decimal-divisor) - scale(packed-decimal-dividend) + prec(packed-decimal-dividend)
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 scale-data. If scale-data is less than or equal to 1, then you should use OTS$DIV_PK_LONG. If scale-data 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³² - 1 bytes (2,147,483,647 bytes) from a specified source address to a specified destination address.

Format

OTS$MOVE3 length-value ,source-array ,destination-array

Corresponding JSB Entry Point

OTS$MOVE3_R5

RETURNS

None.

Arguments

length-value

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by value

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

OpenVMS usage: vector_byte_unsigned

type: byte (unsigned)

access: read only

mechanism: by reference, array reference

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

OpenVMS usage: vector_byte_unsigned

type: byte (unsigned)

access: write only

mechanism: by reference, array reference

Address into which source-array will be moved. The destination-array 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 length-value 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

None.

Contents

Index

Legal

 
5933PRO_004.HTML

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

SS$_FLTDIV_F	Arithmetic fault. Floating-point division by zero.
SS$_FLTOVF_F	Arithmetic fault. Floating-point overflow.

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	varying_arg
type:	packed decimal string
access:	read only
mechanism:	by reference

OpenVMS usage:	word_signed
type:	word (signed)
access:	read only
mechanism:	by value

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

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