HP OpenVMS Systems Documentation 
OpenVMS VAX RTL Mathematics (MTH$) ManualOrder Number: AAPVXJDTE
April 2001
This manual documents the mathematics routines contained in the MTH$ facility of the OpenVMS RunTime 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 thirdparty 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.
ZK6117 The Compaq OpenVMS documentation set is available on CDROM.
PrefaceThis 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 RunTime Library. RunTime 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 highlevel languages: Compaq Ada Interpreted languages that can also access RunTime Library routines include VAX DSM and Compaq Datatrieve. Intended AudienceThis manual is intended for system and application programmers who write programs that call MTH$ RunTime Library routines. Document StructureThis manual contains two tutorial chapters, two reference sections, and two appendixes:
Related DocumentsThe RunTime Library routines are documented in a series of reference manuals. A description of how the RunTime Library routines are accessed and of how OpenVMS features and functionality are available through calls to the MTH$ RunTime 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. Highlevel language programmers will find additional information on calling RunTime 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:
Reader's CommentsCompaq welcomes your comments on this manual. Please send comments to either of the following addresses:
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. ConventionsThe following conventions are used in this manual:
Part 1
This part of the OpenVMS VAX RTL Mathematics (MTH$) Manual contains tutorial information about the
OpenVMS RTL MTH$ facility, and is structured as follows:

Letter  Data Type 

I  Word 
J  Longword 
D  D_floating 
G  G_floating 
H  H_floating 
C  F_floating complex 
CD  D_floating complex 
CG  G_floating complex 
Generally, Ffloating data types have no letter designation. For example, MTH$SIN returns an Ffloating value of the sine of an Ffloating argument and MTH$DSIN returns a Dfloating value of the sine of a Dfloating argument. However, in some of the miscellaneous functions, Ffloating data types are referenced by the letter designation A.
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. Dfloating complex, Gfloating complex, and Hfloating 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.
Data Type  m 

F_floating  0 
D_floating  1 
G_floating  1 
H_floating  3 
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 this manual.
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 userestablished 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 userestablished handler should correct CHF$L_MCH_SAVR0/R1 to the desired function value to be returned to the caller of the mathematics routine.
Dfloating complex, Gfloating complex, and Hfloating values cannot be corrected with a userestablished 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 doubleprecision floatingpoint value. A doubleprecision floatingpoint value correction works for both single and doubleprecision values.
If the correction is not performed, the floatingpoint reserved operand 0.0 is returned. A floatingpoint reserved operand is a floatingpoint datum with a sign bit of 1 and a biased exponent of 0. Accessing the floatingpoint 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 floatingpoint instructions. Therefore, a reserved operand fault can occur in any mathematics routine.
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.
y=(r,i) 
OpenVMS supports three floatingpoint complex types: Ffloating complex, Dfloating complex, and Gfloating complex. There is no Hfloating complex data type.
RunTime Library mathematics routines that use complex arguments require a pointer to a structure containing two xfloating values to be passed by reference for each argument. The first xfloating value contains r, the real part of the complex number. The second xfloating value contains i, the imaginary part of the complex number. Similarly, RunTime Library mathematics routines that return complex function values return two xfloating values. Some Language Independent Support (OTS$) routines also calculate complex functions.
Note that complex functions have no JSB entry points.
The mathematics routines in Table 11 are not found in the reference section of this manual. Instead, their entry points and argument information are listed in Appendix A of this manual.
A reserved operand fault can occur for any floatingpoint input argument in any mathematics routine. Other condition values signaled by each mathematics routine are indicated in the footnotes.
Entry Point  Function 

