HP OpenVMS Systems Documentation 
Compaq Portable Mathematics Library
1.5 IEEE Std 754 ConsiderationsThe Institute of Electrical and Electronics Engineers (IEEE) ANSI/IEEE Std 7541985, IEEE Standard for Binary FloatingPoint Arithmetic data types include denormalized numbers (very close to zero). The standard supports the concept of "NotaNumber" or NaN to represent indeterminate quantities, and uses plus infinity or minus infinity (so that they behave in arithmetic) like the mathematical infinities. Whenever a CPML routine produces an overflow or indeterminate condition, it generates an infinity or NaN value. All CPML routines, except one, return a NaN result when presented with a NaN input. The only exception is pow(NaN,0) = 1 in ANSI C. 1.6 X/Open Portability Guide ConsiderationsTable 14 lists the routines described in this manual that conform to the requirements of the X/Open Portability Guide, Version 4 (XPG4), or are implemented as UNIX extensions to the XPG4 standard (XPG4UNIX). Descriptions of these routines appear in Chapter 2 under the generic function name listed in Table 14. Platformspecific entrypoints are listed in Appendix B.
Chapter 2

Unless otherwise noted, arguments are readonly and passed by value. Arguments passed by another mechanism are prefaced by an asterisk (*); for example, *n in the frexp() routine. 
Each generic interface name documented in the interface section of a routine description corresponds to one or more specific entrypoint names described in Appendix B. For example, on OpenVMS Alpha systems, the acosd function has five entrypoint names, one for each available floatingpoint data type. The acosd entrypoint names are math$acosd_f, math$acosd_s, math$acosd_x, math$acosd_g, and math$acosd_t. On Compaq Tru64 UNIX Alpha systems, the acosd function has two entrypoint names corresponding to their supported data types: S_FLOAT and T_FLOAT. The two entrypoint names are acosdf for S_FLOAT input arguments and acosd for T_FLOAT arguments. Use the specific entrypoint name that corresponds to the input argument data type.
Each CPML routine description contains a table of exceptions. Each exception listed in the table represents an exceptional case that is handled in a platformspecific manner. For example, the atan2() exception table contains the following two entries:
Exceptional Argument  Routine Behavior 

y = x = 0  Invalid argument 
y = x = infinity  Invalid argument 
The first entry describes an exception condition containing two input arguments with zero values. Upon detecting this error, the routine behavior signals the "invalid argument" condition. The second entry is applicable only to platforms supporting signed or unsigned infinity values. Here, if the absolute value of both input arguments is equal to infinity, an "invalid argument" condition is signaled.
The exact behavior of a routine that detects an exceptional argument varies from platform to platform and is sometimes dependent on the environment in which it is called. The behavior you see depends on the platform and language used. It also depends on how the routine was called and the interaction of the various layers of software through which the call to the routine was made. Remember, access to a CPML routine can be made either through direct access (a CALL statement written by a programmer in a source code statement) or through indirect access (from compilerimplemented mathematical syntax).
The default behavior for detecting the x=y=0 arguments is to generate an exception trap when accessing atan2() indirectly through Fortran compiler syntax. C compiler syntax for the atan2() routine sets errno and returns a NaN when give the same input. In these cases, your compiler documentation provides you with information on how to work with exception conditions.
This section discusses the atan2() and cdiv() interfaces and explains how to interpret them. The explanations given in this section apply to all CPML routines.
The interface to the atan2() routine is:
F_TYPE atan2 (F_TYPE y, F_TYPE x)
The routine name atan2() is the highlevel language sourcelevel name that gets mapped to a specific entrypoint name documented in Appendix B. This is the name that appears in compiler documentation for this mathematical routine. The appropriate entrypoint name is automatically selected when atan2() is called from highlevel language syntax. This selection depends upon the data type of the input arguments. If you make direct calls to this routine, you must manually select the proper entrypoint name documented in Appendix B for the data type of your input arguments.
The format of the atan2() routine shows that it expects to receive two input arguments by value. Both arguments must be the same F_TYPE. The returned value will also be the same F_TYPE as the input arguments.
For example, on OpenVMS Alpha systems, the G_FLOAT entrypoint name is math$atan2_g(). It takes two G_FLOAT arguments by value and returns a G_FLOAT result.
For Compaq Tru64 UNIX Alpha systems, the S_FLOAT entrypoint name is atan2f(). The routine takes two S_FLOAT input arguments by value and returns an S_FLOAT result.
The interface to the cdiv() routine is:
F_COMPLEX cdiv (F_TYPE a, F_TYPE b, F_TYPE c, F_TYPE d)
The routine name cdiv() is the generic name that gets mapped to a specific entrypoint name documented in Appendix B. Selection of the appropriate entrypoint name is done automatically when cdiv() is called from highlevel language syntax. This selection depends upon the data type of the input arguments. Again, if you make direct calls to this routine, you must manually select the proper entrypoint name documented in Appendix B for the data type of your input arguments.
The format of the cdiv() routine shows that it expects to receive four input arguments by value. All arguments must be the same F_TYPE. The returned value will be an F_COMPLEX data type and will be the same base data type as the input arguments.
For example, on OpenVMS Alpha systems, the F_FLOAT entrypoint name is math$cdiv_f(). This routine takes four F_FLOAT input arguments by value and returns an F_FLOAT_COMPLEX result in an ordered pair of F_FLOAT quantities.
For Compaq Tru64 UNIX Alpha systems, the S_FLOAT entrypoint name is cdivf(). This routine takes four S_FLOAT input arguments by value and returns an S_FLOAT_COMPLEX result.
F_TYPE acos (F_TYPE x)F_TYPE acosd (F_TYPE x)
acos() computes the principal value of the arc cosine of x in the interval [0,pi] radians for x in the interval [1,1].acosd() computes the principal value of the arc cosine of x in the interval [0,180] degrees for x in the interval [1,1].
Exceptional Argument  Routine Behavior 

