HP OpenVMS Systems Documentation
Compaq Portable Mathematics Library
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
OpenVMS Alpha Version 7.3
© 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.
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.
This book is for compiler writers, system programmers, and application programmers who want to use CPML routines.
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.
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.
For additional information about CPML, you can access the Compaq CPML website at the following location:
For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:
How to Order Additional Documentation
Use the following World Wide Web address to order additional documentation:
If you need help deciding which documentation best meets your needs, call 800-282-6672.
Compaq welcomes your comments about this manual. Please send comments to one of the following:
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:
Compaq strongly recommends that you limit your access to the CPML 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 CPML routines, the behavior of direct calls to CPML routines may change from release to release.
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.
|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, 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.
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.
|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|
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:
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:
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):
|Exceptional Argument||Exception Condition/Routine Behavior|
|x > ln(max_float)||Overflow|
|x < ln(min_float)||Underflow|
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.
|Exception Condition||Default Action||Return Value|
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.