HP OpenVMS Systems Documentation

Order Number: AA-PV6VE-TE

This document provides reference and exception information for CPML, the Compaq Portable Mathematics Library software.

Revision/Update Information: This manual supersedes Compaq Portable Mathematics Library, Version 7.1

Software Version: OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3

Compaq Computer Corporation Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, VAX, VMS, and the Compaq Logo Registered in U.S. Patent and Trademark Office.

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 in the United States and other countries.

Motif, OSF, OSF/1, OSF/Motif, and UNIX are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6118

The Compaq OpenVMS documentation set is available on CD-ROM.

The Compaq Portable Mathematics Library (CPML) is a set of mathematical routines that are accessed from high-level languages (such as Fortran and C) which support mathematical functions. Many CPML routines can also be called directly using standard call interfaces, but it is recommended that you invoke CPML routines only from a high-level language.

Intended Audience

This book is for compiler writers, system programmers, and application programmers who want to use CPML routines.

Document Structure

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 CPML routine and how to interpret a routine's interface. It also alphabetically lists and describes the routines.

Appendix A lists the floating-point boundary values used by the CPML 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.

Related Documents

Some books in Compaq's documentation sets help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.

Use the documentation overview and the master index information for your operating system when searching for hardcopy information on a topic. They provide information on all of the books in your operating system's documentation set.

CPML Documentation

For additional information about CPML, you can access the Compaq CPML website at the following location:

http://h18000.www1.hp.com/math

OpenVMS Documentation

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

http://www.openvms.compaq.com/

How to Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Reader's Comments

Compaq welcomes your comments about this manual. Please send comments to one of the following:

Conventions

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

The following conventions are used in this manual:

Monospace text 

The Compaq Portable Mathematics Library (referred to as CPML) 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 CPML 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. CPML was developed to provide a common set of routines that supports 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 in the same way for all languages and platforms. Occasionally, however, high-level language definitions of the same mathematical function 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, CPML traps exceptional arguments and invokes a system-specific routine called the CPML exception handler. The exception handler is designed to work 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 CPML library but rather by a combination of several entities acting in concert.

CPML 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, CPML 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. CPML on Compaq Tru64 UNIX Alpha systems supports only IEEE single- and double-precision data types. Table 1-1 describes the floating-point data types.

In addition to the data types mentioned in Table 1-1, CPML 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 CPML 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 it.

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

CPML 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, CPML routines that return complex function values return two floating-point values. Taken together, these two floating-point values represent a complex number.

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

Not all mathematical functions are capable of returning a meaningful result for all input argument values. Any argument value passed to a CPML 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 CPML 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.

CPML routines are designed to provide predictable and platform-consistent exception conditions and behavior. When an exception is triggered in a CPML routine, two pieces of information can be generated and made available to the calling program for exception handling:

• A notification that an exception has occurred. The mechanics of exception notification vary from platform to platform (for example, signaling, trapping, set errno).
• A return value. If your environment allows your routine to continue after raising an exception condition (with an exception handler for example), then a return value is made available upon completion of the routine.

The exception condition-handling mechanisms on your platform dictate how you can recover from an exception condition, and whether you can expect to receive an exception notification, a return value, or both, from a CPML routine.

The Exceptions section of each CPML routine documents each exceptional argument that results in an exception behavior. In addition to the exceptional arguments, an indication of how the CPML routines treat each argument is given. Exceptional arguments are sometimes presented in terms of symbolic constants.

For example, the following table lists the exceptional arguments of the exponential routine, exp(x):

The exceptional arguments indicate that whenever x > ln(max_float)
or x < ln(min_float), CPML recognizes an overflow or underflow condition, respectively.

The symbolic constants ln(max_float) and ln(min_float) represent the natural log of the maximum and minimum representable values of the floating-point data type in question. The actual values of ln(max_float) and ln(min_float) are described in Appendix A.

CPML recognizes three predefined conditions: overflow, underflow, and invalid argument. Table 1-3 describes the default action and return value of each condition.

The values HUGE_RESULT and INV_RESULT are data-type dependent.

For IEEE data types, HUGE_RESULT and INV_RESULT are the floating-point encodings for Infinity and NaN, respectively.

For VAX data types, HUGE_RESULT and INV_RESULT are max_float and 0, respectively.