Document revision date: 30 March 2001  
Order Number: AAPV6VETE
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 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.
Contents  Index 
The 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.
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 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.
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://www.compaq.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/ 
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 8002826672.
Compaq welcomes your comments about this manual. Please send comments to one of the following:
Internet  openvmsdoc@compaq.com 
Compaq Computer Corporation
OSSG Documentation Group, ZKO34/U08 110 Spit Brook Rd. Nashua, NH 030622698 
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:
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.)
In the HTML version of this document, this convention appears in brackets, rather than a box. 
... 
A horizontal ellipsis in examples indicates one of the following
possibilities:

.
. . 
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 you must enclose choices in parentheses if you specify more than one. 
[ ]  In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement. 
  In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line. 
{ }  In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line. 
bold text  This typeface represents the introduction of a new term. It also represents 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 dd represents the predefined code for the device type). 
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 radixesbinary, octal, or hexadecimalare explicitly indicated. 
The Compaq Portable Mathematics Library (referred to as CPML) includes a wide variety of mathematical routines that cover the following areas:
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 floatingpoint data types.
Developing software within the confines of highlevel languages like Fortran and C greatly increases the portability and maintainability of your source code. Many highlevel 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, highlevel 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 systemdefined value.
This document uses the term exceptional arguments to refer to values in the following situations:
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 systemspecific routine called the CPML exception handler. The exception handler is designed to work with highlevel language compilers and runtime libraries (RTLs) to provide specific language semantics for exceptional arguments. This means that the uservisible 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.
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 
privacy and legal statement  
6118PRO.HTML 