Digital PDFs

AA-PVXJA-TE

1993

285 pages

Original

8.3MB

Document:	AA-PVXJA-TE OpenVMS VAX 6.0 RTL Mathematics MTH$ Manual 199305
Order Number:	AA-PVXJA-TE
Revision:	0
Pages:	285
Original Filename:

OCR Text

OpenVMS VAX RTL Mathematics (MTH$) Manual

Part Number: AA- PVXJA- TE

OpenVMS VAX RTL
Mathematics (MTH$) Manual
Order Number: AA-PVXJA-TE
May 1993

This manual documents the mathematics routines contained in the
MTH$ facility of the OpenVMS Run-Time Library.

Revision/Update Information:

This manual supersedes the Open VMS
VAX RTL Mathematics (MTH$)
Manual, Version 5.5.

Software Version:

OpenVMS VAX Version 6.0

Digital Equipment· Corporation
Maynard, Massachusetts

May 1993
The information in this document is subject to change without notice and should not be construed
as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or copied
only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied
by Digital Equipment Corporation or its affiliated companies.

© Digital Equipment Corporation 1993.
All Rights Reserved.
The postpaid Reader's Comments forms at the end of this document request your critical evaluation
to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation: Bookreader, Digital, OpenVMS,
VAX, VAX Ada, VAX BASIC, VAX BLISS-32, VAX C, VAX COBOL, VAX COBOL-74, VAX CORAL,
VAX DATATRIEVE, VAX DIBOL, VAX DSM, VAX FORTRAN, VAX Pascal, VAX SCAN, VMS, and
the DIGITAL logo.
ZK6117

This document was prepared using VAX DOCUMENT, Version 2.1.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vii

1 Introduction to MTH$
1.1

1.2

1.3
1.4
1.5
1.6
1.7
1.7.1
1.7.2
1.7.3
1.7.4
1.7.5
1.7.6
1.7.7

Entry Point Names ......................................... .
Calling Conventions ......................................... .
Algorithms ................................................ .
Condition Handling ......................................... .
Complex Numbers .......................................... .
Mathematics Routines Not Documented in the MTH$ Reference
Section ................................................... .
Examples of Calls to Run-Time Library Mathematics Routines ........ .
BASIC Example ......................................... .
COBOL Example ........................................ .
FORTRAN Examples ..................................... .
MACRO Examples ....................................... .
Pascal Examples ........................................ .
PL/I Examples .......................................... .
Ada Example ........................................... .

1-1

1-2

1-3
1-3
1-3
1-4

1-9
1-9
1-9
1-10

1-11
1-14
1-15
1-16

2 Vector Routines in MTH$
2.1
BLAS - Basic Linear Algebra Subroutines Level 1 ................ .
2.1.1
Using BLAS Level 1 ...................................... .
2.1.1.1
Memory Overlap ..................................... .
2.1.1.2
Round-Off Effects ..................................... .
2.1.1.3
Underflow and Overflow ................................ .
2.1.1.4
Notational Definitions ................................. .
2.2
FOLR - First Order Linear Recurrence Routines .................. .
2.2.1
FOLR Routine Name Format ............................... .
2.2.2
Calling a FOLR Routine .................................. .
2.3
Vector Versions of Existing Scalar Routines ....................... .
2.3.1
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2
Underflow Detection ...................................... .
2.3.3
Vector Routine Name Format ............................... .
2.3.4
Calling a Vector Math Routine .............................. .
2.4
Fast-Vector Math Routines .................................... .
2.4.1
Exception Handling ...................................... .
2.4.2
Special Restrictions On Input Arguments ..................... .
2.4.3
Accuracy .............................................. .
2.4.4
Performance ............................................ .

2-1
2-5
2-5
2-5
2-5
2-5
2-6
2-6
2-7
2-7
2-7
2-8
2-8

2-9
2-11
2-12
2-13
2-13
2-13

iii

Scalar MTH$ Reference Section
MTH$xACOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xACOSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xASIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xASIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xATAN...............................................
MTH$xATAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xATAN2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xATAND2 .............................................
MTH$xATANH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CxABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CCOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CxCOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CEXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CxEXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CxLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CMPLX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xCMPLX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CONJG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xCONJG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xCOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xCOSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xCOSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CSIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CxSIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CSQRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CxSQRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CVT_x_x. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$CVT_xA_xA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$xEXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HACOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HACOSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HASIN ................ ·...............................
MTH$HASIND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HATAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HATAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HATAN2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HATAND2 ............................................
MTH$HATANH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HCOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HCOSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HCOSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HEXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTH$HLOG2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

MTH-3
MTH-6
MTH-9
MTH-11
MTH-13
MTH-15
MTH-17
MTH-19
MTH-21
MTH-23
MTH-26
MTH-28
MTH-30
MTH-32
MTH-34
MTH-36
MTH-39
MTH-41
MTH-43
MTH-44
MTH-46
MTH-48
MTH-50
MTH-52
MTH-53
MTH-56
MTH-58
MTH-61
MTH-63
MTH-65
MTH-68
MTH-70
MTH-72
MTH-74
MTH-76
MTH-78
MTH-80
MTH-82
MTH-84
MTH-86
MTH-87
MTH-88
MTH-90
MTH-92
MTH-94

MTH$HLOG 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-96
MTH$HSIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-98
MTH$HSIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-99
MTH$HSINH ............................................... MTH-101
MTH$HSQRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-103
MTH$HTAN ................................................ MTH-105
MTH$HTAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-107
MTH$HTANH ......... ; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-109
MTH$xIMAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-111
MTH$xLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-113
MTH$xLOG2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-115
MTH$xLOG 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-117
MTH$RANDOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-119
MTH$xREAL ............................................... MTH-121
MTH$xSIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-123
MTH$xSINCOS ............................................. MTH-125
MTH$xSINCOSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-128
MTH$xSIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-131
MTH$xSINH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-133
MTH$xSQRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-136
MTH$xTAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-138
MTH$xTAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-140
MTH$xTANH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-142
MTH$UMAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-144
MTH$UMIN ................................................ MTH-145

Vector MTH$ Reference Section
BLAS1$VlxAMAX ........................................... MTH-149
BLAS1$VxASUM ............................................ MTH-152
BLAS1$V:xAXPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-155
BLAS1$VxCOPY ............................................ MTH-160
BLAS1$VxDOTx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-165
BLAS1$VxNRM2 ............................................ MTH-170
BLAS1$VxROT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-173
BLAS1$VxROTG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MTH-178
BLAS1$VxSCAL ............................................ MTH-182
BLAS1$VxSWAP ............................................ MTH-186
MTH$VxFOLRy_MA_V15 ..................................... MTH-190
MTH$VxFOLRy_z_V8 ........................................ MTH-194
MTH$VxFOLRLy_MA_V5 ..................................... MTH-198
MTH$VxFOLRLy_z_V2 ....................................... MTH-202

A Additional MTH$ Routines
B Vector MTH$ Routine Entry Points
Index
Tables
1-1

2-1
2-2
2-3
2-4
2-5
2-6
A-1

8-1

Additional Mathematics Routines ........................... .
Functions of BLAS Level 1 ................................. .
Determining the FOLR Routine You Need ..................... .
Vector Routine Format - Underflow Signaling Enabled .......... .
Vector Routine Format - Underflow Signaling Disabled .......... .
Fast-Vector Math Routines ................................. .
Input Argument Restrictions ............................... .
Additional MTH$ Routines ................................ .
Vector MTH$ Routines .................................... .

1-4

2-3
2-7
2-8
2-8
2-12
2-13
A-1

8-1

Preface
This manual provides users of the OpenVMS operating system with detailed
usage and reference information on mathematics routines supplied in the MTH$
facility of the Run-Time Library.
Run-Time Library routines can be used only in programs written in languages
that produce native code for the VAX hardware. At present, these languages
include VAX MACRO and the following compiled high-level languages:
VAX Ada
VAX BASIC
VAX BLISS-32
VAXC
VAX COBOL
VAX COBOL-74
VAX CORAL
VAXDIBOL
VAX FORTRAN
VAX Pascal
VAX PL/I
VAX RPG
VAX SCAN
Interpreted languages that can also access Run-Time Library routines include
VAX DSM and VAX DATATRIEVE.

Intended Audience
This manual is intended for system and application programmers who want to
call Run-Time Library routines.

Document Structure
This manual contains two tutorial chapters, two reference sections, and two
appendixes:
•

Chapter 1 is an introductory chapter that provides guidelines on using the
MTH$ scalar routines.

•

Chapter 2 provides guidelines on using the MTH$ vector routines.

•

The Scalar MTH$ Reference Section provides detailed reference information
on each scalar mathematics routine contained in the MTH$ facility of
the Run-Time Library. The routines in this section are the same as those
provided in VMS Version 5.5.

•

The Vector MTH$ Reference Section provides detailed reference information
on the BLAS Level 1 (Basic Linear Algebra Subroutines) and FOLR (First
Order Linear Recurrence) routines.

Reference information is presented using the documentation format described
in the OpenVMS Programming Interfaces: Calling a System Routine. Routine
descriptions are in alphabetical order by routine name.
•

Appendix A lists supported MTH$ routines not included with the routines in
the Scalar MTH$ Reference Section, because they are rarely used.

•

Appendix B contains all of the vector MTH$ routines that you can call from
VAX MACRO in one table.

Associated Documents
The Run-Time Library routines are documented in a series of reference manuals.
A description of how the Run-Time Library routines are accessed is presented in
OpenVMS Programming Interfaces: Calling a System Routine. A description of
OpenVMS features and functionality available through calls to the MTH$ RunTime Library appears in Open VMS Programming Concepts Manual. Descriptions
of the other RTL facilities and their corresponding routines are presented in the
following books:

•

DPML, Digital Portable Mathematics Library

•

OpenVMS RTL DECtalk (DTK$) Manual

•

Open VMS RTL Library (LIB$) Manual

•

Open VMS RTL General Purpose (OTS$) Manual

•

Open VMS RTL Parallel Processing (PPL$) Manual

•

Open VMS RTL Screen Management (SMG$) Manual

•

Open VMS RTL String Manipulation (STR$) Manual

Application programmers using any language can refer to the Guide to Creating
Open VMS Modular Procedures for writing modular and reentrant code.
High-level language programmers will find additional information on calling
Run-Time Library routines in their language reference manuals. Additional
information may also be found in the language user's guide provided with your
OpenVMS language software.
For a complete list and description of the manuals in the OpenVMS
documentation set, see Overview of Open VMS Documentation.

Conventions
In this manual, every use of OpenVMS VAX means the OpenVMS VAX operating
system.
The following conventions are also used in this manual:

\/iii

Ctrllx

A sequence such as Ctrl/x indicates that you must hold down
the key labeled Ctrl while you press another key or a pointing
device button.

PFlx

A sequence such as PFl x indicates that you must first press
and release the key labeled PFl, then press and release
another key or a pointing device button.

GOLDx

A sequence such as GOLD x indicates that you must first press
and release the key defined GOLD, then press and release
another key. GOLD key sequences can also have a slash(/),
dash (-),or underscore(_) as a delimiter in EVE commands.
In examples, a key name enclosed in a box indicates that
you press a key on the keyboard. (In text, a key name is not
enclosed in a box.)
A horizontal ellipsis in examples indicates one of the following
possibilities:
•

Additional optional arguments in a statement have been
omitted.

•

The preceding item or items can be repeated one or more
times.

•

Additional parameters, values, or other information can be
entered.

A vertical ellipsis indicates the omission of items from a code
example or command format; the items are omitted because
they are not important to the topic being discussed.
()

In format descriptions, parentheses indicate that, if you
choose more than one option, you must enclose the choices
in parentheses.

[ ]

In format descriptions, brackets indicate optional elements.
You can choose one, none, or all of the options. (Brackets are
not optional, however, in the syntax of a directory name in
an OpenVMS file specification, or in the syntax of a substring
specification in an assignment statement.)

{}

In format descriptions, braces surround a required choice of
options; you must choose one of the options listed.

boldface text

Boldface text represents the introduction of a new term or the
name of an argument, an attribute, or a reason.
Boldface text is also used to show user input in Bookreader
versions of the manual.

italic text

Italic text emphasizes important information, indicates
variables, and indicates complete titles of manuals. Italic
text also represents information that can vary in system
messages (for example, Internal error number), command lines
(for example, IPRODUCER=name), and command parameters
in text.

UPPERCASE TEXT

Uppercase text indicates a command, the name of a routine,
the name of a file, or the abbreviation for a system privilege.
A hyphen in code examples indicates that additional
arguments to the request are provided on the line that follows.

numbers

All numbers in text are assumed to be decimal, unless
otherwise noted. Non decimal radixes-binary, octal, or
hexadecimal-are explicitly indicated.

1
~ntroduction to MTH$
The Run-Time Library mathematics routines may be called to perform a wide
variety of computations including the following:
•

Floating-point trigonometric function evaluation

•

Exponentiation

•

Complex function evaluation

•

Complex exponentiation

•

Miscellaneous function evaluation

The OTS$ facility provides additional language-independent arithmetic support
routines.
This introduction to Run-Time Library mathematics routines includes examples
of how to call mathematics routines from BASIC, COBOL, FORTRAN, MACRO,
Pascal, PL/I, and Ada.

1.1 Entry Point Names
The names of the mathematics routines are formed by adding the MTH$ prefix to
the function names.
When function arguments and returned values are of the same data type, the
first letter of the name indicates this data type. When function arguments and
returned values are of different data types, the first letter indicates the data
type of the returned value, and the second letter indicates the data type of the
argument(s).
The letters used as data type prefixes are listed below.
Letter

Data Type

Word

Longword

D_floating

G_floating

H_floating

F _floating complex

D_floating complex

G_floating complex

Generally, F-floating data types have no letter designation. For example,
MTH$SIN returns an F-floating value of the sine of an F-floating argument and
MTH$DSIN returns a D-floating value of the sine of a D-floating argument.

1-1

Introduction to MTH$
1.1 Entry Point Names
However, in some of the miscellaneous functions, F-floating data types are
referenced by the letter designation A.

1.2 Calling Conventions
For calling conventions specific to the MTH$ vector routines, refer to Chapter 2.
All calls to mathematics routines, as described in the FORMAT section of
each routine, accept arguments passed by reference. JSB entry points accept
arguments passed by value.
All mathematics routines return values in RO or RO/Rl except those routines for
which the values cannot fit in 64 bits. D-floating complex, G-floating complex,
and H-floating values are data structures which are larger than 64 bits. Routines
returning values that cannot fit in registers RO/Rl return their function values
into the first argument in the argument list.
The notation JSB MTH$NAME_Rn, where n is the highest register number
referenced, indicates that an equivalent JSB entry point is available. Registers
RO:Rn are not preserved.
Routines with JSB entry points accept a single argument in RO:Rm, where m,
which is defined in the following table, is dependent on the data type.
Data Type

F _floating

D_floating

G_floating

H_floating

A routine returning one value returns it to registers RO:Rm.
When a routine returns two values (for example, MTH$SINCOS), the first value
is returned in RO:Rm and the second value is returned in (R<m+l>:R<2*m+l>).
Note that for routines returning a single value, n>=m. For routines returning
two values, n>=2*m + 1.
In general, CALL entry points for mathematics routines do the following:
•

Disable floating-point underflow

•

Enable integer overflow

•

Cause no floating-point overflow or other arithmetic traps or faults

•

Preserve all other enabled operations across the CALL

JSB entry points execute in the context of the caller with the enable operations
as set by the caller. Since the routines do not cause arithmetic traps or faults,
their operation is not affected by the setting of the arithmetic trap enables, except
as noted.
For more detailed information on CALL and JSB entry points, refer to the
Open VMS Programming Interfaces: Calling a System Routine.

1-?

Introduction to MTH$
1.3 Algorithms

1.3 Algorithms
For those mathematics routines having corresponding algorithms, the complete
algorithm can be found in the Description section of the routine description
appearing in the MTH$ Reference Section of this manual.

1.4 Condition Handling
Error conditions are indicated by using the VAX signaling mechanism. The VAX
signaling mechanism signals all conditions in mathematics routines as SEVERE
by calling LIB$SIGNAL. When a SEVERE error is signaled, the default handler
causes the image to exit after printing an error message. A user-established
condition handler can be written to cause execution to continue at the point of the
error by returning SS$_CONTINUE. A mathematics routine returns to its caller
after the contents of RO/Rl have been restored from the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. Thus, the user-established handler should
correct CHF$L_MCH_SAVRO/Rl to the desired function value to be returned to
the caller of the mathematics routine.
D-floating complex, G-floating complex, and H-floating values cannot be corrected
with a user-established condition handler, because R2/R3 is not available in the
mechanism argument vector.
Note that it is more reliable to correct RO and Rl to resemble RO and Rl of a
double-precision floating-point value. A double-precision floating-point value
correction works for both single- and double-precision values.
If the correction is not performed, the floating-point reserved operand -0.0 is

returned. A floating-point reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Accessing the floating-point reserved
operand will cause a reserved operand fault. See the OpenVMS RTL Library
(LIB$) Manual for a complete description of how to write user condition handlers
for SEVERE errors.
A few mathematics routines signal floating underflow if the calling program (JSB
or CALL) has enabled floating underflow faults or traps.
All mathematics routines access input arguments and the real and imaginary
parts of complex numbers using floating-point instructions. Therefore, a reserved
operand fault can occur in any mathematics routine.

1.5 Complex Numbers
A complex number y is defined as an ordered pair of real numbers r and i, where
r is the real part and i is the imaginary part of the complex number.
y=(r,i)

OpenVMS supports three floating-point complex types: F-floating complex,
D-floating complex, and G-floating complex. There is no H-floating complex data
type.
Run-Time Library mathematics routines that use complex arguments require a
pointer to a structure containing two x-floating values to be passed by reference
for each argument. The first x-floating value contains r, the real part of the
complex number. The second x-floating value contains i, the imaginary part of
the complex number. Similarly, Run-Time Library mathematics routines that
return complex function values return two x-floating values. Some Language
Independent Support (OTS$) routines also calculate complex functions.

Introduction to MTH$
1.5 Complex Numbers
Note that complex functions have no JSB entry points.

1.6 Mathematics Routines Not Documented in the MTH$ Reference
Section
The mathematics routines in Table 1-1 are not found in the reference section of
this manual. Instead, their entry points and argument information are listed in
Appendix A of this manual.
A reserved operand fault can occur for any floating-point input argument in
any mathematics routine. Other condition values signaled by each mathematics
routine are indicated in the footnotes.
Table 1-1 Additional Mathematics Routines
Entry Point

Function

Absolute Value Routines
MTH$ABS

F-floating absolute value

MTH$DABS

D-floating absolute value

MTH$GABS

G-floating absolute value

MTH$HABS

H-floating absolute value 1

MTH$IIABS

Word absolute value 2

MTH$JIABS

Longword absolute value 2

Bitwise AND Operator Routines
MTH$IIAND

Bitwise AND of two word arguments

MTH$JIAND

Bitwise AND of two longword arguments

F-floating Conversion Routines
MTH$DBLE

Convert F-floating to D-floating (exact)

MTH$GDBLE

Convert F-floating to G-floating (exact)

MTH$IIFIX

Convert F-floating to word (truncated)2

MTH$JIFIX

Convert F-floating to longword (truncated) 2

1 Returns value to the first argument; value exceeds 64 bits.
2 Integer overflow exceptions can occur.

(continued on next page)

Introduction to MTH$
1.6 Mathematics Routines Not Documented in the MTH$ Reference Section
Table 1-1 (Cont.) Additional Mathematics Routines
Entry Point

Function

Floating-Point Positive Difference Routines
MTH$DIM

Positive difference of two F-fioating arguments 3

MTH$DDIM

Positive difference of two D-fioating arguments 3

MTH$GDIM

Positive difference of two G-fioating arguments 3

MTH$HDIM

Positive difference of two H-fioating arguments 1•3

MTH$IIDIM

Positive difference of two word arguments2

MTH$JIDIM

Positive difference of two longword arguments 2

Bitwise Exclusive OR Operator Routines
MTH$IIEOR

Bitwise exclusive OR of two word arguments

MTH$JIEOR

Bitwise exclusive OR of two longword arguments

Integer to Floating-Point Conversion Routines
MTH$FLOATI

Convert word to F-fioating (exact)

MTH$DFLOTI

Convert word to D-fioating (exact)

MTH$GFLOTI

Convert word to G-fioating (exact)

MTH$FLOATJ

Convert longword to F-fioating (rounded)

MTH$DFLOTJ

Convert longword to D-fioating (exact)

MTH$GFLOTJ

Convert longword to G-fioating (exact)

Conversion to Greatest Floating-Point Integer Routines
MTH$FLOOR

Convert F-fioating to greatest F-fioating integer

MTH$DFLOOR

Convert D-fioating to greatest D-fioating integer

MTH$GFLOOR

Convert G-fioating to greatest G-fioating integer

MTH$HFLOOR

Convert H-fioating to greatest H-fioating integer1

1 Returns value to the first argument; value exceeds 64 bits.
2 Integer overflow exceptions can occur.

3 Floating-point overflow exceptions can occur.

(continued on next page)

Introduction to MTH$
1.6 Mathematics Routines Not Documented in the MTH$ Reference Section
Table 1-1 (Cont.) Additional Mathematics Routines
Entry Point

Function

Floating-Point Truncation Routines
MTH$AINT

Convert F-fl.oating to truncated F-fl.oating

MTH$IINT

Convert F-fl.oating to truncated word 2

MTH$JINT

Convert F-fl.oating to truncated longword2

MTH$DINT

Convert D-fl.oating to truncated D-fl.oating

MTH$IIDINT

Convert D-fl.oating to truncated word2

MTH$JIDINT

Convert D-fl.oating to truncated longword2

MTH$GINT

Convert G-fl.oating to truncated G-fl.oating

MTH$IIGINT

Convert G-fl.oating to truncated word 2

MTH$JIGINT

Convert G-fl.oating to truncated longword2

MTH$HINT

Convert H-fl.oating to truncated H-fl.oating1

MTH$IIHINT

Convert H-fl.oating to truncated word 2

MTH$JIHINT

Convert H-floating to truncated longword2

Bitwise Inclusive OR Operator Routines
MTH$IIOR

Bitwise inclusive OR of two word arguments

MTH$JIOR

Bitwise inclusive OR of two longword arguments

Maximum Value Routines
MTH$AIMAXO

F-fl.oating maximum of n word arguments

MTH$AJMAXO

F-fl.oating maximum of n longword arguments

MTH$IMAXO

Word maximum of n word arguments

MTH$JMAXO

Longword maximum of n longword arguments

MTH$AMAX1

F-fl.oating maximum of n F-fl.oating arguments

MTH$DMAX1

D-fl.oating maximum of n D-fl.oating arguments

MTH$GMAX1

G-fl.oating maximum of n G-fl.oating arguments

MTH$HMAX1

H-fl.oating maximum of n H-fl.oating arguments 1

MTH$IMAX1

Word maximum of n F-fl.oating arguments 2

MTH$JMAX1

Longword maximum of n F-fl.oating arguments 2

1 Returns value to the first argument; value exceeds 64 bits.
2 Integer overflow exceptions can occur.

(continued on next page)

Introduction to MTH$
1.6 Mathematics Routines Not Documented in the MTH$ Reference Section
Table 1-1 (Cont.) Additional Mathematics Routines
Entry Point

Function

Minimum Value Routines
MTH$AIMINO

F-floating minimum of n word arguments

MTH$AJMINO

F-floating minimum of n longword arguments

MTH$IMINO

Word minimum of n word arguments

MTH$JMINO

Longword minimum of n longword arguments

MTH$AMIN1

F-floating minimum of n F-floating arguments

MTH$DMIN1

D-floating minimum of n D-floating arguments

MTH$GMIN1

G-floating minimum of n G-floating arguments

MTH$HMIN1

H-floating minimum of n H-floating arguments 1

MTH$IMIN1

Word minimum of n F-floating arguments 2

MTH$JMIN1

Longword minimum of n F-floating arguments 2

Remainder Routines
MTH$AMOD

Remainder of two F-floating arguments, argl/arg2 36

MTH$DMOD

Remainder of two D-floating arguments, argl/arg2 36

MTH$GMOD

Remainder of two G-floating arguments, argl/arg2 3

MTH$HMOD

Remainder of two H-floating arguments, argl/arg2 1' 3

MTH$IMOD

Remainder of two word arguments, argl/arg2 5

MTH$JMOD

Remainder of two longword arguments, argl/arg2 5

Floating-Point Conversion to Nearest Value Routines
MTH$ANINT

Convert F-floating to nearest F-floating integer

MTH$1NINT

Convert F-floating to nearest word integer2

MTH$JNINT

Convert F-floating to nearest longword integer2

MTH$DNINT

Convert D-floating to nearest D-floating integer

MTH$11DNNT

Convert D-floating to nearest word integer2

MTH$JIDNNT

Convert D-floating to nearest longword integer2

MTH$GNINT

Convert G-floating to nearest G-floating integer

MTH$IIGNNT

Convert G-floating to nearest word integer2

MTH$JIGNNT

Convert G-floating to nearest longword integer2

1 Returns value to the first argument; value exceeds 64 bits.
2 Integer overflow exceptions can occur.

3 Floating-point overflow exceptions can occur.

5 Divide-by-zero exceptions can occur.
6 Floating-point underflow exceptions are signaled.

(continued on next page)

Introduction to MTH$
1.6 Mathematics Routines Not Documented in the MTH$ Reference Section
Table 1-1 (Cont.) Additional Mathematics Routines
Entry Point

Function

MTH$HNINT

Convert H-fl.oating to nearest H-fl.oating integer1

MTH$IIHNNT

Convert H-fl.oating to nearest word integer2

MTH$JIHNNT

Convert H-fl.oating to nearest longword integer2

Bitwise Complement Operator Routines
MTH$INOT

Bitwise complement of word argument

MTH$JNOT

Bitwise complement of longword argument

Floating-Point Multiplication Routines
MTH$DPROD

D-fl.oating product of two F-fl.oating arguments3

MTH$GPROD

G-fl.oating product of two F-fl.oating arguments

Bitwise Shift Operator Routines
MTH$IISHFT

Bitwise shift of word

MTH$JISHFT

Bitwise shift of longword

Floating-Point Sign Function Routines
MTH$SGN

F- or D-fl.oating sign function

MTH$SIGN

F-fl.oating transfer of sign of y to sign of x

MTH$DSIGN

D-fl.oating transfer of sign of y to sign of x

MTH$GSIGN

G-fl.oating transfer of sign of y to sign of x

MTH$HSIGN

H-fl.oating transfer of sign of y to sign of x 1

MTH$IISIGN

Word transfer of sign of y to sign of x

MTH$JISIGN

Longword transfer of sign of y to sign of x

1 Returns value to the first argument; value exceeds 64 bits.
2 Integer overflow exceptions can occur.

3 Floating-point overflow exceptions can occur.

(continued on next page)

Introduction to MTH$
1.6 Mathematics Routines Not Documented in the MTH$ Reference Section
Table 1-1 (Cont.) Additional Mathematics Routines
Entry Point

Function

Conversion of Double to Single Floating-Point Routines
MTH$SNGL

Convert D-floating to F-floating (rounded)3

MTH$SNGLG

Convert G-floating to F-floating (rounded)3,4

3 Floating-point overflow exceptions can occur.
4 Floating-point underflow exceptions can occur.

1. 7 Examples of Calls to Run-Time Library Mathematics Routines
1.7.1 BASIC Example
The following BASIC program uses the H-floating data type. BASIC also supports
the D-floating, F-floating, and G-floating data types, but does not support the
complex data types.
10

!+
! Sample program to demonstrate a call to MTH$HEXP from BASIC.
!-

EXTERNAL SUB MTH$HEXP ( HFLOAT, HFLOAT )
DECLARE HFLOAT X,Y
! X and Y are H-floating
DIGITS$ = '###.#################################'
X = '1.2345678901234567891234567892'H
CALL MTH$HEXP (Y,X)
A$ = 'MTH$HEXP of ' + DIGITS$ + ' is ' + DIGITS$
PRINT USING A$, X, Y
END

The output from this program is as follows:
MTH$HEXP of 1.234567890123456789123456789200000
is 3.436893084346008004973301321342110

1.7.2 COBOL Example
The following COBOL program uses the F-floating and D-floating data types.
COBOL does not support the G-floating and H-floating data types or the complex
data types.
This COBOL program calls MTH$EXP and MTH$DEXP.

1-Q

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
IDENTIFICATION DIVISION.
PROGRAM-ID.
FLOATING POINT.

* Calls MTH$EXP using a Floating Point data type.
* Calls MTH$DEXP using a Double Floating Point data type.

ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FLOAT PT
COMP-1.
01 ANSWER F
COMP-1.
01 DOUBLE-PT
COMP-2.
01 ANSWER-D
COMP-2.
PROCEDURE-DIVISION.
PO.
MOVE 12.34 TO FLOAT PT.
MOVE 3.456 TO DOUBLE PT.
CALL MTH$EXP USING BY REFERENCE FLOAT PT GIVING ANSWER F.
DISPLAY MTH$EXP of
FLOAT PT CONVERSION,
is
ANSWER F CONVERSION.
11

CALL MTH$DEXP USING BY REFERENCE DOUBLE PT GIVING ANSWER D.
DISPLAY MTH$DEXP of
DOUBLE PT CONVERSION,
is
ANSWER D CONVERSION.
STOP RUN.
11

The output from this example program is as follows:
MTH$EXP of 1.234000E+Ol is 2.286620E+05
MTH$DEXP of 3.456000000000000E+OO is
3.168996280537917E+Ol

1.7.3 FORTRAN Examples
The first FORTRAN program below uses the G-floating data type. The second
FORTRAN program below uses the H-floating data type. The third FORTRAN
program below uses the F-floating complex data type. FORTRAN supports the
four floating data types and the three complex data types.
1.

C+
C This FORTRAN program computes the log base 2 of x, log2(x) in
C G-floating double precision by using the RTL routine MTH$GLOG2.

c
c Declare X and Y and MTH$GLOG2 as double precision values.
c
c MTH$GLOG2 will return a double precision value to variable Y.
CREAL* 8 X, Y, MTH$GLOG2
x = 16.0
Y = MTH$GLOG2(X)
WRITE (6,1) X, Y
1 FORMAT(' MTH$GLOG2(' ,F4.1,') is ',F4.1)
END

The output generated by the preceding program is as follows:
MTH$GLOG2(16.0) is

1-10

4.0

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
2.

C+

C This FORTRAN program computes the log base 2 of x, log2(x) in
C H-floating precision by using the RTL routine MTH$HLOG2.

C Declare X and Y and MTH$GLOG2 as REAL*l6 values.

C MTH$HLOG2 will return a REAL*l6 value to variable Y.
CREAL* 16 X, Y
x = 16.12345678901234567890123456789
CALL MTH$HLOG2(Y, X)
WRITE (6,1) X, Y
1 FORMAT(' MTH$HLOG2(' ,F30.27,') is ',F30.28)
END

The output generated by the preceding program is as follows:
MTH$HLOG2(16.123456789012345678901234568) is 4.0110891785623860194931388310
3.

C+

c
c
c
c
c
c
c

This FORTRAN example raises a complex base to
a NONNEGATIVE integer power using OTS$POWCJ.
Declare Zl, Z2, Z3, and OTS$POWCJ as complex values.
Then OTS$POWCJ returns the complex result of
Zl**Z2:
Z3 = OTS$POWCJ(Zl,Z2),
where Zl and Z2 are passed by value.

C-

COMPLEX Zl,Z3,0TS$POWCJ
INTEGER Z2
C+

C
C-

c+
C
C-

Generate a complex base.
Zl = (2.0,3.0)
Generate an integer power.
Z2 = 2

c+
C
C-

Compute the complex value of Zl**Z2.
Z3 = OTS$POWCJ( %VAL(REAL(Zl)), %VAL(AIMAG(Zl)), %VAL(Z2))
TYPE 1,Zl,Z2,Z3
1
FORMAT(' The value of (' ,Fl0.8,' ,' ,Fll.8,')**' ,Il,' is
+ ( ,Fll.8,
,Fl2.8,').')
END
1

The output generated by the preceding FORTRAN program is as follows:
The value of (2.00000000, 3.00000000)**2 is
(-5.00000000, 12.00000000).

1.7.4 MACRO Examples
MACRO and BLISS support JSB entry points as well as CALLS and CALLG
entry points. Both MACRO and BLISS support the four floating data types and
the three complex data types.
The following MACRO programs show the use of the CALLS and CALLG
instructions, as well as JSB entry points.

1-11

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
1.

.TITLE EXAMPLE JSB

;+
This example calls MTH$DEXP by using a MACRO JSB command.
The JSB command expects RO/Rl to contain the quadword input value X.
The result of the JSB will be located in RO/Rl.
;-

.EXTRN MTH$DEXP R6
;MTH$DEXP is an external routine •
. PSECT DATA, PIC, EXE, NOWRT
.DOUBLE 2.0
; X is 2.0
.ENTRY EXAMPLE JSB, "M<>
MOVQ
X, RO ; X is in registers RO and Rl
JSB
G"MTH$DEXP R6
; The result is returned in RO/Rl.
RET
.END
EXAMPLE JSB

This MACRO program generates the following output:

RO <-- 732541EC
Rl <-- ED6EC6A6
That is, MTH$DEXP(2) is 7.3890560989306502
2.

.TITLE EXAMPLE CALLG

;+
This example calls MTH$HEXP by using a MACRO CALLG command.
The CALLG command expects that the address of the return value
Y, the address of the input value X, and the argument count 2 be
stored in memory; this program stores this information in ARGUMENTS.
The result of the CALLG will be located in RO/Rl.
;-

.EXTRN MTH$HEXP
i MTH$HEXP is an external routine •
. PSECT DATA, PIC, EXE, WRT
ARGUMENTS:
•LONG 2
The CALLG will use two arguments •
The first argument must be the address
.ADDRESS Y, X
receiving the computed value, while
the second argument is used to
compute exp (X) •
X:
.H FLOATING 2
x = 2.0
.H-FLOATING 0
Y is the result, initially set to 0.
Y:
.ENTRY EXAMPLE G, "M<>
CALLG ARGUMENTS, G"MTH$HEXP i CALLG returns the value to Y.
RET
.END
EXAMPLE G
The output generated by this MACRO program is as follows:

address of Y <-- D8E64003
<-- 4DDA4B8D
<-- 3A3BDCC3
<-- B68BA206
That is, MTH$HEXP of 2.0 returns
7.38905609893065022723042746057501

1-12

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
3.

.TITLE EXAMPLE CALLS

;+
This example calls MTH$HEXP by using the MACRO CALLS command.
The CALLS command expects the SP to contain the H-f loating address of
the return value, the address of the input argument X, and the argument
count 2. The result of the CALLS will be located in registers RO-R3.
;-

.EXTRN MTH$HEXP
; MTH$HEXP is an external routine .
. PSECT DATA, PIC, EXE, WRT
.H FLOATING 0
Y is the result, initially set to 0.
.H-FLOATING 2
X= 2
.ENTRY EXAMPLE S, AM<>
MOVAL X, -(SP)
The address of X is in the SP.
MOVAL Y, -(SP)
The address of Y is in the SP
CALLS Y, GAMTH$HEXP
The value is returned to the address of Y.
RET
.END
EXAMPLE S

Y:
X:

The output generated by this program is as follows:
address of Y <-- D8E64003
<-- 4DDA4B8D
<-- 3A3BDCC3
<-- B68BA206
That is, MTH$HEXP of 2.0 returns
7.38905609893065022723042746057501
.TITLE COMPLEX EXl

;+
This example calls MTH$CLOG by using a MACRO CALLG command.
To compute the complex natural logarithm of z = (2.0,1.0) register
RO is loaded with 2.0, the real part of z, and register Rl is loaded
with 1.0, the imaginary part of Z. The CALLG to MTH$CLOG
returns the value of the natural logarithm of z in
registers RO and Rl. RO gets the real part of Z and Rl
gets the imaginary part .

ARGS:

REAL:
IMAG:

. EXTRN MTH$CLOG
.PSECT DATA, PIC, EXE, NOWRT
.LONG 1
The CALLG will use one argument .
. ADDRESS REAL
The one argument that the CALLG
uses is the address of the argument
of MTH$CLOG.
.FLOAT 2
real part of Z is 2.0
.FLOAT 1
; imaginary part z is 1.0
.ENTRY COMPLEX EXl, AM<>
CALLG ARGS, GAMTH$CLOG; MTH$CLOG returns the real part of the
complex natural logarithm in RO and
the imaginary part in Rl.
RET
.END
COMPLEX EXl

This program generates the following output:
RO <--Rl <---

0210404E
63383FED

That is, MTH$CLOG(2.0,l.O) is
(0.8047190,0.4636476)

1-13

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
.TITLE COMPLEX EX2

;+
This example calls MTH$CLOG by using a MACRO CALLS command.
To compute the complex natural logarithm of Z = (2.0,1.0) register
RO is loaded with 2.0, the real part of z, and register Rl is loaded
with 1.0, the imaginary part of z. The CALLS to MTH$CLOG
returns the value of the natural logarithm of Z in registers RO
and Rl. RO gets the real part of z and Rl gets the imaginary
part.
;-

REAL:
!MAG:

.EXTRN
.PSECT
.FLOAT
.FLOAT
.ENTRY
MO VAL
CALLS

RET
.END

MTH$CLOG
DATA, PIC, EXE, NOWRT
2
; real part of z is 2.0
1
; imaginary part Z is 1.0
COMPLEX EX2, AM<>
REAL, -(SP)
SP <-- address of z. Real part of z is
in @(SP) and imaginary part is in
#1, GAMTH$CLOG
@(SP)+4.
MTH$CLOG return the real part of the
complex natural logarithm in RO and
the imaginary part in Rl.
COMPLEX EX2

This MACRO example program generates the following output:
RO <--Rl <---

0210404E
63383FED

That is, MTH$CLOG(2.0,1.0) is
(0.8047190,0.4636476)

1.7 .5 Pascal Examples
The following Pascal programs use the D-fioating and H-fioating data types.
Pascal also supports the F-fioating and G-fioating data types. Pascal does not
support the complex data types, however.
1.

{+}

{ Sample program to demonstrate a call to MTH$DEXP from PASCAL.
{-}
PROGRAM CALL_MTH$DEXP (OUTPUT);

{+}
{ Declare variables used by this program.
{-}
VAR
x DOUBLE := 3.456;
{ X,Y are D-floating unless overridden }
y
DOUBLE;
{ with /DOUBLE qualifier on compilation }
{+}
{ Declare the RTL routine used by this program.
{-}

[EXTERNAL,ASYNCHRONOUS) FUNCTION MTH$DEXP (VAR value
BEGIN
Y := MTH$DEXP (x);
WRITELN ('MTH$DEXP of '
END.

X:5:3, ' is '

DOUBLE)

Y:20:16);

The output generated by this Pascal program is as follows:
MTH$DEXP of 3.456 is

1-14

31.6899656462382318

DOUBLE; EXTERN;

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
2.

{+}

{ Sample program to demonstrate a call to MTH$HEXP from PASCAL.
{-}
PROGRAM CALL_MTH$HEXP (OUTPUT);
{+}
{ Declare variables used by this program.
{-}

VAR

x
y

QUADRUPLE := 1.2345678901234567891234567892; { x is H-floating }
QUADRUPLE;
{ y is H-floating }

{+}
{ Declare the RTL routine used by this program.
{-}

[EXTERNAL,ASYNCHRONOUS] PROCEDURE MTH$HEXP (VAR h_exp
value : QUADRUPLE); EXTERN;
BEGIN
MTH$HEXP (Y,X);
WRITELN ('MTH$HEXP of '
END.

QUADRUPLE;

X:30:28, ' is ', Y:35:33);

This Pascal program generates the following output:
MTH$DEXP of 3.456 is

31.6899656462382318

1.7.6 PL/I Examples
The following PL/I programs use the D-floating and H-floating data types to test
entry points. PL/I also supports the F-floating and G-floating data types. PL/I
does not support the complex data types, however.
1.

/*
*
*
*
*/
TEST:

This program tests a MTH$D entry point

*
*
*

PROC OPTIONS (MAIN) ;
DCL (MTH$DEXP)
ENTRY (FLOAT(53)) RETURNS (FLOAT(53));
DCL OPERAND FLOAT(53);
DCL RESULT FLOAT(53);

/*** Begin test ***/
OPERAND = 3.456;
RESULT= MTH$DEXP(OPERAND);
PUT EDIT ('MTH$DEXP of ',OPERAND, ' is ',
RESULT)(A(12),F(5,3),A(4),F(20,15));
END TEST;

The output generated by this PL/I program is as follows:
MTH$DEXP of 3.456 is

31.689962805379165

1-15

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
2.

*
*
*
*

This program tests a MTH$H entry point.
Note that in the PL/I statement below, the /G-float switch
is needed to compile both G- and H-floating point MTH$ routines.

TEST:

PROC OPTIONS (MAIN) ;
DCL (MTH$HEXP)
ENTRY (FLOAT (113), FLOAT (113))
DCL OPERAND FLOAT (113);
DCL RESULT FLOAT (113);

/*** Begin test ***/
OPERAND = 1.234578901234567891234567892;
CALL MTH$HEXP(RESULT,OPERAND);
PUT EDIT ('MTH$HEXP of ',OPERAND, ' is ',
RESULT) (A(l2),F(29,27),A(4),F(29,27));
END TEST;

To run this program, use the following DCL commands:
$ PLI/G FLOAT EXAMPLE
$ LINK EXAMPLE
$ RUN EXAMPLE

This program generates the following output:
MTH$HEXP of 1.234578901234567891234567892 is
3.436930928565989790506225633

1.7.7 Ada Example
The following Ada program demonstrates the use of MTH$ routines in a manner
that an actual program might use. The program performs the following steps:
•

Reads a floating-point number from the terminal

•

Calls MTH$SQRT to obtain the square root of the value read

•

Calls MTH$JNINT to find the nearest integer of the square root

•

Displays the result

This example runs on VAX Ada Version 2.0 or later.
-- This Ada program calls the MTH$SQRT and MTH$JNINT routines.
with FLOAT MATH LIB;
-- Package FLOAT MATH LIB is an instantiation of the generic package
-- MATH LIB for the FLOAT datatype. This package provides the most
-- common mathematical functions (SQRT, SIN, COS, etc.) in an easy
-- to use fashion. An added benefit is that the VAX Ada compiler
-- will use the faster JSB interface for these routines.
with MTH;
-- Package MTH defines all the MTH$ routines. It should be used when
-- package MATH LIB is not sufficient. All functions are defined here
-- as "valued procedures" for consistency.
with FLOAT TEXT IO, INTEGER TEXT IO, TEXT IO;
procedure ADA EXAMPLE is FLOAT VAL: FLOAT;
INT VAL: INTEGER;
begin -- Prompt for initial value.
TEXT IO.PUT ("Enter value: ");
FLOAT TEXT IO.GET (FLOAT VAL);
TEXT_IO.NEW_LINE;
1-16

*
*
*

Introduction to MTH$
1.7 Examples of Calls to Run-Time Library Mathematics Routines
-- Take the square root by using the SQRT routine from package
-- FLOAT MATH LIB. The compiler will use the JSB interface
-- to MTH$SQRT.
FLOAT_VAL := FLOAT_MATH_LIB.SQRT (FLOAT_VAL);
-- Find the nearest integer using MTH$JNINT. Argument names are
-- the same as those listed for MTH$JNINT in the reference
-- section of this manual.
MTH.JNINT (F_FLOATING => FLOAT_VAL, RESULT=> INT_VAL);
-- Write the result.
TEXT IO.PUT ("Result is: ");
INTEGER TEXT IO.PUT (INT_VAL);
TEXT Io:NEW LINE;
end ADA_EXAMPLET
To run this example program, use the following DCL commands:

$CREATE/DIR [.ADALIB]
$ACS CREATE LIB [.ADALIB]
$ACS SET LIB [.ADALIB]
$ ADA ADA EXAMPLE
$ ACS LINK ADA EXAMPLE
$ RUN ADA_EXAMPLE
The preceding Ada example generates the following output:

Enter value: 42.0
Result is:

2
Vector Routines in MTH$
This chapter discusses four sets of routines provided by the RTL MTH$ facility
that support vector processing. These routines are as follows:
•

Basic Linear Algebra Subroutines (BLAS) Level 1

•

First Order Linear Recurrence (FOLR) routines

•

Vector versions of existing scalar routines

•

Fast-Vector math routines

2.1 BLAS -

Basic Linear Algebra Subroutines Level 1

The BLAS Level 1 routines perform operations on vectors, such as copying a
vector to another vector, swapping vectors, and so on. These routines help you
take advantage of the vector processing speed. BLAS Level 1 routines form an
integral part of many mathematical libraries such as LINPACK and EISPACK.
1 Because these routines usually occur in the innermost loops of user code, the
Run-Time Library provides versions of the BLAS Level 1 that are tuned to take
best advantage of the VAX vector processors.
Two versions of BLAS Level 1 are provided. To use either of these libraries, link
in the appropriate shareable image. The libraries are:
•

Scalar BLAS - contained in the shareable image BLASlRTL

•

Vector BLAS (routines that take advantage of vectorization) - contained in
the shareable image VBLASlRTL
Note

To call the scalar BLAS from a program that runs on scalar
hardware, specify the routine name preceded by BLAS1$ (for example,
BLAS1$xCOPY). To call the vector BLAS from a program that runs on
vector hardware, specify the routine name preceded by BLAS1$V (for
example, BLAS1$VxCOPY).

This manual describes both the scalar and vector versions of BLAS Level 1,
but for simplicity the vector prefix (BLAS1$V) is used exclusively. Remember
to remove the letter V from the routine prefix when you want to call the scalar
version.

For more information, see Basic Linear Algebra Subprograms for FORTRAN Usage in
ACM Transactions on Mathematical Software, Vol. 5, No. 3, September 1979.

Vector Routines in MTH$
2.1 BLAS - Basic Linear Algebra Subroutines Level 1
If you are a VAX FORTRAN programmer, do not specify BLAS vector
routines explicitly. Specify the FORTRAN intrinsic function name only.
The VAX FORTRAN-RPO compiler will then determine whether the vector
or scalar version of a BLAS routine should be used. The FORTRAN
/BLAS=([NO]INLINE,[NO]MAPPED) qualifier controls how the compiler
processes calls to BLAS Level 1. If /NOBLAS is specified, then all BLAS calls
are treated as ordinary external routines. The default of INLINE means that
calls to BLAS Level 1 routines will be treated as known language constructs, and
VAX object code will be generated to compute the corresponding operations at
the call site, rather than call a user-supplied routine. If the FORTRAN qualifier
NECTOR or /PARALLEL=AUTO is in effect, the generated code for the loops
may use vector instructions or be decomposed to run on multiple processors.
If MAPPED is specified, these calls will be treated as calls to the optimized
implementations of these routines in the BLAS1$ and BLAS1$V portions of the
MTH$ facility. For more information on the FORTRAN /BLAS qualifier, refer to
the VAX FORTRAN Performance Guide.

Ten families of routines form BLAS Level 1. (BLAS1$VxCOPY is one family
of routines, for example.) These routines operate at the vector-vector operation
level. This means that BLAS Level 1 perform operations on one or two vectors.
The level of complexity of the computations (in other words, the number of
operations being performed in a BLAS Level 1 routine) is of the order n (the
length of the vector).
Each family of routines in BLAS Level 1 contains routines coded in single
precision, double precision (D and G formats), single precision complex, and
double precision complex (D and G formats). BLAS Level 1 can be broadly
classified into three groups:
•

BLAS1$VxCOPY, BLAS1$VxSWAP, BLAS1$VxSCAL and BLAS1$VxAX.PY:
These routines return vector output(s) for vector inputs. The results of all
these routines are independent of the order in which the elements of the
vector are processed. The scalar and vector versions of these routines return
the same results.

•

BLAS1$VxDOT, BLAS1$VlxAMAX, BLAS1$VxASUM, and BLAS1$VxNRM2:
These routines are all reduction operations that return a scalar value. The
results of these routines (except BLAS1$VlxAMAX) are dependent upon the
order in which the elements of the vector are processed. The scalar and vector
versions of BLAS1$VxDOT, BLAS1$VxASUM, and BLAS1$VxNRM2 can
return different results. The scalar and vector versions of BLAS 1$VlxAMAX
return the same results.

•

BLAS1$VxROTG and BLAS1$VxROT: These routines are used for a
particular application (plane rotations), unlike the routines in the previous
two categories. The results of BLAS1$VxROTG and BLAS1$VxROT are
independent of the order in which the elements of the vector are processed.
The scalar and vector versions of these routines return the same results.

Table 2-1 lists the functions and corresponding routines of BLAS Level 1.

2.1 BLAS Table 2-1

Vector Routines in MTH$
Basic Linear Algebra Subroutines Level 1

Functions of BLAS Level 1

Function

Routine

Data Type

Copy a vector to

BLAS1$VSCOPY

Single

another vector

BLAS1$VDCOPY

Double CD-floating or G-floating)

BLAS1$VCCOPY

Single complex

BLAS1$VZCOPY

Double complex CD-floating or
G-floating)

Swap the elements

BLAS1$VSSWAP

Single

of two vectors

BLAS1$VDSWAP

Double CD-floating or G-floating)

BLAS1$VCSWAP

Single complex

BLAS1$VZSWAP

Double complex CD-floating or
G-floating)

Scale the elements

BLAS1$VSSCAL

Single

of a vector

BLAS1$VDSCAL

Double CD-floating)

BLAS1$VGSCAL

Double CG-floating)

BLAS1$VCSCAL

Single complex with complex
scale

BLAS1$VCSSCAL

Single complex with real scale

BLAS1$VZSCAL

Double complex with complex
scale CD-floating)

BLAS1$VWSCAL

Double complex with complex
scale CG-floating)

BLAS1$VZDSCAL

Double complex with real scale
CD-floating)

BLAS1$VWGSCAL

Double complex with real scale
CG-floating)

Multiply a vector by a

BLAS1$VSAXPY

Single

scalar and add a vector

BLAS1$VDAXPY

Double CD-floating)

BLAS1$VGAXPY

Double CG-floating)

BLAS1$VCAXPY

Single complex

BLAS1$VZAXPY

Double complex CD-floating)

BLAS1$VWAXPY

Double complex CG-floating)

Obtain the index of the

BLAS1$VISAMAX

Single

first element of a vector

BLAS1$VIDAMAX

Double CD-floating)

having the largest

BLAS1$VIGAMAX

Double CG-floating)

absolute value

BLAS1$VICAMAX

Single complex

BLAS1$VIZAMAX

Double complex CD-floating)

BLAS1$VIWAMAX

Double complex CG-floating)
(continued on next page)

2-3

Vector Routines in MTH$
2.1 BLAS - Basic Linear Algebra Subroutines Level 1
Table 2-1 (Cont.) Functions of BLAS Level 1

Function

Routine

Data Type

Obtain the sum of the

BLAS1$VSASUM

Single

absolute values of the

BLAS1$VDASUM

Double CD-floating)

elements of a vector

BLAS1$VGASUM

Double (G-floating)

BLAS1$VSCASUM

Single complex

BLAS1$VDZASUM

Double complex (D-floating)

BLAS1$VGWASUM

Double complex (G-floating)

Obtain the inner

BLAS1$VSDOT

Single

product of two vectors

BLAS1$VDDOT

Double CD-floating)

BLAS1$VGDOT

Double (G-floating)

BLAS1$VCDOTU

Single complex unconjugated

BLAS1$VCDOTC

Single complex conjugated

BLAS1$VZDOTU

Double complex unconjugated
(D-floating)

BLAS1$VWDOTU

Double complex unconjugated
(G-floating)

BLAS1$VZDOTC

Double complex conjugated (Dfloating)

BLAS1$VWDOTC

Double complex conjugated (Gfloating)

BLAS1$VSNRM2

Single

Obtain the Euclidean
norm of the vector

BLAS1$VDNRM2

Double CD-floating)

BLAS1$VGNRM2

Double CG-floating)

BLAS1$VSCNRM2

Single complex

BLAS1$VDZNRM2

Double complex CD-floating)

BLAS1$VGWNRM2

Double complex CG-floating)

Generate the elements

BLAS1$VSROTG

Single

for a Givens plane

BLAS1$VDROTG

Double CD-floating)

rotation

BLAS1$VGROTG

Double CG-floating)

BLAS1$VCROTG

Single complex

BLAS1$VZROTG

Double complex CD-floating)

BLAS1$VWROTG

Double complex CG-floating)
(continued on next page)

2-4

2.1 BLAS -

Vector Routines in MTH$
Basic Linear Algebra Subroutines Level 1

Table 2-1 (Cont.) Functions of BLAS Level 1
Function

Routine

Data Type

Apply a Givens plane

BLAS1$VSROT

Single

rotation

BLAS1$VDROT

Double (D-floating)

BLAS1$VGROT

Double (G-floating)

BLAS1$VCSROT

Single complex

BLAS1$VZDROT

Double complex (D-floating)

BLAS1$VWGROT

Double complex (G-floating)

For a detailed description of these routines, refer to the Vector MTH$ Reference
Section of this manual.

2.1.1 Using BLAS Level 1
The following sections provide some guidelines for using BLAS Level 1.
2.1.1.1 Memory Overlap
The vector BLAS produces unpredictable results when any element of the input
argument shares a memory location with an element of the output argument. (An
exception is a special case found in the BLAS1$VxCOPY routines.)

The vector BLAS and the scalar BLAS can yield different results when the input
argument overlaps the output array.
2.1.1.2 Round-Off Effects
For some of the routines in BLAS Level 1, the final result is independent of
the order in which the operations are performed. However, in other cases (for
example, some of the reduction operations), efficiency dictates that the order of
operations on a vector machine be different from the natural order of operations.
Because round-off errors are dependent upon the order in which the operations
are performed, some of the routines will not return results that are bit-for-bit
identical to the results obtained by performing the operations in natural order.

Where performance can be increased by the use of a backup data type, this
has been done. This is the case for BLAS1$VSNRM2, BLAS1$VSCNRM2,
BLAS1$VSROTG, and BLAS1$VCROTG. The use of a backup data type can
also yield a gain in accuracy over the scalar BLAS.
2.1.1.3 Underflow and Overflow
In accordance with LINPACK convention, underflow, when it occurs, is replaced
by a zero. A system message informs you of overflow. Because the order of
operations for some routines is different from the natural order, overflow might
not occur at the same array element in both the scalar and vector versions of the
routines.
2.1.1.4 Notational Definitions
The vector BLAS (except the BLAS1$VxROTG routines) perform operations on
vectors. These vectors are defined in terms of three quantities:

•

A vector length, specified as n

•

An array or a starting element in an array, specified as x

•

An increment or spacing parameter to indicate the distance in number of
array elements to skip between successive vector elements, specified as incx

2-5

Vector Routines in MTH$
2.1 BLAS- Basic Linear Algebra Subroutines Level 1
Suppose x is a real array of dimension ndim, n is its vector length, and incx is
the increment used to access the elements of a vector X. The elements of vector
X, Xi, i = 1, ... , n, are stored in x. If incx is greater than or equal to 0, then Xi is
stored in the following location:

x(l + (i - 1) * incx)
However, if incx is less than 0, then Xi is stored in the following location:

x(l + (n - i) * jincxj)
It therefore follows that the following condition must be satisfied:

ndim2::1 + (n - 1) * jincxj
A positive value for incx is referred to as forward indexing, and a negative
value is referred to as backward indexing. A value of zero implies that all of the
elements of the vector are at the same location, x1.
Suppose ndim = 20 and n = 5. In this case, incx = 2 implies that X1, X2, X3,
X4, and X5 are located in array elements x1, x3, x5, x7, and x9.

If, however, incx is negative, then X1, X2, X3, X4, and X5 are located in array
elements xg, x7, x5, x3, and x1. In other words, when incx is negative, the
subscript of x decreases as i increases.
For some of the routines in BLAS Level 1, incx = 0 is not permitted. In the cases
where a zero value for incx is permitted, it means that x1 is broadcast into each
element of the vector X of length n.
You can operate on vectors that are embedded in other vectors or matrices by
choosing a suitable starting point of the vector. For example, if A is an nl by n2
matrix, its j-th column is referenced with a length of nl, starting point A(lj), and
increment 1. Similarly, the i-th row is referenced with a length of n2, starting
point A(i,1), and increment nl.

2.2 FOLR -

First Order Linear Recurrence Routines

The MTH$ FOLR routines provide a vectorized algorithm for the linear
recurrence relation. A linear recurrence uses the result of a previous pass
through a loop as an operand for subsequent passes through the loop and
prevents the vectorization of a loop.
The only error checking performed by the FOLR routines is for a reserved
operand.
There are four families of FOLR routines in the MTH$ facility. Each family
accepts each of four data types (longword integer, F-floating, D-floating, and
G-floating). However, all of the arrays you specify in a single FOLR call must be
of the same data type.
For a detailed description of these routines, refer to the Vector MTH$ Reference
Section of this manual.

2.2.1 FOLR Routine Name Format
The four families of FOLR routines are as follows:

2-6

•

MTH$VxFOLRy_MA_V15

•

MTH$VxFOLRy_z_V8

•

MTH$VxFOLRLy_MA_V5

Vector Routines in MTH$
2.2 FOLR - First Order Linear Recurrence Routines
•

MTH$VxFOLRLy_z_V2

where:
x

J for longword integer, F for F-floating, D for D-floating, or G for G-floating

P for a positive recursion element, or N for a negative recursion element

M for multiplication, or A for addition

The FOLR entry points end with_Vn, where n is an integer between 0 and
15 that denotes the vector registers that the FOLR routine uses. For example,
MTH$VxFOLRy_z_V8 uses vector registers VO through V8.
To determine which group of routines you should use, match the task in the left
column in Table 2-2 that you need the routine to perform with the method of
storage that you need the routine to employ. The point where these two tasks
meet shows the FOLR routine you should call.
Table 2-2 Determining the FOLR Routine You Need
Tasks

Save each iteration in an array

Save only last result in a variable

Multiplication AND
addition

MTH$VxFOLRy_MA_V15

MTH$VxFOLRLy_MA_V5

Multiplication OR
addition

MTH$VxFOLRy_z_V8

MTH$VxFOLRLy_z_V2

2.2.2 Calling a FOLR Routine
Save the contents of VO through Vn before calling a FOLR routine if you need
it after the call. The variable n can be 2, 5, 8, or 15, depending on the FOLR
routine entry point. (The OpenVMS Calling Standard specifies that a called
procedure may modify all of the vector registers. The FOLR routines modify only
the vector registers VO through Vn.)
The MTH$ FOLR routines assume that all of the arrays are of the same data
type.

2.3 Vector Versions of Existing Scalar Routines
Vector forms of many MTH$ routines are provided to support vectorized compiled
applications. Vector versions of key F-floating, D-floating, and G-floating scalar
routines employ vector hardware, while maintaining identical results with their
scalar counterparts. Many of the scalar algorithms have been redesigned to
ensure identical results and good performance for both the vector and scalar
versions of each routine. All vectorized routines return bit-for-bit identical results
as the scalar versions.
You can call the vector MTH$ routines directly if your program is written in
VAX MACRO. If you are a FORTRAN programmer, specify the FORTRAN
intrinsic function name only. The VAX FORTRAN-RPO compiler will then
determine whether the vector or scalar version of a routine should be used.

2.3.1 Exceptions
You should not attempt to recover from an MTH$ vector exception. After an
MTH$ vector exception, the vector routines cannot continue execution, and
nonexceptional values might not have been computed.

2-7

Vector Routines in MTH$
2.3 Vector Versions of Existing Scalar Routines
2.3.2 Underflow Detection
In general, if a vector instruction results in the detection of both a floating
overflow and a floating underflow, only the overflow will be signaled.
Some scalar routines check to see if a user has enabled underflow detection. For
each of those scalar routines, there are two corresponding vector routines:
one that always enables underflow checking and one that never enables
underflow checking. (In the latter case, underflows produce a result of zero.)
The VAX FORTRAN-RPO compiler always chooses the vector version that does
not signal underflows, unless the user specifies the appropriate VAX FORTRANHPO compiler switch (the /CHECK=UNDERFLOW qualifier). This ensures that
the check is performed but does not impair vector performance for those not
interested in underflow detection.

2.3.3 Vector Routine Name Format
Use one of the formats in Table 2-3 to call (from VAX MACRO) a vector math
routine that enables underflow signaling. (The E in the routine name means
enabled underflow signaling.)
Table 2-3 Vector Routine Format -

Underflow Signaling Enabled

Format

Type of Routine

MTH$VxSAMPLE_E_Ry_Vz

Real valued math routine

MTH$VCxSAMPLE_E_Ry_Vz

Complex valued math routine

OTS$SAMPLEq_E_Ry_Vz

Power routine or complex multiply and divide

Use one of the formats in Table 2-4 to call (from VAX MACRO) a vector math
routine that does not enable underflow signaling.
Table 2-4 Vector Routine Format -

Underflow Signaling Disabled

Format

Type of Routine

MTH$VxSAMPLE_Ry_Vz

Real valued math routine

MTH$VCxSAMPLE_Ry_Vz

Complex valued math routine

OTS$SAMPLEq_Ry_Vz

Power routine or complex multiply/divide

In the preceding formats, the following conventions are used:

2-8

The letter A (or blank) for F-floating, D for D-floating, G for G-floating.

A number between 0 and 11 (inclusive). Ry means that the scalar registers RO
through Ry will be used by the routine SAMPLE. You must save these registers.

A number between 0 and 15 (inclusive). Vz means that the vector registers VO
through Vz will be used by the routine SAMPLE. You must save these registers.

Two letters denoting the base and power data type, as follows:
RR

F-floating base raised to an F-floating power

F-floating base raised to a longword power

D-floating base raised to a D-floating power

D-floating base raised to a longword power

Vector Routines in MTH$
2.3 Vector Versions of Existing Scalar Routines
GG

G-fioating base raised to a G-fioating power

G-fioating base raised to a longword power

Longword base raised to a longword power

2.3.4 Calling a Vector Math Routine
You can call the vector MTH$ routines directly if your program is written in
VAX MACRO.
Note ~~~~~~~~~~~~~

If you are a VAX FORTRAN programmer, do not specify the MTH$ vector

routines explicitly. Specify the FORTRAN intrinsic function name only.
The VAX FORTRAN-RPO compiler will then determine whether the
vector or scalar version of a routine should be used.

In the following examples, keep in mind that vector real arguments are passed
in VO, Vl, and so on, and vector real results are returned in VO. On the other
hand, vector complex arguments are passed in VO and Vl, V2, and V3, and so on.
Vector complex results are returned in VO and Vl.

Argument

Argument Passed
Register

Results Returned
Register

Vector real arguments

VO, Vl, ...

Vector complex arguments

VO and Vl, V2 and V3, ...

VO and Vl

Example 1

The following example shows how to call the vector version of MTH$EXP. Assume
that you do not want underflows to be signaled, and you need to use the current
contents of all vector and scalar registers after the invocation. Before you can call
the vector routine from VAX MACRO, perform the following steps.
1.

Find EXP in the column of scalar names in Appendix B to determine:
•

The full vector routine name: MTH$VEXP_R3_V6

•

How the routine is invoked (CALL or JSB): JSB

•

The scalar registers that must be saved: RO through R3 (as specified by
R3 in MTH$VEXP_R3_V6)

•

The vector registers that must be saved: VO through V6 (as specified by
V6 in MTH$VEXP_R3_V6)

•

The vector register(s) used to hold the input argument(s): VO

•

The vector register(s) used to hold the output argument(s): VO

•

If there is a vector version that signals underflow (not needed in this
example)

Save the scalar registers RO, Rl, R2, and R3.

3. Save the vector registers VO, Vl, V2, V3, V4, V5, and V6.
4. Save the vector mask register VMR.
5. Save the vector count register VCR.

2-9

Vector Routines in MTH$
2.3 Vector Versions of Existing Scalar Routines
6.

Load the vector length register VLR.

Load the vector register VO with the argument for MTH$EXP.

S. JSB to MTH$VEXP_R3_V6.
9.

Store result in memory.

10. Restore all scalar and vector registers except for VO. (The results of the "call"
to MTH$VEXP_R3_V6 are stored in VO.)
The following MACRO program fragment shows this example. Assume that:
•

VO through V6 and RO through R3 have been saved.

•

R4 points to a vector of 60 input values.

•

R6 points to the location where the results of MTH$VEXP_R3_V6 will be
stored.

•

R5 contains the stride in bytes.

Note that MTH$VEXP_R3_V6 denotes an F-floating data type because there is
no letter between V and E in the routine name. (For further explanation, refer to
Section 2.3.3.) The stride (the number of array elements that are skipped) must
be a multiple of 4 because each F-floating value requires 4 bytes.

MTVLR
MOVL
VLDL
JSB
VSTL

#60
#4, RS
(R4), RS, VO
GAMTH$VEXP R3 V6
VO I ( R6 ) I RS -

Load VLR
Stride
Load VO with the actual arguments
JSB to MTH$VEXP
Store the results

Example 2
The following example demonstrates how to call the vector version of
OTS$POWDD with a vector base raised to a scalar power. Before you can call the
vector routine from VAX MACRO, perform the following steps.

2-10

Find POWDD (V 8 ) in the column of scalar names in Appendix B to
determine:
•

The full vector routine name: OTS$VPOWDD_Rl_VS

•

How the routine is invoked (CALL or JSB): CALL

•

The scalar registers that must be saved: RO through Rl (as specified by
Rl in OTS$VPOWDD_Rl_VS)

•

The vector registers that must be saved: VO through VS (as specified by
VS in OTS$VPOWDD_Rl_VS)

•

The vector register(s) used to hold the input argument(s): VO, RO

•

The vector register(s) used to hold the output argument(s): VO

•

If there is a vector version that signals underflow (not needed in this
example)

Save the scalar registers RO and Rl.

Save the vector registers VO, Vl, V2, V3, V4, V5, V6, V7, and VS.

Save the vector mask register VMR.

Save the vector count register VCR.

Load the vector length register VLR.

Vector Routines in MTH$
2.3 Vector Versions of Existing Scalar Routines
7. Load the vector register VO and the scalar register RO with the arguments for
OTS$POWDD.
8. Call OTS$VPOWDD_Rl_V8.
9. Store result in memory.
10. Restore all scalar and vector registers except for VO. (The results of the call
to OTS$VPOWDD_Rl_V8 are stored in VO.)
The following MACRO program fragment shows how to call OTS$VPOWDD_Rl_
V8 to compute the result of raising 60 values to the power P. Assume that:
•

VO through V8 and RO and Rl have been saved.

•

R4 points to the vector of 60 input base values.

•

RO and Rl contain the D-floating value P.

•

R6 points to the location where the results will be stored.

•

R5 contains the stride.

Note that OTS$VPOWDD_Rl_V8 raises a D-floating base to a D-floating power,
which you determine from the DD in the routine name. (For further explanation,
refer to Section 2.3.3.) The stride (the number of array elements that are skipped)
must be a multiple of 8 because each D-floating value requires 8 bytes.
MTVLR
MOVL
VLDQ
CALLS
VSTQ

; RO/Rl already contains the power
#60
i Load VLR
#8, RS
; Stride
(R4), RS, VO
; Load VO with the actual arguments
#0,GAOTS$VPOWDD Rl VB ; CALL OTS$VPOWDD
VO, (R6), RS - ; Store the results

2.4 Fast-Vector Math Routines
This section describes the fast-vector math routines that offer significantly
higher performance at the cost of slightly reduced accuracy when compared with
corresponding standard vector math routines. Also note that some fast-vector
math routines have restricted argument domains.
When you specify the compile command qualifiers NECTOR and /MATH_
LIBRARY=FAST, VAX FORTRAN-RPO Version 1.2 selects the appropriate fastvector math routine, if one exists. The default is /MATR_LIBRARY=ACCURATE.
You must specify the /G_FLOATING compile qualifier in conjunction with the
/MATR_LIBRARY=FAST and NECTOR qualifiers to access the G_floating
versions from VAX FORTRAN-RPO. See the VAX FORTRAN-RPO Vl.2 Release
Notes for more information.
You can call these routines from VAX MACRO using the standard calling method.
The math function names, together with corresponding entry points of the
fast-vector math routines, are listed in Table 2-5.

2-11

Vector Routines in MTH$
2.4 Fast-Vector Math Routines
Table 2-5 Fast-Vector Math Routines

Function Name

Data Type

Call or JSB

Vector
Input
Registers

Vector
Output
Registers

Vector Name
(Underflows Not Signaled)

ATAN

F _ftoating

JSB

MTH$VYATAN_RO_V3

DATAN

D_floating

JSB

MTH$VYDATAN_RO_V5

GATAN

G_ftoating

JSB

MTH$VYGATAN_RO_V5

ATAN2

F_ftoating

JSB

VO, Vl

MTH$VVYATAN2_RO_V5

DATAN2

D_ftoating

JSB

VO, Vl

GATAN2

G_ftoating

JSB

VO, Vl

MTH$VVYDATAN2_RO_V5
MTH$VVYGATAN2_RO_V5

cos

F _ftoating

JSB

MTH$VYCOS_RO_V3

DCOS

D_ftoating

JSB

MTH$VYDCOS_RO_V3

GCOS
EXP

G_ftoating

JSB

F _ftoating

JSB

MTH$VYGCOS_RO_V3
MTH$VYEXP_RO_V4

DEXP

D_ftoating

JSB

MTH$VYDEXP_RO_V6

GEXP

G_ftoating

JSB

MTH$VYGEXP_RO_V6

LOG

F _floating

JSB

MTH$VYALOG_RO_V5

DLOG

D_ftoating

JSB

MTH$VYDLOG_RO_V5

GLOG

G_ftoating

JSB

MTH$VYGLOG_RO_V5

LOGlO

F _ftoating

JSB

MTH$VYALOG 10_RO_V5

DLOGlO

D_ftoating

JSB

MTH$VYDLOG 10_RO_V5

GLOGlO

G_ftoating

JSB

MTH$VYGLOG 10_RO_V5

SIN

F_ftoating

JSB

MTH$VYSIN_RO_V3

DSIN

D_ftoating

JSB

MTH$VYDSIN_RO_V3

GSIN

G_ftoating

JSB

MTH$VYGSIN_RO_V3

SQRT

F_floating

JSB

MTH$VYSQRT_RO_V4

DSQRT

D_ftoating

JSB

MTH$VYDSQRT_RO_V4

GSQRT

G_floating

JSB

MTH$VYGSQRT_RO_V4

TAN

F_floating

JSB

MTH$VYTAN_RO_V3

DTAN

D_ftoating

JSB

MTH$VYDTAN_RO_V3

GTAN

G_floating

JSB

MTH$VYGTAN_RO_V3

POWRR(X**Y)

F _floating

CALL

VO,RO

OTS$VYPOWRR_Rl_V4

POWDD(X**Y)

D_floating

CALL

VO,RO

OTS$VYPOWDD_Rl_V8

POWGG(X**Y)

G_floating

CALL

VO,RO

OTS$VYPOWGG_Rl_V9

2.4.1 Exception Handling
The fast-vector math routines signal all errors except floating underflow. No
intermediate calculations result in exceptions. To optimize performance, the
following message signals all errors:
%SYSTEM-F-VARITH, vector arithmetic fault

2-12

Vector Routines in MTH$
2.4 Fast-Vector Math Routines
2.4.2 Special Restrictions On Input Arguments
The special restrictions listed in Table 2-6 apply only to fast-vector routines
SIN, COS, and TAN. The standard vector routines handle the full range of VAX
floating point numbers.
Table 2-6 Input Argument Restrictions
Function Name

Input Argument Domain (in Radians)

SIN

-( -6746518783.0, 6746518783.0)

cos

-( -6746518783.0, 6746518783.0)

TAN

-( -3373259391.5, 3373259391.5 )

If the application program uses arguments outside of the listed domain, the
routine returns the following error message:

%SYSTEM-F-VARITH, vector arithmetic fault
If the application requires argument values beyond the listed limits, use the
corresponding standard vector math routine.

2.4.3 Accuracy
The fast-vector math routines do not guarantee the same results as those obtained
with the corresponding standard vector math routines. Calls to the fast-vector
routines generally yield results that are different from the scalar and original
vector MTH$ library routines. The typical maximum error is a 2-LSB (Least
Significant Bit) error for the F _floating routines and a 4-LSB error for the D_
floating and G_floating routines. This generally corresponds to a difference in
the 6th significant decimal digit for the F _floating routines, the 15th digit for
D_floating, and the 14th digit for G_floating.

2.4.4 Performance
The fast-vector math routines generally provide performance improvements over
the standard vector routines ranging from 15 to 300 percent, depending on the
routines called and input arguments to the routines. The overall performance
improvement using fast-vector math routines in a typical user application will
increase, but not at the same level as the routines themselves. You should do
performance and correctness testing of your application using both the fast-vector
and the standard vector math routines before deciding which to use for your
application.

2-13

Scalar MTH$ Reference Section

The Scalar MTH$ Reference Section provides detailed descriptions of the scalar
routines provided by the OpenVMS RTL Mathematics (MTH$) Facility.

MTH$xACOS

MTH$xACOS-Arc Cosine of Angle Expressed in Radians
Given the cosine of an angle, the Arc Cosine of Angle Expressed in Radians
routine returns that angle (in radians).

Format
MTH$ACOS

cosine

MTH$DACOS

cosine

MTH$GACOS

cosine

Each of the above three formats accepts one of the floating-point types as input.
JSB Entries
MTH$ACOS_R4
MTH$DACOS_R7
MTH$GACOS_R7

Each of the above three JSB entries accepts one of the floating-point types as
input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle in radians. The angle returned will have a value in the range
0 ::; angle ::; 7r

MTH$ACOS returns an F-floating number. MTH$DACOS returns a D-floating
number. MTH$GACOS returns a G-floating number.

Arguments
cosine
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The cosine of the angle whose value (in radians) is to be returned. The cosine
argument is the address of a floating-point number that is this cosine. The
absolute value of cosine must be less than or equal to 1. For MTH$ACOS,
cosine specifies an F-floating number. For MTH$DACOS, cosine specifies a
D-floating number. For MTH$GACOS, cosine specifies a G-floating number.

MTH$xACOS

Description
The angle in radians whose cosine is Xis computed as:
Value of Cosine

Value Returned

7r/2
0

-1

0<x<1

zATAN(zSQRT(l - X 2 )/X), where zATAN and zSQRT are the

Math Library arc tangent and square root routines, respectively,
of the appropriate data type
zAT AN(zSQRT(l - X 2 )/ X) + 7r

-1<x<0
1 < IXI

The error MTH$_INVARGMAT is signaled

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HACOS.

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

Reserved operand. The MTH$xACOS routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. The absolute value of cosine
is greater than 1. LIB$SIGNAL copies the
floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.

Examples
1.

100

!+
! This BASIC program demonstrates the use of
! MTH$ACOS.
!-

300
400
500

32767

~ATU

EXTERNAL REAL FUNCTION MTH$ACOS
DECLARE REAL COS VALUE, ANGLE
INPUT "Cosine value between -1 and +1 "; cos VALUE
IF (COS VALUE < -1) OR (COS VALUE > 1)
-THEN PRINT "Invalid-cosine value"
GOTO 300
ANGLE = MTH$ACOS( COS VALUE )
PRINT "The angle with-that cosine is "; ANGLE; "radians"
END

MTH$xACOS

This BASIC program prompts for a cosine value and determines the angle
that has that cosine. The output generated by this program is as follows:
$ RUN ACOS
Cosine value between -1 and +1 ? .5
The angle with that cosine is 1.0472 radians
2.

PROGRAM GETANGLE(INPUT,OUTPUT);
{+}
{ This PASCAL program uses MTH$ACOS to determine
{ the angle which has the cosine given as input.
{-}

VAR
COS : REAL;
FUNCTION MTH$ACOS(COS
EXTERN;

REAL)

REAL;

BEGIN
WRITE('Cosine value between -1 and +1: ');
READ (COS);
WRITELN('The angle with that cosine is ', MTH$ACOS(COS),
' radians');
END.
This PASCAL program prompts for a cosine value and determines the angle
that has that cosine. The output generated by this program is as follows:
$ RUN ACOS
Cosine value between -1 and +1: .5
The angle with that cosine is 1.04720E+OO radians

MTH-Fi

MTH$xACOSD

MTH$xACOSD-Arc Cosine of Angle Expressed in Degrees
Given the cosine of an angle, the Arc Cosine of Angle Expressed in Degrees
routine returns that angle (in degrees).

Format
MTH$ACOSD

cosine

MTH$DACOSD

cosine

MTH$GACOSD

cosine

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ACOSD_R4
MTH$DACOSD_R7
MTH$GACOSD_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle in degrees. The angle returned will have a value in the range
0 :::; angle :::; 180

MTH$ACOSD returns an F-floating number. MTH$DACOSD returns a D-floating
number. MTH$GACOSD returns a G-floating number.

Arguments
cosine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, G_floating, D_floating
read only
by reference

Cosine of the angle whose value (in degrees) is to be returned. The cosine
argument is the address of a floating-point number that is this cosine. The
absolute value of cosine must be less than or equal to 1. For MTH$ACOSD,
cosine specifies an F-floating number. For MTH$DACOSD, cosine specifies a
D-floating number. For MTH$GACOSD, cosine specifies a G-floating number.

MTH-6

MTH$xACOSD

Description
The angle in degrees whose cosine is Xis computed as:
Value of Cosine

Angle Returned

-1

180

0< X < 1

zAT AN D(zSQRT(l - X 2 )/ X), where zATAND and zSQRT

-1 < X < O
1 < IXI

are the Math Library arc tangent and square root routines,
respectively, of the appropriate data type
zATAND(zSQRT(l - X 2 )/X) + 180
The error MTH$_INVARGMAT is signaled

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HACOSD.

Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xACOSD routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. The absolute value of cosine
is greater than 1. LIB$SIGNAL copies the
floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.

MTH$_INVARGMAT

Example
PROGRAM ACOSD(INPUT,OUTPUT);
{+}
{ This PASCAL program demonstrates the use of
{ MTH$ACOSD.
{-}
FUNCTION MTH$ACOSD(COS

REAL): REAL; EXTERN;

VAR
COSINE : REAL;
RET_STATUS : REAL;
BEGIN
COSINE := 0.5;
RET STATUS := MTH$ACOSD(COSINE);
WRITELN('The angle, in degrees, is: '
END.

RET_STATUS);

MTH-7

MTH$xACOSD

The output generated by this PASCAL example program is as follows:
The angle, expressed in degrees, is:

MTH-8

6.00000E+Ol

MTH$xASIN

MTH$xASIN-Arc Sine in Radians
Given the sine of an angle, the Arc Sine in Radians routine returns that angle (in
radians).

Format
MTH$ASIN

sine

MTH$DASIN

sine

MTH$GASIN

sine

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ASIN_R4
MTH$DASIN_R7
MTH$GASI N_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle in radians. The angle returned will have a value in the range

-7r/2::; angle::; 7r/2
MTH$ASIN returns an F-floating number. MTH$DASIN returns a D-floating
number. MTH$GASIN returns a G-floating number.

Arguments
sine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The sine of the angle whose value (in radians) is to be returned. The sine
argument is the address of a floating-point number that is this sine. The absolute
value of sine must be less than or equal to 1. For MTH$ASIN, sine specifies an
F-floating number. For MTH$DASIN, sine specifies a D-floating number. For
MTH$GASIN, sine specifies a G-floating number.

MTH-9

MTH$xASIN

Description
The angle in radians whose sine is Xis computed as:
Value of Sine

Angle Returned

7r/2

-1

-7r/2

0 < IXI < 1

zATAN(X/zSQRT(l - X 2 )), where zATAN and zSQRT are
the Math Library arc tangent and square root routines,
respectively, of the appropriate data type

1 < IXI

The error MTH$_INVARGMAT is signaled

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HASIN.

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

MTH-10

Reserved operand. The MTH$xASIN routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. The absolute value of sine
is greater than 1. LIB$SIGNAL copies the
floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.

MTH$xASIND

MTH$xASIND-Arc Sine in Degrees
Given the sine of an angle, the Arc Sine in Degrees routine returns that angle (in
degrees).

Format
MTH$ASIND

sine

MTH$DASIND

sine

MTH$GASIND

sine

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ASIND_R4
MTH$DASIND_R7
MTH$GASIND_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle in degrees. The angle returned will have a value in the range
-90 ~ angle :s; 90

MTH$ASIND returns an F-floating number. MTH$DASIND returns a D-floating
number. MTH$GASIND returns a G-floating number.

Arguments
sine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Sine of the angle whose value (in degrees) is to be returned. The sine argument
is the address of a floating-point number that is this sine. The absolute value
of sine must be less than or equal to 1. For MTH$ASIND, sine specifies an
F-floating number. For MTH$DASIND, sine specifies a D-floating number. For
MTH$GASIND, sine specifies a G-floating number.

MTH-11

MTH$xASIND

Description
The angle in degrees whose sine is X is computed as:
Value of Sine

Value Returned

-1

-90

0 < IXI < 1

zATAN D(X/zSQRT(1 - X 2 )), where zATAND and zSQRT

1 < IXI

are the Math Library arc tangent and square root routines,
respectively, of the appropriate data type
The error MTH$_INVARGMAT is signaled

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HASIND.

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

MTH-12

Reserved operand. The MTH$xASIND routine
encountered a floating point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. The absolute value of sine
is greater than 1. LIB$SIGNAL copies the
floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.

MTH$xATAN

MTH$xATAN-Arc Tangent in Radians
Given the tangent of an angle, the Arc Tangent in Radians routine returns that
angle (in radians).

Format
MTH$ATAN

tangent

MTH$DATAN

tangent

MTH$GATAN

tangent

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ATAN_R4
MTH$DATAN_R7
MTH$GATAN_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle in radians. The angle returned will have a value in the range
-7r

/2 ~ angle ::::; 7r /2

MTH$ATAN returns an F-floating number. MTH$DATAN returns a D-floating
number. MTH$GATAN returns a G-floating number.

Arguments
tangent

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The tangent of the angle whose value (in radians) is to be returned. The tangent
argument is the address of a floating-point number that is this tangent. For
MTH$ATAN, tangent specifies an F-floating number. For MTH$DATAN,
tangent specifies a D-floating number. For MTH$GATAN, tangent specifies a
G-floating number.

11.llTLJ

-1 t)

MTH$xATAN

Description
In radians, the computation of the arc tangent function is based on the following
identities:
arctan(X) = X - X 3 /3 + X 5 /5 - x 7 /7 + ...
arctan(X) = X + X * Q(X 2 ),

where Q(Y) = -Y/3 + Y2 /5 - y3 /7 + ...
arctan(X) = X * P(X 2 ),
where P(Y) = 1- Y/3 + Y2 /5 - y3/7 + ...
arctan(X) = 7r/2 - arctan(l/X)
arctan(X) = arctan(A) + arctan((X - A)/(1 +A* X))

for any real A
The angle in radians whose tangent is Xis computed as:
Value of X

Angle Returned

o::;X::;3/32
3/32 < x::;u

X + X * Q(X 2 )

11 <

X< O

ATAN(A) + V * (P(V 2 )), where A and ATAN(A) are
chosen by table lookup and V = (X - A)/(1 +A* X)
7r/2 - W * (P(W 2 )) where W = 1/X

-zAT AN(IXI)

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HATAN.

Condition Value Signaled
SS$_ROPRAND

MTH-1.d.

Reserved operand. The MTH$xATAN routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xATAND

MTH$xATAND-Arc Tangent in Degrees
Given the tangent of an angle, the Arc Tangent in Degrees routine returns that
angle (in degrees).

Format
MTH$ATAND

tangent

MTH$DATAND

tangent

MTH$GATAND

tangent

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ATAND_R4
MTH$DATAND_R7
MTH$GATAND_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_poin t
F _floating, D_floating, G_floating
write only
by value

Angle in degrees. The angle returned will have a value in the range
-90 ~ angle ~ 90

MTH$ATAND returns an F-floating number. MTH$DATAND returns a D-floating
number. MTH$GATAND returns a G-floating number.

Arguments
tangent

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The tangent of the angle whose value (in degrees) is to be returned. The tangent
argument is the address of a floating-point number that is this tangent. For
MTH$ATAND, tangent specifies an F-floating number. For MTH$DATAND,
tangent specifies a D-floating number. For MTH$GATAND, tangent specifies a
G-floating number.

~ATl-l-1!=\

MTH$xATAND

Description
The computation of the arc tangent function is based on the following identities:
arctan(X) = (180/7r) * (X - X 3 /3 + X5 /5 - x7 /7 + ... )
arctan(X) = 64 * X + X * Q(X 2 ),
where Q(Y) = 180/71" * [(1 - 64 * 71" /180)] - Y /3 + Y2 /5 - Y 3 /7 + Y 4 /9
arctan(X) = X * P(X 2 ),
where P(Y) = 180/71" * [1 - Y/3 + y2/5 - y3 /7 + y4 /9 ... ]
arctan(X) = 90 - arctan(l/ X)
arctan(X) = arctan(A) + arctan((X - A)/(1 +A* X))

The angle in degrees whose tangent is X is computed as:
Tangent

Angle Returned

X<_5;3/32

64 * X + X * Q(X )

3/32 < x::;11

ATAND(A) + V * P(V 2 ), where A and ATAND(A) are
chosen by table lookup and V = (X - A)/(1 +A* X)
90 - W * (P(W 2 )), where W = 1/X
-zATAND( I X I )

11 <

X< O

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HATAND.

Condition Value Signaled
SS$_ROPRAND

MTH-16

Reserved operand. The MTH$xATAND routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xATAN2

MTH$xATAN2-Arc Tangent in Radians with Two Arguments
Given sine and cosine, the Arc Tangent in Radians with Two Arguments routine
returns the angle (in radians) whose tangent is given by the quotient of sine and
cosine (sine/cosine).

Format
MTH$ATAN2

sine ,cosine

MTH$DATAN2

sine ,cosine

MTH$GATAN2

sine ,cosine

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle in radians. MTH$ATAN2 returns an F-floating number. MTH$DATAN2
returns a D-floating number. MTH$GATAN2 returns a G-floating number.

Arguments
sine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Dividend. The sine argument is the address of a floating-point number that
is this dividend. For MTH$ATAN2, sine specifies an F-floating number. For
MTH$DATAN2, sine specifies a D-floating number. For MTH$GATAN2, sine
specifies a G-floating number.
cosine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Divisor. The cosine argument is-the address of a floating-point number that
is this divisor. For MTH$ATAN2, cosine specifies an F-floating number. For
MTH$DATAN2, cosine specifies a D-floating number. For MTH$GATAN2,
cosine specifies a G-floating number.

l\JITl-L17

MTH$xATAN2

Description
The angle in radians whose tangent is Y/X is computed as follows, where f is
defined in the description of MTH$zCOSH.
Value of Input Arguments

X = o or Y/X > 2U+l)
X > 0 and Y/X~ 2(/+l)
X < 0 and Y/X~ 2(/+l)

Angle Returned
7r

/2 * (signY)

zATAN(Y/X)
7r * (signY) + zATAN(Y/X)

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HATAN2.

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

MTH-1R

Reserved operand. The MTH$xATAN2 routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. Both cosine and sine are
zero. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH$xATAND2

MTH$xATAND2-Arc Tangent in Degrees with Two Arguments
Given sine and cosine, the Arc Tangent in Degrees with Two Arguments routine
returns the angle (in degrees) whose tangent is given by the quotient of sine and
cosine (sine/cosine).

Format
MTH$ATAND2

sine ,cosine

MTH$DATAND2

sine ,cosine

MTH$GATAND2

sine ,cosine

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Angle (in degrees). MTH$ATAND2 returns an F-floating number.
MTH$DATAND2 returns a D-floating number. MTH$GATAND2 returns a
G-floating number.

Arguments
sine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Dividend. The sine argument is the address of a floating-point number that
is this dividend. For MTH$ATAND2, sine specifies an F-floating number. For
MTH$DATAND2, sine specifies a D-floating number. For MTH$GATAND2, sine
specifies a G-floating number.
cosine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Divisor. The cosine argument is the address of a floating-point number that
is this divisor. For MTH$ATAND2, cosine specifies an F-floating number. For
MTH$DATAND2, cosine specifies a D-floating number. For MTH$GATAND2,
cosine specifies a G-fioating number.

MTH$xATAND2

Description
The angle in degrees whose tangent is YIX is computed below and where f is
defined in the description of MTH$zCOSH.
Value of Input Arguments

Angle Returned

X = 0 or Y/X > 2<J+l)
X > 0 and Y/X ~ 2<J+l)
X < 0 and Y/X ~ 2<J+l)

90 * (signY)

zATAND(Y/X)
180 * (signY) + zATAN D(Y / X)

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HATAND2.

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

l\ATU

l)n

Reserved operand. The MTH$xATAND2 routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. Both cosine and sine are
zero. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH$xATANH

MTH$xATANH-Hyperbolic Arc Tangent
Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent routine
returns the hyperbolic arc tangent of that angle.

Format
MTH$ATANH

hyperbolic-tangent

MTH$DATANH

hyperbolic-tangent

MTH$GATANH

hyperbolic-tangent

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The hyperbolic arc tangent of hyperbolic-tangent. MTH$ATANH returns an
F-floating number. MTH$DATANH returns a D-floating number. MTH$GATANH
returns a G-floating number.

Arguments
hyperbolic-tangent
OpenVMS usage floating_point
type
F _floating, D_floating, G_floating
access
read only
mechanism
by reference

Hyperbolic tangent of an angle. The hyperbolic-tangent argument is the
address of a floating-point number that is this hyperbolic tangent. For
MTH$ATANH, hyperbolic-tangent specifies an F-floating number. For
MTH$DATANH, hyperbolic-tangent specifies a D-floating number. For
MTH$GATANH, hyperbolic-tangent specifies a G-floating number.

Description
The hyperbolic arc tangent function is computed as follows:
Value of x

Value Returned

IXI < 1
IXl2::1

zATAN H(X) = zLOG((1 + X)/(1 - X))/2
An invalid argument is signaled

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HATANH.

MTH$xATANH

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

P.ATU

'l'l

Reserved operand. The MTH$xATANH routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument: IXl~l. LIB$SIGNAL copies
the floating-point reserved operand to the
mechanism argument vector CHF$L_MCH_
SAVRO/Rl. The result is the floating-point
reserved operand unless you have written a
condition handler to change CHF$L_MCH_
SAVRO/Rl.

MTH$CxABS

MTH$CxABS-Complex Absolute Value
The Complex Absolute Value routine returns the absolute value of a complex
number (r,i).

Format
MTH$CABS

complex-number

MTH$CDABS

complex-number

MTH$CGABS

complex-number

Each of the above three formats accepts one of the three floating-point complex
types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The absolute value of a complex number. MTH$CABS returns an F-floating
number. MTH$CDABS returns a D-floating number. MTH$CGABS returns a
G-floating number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex, D_floating complex, G_floating complex
read only
by reference

A complex number (r,i), where rand i are both floating-point complex values.
The complex-number argument is the address of this complex number. For
MTH$CABS, complex-number specifies an F-floating complex number. For
MTH$CDABS, complex-number specifies a D-floating complex number. For
MTH$CGABS, complex-number specifies a G-floating complex number.

Description
The complex absolute value is computed as follows, where MAX is the larger of
I r I and I i I , and MIN is the smaller of I r I and I i I .
result= MAX* SQRT((MIN/MAX) 2 + 1)

MTH$CxABS

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$CxABS routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library when
both r and i are large.

Examples
1.

c
c
c
c
c
c

This FORTRAN example forms the absolute value of an
F-f loating complex number using MTH$CABS and the
FORTRAN random number generator RAN.
Declare Z as a complex value and MTH$CABS as a REAL*4 value.
MTH$CABS will return the absolute value of Z:
Z_NEW = MTH$CABS(Z).

C-

COMPLEX Z
COMPLEX CMPLX
REAL*4 Z NEW,MTH$CABS
INTEGER M
M = 1234567
C+
C
C-

Generate a random complex number with the FORTRAN generic CMPLX.
Z = CMPLX(RAN(M),RAN(M))

C+
C

Z is a complex number (r,i) with real part "r" and
imaginary part "i".

C-

TYPE *, ' The complex number z is' ,z
TYPE *, ' It has real part' ,REAL(Z),'and imaginary part' ,AIMAG(Z)
TYPE * , , ,
C+
C
C-

Compute the complex absolute value of z.
Z NEW = MTH$CABS(Z)
TYPE*, ' The complex absolute value of' ,z,' is' ,Z_NEW
END

This example uses an F-floating complex number for complex-number. The
output of this FORTRAN example is as follows:
The complex number z is (0.8535407,0.2043402)
It has real part 0.8535407
and imaginary part

0.2043402

The complex absolute value of (0.8535407,0.2043402) is

0.8776597

MTH$CxABS
2.

c
c
c
c
c

This FORTRAN example forms the absolute
value of a G-f loating complex number using
MTH$CGABS and the FORTRAN random number
generator RAN.

c
c

Declare Z as a complex value and MTH$CGABS as a
REAL*8 value. MTH$CGABS will return the absolute
value of Z: Z_NEW = MTH$CGABS(Z).

C-

COMPLEX*l6 Z
REAL*8 Z_NEW,MTH$CGABS
Ct
C

Generate a random complex number with the FORTRAN
generic CMPLX.

C-

z = (12.34567890123,45.536376385345)
TYPE *, ' The complex number z is' ,z
TYPE *, ' '
Ct
C
C-

Compute the complex absolute value of z.
Z NEW = MTH$CGABS(Z)
TYPE*, ' The complex absolute value of' ,z,' is' ,Z_NEW
END

This FORTRAN example uses a G-floating complex number for complexnumber. Because this example uses a G-floating number, it must be
compiled as follows:
$ FORTRAN/G MTHEX.FOR

Notice the difference in the precision of the output generated:
The complex number z is (12.3456789012300,45.5363763853450)
The complex absolute value of (12.3456789012300,45.5363763853450) is
47.1802645376230

MTH-25

MTH$CCOS

MTH$CCOS-Cosine of a Complex Number (F-Floating Value)
The Cosine of a Complex Number (F-Floating Value) routine returns the cosine of
a complex number as an F-floating value.

Format
MTH$CCOS

complex-number

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

The complex cosine of the complex input number. MTH$CCOS returns an
F-floating complex number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
read only
by reference

A complex number (r,i) where r and i are floating-point numbers. The complexnumber argument is the address of this complex number. For MTH$CCOS,
complex-number specifies an F-floating complex number.

Description
The complex cosine is calculated as follows:
result= (COS(r) * COSH(i),-SJN(r) *SIN H(i))

The routine descriptions for the D- and G-floating point versions of this routine
are listed alphabetically under MTH$CxCOS.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH-26

Reserved operand. The MTH$CCOS routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of i is greater than about 88.029
for F-floating values.

MTH$CCOS

Example
C+
C
C
C
C

C
C
C
C-

This FORTRAN example forms the complex
cosine of an F-f loating complex number using
MTH$CCOS and the FORTRAN random number
generator RAN.
Declare Z and MTH$CCOS as complex values.
MTH$CCOS will return the cosine value of
Z:
Z_NEW = MTH$CCOS(Z)
COMPLEX Z,Z NEW,MTH$CCOS
COMPLEX CMPLX
INTEGER M
M = 1234567

C+
C

Generate a random complex number with the
FORTRAN generic CMPLX.

C-

Z = CMPLX(RAN(M),RAN(M))

c+
C

Z is a complex number (r,i) with real part "r" and
imaginary part "i".

C-

TYPE *, ' The complex number z is' ,z
TYPE*, ' It has real part' ,REAL(Z),'and imaginary part' ,AIMAG(Z)
TYPE *I , ,
C+
C
C-

Compute the complex cosine value of z.
Z NEW = MTH$CCOS(Z)
TYPE*, 'The complex cosine value of' ,z,' is' ,Z_NEW
END

This FORTRAN example demonstrates the use of MTH$CCOS, using the
MTH$CCOS entry point. The output of this program is as follows:
The complex number z is (0.8535407,0.2043402)
It has real part 0.8535407
and imaginary part 0.2043402
The complex cosine value of (0.8535407,0.2043402) is (0.6710899,-0.1550672)

MTH-27

MTH$CxCOS

MTH$CxCOS-Cosine of a Complex Number
The Cosine of a Complex Number routine returns the cosine of a complex number.

Format
MTH$CDCOS

complex-cosine ,complex-number

MTH$CGCOS

complex-cosine ,complex-number

Each of the above formats accepts one of the floating-point complex types as
input.

Returns
None.

Arguments
complex-cosine
OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
write only
by reference

Complex cosine of the complex-number. The complex cosine routines that have
D-floating and G-floating complex input values write the address of the complex
cosine into the complex-cosine argument. For MTH$CDCOS, the complexcosine argument specifies a D-floating complex number. For MTH$CGCOS, the
complex-number argument specifies a G-floating complex number.
complex-number
OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
read only
by reference

A complex number (r,i) where r and i are floating-point numbers. The complexnumber argument is the address of this complex number. For MTH$CDCOS,
complex-number specifies a D-floating complex number. For MTH$CGCOS,
complex-number specifies a G-floating complex number.

Description
The complex cosine is calculated as follows:
result= (COS(r) * COSH(i), -SIN(r) *SIN H(i))

MTH-28

MTH$CxCOS

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$CxCOS routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of i is greater than about 88.029
for F-floating and D-floating values, or greater
than 709.089 for G-floating values.

Example
c+
C
C
C
C

This FORTRAN example forms the complex
cosine of a D-f loating complex number using
MTH$CDCOS and the FORTRAN random number
generator RAN.

C
C
C
C-

Declare z and MTH$CDCOS as complex values.
MTH$CDCOS will return the cosine value of
Z:
Z_NEW = MTH$CDCOS(Z)

COMPLEX*l6 Z,Z NEW,MTH$CDCOS
COMPLEX*l6 DCMPLX
INTEGER M
M = 1234567
C+
C
C
C-

Generate a random complex number with the
FORTRAN generic DCMPLX.
Z = DCMPLX(RAN(M),RAN(M))

C+
C
C
C-

Z is a complex number (r,i) with real part "r" and
imaginary part "i".
TYPE *, ' The complex number z is' ,z
TYPE * ,

C+
C
C-

Compute the complex cosine value of z.
Z NEW = MTH$CDCOS(I)
TYPE*, 'The complex cosine value of' ,z,' is' ,Z_NEW
END

This FORTRAN example program demonstrates the use of MTH$CxCOS, using
the MTH$CDCOS entry point. Notice the high precision of the output generated:
The complex number z is (0.8535407185554504,0.2043401598930359)
The complex cosine value of (0.8535407185554504,0.2043401598930359) is
(0.6710899028500762,-0.1550672019621661)

MTH-29

MTH$CEXP

MTH$CEXP-Complex Exponential (F-Floating Value)
The Complex Exponential (F-Floating Value) routine returns the complex
exponential of a complex number as an F-floating value.

Format
MTH$CEXP complex-number

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

Complex exponential of the complex input number. MTH$CEXP returns an
F-floating complex number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
read only
by reference

Complex number whose complex exponential is to be returned. This complex
number has the form (r,i), where r is the real part and i is the imaginary part.
The complex-number argument is the address of this complex number. For
MTH$CEXP, complex-number specifies an F-floating number.

Description
The complex exponential is computed as follows:
complex - exponent= (EXP(r) * COS(i), EXP(r) * SJN(i))
The routine descriptions for the D- and G-floating point versions of this routine
are listed alphabetically under MTH$CxEXP.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH-30

Reserved operand. The MTH$CEXP routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of r is greater than about 88.029
for F-floating values.

MTH$CEXP

Example
c+

C
C

This FORTRAN example forms the complex exponential
of an F~f loating complex number using MTH$CEXP
and the FORTRAN random number generator RAN.

C
C
C-

Declare Z and MTH$CEXP as complex values. MTH$CEXP
will return the exponential value of Z: Z_NEW = MTH$CEXP(Z)

COMPLEX Z,Z NEW,MTH$CEXP
COMPLEX CMPLX
INTEGER M
M = 1234567
C+
C

Generate a random complex number with the
FORTRAN generic CMPLX.

C-

Z = CMPLX(RAN(M),RAN(M))

c+
C

Z is a complex number (r,i) with real part "r"
and imaginary part "i".

C-

TYPE*, 'The complex number z is',z
TYPE*, ' It has real part' ,REAL(Z),'and imaginary part' ,AIMAG(Z)
TYPE *,
I

C+
C
C-

Compute the complex exponential value of z.
Z NEW = MTH$CEXP(Z)
TYPE*, 'The complex exponential value of' ,z,' is' ,Z_NEW
END

This FORTRAN program demonstrates the use of MTH$CEXP as a function call.
The output generated by this example is as follows:
The complex number z is (0.8535407,0.2043402)
It has real part 0.8535407
and imaginary part 0.2043402
The complex exponential value of (0.8535407,0.2043402) is
(2.299097,0.4764476)

MTH-31

MTH$CxEXP

MTH$CxEXP-Complex Exponential
The Complex Exponential routine returns the complex exponential of a complex
number.

Format
MTH$CDEXP

complex-exponent ,complex-number

MTH$CGEXP

complex-exponent ,complex-number

Each of the above formats accepts one of the floating-point complex types as
input.

Returns
None.

Arguments
complex-exponent

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
write only
by reference

Complex exponential of complex-number. The complex exponential routines
that have D-floating complex and G-floating complex input values write the
complex-exponent into this argument. For MTH$CDEXP, complex-exponent
argument specifies a D-floating complex number. For MTH$CGEXP, complexexponent specifies a G-floating complex number.
complex-number

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
read only
by reference

Complex number whose complex exponential is to be returned. This complex
number has the form (r,i), where r is the real part and i is the imaginary
part. The complex-number argument is the address of this complex number.
For MTH$CDEXP, complex-number specifies a D-floating number. For
MTH$CGEXP, complex-number specifies a G-floating number.

Description
The complex exponential is computed as follows:

complex - exponent= (EXP(r) * COS(i), EXP(r) * SIN(i))

MTH-32

MTH$CxEXP

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$CxEXP routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of r is greater than about 88.029
for D-floating values, or greater than about
709.089 for G-floating values.

Example
C+
C
C
C

C
C
C
C-

This FORTRAN example forms the complex exponential
of a G-f loating complex number using MTH$CGEXP
and the FORTRAN random number generator RAN.
Declare Z and MTH$CGEXP as complex values.
MTH$CGEXP will return the exponential value
of Z:
CALL MTH$CGEXP(Z_NEW,Z)
COMPLEX*l6 Z,Z NEW
COMPLEX*l6 MTH$GCMPLX
REAL*8 R, I
INTEGER M
M = 1234567

C+
C
CC-

Generate a random complex number with the FORTRAN
generic CMPLX.
R = RAN(M)
I = RAN(M)
Z = MTH$GCMPLX(R,I)
TYPE *, ' The complex number z is' ,z
TYPE * I I I

C+
C
C-

Compute the complex exponential value of z.
CALL MTH$CGEXP(Z NEW,Z)
TYPE *,
The complex exponential value of' ,z,
END
I

is' ,Z_NEW

This FORTRAN example demonstrates how to access MTH$CGEXP as a
procedure call. Because G-floating numbers are used, this program must be
compiled using the command "FORTRAN/G filename".
Notice the high precision of the output generated:
The complex number z is (0.853540718555450,0.204340159893036)
The complex exponential value of (0.853540718555450,0.204340159893036) is
(2.29909677719458,0.476447678044977)

MTH-33

MTH$CLOG

MTH$CLOG-Complex Natural Logarithm (F-Floating Value)
The Complex Natural Logarithm CF-Floating Value) routine returns the complex
natural logarithm of a complex number as an F-floating value.

Format
MTH$CLOG

complex-number

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

The complex natural logarithm of a complex number. MTH$CLOG returns an
F-floating complex number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
read only
by reference

Complex number whose complex natural logarithm is to be returned. This
complex number has the form (r,i), where r is the real part and i is the imaginary
part. The complex-number argument is the address of this complex number.
For MTH$CLOG, complex-number specifies an F-floating number.

Description
The complex natural logarithm is computed as follows:

CLOG(x) = (LOG(CABS(x)), ATAN2(i, r))
The routine descriptions for the D- and G-floating point versions of this routine
are listed alphabetically under MTH$CxLOG.

Condition Value Signaled
SS$_ROPRAND

MTH-34

Reserved operand. The MTH$CLOG routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$CLOG

Example
Examples of using MTH$CLOG from VAX MACRO (using both the CALLS and
the CALLG instructions) appear in the introductory section of this manual.

MTH-35

MTH$CxLOG

MTH$CxLOG-Complex Natural Logarithm
The Complex Natural Logarithm routine returns the complex natural logarithm
of a complex number.

Format
MTH$CDLOG

complex-natural-log ,complex-number

MTH$CGLOG

complex-natural-log ,complex-number

Each of the above formats accepts one of the floating-point complex types as
input.

Returns
None.

Arguments
complex-natural-log
OpenVMS usage complex_number
type
D_floating complex, G_floating complex
access
write only
mechanism
by reference

Natural logarithm of the complex number specified by complex-number. The
complex natural logarithm routines that have D-floating complex and G-floating
complex input values write the address of the complex natural logarithm into
complex-natural-log. For MTH$CDLOG, the complex-natural-log argument
specifies a D-floating complex number. For MTH$CGLOG, the complex-naturallog argument specifies a G-floating complex number.
complex-number
OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
read only
by reference

Complex number whose complex natural logarithm is to be returned. This
complex number has the form (r,i), where r is the real part and i is the imaginary
part. The complex-number argument is the address of this complex number.
For MTH$CDLOG, complex-number specifies a D-floating number. For
MTH$CGLOG, complex-number specifies a G-floating number.

Description
The complex natural logarithm is computed as follows:
CLOG(x) = (LOG(CABS(x)), ATAN2(i, r))

MTH-36

MTH$CxLOG

Condition Value Signaled
MTH$_INVARGMAT

SS$_FLTOVF_F

SS$_ROPRAND

Invalid argument: r = i = 0. LIB$SIGNAL
copies the floating-point reserved operand to
the mechanism argument vector CHF$L_MCH_
SAVRO/Rl. The result is the floating-point
reserved operand unless you have written a
condition handler to change CHF$L_MCH_
SAVRO/Rl.
Floating point overflow can occur. This condition
value is signaled from MTH$CxABS when
MTH$CxABS overflows.
Reserved operand. The MTH$CxLOG routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

Example
C+
C
C

c
c

C
c

This FORTRAN example forms the complex logarithm
of a D-f loating complex number by using MTH$CDLOG
and the FORTRAN random number generator RAN.
Declare z and MTH$CDLOG as complex values. Then MTH$CDLOG
will return the logarithm of Z: CALL MTH$CDLOG(Z_NEW,Z).

c
C
C
C

Declare Z,Z LOG, and MTH$DCMPLX as complex values,
and R and I-as real values. MTH$DCMPLX takes two real
arguments and returns one complex number.

c
C
C
C-

Given a complex number Z, MTH$CDLOG(Z) returns the
complex natural logarithm of z.
COMPLEX*l6 Z,Z NEW,MTH$DCMPLX
REAL*B R, I
R = 3.1425637846746565
I= 7.43678469887
Z = MTH$DCMPLX(R,I)

c+
C
C
C-

Z is a complex number (r,i) with real part "r" and imaginary
part "i".
TYPE *, ' The complex number z is' ,z
TYPE *I
CALL MTH$CDLOG(Z NEW,Z)
TYPE*,' The complex logarithm of' ,z,' is' ,Z_NEW
END
I

MTH-37

MTH$CxLOG

This FORTRAN example program uses MTH$CDLOG by calling it as a procedure.
The output generated by this program is as follows:
The complex number z is (3.142563784674657,7.436784698870000)
The complex logarithm of (3.142563784674657,7.436784698870000) is
(2.088587642177504,1.170985519274141)

MTH-38

MTH$CMPLX

MTH$CMPLX-Complex Number Made from F-Floating-Point
The Complex Number Made from F-Floating-Point routine returns a complex
number from two floating-point input values.

Format
MTH$CMPLX

real-part ,imaginary-part

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

A complex number. MTH$CMPLX returns an F-floating complex number.

Arguments
real-part

OpenVMS usage
type
access
mechanism

floating_point
F _floating
read only
by reference

Real part of a complex number. The real-part argument is the address of a
floating-point number that contains this real part, r, of (r,i). For MTH$CMPLX,
real-part specifies an F-floating number.
imaginary-part

OpenVMS usage
type
access
mechanism

floating_point
F _floating
read only
by reference

Imaginary part of a complex number. The imag-parg argument is the address
of a floating-point number that contains this imaginary part, i, of (r,i). For
MTH$CMPLX, imaginary-part specifies an F-floating number.

Description
The MTH$CMPLX routines return a complex number from two F-floating input
values. The routine descriptions for the D- and G-floating point versions of this
routine are listed alphabetically under MTH$xCMPLX.

MTH-39

MTH$CMPLX

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$CMPLX routine
encountered a :floating-point reserved operand
due to incorrect user input. A :floating-point
reserved operand is a :floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

Example
C+
C
C
C

This FORTRAN example forms two F-f loating
point complex numbers using MTH$CMPLX
and the FORTRAN random number generator RAN.

C
C
C

Declare z and MTH$CMPLX as complex values, and R
and I as real values. MTH$CMPLX takes two real
F-floating point values and returns one COMPLEX*8 number.

C
C
C

Note, since CMPLX is a generic name in FORTRAN, it would be
sufficient to use CMPLX.
CMPLX must be declare to be of type COMPLEX*8.

C
C-

Z = CMPLX(R,I)

c
c
c

COMPLEX Z,MTH$CMPLX,CMPLX
REAL*4 R,I
INTEGER M
M = 1234567
R = RAN(M)
I = RAN(M)
Z = MTH$CMPLX(R,I)

c+
C
C
C-

z is a complex number (r,i) with real part "r" and
imaginary part "i".
TYPE*, ' The two input values are:' ,R,I
TYPE *, ' The complex number z is' ,z
z = CMPLX(RAN(M),RAN(M))
TYPE * I I I
TYPE *,
Using the FORTRAN generic CMPLX with random Rand I:'
TYPE *, ' The complex number z is' ,z
END
I

This FORTRAN example program demonstrates the use of MTH$CMPLX. The
output generated by this program is as follows:
The two input values are: 0.8535407
0.2043402
The complex number z is (0.8535407,0.2043402)
Using the FORTRAN generic CMPLX with random R and I:
The complex number z is (0.5722565,0.1857677)

MTH-40

MTH$xCMPLX

MTH$xCMPLX-Complex Number Made from D- or
G-Floating-Point
The Complex Number Made from D- or G-Floating-Point routine returns a
complex number from two D- or G-floating input values.

Format
MTH$DCMPLX

complx ,real-part ,imaginary-part

MTH$GCMPLX

complx ,real-part ,imaginary-part

Each of the above formats accepts one of floating-point complex types as input.

Returns
None.

Arguments
comp Ix

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
write only
by reference

The floating-point complex value of a complex number. The complex
exponential functions that have D-floating complex and G-floating complex
input values write the address of this floating-point complex value into
complx. For MTH$DCMPLX, complx specifies a D-floating complex number.
For MTH$GCMPLX, complx specifies a G-floating complex number. For
MTH$CMPLX, complx is not used.
real-part

OpenVMS usage
type
access
mechanism

floating_point
D_floating, G_floating
read only
by reference

Real part of a complex number. The real-part argument is the address of a
floating-point number that contains this real part, r, of (r,i). For MTH$DCMPLX,
real-part specifies a D-floating number. For MTH$GCMPLX, real-part specifies
a G-floating number.
imaginary-part

OpenVMS usage
type
access
mechanism

floating_point
D_floating, G_floating
read only
by reference

Imaginary part of a complex number. The imag-parg argument is the
address of a floating-point number that contains this imaginary part, i, of
(r,i). For MTH$DCMPLX, imaginary-part specifies a D-floating number. For
MTH$GCMPLX, imaginary-part specifies a CT-floating number.

MTH-41

MTH$xCMPLX

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xCMPLX routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

Example
C+
C
C
C

C
C

This FORTRAN example forms two D-f loating
point complex numbers using MTH$CMPLX
and the FORTRAN random number generator RAN.
Declare z and MTH$DCMPLX as complex values, and R
and I as real values. MTH$DCMPLX takes two real
D-f loating point values and returns one
COMPLEX*l6 number.

C-

COMPLEX*l6 Z
REAL*8 R,I
INTEGER M
M = 1234567
R = RAN(M)
I = RAN(M)
CALL MTH$DCMPLX(Z,R,I)
C+
C

Z is a complex number (r,i) with real part "r" and imaginary
part "i".

C-

TYPE*, ' The two input values are:' ,R,I
TYPE *, ' The complex number z is' ,z
END

This FORTRAN example demonstrates how to make a procedure call to
MTH$DCMPLX. Notice the difference in the precision of the output generated.
The two input values are: 0.8535407185554504
0.2043401598930359
The complex number z is (0.8535407185554504,0.2043401598930359)

MTH-42

MTH$CONJG

MTH$CONJG-Conjugate of a Complex Number (F-Floating Value)
The Conjugate of a Complex Number CF-Floating Value) routine returns the
complex conjugate (r,-i) of a complex number (r,i) as an F-floating value.

Format
MTH$CONJG

complex-number

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

Complex conjugate of a complex number. MTH$CONJG returns an F-floating
complex number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
read only
by reference

A complex number (r,i), where rand i are floating-point numbers. The complexnumber argument is the address of this floating-point complex number. For
MTH$CONJG, complex-number specifies an F-floating number.

Description
The MTH$CONJG routine returns the complex conjugate (r,-i) of a complex
number (r,i) as an F-floating value. The routine descriptions for the Dand G-floating point versions of this routine are listed alphabetically under
MTH$xCONJG.

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$CONJG routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

llATU

A'l

MTH$xCONJG

MTH$xCONJG-Conjugate of a Complex Number
The Conjugate of a Complex Number routine returns the complex conjugate (r,-i)
of a complex number (r,i).

Format
MTH$DCONJG

complex-conjugate ,complex-number

MTH$GCONJG

complex-conjugate ,complex-number

Each of the above formats accepts one of the floating-point complex types as
input.

Returns
None.

Arguments
complex-conjugate

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
write only
by reference

The complex conjugate (r,-i) of the complex number specified by complexnumber. MTH$DCONJG and MTH$GCONJG write the address of this
complex conjugate into complex-conjugate. For MTH$DCONJG, the complexconjugate argument specifies the address of a D-floating complex number. For
MTH$GCONJG, the complex-conjugate argument specifies the address of a
G-floating complex number.
complex-number

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
read only
by reference

A complex number (r,i), where r and i are floating-point numbers. The complexnumber argument is the address of this floating-point complex number.
For MTH$DCONJG, complex-number specifies a D-floating number. For
MTH$GCONJG, complex-number specifies a G-floating number.

Condition Value Signaled
SS$_ROPRAND

MTH-44

Reserved operand. The MTH$xCONJG routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xCONJG

Example
Ct
C
C
C

This FORTRAN example forms the complex conjugate
of a G-f loating complex number using MTH$GCONJG
and the FORTRAN random number generator RAN.

Declare z, Z NEW, and MTH$GCONJG as a complex values.
MTH$GCONJG will return the complex conjugate
value of Z:
Z_NEW = MTH$GCONJG(Z).

C
C
C
C-

COMPLEX*l6 Z,Z NEW,MTH$GCONJG
COMPLEX*l6 MTH$GCMPLX
REAL*8 R,I,MTH$GREAL,MTH$GIMAG
INTEGER M
M = 1234567
C+
C
C
C-

Generate a random complex number with the
FORTRAN generic CMPLX.

1
Ct
C
C-

R = RAN(M)
I = RAN(M)
Z = MTH$GCMPLX(R,I)
TYPE *, ' The complex number z is' ,z
TYPE 1,MTH$GREAL(Z),MTH$GIMAG(Z)
FORMAT(' with real part ',F20.16,' and imaginary part' ,F20.16)
TYPE * I I ,
Compute the complex absolute value of z.
Z NEW = MTH$GCONJG(Z)
TYPE*, 'The complex conjugate value of' ,z,' is' ,Z_NEW
TYPE 1,MTH$GREAL(Z NEW),MTH$GIMAG(Z NEW)
END
-

This FORTRAN example demonstrates how to make a function call to
MTH$GCONJG. Because G-floating numbers are used, the examples must
be compiled with the statement "FORTRAN/G filename".
The output generated by this program is as follows:
The complex number z is (0.853540718555450,0.204340159893036)
with real part
0.8535407185554504
and imaginary part 0.2043401598930359
The complex conjugate value of
(0.853540718555450,0.204340159893036) is
(0.853540718555450,-0.204340159893036)
with real part
0.8535407185554504
and imaginary part -0.2043401598930359

l\llTl-L.i:ii::

MTH$xCOS

MTH$xCOS-Cosine of Angle Expressed in Radians
The Cosine of Angle Expressed in Radians routine returns the cosine of a given
angle (in radians).

Format
MTH$COS

angle-in-radians

MTH$DCOS

angle-in-radians

MTH$GCOS

angle-in-radians

Each of the above formats accepts one of the floating-point types as input.
JSB Entries

MTH$COS_R4
MTH$DCOS_R7
MTH$GCOS_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Cosine of the angle. MTH$COS returns an F-floating number. MTH$DCOS
returns a D-floating number. MTH$GCOS returns a G-floating number.

Arguments
angle-in-radians

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The angle in radians. The angle-in-radians argument is the address of a
floating-point number. For MTH$COS, angle-in-radians is an F-floating
number. For MTH$DCOS, angle-in-radians specifies a D-floating number. For
MTH$GCOS, angle-in-radians specifies a G-floating number.

Description
See the MTH$xSINCOS routine for the algorithm used to compute the cosine.
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HCOS.

MTH$xCOS

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xCOS procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

llJITU

11"7

MTH$xCOSD

MTH$xCOSD-Cosine of Angle Expressed in Degrees
The Cosine of Angle Expressed in Degrees routine returns the cosine of a given
angle (in degrees).

Format
MTH$COSD

angle-in-degrees

MTH$DCOSD

angle-in-degrees

MTH$GCOSD

angle-in-degrees

Each of the above formats accepts one of the floating-point types as input.
JSB Entries

MTH$COSD_R4
MTH$DCOSD_R7
MTH$GCOSD_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Cosine of the angle. MTH$COSD returns an F-floating number. MTH$DCOSD
returns a D-floating number. MTH$GCOSD returns a G-floating number.

Arguments
angle-in-degrees

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Angle (in degrees). The angle-in-degrees argument is the address of a floatingpoint number. For MTH$COSD, angle-in-degrees specifies an F-floating
number. For MTH$DCOSD, angle-in-degrees specifies a D-floating number. For
MTH$GCOSD, angle-in-degrees specifies a G-floating number.

Description
See the MTH$SINCOSD routine for the algorithm used to compute the cosine.
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HCOSD.

MTH-48

MTH$xCOSD

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xCOSD procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xCOSH

MTH$xCOSH-Hyperbolic Cosine
The Hyperbolic Cosine routine returns the hyperbolic cosine of the input value.

Format
MTH$COSH

floating-point-input-value

MTH$DCOSH

floating-point-input-value

MTH$GCOSH

floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The hyperbolic cosine of the input value floating-point-input-value.
MTH$COSH returns an F-floating number. MTH$DCOSH returns a D-fioating
number. MTH$GCOSH returns a G-fioating number.

Arguments
floating-point-input-value

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_fioating, G_floating
read only
by reference

The input value. The floating-point-input-value argument is the address of
this input value. For MTH$COSH, floating-point-input-value specifies an
F-floating number. For MTH$DCOSH, floating-point-input-value specifies a
D-floating number. For MTH$GCOSH, floating-point-input-value specifies a
G-floating number.

Description
Computation of the hyperbolic cosine depends on the magnitude of the input
argument. The range of the function is partitioned using four data-typedependent constants: a(z), b(z), and c(z). The subscript z indicates the data
type. The constants depend on the number of exponent bits (e) and the number of
fraction bits ({) associated with the data type (z ).
The values of e and fare:

MTH-50

F
D
G

8
8
11

MTH$xCOSH

The values of the constants in terms of e and fare:
Variable

Value

a(z)
b(z)
c(z)

2(-/ /2)

CEILING[(!+ 1)/2 * ln(2)]
(2e - l) * In (2)

Based on the above definitions, zCOSH(X) is computed as follows:
Value of X

Value Returned

IX I < a(z)
a(z) s I X I < .25
.25 s I X I < b(z)
b(z) ::::; I X I < c(z)
c(z) ::::; I x I

Computed using a power series expansion in IXl 2

(zEXP(IXI) + 1/zEXP(IXl))/2
zEXP(IXl)/2
Overflow occurs

This routine description for the H-floating point value is listed alphabetically
under MTH$HCOSH.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$xCOSH procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of floating-point-input-value is
greater than about yyy; LIB$SIGNAL copies the
reserved operand to the signal mechanism vector.
The result is the reserved operand -0.0 unless a
condition handler changes the signal mechanism
vector.
The values of yyy are:
MTH$COSH-88.722
MTH$DCOSH-88. 722
MTH$GCOSH-709.782

MTH-Fi1

MTH$CSIN

MTH$CSIN-Sine of a Complex Number (F-Floating Value)
The Sine of a Complex Number CF-Floating Value) routine returns the sine of a
complex number (r,i) as an F-floating value.

Format
MTH$CSIN

complex-number

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

Complex sine of the complex number. MTH$CSIN returns an F-floating complex
number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
read only
by reference

A complex number (r,i), where r and i are floating-point numbers. The complexnumher argument is the address of this complex number. For MTH$CSIN,
complex-number specifies an F-floating complex number.

Description
The complex sine is computed as follows:
complex - sine= (SIN(r) * COSH(i), COS(r) * SJNH(i))

The routine descriptions for the D- and G-floating point versions of this routine
are listed alphabetically under MTH$CxSIN.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH-52

Reserved operand. The MTH$CSIN procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of i is greater than about 88.029
for F-floating values.

MTH$CxSIN

MTH$CxSIN-Sine of a Complex Number
The Sine of a Complex Number routine returns the sine of a complex number (r,i).

Format
MTH$CDSIN

complex-sine ,complex-number

MTH$CGSIN

complex-sine ,complex-number

Each of the above formats accepts one of the floating-point complex types as
input.

Returns
None.

Arguments
complex-sine

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
write only
by refere nee

Complex sine of the complex number. The complex sine routines with D-floating
complex and G-floating complex input values write the complex sine into this
complex-sine argument. For MTH$CDSIN, complex-sine specifies a D-floating
complex number. For MTH$CGSIN, complex-sine specifies a G-floating complex
number.
complex-number

OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
read only
by reference

A complex number (r,i), where r and i are floating-point numbers. The complexnumber argument is the address of this complex number. For MTH$CDSIN,
complex-number specifies a D-floating complex number. For MTH$CGSIN,
complex-number specifies a G-floating complex number.

Description
The complex sine is computed as follows:
complex - sine= (SIN(r) * COSH(i), COS(r) *SIN H(i))

MTH-S~

MTH$CxSIN

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$CxSIN procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of i is greater than about 88.029
for D-floating values, or greater than about
709.089 for G-floating values.

Example
C+

c
c

C
C

c
c

C
C
C-

This FORTRAN example forms the complex
sine of a G-f loating complex number using
MTH$CGSIN and the FORTRAN random number
generator RAN.
Declare Z and MTH$CGSIN as complex values.
MTH$CGSIN will return the sine value
of Z:
CALL MTH$CGSIN(Z_NEW,Z)
COMPLEX*l6 Z,Z NEW
COMPLEX*l6 DCMPLX
REAL*8 R,I
INTEGER M
M = 1234567

C+

C
C-

Generate a random complex number with the
FORTRAN generic DCMPLX.
R = RAN(M)
I = RAN(M)
Z = DCMPLX(R,I)

C+
C
C
C-

Z is a complex number (r,i) with real part "r" and
imaginary part "i".
TYPE *, ' The complex number z is' ,z
TYPE * I

C+
C
C-

Compute the complex sine value of z.
CALL MTH$CGSIN(Z NEW,Z)
TYPE*,
The complex sine value of' ,z,' is' ,Z_NEW
END
I

This FORTRAN example demonstrates a procedure call to MTH$CGSIN. Because
this program uses G-floating numbers, it must be compiled with the statement
"FORTRAN/G filename".

MTH-54

MTH$CxSIN

The output generated by this program is as follows:
The complex number z is (0.853540718555450,0.204340159893036)
The complex sine value of (0.853540718555450,0.204340159893036) is
(0.769400835484975,0.135253340912255)

MTH-55

MTH$CSQRT

MTH$CSQRT-Complex Square Root (F-Floating Value)
The Complex Square Root CF-Floating Value) routine returns the complex square
root of a complex number (r,i).

Format
MTH$CSQRT complex-number

Returns
OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
write only
by value

The complex square root of complex-number. MTH$CSQRT returns an Ffioating number.

Arguments
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex
read only
by reference

Complex number (r,i). The complex-number argument contains the address
of this complex number. For MTH$CSQRT, complex-number specifies an
F-fioating number.

Description
The complex square root is computed as follows.
First, calculate ROOT and Q using the following equations:
ROOT= SQRT((ABS(r) + CABS(r, i))/2)
Q = i/(2 *ROOT)

Then, the complex result is given as follows:
r

CSQRT((r,i))

Any
~o

(ROOT,Q)
(Q,ROOT)
(-Q,-ROOT)

The routine descriptions for the D- and G-fioating point versions of this routine
are listed alphabetically under MTH$CxSQRT.

MTH-56

MTH$CSQRT

Condition Value Signaled
SS$_FLTOVF_F
SS$_ROPRAND

Floating point overflow can occur.
Reserved operand. The MTH$CSQRT procedure
encountered a :floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a :floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH-57

MTH$CxSQRT

MTH$CxSQRT-Complex Square Root
The Complex Square Root routine returns the complex square root of a complex
number (r,i).

Format
MTH$CDSQRT complex-square-root ,complex-number
MTH$CGSQRT complex-square-root ,complex-number

Each of the above formats accepts one of the floating-point complex types as
input.

Returns
None.

Arguments
complex-square-root
OpenVMS usage complex_number
type
D_floating complex, G_floating complex
access
write only
mechanism
by reference

Complex square root of the complex number specified by complex-number.
The complex square root routines that have D-floating complex and G-floating
complex input values write the complex square root into complex-squareroot. For MTH$CDSQRT, complex-square-root specifies a D-floating complex
number. For MTH$CGSQRT, complex-square-root specifies a G-floating
complex number.
complex-number
OpenVMS usage
type
access
mechanism

complex_number
D_floating complex, G_floating complex
read only
by reference

Complex number (r,i). The complex-number argument contains the address
of this complex number. For MTH$CDSQRT, complex-number specifies a Dfloating number. For MTH$CGSQRT, complex-number specifies a G-floating
number.

Description
The complex square root is computed as follows.
First, calculate ROOT and Q using the following equations:
ROOT= SQRT((ABS(r) + CABS(r, i))/2)
Q = i/(2 *ROOT)

MTH-58

MTH$CxSQRT

Then, the complex result is given as follows:
CSQRT((r,i))

2:0

any

2:0

(ROOT,Q)
(Q,ROOT)
(-Q,-ROOT)

Condition Value Signaled
SS$_FLTOVF_F
SS$_ROPRAND

Floating point overflow can occur.
Reserved operand. The MTH$CxSQRT procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

Example
C+

C
C
C
C

This FORTRAN example forms the complex square
root of a D-f loating complex number using
MTH$CDSQRT and the FORTRAN random number
generator RAN.

C
C
C
C-

Declare z and Z NEW as complex values. MTH$CDSQRT
will return the-complex square root of
Z:
CALL MTH$CDSQRT(Z_NEW,Z).

COMPLEX*l6 Z,Z NEW
COMPLEX*l6 DCMPLX
INTEGER M
M = 1234567

c+
C
C
C-

Generate a random complex number with the
FORTRAN generic CMPLX.
Z = DCMPLX(RAN(M),RAN(M))

C+

C
C
C-

z is a complex number (r,i) with real part "r" and imaginary
part "i".
TYPE *, ' The complex number z is' ,z
TYPE * , , ,

c+
C

Compute the complex complex square root of z.
CALL MTH$CDSQRT(Z NEW,Z)
TYPE*, 'The complex square root of' ,z,' is' ,Z_NEW
END

MTH-59

MTH$CxSQRT

This FORTRAN example program demonstrates a procedure call to
MTH$CDSQRT. The output generated by this program is as follows:
The complex number z is (0.8535407185554504,0.2043401598930359)
The complex square root of (0.8535407185554504,0.2043401598930359) is
(0.9303763973040062,0.1098158554350485)

MTH-60

MTH$CVT_x_x

MTH$CVT_x_x-Convert One Double-Precision Value
The Convert One Double-Precision Value routines convert one double-precision
value to the destination data type and return the result as a function value.
MTH$CVT_D_G converts a D-floating value to G-floating and MTH$CVT_G_D
converts a G-floating value to a D-floating value.

Format
MTH$CVT_D_G

floating-point-input-val

MTH$CVT_G_D

floating-point-input-val

OpenVMS usage
type
access
mechanism

floating_point
G_floating, D_floating
write only
by value

Returns

The converted value. MTH$CVT_D_G returns a G-floating value. MTH$CVT_G_
D returns a D-floating value.

ARGUMENT
floating-point-input-val

OpenVMS usage
type
access
mechanism

floating_point
D_floating, G_floating
read only
by reference

The input value to be converted. The floating-point-input-val argument
is the address of this input value. For MTH$CVT_D_G, the floating-pointinput-val argument specifies a D-floating number. For MTH$CVT_G_D, the
floating-point-input-val argument specifies a G-floating number.

Description
These procedures are designed to function as hardware conversion instructions.
They fault on reserved operands. If floating-point overflow is detected, an error
is signaled. If floating-point underflow is detected and floating-point underflow is
enabled, an error is signaled.

MTH-n1

MTH$CVT_x_x

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT
MTH$_FLOUNDMAT

MTH-62

Reserved operand. The MTH$CVT_x_x
procedure encountered a floating-point reserved
operand due to incorrect user input. A floatingpoint reserved operand is a floating-point datum
with a sign bit of 1 and a biased exponent of 0.
Floating-point reserved operands are reserved for
future use by Digital.
Floating-point overflow in Math Library.
Floating-point underflow in Math Library.

MTH$CVT_xA_xA

MTH$CVT_xA_xA-Convert an Array of Double-Precision Values
The Convert an Array of Double-Precision Values routines convert a contiguous
array of double-precision values to the destination data type and return the
results as an array. MTH$CVT_DA_GA converts D-floating values to G-floating
and MTH$CVT_GA_DA converts G-floating values to D-floating.

Format
MTH$CVT_DA_GA

floating-point-input-array ,floating-point-dest-array [,array-size]

MTH$CVT_GA_DA

floating-point-input-array ,floating-point-dest-array [,array-size]

Returns
OpenVMS usage

HEADONLY

MTH$CVT_DA_GA and MTH$CVT_GA_DA return the address of the output
array to the floating-point-dest-array argument.

Arguments
floating-point-in put-array
OpenVMS usage :floating_point
type
D_floating, G_:floating
access
read only
mechanism
by reference, array reference

Input array of values to be converted. The floating-point-input-array argument
is the address of an array of :floating-point numbers. For MTH$CVT_DA_GA,
floating-point-input-array specifies an array of D-:floating numbers. For
MTH$CVT_GA_DA, floating-point-input-array specifies an array of G-:floating
numbers.
floating-point-dest-array
OpenVMS usage :floating_point
type
G_floating, D_:floating
access
write only
mechanism
by reference, array reference

Output array of converted values. The floating-point-dest-array argument
is the address of an array of :floating-point numbers. For MTH$CVT_DA_
GA, floating-point-dest-array specifies an array of G-floating numbers. For
MTH$CVT_GA_DA, floating-point-dest-array specifies an array of D-floating
numbers.
array-size
OpenVMS usage
type
access
mechanism

longword_signed
longword (signed)
read only
by reference

Number of array elements to be converted. The default value is 1. The arraysize argument is the address of a longword containing this number of elements.

MTH-63

MTH$CVT_xA_xA

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT
MTH$_FLOUNDMAT

MTH-64

Reserved operand. The MTH$CVT_xA_xA
procedure encountered a floating-point reserved
operand due to incorrect user input. A floatingpoint reserved operand is a floating-point datum
with a sign bit of 1 and a biased exponent of 0.
Floating-point reserved operands are reserved for
future use by Digital.
Floating-point overflow in Math Library.
Floating-point underflow in Math Library.

MTH$xEXP

MTH$xEXP-Exponential
The Exponential routine returns the exponential of the input value.

Format
MTH$EXP

floating-point-input-value

MTH$DEXP

floating-point-input-value

MTH$GEXP

floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$EXP_R4
MTH$DEXP_R6
MTH$GEXP_R6

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
floating_point
F _floating, D_floating, G_floating
write only
by value

OpenVMS usage
type
access
mechanism

The exponential of floating-point-input-value. MTH$EXP returns an F-floating
number. MTH$DEXP returns a D-floating number. MTH$GEXP returns a
G-floating number.

Arguments
floating-point-in put-value
OpenVMS usage floating_point
type
F _floating, D_floating, G_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of
a floating-point number. For MTH$EXP, floating-point-input-value specifies
an F-floating number. For MTH$DEXP, floating-point-input-value specifies
a D-floating number. For MTH$GEXP, floating-point-input-value specifies a
G-floating number.

Description
The exponential of x is computed as:
Value of x

Value Returned

X > c(z)

Overflow occurs

- c(z)

l\ATH-RFi

MTH$xEXP

Value of x

Value Returned

IXI < 2-(f+l)
Otherwise
where: Y = INTEGER(x * ln2(E)) V = FRAC(x * ln2(E)) * 16
U = INTEGER(V)/16 W = FRAC(V)/16 2W =polynomial approximation of
degree 4, 8, or 8 for z = F, D, or G.
See also the section on the hyperbolic cosine for definitions off and c(z).
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HEXP.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH$_FLOUNDMAT

Floating-point underflow in Math Library:
floating-point-input-value is less than or
equal to yyy and the caller (CALL or JSB) has
set hardware floating-point underflow enable.
The result is set to 0.0. If the caller has not
enabled floating-point underflow (the default), a
result of 0.0 is returned but no error is signaled.
The values of yyy are approximately:
MTH$EXP- - 88. 722
MTH$DEXP- - 88.722
MTH$GEXP- - 709.774

MTH-66

MTH$xEXP

Example
IDENTIFICATION DIVISION.
PROGRAM-ID.
FLOATING POINT.

*
* Calls MTH$EXP using a Floating Point data type.
* Calls MTH$DEXP using a Double Floating Point data type.
*

CALL MTH$EXP USING BY REFERENCE FLOAT PT GIVING ANSWER F.
DISPLAY MTH$EXP of
FLOAT PT CONVERSION,
is
ANSWER F CONVERSION.
11

CALL MTH$DEXP" USING BY REFERENCE DOUBLE PT GIVING ANSWER D.
DISPLAY MTH$DEXP of
DOUBLE PT CONVERSION,
is
ANSWER D CONVERSION .
STOP RUN.
11

This sample program demonstrates calls to MTH$EXP and MTH$DEXP from
COBOL.
The output generated by this program is as follows:
MTH$EXP of 1.234000E+Ol is 2.286620E+05
MTH$DEXP of 3.456000000000000E+OO is
3.168996280537917E+Ol

MTH-n7

MTH$HACOS

MTH$HACOS-Arc Cosine of Angle Expressed in Radians
(H-Floating Value)
Given the cosine of an angle, the Arc Cosine of Angle Expressed in Radians
CH-Floating Value) routine returns that angle (in radians) in H-floating-point
precision.

Format
MTH$HACOS

h-radians ,cosine

JSB Entries
MTH$HACOS_R8

Returns
None.

Arguments
h-radians
OpenVMS usage
type
·access
mechanism

floating_point
H_floating
write only
by reference

Angle (in radians) whose cosine is specified by cosine. The h-radians argument
is the address of an H-floating number that is this angle. MTH$HACOS writes
the address of the angle into h-radians.
cosine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Description
The angle in radians whose cosine is X is computed as:

MTH-68

Value of Cosine

Value Returned

7r/2

-1

MTH$HACOS

Value of Cosine

x<1

-1 <

x<0

1 < IXI

Value Returned

zAT AN(zSQRT(l - X 2 )/ X), where zATAN and zSQRT are the

Math Library arc tangent and square root routines, respectively,
of the appropriate data type
zAT AN(zSQRT(l - X 2 )/ X) + n
The error MTH$_INVARGMAT is signaled

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

Reserved operand. The MTH$xACOS routine
encountered a floating-point reserved operand
due to incorrect user input. A :floating-point
reserved operand is a :floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. The absolute value of cosine
is greater than 1. LIB$SIGNAL copies the
:floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the :floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.

MTH-RQ

MTH$HACOSD

MTH$HACOSD-Arc Cosine of Angle Expressed in Degrees
(H-Floating Value)
Given the cosine of an angle, the Arc Cosine of Angle Expressed in Degrees
(H-Floating Value) routine returns that angle (in degrees) as an H-floating value.

Format
MTH$HACOSD

h-degrees ,cosine

JSB Entries
MTH$HACOSD_R8

Returns
None.

Arguments
h-degrees
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Angle (in degrees) whose cosine is specified by cosine. The h-degrees argument
is the address of an H-floating number that is this angle. MTH$HACOSD writes
the address of the angle into h-degrees.
cosine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Description
The angle in degrees whose cosine is Xis computed as:
Value of Cosine

Angle Returned

-1

180

0< X < 1

zATAND(zSQRT(l - X 2 )/X), where zATAND and zSQRT

are the Math Library arc tangent and square root routines,
respectively, of the appropriate data type

MTH-70

MTH$HACOSD

Value of Cosine

Angle Returned

-1 < X < O

zATAND(zSQRT(1- X 2 )/X) + 180
The error MTH$_INVARGMAT is signaled

1 <\XI

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

MTH-71

MTH$HASIN

MTH$HASIN-Arc Sine in Radians (H-Floating Value)
Given the sine of an angle, the Arc Sine in Radians CH-Floating Value) routine
returns that angle (in radians) as an H-floating value.

Format
MTH$HASIN

h-radians ,sine

JSB Entries
MTH$HASIN_R8

Returns
None.

Arguments
h-radians
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Angle (in radians) whose sine is specified by sine. The h-radians argument is
the address of an H-floating number that is this angle. MTH$HASIN writes the
address of the angle into h-radians.
sine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Description
The angle in radians whose sine is Xis computed as:
Value of Sine

Angle Returned

7r/2

-1

-7r/2

0 < IXI < 1

zATAN(X/zSQRT(l - X 2 )), where zATAN and zSQRT are the

1x1

Math Library arc tangent and square root routines, respectively,
of the appropriate data type
The error MTH$_INVARGMAT is signaled

i <

MTH-72

MTH$HASIN

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

Reserved operand. The MTH$xASIN routine
encountered a :floating-point reserved operand
due to incorrect user input. A :floating-point
reserved operand is a :floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. The absolute value of sine
is greater than 1. LIB$SIGNAL copies the
:floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.

MTH-73

MTH$HASIND

MTH$HASIND-Arc Sine in Degrees (H-Floating Value)
Given the sine of an angle, the Arc Sine in Degrees CH-Floating Value) routine
returns that angle (in degrees) as an H-fioating value.

Format
MTH$HASIND

h-degrees ,sine

JSB Entries
MTH$HASIND_R8

Returns
None.

Arguments
h-degrees
OpenVMS usage
type
access
mechanism

fioating_point
H_fioating
write only
by reference

Angle (in degrees) whose sine is specified by sine. The h-degrees argument is
the address of an H-fioating number that is this angle. MTH$HASIND writes the
address of the angle into h-degrees.
sine
OpenVMS usage
type
access
mechanism

floating_point
H_fioating
read only
by reference

Description
The angle in degrees whose sine is Xis computed as:

MTH-74

Value of Sine

Value Returned

-1

-90

0 < IXI < 1

zATAN D(X/zSQRT(l - X 2 )), where zATAND and zSQRT

1 < IXI

are the Math Library arc tangent and square root routines,
respectively, of the appropriate data type
The error MTH$_INVARGMAT is signaled

MTH$HASIND

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

MTH-75

MTH$HATAN

MTH$HATAN-Arc Tangent in Radians {H-Floating Value)
Given the tangent of an angle, the Arc Tangent in Radians (H-Floating Value)
routine returns that angle (in radians) as an H-floating value.

Format
MTH$HATAN

h-radians ,tangent

JSB Entries
MTH$HATAN_R8

Returns
None.

Arguments
h-radians
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Angle (in radians) whose tangent is specified by tangent. The h-radians
argument is the address of an H-floating number that is this angle.
MTH$HATAN writes the address of the angle into h-radians.
tangent
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The tangent of the angle whose value (in radians) is to be returned. The tangent
argument is the address of a floating-point number that is this tangent. For
MTH$HATAN, tangent specifies an H-floating number.

Description
In radians, the computation of the arc tangent function is based on the following
identities:
arctan(X) = X - X 3 /3 + x 5 /5 - X 7 /7 + ...
arctan(X) = X + X * Q(X2 ),
where Q(Y) = -Y/3 + Y 2 /5 - y3 /7 + ...
arctan(X) = X * P(X2 ),
where P(Y) = 1- Y /3 + Y 2 /5 - Y 3 /7 + ...
arctan(X) = rr /2 - arctan(l/ X)
arctan(X) = arctan(A) + arctan((X - A)/(1 +A* X))
for any real A

MTH-76

MTH$HATAN

The angle in radians whose tangent is X is computed as:
Value of X

Angle Returned

O~X~3/32

X + X * Q(X 2 )
ATAN(A) + V * (P(V 2 )), where A and ATAN(A) are
chosen by table lookup and V = (X - A)/(1 +A* X)

3/32 < X~ll
11 <

X< o

7r/2 - W * (P(W 2 )) where W = 1/X
-zAT AN(JXJ)

Condition Value Signaled
SS$_ROPRAND

MTH-77

MTH$HATAND

MTH$HATAND-Arc Tangent in Degrees (H-Floating Value)
Given the tangent of an angle, the Arc Tangent in Degrees CH-Floating Value)
routine returns that angle (in degrees) as an H-floating point value.

Format
MTH$HATAND

h-degrees ,tangent

JSB Entries
MTH$HATAND_R8

Returns
None.

Arguments
h-degrees

OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Angle (in degrees) whose tangent is specified by tangent. The h-degrees
argument is the address of an H-floating number that is this angle.
MTH$HATAND writes the address of the angle into h-degrees.
tangent

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The tangent of the angle whose value (in degrees) is to be returned. The tangent
argument is the address of a floating-point number that is this tangent. For
MTH$HATAND, tangent specifies an H-floating number.

Description
The computation of the arc tangent function is based on the following identities:
arctan(X) = 180/11" * (X - X 3 /3 + x 5 /5 - x 7 /7 + ... )
arctan(X) = 64 * X + X * Q(X2),
where Q(Y) = 180/11" * [(1- 64 * 11"/180) - Y/3+
y2 /5- y3 /7 + y4 /9 ... ]
arctan(X) = X * P(X 2 ),
where P(Y) = 180/11" * [1 - Y/3 + Y 2/5 - y3 /7+
y4/9 ... ]
arctan(X) = 90 - arctan(l/ X)
arctan(X) = arctan(A) + arctan((X - A)/(l +A* X))

MTH-78

MTH$HATAND

The angle in degrees whose tangent is Xis computed as:
Tangent

Angle Returned

X5:3/32

64 *

3/32 < X5:11

ATAND(A) + V * P(V 2 ), where A and ATAND(A) are
chosen by table lookup and V = (X - A)/(1 +A* X)

11 <

X< O

x + x * Q (x 2 )

90 - W * (P(W 2 )), where W = 1/X
-zATAN D(IXI)

Condition Value Signaled
SS$_ROPRAND

MTH-79

MTH$HATAN2

MTH$HATAN2-Arc Tangent in Radians (H-Floating Value) with Two
Arguments
Given sine and cosine, the Arc Tangent in Radians (H-Floating Value) with Two
Arguments routine returns the angle (in radians) as an H-floating value whose
tangent is given by the quotient of sine and cosine, (sine/cosine).

Format
MTH$HATAN2

h-radians ,sine ,cosine

Returns
None.

Arguments
h-radians
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Angle (in radians) whose tangent is specified by (sine/cosine). The hradians argument is the address of an H-floating number that is this angle.
MTH$HATAN2 writes the address of the angle into h-radians.
sine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Dividend. The sine argument is the address of a floating-point number that is
this dividend. For MTH$HATAN2, sine specifies an H-floating number.
cosine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Divisor. The cosine argument is the address of a floating-point number that is
this divisor. For MTH$HATAN2, cosine specifies an H-floating number.

Description
The angle in radians whose tangent is Y/X is computed as follows, where f is
defined in the description of MTH$zCOSH:

MTH-80

Value of Input Arguments

Angle Returned

X =a or Y/X > 2U+l)

X > 0 and Y/X~ 2U+l)

zATAN(Y/X)

/2 * (signY)

MTH$HATAN2

Value of Input Arguments

Angle Returned

X < 0 and Y/X~ 2(/+l)

11"

* (signY) + zATAN(Y/X)

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

Reserved operand. The MTH$HATAN2 routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. Both cosine and sine are
zero. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH-81

MTH$HATAND2

MTH$HATAND2-Arc Tangent in Degrees (H-Floating Value) with Two
Arguments
Given sine and cosine, the Arc Tangent in Degrees CH-Floating Value) with Two
Arguments routine returns the angle (in degrees) whose tangent is given by the
quotient of sine and cosine, (sine/cosine).

Format
MTH$HATAND2

h-degrees ,sine ,cosine

Returns
None.

Arguments
h-degrees
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Angle (in degrees) whose tangent is specified by (sine/cosine). The hdegrees argument is the address of an H-floating number that is this angle.
MTH$HATAND2 writes the address of the angle into h-degrees.
sine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Dividend. The sine argument is the address of a floating-point number that is
this dividend. For MTH$HATAND2, sine specifies an H-floating number.
cosine
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Divisor. The cosine argument is the address of a floating-point number that is
this divisor. For MTH$HATAND2, cosine specifies an H-floating number.

Description
The angle in degrees whose tangent is YIX is computed below. The value off is
defined in the description of MTH$zCOSH.

MTH-82

Value of Input Arguments

Angle Returned

X = 0 or Y/X > 2U+l)

90 * (signY)

X > O and Y/X::; 2U+l)

zATAND(Y/X)

MTH$HATAND2

Value of Input Arguments

Angle Returned

X < o and Y/ X~ 2U+l)

180 * (signY) + zATAN D(Y / X)

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

Reserved operand. The MTH$HATAND2 routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument. Both cosine and sine are
zero. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

l\llTl-LR".:l

MTH$HATANH

MTH$HATANH-Hyperbolic Arc Tangent (H-Floating Value)
Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent CH-Floating
Value) routine returns the hyperbolic arc tangent (as an H-floating Value) of that
angle.

Format
MTH$HATANH

h-atanh ,hyperbolic-tangent

Returns
None.
"-,

Arguments
h-atanh
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Hyperbolic arc tangent of the hyperbolic tangent specified by hyperbolictangent. The h-atanh argument is the address of an H-floating number that is
this hyperbolic arc tangent. MTH$HATANH writes the address of the hyperbolic
arc tangent into h-atanh.
hyperbolic-tangent
OpenVMS usage floating_point
type
H_floating
access
read only
mechanism
by reference

Hyperbolic tangent of an angle. The hyperbolic-tangent argument is
the address of a floating-point number that is this hyperbolic tangent. For
MTH$HATANH, hyperbolic-tangent specifies an H-floating number.

Description
The hyperbolic arc tangent function is computed as follows:

MTH-84

Value of x

Value Returned

IXI < 1
IX kl

zATAN H(X) = zLOG((X + 1)/(X - 1))/2
An invalid argument is signaled

MTH$HATANH

Condition Values Signaled
SS$_ROPRAND

MTH$_INVARGMAT

Reserved operand. The MTH$xATANH routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Invalid argument: I X I ~ 1. LIB$SIGNAL
copies the floating-point reserved operand to
the mechanism argument vector CHF$L_MCH_
SAVRO/Rl. The result is the floating-point
reserved operand unless you have written a
condition handler to change CHF$L_MCH_
SAVRO/Rl.

MTH-85

MTH$HCOS

MTH$HCOS-Cosine of Angle Expressed in Radians {H-Floating
Value)
The Cosine of Angle Expressed in Radians (H-Floating Value) routine returns the
cosine of a given angle (in radians) as an H-floating value.

Format
MTH$HCOS

h-cosine ,angle-in-radians

JSB Entries

MTH$HCOS_R5

Returns
None.

Arguments
h-cosine

OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Cosine of the angle specified by angle-in-radians. The h-cosine argument is
the address of an H-floating number that is this cosine. MTH$HCOS writes the
address of the cosine into h-cosine.
angle-in-radians

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The angle in radians. The angle-in-radians argument is the address of a
floating-point number. For MTH$HCOS, angle-in-radians specifies an Hfloating number.

Description
See the MTH$xSINCOS routine for the algorithm used to compute the cosine.

Condition Value Signaled
SS$_ROPRAND

MTH-86

Reserved operand. The MTH$HCOS procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$HCOSD

MTH$HCOSD-Cosine of Angle Expressed in Degrees (H-Floating
Value)
The Cosine of Angle Expressed in Degrees CH-Floating Value) routine returns the
cosine of a given angle (in degrees) as an H-fioating value.

Format
MTH$HCOSD

h-cosine ,angle-in-degrees

JSB Entries

MTH$HCOSD_R5

Returns
None.

Arguments
h-cosine

OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Cosine of the angle specified by angle-in-degrees. The h-cosine argument is
the address of an H-floating number that is this cosine. MTH$HCOSD writes this
cosine into h-cosine.
angle-in-degrees

OpenVMS usage
type
access
mechanism

floating_point
H_fioating
read only
by reference

Angle (in degrees). The angle-in-degrees argument is the address of a floatingpoint number. For MTH$HCOSD, angle-in-degrees specifies an H-floating
number.

Description
See the MTH$SINCOSD routine for the algorithm used to compute the cosine.

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$HCOSD procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH-87

MTH$HCOSH

MTH$HCOSH-Hyperbolic Cosine (H-Floating Value)
The Hyperbolic Cosine CH-Floating Value) routine returns the hyperbolic cosine of
the input value as an H-floating value.

Format
MTH$HCOSH

h-cosh ,floating-point-input-value

Returns
None.

Arguments
h-cosh
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Hyperbolic cosine of the input value specified by floating-point-input-value.
The h-cosh argument is the address of an H-floating number that is this
hyperbolic cosine. MTH$HCOSH writes the address of the hyperbolic cosine into
h-cosh.
floating-point-input-value
OpenVMS usage floating_point
type
H_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of
this input value. For MTH$HCOSH, floating-point-input-value specifies an
H-floating number.

Description
Computation of the hyperbolic cosine depends on the magnitude of the input
argument. The range of the function is partitioned using four data-typedependent constants: a(z), b(z), and c(z). The subscript z indicates the data
type. The constants depend on the number of exponent bits (e) and the number of
fraction bits (f) associated with the data type (z).
The values of e and fare as follows:
e = 15

f = 113

MTH-88

MTH$HCOSH

The values of the constants in terms of e and fare:
Variable

Value

a(z)
b(z)
c(z)

2-f/2

(! + 1) / 2 * In (2)
2e-l * ln(2)

Based on the above definitions, zCOSH(X) is computed as follows:
Value of X

Value Returned

\X\ < a(z)

a(z)::;\X\ < .25
.25::;\X\ < b(z)
b(z)::;\X\ < c(z)
c(z)::;\X\

Computed using a power series expansion in \X\ 2

(zEXP(\X\) + 1/zEXP(\X\))/2
zEXP(\X\)/2
Overflow occurs

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$HCOSH procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of floating-point-input-value is
greater than about yyy; LIB$SIGNAL copies the
reserved operand to the signal mechanism vector.
The result is the reserved operand -0.0 unless a
condition handler changes the signal mechanism
vector. The value of yyy is 11356.523.

MTH-89

MTH$HEXP

MTH$HEXP-Exponential {H-Floating Value)
The Exponential CH-Floating Value) routine returns the exponential of the input
value as an H-floating value.

Format
MTH$HEXP

h-exp ,floating-point-input-value

JSB Entries
MTH$HEXP_R6

Returns
None.

Arguments
h-exp
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Exponential of the input value specified by floating-point-input-value. The
h-exp argument is the address of an H-floating number that is this exponential.
MTH$HEXP writes the address of the exponential into h-exp.
floating-point-input-value
OpenVMS usage floating_point
type
H_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of a
floating-point number. For MTH$HEXP, floating-point-input-value specifies an
H-floating number.

Description
The exponential of xis computed as:
Value of x

Value Returned

x > c(z)
x:::; - c(z)
lxl < 2-(f+l)

Overflow occurs
0

Otherwise

2Y * 2U * 2W

where: Y = INTEGER(x * ln2(E)) V = FRAC(x * ln2(E)) * 16
U = INTEGER(V)/16 W = FRAC(V)/16 2W =polynomial approximation of
degree 14 for z = H.
See also the section on the hyperbolic cosine for definitions off and c(z).

MTH-90

MTH$HEXP

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH$_FLOUNDMAT

Reserved operand. The MTH$xEXP routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library:
floating-point-input-value is greater than
yyy; LIB$SIGNAL copies the reserved operand
to the signal mechanism vector. The result is
the reserved operand -0.0 unless a condition
handler changes the signal mechanism vector.
The value of yyy is approximately 11355.830 for
MTH$HEXP.
Floating-point underflow in Math Library:
floating-point-input-value is less than or
equal to yyy and the caller (CALL or JSB) has
set hardware floating-point underflow enable.
The result is set to 0.0. If the caller has not
enabled floating-point underflow (the default), a
result of 0.0 is returned but no error is signaled.
The value of yyy is approximately -11356.523 for
MTH$HEXP.

MTH-91

MTH$HLOG

MTH$HLOG-Natural Logarithm (H-Floating Value)
The Natural Logarithm CH-Floating Value) routine returns the natural (base e)
logarithm of the input argument as an H-floating value.

Format
MTH$HLOG

h-natlog ,floating-point-input-value

JSB Entries
MTH$HLOG_R8

Returns
None.

Arguments
h-natlog
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Natural logarithm of floating-point-input-value. The h-natlog argument is
the address of an H-floating number that is this natural logarithm. MTH$HLOG
writes the address of this natural logarithm into h-natlog.
floating-point-input-value
OpenVMS usage floating_point
type
H_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of a
floating-point number that is this value. For MTH$HLOG, floating-point-inputvalue specifies an H-floating number.

Description
Computation of the natural logarithm routine is based on the following:
1.

ln(X * Y) = ln(X) + ln(Y)

In ( 1 + X) = x - x 2

;2 + x 3 / s - x 4 / 4 ...

for IX I < 1
3.

In(X) = In(A) + 2 * (V + v 3 /3 + v 5 /5 + v 7 /7 ... )

where V = (X - A)/(X +A), A > O,
and p(y) = 2 * (1 + y/3 + y 2 /5 ... )
For x = 2n * f, where n is an integer and f is in the interval of 0.5 to 1, define
the following quantities:
If n~1, thenN=n-1andF=2J
If n:::=;o, then N = n and F = f

MTH-92

MTH$HLOG

From (1) it follows that:

4. ln(X) = N * ln(2) + ln(F)
Based on the previous relationships, zLOG is computed as follows:
1. If \F - 1\ < 2- 5 ,
zLOG(X) = N * zLOG(2) + W + W * p(W),
where W = F-1.
2.

Otherwise,
zLOG(X) = N * zLOG(2) + zLOG(A) + V * p(V 2 ),
where V = (F - A)/(F +A) and A and zLOG(A)
are obtained by table look up.

Condition Values Signaled
SS$_ROPRAND

MTH$_LOGZERNEG

Reserved operand. The MTH$HLOG procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Logarithm of zero or negative value. Argument
floating-point-input-value is less than or equal
to 0.0. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH-93

MTH$HLOG2

MTH$HLOG2-Base 2 Logarithm (H-Floating Value)
The Base 2 Logarithm (H-Floating Value) routine returns the base 2 logarithm of
the input value specified by floating-point-input-value as an H-floating value.

Format
MTH$HLOG2

h-log2 ,floating-point-input-value

Returns
None.

Arguments
h-log2

OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Base 2 logarithm of floating-point-input-value. The h-log2 argument is the
address of an H-floating number that is this base 2 logarithm. MTH$HLOG2
writes the address of this logarithm into h-log2.
floating-point-input-value

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The input value. The floating-point-input-value argument is the address of
a floating-point number that is this input value. For MTH$HLOG2, floatingpoint-input-value specifies an H-floating number.

Description
The base 2 logarithm function is computed as follows:
zLOG2(X) = zLOG2(E) * zLOG(X)

Condition Values Signaled
SS$_ROPRAND

MTH-94

Reserved operand. The MTH$HLOG2 procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$HLOG2

MTH$_LOGZERNEG

Logarithm of zero or negative value. Argument
floating-point-input-value is less than or equal
to 0.0. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH-95

MTH$HLOG10

MTH$HLOG10-Common Logarithm {H-Floating Value)
The Common Logarithm CH-Floating Value) routine returns the common (base 10)
logarithm of the input argument as an H-floating value.

Format
MTH$HLOG10

h-log1 O ,floating-point-input-value

JSB Entries
MTH$HLOG1 O_R8

Returns
None.

Arguments
h-log10
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Common logarithm of the input value specified by floating-point-input-value.
The h-loglO argument is the address of an H-floating number that is this
common logarithm. MTH$HLOG 10 writes the address of the common logarithm
into h-loglO.
floating-point-input-value
OpenVMS usage floating_point
type
H_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of a
floating-point number. For MTH$HLOG 10, floating-point-input-value specifies
an H-floating number.

Description
The common logarithm function is computed as follows:

zLOGIO(X) = zLOGIO(E) * zLOG(X)

MTH-96

MTH$HLOG10

Condition Values Signaled
SS$_ROPRAND

MTH$_LOGZERNEG

Reserved operand. The MTH$HLOG 10
procedure encountered a floating-point reserved
operand due to incorrect user input. A floatingpoint reserved operand is a floating-point datum
with a sign bit of 1 and a biased exponent of 0.
Floating-point reserved operands are reserved for
future use by Digital.
Logarithm of zero or negative value. Argument
floating-point-input-value is less than or equal
to 0.0. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

l\llTl-LQ7

MTH$HSIN

MTH$HSIN-Sine of Angle Expressed in Radians (H-Floating Value)
The Sine of Angle Expressed in Radians (H-Floating Value) routine returns the
sine of a given angle (in radians) as an H-floating value.

Format
MTH$HSIN

h-sine ,angle-in-radians

JSB Entries

MTH$HSIN_R5

Returns
None.

Arguments
h-sine

OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

The sine of the angle specified by angle-in-radians. The h-sine argument is the
address of an H-floating number that is this sine. MTH$HSIN writes the address
of the sine into h-sine.
angle-in-radians

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Angle (in radians). The angle-in-radians argument is the address of a floatingpoint number that is this angle. For MTH$HSIN, angle-in-radians specifies an
H-floating number.

Description
See the MTH$SINCOS routine for the algorithm used to compute this sine.

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$HSIN procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$HSIND

MTH$HSIND-Sine of Angle Expressed in Degrees (H-Floating Value)
The Sine of Angle Expressed in Degrees (H-Floating Value) routine returns the
sine of a given angle (in degrees) as an H-floating value.

Format
MTH$HSIND

h-sine ,angle-in-degrees

JSB Entries

MTH$HSIND_R5

Returns
None.

Arguments
h-sine

OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Sine of the angle specified by angle-in-degrees. The h-sine argument is the
address of an H-floating number that is this sine. MTH$HSIND writes the
address of the angle into h-sine.
angle-in-degrees

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Angle (in degrees). The angle-in-degrees argument is the address of a floatingpoint number that is this angle. For MTH$HSIND, angle-in-degrees specifies
an H-floating number.

Description
See MTH$SINCOSD for the algorithm used to compute the sine.

Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$HSIND procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

l\1ffl-l_QQ

MTH$HSIND

MTH$_FLOUNDMAT

MTH-100

Floating-point underflow in Math Library. The
absolute value of the input angle is less than
180/11" * 2-m (where m = 16,384 for H-floating).

MTH$HSINH

MTH$HSINH-Hyperbolic Sine {H-Floating Value)
The Hyperbolic Sine CH-Floating Value) routine returns the hyperbolic sine of the
input value specified by floating-point-input-value as an H-floating value.

Format
MTH$HSINH

h-sinh ,floating-point-input-value

Returns
None.

Arguments
h-sinh
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Hyperbolic sine of the input value specified by floating-point-input-value. The
h-sinh argument is the address of an H-floating number that is this hyperbolic
sine. MTH$HSINH writes the address of the hyperbolic sine into h-sinh.
floating-point-in put-value

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The input value. The floating-point-input-value argument is the address of
a floating-point number that is this value. For MTH$HSINH, floating-pointinput-value specifies an H-floating number.

Description
Computation of the hyperbolic sine function depends on the magnitude of the
input argument. The range of the function is partitioned using three data type
dependent constants: a(z), b(z), and c(z). The subscript z indicates the data type.
The constants depend on the number of exponent bits (e) and the number of
fraction bits ({) associated with the data type (z).
The values of e and fare as follows:
e = 15

f = 113

l\llTU_1f'1

MTH$HSINH

The values of the constants in terms of e and fare:
Variable

Value

a(z)
b(z)
c(z)

2<-J /2)

(f + 1)/2 * ln(2)
2e-l * ln(2)

Based on the above definitions, zSINH(X) is computed as follows:
Value of X

Value Returned

IXI < a(z)
a(z):::;IXI < 1.0

x
zSINH(X) is computed using a power series expansion in

1.0:::; IXI < b(z)
b(z):::;IXI < c(z)
c(z):::;IXI

(zEXP(X) - zEXP(-X))/2
SJGN(X) * zEXP(IXl)/2
Overflow occurs

1x12

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH-10?

Reserved operand. The MTH$HSINH procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library: the
absolute value of floating-point-input-value
is greater than yyy. LIB$SIGNAL copies the
floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl. The value of
yyy is approximately 11356.523.

MTH$HSQRT

MTH$HSQRT-Square Root (H-Floating Value)
The Square Root CH-Floating Value) routine returns the square root of the input
value floating-point-input-value as an H-floating value.

Format
MTH$HSQRT

h-sqrt ,floating-point-input-value

JSB Entries
MTH$HSQRT_RB

Returns
None.

Arguments
h-sqrt
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Square root of the input value specified by floating-point-input-value. The
h-sqrt argument is the address of an H-floating number that is this square root.
MTH$HSQRT writes the address of the square root into h-sqrt.
floating-point-input-value

OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

Input value. The floating-point-input-value argument is the address of
a floating-point number that contains this input value. For MTH$HSQRT,
floating-point-input-value specifies an H-floating number.

Description
The square root of X is computed as follows:
If X < 0, an error is signaled.
Let X = 2K * F
where:
K is the exponential part of the floating-point data
Fis the fractional part of the floating-point data
If K is even:
X = 2C 2 >1<P) * F,
zSQRT(X) = 2P * zSQRT(F),
1/2~F < 1, where P = K/2

MTH-103

MTH$HSQRT

If K is odd:
X = 2(2*P+l) * F = 2(2*P+2) * (F /2),
zSQRT(X) = 2<P+l) * zSQRT(F /2),
1/4~F /2 < 1/2, where p = (K-1)/2

Let F' = A * F + B, when K is even:
A= 0.95F6198 (hex)
B = 0.6BA5918 (hex)
Let F' =A* (F /2) + B, when K is odd:
A = O.D413CCC (hex)
B = 0.4C1E248 (hex)
Let K' = P, when K is even
Let K' = P+l, when K is odd
Let Y[O] = 2K' * F' be a straight line approximation within the given interval
using coefficients A and B which minimize the absolute error at the midpoint and
endpoint.
Starting with Y[O], n Newton-Raphson iterations are performed:
Y[n + 1] = 1/2 * (Y[n] + X/Y[n])

where n = 5 for H-floating.

Condition Values Signaled
SS$_ROPRAND

MTH$_SQUROONEG

MTH-104

Reserved operand. The MTH$HSQRT procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Square root of negative number. Argument
floating-point-input-value is less than 0.0.
LIB$SIGNAL copies the floating-point reserved
operand to the mechanism argument vector
CHF$L_MCH_SAVRO/Rl. The result is the
floating-point reserved operand unless you have
written a condition handler to change CHF$L_
MCH_SAVRO/Rl.

MTH$HTAN

MTH$HTAN-Tangent of Angle Expressed in Radians (H-Floating
Value)
The Tangent of Angle Expressed in Radians CH-Floating Value) routine returns
the tangent of a given angle (in radians) as an H-floating value.

Format
MTH$HTAN

h-tan ,angle-in-radians

JSB Entries
MTH$HTAN_R5

Returns
None.

Arguments
h-tan
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Tangent of the angle specified by angle-in-radians. The h-tan argument is the
address of an H-floating number that is this tangent. MTH$HTAN writes the
address of the tangent into h-tan.
angle-in-radians
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The input angle (in radians). The angle-in-radians argument is the address of
a floating-point number that is this angle. For MTH$HTAN, angle-in-radians
specifies an H-floating number.

Description
When the input argument is expressed in radians, the tangent function is
computed as follows:
1. If IX I < 2<- f / 2 ), then zT AN (X) = X (see the section on MTH$zCOSH for the
definition off)
2.

Otherwise, call MTH$zSINCOS to obtain zSIN(X) and zCOS(X); then
a.

If zCOS(X) = 0, signal overflow

Otherwise, zTAN(X) = zSIN(X)/zCOS(X)

MTH-105

MTH$HTAN

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH-106

Reserved operand. The MTH$HTAN procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in math library.

MTH$HTAND

MTH$HTAND-Tangent of Angle Expressed in Degrees (H-Floating
Value)
The Tangent of Angle Expressed in Degrees CH-Floating Value) routine returns
the tangent of a given angle (in degrees) as an H-floating value.

Format
MTH$HTAND

h-tan ,angle-in-degrees

JSB Entries
MTH$HTAND_R5

Returns
None.

Arguments
h-tan
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Tangent of the angle specified by angle-in-degrees. The h-tan argument is the
address of an H-floating number that is this tangent. MTH$HTAND writes the
address of the tangent into h-tan.
angle-in-degrees
OpenVMS usage
type
access
mechanism

floating_point
H_floating
read only
by reference

The input angle (in degrees). The angle-in-degrees argument is the address of a
floating-point number which is this angle. For MTH$HTAND, angle-in-degrees
specifies an H-floating number.

Description
When the input argument is expressed in degrees, the tangent function is
computed as follows:
1. If IXI < (180/11") * 2C- 2 /Ce-l)) and underflow signaling is enabled, underflow is

signaled (see the section on MTH$zCOSH for the definition of e).
2.

Otherwise, if IXI < (180/11") * 2(-f/ 2), then zTAND(X) = (7r/180) * X. See the
description of MTH$zCOSH for the definition off.

3. Otherwise, call MTH$zSINCOSD to obtain zSIND(X) and zCOSD(X).
a. Then, if zCOSD(X) = 0, signal overflow
b.

Else, zTAN D(X) = zSIN D(X)/zCOSD(X)

MTH-107

MTH$HTAND

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

MTH-108

Reserved operand. The MTH$HTAND procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in math library.

MTH$HTANH

MTH$HTANH-Compute the Hyperbolic Tangent (H-Floating Value)
The Compute the Hyperbolic Tangent CH-Floating Value) routine returns the
hyperbolic tangent of the input value as an H-floating value.

Format
MTH$HTANH

h-tanh ,floating-point-input-value

Returns
None.

Arguments
h-tanh
OpenVMS usage
type
access
mechanism

floating_point
H_floating
write only
by reference

Hyperbolic tangent of the value specified by floating-point-input-value. The
h-tanh argument is the address of a H-floating number that is this hyperbolic
tangent. MTH$HTANH writes the address of the hyperbolic tangent into h-tanh.
floating-point-input-value
OpenVMS usage floating_point
type
H_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address
of a floating-point number that contains this input value. For MTH$HTANH,
floating-point-input-value specifies an H-floating number.

Description
For MTH$HTANH, the hyperbolic tangent of X is computed using a value of 56
for g and a value of 40 for h. The hyperbolic tangent of Xis computed as follows:
Value of x

Hyperbolic Tangent Returned

\X\::;2-g
2-g < \X\::;0.25
0.25 < \X\ < h
h:S; \X\

x
zSIN H(X)/zCOSH(X)
(zEXP(2 * X) - 1)/(zEXP(2 * X) + 1)
sign(X) * 1

11.ATLJ

-inn

MTH$HTANH

Condition Value Signaled
SS$_ROPRAND

MTH-110

Reserved operand. The MTH$HTANH procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xlMAG

MTH$xlMAG-lmaginary Part of a Complex Number
The Imaginary Part of a Complex Number routine returns the imaginary part of
a complex number.

Format
MTH$AIMAG

complex-number

MTH$DIMAG

complex-number

MTH$GIMAG

complex-number

Each of the above three formats corresponds to one of the three floating-point
complex types.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Imaginary part of the input complex-number. MTH$AIMAG returns an Ffloating number. MTH$DIMAG returns a D-floating number. MTH$GIMAG
returns a G-floating number.

ARGUMENT
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex, D_floating complex, G_floating complex
read only
by reference

The input complex number. The complex-number argument is the address
of this floating-point complex number. For MTH$AIMAG, complex-number
specifies an F-floating number. For MTH$DIMAG, complex-number specifies a
D-floating number. For MTH$GIMAG, complex-number specifies a G-floating
number.

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xIMAG routine
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

l\ATl-l-111

MTH$xlMAG

Example
C+
C
C
C
C

C
C

This FORTRAN example forms the imaginary part of
a G-f loating complex number using MTH$GIMAG
and the FORTRAN random number generator
RAN.
Declare Z as a complex value and MTH$GIMAG as
a REAL*8 value. MTH$GIMAG will return the imaginary
part of Z:
Z_NEW = MTH$GIMAG(Z).

C-

COMPLEX*l6 Z
COMPLEX*l6 DCMPLX
REAL*8 R,I,MTH$GIMAG
INTEGER M
M = 1234567

c+
C
C
C-

Generate a random complex number with the
FORTRAN generic CMPLX.
R = RAN(M)
I = RAN(M)
Z = DCMPLX(R,I)

c+
C
C
C-

Z is a complex number (r,i) with real part "r" and
imaginary part "i".
TYPE *, ' The complex number z is' ,z
TYPE *, ' It has imaginary part' ,MTH$GIMAG(Z)
END

This FORTRAN example demonstrates a procedure call to MTH$GIMAG.
Because this example uses G-floating numbers, it must be compiled with the
statement "FORTRAN/G filename".
The output generated by this program is as follows:
The complex number z is (0.8535407185554504,0.2043401598930359)
It has imaginary part 0.2043401598930359

MTl-l-119

MTH$xLOG

MTH$xLOG-Natural Logarithm
The Natural Logarithm routine returns the natural (base e) logarithm of the
input argument.

Format
MTH$ALOG

floating-point-input-value

MTH$DLOG

floating-point-input-value

MTH$GLOG

floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ALOG_R5
MTH$DLOG_R8
MTH$GLOG_R8

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D _floating, G_floating
write only
by value

The natural logarithm of floating-point-input-value. MTH$ALOG returns
an F-floating number. MTH$DLOG returns a D-floating number. MTH$GLOG
returns a G-floating number.

Arguments
floating-point-input-value
OpenVMS usage floating_point
type
F _floating, D_floating, G_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of a
floating-point number that is this value. For MTH$ALOG, floating-point-inputvalue specifies an F-floating number. For MTH$DLOG, floating-point-inputvalue specifies a D-floating number. For MTH$GLOG, floating-point-inputvalue specifies a G-floating number.

Description
Computation of the natural logarithm routine is based on the following:
1.

ln(X * Y) = ln(X) + ln(Y)

2. In(l + X) = x - X 2 /2 + x 3 /3 - x 4 /4 ...
for IX I < 1

MTH-113

MTH$xLOG

3. In(X) = In(A) + 2 * (V + v 3 /3 + v 5 /5 + v 7 /7 ... )
= ln(A) + V * p(V 2 ), where V = (X - A)/(X +A),
A> 0, and p(y) = 2 * (1 + y/3 + y2/5 ... )
For x = 2" * f, where n is an integer and f is in the interval of 0.5 to 1, define
the following quantities:
If n~1, then N = n - 1 and F = 2f
If n::;O, then N = n and F = f

From ( 1) above it follows that:

4. ln(X) = N * ln(2) + ln(F)
Based on the above relationships, zLOG is computed as follows:
1. If IF - 1 I < 2- 5 , zLOG(X) = N * zLOG(2) + W + W * p(W),
where W = F-1.

2. Otherwise, zLOG(X) = N * zLOG(2) + zLOG(A) + V * p(V 2 ),
where V = (F - A)/(F +A) and A and zLOG(A)
are obtained by table look up.
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HLOG.

Condition Values Signaled
SS$_ROPRAND

MTH$_LOGZERNEG

MTH-114

Reserved operand. The MTH$xLOG procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Logarithm of zero or negative value. Argument
floating-point-input-value is less than or equal
to 0.0. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH$xLOG2

MTH$xLOG2-Base 2 Logarithm
The Base 2 Logarithm routine returns the base 2 logarithm of the input value
specified by floating-point-input-value.

Format
MTH$ALOG2 floating-point-input-value
MTH$DLOG2

floating-point-input-value

MTH$GLOG2

floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The base 2 logarithm of floating-point-input-value. MTH$ALOG2 returns an
F-floating number. MTH$DLOG2 returns a D-floating number. MTH$GLOG2
returns a G-floating number.·

Arguments
floating-point-input-value
OpenVMS usage floating_point
type
F_floating, D_floating, G_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of
a floating-point number that is this input value. For MTH$ALOG2, floatingpoint-input-value specifies an F-floating number. For MTH$DLOG2, floatingpoint-input-value specifies a D-floating number. For MTH$GLOG2, floatingpoint-input-value specifies a G-floating number.

Description
The base 2 logarithm function is computed as follows:
zLOG2(X) = zLOG2(E) * zLOG(X)

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HLOG2.

MTH-115

MTH$xLOG2

Condition Values Signaled
SS$_ROPRAND

MTH$_LOGZERNEG

MTH-116

Reserved operand. The MTH$xLOG2 procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Logarithm of zero or negative value. Argument
floating-point-input-value is less than or equal
to 0.0. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH$xLOG10

MTH$xLOG10-Common Logarithm
The Common Logarithm routine returns the common (base 10) logarithm of the
input argument.

Format
MTH$ALOG10

floating-point-input-value

MTH$DLOG10

floating-point-input-value

MTH$GLOG1 O floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$ALOG1 O_R5
MTH$DLOG1 O_R8
MTH$GLOG 1O_R8

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The common logarithm of floating-point-input-value. MTH$ALOG 10
returns an F-floating number. MTH$DLOG10 returns a D-floating number.
MTH$GLOG 10 returns a G-floating number.

Arguments
floating-point-input-value
OpenVMS usage floating_point
type
F _floating, D_floating, G_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address of a
floating-point number. For MTH$ALOG 10, floating-point-input-value specifies
an F-floating number. For MTH$DLOG 10, floating-point-input-value specifies
a D-floating number. For MTH$GLOG 10, floating-point-input-value specifies a
G-floating number.

Description
The common logarithm function is computed as follows:

zLOGlO(X) = zLOGlO(E) * zLOG(X)
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HLOG 10.

l\ATLJ

ii7

MTH$xLOG10

Condition Values Signaled
SS$_ROPRAND

MTH$_LOGZERNEG

MTH-118

Reserved operand. The MTH$xLOG 10 procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Logarithm of zero or negative value. Argument
floating-point-input-value is less than or equal
to 0.0. LIB$SIGNAL copies the floating-point
reserved operand to the mechanism argument
vector CHF$L_MCH_SAVRO/Rl. The result
is the floating-point reserved operand unless
you have written a condition handler to change
CHF$L_MCH_SAVRO/Rl.

MTH$RANDOM

MTH$RANDOM-Random Number Generator, Uniformly Distributed
The Random Number Generator, Uniformly Distributed routine is a general
random number generator.

Format
MTH$RANDOM

seed

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating
write only
by value

MTH$RANDOM returns an F-floating random number.

ARGUMENT
seed

OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
modify
by reference

The integer seed, a 32-bit number whose high-order 24 bits are converted by
MTH$RANDOM to an F-floating random number. The seed argument is the
address of an unsigned longword that contains this integer seed. The seed is
modified by each call to MTH$RANDOM.

Description
This routine must be called again to obtain the next pseudorandom number. The
seed is updated automatically.
The result is a floating-point number that is uniformly distributed between 0.0
inclusively and 1.0 exclusively.
There are no restrictions on the seed, although it should be initialized to
different values on separate runs in order to obtain different random sequences.
MTH$RANDOM uses the following method to update the seed passed as the
argument:
SEED= (69069 *SEED+ l)(modulo2 32 )

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$RANDOM
procedure encountered a floating-point reserved
operand due to incorrect user input. A floatingpoint reserved operand is a floating-point datum
with a sign bit of 1 and a biased exponent of 0.
Floating-point reserved operands are reserved for
future use by Digital.

I. ATI I

-4 ... n.

MTH$RANDOM

Example
RAND:
PROCEDURE OPTIONS (MAIN);
DECLARE FOR$SECNDS ENTRY (FLOAT BINARY (24))
RETURNS (FLOAT BINARY (24));
DECLARE MTH$RANDOM ENTRY (FIXED BINARY (31))
RETURNS (FLOAT BINARY (24));
DECLARE TIME FLOAT BINARY (24);
DECLARE SEED FIXED BINARY (31);
DECLARE I FIXED BINARY (7);
DECLARE RESULT FIXED DECIMAL (2);
/* Get floating random time value
*/
TIME= FOR$SECNDS (OEO);
/* Convert to fixed
*/
SEED = TIME;
/* Generate 100 random numbers between 1 and 10 */
DO I = 1 TO 100;
RESULT= 1 +FIXED ( (lOEO * MTH$RANDOM (SEED) ),31 );
PUT LIST (RESULT);
END;
END RAND;

This PL/I program demonstrates the use of MTH$RANDOM. The value returned
by FOR$SECNDS is used as the seed for the random-number generator to ensure
a different sequence each time the program is run. The random value returned is
scaled so as to represent values between 1 and 10.
Because this program generates random numbers, the output generated will be
different each time the program is executed. One example of the outut generated
by this program is as follows:
7
4

4
4

6
2

6
8

2
5
2
8

3
4
2

1
3

5
4
6
6
9

3
5

8
3
8

8
6

5
3
2
5
6
2

5
8
2
5
6
3

2
2

4
8
4

8
7
6
8

1
1

6
5
5

3
8
3
9
9

5
4
5
5

8
2

6
4
8

MTH$xREAL

MTH$xREAL-Real Part of a Complex Number
The Real Part of a Complex Number routine returns the real part of a complex
number.

Format
MTH$REAL complex-number
MTH$DREAL complex-number
MTH$GREAL complex-number

Each of the above three formats accepts one of the three floating-point complex
types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Real part of the complex number. MTH$REAL returns an F-floating number.
MTH$DREAL returns a D-floating number. MTH$GREAL returns a G-floating
number.

ARGUMENT
complex-number

OpenVMS usage
type
access
mechanism

complex_number
F _floating complex, D_floating complex, G_floating complex
read only
by reference

The complex number whose real part is returned by MTH$REAL. The
complex-number argument is the address of this floating-point complex
number. For MTH$REAL, complex-number is an F-floating complex number.
For MTH$DREAL, complex-number is a D-floating complex number. For
MTH$GREAL, complex-number is a G-floating complex number.

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xREAL procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH-121

MTH$xREAL

Example
Ct

c
c

This FORTRAN example forms the real
part of an F-f loating complex number using
MTH$REAL and the FORTRAN random number
generator RAN.
Declare Z as a complex value and MTH$REAL as a
REAL*4 value. MTH$REAL will return the real
part of Z:
Z_NEW = MTH$REAL(Z).

CCOMPLEX Z
COMPLEX CMPLX
REAL*4 MTH$REAL
INTEGER M
M = 1234567
Ct

C
C
C-

Generate a random complex number with the FORTRAN
generic CMPLX.
Z = CMPLX(RAN(M),RAN(M))

C
C
C-

Z is a complex number (r,i) with real part "r" and imaginary
part "i".
TYPE *, ' The complex number z is' ,z
TYPE *, ·' It has real part' , MTH$REAL ( z)
END

This FORTRAN example demonstrates the use of MTH$REAL. The output of this
program is as follows:
The complex number z is (0.8535407,0.2043402)
It has real part 0.8535407

MTH-122

MTH$xSIN

MTH$xSIN-Sine of Angle Expressed in Radians
The Sine of Angle Expressed in Radians routine returns the sine of a given angle
(in radians).

Format
MTH$SIN

angle-in-radians

MTH$DSIN

angle-in-radians

MTH$GSIN

angle-in-radians

Each of the above formats accepts one of the floating-point types as input.
JSB Entries

MTH$SIN_R4
MTH$DSIN_R7
MTH$GSIN_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Sine of the angle specified by angle-in-radians. MTH$SIN returns an Ffl.oating number. MTH$DSIN returns a D-fl.oating number. MTH$GSIN returns a
G-fl.oating number.

Arguments
angle-in-radians

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Angle (in radians). The angle-in-radians argument is the address of a fl.oatingpoint number that is this angle. For MTH$SIN, angle-in-radians specifies an
F-fl.oating number. For MTH$DSIN, angle-in-radians specifies a D-fl.oating
number. For MTH$GSIN, angle-in-radians specifies a G-fl.oating number.

Description
See the MTH$SINCOS routine for the algorithm used to compute this sine.
The routine description for the H-fl.oating point version of this routine is listed
alphabetically under MTH$HSIN.

MTH-123

MTH$xSIN

Condition Value Signaled
SS$_ROPRAND

MTH-124

Reserved operand. The MTH$xSIN procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xSINCOS

MTH$xSINCOS-Sine and Cosine of Angle Expressed in Radians
The Sine and Cosine of Angle Expressed in Radians routine returns the sine and
cosine of a given angle (in radians).

Format
MTH$SINCOS

angle-in-radians ,sine ,cosine

MTH$DSINCOS

angle-in-radians ,sine ,cosine

MTH$GSINCOS

angle-in-radians ,sine ,cosine

MTH$HSINCOS

angle-in-radians ,sine ,cosine

Each of the above four formats accepts one or'the four floating-point types as
input.
JSB Entries

MTH$SINCOS_R5
MTH$DSINCOS_R7
MTH$GSINCOS_R7
MTH$HSINCOS_R7

Each of the above four JSB entries accepts one of the four floating-point types as
input.

Returns
MTH$SINCOS, MTH$DSINCOS, MTH$GSINCOS, and MTH$HSINCOS return
the sine and cosine of the input angle by reference in the sine and cosine
arguments.

Arguments
angle-in-radians

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating, H_floating
read only
by reference

Angle (in radians) whose sine and cosine are to be returned. The angle-inradians argument is the address of a floating-point number that is this
angle. For MTH$SINCOS, angle-in-radians is an F-floating number. For
MTH$DSINCOS, angle-in-radians is a D-floating number. For MTH$GSINCOS,
angle-in-radians is a G-floating number. For MTH$HSINCOS, angle-inradians is an H-floating number.
sine

OpenVMS usage
type
access
mechanism

floating_poin t
F _floating, D_floating, G_floating, H_floating
write only
by reference

MTH-125

MTH$xSINCOS

Sine of the angle specified by angle-in-radians. The sine argument is the
address of a floating-point number. MTH$SINCOS writes an F-floating
number into sine. MTH$DSINCOS writes a D-floating number into sine.
MTH$GSINCOS writes a G-floating number into sine. MTH$HSINCOS writes
an H-floating number into sine.
cosine
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating, H_floating
write only
by reference

Cosine of the angle specified by angle-in-radians. The cosine argument is
the address of a floating-point number. MTH$SINCOS writes an F-floating
number into cosine. MTH$DSINCOS writes a D-floating number into cosine.
MTH$GSINCOS writes a G-floating number into cosine. MTH$HSINCOS writes
an H-floating number into cosine.

Description
All routines with JSB entry points accept a single argument in RO:Rm, where m,
which is defined below, is dependent on the data type.
Data Type

F _floating
D_floating
G_floating
H_floating

0
1
1

In general, Run-Time Library routines with JSB entry points return one value
in RO:Rm. The MTH$SINCOS routine returns two values, however. The sine of
angle-in-radians is returned in RO:Rm and the cosine of angle-in-radians is
returned in (R<m+l>:R<2*m+l>).
In radians, the computation of zSIN(X) and zCOS(X) is based on the following
polynomial expansions:
sin(X) = X - X 3 /(3!) + X 5 /(5!) - x7 /(7!) ...
= X + X * P(X 2), where
P(y) = y/(3!) + y 2 /(5!) + y 3 /(7!) ...
cos(X) = 1 - X 2 /(2!) + x 4 /(4!) - X 6 /(6!) ...
= Q(X 2 ), where
Q(y) = ( 1 - y / (2!) + y 2 / ( 4!) + y3 / ( 6!)... )

MTH-126

If IXI < 2<-J /2),
then zSIN(X) = X and zCOS(X) = 1
(see the section on MTH$zCOSH for
the definition off)

lf2-1/ 2 ~1x1<7r/4,
then zSIN(X) = X + P(X2)
and zCOS(X) = Q(X2)

MTH$xSINCOS

3. If 7r/4~IXJ and X > O,
a.

Let J = INT(X/(1r/4))
and I = J modulo 8

b. If J is even, let Y = X - J * (7r/4)
otherwise, let Y = (J + 1) * (7r/4) - X
With the above definitions, the following table relates zSIN(X) and
zCOS(X) to zSIN(Y) and zCOS(Y):
Value of I

zSIN(X)

zCOS(X)

0
1

zSIN(Y)
zCOS(Y)
zCOS(Y)
zSIN(Y)
-zSIN(Y)
-zCOS(Y)
-zCOS(Y)
-zSIN(Y)

zCOS(Y)
zSIN(Y)
-zSIN(Y)
-zCOS(Y)
-zCOS(Y)
-zSIN(Y)
zSIN(Y)
zCOS(Y)

3
4
5
6
7
c.

zSIN(Y) and zCOS(Y) are computed as foliows:
zSIN(Y) = Y + P(Y2),
and zCOS(Y) = Q(Y2)

4. If 7r/4~JXJ and X < O,
then zSIN(X) = -zSJN(jXJ)
and zCOS(X) = zOOS(JXJ)

Condition Value Returned
SS$_ROPRAND

Reserved operand. The MTH$xSINCOS
procedure encountered a floating-point reserved
operand due to incorrect user input. A floatingpoint reserved operand is a floating-point datum
with a sign bit of 1 and a biased exponent of 0.
Floating-point reserved operands are reserved for
future use by Digital.

MTH-127

MTH$xSINCOSD

MTH$xSINCOSD-Sine and Cosine of Angle Expressed in Degrees
The Sine and Cosine of Angle Expressed in Degrees routine returns the sine and
cosine of a given angle (in degrees).

Format
MTH$SINCOSD

angle-in-degrees ,sine ,cosine

MTH$DSINCOSD

angle-in-degrees ,sine ,cosine

MTH$GSINCOSD

angle-in-degrees ,sine ,cosine

MTH$HSINCOSD

angle-in-degrees ,sine ,cosine

Each of the above four formats accepts one of the four floating-point types as
input.
JSB Entries

MTH$SINCOSD_R5
MTH$DSINCOSD_R7
MTH$GSINCOSD_R7
MTH$HSINCOSD_R7

Each of the above four JSB entries accepts one of the four floating-point types as
input.

Returns
MTH$SINCOSD, MTH$DSINCOSD, MTH$GSINCOSD, and MTH$HSINCOSD
return the sine and cosine of the input angle by reference in the sine and cosine
arguments.

Arguments
angle-in-degrees

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating, H_floating
read only
by reference

Angle (in degrees) whose sine and cosine are returned by MTH$xSINCOSD.
The angle-in-degrees argument is the address of a floating-point number
that is this angle. For MTH$SINCOSD, angle-in-degrees is an F-floating
number. For MTH$DSINCOSD, angle-in-degrees is a D-floating number.
For MTH$GSINCOSD, angle-in-degrees is a G-floating number. For
MTH$HSINCOSD, angle-in-degrees is an H-floating number.
sine

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating, H_floating
write only
by reference

Sine of the angle specified by angle-in-degrees. The sine argument is the
address of a floating-point number. MTH$SINCOSD writes an F-floating
MTH-128

MTH$xSINCOSD

number into sine. MTH$DSINCOSD writes a D-floating number into sine.
MTH$GSINCOSD writes a G-floating number into sine. MTH$HSINCOSD
writes an H-floating number into sine.
cosine
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating, H_floating
write only
by reference

Cosine of the angle specified by angle-in-degrees. The cosine argument is
the address of a floating-point number. MTH$SINCOSD writes an F-floating
number into cosine. MTH$DSINCOSD writes a D-floating number into cosine.
MTH$GSINCOSD writes a G-floating number into cosine. MTH$HSINCOSD
writes an H-floating number into cosine.

Description
All routines with JSB entry points accept a single argument in RO:Rm, where m,
which is defined below, is dependent on the data type.
Data Type

F _floating
D_floating
G_floating
H_floating

0
1
1
3

In general, Run-Time Library routines with JSB entry points return one value in
RO:Rm. The MTH$SINCOSD routine returns two values, however. The sine of
angle-in-degrees is returned in RO:Rm and the cosine of angle-in-degrees is
returned in (R<m+l>:R<2*m+l>).

In degrees, the computation of zSIND(X) and zCOSD(X) is based on the following
polynomial expansions:
SIN D(X) = (C * X) - (C * X) 3 /(3!)+

(c * XJ 5 I (5!) - (c 2* X) 7I (7!) ...

= X/2 + X * P(X ), where
P(y) = -y/(3J) + y2 /(5!) - y3 /(7l) ...
COSD(X) = 1 - (C * X) 2 /~2l)+
(C * X) 4 /(4!) - (C * X) /(6!) ...
= Q(X 2 ), where
Q(y) = 1 - y/(2!) + y2 /(4!) - y3 /(6!) ...
and C = 7r /180
1. If IXI < (180/7r) * r 2e-l and underflow signaling is enabled,
underflow is signaled for zSIND(X) and zSINCOSD(X).
See MTH$zCOSH for the definition of e.
otherwise:

2. If IXI < (180/7r) * 2(-f / 2 ),
then zSIN D(X) = (7r/l80) * X and zCOSD(X) = 1.
(See MTH$zCOSH for the definition off.)

MTH-129

MTH$xSINCOSD

3. If (180/11") * 2<-J / 2 ) :::; I X I < 45
then zSIN D(X) = X/2 6 + P(X2)
and zCOSD(X) = Q(X2)
4. If 45::::; IXI and X > O,
a.

Let J = JNT(X/(45))and
I= J modulo 8

b. If J is even, let Y = X - J * 45;
otherwise, let Y = (J + 1) * 45 - X.
With the above definitions, the following table relates
zSIND(X) and zCOSD(X) to zSIND(Y) and zCOSD(Y):
Value of I

zSIND(X)

zCOSD(X)

0
1

zSIND(Y)
zCOSD(Y)
zCOSD(Y)
zSIND(Y)
-zSIND(Y)
-zCOSD(Y)
-zCOSD(Y)
-zSIND(Y)

zCOSD(Y)
zSIND(Y)
-zSIND(Y)
-zCOSD(Y)
-zCOSD(Y)
-zSIND(Y)
zSIND(Y)
zCOSD(Y)

3
4

5
6
7
c.

zSIND(Y) and zCOSD(Y) are computed as follows:
zSJN D(Y) = Y/2 6 + P(Y2)
zCOSD(Y) = Q(Y2)

d. If 45::; IXI and X < O,
then zSIN D(X) = -zSIN D(IXI)
and zCOSD(X) = zCOSD(IXI)

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOUNDMAT

MTH-130

Reserved operand. The MTH$xSINCOSD
procedure encountered a floating-point reserved
operand due to incorrect user input. A floatingpoint reserved operand is a floating-point datum
with a sign bit of 1 and a biased exponent of 0.
Floating-point reserved operands are reserved for
future use by Digital.
Floating-point underflow in math library. The
absolute value of the input angle is less than
180/11" * 2-m (where m = 128 for F-floating and
D-floating, 1,024 for G-floating, and 16,384 for
H-floating).

MTH$xSIND

MTH$xSIND-Sine of Angle Expressed in Degrees
The Sine of Angle Expressed in Degrees routine returns the sine of a given angle
(in degrees).

Format
MTH$SIND

angle-in-degrees

MTH$DSIND

angle-in-degrees

MTH$GSIND

angle-in-degrees

Each of the above formats accepts one of the floating-point types as input.
JSB Entries

MTH$SIND_R4
MTH$DSIND_R7
MTH$GSIND_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The sine of the angle. MTH$SIND returns an F-floating number. MTH$DSIND
returns a D-floating number. MTH$GSIND returns a G-floating number.

Arguments
angle-in-degrees

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

Angle (in degrees). The angle-in-degrees argument is the address of a floatingpoint number that is this angle. For MTH$SIND, angle-in-degrees specifies an
F-floating number. For MTH$DSIND, angle-in-degrees specifies a D-floating
number. For MTH$GSIND, angle-in-degrees specifies a G-floating number.

Description
See MTH$SINCOSD for the algorithm that is used to compute the sine.
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HSIND.

MTH-131

MTH$xSIND

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOUNDMAT

MTH-132

Reserved operand. The MTH$SIND procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a.floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point underflow in math library. The
absolute value of the input angle is less than
180/?r * 2-m (where m = 128 for F-floating and
D-floating, and 1,024 for G-floating).

MTH$xSINH

MTH$xSINH-Hyperbolic Sine
The Hyperbolic Sine routine returns the hyperbolic sine of the input value
specified by floating-point-input-value.

Format
MTH$SINH

floating-point-input-value

MTH$DSINH

floating-point-input-value

MTH$GSINH

floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The hyperbolic sine of floating-point-input-value. MTH$SINH returns an
F-floating number. MTH$DSINH returns a D-floating number. MTH$GSINH
returns a G-floating number.

Arguments
floating-point-in put-value

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The input value. The floating-point-input-value argument is the address of a
floating-point number that is this value. For MTH$SINH, floating-point-inputvalue specifies an F-floating number. For MTH$DSINH, floating-point-inputvalue specifies a D-floating number. For MTH$GSINH, floating-point-inputvalue specifies a G-floating number.

Description
Computation of the hyperbolic sine function depends on the magnitude of the
input argument. The range of the function is partitioned using four data type
dependent constants: a(z), b(z), and c(z). The subscript z indicates the data type.
The constants depend on the number of exponent bits (e) and the number of
fraction bits ({) associated with the data type (z).

MTH$xSINH

The values of e and fare:
z

F
D
G

8
8

24
56

The values of the constants in terms of e and fare:
Variable

Value

a(z)
b(z)
c(z)

2(-/ /2)

CEILING[(!+ 1)/2 * ln(2)]
(2(e-l) * ln(2))

Based on the above definitions, zSINH(X) is computed as follows:
Value of X

Value Returned

IX I < a(z)
a(z) ~ I X I < 1.0

1.0 ~ I X I < b(z)

b(z) ::; I X I < c(z)
c(z) ~ IX I

zSINH(X) is computed using a
power series expansion in IXl 2
(zEXP(X) - zEXP(-X))/2
SIGN(X) * zEXP(IXl)/2
Overflow occurs

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HSINH.

Condition Values Signaled
SS$_ROPRAND

MTH-1~.d.

Reserved operand. The MTH$xSINH procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$xSINH

MTH$_FLOOVEMAT

Floating-point overflow in Math Library: the
absolute value of floating-point-input-value
is greater than yyy. LIB$SIGNAL copies the
floating-point reserved operand to the mechanism
argument vector CHF$L_MCH_SAVRO/Rl. The
result is the floating-point reserved operand
unless you have written a condition handler to
change CHF$L_MCH_SAVRO/Rl.
The values of yyy are approximately:
MTH$SINH-88. 722
MTH$DSINH-88.722
MTH$GSINH-709. 782

MTl-l-1~!=\

MTH$xSQRT

MTH$xSQRT-Square Root
The Square Root routine returns the square root of the input value floatingpoint-input-value.

Format
MTH$SQRT floating-point-input-value
MTH$DSQRT floating-point-input-value
MTH$GSQRT floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$SQRT_R3
MTH$DSQRT_R5
MTH$GSQRT_R5

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The square root of floating-point-input-value. MTH$SQRT returns an Ffloating number. MTH$DSQRT returns a D-floating number. MTH$GSQRT
returns a G-floating num?er.

Arguments
floating-point-in put-value
OpenVMS usage floating_point
type
F _floating, D_floating, G_floating
access
read only
mechanism
by reference

Input value. The floating-point-input-value argument is the address of
a floating-point number that contains this input value. For MTH$SQRT,
floating-point-input-value specifies an F-floating number. For MTH$DSQRT,
floating-point-input-value specifies a D-floating number. For MTH$GSQRT,
floating-point-input-value specifies a G-floating number.

Description
The square root of Xis computed as follows:
If X < 0, an error is signaled.
Let X = 2K * F
where:

MTH-136

MTH$xSQRT

K is the exponential part of the floating-point data
F is the fractional part of the floating-point data
If K is even:

x = 2< 2 >1<P) * F,

zSQRT(X) = 2P * zSQRT(F),
1/2~F < 1, where P = K/2
If K is odd:
X = 2<2*P+l) * F = 2(2>1<P+2) * (F /2),
zSQRT(X) = 2<P+l) * zSQRT(F /2),
1/4~F /2 < 1/2, where p = (K-1)/2
Let F' = A * F + B, when K is even:
A= 0.95F6198 (hex)
B = 0.6BA5918 (hex)
Let F' = A * (F /2) + B, when K is odd:
A= O.D413CCC (hex)
B = 0.4C1E248 (hex)
Let K' = P, when K is even
Let K' = P+l, when K is odd
Let Y[O] = 2K' * F 1 be a straight line approximation within the given interval
using coefficients A and B which minimize the absolute error at the midpoint and
endpoint.
Starting with Y[O], n Newton-Raphson iterations are performed:

Y[n + 1] = 1/2 * (Y[n] + X/Y[n])
where n = 2, 3, or 3 for z = F-floating, D-floating, or G-floating, respectively.
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HSQRT.

Condition Values Signaled
SS$_ROPRAND

MTH$_SQUROONEG

Reserved operand. The MTH$xSQRT procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Square root of negative number. Argument
floating-point-input-value is less than 0.0.
LIB$SIGNAL copies the floating-point reserved
operand to the mechanism argument vector
CHF$L_MCH_SAVRO/Rl. The result is the
floating-point reserved operand unless you have
written a condition handler to change CHF$L_
MCH_SAVRO/Rl.

l\llT1-1-1r:t7

MTH$xTAN

MTH$xTAN-Tangent of Angle Expressed in Radians
The Tangent of Angle Expressed in Radians routine returns the tangent of a
given angle (in radians).

Format
MTH$TAN

angle-in-radians

MTH$DTAN

angle-in-radians

MTH$GTAN

angle-in-radians

Each of the above formats accepts one of the floating-point types as input.
JSB Entries
MTH$TAN_R4
MTH$DTAN_R7
MTH$GTAN_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The tangent of the angle specified by angle-in-radians. MTH$TAN returns
an F-floating number. MTH$DTAN returns a D-floating number. MTH$GTAN
returns a G-floating number.

Arguments
angle-in-radians

OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The input angle (in radians). The angle-in-radians argument is the address of
a floating-point number that is this angle. For MTH$TAN, angle-in-radians
specifies an F-floating number. For MTH$DTAN, angle-in-radians specifies a
D-floating number. For MTH$GTAN, angle-in-radians specifies a G-floating
number.

Description
When the input argument is expressed in radians, the tangent function is
computed as follows:
1. If IXI < 2(-f/ 2), then zTAN(X) = X (see the section on MTH$zCOSH for the

definition off)

MTH-138

MTH$xTAN

2. Otherwise, call MTH$zSINCOS to obtain zSIN(X) and zCOS(X); then
a. If zCOS(X) = 0, signal overflow
b. Otherwise, zTAN(X) = zSJN(X)/zCOS(X)
The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HTAN.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT

Reserved operand. The MTH$xTAN procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library.

l\JIT~-L1~Q

MTH$xTAND

MTH$xTAND-Tangent of Angle Expressed in Degrees
The Tangent of Angle Expressed in Degrees routine returns the tangent of a given
angle (in degrees).

Format
MTH$TAND

angle-in-degrees

MTH$DTAND

angle-in-degrees

MTH$GTAND

angle-in-degrees

Each of the above formats accepts one of the floating-point types as input.
JSB Entries

MTH$TAND_R4
MTH$DTAND_R7
MTH$GTAND_R7

Each of the above JSB entries accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

Tangent of the angle specified by angle-in-degrees. MTH$TAND returns an
F-floating number. MTH$DTAND returns a D-floating number. MTH$GTAND
returns a G-floating number.

Arguments
angle-in-degrees
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
read only
by reference

The input angle (in degrees). The angle-in-degrees argument is the address of
a floating-point number which is this angle. For MTH$TAND, angle-in-degrees
specifies an F-floating number. For MTH$DTAND, angle-in-degrees specifies a
D-floating number. For MTH$GTAND, angle-in-degrees specifies a G-fioating
number.

Description
When the input argument is expressed in degrees, the tangent function is
computed as follows:
1. If IXI < (180/71") * 2C- 2/Ce-l)) and underflow signaling is enabled, underflow is
signaled (see the section on MTH$zCOSH for the definition of e).
2.

MTH-140

Otherwise, if IXI < (180/71") * 2(-f/ 2 ), then zTAND(X) = (71"/180) * X. See the
description of MTH$zCOSH for the definition off.

MTH$xTAND

Otherwise, call MTH$zSINCOSD to obtain zSIND(X) and zCOSD(X).
a. Then, if zCOSD(X) = O, signal overflow
b.

Else, zTAND(X) = zSIND(X)/zCOSD(X)

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HTAND.

Condition Values Signaled
SS$_ROPRAND

MTH$_FLOOVEMAT
MTH$_FLOUNDMAT

Reserved operand. The MTH$xTAND procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a ·
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.
Floating-point overflow in Math Library.
Floating-point underflow in Math Library.

P.ATLJ

-4 A-4

MTH$xTANH

MTH$xTANH-Compute the Hyperbolic Tangent
The Compute the Hyperbolic Tangent routine returns the hyperbolic tangent of
the input value.

Format
MTH$TANH

floating-point-input-value

MTH$DTANH

floating-point-input-value

MTH$GTANH

floating-point-input-value

Each of the above formats accepts one of the floating-point types as input.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, G_floating
write only
by value

The hyperbolic tangent of floating-point-input-value. MTH$TANH returns an
F-floating number. MTH$DTANH returns a D-floating number. MTH$GTANH
returns a G-floating number. Unlike the other three routines, MTH$HTANH
returns the hyperbolic tangent by reference in the h-tanh argument.

Arguments
floating-point-input-value
OpenVMS usage floating_point
type
F _floating, D_floating, G_floating
access
read only
mechanism
by reference

The input value. The floating-point-input-value argument is the address
of a floating-point number that contains this input value. For MTH$TANH,
floating-point-input-value specifies an F-floating number. For MTH$DTANH,
floating-point-input-value specifies a D-floating number. For MTH$GTANH,
floating-point-input-value specifies a G-floating number.

Description
In calculating the hyperbolic tangent of x, the values of g and h are:

l\ATl-l-1.!l?

D
G

10
21

MTH$xTANH

For MTH$TANH, MTH$DTANH, and MTH$GTANH the hyperbolic tangent of x
is then computed as follows:
Value of x

Hyperbolic Tangent Returned

Jxj~2-g

2-g <
0.5~

IXI < 0.5

IXI < 1.0

t.o < 1x1 < h
h~IXI

xTAN H(X) = X + x 3 * R(X2 ), where R(X2 ) is a rational
function of x 2 •
xTANH(X) = xTANH(xHI) + xTANH(xLO) * C/B
where C = 1 - xT AN H(xH I) * xT AN H(xH I),
B = 1 + xT AN H(xH I) * xT AN H(xLO),
xHI = 1/2 + N/16 + 1/32 for N=0,1, ... ,7,
and xLO = X- xHI.
xT AN H(X) = (xEXP(2 * X) - 1)/(xEXP(2 * X) + 1)
xT AN H(X) = sign(X) * 1

The routine description for the H-floating point version of this routine is listed
alphabetically under MTH$HTANH.

Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xTANH procedure
encountered a floating-point reserved operand
due to incorrect user input. A floating-point
reserved operand is a floating-point datum with a
sign bit of 1 and a biased exponent of 0. Floatingpoint reserved operands are reserved for future
use by Digital.

MTH$UMAX

MTH$UMAX-Compute Unsigned Maximum
The Compute Unsigned Maximum routine computes the unsigned longword
maximum of n unsigned longword arguments, where n is greater than or equal to
1.

Format
MTH$UMAX

argument [argument, ... ]

Returns
OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
write only
by value

Maximum value returned by MTH$UMAX.

Arguments
argument

OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
read only
by reference

Argument whose maximum MTH$UMAX computes. Each argument argument
is an unsigned longword that contains one of these values.
argument

OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
read only
by reference

Additional arguments whose maximum MTH$UMAX computes. Each argument
argument is an unsigned longword that contains one of these values.

Description
MTH$UMAX is the unsigned version of MTH$JMAXO.

Condition Values Returned
None.

l\ATU_1AA

MTH$UMIN

MTH$UMIN-Compute Unsigned Minimum
The Compute Unsigned Minimum routine computes the unsigned longword
minimum of n unsigned longword arguments, where n is greater than or equal to
1.

Format
MTH$UMIN

argument [argument, ... ]

Returns
OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
write only
by value

Minimum value returned by MTH$UMIN.

Arguments
argument

OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
read only
by reference

Argument whose minimum MTH$UMIN computes. Each argument argument is
an unsigned longword that contains one of these values.
argument

OpenVMS usage
type
access
mechanism

longword_unsigned
longword (unsigned)
read only
by reference

Additional arguments whose minimum MTH$UMIN computes. Each argument
argument is an unsigned longword that contains one of these values.

Description
MTH$UMIN is the unsigned version of MTH$JMINO.

Condition Values Returned
None.

l\AT1-1-1LLi:;:

Vector MTH$ Reference Section
The Vector MTH$ Reference Section provides detailed descriptions of two sets
of vector routines provided by the OpenVMS RTL Mathematics (MTH$) Facility,
BLAS Level 1 and FOLR. The BLAS Level 1 are the Basic Linear Algebraic
Subroutines designed by Lawson, Hanson, Kincaid, and Krogh (1978). The FOLR
(First Order Linear Recurrence) routines provide a vectorized algorithm for the
linear recurrence relation.

BLAS1 $VlxAMAX

BLAS1 $VlxAMAX-Obtain the Index of the First Element of a Vector
Having the Largest Absolute Value
The Obtain the Index of the First Element of a Vector Having the Largest
Absolute Value routines find the index of the first occurrence of a vector element
having the maximum absolute value.

Format
BLAS1 $VISAMAX

n ,x ,incx

BLAS1 $VIDAMAX

n ,x ,incx

BLAS1 $VIGAMAX

n ,x ,incx

BLAS1$VICAMAX

n ,x ,incx

BLAS1 $VIZAMAX

n ,x ,incx

BLAS1 $VIWAMAX

n ,x ,incx

Use BLAS1$VISAMAX for single-precision real operations. Use
BLAS1$VIDAMAX for double-precision real CD-floating) operations and
BLAS1$VIGAMAX for double-precision real (G-floating) operations.
Use BLAS1$VICAMAX for single-precision complex operations. Use
BLAS1$VIZAMAX for double-precision complex CD-floating) operations and
BLAS1$VIWAMAX for double-precision complex CG-floating) operations.

Returns
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
write only
by value

For the real versions of this routine, the function value is the index of the first
occurrence of a vector element having the maximum absolute value, as follows:

lxil =max {lxjl for j = 1, 2, ... , n}
For the complex versions of this routine, the function value is the index of the
first occurrence of a vector element having the largest sum of the absolute values
of the real and imaginary parts of the vector elements, as follows:

jRe(xi) I+ jlm(xi) I =max { jRe(xj) I+ jlm(xj) I for J. = 1, 2, ... , n}

Arguments
n

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x. Then argument is the address of a signed
longword integer containing the number of elements. If you specify a negative
value or 0 for n, 0 is returned.

l\AT~-1.£1.Q

BLAS1 $VlxAMAX

OpenVMS usage
type
access
mechanism

floating_point or complex_number
F_floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

Array containing the elements to be accessed. All elements of array x are
accessed only if the increment argument of x, called incx, is 1. The x argument
is the address of a floating-point or floating-point complex number that is this
array. This argument is an array of length at least

1+ (n-1) * lincxl
where:
n

incx =

number of vector elements specified in n
increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VISAMAX
BLAS1$VIDAMAX
BLAS1$VIGAMAX
BLAS1$VICAMAX
BLAS1$VIZAMAX
BLAS1$VIWAMAX

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If n is less than or equal to 0, then imax is 0.
incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array x. The incx argument is the address of a
signed longword integer containing the increment argument. If incx is greater
than or equal to 0, then xis referenced forward in array x; that is, Xi is referenced
as:

x(l + (i - 1) * incx)
where:

= array specified in x
= element of the vector x
incx = increment argument for the array x specified in incx

If you specify a negative value for incx, it is interpreted as the absolute value of
incx.

MTl-l-1F\O

BLAS1 $VlxAMAX

Description
BLAS1$VISAMAX, BLAS1$VIDAMAX, and BLAS1$VIGAMAX find the index, i,
of the first occurrence of a vector element having the maximum absolute value.
BLAS1$VICAMAX, BLAS1$VIZAMAX, and BLAS1$VIWAMAX find the index, i,
of the first occurrence of a vector element having the largest sum of the absolute
values of the real and imaginary parts of the vector elements.
Vector x contains n elements that are accessed from array x by stepping incx
elements at a time. The vector xis a real or complex single-precision or doubleprecision (D and G) n-element vector. The vector can be a row or a column of a
matrix. Both forward and backward indexing are permitted.
BLAS1$VISAMAX, BLAS1$VIDAMAX, and BLAS1$VIGAMAX determine the
smallest integer i of the n-element vector x such that:

lxil = max{lxjl for J. = 1,2, ... ,n}
BLAS1$VICAMAX, BLAS1$VIZAMAX, and BLAS1$VIWAMAX determine the
smallest integer i of the n-element vector x such that:

IRe(xi) I + IIm(xi) I = max { IRe(xj) I + IIm(xj) I for i = 1, 2, ... , n}
You can use the BLAS1$VIxAMAX routines to obtain the pivots in Gaussian
elimination.
The public-domain BLAS Level 1 IxAMAX routines require a positive value for
incx. The Run-Time Library BLAS Level 1 routines interpret a negative value
for incx as the absolute value of incx.
The algorithm does not provide a special case for incx = 0. Therefore, specifying
0 for incx has the effect of setting imax equal to 1 using vector operations.

Example

c
C To obtain the index of the element with the maximum
C absolute value.

c
INTEGER IMAX,N,INCX
REAL X( 40)
INCX = 2
N = 20
IMAX = BLAS1$VISAMAX(N,X,INCX)

l\JITl-L1 ~1

BLAS1 $VxASUM

BLAS1 $VxASUM-Obtain the Sum of the Absolute Values of the
Elements of a Vector
The Obtain the Sum of the Absolute Values of the Elements of a Vector routines
determine the sum of the absolute values of the elements of the n-element vector
x.

Format
BLAS1 $VSASUM

n ,x ,incx

BLAS1 $VDASUM

n ,x ,incx

BLAS1 $VGASUM

n ,x ,incx

BLAS1 $VSCASUM

n ,x ,incx

BLAS1 $VDZASUM

n ,x ,incx

BLAS1 $VGWASUM

n ,x ,incx

Use BLAS1$VSASUM for single-precision real operations. Use BLAS1$VDASUM
for double-precision real CD-floating) operations and BLAS1$VGASUM for doubleprecision real CG-floating) operations.
Use BLAS1$VSCASUM for single-precision complex operations. Use
BLAS1$VDZASUM for double-precision complex CD-floating) operations and
BLAS1$VGWASUM for double-precision complex CG-floating) operations.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, or G_floating real
write only
by value

The function value, called sum, is the sum of the absolute values of the elements
of the vector x. The data type of the function value is a real number; for the
BLAS1$VSCASUM, BLAS1$VDZASUM, and BLAS1$VGWASUM routines, the
data type of the function value is the real data type corresponding to the complex
argument data type.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x to be added. Then argument is the address of a
signed longword integer containing the number of elements.
x

OpenVMS usage
type
access
mechanism
MTl-l-1F\?

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

BLAS1$VxASUM

lincxl

where:
n

incx =

number of vector elements specified in n
increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSASUM
BLAS1$VDASUM
BLAS1$VGASUM
BLAS1$VSCASUM
BLAS1$VDZASUM
BLAS1$VGWASUM

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If n is less than or equal to 0, then sum is 0.0.
incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

=
=
incx =

array specified in x
element of the vector x
increment argument for the array x specified in incx

If you specify a negative value for incx, it is interpreted as the absolute value of
incx.

Description
BLAS1$VSASUM, BLAS1$VDASUM, and BLAS1$VGASUM obtain the sum of
the absolute values of the elements of the n-element vector x. BLAS1$VSCASUM,
BLAS1$VDZASUM, and BLAS1$VGWASUM obtain the sum of the absolute
values of the real and imaginary parts of the elements of the n-element vector x.
Vector x contains n elements that are accessed from array x by stepping incx
elements at a time. The vector xis a real or complex single-precision or doubleprecision (D and G) n-element vector. The vector can be a row or a column of a
matrix. Both forward and backward indexing are permitted.

BLAS1 $VxASUM

BLAS1$VSASUM, BLAS1$VDASUM, and BLAS1$VGASUM compute the sum of
the absolute values of the elements of x, which is expressed as follows:

2:?=1 lxil = lx1I + lx2I + · · · + lxnl
BLAS1$VSCASUM, BLAS1$VDZASUM, and BLAS1$VGWASUM compute the
sum of the absolute values of the real and imaginary parts of the elements of x,
which is expressed as follows:

2:f=1(lail + lbil) = (la1I + lb1I) + (la2I + lb2I) +···+(Ian I+ lbnl)
where lxil = (ai, bi)
and lail + lbil = lreall + limaginaryl
The public-domain BLAS Level 1 xASUM routines require a positive value for
incx. The Run-Time Library BLAS Level 1 routines interpret a negative value
for incx as the absolute value of incx.
The algorithm does not provide a special case for incx = 0. Therefore, specifying
0 for incx has the effect of computing n * Ix1 I using vector operations.
Rounding in the summation occurs in a different order than in a sequential
evaluation of the sum, so the final result may differ from the result of a sequential
evaluation.

Example

c
c To obtain the sum of the absolute values of the
c elements of vector x:
c
INTEGER N,INCX
REAL X(20),SUM
INCX = 1
N = 20
SUM = BLAS1$VSASUM(N,X,INCX)

l\ATU_"fi:::A

BLAS1 $VxAXPY

BLAS1 $VxAXPY-Multiply a Vector by a Scalar and Add a Vector
The Multiply a Vector by a Scalar and Add a Vector routines compute ax+ y,
where a is a scalar number and x and y are n-element vectors.

Format
BLAS1 $VSAXPY

n ,a ,x ,incx ,y ,incy

BLAS1$VDAXPY

n ,a ,x ,incx ,y ,incy

BLAS1 $VGAXPY

n ,a ,x ,incx ,y ,incy

BLAS1 $VCAXPY

n ,a ,x ,incx ,y ,incy

BLAS1$VZAXPY

n ,a ,x ,incx ,y ,incy

BLAS1 $VWAXPY

n ,a ,x ,incx ,y ,incy

Use BLAS1$VSAXPY for single-precision real operations. Use BLAS1$VDAXPY
for double-precision real CD-floating) operations and BLAS1$VGAXPY for doubleprecision real CG-floating) operations.
Use BLAS1$VCAXPY for single-precision complex operations. Use
BLAS1$VZAXPY for double-precision complex CD-floating) operations and
BLAS1$VWAXPY for double-precision complex CG-floating) operations.

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vectors x and y. Then argument is the address of a
signed longword integer containing the number of elements. If n is less than or
equal to 0, then y is unchanged.

a
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

Scalar multiplier for the array x. The a argument is the address of a floatingpoint or floating-point complex number that is this multiplier. If a equals 0, then
y is unchanged. If a shares a memory location with any element of the vector y,
results are unpredictable. Specify the same data type for arguments a, x, and y.

BLAS1 $VxAXPY

x
OpenVMS usage
type

access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

1 + (n - 1) * JincxJ
where:
number of vector elements specified in n

incx

= increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSAXPY
BLAS1$VDAXPY
BLAS1$VGAXPY
BLAS1$VCAXPY
BLAS1$VZAXPY
BLAS1$VWAXPY

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If any element of x shares a memory location with an element of y, the results

are unpredictable.
incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

x(l + (i - 1) * incx)
where:
x

=
=

incx =

array specified in x
element of the vector x
increment argument for the array x specified in incx

If incx is less than 0, then x is referenced backward in array x; that is, xi is

referenced in:

x(l + (n - i) * JincxJ)

l\ATLI

r::.c

BLAS1 $VxAXPY

where:
x

array specified in x
number of vector elements specified in n
element of the vector x
increment argument for the array x specified in incx

=
=
incx =
n

y
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference, array reference

On entry, array containing the elements to be accessed. All elements of array
y are accessed only if the increment argument of y, called incy, is 1. They
argument is the address of a floating-point or floating-point complex number that
is this array. The length of this array is at least
1 + (n - 1) * lincyl

where:

n
=
incy =

number of vector elements specified in n
increment argument for the array y specified in incy

Specify the data type as follows:
Routine

Data Type for y

BLAS1$VSAXPY
BLAS1$VDAXPY
BLAS1$VGAXPY
BLAS1$VCAXPY
BLAS1$VZAXPY
BLAS1$VWAXPY

F-floa ting real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If n is less than or equal to 0, then y is unchanged. If any element of x shares a
memory location with an element of y, the results are unpredictable.

On exit, y contains an array of length at least
1 + (n - 1) * lincyl

where:
n
incy

=
=

number of vector elements specified in n
increment argument for the array y specified in incy

After the call to BLAS1$VxAXPY, Yi is set equal to
Yi+ a* Xi·

MTH-157

BLAS1$VxAXPY

where:
y
a

= the vector y
= element of the vector x or y
= scalar multiplier for the vector x specified in a
= the vector x

incy

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array y. The incy argument is the address of a
signed longword integer containing the increment argument. If incy is greater
than or equal to 0, then y is referenced forward in array y; that is, Yi is referenced
in:

y(l + (i - 1) * incy)
where:
y
=

incy

array specified in y
element of the vector y
increment argument for the array y specified in incy

If incy is less than 0, then y is referenced backward in array y; that is, Yi is
referenced in:

y(l + (n - i) * lincyl)
where:
y

=
=
incy =
n

array specified in y
number of vector elements specified in n
element of the vector y
increment argument for the array y specified in incy

Description
BLAS1$VxAXPY multiplies a vector x by a scalar, adds to a vector y, and stores
the result in the vector y. This is expressed as follows:
y~ax

where a is a scalar number and x and y are real or complex single-precision or
double-precision (D and G) n-element vectors. The vectors can be rows or columns
of a matrix. Both forward and backward indexing are permitted. Vectors x and y
contain n elements that are accessed from arrays x and y by stepping incx and
incy elements at a time.
The routine name determines the data type you should specify for arguments a,
x, and y. Specify the same data type for each of these arguments.
The algorithm does not provide a special case for incx = 0. Therefore, specifying
0 for incx has the effect of adding the constant a * x 1 to all elements of the vector
y using vector operations.

MTH-158

BLAS1$VxAXPY

Example

c
C To compute y=y+2.0*x using SAXPY:

INTEGER N,INCX,INCY
REAL X(20), Y(20),A
INCX = 1
INCY = 1
A= 2.0
N = 20
CALL BLAS1$VSAXPY(N,A,X,INCX,Y,INCY)

MTH-159

BLAS1 $VxCOPY

BLAS1 $VxCOPY-Copy a Vector
The Copy a Vector routines copy n elements of the vector x to the vector y.

Format
BLAS1 $VSCOPY

n ,x ,incx ,y ,incy

BLAS1 $VDCOPY

n ,x ,incx ,y ,incy

BLAS1 $VCCOPY

n ,x ,incx ,y ,incy

BLAS1 $VZCOPY

n ,x ,incx ,y ,incy

Use BLAS1$VSCOPY for single-precision real operations and BLAS1$VDCOPY
for double-precision real (D or G) operations.
Use BLAS1$VCCOPY for single-precision complex operations and
BLAS1$VZCOPY for double-precision complex (Dor G) operations.

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x to be copied. Then argument is the address of
a signed longword integer containing the number of elements in vector x. If n is
less than or equal to 0, then y is unchanged.
x
OpenVMS usage
type

access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

where:

n
= number of vector elements specified in n
incx = increment argument for the array x specified in incx

MTH-160

BLAS1$VxCOPV

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSCOPY
BLAS1$VDCOPY
BLAS1$VCCOPY
BLAS1$VZCOPY

F-floating real
D-floa ting or G-floating real
F-floating complex
D-floating or G-floating complex

incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

x(l + (i - 1) * incx)
where:
x
=
i
=
incx =

array specified in x
element of the vector x
increment argument for the array x specified in incx

If incx is less than 0, then x is referenced backward in array x; that is, xi is
referenced in:

x(l + (n - i) * lincxl)
where:
x

=
=

incx =

array specified in x
number of vector elements specified in n
element of the vector x
increment argument for the array x specified in incx

y
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
write only
by reference, array reference

Array that receives the copied elements. All elements of array y receive the
copied elements only if the increment argument of y, called incy, is 1. They
argument is the address of a floating-point or floating-point complex number that
is this array. This argument is an array of length at least
1 + (n - 1) * lincyl

MTH-161

BLAS1$VxCOPY

where:

n
incy

number of vector elements specified in n
increment argument for the array y specified in incy

Specify the data type as follows:
Routine

Data Type for y

BLAS1$VSCOPY
BLAS1$VDCOPY
BLAS1$VCCOPY
BLAS1$VZCOPY

F-floating real
D-floating or G-floating real
F-floating complex
D-floating or G-floating complex

If n is less than or equal to 0, then y is unchanged. If incx is equal to 0, then
each Yi is set to x1. If incy is equal to 0, then Yi is set to the last referenced
element of x. If any element of x shares a memory location with an element of y,
the results are unpredictable. (See the Description section for a special case that
does not cause unpredictable results when the same memory location is shared by
input and output.)

incy
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

where:
y

=
=

array specified in y
element of the vector y

If incy is less than 0, then y is referenced backward in array y; that is, Yi is
referenced in:
y(l + (n - i) * lincyl)

where:
y
n

=
=

=
incy =

MTH-162

array specified in y
number of vector elements specified in n
element of the vector y
increment argument for the array y specified in incy

BLAS1 $VxCOPY

Description
BLAS1$VSCOPY, BLAS1$VDCOPY, BLAS1$VCCOPY, and BLAS1$VZCOPY copy
n elements of the vector x to the vector y. Vector x contains n elements that are
accessed from array x by stepping incx elements at a time. Both x and y are real

or complex single-precision or double-precision (D and G) n-element vectors. The
vectors can be rows or columns of a matrix. Both forward and backward indexing
are permitted.
If you specify 0 for incx, BLAS1$VxCOPY initializes all elements of y to a
constant.
If you specify -incx for incy, the vector x is stored in reverse order in y. In this
case, the call format is as follows:

CALL BLAS1$VxCOPY (N,X,INCX,Y,-INCX)
It is possible to move the contents of a vector up or down within itself and not
cause unpredictable results even though the same memory location is shared
between input and output. To do this when i is greater thanj, call the routine
BLAS1$VxCOPY with incx = incy > 0 as follows:

CALL BLAS1$VxCOPY (N,X(I),INCX,X(J),INCX)

The preceding call to BLAS1$VxCOPY moves:

x(i), x(i + 1 * incx), ... x(i + (n - 1) * incx)
to

x(j), x(i + 1 * incx), ... x(i + (n - 1) * incx)
If i is less than j, specify a negative value for incx and incy in the call to
BLAS1$VxCOPY, as follows. The parts that do not overlap are unchanged.

CALL BLAS1$VxCOPY (N,X(I),-INCX,X(J),-INCX)
Note ~~~~~~~~~~~~~

BLAS1$VxCOPY does not perform floating operations on the input
data. Therefore, floating reserved operands are not detected by
BLAS1$VxCOPY.

MTH-163

BLAS1$VxCOPY

Example
c

c To copy a vector x to a vector y using BLAS1$VSCOPY:
c

INTEGER N,INCX,INCY
REAL x ( 20 ) I y ( 20 )
INCX = 1
INCY = 1
N = 20
CALL BLAS1$VSCOPY(N,X,INCX,Y,INCY)

.c. To move the contents of X( 1) ,X( 3) ,X( 5), •.• ,X( 2N-1)
C to X(3),X(5), .•• ,X(2N+l) and leave x unchanged:

CALL BLAS1$VSCOPY(N,X,-2,X(3),-2))

c
c To move the contents of X(2),X(3), •.• ,X(l00) to
C X(l),X(2), ••• ,X(99)and.leave x(lOO) unchanged:

CALL BLAS1$VSCOPY(99,X(2),1,X,1))

c
C To move the contents of X(l),X(2),X(3), ••• ,X(N) to
C Y(N),Y(N-1), .•. ,Y

CALL BLAS1$VSCOPY(N,X,1,Y,-l))

MTH-164

BLAS1 $VxDOTx

BLAS1 $VxDOTx-Obtain the Inner Product of Two Vectors
The Obtain the Inner Product of Two Vectors routines return the dot product of
two n-element vectors, x and y.

Format
BLAS1$VSDOT

n ,x ,incx ,y ,incy

BLAS1$VDDOT

n ,x ,incx ,y ,incy

BLAS1 $VG DOT

n ,x ,incx ,y ,incy

BLAS1 $VCDOTU

n ,x ,incx ,y ,incy

BLAS1 $VCDOTC

n ,x ,incx ,y ,incy

BLAS1 $VZDOTU

n ,x ,incx ,y ,incy

BLAS1 $VWDOTU

n ,x ,incx ,y ,incy

BLAS1 $VZDOTC

n ,x ,incx ,y ,incy

BLAS1 $VWDOTC

n ,x ,incx ,y ,incy

Use BLAS1$VSDOT to obtain the inner product of two single-precision real
vectors.
Use BLAS1$VDDOT to obtain the inner product of two double-precision (Dfloating) real vectors. Use BLAS1$VGDOT to obtain the inner product of two
double-precision CG-floating) real vectors.
Use BLAS1$VCDOTU to obtain the inner product of two single-precision complex
vectors (unconjugated).
Use BLAS1$VCDOTC to obtain the inner product of two single-precision complex
vectors (conjugated).
Use BLAS1$VZDOTU to obtain the inner product of two double-precision (Dfloating) complex vectors (unconjugated). Use BLAS1$VWDOTU to obtain the
inner product of two double-precision CG-floating) complex vectors (unconjugated).
Use BLAS1$VZDOTC to obtain the inner product of two double-precision (Dfloating) complex vectors (conjugated). Use BLAS1$VWDOTC to obtain the inner
product of two double-precision CG-floating) complex vectors (conjugated).

Returns
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
write only
by value

The function value, called dotpr, is the dot product of two n-element vectors, x
and y. Specify the same data type for dotpr and the argument x.

MTH-165

BLAS1 $VxDOTx

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x. Then argument is the address of a signed
longword integer containing the number of elements. If you specify a value for n
that is less than or equal to 0, then the value of dotpr is 0.0.
x
OpenVMS usage
type

access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

where:
n

incx =

number of vector elements specified in n
increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSDOT
BLAS1$VDDOT
BLAS1$VGDOT
BLAS1$VCDOTU and
BLAS1$VCDOTC
BLAS1$VZDOTU and
BLAS1$VZDOTC
BLAS1$VWDOTU and
BLAS1$VWDOTC

F-floating real
D-floating real
G-floating real
F-floating complex

incx
OpenVMS usage
type
access
mechanism

D-floating complex
G-floating complex

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array x. The incx argument is the address of a
signed longword integer containing the increment argument. If incx is greater
than 0, then xis referenced forward in array x; that is, Xi is referenced in:

x(l + (i - 1) * incx)

MTH-166

BLAS1 $VxDOTx

where:

=
=
incx =

array specified in x
element of the vector x
increment argument for the array x specified in incx

If incx is less than 0, then x is referenced backward in array x; that is, Xi is

referenced in:

x(l + (n - i) * lincxl)
where:
x

=
incx =

array specified in x
number of vector elements specified in n
element of the vector x
increment argument for the array x specified in incx

y
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

Array containing the elements to be accessed. All elements of array y are
accessed only if the increment argument of y, called incy, is 1. The y argument
is the address of a floating-point or floating-point complex number that is this
array. This argument is an array of length at least
1 + (n - 1) * lincyl

where:
n

incy =

number of vector elements specified in n
increment argument for the array y specified in incy

Specify the data type as follows:
Routine

Data Type for y

BLAS1$VSDOT
BLAS1$VDDOT
BLAS1$VGDOT
BLAS1$VCDOTU and
BLAS1$VCDOTC
BLAS1$VZDOTU and
BLAS1$VZDOTC
BLAS1$VWDOTU and
BLAS1$VWDOTC

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

MTH-167

BLAS1$VxDOTx

incy

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

y(l + (i - 1) * incy)
where:
y

=
=

incy

array specified in y
element of the vector y
increment argument for the array y specified in incy

If incy is less than 0, then y is referenced backward in array y; that is, Yi is
referenced in:

y(l + (n - i) * lincyl)
where:
y

incy

array specified in y
number of vector elements specified in n
element of the vector y
increment argument for the array y specified in incy

Description
The unconjugated versions of this routine, BLAS1$VSDOT, BLAS1$VDDOT,
BLAS1$VGDOT, BLAS1$VCDOTU, BLAS1$VZDOTU, and BLAS1$VWDOTU
return the dot product of two n-element vectors, x and y, expressed as follows:
X · Y = XlYl + X2Y2 + · · · + XnYn

The conjugated versions of this routine, BLAS1$VCDOTC, BLAS1$VZDOTC, and
BLAS1$VWDOTC return the dot product of the conjugate of the first n-element
vector with a second n-element vector, as follows:

x · Y = X°1Y1 + X'2Y2 + · · · + XnYn
Vectors x and y contain n elements that are accessed from arrays x and y by
stepping incx and incy elements at a time. The vectors x and y can be rows or
columns of a matrix. Both forward and backward indexing are permitted.
The routine name determines the data type you should specify for arguments x
and y. Specify the same data type for these arguments.
Rounding in BLAS1$VxDOTx occurs in a different order than in a sequential
evaluation of the dot product. The final result may differ from the result of a
sequential evaluation.

MTH-168

BLAS1 $VxDOTx

Example

C To compute the dot product of two vectors, x and y,

c and return the result in DOTPR:
c

INTEGER INCX,INCY
REAL X(20),Y(20),DOTPR
INCX = 1
INCY = 1
N = 20
DOTPR = BLAS1$VSDOT(N,X,INCX,Y,INCY)

BLAS1$VxNRM2

BLAS1 $VxNRM2-0btain the Euclidean Norm of a Vector
The Obtain the Euclidean Norm of a Vector routines obtain the Euclidean norm
of an n-element vector x, expressed as follows:

Vxi + x§ + ... + x~
Format
BLAS1$VSNRM2

n ,x ,incx

BLAS1 $VDNRM2

n ,x ,incx

BLAS1 $VGNRM2

n ,x ,incx

BLAS1 $VSCNRM2

n ,x ,incx

BLAS1 $VDZNRM2

n ,x ,incx

BLAS1 $VGWNRM2

n ,x ,incx

Use BLAS1$VSNRM2 for single-precision real operations. Use BLAS1$VDNRM2
for double-precision real CD-floating) operations and BLAS1$VGNRM2 for doubleprecision real CG-floating) operations.
Use BLAS1$VSCNRM2 for single-precision complex operations. Use
BLAS1$VDZNRM2 for double-precision complex CD-floating) operations and
BLAS1$VGWNRM2 for double-precision complex CG-floating) operations.

Returns
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, or G_floating real
write only
by value

The function value, called e_norm, is the Euclidean norm of the vector x. The
data type of the function value is a real number; for the BLAS1$VSCNRM2,
BLAS1$VDZNRM2, and BLAS1$VGWNRM2 routines, the data type of the
function value is the real data type corresponding to the complex argument data
type.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x to be processed. Then argument is the address
of a signed longword integer containing the number of elements.
x

OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference, array reference

BLAS1$VxNRM2

where:

n
=
incx =

number of vector elements specified in n
increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSNRM2
BLAS1$VDNRM2
BLAS1$VGNRM2
BLAS1$VSCNRM2
BLAS1$VDZNRM2
BLAS1$VGWNRM2

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If n is less than or equal to 0, then e_norm is 0.0.
incx

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

x(l + (i - 1) * incx)
where:
x

=
incx

array specified in x
element of the vector x
increment argument for the array x specified in incx

If you specify a negative value for incx, it is interpreted as the absolute value of
incx.

Description
BLAS1$VxNRM2 obtains the Euclidean norm of an n-element vector x, expressed
as follows:

v. IXl2 + X22 + .,. + Xn2
Vector x contains n elements that are accessed from array x by stepping incx
elements at a time. The vector xis a real or complex single-precision or doubleprecision (D and G) n-element vector. The vector can be a row or a column of a
matrix. Both forward and backward indexing are permitted.

BLAS1$VxNRM2

The public-domain BLAS Level 1 xNRM2 routines require a positive value for
incx. The Run-Time Library BLAS Level 1 routines interpret a negative value
for incx as the absolute value of incx.
The algorithm does not provide a special case for incx = 0. Therefore, specifying
0 for incx has the effect of using vector operations to set e_norm as follows:
e_norm =

n°· 5 * lx1

For BLAS1$VDNRM2, BLAS1$VGNRM2, BLAS1$VDZNRM2, and
BLAS1$VGWNRM2 (the double-precision routines), the elements of the vector
x are scaled to avoid intermediate overflow or underflow. BLAS1$VSNRM2 and
BLAS1$VSCNRM2 (the single-precision routines) use a backup data type to avoid
intermediate overflow or underflow.
Rounding in BLAS1$VxNRM2 occurs in a different order than in a sequential
evaluation of the Euclidean norm. The final result may differ from the result of a
sequential evaluation.

Example

c
c To obtain the Euclidean norm of the vector x:
c
INTEGER INCX, N
REAL X(20),E NORM
INCX = 1
N = 20
E_NORM = BLAS1$VSNRM2(N,X,INCX)

BLAS1$VxROT

BLAS1 $VxROT-Apply a Givens Plane Rotation
The Apply a Givens Plane Rotation routines apply a Givens plane rotation to a
pair of n-element vectors x and y.

Format
BLAS1$VSROT

n ,x ,incx ,y ,incy ,c ,s

BLAS1 $VD ROT

n ,x ,incx ,y ,incy ,c ,s

BLAS1$VGROT

n ,x ,incx ,y ,incy ,c ,s

BLAS1 $VCSROT

n ,x ,incx ,y ,incy ,c ,s

BLAS1 $VZDROT

n ,x ,incx ,y ,incy ,c ,s

BLAS1 $VWGROT

n ,x ,incx ,y ,incy ,c ,s

Use BLAS1$VSROT for single-precision real operations. Use BLAS1$VDROT
for double-precision real CD-floating) operations and BLAS1$VGROT for doubleprecision real CG-floating) operations.
Use BLAS1$VCSROT for single-precision complex operations. Use
BLAS1$VZDROT for double-precision complex CD-floating) operations and
BLAS1$VWGROT for double-precision complex CG-floating) operations.
BLAS1$VCSROT, BLAS1$VZDROT, and BLAS1$VWGROT are real rotations
applied to a complex vector.

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vectors x and y to be rotated. Then argument is the
address of a signed longword integer containing the number of elements to be
rotated. If n is less than or equal to 0, then x and y are unchanged.
x
OpenVMS usage
type

access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference, array reference

BLAS1$VxROT

where:
n

incx

number of vector elements specified in n
increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSROT
BLAS1$VDROT
BLAS1$VGROT
BLAS1$VCSROT
BLAS1$VZDROT
BLAS1$VWGROT

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If n is less than or equal to 0, then x and y are unchanged. If c equals 1.0 and
s equals 0, then x and y are unchanged. If any element of x shares a memory
location with an element of y, then the results are unpredictable.

On exit, x contains the rotated vector x, as follows:

where:
x

=
=

array x specified in x
array y specified in y
i = 1,2, ... ,n
rotation element generated by the BLAS1$VxROTG routines
rotation element generated by the BLAS1$VxROTG routines

incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

x(l + (i - 1) * incx)
where:
x

incx

array specified in x
element of the vector x
increment argument for the array x specified in incx

If incx is less than 0, then x is referenced backward in array x; that is, xi is
referenced in:

x(l + (n - i) * lincxl)

P.ATU

-f"7A

BLAS1$VxROT

where:

x
n

=
=
=
incx =

array specified in x
number of vector elements specified in n
element of the vector x
increment argument for the array x specified in incx

y
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference, array reference

Array containing the elements to be accessed. All elements of array y are
accessed only if the increment argument of y, called incy, is 1. The y argument
is the address of a floating-point or floating-point complex number that is this
array. On entry, this argument is an array of length at least
1 + (n - 1) *

lincxl

where:
n

incx =

number of vector elements specified in n
increment argument for the array x specified in incx

Specify the data type as follows:
Routine

Data Type for y

BLAS1$VSROT
BLAS1$VDROT
BLAS1$VGROT
BLAS1$VCSROT
BLAS1$VZDROT
BLAS1$VWGROT

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

On exit, y contains the rotated vector y, as follows:
Yi+- - s

* Xi + c * Yi

where:
x
y

c
s

=
=
=
=
=

array x specified in x
array y specified in y
i = 1,2, ... ,n
real rotation element (can be generated by the BLAS1$VxROTG routines)
complex rotation element (can be generated by the BLAS1$VxROTG
routines)

MTH-175

BLAS1$VxROT

incy
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

where:
y

incy

array specified in y
element of the vector y
increment argument for the array y specified in incy

If incy is less than 0, then y is referenced backward in array y; that is, Yi is
referenced in:
y(l + (n - i) * lincyl)

where:
y

=
incy

array specified in y
number of vector elements specified in n
element of the vector y
increment argument for the array y specified in incy

c
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, or G_floating real
read only
by reference

First rotation element, which can be interpreted as the cosine of the angle of
rotation. The c argument is the address of a floating-point or floating-point
complex number that is this vector element. The c argument is the first rotation
element generated by the BLAS1$VxROTG routines.
Specify the data type (which is always real) as follows:

MTH-176

Routine

Data Type for c

BLAS1$VSROT and
BLAS1$VCSROT
BLAS1$VDROT and
BLAS1$VZDROT
BLAS1$VGROT and
BLAS1$VWGROT

F-floating real
D-floating real
G-floating real

BLAS1 $VxROT

s
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference

Second rotation element, which can be interpreted as the sine of the angle of
rotation. The s argument is the address of a floating-point or floating-point
complex number that is this vector element. The s argument is the second
rotation element generated by the BLAS1$VxROTG routines.
Specify the same data type for arguments s and c.

Description
BLAS1$VSROT, BLAS1$VDROT, and BLAS1$VGROT apply a real Givens
plane rotation to a pair of real vectors. BLAS1$VCSROT, BLAS1$VZDROT, and
BLAS1$VWGROT apply a real Givens plane rotation to a pair of complex vectors.
The vectors x and y are real or complex single-precision or double-precision (D
and G) vectors. The vectors can be rows or columns of a matrix. Both forward
and backward indexing are permitted. The routine name determines the data
type you should specify for arguments x and y. Specify the same data type for
each of these arguments.
The Givens plane rotation is applied ton elements, where the elements to be
rotated are contained in vectors x and y (i equals 1,2, ... ,n). These elements are
accessed from arrays x and y by stepping incx and incy elements at a time. The
cosine and sine of the angle of rotation are c and s, respectively. The arguments
c ands are usually generated by the BLAS Level 1 routine BLAS1$VxROTG,
using a = x and b = y:

The BLAS1$VxROT routines can be used to introduce zeros selectively into a
matrix.

Example

c
C To rotate the first two rows of a matrix and zero
C out the element in the first column of the second row:

INTEGER INCX,N
REAL X(20,20),A,B,C,S
INCX = 20
N = 20
A= X(l,1)
B = X(2,l)
CALL BLAS1$VSROTG(A,B,C,S)
CALL BLAS1$VSROT(N,X,INCX,X(2,l),INCX,C,S)

llATU

-177

BLAS1 $VxROTG

BLAS1 $VxROTG-Generate the Elements for a Givens Plane
Rotation
The Generate the Elements for a Givens Plane Rotation routines construct a
Givens plane rotation that eliminates the second element of a two-element vector.

Format
BLAS1 $VSROTG

a,b ,c ,s

BLAS 1$VDROTG

a,b ,c ,s

BLAS1$VGROTG

a,b ,c,s

BLAS1$VCROTG

a,b ,c ,s

BLAS 1$VZROTG

a ,b ,c ,s

BLAS 1$VWROTG

a ,b ,c,s

Use BLAS1$VSROTG for single-precision real operations. Use BLAS1$VDROTG
for double-precision real (D-floating) operations and BLAS1$VGROTG for doubleprecision real (G-floating) operations.
Use BLAS1$VCROTG for single-precision complex operations. Use
BLAS1$VZROTG for double-precision complex (D-floating) operations and
BLAS1$VWROTG for double-precision complex (G-floating) operations.

Returns
None.

Arguments
a
OpenVMS usage
type

access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference

On entry, first element of the input vector. On exit, rotated element r. The a
argument is the address of a floating-point or floating-point complex number that
is this vector element.
Specify the data type as follows:

l\ATl-l-17R

Routine

Data Type for a

BLAS1$VSROTG
BLAS1$VDROTG
BLAS1$VGROTG
BLAS1$VCROTG
BLAS1$VZROTG
BLAS1$VWROTG

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

BLAS1 $VxROTG

OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference

On entry, second element of the input vector. On exit from BLAS1$VSROTG,
BLAS1$VDROTG, and BLAS1$VGROTG, reconstruction element z. (See the
Description section for more information about z.) The b argument is the address
of a floating-point or floating-point complex number that is this vector element.
Specify the data type as follows:

Routine

Data Type for b

BLAS1$VSROTG
BLAS1$VDROTG
BLAS1$VGROTG
BLAS1$VCROTG
BLAS1$VZROTG
BLAS1$VWROTG

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

c
OpenVMS usage
type
access
mechanism

floating_point
F _floating, D_floating, or G_floating real
write only
by reference

First rotation element, which can be interpreted as the cosine of the angle of
rotation. The c argument is the address of a floating-point or floating-point
complex number that is this vector element.
Specify the data type (which is always real) as follows:

Routine

Data Type for c

BLAS1$VSROTG and
BLAS1$VCROTG
BLAS1$VDROTG and
BLAS1$VZROTG
BLAS1$VGROTG and
BLAS1$VWROTG

F-floating real
D-floating real
G-floating real

s
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
write only
by reference

P.ATU_i"7Q

BLAS1 $VxROTG

Data Type for s

BLAS1$VSROTG
BLAS1$VDROTG
BLAS1$VGROTG
BLAS1$VCROTG
BLAS1$VZROTG
BLAS1$VWROTG

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

Description
BLAS1$VSROTG, BLAS1$VDROTG, and BLAS1$VGROTG construct
a real Givens plane rotation. BLAS1$VCROTG, BLAS1$VZROTG, and
BLAS1$VWROTG construct a complex Givens plane rotation. The Givens plane
rotation eliminates the second element of a two-element vector. The elements
of the vector are real or complex single-precision or double-precision (D and G)
numbers. The routine name determines the data type you should specify for
arguments a, b, and s. Specify the same data type for each of these arguments.
BLAS1$VSROTG, BLAS1$VDROTG, and BLAS1$VGROTG can use the
reconstruction element z to store the rotation elements for future use. There
is no counterpart to the term z for BLAS1$VCROTG, BLAS1$VZROTG, and
BLAS1$VWROTG.
The BLAS1$VxROTG routines can be used to introduce zeros selectively into a
matrix.
For BLAS1$VDROTG, BLAS1$VGROTG, BLAS1$VZROTG, and
BLAS1$VWROTG (the double-precision routines), the elements of the vector
are scaled to avoid intermediate overflow or underflow. BLAS1$VSROTG and
BLAS1$VCROTG (the single-precision routines) use a backup data type to avoid
intermediate underflow or overflow, which may cause the final result to differ
from the original FORTRAN routine.
BLAS1 $VSROTG, BLAS1 $VDROTG, and BLAS1 $VGROTG - Real Givens Plane
Rotation
Given the elements a and b of an input vector, BLAS1$VSROTG, and
BLAS1$VDROTG, BLAS1$VGROTG calculate the elements c ands of an

orthogonal matrix such that:

[~. :][ ~ l ~ l
= [

l\ATl-L 1 Q()

BLAS1 $VxROTG

A real Givens plane rotation is constructed for values a and b by computing values
for r, c, s, and z, as follows:
r = pVa2

+ b2

where:
p = SIGN(a) if !al > lbl
p = SIGN (b) if [a [~ [bI

c = ~ if r:fO

c=lifr=O
s = ~ if r:fO

s=Oifr=O
z = s if !al > lbl

z = ~if la[::;[b[ and c:fO and r:fO
z = 1 if la[::; lb [ and c = 0 and r:fO

z=Oifr=O
BLAS1$VSROTG, BLAS1$VDROTG, and BLAS1$VGROTG can use the
reconstruction element z to store the rotation elements for future use. The
quantities c and s are reconstructed from z as follows:
For lz I = 1, c = 0 and s = 1.0
For lzl < 1, c =~ands= z
For [zl > 1,' c = ~ and s = ~
The arguments c and s can be passed to the BLAS1$VxROT routines.

BLAS1 $VCROTG, BLAS1 $VZROTG, and BLAS1 $VWROTG - Complex Givens
Plane Rotation
Given the elements a and b of an input vector, BLAS1$VCROTG,

BLAS1$VZROTG, and BLAS1$VWROTG calculate the elements c ands of an
orthogonal matrix such that:

There are no BLAS Level 1 routines with which you can use complex c ands
arguments.

Example

c
c To generate the rotation elements for a vector of
C elements a and b:

REAL A,B,C,S
CALL SROTG(A,B,C,S)

MTH-181

BLAS1 $VxSCAL

BLAS1 $VxSCAL-Scale the Elements of a Vector
The Scale the Elements of a Vector routines compute a* x where a is a scalar
number and x is an n-element vector.

Format
BLAS1$VSSCAL

n ,a ,x ,incx

BLAS1$VDSCAL

n ,a ,x ,incx

BLAS1$VGSCAL

n ,a ,x ,incx

BLAS1 $VCSCAL

n ,a ,x ,incx

BLAS1$VCSSCAL

n ,a ,x ,incx

BLAS1$VZSCAL

n ,a ,x ,incx

BLAS1$VWSCAL

n ,a ,x ,incx

BLAS1$VZDSCAL

n ,a ,x ,incx

BLAS1$VWGSCAL

n ,a ,x ,incx

Use BLAS1$VSSCAL to scale a real single-precision vector by a real singleprecision scalar.
Use BLAS1$VDSCAL to scale a real double-precision (D-floating) vector by a
real double-precision (D-floating) scalar. Use BLAS1$VGSCAL to scale a real
double-precision (G-floating) vector by a real double-precision (G-floating) scalar.
Use BLAS1$VCSCAL to scale a complex single-precision vector by a complex
single-precision scalar. Use BLAS1$VCSSCAL to scale a complex single-precision
vector by a real single-precision scalar.
Use BLAS1$VZSCAL to scale a complex double-precision (D-floating) vector
by a complex double-precision (D-floating) scalar. Use BLAS1$VWSCAL to
scale a complex double-precision (G-floating) vector by a complex doubleprecision (G-floating) scalar. Use BLAS1$VZDSCAL to scale a complex doubleprecision (D-floating) vector by a real double-precision (D-floating) scalar. Use
BLAS1$VWGSCAL to scale a complex double-precision (G-floating) vector by a
real double-precision (G-floating) scalar.

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x to be scaled. Then argument is the address of a
signed longword integer containing the number of elements to be scaled. If you
specify a value for n that is less than or equal to 0, then x is unchanged.

MTH-182

BLAS1 $VxSCAL

OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
read only
by reference

Scalar multiplier for the elements of vector x. The a argument is the address of a
floating-point or floating-point complex number that is this multiplier.
Specify the data type as follows:
Routine

Data Type for a

BLAS1$VSSCAL and
BLAS1$VCSSCAL
BLAS1$VDSCAL and
BLAS1$VZDSCAL
BLAS1$VGSCAL and
BLAS1$VWGSCAL
BLAS1$VCSCAL
BLAS1$VZSCAL
BLAS1$VWSCAL

F-floating real
D-floating real
G-floating real
F-floating complex
D-floating complex
G-floating complex

If you specify 1.0 for a, then x is unchanged.
x

OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference, array reference

JincxJ

where:

= number of vector elements specified in n
incx = increment argument for the array x specified in incx
n

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSSCAL
BLAS1$VDSCAL
BLAS1$VGSCAL
BLAS1$VCSCAL and
BLAS1$VCSSCAL

F-floating real
D-floating real
G-floating real
F-floating complex

MTH-183

BLAS1 $VxSCAL

Routine

Data Type for x

BLAS1$VZSCAL and
BLAS1$VZDSCAL
BLAS1$VWSCAL and
BLAS1$VWGSCAL

D-fioating complex
G-fioating complex

· On exit, x is an array of length at least
1 + (n - 1) * lincxl

where:
n

incx =

number of vector elements specified in n
increment argument for the array x specified in incx

After the call to BLAS1$VxSCAL, xi is replaced by a* xi. If a shares a memory
location with any element of the vector x, results are unpredictable.
incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array x. The incx argument is ~he address of a
signed longword integer containing the increment argument. If incx is greater
than 0, then xis referenced forward in array x; that is, xi is referenced in:
x(l + (i - 1) * incx)
where:
x

=
incx =

array specified in x
element of the vector x
increment argument for the array x specified in incx

If you specify a negative value for incx, it is interpreted as the absolute value of
incx. If incx equals 0, the results are unpredictable.

Description
BLAS1$VxSCAL computes a * x where a is a scalar number and x is an n-element
vector. The computation is expressed as follows:

Vector x contains n elements that are accessed from array x by stepping incx
elements at a time. The vector x can be a row or a column of a matrix. Both
forward and backward indexing are permitted.
The public-domain BLAS Level 1 xSCAL routines require a positive value for
incx. The Run-Time Library BLAS Level 1 routines interpret a negative value
for incx as the absolute value of incx.
The algorithm does not provide a special case for a= 0. Therefore, specifying
0 for a has the effect of setting to zero all elements of the vector x using vector
operations.
MTH-184

BLAS1 $VxSCAL

Example
c
C To scale a vector x by 2.0 using SSCAL:

INTEGER INCX,N
REAL X(20) ,A
INCX = 1
A= 2
N = 20
CALL BLAS1$VSSCAL(N,A,X,INCX)

MTH-185

BLAS1$VxSWAP

BLAS1 $VxSWAP-Swap the Elements of Two Vectors
The Swap the Elements of Two Vectors routines swap n elements of the vector x
with the vector y.

Format
BLAS1$VSSWAP

n ,x ,incx ,y ,incy

BLAS1$VDSWAP

n ,x ,incx ,y ,incy

BLAS1 $VCSWAP

n ,x ,incx ,y ,incy

BLAS1 $VZSWAP

n ,x ,incx ,y ,incy

Use BLAS1$VSSWAP for single-precision real operations and BLAS1$VDSWAP
for double-precision real (D or G) operations.
Use BLAS1$VCSWAP for single-precision complex operations and
BLAS1$VZSWAP for double-precision complex (Dor G) operations.

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Number of elements in vector x to be swapped. Then argument is the address of
a signed longword integer containing the number of elements to be swapped.
x

OpenVMS usage
type
access
mechanism

:floating_point or complex_number
F _fioating, D_:floating, G_fioating real or F _fioating,
D_fioating, G_:floating complex
modify
by reference, array reference

Array containing the elements to be accessed. All elements of array x are
accessed only if the increment argument of x, called incx, is 1. The x argument
is the address of a :floating-point or :floating-point complex number that is this
array. On entry, this argument is an array of length at least
1 + (n - 1) * lincxl

where:

MTH-186

zncx

number of vector elements specified in n
increment argument for the array x specified in incx

BLAS1$VxSWAP

Specify the data type as follows:
Routine

Data Type for x

BLAS1$VSSWAP
BLAS1$VDSWAP
BLAS1$VCSWAP
BLAS1$VZSWAP

F-floating real
D-floating or G-floating real
F-floating complex
D-floating or G-floating complex

If n is less than or equal to 0, then x and y are unchanged. If any element of x
shares a memory location with an element of y, the results are unpredictable.

On exit, x is an array of length at least
1 + (n - 1) * lincxl

where:
n

incx =

number of vector elements specified in n
increment argument for the array x specified in incx

After the call to BLAS1$VxSWAP, n elements of the array specified by x are
interchanged with n elements of the array specified by y.
incx
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

x(l + (i - 1) * incx)
where:
x

=
incx =

array specified in x
element of the vector x
increment argument for the array x specified in incx

If incx is less than 0, then xis referenced backward in array x; that is, xi is
referenced in:

x(l + (n - i) * lincxl)
where:

x
n

=
=
=
incx =

array specified in x
number of vector elements specified in n
element of the vector x
increment argument for the array x specified in incx

MTH-187

BLAS1$VxSWAP

y
OpenVMS usage
type
access
mechanism

floating_point or complex_number
F _floating, D_floating, G_floating real or F _floating,
D_floating, G_floating complex
modify
by reference, array reference

Array containing the elements to be accessed. All elements of array y are
accessed only if the increment argument of y, called incy, is 1. The y argument
is the address of a floating-point or floating-point complex number that is this
array. On entry, this argument is an array of length at least
1 + (n - 1) * lincyl

where:
n

incy

number of vector elements specified in n
increment argument for the array y specified in incy

Specify the data type as follows:
Routine

Data Type for y

BLAS1$VSSWAP
BLAS1$VDSWAP
BLAS1$VCSWAP
BLAS1$VZSWAP

F-floating real
D-floating or G-floating real
F-floating complex
D-floating or G-floating complex

If n is less than or equal to 0, then x and y are unchanged. If any element of x
shares a memory location with an element of y, the results are unpredictable.
On exit, y is an array of length at least
1 + (n - 1) * lincyl

where:
n

incy =

number of vector elements specified in n
increment argument for the array y specified in incy

After the call to BLAS1$VxSWAP, n elements of the array specified by x are
interchanged with n elements of the array specified by y.
incy
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

yq + (i - 1) * incy)

MTH-188

BLAS1$VxSWAP

where:
y

=
incy =

array specified in y
element of the vector y
increment argument for the array y specified in incy

If incy is less than 0, then y is referenced backward in array y; that is, Yi. is

referenced in:

y(l + (n - i) * lincyl)
where:
y

incy =

array specified in y
number of vector elements specified in n
element of the vector y
increment argument for the array y specified in incy

Description
BLAS1$VSSWAP, BLAS1$VDSWAP, BLAS1$VCSWAP, and BLAS1$VZSWAP
swap n elements of the vector x with the vector y. Vectors x and y contain n
elements that are accessed from arrays x and y by stepping incx and incy
elements at a time. Both x and y are real or complex single-precision or doubleprecision (D and G) n-element vectors. The vectors can be rows or columns of a
matrix. Both forward and backward indexing are permitted.
You can use the routine BLAS1$VxSWAP to invert the storage of elements of a
vector within itself. If incx is greater than 0, then xi can be moved from location

x(l + (i - 1) * incx) to x(l + (n - i) * incx)
The following code fragment inverts the storage of elements of a vector within
itself:
NN = N/2
LHALF = l+(N-NN)*INCX
CALL BLAS1$VxSWAP(NN,X,INCX,X(LHALF),-INCX)

BLAS1$VxSWAP does not check for a reserved operand.

Example

C To swap the contents of vectors x and y:

INTEGER INCX,INCY,N
REAL X(20),Y(20)
INCX = 1
INCY = 1
N = 20
CALL BLAS1$VSSWAP(N,X,INCX,Y,INCY)

C To invert the order of storage of the elements of x within

c itself; that is, to move x(l), ... ,x(lOO) to x(lOO), ••. ,x(l):
c
INCX = 1
INCY = -1
N = 50
CALL BLAS1$VSSWAP(N,X,INCX,X(Sl),INCY)

MTH-189

MTH$VxFOLRy_MA_V15

MTH$VxFOLRy_MA_V15-First Order Linear RecurrenceMultiplication and Addition
The First Order Linear Recurrence - Multiplication and Addition routines
provide a vectorized algorithm for the linear recurrence relation that includes
both multiplication and addition operations.

Format
MTH$VJFOLRP_MA_V15

n,a,inca,b,incb,c,incc

MTH$VFFOLRP_MA_V15

n,a,inca,b,incb,c,incc

MTH$VDFOLRP_MA_V15

n,a,inca,b,incb,c,incc

MTH$VGFOLRP_MA_V15

n,a,inca,b,incb,c,incc

MTH$VJFOLRN_MA_V15

n,a,inca,b,incb,c,incc

MTH$VFFOLRN_MA_V15

n,a,inca,b,incb,c,incc

MTH$VDFOLRN_MA_V15

n,a,inca,b,incb,c,incc

MTH$VGFOLRN_MA_V15

n,a,inca,b,incb,c,incc

To obtain one of the preceding formats, substitute the following for x and yin
MTH$VxFOLRy_MA_V15:
x

J for longword integer, F for F-floating, D for D-floating, G for G-floating

P for a positive recursion element, N for a negative recursion element

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Length of the linear recurrence. The n argument is the address of a signed
longword integer containing the length.

a
OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
read only
by reference, array reference

Array of length at least
1 + (n - 1) * inca

where:
n

MTH-190

length of the linear recurrence specified in n

MTH$VxFOLRy_MA_V15

inca =

increment argument for the array a specified in inca

The a argument is the address of a longword integer or floating-point that is this
array.
inca

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array a. The inca argument is the address of a
signed longword integer containing the increment argument. For contiguous
elements, specify 1 for inca.
b

OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
read only
by reference, array reference

Array of length at least
1 + (n - 1) * incb

where:
n

incb =

length of the linear recurrence specified in n
increment argument for the array h specified in inch

The h argument is the address of a longword integer or floating-point number
that is this array.
incb

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array h. The inch argument is the address of a
signed longword integer containing the increment argument. For contiguous
elements, specify 1 for inch.

c
OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
modify
by reference, array reference

Array of length at least
1 + n * incc

where:

= length of the linear recurrence specified in n
incc = increment argument for the array c specified in incc

The c argument is the address of a longword integer or floating-point number
that is this array.

l\llTl-L101

MTH$VxFOLRy_MA_V15

incc

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array c. The incc argument is the address of a
signed longword integer containing the increment argument. For contiguous
elements, specify 1 for incc. Do not specify 0 for incc.

Description
MTH$VxFOLRy_MA_V15 is a group of routines that provides a vectorized
algorithm for computing the following linear recurrence relation:

C (I + 1) = + /- C (I) * A (I) + B (I)
Note ~~~~~~~~~~~~~

Save the contents of vector registers VO through V15 before you call this
routine.

Call this routine to utilize vector hardware when computing the recurrence. As
an example, the call from VAX FORTRAN is as follows:
Kl = ••••
K2 = ••••
K3 = ••••
CALL MTH$VxFOLRy_MA_Vl5(N,A(Kl),INCA,B(K2),INCB,C(K3),INCC)

The preceding FORTRAN call replaces the following loop:
Kl = ••••
K2 = ••••
K3 = .•..
DO I

= 1, N

C(K3+I*INCC) = {+/-}C(K3+(I-l)*INCC) * A(Kl+(I-l)*INCA)
+ B(K2+(I-l)*INCB)
END DO

_z_

For the output array (c), the increment argument (incc) cannot be 0. However,
you can specify 0 for the input increment arguments (inca and inch). In that
case, the input will be treated as a scalar value and broadcast to a vector input
with all vector elements equal to the scalar value.
In MTH$VxFOLRy_MA_V15, array c can overlap array a and array b, or both,
as long as the address of array element ex is not also the address of an element
of a or b that will be referenced at a future time in the recurrence relation. For
example, in the following code fragment you must ensure that the address of
c(l + i * incc) does not equal the address of either a(i * inca) or b(k * incb) for
MTH-192

MTH$VxFOLRy_MA_V15

l~i~n and j?.i

+ 1.

DO I = 1,N
C(l+I*INCC) = C(l+(I-l)*INCC) * A(l+(I-l)*INCA) + B(l+(I-l)*INCB)
END DO

Examples
1.

c
C
C

The following FORTRAN loop computes
a linear recurrence.
INTEGER I
DIMENSION A(200), B(50), C(50)
EQUIVALENCE (B,C)
C(4) = .•.•
DO I = 5, 50
C(I) = C((I-1)) * A(I*3) + B(I)
END DO

c
C
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.
DIMENSION A(200), B(50), C(50)
EQUIVALENCE (B,C)
C(4) = ••••
CALL MTH$VFFOLRP_MA_Vl5(46, A(15), 3, B(5), 1, C(4), 1)

c
c
C

The following FORTRAN loop computes
a linear recurrence.
INTEGER K,N,INCA,INCB,INCC,I
DIMENSION A(30), B(6), C(50)
K = 44
N= 6
INCA = 5
INCB = 1
INCC = 1
DO I = 1, N
C(K+I*INCC) = -C(K+(I-l)*INCC) * A(I*INCA) + B(I*INCB)
END DO

c
c
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.
INTEGER K,N,INCA,INCB,INCC
DIMENSION A(30), B(6), C(50)
K = 44
N= 6
INCA = 5
INCB = 1
INCC = 1
CALL MTH$VFFOLRN_MA_Vl5(N, A(INCA), INCA, B(INCB), INCB, C(K), INCC)

MTH$VxFOLRy_z_V8

MTH$VxFOLRy_z_V8-First Order Linear Recurrence Multiplication or Addition
The First Order Linear Recurrence - Multiplication or Addition routines provide
a vectorized algorithm for the linear recurrence relation that includes either a
multiplication or an addition operation, but not both.

Format

MTH$VJFOLRP_M_V8 n,a,inca,b,incb
MTH$VFFOLRP_M_V8 n,a,inca,b,incb
MTH$VDFOLRP_M_V8 n,a,inca,b,incb
MTH$VGFOLRP_M_V8 n,a,inca,b,incb
MTH$VJFOLRN_M_V8 n,a,inca,b,incb
MTH$VFFOLRN_M_V8 n,a,inca,b,incb
MTH$VDFOLRN_M_V8 n,a,inca,b,incb
MTH$VGFOLRN_M_V8 n,a,inca,b,incb
MTH$VJFOLRP_A_V8 n,a,inca,b,incb
MTH$VFFOLRP_A_V8 n,a,inca,b,incb
MTH$VDFOLRP_A_V8 n,a,inca,b,incb
MTH$VGFOLRP_A_V8 n,a,inca,b,incb
MTH$VJFOLRN_A_V8 n,a,inca,b,incb
MTH$VFFOLRN_A_V8 n,a,inca,b,incb
MTH$VDFOLRN_A_V8 n,a,inca,b,incb
MTH$VGFOLRN_A_V8 n,a,inca,b,incb
To obtain one of the preceding formats, substitute the following for x, y, and z in
MTH$VxFOLRy_z_V8:
x

J for longword integer, F for F-floating, D for D-floating, G for G-floating

P for a positive recursion element, N for a negative recursion element

M for multiplication, A for addition

Returns
None.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Length of the linear recurrence. The n argument is the address of a signed
longword integer containing the length.

ll.ATl-L10A

MTH$VxFOLRy_z_V8

a
OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
read only
by reference, array reference

Array of length at least

1+ (n-1) *inca
where:
n

= length of the linear recurrence specified in n

inca =

increment argument for the array a specified in inca

The a argument is the address of a longword integer or floating-point that is this
array.
inca
OpenVMS us.age
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array a. The inca argument is the address of a
signed longword integer containing the increment argument. For contiguous
elements, specify 1 for inca.
b
OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
modify
by reference, array reference

Array of length at least
1+(n-1)*incb

where:
n

= length of the linear recurrence specified in n

incb =

increment argument for the array b specified in inch

The h argument is the address of a longword integer or floating-point number
that is this array.
incb
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array h. The inch argument is the address of a
signed longword integer containing the increment argument. For contiguous
elements, specify 1 for inch.

11.A"T"LJ

-I nr::-

MTH$VxFOLRy_z_V8

Description
MTH$VxFOLRy_z_VS is a group of routines that provide a vectorized algorithm
for computing one of the following linear recurrence relations:
B (J) = +I - B (I - 1) * A (1)

B(I) = +/-B(J - 1) +A(!)
For the first relation, specify M for z in the routine name to denote multiplication;
for the second relation, specify A for z in the routine name to denote addition.
Note

Save the contents of vector registers VO through VS before you call this
routine.

Call this routine to utilize vector hardware when computing the recurrence. As
an example, the call from VAX FORTRAN is as follows:
CALL MTH$VxFOLRy_z_V8(N,A(Kl),INCA,B(K2),INCB)

The preceding FORTRAN call replaces the following loop:
Kl = .•..
K2 = •••.
DO I = 1, N

B(K2+I*INCB) = {+/-}B(K2+(I-l)*INCB) {+/*} A(Kl+(I-l)*INCA)
END DO

The arrays used in a FOLR expression must be of the same data type in order to
be vectorized and user callable. The MTH$ FOLR routines assume that all of the
arrays are of the same data type.
This group of routines, MTH$VxFOLRy_z_VS (and also MTH$VxFOLRy_MA_
V15) save the result of each iteration of the linear recurrence relation in an
array. This is different from the behavior of MTH$VxFOLRLy_MA_V5 and
MTH$VxFOLRLy_z_V2, which return only the result of the last iteration of the
linear recurrence relation.
For the output array (b), the increment argument (inch) cannot be 0. However,
you can specify 0 for the input increment argument (inca). In that case, the
input will be treated as a scalar and broadcast to a vector input with all vector
elements equal to the scalar value.

l\ATLI

-1 oa

MTH$VxFOLRy_z_V8

Examples
1.

C
C

The following FORTRAN loop computes
a linear recurrence.

D FLOAT
INTEGER N,INCA,INCB,I
DIMENSION A(30), B(l3)
N=6
INCA = 5
INCB = 2
DO I = 1, N
B(l+I*INCB)
-B(l+(I-l)*INCB) * A(I*INCA)
END DO

c
C
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.

D FLOAT
INTEGER N,INCA,INCB
REAL*8 A(30), B(13)

INCA = 5
INCB = 2
CALL MTH$VDFOLRN_M_V8(N, A(INCA), INCA, B(l), INCB)

C
C

The following FORTRAN loop computes
a linear recurrence.

G FLOAT
INTEGER N,INCA,INCB
DIMENSION A(30), B(l3)
N=5
INCA = 5
INCB = 2
DO I = 2, N
B(l+I*INCB) = B((I-l)*INCB) + A(I*INCA)
END DO

c
C
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.

G FLOAT
INTEGER N,INCA,INCB
REAL*8 A(30), B(l3)
N=5
INCA = 5
INCB = 2
CALL MTH$VGFOLRP_A_V8(N, A(INCA), INCA, B(INCB), INCB)

II.AILI

-4 r\"'7

MTH$VxFOLRLy_MA_V5

MTH$VxFOLRLy_MA_V5-First Order Linear Recurrence Multiplication and Addition - Last Value
The First Order Linear Recurrence - Multiplication and Addition - Last
Value routines provide a vectorized algorithm for the linear recurrence relation
that includes both multiplication and addition operations. Only the last value
computed is stored.

Format

MTH$VJFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VFFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VDFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VGFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VJFOLRLN_MA_V5 n,a,inca,b,incb,t
MTH$VFFOLRLN_MA_V5 n,a,inca,b,incb,t
MTH$VDFOLRLN_MA_V5 n,a,inca,b,incb,t
MTH$VGFOLRLN_MA_V5 n,a,inca,b,incb,t
To obtain one of the preceding formats, substitute the following for x and y in
MTH$VxFOLRLy_MA_V5:
x

J for longword integer, F for F-floating, D for D-floating, G for G-floating

P for a positive recursion element, N for a negative recursion element

Returns
OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating or G_floating
write only
by value

The function value is the result of the last iteration of the linear recurrence
relation. The function value is returned in RO or RO and Rl.

Arguments
n
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Length of the linear recurrence. The n argument is the address of a signed
longword integer containing the length.

a
OpenVMS usage
type
access
mechanism

l\JITl-L1QA

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
read only
by reference, array reference

MTH$VxFOLRLy_MA_V5
Array of length at least

1+ (n-1) *inca
where:

= length of the linear recurrence specified in n
mca = increment argument for the array a specified in inca

The a argument is the address of a longword integer or floating-point that is this
array.
inca
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

longword_signed or floating_point
longword integer (signed), F_floating, D_floating, or G_floating
read only
by reference, array reference

Array of length at least

1+ (n-1) *incb
where:

= length of the linear recurrence specified in n
incb = increment argument for the array b specified in inch
n

The h argument is the address of a longword integer or floating-point number
that is this array.
incb
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Increment argument for the array h. The inch argument is the address of a
signed longword integer containing the increment argument. For contiguous
elements, specify 1 for inch.
t

OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floatingmodify
by reference

Variable containing the starting value for the recurrence; overwritten with the
value computed by the last iteration of the linear recurrence relation. The t
argument is the address of a longword integer or floating-point number that is
this value.

MTH-199

MTH$VxFOLRLy_MA_V5

Description
MTH$VxFOLRLy_MA_V5 is a group of routines that provide a vectorized
algorithm for computing the following linear recurrence relation. (The Ton the
right side of the equation is the result of the previous iteration of the loop.)

T = +/-T * A(I) + B(I)
Note _ _ _ _ _ _ _ _ _ _ __

Save the contents of vector registers VO through V5 before you call this
routine.

Call this routine to utilize vector hardware when computing the recurrence. As
an example, the call from VAX FORTRAN is as follows:
CALL MTH$VxFOLRy_MA_VS(N,A(Kl),INCA,B(K2),INCB,T)

The preceding FORTRAN call replaces the following loop:
Kl = ••.
K2 = .••
DO I = 1, N
T = {+/-}T * A(Kl+(I-l)*INCA) + B(Kl+(I-l)*INCB)
END DO

The arrays used in a FOLR expression must be of the same data type in order to
be vectorized and user callable. The MTH$ FOLR routines assume that all of the
arrays are of the same data type.
This group of routines, MTH$VxFOLRLy_MA_V5 (and also MTH$VxFOLRLy_
z_V2) returns only the result of the last iteration of the linear recurrence
relation. This is different from the behavior of MTH$VxFOLRy_MA_V15 (and
also MTH$VxFOLRy_z_V8), which save the result of each iteration of the linear
recurrence relation in an array.
If you specify 0 for the input increment arguments (inca and inch), the input will
be treated as a scalar and broadcast to a vector input with all vector elements
equal to the scalar value.

Examples
1.

The following FORTRAN loop computes
a linear recurrence.

G FLOAT
INTEGER N,INCA,INCB,I
REAL*8 A(30), B(6), T
N =6
INCA = 5
INCB = 1
T = 78.9847562
DO I = 1, N
T = -T * A(I*INCA) + B(I*INCB)
END DO

c
c

MTH-200

MTH$VxFOLRLy_MA_V5
c
c
c
c
C

C
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.
G FLOAT
INTEGER N,INCA,INCB
DIMENSION A(30), B(6), T
N=6
INCA = 5
INCB = 1
T = 78.9847562
T = MTH$VGFOLRLN_MA_V5(N, A(INCA), INCA, B(INCB), INCB, T)

The following FORTRAN loop computes
a linear recurrence.

c
C

G FLOAT
INTEGER N,INCA,INCB,I
REAL*8 A(30), B(6), T
N= 6
INCA = 5
INCB = 1
T = 78.9847562
DO I = 1, N
T = T * A(I*INCA) + B(I*INCB)
END DO

C
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.

G FLOAT
INTEGER N,INCA,INCB
DIMENSION A(30), B(6), T
N = 6
INCA = 5
INCB = 1
T = 78.9847562
T = MTH$VGFOLRLP_MA_V5(N, A(INCA), INCA, B(INCB), INCB, T)

MTH-201

MTH$VxFOLRLy_z_V2

MTH$VxFOLRLy_z_V2-First Order Linear Recurrence Multiplication or Addition - Last Value
The First Order Linear Recurrence - Multiplication or Addition - Last Value
routines provide a vectorized algorithm for the linear recurrence relation that
includes either a multiplication or an addition operation. Only the last value
computed is stored.

Format

MTH$VJFOLRLP_M_V2 n,a,inca,t
MTH$VFFOLRLP_M_V2 n,a,inca,t
MTH$VDFOLRLP_M_V2 n,a,inca,t
MTH$VGFOLRLP_M_V2 n,a,inca,t
MTH$VJFOLRLN_M_V2 n,a,inca,t
MTH$VFFOLRLN_M_V2 n,a,inca,t
MTH$VDFOLRLN_M_V2 n,a,inca,t
MTH$VGFOLRLN_M_V2 n,a,inca,t
MTH$VJFOLRLP_A_V2 n,a,inca,t
MTH$VFFOLRLP_A_V2 n,a,inca,t
MTH$VDFOLRLP_A_V2 n,a,inca,t
MTH$VGFOLRLP_A_V2 n,a,inca,t
MTH$VJFOLRLN_A_V2 n,a,inca,t
MTH$VFFOLRLN_A_V2 n,a,inca,t
MTH$VDFOLRLN_A_V2 n,a,inca,t
MTH$VGFOLRLN_A_V2 n,a,inca,t
To obtain one of the preceding formats, substitute the following for x, y, and z in
MTH$VxFOLRLy_z_V2:
x
y
z

J for longword integer, F for F-floating, D for D-floating, G for G-floating
P for a positive recursion element, N for a negative recursion element
M for multiplication, A for addition

Returns
OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating or G_floating
write only
by value

The function value is the result of the last iteration of the linear recurrence
relation. The function value is returned in RO or RO and Rl.

MTH-202

MTH$VxFOLRLy_z_V2

Arguments
n

OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

Length of the linear recurrence. The n argument is the address of a signed
longword integer containing the length.
a

OpenVMS usage
type
access
mechanism

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
read only
by reference, array reference

Array of length at least
n * inca

where:
n
= length of the linear recurrence specified in n
inca = increment argument for the array a specified in inca

The a argument is the address of a longword integer or floating-point that is this
array.
in ca
OpenVMS usage
type
access
mechanism

longword_signed
longword integer (signed)
read only
by reference

longword_signed or floating_point
longword integer (signed), F _floating, D_floating, or G_floating
modify
by reference

MTH$VxFOLRLy_z_V2

Description
MTH$VxFOLRLy_z_V2 is a group of routines that provide a vectorized algorithm
for computing one of the following linear recurrence relations. (The T on the right
side of the following equations is the result of the previous iteration of the loop.)

T = +/-T *A(!)
or
T = +/-T + A(I)

For the first relation, specify M for z in the routine name to denote multiplication;
for the second relation, specify A for z in the routine name to denote addition.
Note

Save the contents of vector registers VO, Vl, and V2 before you call this
routine.

Call this routine to utilize vector hardware when computing the recurrence. As
an example, the call from VAX FORTRAN is as follows:
CALL MTH$VxFOLRLy_z_V2(N,A(Kl),INCA,T)

The preceding FORTRAN call replaces the following loop:
Kl = ••• ,
DO I

= 1, N

T = {+/-}T {+/*} A(Kl+(I-l)*INCA)

END DO

The arrays used in a FOLR expression must be of the same data type in order to
be vectorized and user callable. The MTH$ FOLR routines assume that all of the
arrays are of the same data type.
This group of routines, MTH$VxFOLRLy_z_V2 (and also MTH$VxFOLRLy_
MA_V5) return only the result of the last iteration of the linear recurrence
relation. This is different from the behavior of MTH$VxFOLRy_MA_V15 (and
also MTH$VxFOLRy_z_V8), which save the result of each iteration of the linear
recurrence relation in an array.
If you specify 0 for the input increment argument (inca), the input will be treated
as a scalar and broadcast to a vector input with all vector elements equal to the
scalar value.

MTH$VxFOLRLy_z_V2

Examples
1.

c
C
C

The following FORTRAN loop computes
a linear recurrence.

D FLOAT
INTEGER I,N
REAL*8 A(200), T
T = 78.9847562
N = 20
DO I = 4, N
T = -T * A(I*lO)
END DO

c
c
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.

c
C

D FLOAT
INTEGER N
REAL*8 A(200), T
T = 78.9847562
N = 20
T = MTH$VDFOLRLN_M_V2(N-3, A(40), 10, T)

C
C

The following FORTRAN loop computes
a linear recurrence.

D FLOAT
INTEGER I,N
REAL*8 A(200), T
T = 78.9847562
N = 20
DO I = 4, N
T = T + A(I*lO)
END DO

c
C
C

The following call from FORTRAN to a FOLR
routine replaces the preceding loop.

D FLOAT
INTEGER N
REAL*8 A(200), T
T = 78.9847562
N = 20
T = MTH$VDFOLRLP_A_V2(N-3, A(40), 10, T)

A
Additional MTH$ Routines
The following supported MTH$ routines are not included with the routines in
the Scalar MTH$ Reference Section because they are rarely used. The majority
of these routines serve to satisfy external references when intrinsic functions
in FORTRAN and other languages are passed as parameters. Otherwise, the
functions are performed by inline code.
Table A-1 lists all of the entry point and argument information for the MTH$
routines not documented in the Scalar MTH$ Reference Section of this manual.
Table A-1 Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$ABS

F-fioating Absolute Value Routine

Format:
Returns:
f·floating:

MTH$DABS

MTH$ABS f-floating
floating_point, F _floating, write only, by value
floating_point, F _floating, read only, by reference
D-fioating Absolute Value Routine

Format:
Returns:
d-floating:

MTH$GABS

MTH$DABS d-floating
floating_point, D_floating, write only, by value
floating_point, D_floating, read only, by reference
G-fioating Absolute Value Routine

Format:
Returns:
g-floating:

MTH$HABS

MTH$GABS g-floating
floating_point, G_floating, write only, by value
floating_point, G_floating, read only, by reference
H-fioating Absolute Value Routine

Format:
Returns:
h-abs-val:
h-floating:

MTH$HABS h-abs-val, h-floating
None
floating_point, H_floating, write only, by
reference
floating_point, H_floating, read only, by
reference
(continued on next page)

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$IIABS

Word Absolute Value Routine
Format:

MTH$IIABS word

Returns:

word_signed, word (signed), write only, by value

word:

word_signed, word (signed), read only, by
reference

MTH$JIABS

Longword Absolute Value Routine
Format:

MTH$JIABS longword

Returns:

longword_signed, longword (signed), write only,
by value

longword:

longword_signed, longword (signed), read only,
by reference

MTH$IIAND

Bitwise AND of Two Word Parameters Routine
Format:

MTH$1~ wordl, word2

Returns:

word_unsigned, word (unsigned), write only, by
value

wordl:

word_unsigned, word (unsigned), read only, by
reference

word2:

word_unsigned, word (unsigned), read only, by
reference

MTH$JIAND

Bitwise AND of Two Longword Parameters
Routine
Format:

MTH$JIAND longword!, longword2

Returns:

longword_unsigned, longword (unsigned), write
only, by value

longword!:

longword_unsigned, longword (unsigned), read
only, by reference

longWord2:

longword_unsigned, longword (unsigned), read
only, by reference

Format:

MTH$DBLE f-floating

Returns:

floating_point, D_floating, write only, by value

f-floating:

floating_point, F _floating, read only, by reference

MTH$DBLE

Convert F-floating to D-floating (Exact) Routine

MTH$GDBLE

Convert F-fioating to G-floating (Exact) Routine
Format:

MTH$GDBLE f-floating

Returns:

floating_point, G_floating, write only, by value

f-floating:

floating_point, F _floating, read only, by reference
(continued on next page)

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$DIM

Positive Difference of Two F-floating Parameters
Routine
Format:

MTH$DIM f-floatingl, f-floating2

Returns:

floating_point, F _floating, write only, by value

f-floatingl:

floating_point, F _floating, read only, by reference

f-floating2:

floating_point, F _floating, read only, by reference

Positive Difference of Two D-floating Parameters
Routine

MTH$DDIM

Format:

MTH$DDIM d-floatingl, d-floating2

Returns:

floating_point, D_floating, write only, by value

d-floatingl:

floating_point, D_floating, read only, by reference

d-floating2:

floating_point, D_floating, read only, by reference

Positive Difference of Two G-floating Parameters
Routine

MTH$GDIM

Format:

MTH$GDIM g-floatingl, g-floating2

Returns:

floating_point, G_floating, write only, by value

g-floatingl:

floating_point, G_floating, read only, by reference

g-floating2:

floating_point, G_floating, read only, by reference

Positive Difference of Two H-floating Parameters
Routine

MTH$HDIM

Format:

MTH$HDIM h-floating, h-floatingl, h-floating2

Returns:

None

h-floating:

floating_point, H_floating, write only, by
reference

h-floatingl:

floating_point, H_floating, read only, by
reference

h-floating2:

floating_point, H_floating, read only, by
reference

Positive Difference of Two Word Parameters
Routine

MTH$IIDIM

Format:

MTH$IIDIM wordl, word2

Returns:

word_signed, word (signed), write only, by value

wordl:

word_signed, word (signed), read only, by
reference

word2:

word_signed, word (signed), read only, by
reference
(continued on next page)

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$JIDIM

Positive Difference of Two Longword Parameters
Routine

Format:
Returns:
longwordl:
longword2:

MTH$JIDIM longwordl, longword2
longword_signed, longword (signed), write only,
by value
longword_signed, longword (signed), read only,
by reference
longword_signed, longword (signed), read only,
by reference
Bitwise Exclusive OR of Two Word Parameters
Routine

MTH$IIEOR

Format:
Returns:
wordl:
word2:

MTH$JIEOR

MTH$IIEOR wordl, word2
word_unsigned, word (unsigned), write only, by
value
word_unsigned, word (unsigned), read only, by
reference
word_unsigned, word (unsigned), read only, by
reference
Bitwise Exclusive OR of Two Longword
Parameters Routine

Format:
Returns:
longword!:
longword2:

MTH$IIFIX

Format:
Returns:
f-ftoating:
MTH$JIFIX

MTH$JIEOR longwordl, longword2
longword_unsigned, longword (unsigned), write
only, by value
longword_unsigned, longword (unsigned), read
only, by reference
longword_unsigned, longword (unsigned), read
only, by reference
Convert F-fioating to Word (Truncated) Routine
MTH$IIFIX f-floating
word_signed, word (signed), write only, by value
floating_point, F _floating, read only, by reference
Convert F-fioating to Longword (Truncated)
Routine

Format:
Returns:
f-floating:

MTH$JIFIX f-floating
longword_signed, longword (signed), write only,
by value
floating_point, F_floating, read only, by reference
(continued on next page)

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$FLOATI

Convert Word to F-floating (Exact) Routine
Format:

MTH$FLOATI word

Returns:

floating_point, F _floating, write only, by value

word:

word_signed, word (signed), read only, by
reference

MTH$DFLOTI

Convert Word to D-floating (Exact) Routine
Format:

MTH$DFLOTI word

Returns:

floating_point, D_floating, write only, by value

word:

word_signed, word (signed), read only, by
reference

Format:

MTH$GFLOTI word

Returns:

floating_point, G_floating, write only, by value

word:

word_signed, word (signed), read only, by
reference

MTH$GFLOTI

Convert Word to G-floating (Exact) Routine

Convert Longword to F-floating (Rounded)
Routine

MTH$FLOATJ

Format:

MTH$FLOATJ longword

Returns:

floating_point, F _floating, write only, by value

longword:

longword_signed, longword (signed), read only,
by reference

Convert Longword to D-floating (Exact) Routine

MTH$DFLOTJ

Format:

MTH$DFLOTJ longword

Returns:

floating_point, D_floating, write only, by value

longword:

longword_signed, longword (signed), read only,
by reference

Convert Longword to G-floating (Exact) Routine

MTH$GFLOTJ

Format:

MTH$GFLOTJ longword

Returns:

floating_point, G_floating, write only, by value

longword:

longword_signed, longword (signed), read only,
by reference
(continued on next page)

A-5

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$FLOOR

Convert F-floating to Greatest F-floating Integer
Routine

Format:

MTH$FLOOR f-floating

JSB:

MTH$FLOOR_Rl f-floating

Returns:

floating_point, F_floating, write only, by value

f-floating:

floating_point, F_floating, read only, by reference

Convert D-fioating to Greatest D-fioating Integer
Routine

MTH$DFLOOR

Format:

MTH$DFLOOR cl-floating

JSB:

MTH$DFLOOR_R3 cl-floating

Returns:

floating_point, D_floating, write only, by value

d-floating:

floating_point, D_floating, read only, by reference

Convert G-floating to Greatest G-floating Integer
Routine

MTH$GFLOOR

Format:

MTH$GFLOOR g-floating

JSB:

MTH$GFLOOR_R3 g-floating

Returns:

floating_point, G_floating, write only, by value

g-floating:

floating_point, G_floating, read only, by reference

Convert H-floating to Greatest H-floating Integer
Routine

MTH$HFLOOR

Format:

MTH$HFLOOR max-h-float, h-floating

JSB:

MTH$HFLOOR_R7 h-floating

Returns:

None

max-h-float:

floating_point, H_floating, write only, by
reference

h-floating:

floating_point, H_floating, read only, by
reference

Convert F-floating to Truncated F-fioating
Routine

MTH$AINT

Format:

MTH$AINT f-floating

JSB:

MTH$AINT_R2 f-floating

Returns:

floating_point, F _floating, write only, by value

f-floating:

floating_point, F _floating, read only, by reference
(continued on next page)

A-6

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$DINT

Convert D-floating to Truncated D-floating
Routine
Format:

MTH$DINT d-floating

JSB:

MTH$DINT_R4 d-floating

Returns:

floating_point, D_floating, write only, by value

d-fioating:

floating_point, D_floating, read only, by reference

Convert D-floating to Word (Truncated) Routine

MTH$IIDINT
Format:

MTH$IIDINT d-floating

Returns:

word_signed, word (signed), write only, by value

d-fioating:

floating_point, D _floating, read only, by reference

Convert D-floating to Longword (Truncated)
Routine

MTH$JIDINT
Format:

MTH$JIDINT d-floating

Returns:

longword_signed, longword (signed), write only,
by value

d-fioating:

floating_point, D_floating, read only, by reference

Convert G-floating to Truncated G-floating
Routine

MTH$GINT
Format:

MTH$GINT g-floating

JSB:

MTH$GINT_R4 g-floating

Returns:

floating_point, G_floating, write only, by value

g-fioating:

floating_point, G_floating, read only, by reference

Convert G-fioating to Word (Truncated) Routine

MTH$IIGINT
Format:

MTH$IIGINT g-floating

Returns:

word_signed, word (signed), write only, by value

g-fioating:

floating_point, G_floating, read only, by reference

Convert G-fioating to Longword (Truncated)
Routine

MTH$JIGINT
Format:

MTH$JIGINT g-floating

Returns:

longword_signed, longword (signed), write only,
by value

g-fioating:

floating_point, G_floating, read only, by reference
(continued on next page)

A-7

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$HINT

Convert H-floating to Truncated H-floating
Routine
Format:

MTH$HINT trunc-h-flt, h-floating

JSB:

MTH$HINT_R8 h-floating

Returns:

None

trunc-h-flt:

floating_point, H_floating, write only, by
reference

h-floating:

floating_point, H_floating, read only, by
reference

Format:

MTH$IIHINT h-floating

Returns:

word_signed, word (signed), write only, by value

h-floating:

floating_point, H_floating, read only, by
reference

Convert H-floating to Word (Truncated) Routine

MTH$IIHINT

Convert H-floating to Longword (Truncated)
Routine

MTH$JIHINT
Format:

MTH$JIHINT h-floating

Returns:

longword_signed, longword (signed), write only,
by value

h-floating:

floating_point, H_floating, read only, by
reference

Convert F-floating to Word (Truncated) Routine

MTH$IINT
Format:

MTH$IINT f-floating

Returns:

word_signed, word (signed), write only, by value

f-floating:

floating_point, F _floating, read only, by reference

Convert F-floating to Longword (Truncated)
Routine

MTH$JINT
Format:

MTH$JINT f-floating

Returns:

longword_signed, longword (signed), write only,
by value

f-floating:

floating_point, F _floating, read only, by reference
(continued on next page)

A-8

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$IIOR

Bitwise Inclusive OR of Two Word Parameters
Routine

Format:

MTH$110R wordl, word2

Returns:

word_unsigned, word (unsigned), write only, by
value

wordl:

word_unsigned, word (unsigned), read only, by
reference

word2:

word_unsigned, word (unsigned), read only, by
reference

MTH$JIOR

Bitwise Inclusive OR of Two Longword
Parameters Routine

Format:

MTH$JIOR longwordl, longword2

Returns:

longword_unsigned, longword (unsigned), write
only, by value

longwordl:

longword_unsigned, longword (unsigned), read
only, by reference

longword2:

longword_unsigned, longword (unsigned), read
only, by reference

MTH$AIMAXO

F-fioating Maximum of N Word Parameters
Routine

Format:

MTH$AIMAXO word, ...

Returns:

floating_point, F _floating, write only, by value

word:

word_signed, word (signed), read only, by
reference

MTH$AJMAXO

F-fioating Maximum of N Longword Parameters
Routine

Format:

MTH$AJMAXO longword, ...

Returns:

floating_point, F _floating, write only, by value

longword:

longword_signed, longword (signed), read only,
by reference

MTH$IMAXO

Word Maximum of N Word Parameters Routine

Format:

MTH$1MAXO word, ...

Returns:

word_signed, word (signed), write only, by value

word:

word_signed, word (signed), read only, by
reference
(continued on next page)

A_Q

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$JMAXO

Longword Maximum of N Longword Parameters
Routine

Format:

MTH$JMAXO longword, ...

Returns:

longword_signed, longword (signed), write only,
by value

longword:

longword_signed, longword (signed), read only,
by reference

F-floating Maximum of NF-floating Parameters
Routine

MTH$AMAX1

Format:

MTH$AMAX1 f-floating, ...

Returns:

floating_point, F _floating, write only, by value

f-floating:

floating_point, F _floating, read only, by reference

D-floating Maximum of ND-floating Parameters
Routine

MTH$DMAX1

Format:

MTH$DMAX1 cl-floating, ...

Returns:

floating_point, D_floating, write only, by value

d-floating:

floating_point, D_floating, read only, by reference

G-floating Maximum of NG-floating Parameters
Routine

MTH$GMAX1

Format:

MTH$GMAX1 g-floating, ...

Returns:

floating_point, G_floating, write only, by value

g-floating:

floating_point, G_floating, read only, by reference

H-floating Maximum of NH-floating Parameters
Routine

MTH$HMAX1

Format:

MTH$HMAX1 h-float-max, h-floating, ...

Returns:

None

h-float-max:

floating_point, H_floating, write only, by
reference

h-floating:

floating_point, H_floating, read only, by
reference

Word Maximum of NF-floating Parameters
Routine

MTH$IMAX1

Format:

MTH$IMAX1 f-floating, ...

Returns:

word_signed, word (signed), write only, by value

f-floating:

floating_point, F _floating, read only, by reference
(continued on next page)

A-10

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$JMAX1

Longword Maximum of NF-floating Parameters
Routine
Format:

MTH$JMAX1 f-floating, ...

Returns:

longword_signed, longword (signed), write only,
by value

f-floating:

floating_point, F _floating, read only, by reference

F-floating Minimum of N Word Parameters
Routine

MTH$AIMINO
Format:

MTH$AIMINO word, ...

Returns:

floating_point, F _floating, write only, by value

word:

word_signed, word (signed), read only, by
reference

F-floating Minimum of N Longword Parameters
Routine

MTH$AJMINO
Format:

MTH$AJMINO longword, ...

Returns:

floating_point, F _floating, write only, by value

longword:

longword_signed, longword (signed), read only,
by reference

Format:

MTH$IMINO word, ...

Returns:

word_signed, word (signed), write only, by value

word:

word_signed, word (signed), read only, by
reference

Word Minimum of N Word Parameters Routine

MTH$IMINO

Longword Minimum of N Longword Parameters
Routine

MTH$JMINO
Format:

MTH$JMINO longword, ...

Returns:

longword_signed, longword (signed), write only,
by value

longword:

longword_signed, longword (signed), read only,
by reference

F-floating Minimum of NF-floating Parameters
Routine

MTH$AMIN1
Format:

MTH$AMIN1 f-floating, ...

Returns:

floating_point, F _floating, write only, by value

f-floating:

floating_point, F _floating, read only, by reference
(continued on next page)

l\_11

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$DMIN1

D-floating Minimum of ND-floating Parameters
Routine

Format:

MTH$DMIN1 d-floating, ...

Returns:

floating_point, D_floating, write only, by value

d-floating:

floating_point, D_floating, read only, by reference

MTH$GMIN1

G-floating Minimum of NG-floating Parameters
Routine

Format:

MTH$GMIN1 g-floating, ...

Returns:

floating_point, G_floating, write only, by value

g-floating:

floating_point, G_floating, read only, by reference

MTH$HMIN1

H-floating Minimum of NH-floating Parameters
Routine

Format:

MTH$HMIN1 h-float-max, h-floating, ...

Returns:

None

h-float-max:

floating_point, H_floating, write only, by
reference

h-floating:

floating_point, H_floating, read only, by
reference

MTH$IMIN1

Word Minimum of N F-floating Parameters
Routine

Format:

MTH$IMIN1 f-floating, ...

Returns:

word_signed, word (signed), write only, by value

f-floating:

floating_point, F _floating, read only, by reference

MTH$JMIN1

Longword Minimum of NF-floating Parameters
Routine

Format:

MTH$JMIN1 f-floating, ...

Returns:

longword_signed, longword (signed), write only,
by value

f-floating:

floating_point, F _floating, read only, by reference

MTH$AMOD

Remainder from Division of 'llvo F-floating
Parameters Routine

Format:

MTH$AMOD dividend, divisor

Returns:

floating_point, F _floating, write only, by value

dividend:

floating_point, F _floating, read only, by reference

divisor:

floating_point, F _floating, read only, by reference
(continued on next page)

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$DMOD

Remainder from Division of Two D-floating
Parameters Routine
Format:

MTH$DMOD dividend, divisor

Returns:

floating_point, D_floating, write only, by value

dividend:

floating_point, D_floating, read only, by reference

divisor:

fl.oating_point, D_floating, read only, by reference

Remainder from Division of Two G-floating
Parameters Routine

MTH$GMOD

Format:

MTH$GMOD dividend, divisor

Returns:

floating_point, G_floating, write only, by value

dividend:

floating_point, G_floating, read only, by reference

divisor:

floating_point, G_floating, read only, by reference

Remainder from Division of Two H-floating
Parameters Routine

MTH$HMOD

Format:

MTH$HMOD h-mod, dividend, divisor

Returns:

None

h-mod:

floating_point, H_floating, write only, by
reference

dividend:

floating_point, H_floating, read only, by
reference

divisor:

fl.oating_point, H_fl.oating, read only, by
reference

Remainder from Division of Two Word
Parameters Routine

MTH$IMOD

Format:

MTH$IMOD dividend, divisor

Returns:

word_signed, word (signed), write only, by value

dividend:

word_signed, word (signed), read only, by
reference

divisor:

word_signed, word (signed), read only, by
reference

Remainder of Two Longword Parameters Routine

MTH$JMOD

Format:

MTH$JMOD dividend, divisor

Returns:

longword_signed, longword (signed), write only,
by value

dividend:

longword_signed, longword (signed), read only,
by reference

divisor:

longword_signed, longword (signed), read only,
by reference
(continued on next page)

A-13

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$ANINT

Convert F-floating to Nearest F-floating Integer
Routine
Format:

MTH$ANINT f-floating

Returns:

floating_point, F _floating, write only, by value

f-floating:

floating_point, F _floating, read only, by reference

MTH$DNINT

Convert D-floating to Nearest D-floating Integer
Routine
Format:

MTH$DNINT cl-floating

Returns:

floating_point, D_floating, write only, by value

d-floating:

floating_point, D_floating, read only, by reference

Convert D-floating to Nearest Word Integer
Routine

MTH$IIDNNT

Format:

MTH$IIDNNT cl-floating

Returns:

word_signed, word (signed), write only, by value

d-floating:

floating_point, D_floating, read only, by reference

Convert D-floating to Nearest Longword Integer
Routine

MTH$JIDNNT

Format:

MTH$JIDNNT cl-floating

Returns:

longword_signed, longword (signed), write only,
by value

d-floating:

floating_point, D_floating, read only, by reference

MTH$GNINT

Convert G-floating to Nearest G-floating Integer
Routine
Format:

MTH$GNINT g-floating

Returns:

floating_point, G_floating, write only, by value

g-floating:

floating_point, G_floating, read only, by reference

MTH$IIGNNT

Convert G-floating to Nearest Word Integer
Routine
Format:

MTH$IIGNNT g-floating

Returns:

word_signed, word (signed), write only, by value

g-floating:

floating_point, G_floating, read only, by reference
(continued on next page)

A-14

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$JIGNNT

Convert G-floating to Nearest Longword Integer
Routine
Format:

MTH$JIGNNT g-floating

Returns:

longword_signed, longword (signed), write only,
by value

g-fl.oating:

floating_point, G_floating, read only, by reference

Convert H-floating to Nearest H-floating Integer
Routine

MTH$HNINT
Format:

MTH$HNINT nearst-h-flt, h-floating

Returns:

None

nearst-h-flt:

floating_point, H_floating, write only, by
reference

h-floating:

floating_point, H_floating, read only, by
reference

Convert H-floating to Nearest Word Integer
Routine

MTH$IIHNNT
Format:

MTH$IIHNNT h-floating

Returns:

word_signed, word (signed), write only, by value

h-fl.oating:

floating_point, H_floating, read only, by
reference

Convert H-floating to Nearest Longword Integer
Routine

MTH$JIHNNT
Format:

MTH$JIHNNT h-floating

Returns:

longword_signed, longword (signed), write only,
by value

h-floating:

floating_point, H_floating, read only, by
reference

Convert F-floating to Nearest Word Integer
Routine

MTH$ININT
Format:

MTH$ININT f-floating

Returns:

word_signed, word (signed), write only, by value

f-fl.oating:

floating_point, F _floating, read only, by reference

MTH$JNINT

Convert F-floating to Nearest Longword Integer
Routine
Format:

MTH$JNINT f-floating

Returns:

longword_signed, longword (signed), write only,
by value

f-floating:

floating_point, F _floating, read only, by reference
(continued on next page)

A-15

Additional MTH$ Routines

Table A-1 {Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$INOT

Bitwise Complement of Word Parameter Routine
Format:

MTH$INOT word

Returns:

word_unsigned, word (unsigned), write only, by
value

word:

word_unsigned, word (unsigned), read only, by
reference

Bitwise Complement of Longword Parameter
Routine

MTH$JNOT
Format:

MTH$JNOT longword

Returns:

longword_unsigned, longword (unsigned), write
only, by value

longword:

longword_unsigned, longword (unsigned), read
only, by reference

D-fioating Product of Two F-fioating Parameters
Routine

MTH$DPROD
Format:

MTH$DPROD f-floatingl, f-floating2

Returns:

floating_point, D_floating, write only, by value

f-floatingl:

floating_point, F _floating, read only, by reference

f-floating2:

floating_point, F _floating, read only, by reference

G-fioating Product of Two F-fioating Parameters
Routine

MTH$GPROD
Format:

MTH$GPROD f-floatingl, f-floating2

Returns:

floating_point, G_floating, write only, by value

f-floatingl:

floating_point, F _floating, read only, by reference

f-floating2:

floating_point, F _floating, read only, by reference

F-fioating Sign Function

MTH$SGN
Format:

MTH$SGN f-floating

Returns:

longword_signed, longword (signed), write only,
by reference

f-floating:

floating_point, F _floating, read only, by reference

D-fioating Sign Function

MTH$SGN
Format:

MTH$SGN cl-floating

Returns:

longword_signed, longword (signed), write only,
by reference

d-floating:

floating_point, D_floating, read only, by reference
(continued on next page)

A-16

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$IISHFT

Bitwise Shift of Word Routine
Format:

MTH$IISHFT word, shift-cnt

Returns:

word_unsigned, word (unsigned), write only, by
value

word:

word_unsigned, word (unsigned), read only, by
reference

shift-cnt:

word_signed, word (signed), read only, by
reference

MTH$JISHFT

Bitwise Shift of Longword Routine
Format:

MTH$JISHFT longword, shift-cnt

Returns:

longword_unsigned, longword (unsigned), write
only, by value

longword:

longword_unsigned, longword (unsigned), read
only, by reference

shift-cnt:

longword_signed, longword (signed), read only,
by reference

MTH$SIGN

F-floating Transfer of Sign of Y to Sign of X
Routine
Format:

MTH$SIGN f-float-x, f-float-y

Returns:

floating_point, F _floating, write only, by value

f-float-x:

floating_point, F _floating, read only, by reference

f-float-y:

floating_point, F _floating, read only, by reference

MTH$DSIGN

D-floating Transfer of Sign of Y to Sign of X
Routine
Format:

MTH$DSIGN d-float-x, d-float-y

Returns:

floating_point, D_floating, write only, by value

d-float-x:

floating_point, D_floating, read only, by reference

d-float-y:

floating_point, D_floating, read only, by reference

MTH$GSIGN

G-floating Transfer of Sign of Y to Sign of X
Routine
Format:

MTH$GSIGN g-float-x, g-float-y

Returns:

floating_point, G_floating, write only, by value

g-float-x:

floating_point, G_floating, read only, by reference

g-float-y:

floating_point, G_floating, read only, by reference
(continued on next page)

A-17

Additional MTH$ Routines

Table A-1 (Cont.) Additional MTH$ Routines
Routine Name

Entry Point Information

MTH$HSIGN

H-fioating Transfer of Sign of Y to Sign of X
Routine
Format:

MTH$HSIGN h-result, h-float-x, h-float-y

Returns:

None

h-result:

floating_point, H_floating, write only, by
reference

h-float-x:

floating_point, H_floating, read only, by
reference

h-float-y:

floating_point, H_floating, read only, by
reference

Format:

MTH$IISIGN word-x, word-y

Returns:

word_signed, word (signed), write only, by value

word-x:

word_signed, word (signed), read only, by
reference

word-y:

word_signed, word (signed), read only, by
reference

Word Transfer of Sign of Y to Sign of X Routine

MTH$IISIGN

Longword Transfer of Sign of Y to Sign of X
Routine

MTH$JISIGN
Format:

MTH$JISIGN longwrd-x, longwrd-y

Returns:

longword_signed, longword (signed), write only,
by reference

longwrd-x:

longword_signed, longword (signed), read only,
by reference

longwrd-y:

longword_signed, longword (signed), read only,
by reference

Convert D-fioating to F-fioating (Rounded)
Routine

MTH$SNGL
Format:

MTH$SNGL cl-floating

Returns:

floating_point, F _floating, write only, by value

d-floating:

floating_point, D_floating, read only, by reference

Convert G-fioating to F-fioating (Rounded)
Routine

MTH$SNGLG

A-18

Format:

MTH$SNGLG g-floating

Returns:

floating_point, F _floating, write only, by value

g-floating:

floating_point, G_floating, read only, by reference

B
Vector MTH$ Routine Entry Points
Table B-1 contains all of the vector MTH$ routines that you can call from
VAX MACRO. Be sure to read Section 2.3.3 and Section 2.3.4 before using the
information in this table.
Table B-1

Vector MTH$ Routines

Scalar
Name

Call
or
JSB

Vector Input
Registers

Vector
Output
Registers

Vector Name
(Underflows Not Signaled)

AINT

JSB

MTH$VAINT_RO_Vl

DINT

JSB

MTH$VDINT_R3_V3

GINT

JSB

MTH$VGINT_R3_V3

DPROD

Call

VO,Vl

MTH$VVDPROD_Rl_Vl

GPROD

Call

VO,Vl

MTH$VVGPROD_Rl_Vl

ACOS

JSB

MTH$VACOS_R6_V7

DACOS

JSB

MTH$VDACOS_R2_V7

GACOS

JSB

MTH$VGACOS_R2_V7

ACOSD

JSB

MTH$VACOSD_R6_v7

DACOSD

JSB

MTH$VDACOSD_R2_V7

GACOSD

JSB

MTH$VGACOS_R2_V7

ASIN

JSB

MTH$VASIN_R2_V6

DAS IN

JSB

MTH$VDASIN_R2_V6

GAS IN

JSB

MTH$VGASIN_R2_V6

AS IND

JSB

MTH$VASIND_R2_V6

DAS IND

JSB

MTH$VDASIND_R2_V6

GAS IND

JSB

MTH$VGASIND_R2_V6

ATAN

JSB

MTH$VATAN_RO_V4

DATAN

JSB

MTH$VDATAN_RO_V6

GATAN

JSB

MTH$VGATAN_RO_V6

ATAND

JSB

MTH$VATAND_RO_V4

DATAND

JSB

MTH$VDATAND_RO_V6

GATAND

JSB

MTH$VGATAND_RO_V6

ATAN2

JSB

VO,Vl

MTH$VVATAN2_R4_V7

DATAN2

JSB

VO,Vl

MTH$VVDATAN2_R4_V9

Vector Name
(Underflows Signaled)

(continued on next page)

Vector MTH$ Routine Entry Points

Table 8-1 (Cont.) Vector MTH$ Routines
Scalar
Name

Call
or
JSB

Vector Input
Registers

Vector
Output
Registers

Vector Name
(Underflows Not Signaled)

GATAN2

JSB

VO,Vl

MTH$VVGATAN2_R4_V9

ATAND2

JSB

VO,Vl

MTH$VVATAND2_R4_V7

DATAND2

JSB

VO,Vl

MTH$VVDATAND2_R4_V9

GATAND2

JSB

VO,Vl

MTH$VVGATAND2_R4_V9

CABS

Call

VO,Vl

MTH$VCABS_Rl_V5

CD ABS

Call

VO,Vl

MTH$VCDABS_Rl_v6

CGABS

Call

VO,Vl

MTH$VCGABS_Rl_v6

ccos

Call

VO,Vl

MTH$VCCOS_Rl_Vll

CDCOS

Call

VO,Vl

MTH$VCDCOS_Rl_Vll

CGCOS

Call

VO,Vl

MTH$VCGCOS_Rl_Vll

cos

JSB

MTH$VCOS_R4_v7

DCOS

JSB

MTH$VDCOS_R4_VS

GCOS

JSB

MTH$VGCOS_R4_VS

COSD

JSB

MTH$VCOSD_R4_v6

DCOSD

JSB

MTH$VDCOSD_R4_v6

Vector Name
(Underflows Signaled)

GCOSD

JSB

MTH$VGCOSD_R4_v6

CEXP

Call

VO,Vl

MTH$VCEXP_Rl_VS

CD EXP

Call

VO,Vl

MTH$VCDEXP_Rl_VlO

CGEXP

Call

VO,Vl

MTH$VCGEXP_Rl_VlO

CLOG

Call

VO,Vl

MTH$VCLOG_Rl_VS

CDLOG

Call

VO,Vl

MTH$VCDLOG_Rl_V10

CGLOG

Call

VO,Vl

MTH$VCGLOG_Rl_V10

AMOD

JSB

VO,RO

MTH$VAMOD_R4_V5

MTH$VAMOD_E_R4_V5

DMOD

JSB

VO,RO

MTH$VDMOD_R7_v6

MTH$VDMOD_E_R7_V6

GMOD

JSB

VO,RO

MTH$VGMOD_R7_v6

MTH$VGMOD_E_R7 _V6

CSIN

Call

VO,Vl

MTH$VCSIN_Rl_Vll

CDS IN

Call

VO,Vl

MTH$VCDSIN_Rl_Vll

CGSIN

Call

VO,Vl

MTH$VCGSIN_Rl_Vll

CSQRT

Call

VO,Vl

MTH$VCSQRT_Rl_V7

CD SQRT

Call

VO,Vl

MTH$VCDSQRT_Rl_VS

CGSQRT

Call

VO,Vl

MTH$VCGSQRT_Rl_VS

COSH

JSB

MTH$VCOSH_R5_VS

DCOSH

JSB

MTH$VDCOSH_R5_VS

GCOSH

JSB

MTH$VGCOSH_R5_V8

EXP

JSB

MTH$VEXP_R3_v6

MTH$VEXP_E_R3_v6

DEXP

JSB

MTH$VDEXP_R3_v6

MTH$VDEXP_E_R3_v6

(continued on next page)

B-2

Vector MTH$ Routine Entry Points

Table 8-1 (Cont.) Vector MTH$ Routines
Scalar
Name

Call
or
JSB

Vector Input
Registers

Vector
Output
Registers

Vector Name
(Underflows Not Signaled)

Vector Name
(Underflows Signaled)

MTH$VGEXP_E_R3_V6

GEXP

JSB

MTH$VGEXP_R3_V6

ALOG

JSB

MTH$VALOG_R3_V5

DLOG

JSB

MTH$VDLOG_R3_V7

GLOG

JSB

MTH$VGLOG_R3_V7

ALOGlO

JSB

MTH$VALOG 10_R3_V5

DLOGlO

JSB

MTH$VDLOG 10_R3_V7

GLOGlO

JSB

MTH$VGLOG 10_R3_V7

ALOG2

JSB

MTH$VALOG2_R3_V5

DLOG2

JSB

MTH$VDLOG2_R3_V7

GLOG2

JSB

MTH$VGLOG2_R3_V7

RANDOM

JSB

MTH$VRANDOM_R2_VO

SIN

JSB

MTH$VSIN_R4_V6

DSIN

JSB

MTH$VDSIN_R4_V8

GSIN

JSB

MTH$VGSIN_R4_V8

SIND

JSB

MTH$VSIND_R4_V6

MTH$VSIND_E_R6_V6
MTH$VDSIND_E_R6_V6
MTH$VGSIND_E_R6_V6

DSIND

JSB

MTH$VDSIND_R4_V6

GS IND

JSB

MTH$VGSIND_R4_V6

SINCOS

JSB

VO,Vl

MTH$VSINCOS_R4_v7

DSINCOS

JSB

VO,Vl

MTH$VDSINCOS_R4_V8

GSINCOS

JSB

VO,Vl

MTH$VGSINCOS_R4_V8

SINCOSD

JSB

VO,Vl

MTH$VSINCOSD_R4_V6

MTH$VSINCOSD_E_R6_V6

DSINCOSD

JSB

VO,Vl

MTH$VDSINCOSD_R4_V7

MTH$VDSINCOSD_E_R6_V7

GSINCOSD

JSB

VO,Vl

MTH$VGSINCOSD_R4_V7

MTH$VGSINCOSD_E_R6_V7

SINH

JSB

MTH$VSINH_R5_v9

DSINH

JSB

MTH$VDSINH_R5_V9

GSINH

JSB

MTH$VGSINH_R5_V9

SQRT

JSB

MTH$VSQRT_R2_V4

DSQRT

JSB

MTH$VDSQRT_R2_V5

GSQRT

JSB

MTH$VGSQRT_R2_V5

TAN

JSB

MTH$VTAN_R4_V5

DTAN

JSB

MTH$VDTAN_R4_V5

GTAN

JSB

MTH$VGTAN_R4_V5

TAND

JSB

MTH$VTAND_R4_V5

MTH$VTAND_E_R4_V5

DTAND

JSB

MTH$VDTAND_R4_V5

MTH$VDTAND_E_R4_V5

GTAND

JSB

MTH$VGTAND_R4_V5

MTH$VGTAND_E_R4_V5

TANH

JSB

MTH$VTANH_R3_VlO

(continued on next page)

Vector MTH$ Routine Entry Points

Table 8-1 (Cont.) Vector MTH$ Routines
Scalar
Name

Call
or
JSB

Vector Input
Registers

Vector
Output
Registers

Vector Name
(Underflows Not Signaled)

DTANH

JSB

MTH$VDTANH_R3_V10

Vector Name
(Underflows Signaled)

GTANH

JSB

MTH$VGTANH_R3_VlO

DIVC

Call

VO,Vl,V2,V3

VO,Vl

OTS$VVDIVC_Rl_V6

DIVCD

Call

VO,Vl,V2,V3

VO,Vl

OTS$VVDIVCD_R1_v7

DIVCG

Call

VO,Vl,V2,V3

VO,Vl

OTS$VVDIVCG_Rl_V7

MULC

Call

VO,Vl,V2,V3

VO,Vl

OTS$VVMULC_Rl_V4

MULCD

Call

VO,Vl,V2,V3

VO,Vl

OTS$VVMULCD_Rl_V4

MULCG

Call

VO,Vl,V2,V3

VO,Vl

OTS$VVMULCG_Rl_V4

POWJJ

Call

VO,RO

OTS$VPOWJJ_Rl_Vl

POWRJ

Call

VO,RO

OTS$VPOWRJ_Rl_V2

OTS$VPOWRJ_E_Rl_V2

POWDJ

Call

VO,RO

OTS$VPOWDJ_Rl_V2

OTS$VPOWDJ_E_R1_v2

POWGJ

Call

VO,RO

OTS$VPOWGJ_Rl_V2

OTS$VPOWGJ_E_Rl_V2

POWRR

Call

VO,RO

OTS$VPOWRR_Rl_V4

OTS$VPOWRR_E_Rl_V 4

POWDD

Call

VO,RO

OTS$VPOWDD_Rl_V8

OTS$VPOWDD_E_Rl_V8

POWGG

Call

VO,RO

OTS$VPOWGG_Rl_V9

OTS$VPOWGG_E_Rl_V9

R--LI

Index
A

Absolute value, 1-4
· of complex number, MTH-23
Additional routines
list of, 1-4 to 1-9
Algorithm, 1-3
Arc cosine
in degrees, MTH-6, MTH-70
in radians, MTH-3, MTH-68
Arc sine
in degrees, MTH-11, MTH-74
in radians, MTH-9, MTH-72
Arc tangent
hyperbolic, MTH-21, MTH-84
in degrees, MTH-15, MTH-19, MTH-78,
MTH-82
in radians, MTH-13, MTH-17, MTH-76,
MTH-80
Arrays
conversion of, MTH-63

Calling convention, 1-2
Complex numbers, 1-3, MTH-56, MTH-58,
MTH-111, MTH-121
absolute value of, MTH-23
complex exponential of, MTH-30, MTH-32
conjugate of, MTH-43, MTH-44
cosine of, MTH-26, MTH-28
made from floating-point, MTH-39, MTH-41
natural logarithm of, MTH-34, MTH-36
sine of, MTH-52, MTH-53
Condition handling, 1-3
Conjugate of complex number, MTH-43, MTH-44
Conversion of double to single floating-point value,
1-9
Conversion to greatest floating-point integer, 1-5
Copying
vector, MTH-160
Cosind
in radians, MTH-125
Cosine
hyperbolic, MTH-50, MTH-88
in degrees, MTH-48, MTH-87, MTH-128
in radians, MTH-46, MTH-86
of complex number, MTH-26, MTH-28

8
Backward indexing, 2-6
Bitwise AND operator, 1-4
Bitwise complement operator, 1-8
Bitwise exclusive OR operator, 1-5
Bitwise inclusive OR operator, 1-6
Bitwise shift, 1-8
BLAS
definition of, 2-1
BLAS Level 1
BLAS1$VlxAMAX, MTH-149
BLAS1$VxASUM, MTH-152
BLAS1$VxAXPY, MTH-155
BLAS1$VxCOPY, MTH-160
BLAS1$VxDOT, MTH-165
BLAS1$VxNRM2, MTH-170
BLAS1$VxROT, MTH-173
BLAS1$VxROTG, MTH-178
BLAS1$VxSCAL, MTH-182
BLAS1$VxSWAP, MTH-186

D
Double-precision value
converting, MTH-61
converting an array of, MTH-63

E
Entry point name, 1-1
Error checking
in FOLR routines, 2-6
Euclidean norm
of a vector, MTH-170
Exceptions
recovering from, 2-7
Exponential, MTH-65, MTH-90
of complex number, MTH-30, MTH-32

F-floating conversion, 1-4
First Order Linear Recurrence, MTH-190,
MTH-194, MTH-198, MTH-202
Floating-point
conversion to nearest value, 1-7
multiplication, 1-8
positive difference, 1-5
sign function, 1-8
FOLR
definition of, 2-6
FOLR routines, MTH-190, MTH-194, MTH-198,
MTH-202
error checking, 2-6
naming conventions, 2-6
FORTRAN
/BLAS qualifier, 2-2
Forward indexing, 2-6

Mathematics routine
additional routines, A-1 to A-18
Maximum value, 1-6
Minimum value, 1-7
MTH$ACOS, MTH-3
MTH$ACOSD, MTH-6
MTH$AIMAG, MTH-111
MTH$ALOG, MTH-113
MTH$ALOG10, MTH-117
MTH$ALOG2, MTH-115
MTH$ASIN, MTH-9
MTH$ASIND, MTH-11
MTH$ATAN, MTH-13
MTH$ATAN2, MTH-17
MTH$ATAND, MTH-15
MTH$ATAND2, MTH-19
MTH$ATANH, MTH-21
MTH$CABS, MTH-23
MTH$CCOS, MTH-26
MTH$CDABS, MTH-23
MTH$CDCOS, MTH-28
MTH$CDEXP, MTH-32
MTH$CDLOG, MTH-36
MTH$CDSIN, MTH-53
MTH$CDSQRT, MTH-58
MTH$CEXP, MTH-30
MTH$CGABS, MTH-23
MTH$CGCOS, MTH-28
MTH$CGEXP, MTH-32
MTH$CGLOG, MTH-36
MTH$CGSIN, MTH-53
MTH$CGSQRT, MTH-58
MTH$CLOG, MTH-34
MTH$CMPLX, MTH-39
MTH$CONJG, MTH-43
MTH$COS, MTH-46
MTH$COSD, MTH-48
MTH$COSH, MTH-50
MTH$CSIN, MTH-52
MTH$CSQRT, MTH-56
MTH$CVT_DA_GA, MTH-63
MTH$CVT_D_G, MTH-61
MTH$CVT_GA_DA, MTH-63
MTH$CVT_G_D, MTH-61
MTH$DACOS, MTH-3
MTH$DACOSD, MTH-6
MTH$DASIN, MTH-9
MTH$DASIND, MTH-11
MTH$DATAN, MTH-13
MTH$DATAN2, MTH-17
MTH$DATAND, MTH-15
MTH$DATAND2, MTH-19
MTH$DATANH, MTH-21

G
Givens plane rotation
applying to a vector, MTH-173
generating the elements for, MTH-178

H
Hyperbolic arc tangent, MTH-21, MTH-84
Hyperbolic cosine, MTH-50, MTH-88
Hyperbolic sine, MTH-101, MTH-133
Hyperbolic tangent, MTH-109, MTH-142

Index
of a vector, MTH-149
Indexing
backward, 2-6
forward, 2-6
Inner product
of a vector, MTH-165
Integer to floating-point conversion, 1-5

J
JSB entry point, 1-2

L
Linear recurrence
definition of, 2-6
Logarithm
base 2, MTH-94, MTH-115
common, MTH-96, MTH-117
natural, MTH-92, MTH-113
natural complex, MTH-34, MTH-36

...... _..,

__ ~

MTH$DCMPLX, MTH--41
MTH$DCONJG, MTH-44
MTH$DCOS, MTH-46
MTH$DCOSD, MTH-48
MTH$DCOSH, MTH-50
MTH$DEXP, MTH-65
MTH$DIMAG, MTH-111
MTH$DLOG, MTH-113
MTH$DLOG10, MTH-117
MTH$DLOG2, MTH-115
MTH$DREAL, MTH-121
MTH$DSIN, MTH-123
MTH$DSINCOS, MTH-125
MTH$DSINCOSD, MTH-128
MTH$DSIND, MTH-131
MTH$DSINH, MTH-133
MTH$DSQRT, MTH-136
MTH$DTAN, MTH-138
MTH$DTAND, MTH-140
MTH$DTANH, MTH-142
MTH$EXP, MTH-65
MTH$GACOS, MTH-3
MTH$GACOSD, MTH-6
MTH$GASIN, MTH-9
MTH$GASIND, MTH-11
MTH$GATAN, MTH-13
MTH$GATAN2, MTH-17
MTH$GATAND, MTH-15
MTH$GATAND2, MTH-19
MTH$GATANH, MTH-21
MTH$GCMPLX, MTH-41
MTH$GCONJG, MTH-44
MTH$GCOS, MTH-46
MTH$GCOSD, MTH-48
MTH$GCOSH, MTH-50
MTH$GEXP, MTH-65
MTH$GIMAG, MTH-111
MTH$GLOG, MTH-113
MTH$GLOG10, MTH-117
MTH$GLOG2, MTH-115
MTH$GREAL, MTH-121
MTH$GSIN, MTH-123
MTH$GSINCOS, MTH-125
MTH$GSINCOSD, MTH-128
MTH$GSIND, MTH-131
MTH$GSINH, MTH-133
MTH$GSQRT, MTH-136
MTH$GTAN, MTH-138
MTH$GTAND, MTH-140
MTH$GTANH, MTH-142
MTH$HACOS, MTH-68
MTH$HACOSD, MTH-70
MTH$HASIN, MTH-72
MTH$HASIND, MTH-74
MTH$HATAN, MTH-76
MTH$HATAN2, MTH-80

MTH$HATAND, MTH-78
MTH$HATAND2, MTH-82
MTH$HATANH, MTH-84
MTH$HCOS, MTH-86
MTH$HCOSD, MTH-87
MTH$HCOSH, MTH-88
MTH$HEXP, MTH-90
MTH$HLOG, MTH-92
MTH$HLOG 10, MTH-96
MTH$HLOG2, MTH-94
MTH$HSIN, MTH-98
MTH$HSINCOS, MTH-125
MTH$HSINCOSD, MTH-128
MTH$HSIND, MTH-99
MTH$HSINH, MTH-101
MTH$HSQRT, MTH-103
MTH$HTAN, MTH-105
MTH$HTAND, MTH-107
MTH$HTANH, MTH-109
MTH$RANDOM, MTH-119
MTH$REAL, MTH-121
MTH$SIN, MTH-123
MTH$SINCOS, MTH-125
MTH$SINCOSD, MTH-128
MTH$SIND, MTH-131
MTH$SINH, MTH-133
MTH$SQRT, MTH-136
MTH$TAN, MTH-138
MTH$TAND, MTH-140
MTH$TANH, MTH-142
MTH$UMAX, MTH-144
MTH$UMIN, MTH-145
MTH$VxFOLRLy_MA_V5, MTH-198
MTH$VxFOLRLy_z_V2, MTH-202
MTH$VxFOLRy_MA_V15, MTH-190
MTH$VxFOLRy_z_V8, MTH-194
Multiplying
vector, MTH-155

N
Naming conventions
FOLR routines, 2-6
vector routines, 2-8
Norm
Euclidean
of a vector, MTH-170

0
Overflow detection, 2-8

lndex-3

p
Plane rotation
applying Givens plane rotation to a vector,
MTH-173
generating the elements for a Givens plane
rotation, MTH-178
Product
of a vector, MTH-165

R
Random number generator, MTH-119
Recurrence
linear
definition of, 2-6
Remainder, 1-7
Rotation
applying to a vector, MTH-173

s
Scaling
vector, MTH-182
Sine
hyperbolic, MTH-101, MTH-133
in degrees, MTH-99, MTH-128, MTH-131
in radians, MTH-98, MTH-123, MTH-125
of complex number, MTH-52, MTH-53
Square root, MTH-103, MTH-136
Sum of absolute values
of a vector, MTH-152
Swapping
vector, MTH-186

T
Tangent, MTH-105, MTH-107, MTH-138,
MTH-140
hyperbolic, MTH-109, MTH-142
Truncation of floating-point value, 1-6

u
Underflow detection, 2-8

v
VAX FORTRAN
/BLAS qualifier, 2-2
VAX FORTRAN-RPO compiler, 2-2, 2-9
Vectorization of a loop
preventing, MTH-190, MTH-194, MTH-198,
MTH-202
Vectorizing FORTRAN compiler, 2-7

lndex-4

Vector routines
table of entry points, B-1 to B-4
Vectors
applying Givens plane rotation, MTH-173
copying, MTH-160
generating the elements for a Givens plane
rotation, MTH-178
multiplying, MTH-155
obtaining
the Euclidean norm of, MTH-170
the index of, MTH-149
the inner product of, MTH-165
the sum of the absolute values of,
MTH-152
scaling, MTH-182
swapping, MTH-186

NOTES

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825)
and press 2 for technical assistance.

Electronic Orders
If you wish to place an order through your account at the Electronic Store, dial 800-234-1998, using a
modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8. bits, no
parity. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for an
Electronic Store specialist.

Telephone and Direct Mail Orders
From

Call

Write

U.S.A.

DEC direct
Phone: 800-DIGITAL
(800-344-4825)
FAX: (603) 884-5597

Digital Equipment Corporation
P.O. Box CS2008
Nashua, NH 03061

Puerto Rico

Phone: (809) 781-0505
FAX: (809) 749-8377

Digital Equipment Caribbean, Inc.
3 Digital Plaza, 1st Street
Suite 200
Metro Office Park
San Juan, Puerto Rico 00920

Canada·

. Phone: 800-267-6215
FAX: (613) 592-1946

Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: DECdirect Sales

International

Local Digital subsidiary or
approved distributor

Internal Orders 1
(for software
documentation)

DTN: 241-3023
(508) 87 4-3023

Software Supply Business (SSB)
Digital Equipment Corporation
1 Digital Drive
Westminster, MA 01473

Internal Orders
(for hardware
documentation)

DTN: 234-4325
(508) 351-4325
FAX: (508) 351-4467

Publishing & Circulation Services
Digital Equipment Corporation
NR02-2
444 Whitney Street
Northboro, MA 01532

1 Call to request an Internal Software Order Form (EN-01740-07).

Reader's Comments

OpenVMS VAX RTL
Mathematics (MTH$) Manual

AA-PVXJA-TE

Your comments and suggestions help us improve the quality of our publications.
Thank you for your assistance.

I rate this manual's:
Accuracy (product works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

D
D
D
D
D
D
D
D

D
D

D
D
D
D
D
D

I would like to see more/less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

For software manuals, please indicate which version of the software you are using:

Name/Title

Dept.

Company

Date

Mailing Address
Phone

Poor

Do Not Tear - Fold Here and Tape
No Postage
Necessary
if Mailed
in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
OpenVMS Documentation
110 SPIT BROOK ROAD ZK03-4/U08
NASHUA, NH 03062-2642

lll11111ll1ll1111ll1111l1l11l1l1ll111l11l11l1l1l1l1I
Do Not Tear- Fold Here - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -