Efficient Floating-Point Control and Inquiry Procedures

XL Fortran provides several procedures that allow you to query and control the floating-point status and control register of the processor directly. These procedures are more efficient than the fpgets and fpsets subroutines because they are mapped into inlined machine instructions that manipulate the floating-point status and control register (fpscr) directly.

XL Fortran supplies the module xlf_fp_util, which contains the interfaces and data type definitions for these procedures and the definitions for the named constants that are needed by the procedures. This module enables type checking of these procedures at compile time rather than at link time. You can use the argument names listed in the examples as the names for keyword arguments when calling a procedure. The following files are supplied for the xlf_fp_util module:

File names File type Locations
xlf_fp_util.mod module symbol file
  • install path/xlf/9.1/include

To use these procedures, you must add a USE XLF_FP_UTIL statement to your source file. For more information on USE, see USE.

If there are name conflicts (for example if the accessing subprogram has an entity with the same name as a module entity), use the ONLY clause or the renaming features of the USE statement. For example,

USE XLF_FP_UTIL, NULL1 => get_fpscr, NULL2 => set_fpscr

When compiling with the -U option, you must code the names of these procedures in all lowercase. We will show the names in lowercase here as a reminder.

The fpscr procedures are:

The following table lists the constants that are used with the fpscr procedures:

Family Constant Description
General
FPSCR_KIND The kind type parameter for a fpscr flags variable
IEEE Rounding Modes
FP_RND_RN Round toward nearest (default)
FP_RND_RZ Round toward zero
FP_RND_RP Round toward plus infinity
FP_RND_RM Round toward minus infinity
FP_RND_MODE Used to obtain the rounding mode from an FPSCR flags variable or value
IEEE Exception Enable Flags(1)
TRP_INEXACT Enable inexact trap
TRP_DIV_BY_ZERO Enable divide-by-zero trap
TRP_UNDERFLOW Enable underflow trap
TRP_OVERFLOW Enable overflow trap
TRP_INVALID Enable invalid trap
FP_ENBL_SUMM Trap enable summary or enable all
IEEE Exception Status Flags
FP_INVALID Invalid operation exception
FP_OVERFLOW Overflow exception
FP_UNDERFLOW Underflow exception
FP_DIV_BY_ZERO Divide-by-zero exception
FP_INEXACT Inexact exception
FP_ALL_IEEE_XCP All IEEE exceptions summary flags
FP_COMMON_IEEE_XCP All IEEE exceptions summary flags excluding the FP_INEXACT exception
Machine Specific Exception Details Flags
FP_INV_SNAN Signaling NaN
FP_INV_ISI Infinity - Infinity
FP_INV_IDI Infinity / Infinity
FP_INV_ZDZ 0 / 0
FP_INV_IMZ Infinity * 0
FP_INV_CMP Unordered compare
FP_INV_SQRT Square root of negative number
FP_INV_CVI Conversion to integer error
FP_INV_VXSOFT Software request
Machine Specific Exception Summary Flags
FP_ANY_XCP Any exception summary flag
FP_ALL_XCP All exceptions summary flags
FP_COMMON_XCP All exceptions summary flags excluding the FP_INEXACT exception

Notes:

  1. In order to enable exception trapping, you must set the desired IEEE Exception Enable Flags and,

xlf_fp_util Floating-Point Procedures

This section lists the efficient floating-point control and inquiry procedures in the XLF_FP_UTIL intrinsic module.

clr_fpscr_flags

Type

The clr_fpscr_flags subroutine clears the floating-point status and control register flags you specify in the MASK argument. Flags that you do not specify in MASK remain unaffected. MASK must be of type INTEGER(FPSCR_KIND). You can manipulate the MASK using the intrinsic procedures described in Integer Bit Model.

For more information on the FPSCR constants, see FPSCR constants.

Examples

USE, INTRINSIC :: XLF_FP_UTIL
INTEGER(FPSCR_KIND) MASK
 
! Clear the overflow and underflow exception flags
 
MASK=(IOR(FP_OVERFLOW,FP_UNDERFLOW))
CALL clr_fpscr_flags(MASK)
 

For another example of the clr_fpscr_flags subroutine, see get_fpscr_flags.

get_fpscr

Type

