DIGITAL Portable Mathematics Library

Document revision date: 19 July 1999

Order Number: AA-PV6VD-TE

January 1999

This document provides reference and exception information for DPML, the DIGITAL^tm Portable Mathematics Library software.

Revision/Update Information: The content of this document has not changed since OpenVMS Version 7.1.

Compaq Computer Corporation Houston, Texas

Reprinted January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DECdirect, DIGITAL, OpenVMS, OpenVMS Cluster, VAX, VAX DOCUMENT, VAXcluster, VMS, VMScluster, and the Compaq logo.

The following are third-party trademarks:

Adobe, Adobe Illustrator, Display POSTSCRIPT, and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.

CRAY is a registered trademark of Cray Research, Inc.

IBM is a registered trademark of International Business Machines Corporation.

IEEE is a registered trademark of the Institute of Electrical and Electronics Engineers Inc.

ITC Avant Garde Gothic is a registered trademark of International Typeface Corporation.

Microsoft, MS, and MS-DOS are registered trademarks of Microsoft Corporation.

Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are trademarks of the Open Software Foundation, Inc.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6118

The OpenVMS and DIGITAL UNIX documentation sets are available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

Audience

This manual is for compiler writers, system programmers, and application programmers who do not have high-level language support of DIGITAL Portable Mathematics Library (DPML) routines in their language of choice. This audience needs to access DPML routines directly from their application programs.

Document Organization

This manual consists of the following:

Chapter 1 gives a general overview of the mathematics library and discusses supported data types, exception behavior, and IEEE considerations.

Chapter 2 explains the presentation format of a DPML routine and how to interpret a routine's interface, and alphabetically lists the routines.

Appendix A lists the floating-point boundary values used by the DPML routines.

Appendix B contains the complete list of entry-point names.

The Glossary lists mathematical terms and symbolic names used in this manual, and provides a brief definition.

Audience	Icon	Color Code
General users	G	Blue
System and network administrators	S	Red
Programmers	P	Purple
Device driver writers	D	Orange
Reference page users	R	Green

Reader's Comments

Compaq welcomes your comments on this manual. A Reader's Comments form is located online in the following location:

UNIX /usr/doc/readers_comment.txt

OpenVMS SYS$HELP:OPENVMSDOC_COMMENTS.TXT

Print or edit the online form and send us your comments by one of the following methods:

Internet dpml@digital.com

Fax (603) 884-0120, Attention: Math Run Time Library Documentation, ZKO2-3/Q18

Mail Compaq Computer Corporation
Math Run Time Library Documentation, ZKO2-3/Q18
110 Spit Brook Rd.
Nashua, NH 03062-2698
USA

Please include the following information along with your comments:

The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)
The section numbers and page numbers of the information on which you are commenting.
The operating system and version of Compaq software that you are using. For example, DIGITAL UNIX Version 4.0, or OpenVMS Version 7.1.
If known, the type of processor that is running the Compaq software. For example, AlphaServer 2000.

Compaq publications groups cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Compaq technical support office. Information provided with the software media explains how to send problem reports to Compaq.

How To Order Additional Documentation

Additional documentation for your operating system is available by contacting Compaq. For help in ordering or in deciding which documentation best meets your needs, call 800-344-4825.

For OpenVMS, you can also use the following World Wide Web address to order documentation:

http://www.openvms.digital.com:81/

Conventions

In this book, every use of OpenVMS means Compaq's OpenVMS operating system, and every use of UNIX or DIGITAL UNIX means Compaq's Tru64 UNIX operating system.

The following conventions are used in this manual:

Ctrl/ x 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.

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

[Return] 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 command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.

[ ] In command 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 command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text
Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

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

Chapter 1
Introduction to DPML

The DIGITAL Portable Mathematics Library (referred to as DPML) includes a wide variety of mathematical routines that cover the following areas:

Floating-point trigonometric function evaluation
Exponentiation, logarithmic, power function evaluation
Hyperbolic function evaluation
Algebraic function evaluation
Complex function evaluation
Complex exponentiation
Miscellaneous function evaluation

This manual documents the DPML routines and, in particular, how they behave when given an exceptional input argument. It also documents operating system entry points and supported floating-point data types.

1.1 Overview

Developing software within the confines of high-level languages like Fortran and C greatly increases the portability and maintainability of your source code. Many high-level languages support mathematical function evaluation. DPML was developed to provide a common set of routines that support many of the common mathematical functions across a wide variety of operating systems, hardware architectures, and languages.

In most cases, the common mathematical functions behave the same way for all languages and platforms. Occasionally, however, high-level language definitions of the same mathematical function will differ for specific input values. For example, in Fortran, log(-1.0) causes a program abort, while in C, log(-1.0) quietly returns a system-defined value.

This document uses the term exceptional arguments to refer to values in the following situations:

Values for which high-level languages disagree on the function behavior.
Values that are mathematically undefined or out of range.
Values for which the function would overflow or underflow.

See Section 1.3 for more detail on exceptional arguments.

To provide uniform quality of mathematical functions for all languages on your system, DPML traps exceptional arguments and invokes a system-specific routine called the DPML exception handler. The exception handler is designed to work in conjunction with high-level language compilers and run-time libraries (RTLs) to provide specific language semantics for exceptional arguments. This means that the user-visible behavior of a given function called from a given language is not necessarily determined by the routines in the DPML library but rather by a combination of several entities acting in concert.

Note

Compaq strongly recommends that you limit your access to the DPML routines documented in this manual to the high-level language syntax of your choice, thereby guaranteeing the behavior of the routines across platforms. Because of the complex relationship between high-level languages and DPML routines, the behavior of direct calls to DPML routines may change from release to release.

1.2 Data Types

DPML is designed to support mathematics function evaluation for multiple data types. These data types include integer, floating-point, and complex floating-point.

The integer data type, identified as int throughout this manual, is the natural size signed integer for a particular platform. On a 32-bit system, int is a 32-bit signed integer, and on a 64-bit system, int is a 64-bit signed integer.

The floating-point types referred to in this document are F_FLOAT, G_FLOAT, X_FLOAT, S_FLOAT, and T_FLOAT respectively. When it is not necessary to distinguish between the different floating types, they are referred to collectively as F_TYPE. Your platform may support all or a subset of these floating-point data types. For example, DPML on OpenVMS Alpha systems supports the following floating-point data types: VAX single- and double-precision, IEEE single- and double-precision, and IEEE extended-precision. DPML on DIGITAL UNIX Alpha systems supports only IEEE single- and double-precision data types. Table 1-1 describes the floating-point data types.

Table 1-1 Floating-Point Data Types
F_TYPE Description

S_FLOAT 32-bit IEEE single-precision number

T_FLOAT 64-bit IEEE double-precision number

X_FLOAT 128-bit IEEE extended-precision number

F_FLOAT 32-bit VAX single-precision number

G_FLOAT 64-bit VAX double-precision number

**Table 1-1 Floating-Point Data Types**
F_TYPE	Description
S_FLOAT	32-bit IEEE single-precision number
T_FLOAT	64-bit IEEE double-precision number
X_FLOAT	128-bit IEEE extended-precision number
F_FLOAT	32-bit VAX single-precision number
G_FLOAT	64-bit VAX double-precision number

In addition to the data types mentioned in Table 1-1, DPML also provides routines that return two values of the same floating-point type; for example, two S_TYPE values or two G_TYPE values. In the discussion that follows, these pairs of floating-point data type values are referred to as F_COMPLEX. Refer to Table 1-2. This document uses F_COMPLEX to indicate that a given routine returns two different values of the same floating-point data type.

The mechanism for returning two floating-point values from DPML routines varies from platform to platform. However, on OpenVMS Alpha systems, F_COMPLEX data is returned in consecutive floating-point registers and is accessible only through a high-level language, like Fortran, that specifically allows access to them.

