HP OpenVMS Systems Documentation
OpenVMS VAX RTL Mathematics (MTH$) Manual
Order Number: AA--PVXJD--TE
This manual documents the mathematics routines contained in the MTH$ facility of the OpenVMS Run-Time Library.
Revision/Update Information: This manual supersedes the OpenVMS VAX RTL Mathematics (MTH$) Manual, Version 7.1.
Software Version: OpenVMS VAX Version 7.3
Compaq Computer Corporation
© 2001 Compaq Computer Corporation
Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.
Compaq Ada and OpenVMS are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.
The following are third-party trademarks:
BASIC is a registered trademark of the Trustees of Dartmouth College, D.B.A. Dartmouth College.
All other product names mentioned herein may be the trademarks or registered 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 waranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.
The Compaq OpenVMS documentation set is available on CD-ROM.
This manual provides users of the Compaq OpenVMS operating system with detailed usage and reference information on mathematics routines supplied in the MTH$ facility of the Run-Time Library.
Run-Time Library routines can be used only in programs written in languages that produce native code for the VAX hardware. At present, these languages include VAX MACRO and the following compiled high-level languages:
Interpreted languages that can also access Run-Time Library routines include VAX DSM and Compaq Datatrieve.
This manual is intended for system and application programmers who write programs that call MTH$ Run-Time Library routines.
This manual contains two tutorial chapters, two reference sections, and two appendixes:
The Run-Time Library routines are documented in a series of reference manuals. A description of how the Run-Time Library routines are accessed and of how OpenVMS features and functionality are available through calls to the MTH$ Run-Time Library appears in OpenVMS Programming Concepts Manual. Descriptions of the other RTL facilities and their corresponding routines are presented in the following books:
Application programmers using any language can refer to the Guide to Creating OpenVMS Modular Procedures for writing modular and reentrant code.
High-level language programmers will find additional information on calling Run-Time Library routines in their language reference manuals. Additional information may also be found in the language user's guide provided with your OpenVMS language software.
For a complete list and description of the manuals in the OpenVMS documentation set, see the OpenVMS Version 7.3 New Features and Documentation Overview.
For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:
Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:
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.
The following conventions are used in this manual:
This part of the OpenVMS VAX RTL Mathematics (MTH$) Manual contains tutorial information about the
OpenVMS RTL MTH$ facility, and is structured as follows:
Generally, F-floating data types have no letter designation. For
example, MTH$SIN returns an F-floating value of the sine of an
F-floating argument and MTH$DSIN returns a D-floating value of the sine
of a D-floating argument. However, in some of the miscellaneous
functions, F-floating data types are referenced by the letter
1.2 Calling Conventions
For calling conventions specific to the MTH$ vector routines, refer to Chapter 2.
All calls to mathematics routines, as described in the Format section of each routine, accept arguments passed by reference. JSB entry points accept arguments passed by value.
All mathematics routines return values in R0 or R0/R1 except those routines for which the values cannot fit in 64 bits. D-floating complex, G-floating complex, and H-floating values are data structures which are larger than 64 bits. Routines returning values that cannot fit in registers R0/R1 return their function values into the first argument in the argument list.
The notation JSB MTH$NAME_Rn, where n is the highest register number referenced, indicates that an equivalent JSB entry point is available. Registers R0:Rn are not preserved.
Routines with JSB entry points accept a single argument in R0:Rm, where m, which is defined in the following table, is dependent on the data type.
A routine returning one value returns it to registers R0:Rm.
When a routine returns two values (for example, MTH$SINCOS), the first value is returned in R0:Rm and the second value is returned in (R<m+1>:R<2*m+1>).
Note that for routines returning a single value, n>=m. For routines returning two values, n>=2*m + 1.
In general, CALL entry points for mathematics routines do the following:
JSB entry points execute in the context of the caller with the enable operations as set by the caller. Since the routines do not cause arithmetic traps or faults, their operation is not affected by the setting of the arithmetic trap enables, except as noted.
For more detailed information on CALL and JSB entry points, refer to
the OpenVMS Programming Concepts Manual.
For those mathematics routines having corresponding algorithms, the
complete algorithm can be found in the Description section of the
routine description appearing in the Scalar MTH$ Reference Section of
1.4 Condition Handling
Error conditions are indicated by using the VAX signaling mechanism. The VAX signaling mechanism signals all conditions in mathematics routines as SEVERE by calling LIB$SIGNAL. When a SEVERE error is signaled, the default handler causes the image to exit after printing an error message. A user-established condition handler can be written to cause execution to continue at the point of the error by returning SS$_CONTINUE. A mathematics routine returns to its caller after the contents of R0/R1 have been restored from the mechanism argument vector CHF$L_MCH_SAVR0/R1. Thus, the user-established handler should correct CHF$L_MCH_SAVR0/R1 to the desired function value to be returned to the caller of the mathematics routine.
D-floating complex, G-floating complex, and H-floating values cannot be corrected with a user-established condition handler, because R2/R3 is not available in the mechanism argument vector.
Note that it is more reliable to correct R0 and R1 to resemble R0 and R1 of a double-precision floating-point value. A double-precision floating-point value correction works for both single- and double-precision values.
If the correction is not performed, the floating-point reserved operand --0.0 is returned. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Accessing the floating-point reserved operand will cause a reserved operand fault. See the OpenVMS RTL Library (LIB$) Manual for a complete description of how to write user condition handlers for SEVERE errors.
A few mathematics routines signal floating underflow if the calling program (JSB or CALL) has enabled floating underflow faults or traps.
All mathematics routines access input arguments and the real and
imaginary parts of complex numbers using floating-point instructions.
Therefore, a reserved operand fault can occur in any mathematics
1.5 Complex Numbers
A complex number y is defined as an ordered pair of real numbers r and i, where r is the real part and i is the imaginary part of the complex number.
OpenVMS supports three floating-point complex types: F-floating complex, D-floating complex, and G-floating complex. There is no H-floating complex data type.
Run-Time Library mathematics routines that use complex arguments require a pointer to a structure containing two x-floating values to be passed by reference for each argument. The first x-floating value contains r, the real part of the complex number. The second x-floating value contains i, the imaginary part of the complex number. Similarly, Run-Time Library mathematics routines that return complex function values return two x-floating values. Some Language Independent Support (OTS$) routines also calculate complex functions.
Note that complex functions have no JSB entry points.
1.6 Mathematics Routines Not Documented in the MTH$ Reference Section
|Absolute Value Routines|
|MTH$ABS||F-floating absolute value|
|MTH$DABS||D-floating absolute value|
|MTH$GABS||G-floating absolute value|
|MTH$HABS||H-floating absolute value 1|
|MTH$IIABS||Word absolute value 2|
|MTH$JIABS||Longword absolute value 2|
|Bitwise AND Operator Routines|
|MTH$IIAND||Bitwise AND of two word parameters|
|MTH$JIAND||Bitwise AND of two longword parameters|
|F-Floating Conversion Routines|
|MTH$DBLE||Convert F-floating to D-floating (exact)|
|MTH$GDBLE||Convert F-floating to G-floating (exact)|
|MTH$IIFIX||Convert F-floating to word (truncated) 2|
|MTH$JIFIX||Convert F-floating to longword (truncated) 2|
|Floating-Point Positive Difference Routines|
|MTH$DIM||Positive difference of two F-floating parameters 3|
|MTH$DDIM||Positive difference of two D-floating parameters 3|
|MTH$GDIM||Positive difference of two G-floating parameters 3|
|MTH$HDIM||Positive difference of two H-floating parameters 1,3|
|MTH$IIDIM||Positive difference of two word parameters 2|
|MTH$JIDIM||Positive difference of two longword parameters 2|
|Bitwise Exclusive OR Operator Routines|
|MTH$IIEOR||Bitwise exclusive OR of two word parameters|
|MTH$JIEOR||Bitwise exclusive OR of two longword parameters|
|Integer to Floating-Point Conversion Routines|
|MTH$FLOATI||Convert word to F-floating (exact)|
|MTH$DFLOTI||Convert word to D-floating (exact)|
|MTH$GFLOTI||Convert word to G-floating (exact)|
|MTH$FLOATJ||Convert longword to F-floating (rounded)|
|MTH$DFLOTJ||Convert longword to D-floating (exact)|
|MTH$GFLOTJ||Convert longword to G-floating (exact)|
|Conversion to Greatest Floating-Point Integer Routines|
|MTH$FLOOR||Convert F-floating to greatest F-floating integer|
|MTH$DFLOOR||Convert D-floating to greatest D-floating integer|
|MTH$GFLOOR||Convert G-floating to greatest G-floating integer|
|MTH$HFLOOR||Convert H-floating to greatest H-floating integer 1|
|Floating-Point Truncation Routines|
|MTH$AINT||Convert F-floating to truncated F-floating|
|MTH$IINT||Convert F-floating to truncated word 2|
|MTH$JINT||Convert F-floating to truncated longword 2|
|MTH$DINT||Convert D-floating to truncated D-floating|
|MTH$IIDINT||Convert D-floating to truncated word 2|
|MTH$JIDINT||Convert D-floating to truncated longword 2|
|MTH$GINT||Convert G-floating to truncated G-floating|
|MTH$IIGINT||Convert G-floating to truncated word 2|
|MTH$JIGINT||Convert G-floating to truncated longword 2|
|MTH$HINT||Convert H-floating to truncated H-floating 1|
|MTH$IIHINT||Convert H-floating to truncated word 2|
|MTH$JIHINT||Convert H-floating to truncated longword 2|
|Bitwise Inclusive OR Operator Routines|
|MTH$IIOR||Bitwise inclusive OR of two word parameters|
|MTH$JIOR||Bitwise inclusive OR of two longword parameters|
|Maximum Value Routines|
|MTH$AIMAX0||F-floating maximum of n word parameters|
|MTH$AJMAX0||F-floating maximum of n longword parameters|
|MTH$IMAX0||Word maximum of n word parameters|
|MTH$JMAX0||Longword maximum of n longword parameters|
|MTH$AMAX1||F-floating maximum of n F-floating parameters|
|MTH$DMAX1||D-floating maximum of n D-floating parameters|
|MTH$GMAX1||G-floating maximum of n G-floating parameters|
|MTH$HMAX1||H-floating maximum of n H-floating parameters 1|
|MTH$IMAX1||Word maximum of n F-floating parameters 2|
|MTH$JMAX1||Longword maximum of n F-floating parameters 2|
|Minimum Value Routines|
|MTH$AIMIN0||F-floating minimum of n word parameters|
|MTH$AJMIN0||F-floating minimum of n longword parameters|
|MTH$IMIN0||Word minimum of n word parameters|
|MTH$JMIN0||Longword minimum of n longword parameters|
|MTH$AMIN1||F-floating minimum of n F-floating parameters|
|MTH$DMIN1||D-floating minimum of n D-floating parameters|
|MTH$GMIN1||G-floating minimum of n G-floating parameters|
|MTH$HMIN1||H-floating minimum of n H-floating parameters 1|
|MTH$IMIN1||Word minimum of n F-floating parameters 2|
|MTH$JMIN1||Longword minimum of n F-floating parameters 2|
|MTH$AMOD||Remainder of two F-floating parameters, arg1/arg2 3,5|
|MTH$DMOD||Remainder of two D-floating parameters, arg1/arg2 3,5|
|MTH$GMOD||Remainder of two G-floating parameters, arg1/arg2 3|
|MTH$HMOD||Remainder of two H-floating parameters, arg1/arg2 1,3|
|MTH$IMOD||Remainder of two word parameters, arg1/arg2 4|
|MTH$JMOD||Remainder of two longword parameters, arg1/arg2 4|
|Floating-Point Conversion to Nearest Value Routines|
|MTH$ANINT||Convert F-floating to nearest F-floating integer|
|MTH$ININT||Convert F-floating to nearest word integer 2|
|MTH$JNINT||Convert F-floating to nearest longword integer 2|
|MTH$DNINT||Convert D-floating to nearest D-floating integer|
|MTH$IIDNNT||Convert D-floating to nearest word integer 2|
|MTH$JIDNNT||Convert D-floating to nearest longword integer 2|
|MTH$GNINT||Convert G-floating to nearest G-floating integer|
|MTH$IIGNNT||Convert G-floating to nearest word integer 2|
|MTH$JIGNNT||Convert G-floating to nearest longword integer 2|
|MTH$HNINT||Convert H-floating to nearest H-floating integer 1|
|MTH$IIHNNT||Convert H-floating to nearest word integer 2|
|MTH$JIHNNT||Convert H-floating to nearest longword integer 2|
|Bitwise Complement Operator Routines|
|MTH$INOT||Bitwise complement of word parameter|
|MTH$JNOT||Bitwise complement of longword parameter|
|Floating-Point Multiplication Routines|
|MTH$DPROD||D-floating product of two F-floating parameters 3|
|MTH$GPROD||G-floating product of two F-floating parameters|
|Bitwise Shift Operator Routines|
|MTH$IISHFT||Bitwise shift of word|
|MTH$JISHFT||Bitwise shift of longword|
|Floating-Point Sign Function Routines|
|MTH$SGN||F- or D-floating sign function|
|MTH$SIGN||F-floating transfer of sign of y to sign of x|
|MTH$DSIGN||D-floating transfer of sign of y to sign of x|
|MTH$GSIGN||G-floating transfer of sign of y to sign of x|
|MTH$HSIGN||H-floating transfer of sign of y to sign of x 1|
|MTH$IISIGN||Word transfer of sign of y to sign of x|
|MTH$JISIGN||Longword transfer of sign of y to sign of x|
|Conversion of Double to Single Floating-Point Routines|
|MTH$SNGL||Convert D-floating to F-floating (rounded) 3|
Convert G-floating to F-floating (rounded)