x>1  Invalid argument 
F_TYPE acosh (F_TYPE x)
acosh() returns the hyperbolic arc cosine of x for x in the interval [1,+infinity]. acosh(x) = ln(x + sqrt(x**2  1)).acosh() is the inverse function of cosh(). The definition of the acosh() function is acosh(cosh (x)) = x.
Exceptional Argument  Routine Behavior 

x<1  Invalid argument 
F_TYPE asin (F_TYPE x)F_TYPE asind (F_TYPE x)
asin() computes the principal value of the arc sine of x in the interval [pi/2,pi/2] radians for x in the interval [1,1].asind() computes the principal value of the arc sine of x in the interval [90,90] degrees for x in the interval [1,1].
Exceptional Argument  Routine Behavior 

x>1  Invalid argument 
F_TYPE asinh (F_TYPE x)
asinh() returns the hyperbolic arc sine of x for x in the interval [infinity, +infinity]. asinh(x) = ln(x + sqrt(x**2 + 1)).asinh() is the inverse function of sinh(). asinh(sinh (x)) = x.
F_TYPE atan (F_TYPE x)F_TYPE atand (F_TYPE x)
atan() computes the principal value of the arc tangent of x in the interval [pi/2,pi/2] radians for x in the interval [infinity, +infinity].atand() computes the principal value of the arc tangent of x in the interval [90,90] degrees for x in the interval [infinity, +infinity].
F_TYPE atan2 (F_TYPE y, F_TYPE x)F_TYPE atand2 (F_TYPE y, F_TYPE x)
atan2() computes the angle in the interval [pi,pi] whose arc tangent is y/x radians for x and y in the interval [infinity, +infinity]. The sign of atan2() is the same as the sign of y. The atan2(y, x) function is computed as follows, where f is the number of fraction bits associated with the data type:
Value of Input Arguments Angle Returned x = 0 or y/x > 2 ^{f+1} Pi sign/2 * (sign y) x > 0 and y/x <= 2 ^{f+1} atan(y/x) x < 0 and y/x <= 2 ^{f+1} Pi sign * (sign y) + atan(y/x) atand2() computes the angle in the interval [180,180] whose arc tangent is y/x degrees for x and y in the interval [infinity, +infinity]. The sign of atand2() is the same as the sign of y.
Exceptional Argument  Routine Behavior 

y = x = 0  Invalid argument 
y = infinity and x = infinity  Invalid argument 
F_TYPE atanh (F_TYPE x)
atanh() returns the hyperbolic arc tangent of x for x in the interval (1,1). atanh() is the inverse function of tanh(). atanh(tanh (x)) = x.atanh(x) is computed as 1/2 ln((1+x)/(1x)).
Exceptional Argument  Routine Behavior 

x > or = 1  Invalid argument 
F_TYPE j0 (F_TYPE x)F_TYPE j1 (F_TYPE x)
F_TYPE jn (int n, F_TYPE x)
F_TYPE y0 (F_TYPE x)
F_TYPE y1 (F_TYPE x)
F_TYPE yn (int n, F_TYPE x)
j0() and j1() return the value of the Bessel function of the first kind of orders 0 and 1, respectively.jn() returns the value of the Bessel function of the first kind of order n.
y0() and y1() return the value of the Bessel function of the second kind of orders 0 and 1, respectively.
yn() returns the value of the Bessel function of the second kind of order n.
The value of x must be positive for the y family of Bessel functions. The value of n specifies some integer value.
Exceptional Argument  Routine Behavior 

(y0(), y1(), yn()) x < 0  Invalid argument 
(y0(), y1(), yn()) x = 0  Overflow 
Previous  Next  Contents  Index 