Absolute Value Routines  
MTH$ABS  Ffloating absolute value 
MTH$DABS  Dfloating absolute value 
MTH$GABS  Gfloating absolute value 
MTH$HABS  Hfloating 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 
FFloating Conversion Routines  
MTH$DBLE  Convert Ffloating to Dfloating (exact) 
MTH$GDBLE  Convert Ffloating to Gfloating (exact) 
MTH$IIFIX  Convert Ffloating to word (truncated) ^{2} 
MTH$JIFIX  Convert Ffloating to longword (truncated) ^{2} 
FloatingPoint Positive Difference Routines  
MTH$DIM  Positive difference of two Ffloating parameters ^{3} 
MTH$DDIM  Positive difference of two Dfloating parameters ^{3} 
MTH$GDIM  Positive difference of two Gfloating parameters ^{3} 
MTH$HDIM  Positive difference of two Hfloating 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 FloatingPoint Conversion Routines  
MTH$FLOATI  Convert word to Ffloating (exact) 
MTH$DFLOTI  Convert word to Dfloating (exact) 
MTH$GFLOTI  Convert word to Gfloating (exact) 
MTH$FLOATJ  Convert longword to Ffloating (rounded) 
MTH$DFLOTJ  Convert longword to Dfloating (exact) 
MTH$GFLOTJ  Convert longword to Gfloating (exact) 
Conversion to Greatest FloatingPoint Integer Routines  
MTH$FLOOR  Convert Ffloating to greatest Ffloating integer 
MTH$DFLOOR  Convert Dfloating to greatest Dfloating integer 
MTH$GFLOOR  Convert Gfloating to greatest Gfloating integer 
MTH$HFLOOR  Convert Hfloating to greatest Hfloating integer ^{1} 
FloatingPoint Truncation Routines  
MTH$AINT  Convert Ffloating to truncated Ffloating 
MTH$IINT  Convert Ffloating to truncated word ^{2} 
MTH$JINT  Convert Ffloating to truncated longword ^{2} 
MTH$DINT  Convert Dfloating to truncated Dfloating 
MTH$IIDINT  Convert Dfloating to truncated word ^{2} 
MTH$JIDINT  Convert Dfloating to truncated longword ^{2} 
MTH$GINT  Convert Gfloating to truncated Gfloating 
MTH$IIGINT  Convert Gfloating to truncated word ^{2} 
MTH$JIGINT  Convert Gfloating to truncated longword ^{2} 
MTH$HINT  Convert Hfloating to truncated Hfloating ^{1} 
MTH$IIHINT  Convert Hfloating to truncated word ^{2} 
MTH$JIHINT  Convert Hfloating 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  Ffloating maximum of n word parameters 
MTH$AJMAX0  Ffloating maximum of n longword parameters 
MTH$IMAX0  Word maximum of n word parameters 
MTH$JMAX0  Longword maximum of n longword parameters 
MTH$AMAX1  Ffloating maximum of n Ffloating parameters 
MTH$DMAX1  Dfloating maximum of n Dfloating parameters 
MTH$GMAX1  Gfloating maximum of n Gfloating parameters 
MTH$HMAX1  Hfloating maximum of n Hfloating parameters ^{1} 
MTH$IMAX1  Word maximum of n Ffloating parameters ^{2} 
MTH$JMAX1  Longword maximum of n Ffloating parameters ^{2} 
Minimum Value Routines  
MTH$AIMIN0  Ffloating minimum of n word parameters 
MTH$AJMIN0  Ffloating minimum of n longword parameters 
MTH$IMIN0  Word minimum of n word parameters 
MTH$JMIN0  Longword minimum of n longword parameters 
MTH$AMIN1  Ffloating minimum of n Ffloating parameters 
MTH$DMIN1  Dfloating minimum of n Dfloating parameters 
MTH$GMIN1  Gfloating minimum of n Gfloating parameters 
MTH$HMIN1  Hfloating minimum of n Hfloating parameters ^{1} 
MTH$IMIN1  Word minimum of n Ffloating parameters ^{2} 
MTH$JMIN1  Longword minimum of n Ffloating parameters ^{2} 
Remainder Routines  
MTH$AMOD  Remainder of two Ffloating parameters, arg1/arg2 ^{3,5} 
MTH$DMOD  Remainder of two Dfloating parameters, arg1/arg2 ^{3,5} 
MTH$GMOD  Remainder of two Gfloating parameters, arg1/arg2 ^{3} 
MTH$HMOD  Remainder of two Hfloating 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} 
FloatingPoint Conversion to Nearest Value Routines  
MTH$ANINT  Convert Ffloating to nearest Ffloating integer 
MTH$ININT  Convert Ffloating to nearest word integer ^{2} 
MTH$JNINT  Convert Ffloating to nearest longword integer ^{2} 
MTH$DNINT  Convert Dfloating to nearest Dfloating integer 
MTH$IIDNNT  Convert Dfloating to nearest word integer ^{2} 
MTH$JIDNNT  Convert Dfloating to nearest longword integer ^{2} 
MTH$GNINT  Convert Gfloating to nearest Gfloating integer 
MTH$IIGNNT  Convert Gfloating to nearest word integer ^{2} 
MTH$JIGNNT  Convert Gfloating to nearest longword integer ^{2} 
MTH$HNINT  Convert Hfloating to nearest Hfloating integer ^{1} 
MTH$IIHNNT  Convert Hfloating to nearest word integer ^{2} 
MTH$JIHNNT  Convert Hfloating to nearest longword integer ^{2} 
Bitwise Complement Operator Routines  
MTH$INOT  Bitwise complement of word parameter 
MTH$JNOT  Bitwise complement of longword parameter 
FloatingPoint Multiplication Routines  
MTH$DPROD  Dfloating product of two Ffloating parameters ^{3} 
MTH$GPROD  Gfloating product of two Ffloating parameters 
Bitwise Shift Operator Routines  
MTH$IISHFT  Bitwise shift of word 
MTH$JISHFT  Bitwise shift of longword 
FloatingPoint Sign Function Routines  
MTH$SGN  F or Dfloating sign function 
MTH$SIGN  Ffloating transfer of sign of y to sign of x 
MTH$DSIGN  Dfloating transfer of sign of y to sign of x 
MTH$GSIGN  Gfloating transfer of sign of y to sign of x 
MTH$HSIGN  Hfloating 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 FloatingPoint Routines  
MTH$SNGL  Convert Dfloating to Ffloating (rounded) ^{3} 
MTH$SNGLG 
Convert Gfloating to Ffloating (rounded)
^{3,6}

Next  Contents  Index 