HP OpenVMS Systems Documentation 
Compaq Portable Mathematics LibraryOrder Number: AAPV6VETE
April 2001
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
© 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 MSDOS 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 CDROM.
PrefaceThe Compaq Portable Mathematics Library (CPML) is a set of mathematical routines that are accessed from highlevel 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 highlevel language. Intended AudienceThis book is for compiler writers, system programmers, and application programmers who want to use CPML routines. Document StructureThis 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 floatingpoint boundary values used by the CPML routines. Appendix B contains the complete list of entrypoint names. The Glossary lists mathematical terms and symbolic names used in this manual, and provides a brief definition. Related DocumentsSome 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:
OpenVMS Documentation
For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:
How to Order Additional DocumentationUse the following World Wide Web address to order additional documentation:
If you need help deciding which documentation best meets your needs, call 8002826672. Reader's CommentsCompaq welcomes your comments about this manual. Please send comments to one of the following:
ConventionsIn 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:
Chapter 1

Compaq strongly recommends that you limit your access to the CPML routines documented in this manual to the highlevel language syntax of your choice, thereby guaranteeing the behavior of the routines across platforms. Because of the complex relationship between highlevel languages and CPML routines, the behavior of direct calls to CPML routines may change from release to release. 
CPML is designed to support mathematics function evaluation for multiple data types. These data types include integer, floatingpoint, and complex floatingpoint.
The integer data type, identified as int throughout this manual, is the natural size signed integer for a particular platform. On a 32bit system, int is a 32bit signed integer, and on a 64bit system, int is a 64bit signed integer.
The floatingpoint 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 floatingpoint data types. For example, CPML on OpenVMS Alpha systems supports the following floatingpoint data types: VAX single and doubleprecision, IEEE single and doubleprecision, and IEEE extendedprecision. CPML on Compaq Tru64 UNIX Alpha systems supports only IEEE single and doubleprecision data types. Table 11 describes the floatingpoint data types.
F_TYPE  Description 

S_FLOAT  32bit IEEE singleprecision number 
T_FLOAT  64bit IEEE doubleprecision number 
X_FLOAT  128bit IEEE extendedprecision number 
F_FLOAT  32bit VAX singleprecision number 
G_FLOAT  64bit VAX doubleprecision number 
In addition to the data types mentioned in Table 11, CPML also provides routines that return two values of the same floatingpoint type, for example, two S_TYPE values or two G_TYPE values. In the discussion that follows, these pairs of floatingpoint data type values are referred to as F_COMPLEX. Refer to Table 12. This document uses F_COMPLEX to indicate that a given routine returns two different values of the same floatingpoint data type.
The mechanism for returning two floatingpoint values from CPML routines varies from platform to platform. However, on OpenVMS Alpha systems, F_COMPLEX data is returned in consecutive floatingpoint registers and is accessible only through a highlevel 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:
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 floatingpoint 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 floatingpoint values are defined by x and sin x, respectively, and are the real part of the complex number. The second floatingpoint 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 floatingpoint values. Taken together, these two floatingpoint values represent a complex number.
CPML supports the floatingpoint complex types described in Table 12. You can access CPML complex functions only through highlevel languages that support the complex data type. Use only the data types supported by your system.
F_COMPLEX  Description^{1} 

S_FLOAT_COMPLEX  An ordered pair of S_FLOAT quantities, representing a singleprecision complex number 
T_FLOAT_COMPLEX  An ordered pair of T_FLOAT quantities, representing a doubleprecision complex number 
X_FLOAT_COMPLEX  An ordered pair of X_FLOAT quantities, representing an extendedprecision complex number 
F_FLOAT_COMPLEX  An ordered pair of F_FLOAT quantities, representing a singleprecision complex number 
G_FLOAT_COMPLEX  An ordered pair of G_FLOAT quantities, representing a doubleprecision 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 platformconsistent 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 conditionhandling 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 floatingpoint 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 13 describes the default action and return value of each condition.
Exception Condition  Default Action  Return Value 

Overflow  Trap  HUGE_RESULT 
Underflow  Continue Quietly  0 
Invalid argument  Trap  INV_RESULT 
The values HUGE_RESULT and INV_RESULT are datatype dependent.
For IEEE data types, HUGE_RESULT and INV_RESULT are the floatingpoint encodings for Infinity and NaN, respectively.
For VAX data types, HUGE_RESULT and INV_RESULT are max_float and 0, respectively.
Next  Contents  Index 