Document revision date: 19 July 1999

DIGITAL Portable Mathematics Library

 Previous Contents Index

1.4 Exception Conditions and Exception Behavior

DPML routines are designed to provide predictable and platform-consistent exception conditions and behavior. When an exception is triggered in a DPML 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 DPML routine.

The Exceptions section of each DPML routine documents each exceptional argument that results in an exception behavior. In addition to the exceptional arguments, an indication of how the DPML 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), DPML 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.

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

Table 1-3 Default Action and Return Values for Exception Conditions
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 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.

1.5 IEEE Std 754 Considerations

The Institute of Electrical and Electronics Engineers (IEEE) ANSI/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point Arithmetic data types include denormalized numbers (very close to zero). The standard supports the concept of "Not-a-Number" 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 DPML routine produces an overflow or indeterminate condition, it generates an infinity or NaN value.

All DPML 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 Considerations

Table 1-4 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 (XPG4-UNIX). Descriptions of these routines appear in Chapter 2 under the generic function name listed in Table 1-4. Platform-specific entry-points are listed in Appendix B.

Table 1-4 XPG4 Conformant Routines
Routine Conforms to Standard Generic Function Name
acos XPG4 acos
acosh XPG4-UNIX acosh
asin XPG4 asin
asinh XPG4-UNIX asinh
atan XPG4 atan
atan2 XPG4 atan
atanh XPG4-UNIX atanh
ceil XPG4 ceil
cos XPG4 cos
cosh XPG4 cosh
cot XPG4 cot
erf XPG4 erf
erfc XPG4 erf
exp XPG4 exp
expm1 XPG4-UNIX exp
fabs XPG4 fabs
floor XPG4 floor
fmod XPG4 fmod
frexp XPG4 frexp
gamma XPG4 lgamma
hypot XPG4 hypot
ilogb XPG4-UNIX ilogb
isnan XPG4 isnan
j0 XPG4 bessel
j1 XPG4 bessel
jn XPG4 bessel
ldexp XPG4 ldexp
lgamma XPG4 lgamma
log XPG4 log
log10 XPG4 log
log1p XPG4-UNIX log
logb XPG4-UNIX logb
modf XPG4 modf
nextafter XPG4-UNIX nextafter
pow XPG4 pow
remainder XPG4-UNIX remainder
rint XPG4-UNIX rint
scalb XPG4-UNIX scalb
sin XPG4 sin
sinh XPG4 sinh
tan XPG4 tan
tanh XPG4 tanh
y0 XPG4 bessel
y1 XPG4 bessel
yn XPG4 bessel

Chapter 2DPML Routines

Each DPML routine documented in this chapter is presented in the following format:

• Routine name---A brief name to identify the function of the routine. A routine may contain more than one function.
• Interface---What the routine expects to receive and what it returns. See Section 2.1 for more information.
• Description---Additional information, including the permitted range of input values and generic calculations used to compute the results.
• Exceptions---A description of how the routine behaves when given a specific exceptional input argument.

2.1 DPML Routine Interface

The interface to each function is:

RETURN_TYPE generic_interface_name (INPUT_ARG_TYPE...)

Each of these is described below.

RETURN_TYPE

The data type of the value returned by the routine to your application program. Each routine returns a specific class of data type. For example, either F_TYPE or F_COMPLEX can appear in a DPML interface described in Chapter 2. The supported data types are described in Section 1.2.

generic_interface_name

The generic name. DPML routines in this chapter are listed in alphabetic order by their interface names. Some DPML routines may be available in the syntax of your high-level language. Fortran and C are examples. To maximize the portability of your application, use the corresponding mathematical routine described in your high-level language, and directly call only the routines documented in this manual that are not supported by your language. Refer to Appendix B for the specific entry-point names needed to directly call a DPML routine from your platform.

INPUT_ARG_TYPE...