A complex number, z, is defined as an ordered pair of real numbers. The convention used in this manual to define an ordered pair of real numbers as complex is as follows:

The first number is the real part of the complex number.
The second number is preceded by i and is the imaginary part of the complex number.
A separator character (plus sign) is used to associate and separate the real and the imaginary number.

For example:

z = x + iy
z = sin x + icos y

DPML includes complex functions, for example, the complex sine, csin(x,y), defined to be sin(x + iy). Complex function routines like csin(), which have complex input, accept floating-point numbers in pairs and treat them as if they are real and imaginary parts of a complex number.

In the previous two examples, the first floating-point values are defined by x and sin x, respectively, and are the real part of the complex number. The second floating-point values used in the examples are defined by iy and icos y, respectively, and are the imaginary part of the complex number. Similarly, DPML routines that return complex function values return two floating-point values. Taken together, these two floating-point values represent a complex number.

DPML supports the floating-point complex types described in Table 1-2. DPML complex functions can be accessed only through high-level languages that support the complex data type. Use only the data types supported by your system.

Table 1-2 Floating-Point Complex Data Types
F_COMPLEX Description¹

S_FLOAT_COMPLEX An ordered pair of S_FLOAT quantities, representing a single-precision complex number

T_FLOAT_COMPLEX An ordered pair of T_FLOAT quantities, representing a double-precision complex number

X_FLOAT_COMPLEX An ordered pair of X_FLOAT quantities, representing an extended-precision complex number

F_FLOAT_COMPLEX An ordered pair of F_FLOAT quantities, representing a single-precision complex number

G_FLOAT_COMPLEX An ordered pair of G_FLOAT quantities, representing a double-precision complex number

**Table 1-2 Floating-Point Complex Data Types**
F_COMPLEX	Description¹
S_FLOAT_COMPLEX	An ordered pair of S_FLOAT quantities, representing a single-precision complex number
T_FLOAT_COMPLEX	An ordered pair of T_FLOAT quantities, representing a double-precision complex number
X_FLOAT_COMPLEX	An ordered pair of X_FLOAT quantities, representing an extended-precision complex number
F_FLOAT_COMPLEX	An ordered pair of F_FLOAT quantities, representing a single-precision complex number
G_FLOAT_COMPLEX	An ordered pair of G_FLOAT quantities, representing a double-precision complex number

¹The lower addressed quantity is the real part; the higher addressed quantity is the imaginary part.

1.3 Exceptional Arguments

Not all mathematical functions are capable of returning a meaningful result for all input argument values. Any argument value passed to a DPML routine that does not return a meaningful result, or is defined differently for different environments, is referred to as an exceptional argument. Exceptional arguments that result in an exception behavior are documented in the Exceptions section of each DPML routine in Chapter 2.

Exceptional arguments typically fall into one of two categories:

Domain errors or invalid arguments. These are arguments for which a function is not defined. For example, the inverse sine function, asin, is defined only for arguments between -1 and +1 inclusive. Attempting to evaluate acos(-2) or acos(3) results in a domain error or invalid argument error.
Range errors. These errors occur when a mathematically valid argument results in a function value that exceeds the range of representable values for the floating-point data type. Appendix A gives the approximate minimum and maximum values representable for each floating-point data type.

Contents

Index

privacy and legal statement

6118PRO.HTML

UNIX	/usr/doc/readers_comment.txt
OpenVMS	SYS$HELP:OPENVMSDOC_COMMENTS.TXT

Internet	dpml@digital.com
Fax	(603) 884-0120, Attention: Math Run Time Library Documentation, ZKO2-3/Q18
Mail	Compaq Computer Corporation Math Run Time Library Documentation, ZKO2-3/Q18 110 Spit Brook Rd. Nashua, NH 03062-2698 USA

Ctrl/ x	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.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	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 command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	In command 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 command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
bold text	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.