The get_fpscr function returns the current value of the floating-point status and control register (fpscr) of the processor.

Result Type and Attributes

INTEGER(FPSCR_KIND)

Result Value

The current value of the floating-point status and control register (FPSCR) of the processor.

Examples

USE, INTRINSIC :: XLF_FP_UTIL
INTEGER(FPSCR_KIND) FPSCR
 
FPSCR=get_fpscr()

get_fpscr_flags

Type

The get_fpscr_flags function returns the current state of the floating-point status and control register flags you specify in the MASK argument. MASK must be of type INTEGER(FPSCR_KIND). You can manipulate the MASK using the intrinsics described in Integer Bit Model.

For more information on the FPSCR constants, see FPSCR constants.

Result Type and Attributes

An INTEGER(FPSCR_KIND)

Result Value

The status of the FPSCR flags specified by the MASK argument. If a flag specified in the MASK argument is on, the value for the flag will be returned in the return value. The following example requests the status of the FP_DIV_BY_ZERO and FP_INVALID flags.

Examples

USE, INTRINSIC :: XLF_FP_UTIL
 
! ...
 
IF (get_fpscr_flags(IOR(FP_DIV_BY_ZERO,FP_INVALID)) .NE. 0) THEN
  ! Either Divide-by-zero or an invalid operation occurred.
 
  ! ...
 
  ! After processing the exception, the exception flags are
  ! cleared.
  CALL clr_fpscr_flags(IOR(FP_DIV_BY_ZERO,FP_INVALID))
END IF

get_round_mode

Type

The get_round_mode function returns the current floating-point rounding mode. The return value will be one of the constants FP_RND_RN, FP_RND_RZ, FP_RND_RP or FP_RND_RM. For more information on the rounding mode constants, see FPSCR constants.

Result Type and Attributes

An INTEGER(FPSCR_KIND)

Result Value

One of the constants FP_RND_RN, FP_RND_RZ, FP_RND_RP or FP_RND_RM.

Examples

USE, INTRINSIC :: XLF_FP_UTIL
INTEGER(FPSCR_KIND) MODE
 
MODE=get_round_mode()
IF (MODE .EQ. FP_RND_RZ) THEN
! ...
END IF

set_fpscr

Type

The set_fpscr function sets the floating-point status and control register (fpscr) of the processor to the value provided in the FPSCR argument, and returns the value of the register before the change.

Argument Type and Attributes

An INTEGER(FPSCR_KIND)

Result Type and Attributes

An INTEGER(FPSCR_KIND).

Result Value

The value of the register before it was set with set_fpscr.

Examples

USE, INTRINSIC :: XLF_FP_UTIL
INTEGER(FPSCR_KIND) FPSCR, OLD_FPSCR
 
FPSCR=get_fpscr()
 
! ...  Some changes are made to FPSCR  ...
 
OLD_FPSCR=set_fpscr(FPSCR)  ! OLD_FPSCR is assigned the value of
                            ! the register before it was
                            ! set with set_fpscr
 

set_fpscr_flags

Type

The set_fpscr_flags subroutine allows you to set the floating-point status and control register flags you specify in the MASK argument. Flags that you do not specify in MASK remain unaffected. MASK must be of type INTEGER(FPSCR_KIND). You can manipulate the MASK using the intrinsics described in Integer Bit Model.

For more information on the FPSCR constants, see FPSCR constants.

Examples

set_round_mode

Type

The set_round_mode function sets the current floating-point rounding mode, and returns the rounding mode before the change. You can set the mode to FP_RND_RN, FP_RND_RZ, FP_RND_RP or FP_RND_RM. For more information on the rounding mode constants, see FPSCR constants.

Argument Type and Attributes

Integer of kind FPSCR_KIND

Result Type and Attributes

Integer of kind FPSCR_KIND

Result Value

The rounding mode before the change.

Examples

USE XLF_FP_UTIL
INTEGER(FPSCR_KIND) MODE
 
MODE=set_round_mode(FP_RND_RZ)  ! The rounding mode is set to
                                ! round towards zero.  MODE is
! ...                           ! assigned the previous rounding
                                ! mode.
MODE=set_round_mode(MODE)       ! The rounding mode is restored.
 
IBM Copyright 2003