The number and type of input arguments provided by your application. Some routines require more than one argument. Arguments must be coded in the order shown in the interface section of each routine described in this chapter. The supported data types for arguments are described in Section 1.2.

 Note Unless otherwise noted, arguments are read-only and passed by value. Arguments passed by another mechanism are prefaced by an asterisk (*); for example, *n in the frexp() routine.

2.2 Specific Entry-Point Names

Each generic interface name documented in the interface section of a routine description corresponds to one or more specific entry-point names described in Appendix B. For example, on OpenVMS Alpha systems, the acosd function has five entry-point names; one for each available floating-point data type. The acosd entry-point names are math\$acosd_f, math\$acosd_s, math\$acosd_x, math\$acosd_g, and math\$acosd_t. On DIGITAL UNIX Alpha systems, the acosd function has two entry-point names corresponding to their supported data types: S_FLOAT and T_FLOAT. The two entry-point names are acosdf for S_FLOAT input arguments and acosd for T_FLOAT arguments. Use the specific entry-point name that corresponds to the input argument data type.

2.3 Working with Exception Conditions

Each DPML routine description contains a table of exceptions. Each exception listed in the table represents an exceptional case that is handled in a platform-specific 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 DPML routine can be made through direct access (a CALL statement written by a programmer in a source code statement) or through indirect access (from compiler-implemented 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.

2.4 DPML Routine Interface Examples

This section discusses the atan2() and cdiv() interfaces and explains how to interpret them. The explanations given in this section apply to all DPML routines.

2.4.1 atan2() Interface

The interface to the atan2() routine is:

F_TYPE atan2 (F_TYPE y, F_TYPE x)

The routine name atan2() is the high-level language source-level name that gets mapped to a specific entry-point name documented in Appendix B. This is the name that appears in compiler documentation for this mathematical routine. The appropriate entry-point name is automatically selected when atan2() is called from high-level 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 entry-point 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 entry-point name is math\$atan2_g(). It takes two G_FLOAT arguments by value and returns a G_FLOAT result.

For DIGITAL UNIX Alpha systems, the S_FLOAT entry-point name is atan2f(). The routine takes two S_FLOAT input arguments by value and returns an S_FLOAT result.

2.4.2 cdiv() Interface

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 entry-point name documented in Appendix B. Selection of the appropriate entry-point name is done automatically when cdiv() is called from high-level 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 entry-point 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 entry-point 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 DIGITAL UNIX Alpha systems, the S_FLOAT entry-point name is cdivf(). This routine takes four S_FLOAT input arguments by value and returns an S_FLOAT_COMPLEX result.

acos - Arc Cosine of Angle

Description

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].

Exceptions

Exceptional Argument Routine Behavior
|x|>1 Invalid argument

acosh - Hyperbolic Arc Cosine of Angle

Description

acosh() returns the hyperbolic arc cosine of x for x in the interval [1,+infinity], where acosh(x) = ln(x + sqrt(x**2 - 1)). acosh() is the inverse function of cosh(), where acosh(cosh (x)) = x.

Exceptions

Exceptional Argument Routine Behavior
x<1 Invalid argument

asin - Arc Sine of Angle

Description

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].

Exceptions

Exceptional Argument Routine Behavior
|x|>1 Invalid argument

asinh - Hyperbolic Arc Sine of Angle

Description

asinh() returns the hyperbolic arc sine of x for x in the interval [-infinity, +infinity], where asinh(x) = ln(x + sqrt(x**2 + 1)). asinh() is the inverse function of sinh(), where asinh(sinh (x)) = x.

None.

atan - Arc Tangent of Angle with One Argument

Description

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].

None.

atan2 - Arc Tangent of Angle with Two Arguments

Description

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.

Exceptions

Exceptional Argument Routine Behavior
y = x = 0 Invalid argument
|y| = infinity and |x| = infinity Invalid argument

 Previous Next Contents Index

 privacy and legal statement 6118PRO_001.HTML