Language Reference

Detailed Descriptions of Intrinsic Procedures

The following is an alphabetical list of all generic names for intrinsic procedures.

For each procedure, several items of information are listed.

Notes:

1. The argument names listed in the title can be used as the names for keyword arguments when calling the procedure.

2. For those procedures with specific names, a table lists each specific name along with information about the specific function:
   • When a function return type or argument type is shown in lowercase, that indicates that the type is specified as shown, but the compiler may actually substitute a call to a different specific name depending on the settings of the -qintsize, -qrealsize, and -qautodbl options.

     For example, references to SINH are replaced by references to DSINH when -qrealsize=8 is in effect, and references to DSINH are replaced by references to QSINH.

   • The column labelled "Pass as Arg?" indicates whether or not you can pass that specific name as an actual argument to a procedure. Only the specific name of an intrinsic procedure may be passed as an actual argument, and then only for some specific names. A specific name passed this way may only be referenced with scalar arguments.

3. The index contains entries for each specific name, if you know the specific name but not the generic one.

ABORT ()

Terminates the program. It truncates all open output files to the current position of the file pointer, closes all open files, and sends the SIGIOT signal to the current process.

If the SIGIOT is neither caught nor ignored, and if the current directory is writable, the system produces a core file in the current directory.

Class

Subroutine

Examples

The following is an example of a statement using the ABORT subroutine.

IF (ERROR_CONDITION) CALL ABORT

The following is the output generated by the above program:

 /home/mark
IOT/Abort trap(coredump)

ABS (A)

Absolute value.

A

must be of type integer, real, or complex.

Class

Elemental function

Result Type and Attributes

The same as A except that if A is complex, the result is real.

Result Value

• If A is of type integer or real, the result is |A|.

• If A is of type complex with value (x,y), the result approximates

  
  
  
  
  

Examples

ABS ((3.0, 4.0)) has the value 5.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
IABS	any integer (1)	same as argument	yes
ABS	default real	default real	yes
DABS	double precision real	double precision real	yes
QABS	REAL(16)	REAL(16)	yes
CABS	default complex	default real	yes
CDABS	double complex	double precision real	yes
ZABS	double complex	double precision real	yes
CQABS	COMPLEX(16)	REAL(16)	yes

Notes:

1. The extension is the ability to specify a nondefault integer argument.

ACHAR (I)

Returns the character in a specified position of the ASCII collating sequence. It is the inverse of the IACHAR function.

I

must be of type integer.

Class

Elemental function

Result Type and Attributes

Character of length one with the same kind type parameter as KIND ('A').

Result Value

• If I has a value in the range 0 <= I <= 127, the result is the character in position I of the ASCII collating sequence, provided that the character corresponding to I is representable.

• If I is outside the allowed value range, the result is undefined.

Examples

ACHAR (88) has the value 'X'.

ACOS (X)

Arccosine (inverse cosine) function.

X

must be of type real with a value that satisfies the inequality |X| <= 1.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in radians and approximates arccos(X).

• It is in the range 0 <= ACOS(X) <= PI.

Examples

ACOS (1.0) has the value 0.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
ACOS	default real	default real	yes
DACOS	double precision real	double precision real	yes
QACOS	REAL(16)	REAL(16)	yes
QARCOS	REAL(16)	REAL(16)	yes

ACOSD (X)

Arccosine (inverse cosine) function. Result in degrees.

X

must be of type real. Its value must satisfy the inequality |X| <= 1.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in degrees and approximates arccos(X).

• It is in the range 0° <= ACOSD(X) <= 180°.

Examples

ACOSD (0.5) has the value 60.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
ACOSD	default real	default real	yes
DACOSD	double precision real	double precision real	yes
QACOSD	REAL(16)	REAL(16)	yes

ADJUSTL (STRING)

Adjust to the left, removing leading blanks and inserting trailing blanks.

STRING

must be of type character.

Class

Elemental function

Result Type and Attributes

Character of the same length and kind type parameter as STRING.

Result Value

The value of the result is the same as STRING except that any leading blanks have been deleted and the same number of trailing blanks have been inserted.

Examples

ADJUSTL (' WORD') has the value 'WORD '.

ADJUSTR (STRING)

Adjust to the right, removing trailing blanks and inserting leading blanks.

STRING

must be of type character.

Class

Elemental function

Result Type and Attributes

Character of the same length and kind type parameter as STRING.

Result Value

The value of the result is the same as STRING except that any trailing blanks have been deleted and the same number of leading blanks have been inserted.

Examples

ADJUSTR ('WORD ') has the value ' WORD'.

AIMAG (Z), IMAG (Z)

Imaginary part of a complex number.

Z

must be of type complex.

Class

Elemental function

Result Type and Attributes

Real with the same kind type parameter as Z.

Result Value

If Z has the value (x,y), the result has the value y.

Examples

AIMAG ((2.0, 3.0)) has the value 3.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
AIMAG	default complex	default real	yes
DIMAG	double complex	double precision real	yes
QIMAG	COMPLEX(16)	REAL(16)	yes

AINT (A, KIND)

Truncates to a whole number.

A

must be of type real.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• The result type is real.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of A.

Result Value

• If |A| < 1, the result is zero.

• If |A| >= 1, the result has a value equal to the integer whose magnitude is the largest integer that does not exceed the magnitude of A and whose sign is the same as the sign of A.

Examples

AINT(3.555) = 3.0
AINT(-3.555) = -3.0

Specific Name	Argument Type	Result Type	Pass As Arg?
AINT	default real	default real	yes
DINT	double precision real	double precision real	yes
QINT	REAL(16)	REAL(16)	yes

ALL (MASK, DIM)

Determines if all values in an entire array, or in each vector along a single dimension, are true.

MASK

is a logical array.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(mask). The corresponding actual argument must not be an optional dummy argument.

Class

Transformational function

Result Value

The result is a logical array with the same type and type parameters as MASK, and rank rank(mask)-1. If the dim is missing, or mask has a rank of one, the result is a scalar of type logical.

The shape of the result is (s₁, s₂, ..., s_(DIM-1), s_(DIM+1), ..., s_n), where n is the rank of mask.

Each element in the result array is .TRUE. only if all the elements given by mask(m₁, m₂, ..., m_(DIM-1), :, m_(DIM+1), ..., m_n), are true. When the result is a scalar, either because dim is not specified or because mask is of rank one, it is .TRUE. only if all elements of mask are true, or MASK has size zero.

Examples

! A is the array | 4 3 6 |, and B is the array | 3 5 2 |
!                | 2 4 1 |                     | 7 8 4 |
 
! Is every element in A less than the
! corresponding one in B?
      RES = ALL(A .LT. B)          ! result RES is false
 
! Are all elements in each column of A less than the
! corresponding column of B?
      RES = ALL(A .LT. B, DIM = 1) ! result RES is (f,t,f)
 
! Same question, but for each row of A and B.
      RES = ALL(A .LT. B, DIM = 2) ! result RES is (f,t)

R

ALLOCATED (ARRAY)

Indicate whether or not an allocatable array is currently allocated.

ARRAY

is an allocatable array whose allocation status you want to know.

Class

Inquiry function

Result Type and Attributes

Default logical scalar.

Result Value

The result corresponds to the allocation status of array: .TRUE. if it is currently allocated, .FALSE. if it is not currently allocated, or undefined if its allocation status is undefined.

Examples

INTEGER, ALLOCATABLE, DIMENSION(:) :: A
PRINT *, ALLOCATED(A)      ! A is not allocated yet.
ALLOCATE (A(1000))
PRINT *, ALLOCATED(A)      ! A is now allocated.
END

Related Information

"Allocatable Arrays", ALLOCATE, "Allocation Status".

ANINT (A, KIND)

Nearest whole number.

A

must be of type real.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• The result type is real.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of A.

Result Value

• If A > 0, ANINT(A) = AINT(A + 0.5)

• If A <= 0, ANINT(A) = AINT(A - 0.5)

Examples

ANINT(3.555) = 4.0
ANINT(-3.555) = -4.0

Specific Name	Argument Type	Result Type	Pass As Arg?
ANINT	default real	default real	yes
DNINT	double precision real	double precision real	yes
QNINT	REAL(16)	REAL(16)	yes

ANY (MASK, DIM)

Determines if any of the values in an entire array, or in each vector along a single dimension, are true.

MASK

is a logical array.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(mask). The corresponding actual argument must not be an optional dummy argument.

Class

Transformational function

Result Value

The result is a logical array of the same type and type parameters as MASK, and rank of rank(mask)-1. If the dim is missing, or mask has a rank of one, the result is a scalar of type logical.

The shape of the result is (s₁, s₂, ..., s_{(DIM -1)}, s_(DIM+1), ..., s_n), where n is the rank of mask.

Each element in the result array is .TRUE. if any of the elements given by mask(m₁, m₂, ..., m_(DIM-1), :, m_(DIM+1), ..., m_n) are true. When the result is a scalar, either because dim is not specified or because mask is of rank one, it is .TRUE. if any of the elements of mask are true.

Examples

! A is the array | 9 -6 7 |, and B is the array | 2 7 8 |
!                | 3 -1 5 |                     | 5 6 9 |
 
! Is any element in A greater than or equal to the
! corresponding element in B?
      RES = ANY(A .GE. B)          ! result RES is true
 
! For each column in A, is there any element in the column
! greater than or equal to the corresponding element in B?
      RES = ANY(A .GE. B, DIM = 1) ! result RES is (t,f,f)
 
! Same question, but for each row of A and B.
      RES = ANY(A .GE. B, DIM = 2) ! result RES is (t,f)

ASIN (X)

Arcsine (inverse sine) function.

X

must be of type real. Its value must satisfy the inequality |X| <= 1.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in radians and approximates arcsin(X).

• It is in the range -PI/2 <= ASIN(X) <= PI/2.

Examples

ASIN (1.0) approximates PI/2.

Specific Name	Argument Type	Result Type	Pass As Arg?
ASIN	default real	default real	yes
DASIN	double precision real	double precision real	yes
QASIN	REAL(16)	REAL(16)	yes
QARSIN	REAL(16)	REAL(16)	yes

ASIND (X)

Arcsine (inverse sine) function. Result in degrees.

X

must be of type real. Its value must satisfy the inequality |X| <= 1.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in degrees and approximates arcsin(X).

• It is in the range -90° <= ASIND(X) <= 90°

Examples

ASIND (0.5) has the value 30.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
ASIND	default real	default real	yes
DASIND	double precision real	double precision real	yes
QASIND	REAL(16)	REAL(16)	yes

ASSOCIATED (POINTER, TARGET)

Returns the association status of its pointer argument, or indicates whether the pointer is associated with the target.

POINTER

A pointer whose association status you want to test. It can be of any type. Its association status must not be undefined.

TARGET (optional)

A pointer or target that might or might not be associated with POINTER. Its association status must not be undefined.

Class

Inquiry function

Result Type and Attributes

Default logical scalar.

Result Value

If only the POINTER argument is specified, the result is .TRUE. if it is associated with any target and .FALSE. otherwise. If TARGET is also specified, the procedure tests whether POINTER is associated with TARGET, or with the same object that TARGET is associated with (if TARGET is also pointer).

The result is undefined if either POINTER or TARGET is associated with a zero-sized array, or if TARGET is a zero-sized array.

Objects with different types or shapes cannot be associated with each other.

Arrays with the same type and shape but different bounds can be associated with each other.

Examples

REAL, POINTER, DIMENSION(:,:) :: A
REAL, TARGET, DIMENSION(5,10) :: B, C
 
NULLIFY (A)
PRINT *, ASSOCIATED (A)   ! False, not associated yet
 
A => B
PRINT *, ASSOCIATED (A)   ! True, because A is
                          ! associated with B
 
PRINT *, ASSOCIATED (A,C) ! False, A is not
                          ! associated with C
END

ATAN (X)

Arctangent (inverse tangent) function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in radians and approximates arctan(X).

• It is in the range -PI/2 <= ATAN(X) <= PI/2.

Examples

ATAN (1.0) approximates PI/4.

Specific Name	Argument Type	Result Type	Pass As Arg?
ATAN	default real	default real	yes
DATAN	double precision real	double precision real	yes
QATAN	REAL(16)	REAL(16)	yes

ATAND (X)

Arctangent (inverse tangent) function. Result in degrees.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in degrees and approximates arctan(X).

• It is in the range -90° <= ATAND(X) <= 90°.

Examples

ATAND (1.0) has the value 45.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
ATAND	default real	default real	yes
DATAND	double precision real	double precision real	yes
QATAND	REAL(16)	REAL(16)	yes

ATAN2 (Y, X)

Arctangent (inverse tangent) function. The result is the principal value of the nonzero complex number (X, Y) formed by the real arguments Y and X.

Y

must be of type real.

X

must be of the same type and kind type parameter as Y. If Y has the value zero, X must not have the value zero.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in radians and has a value equal to the principal value of the argument of the complex number (X, Y).
• It is in the range -PI < ATAN2(Y, X) <= PI.
• If X <> 0, the result approximates arctan(Y/X).
• If Y > 0, the result is positive.
• If Y < 0, the result is negative.
• If Y = 0 and X > 0, the result is zero.
• If Y = 0 and X < 0, the result is PI.
• If X = 0, the absolute value of the result is PI/2.

Examples

ATAN2 (1.5574077, 1.0) has the value 1.0.

Given that:

Y = |  1   1 |        X = | -1  1 |
    | -1  -1 |            | -1  1 |

ATAN2 (Y, X) = |  3PI/4   PI/4 |
               | -3PI/4  -PI/4 |

Specific Name	Argument Type	Result Type	Pass As Arg?
ATAN2	default real	default real	yes
DATAN2	double precision real	double precision real	yes
QATAN2	REAL(16)	REAL(16)	yes

ATAN2D (Y, X)

Arctangent (inverse tangent) function. The result is the principal value of the nonzero complex number (X, Y) formed by the real arguments Y and X.

Y

must be of type real.

X

must be of the same type and kind type parameter as Y. If Y has the value zero, X must not have the value zero.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It is expressed in degrees and has a value equal to the principal value of the argument of the complex number (X, Y).
• It is in the range -180° < ATAN2D(Y,X) <= 180°.
• If X<>0, the result approximates arctan(Y/X).
• If Y>0, the result is positive.
• If Y<0, the result is negative.
• If Y=0 and X>0, the result is zero.
• If Y=0 and X<0, the result is 180°.
• If X=0, the absolute value of the result is 90°.

Examples

ATAN2D (1.5574077, 1.0) has the value 57.295780181 (approximately).

Given that:

Y = |  1.0   1.0 |     X = | -1.0   1.0 |
    | -1.0  -1.0 |         | -1.0   1.0 |

ATAN2D(Y,X) =  |  135.0000000   45.00000000 |
               | -135.0000000  -45.00000000 |

Specific Name	Argument Type	Result Type	Pass As Arg?
ATAN2D	default real	default real	yes
DATAN2D	double precision real	double precision real	yes
QATAN2D	REAL(16)	REAL(16)	yes

BIT_SIZE (I)

Returns the number of bits in an integer type. Because only the type of the argument is examined, the argument need not be defined.

I

must be of type integer.

Class

Inquiry function

Result Type and Attributes

Scalar integer with the same kind type parameter as I.

Result Value

The result is the number of bits in the integer data type of the argument:

    type                    bits
-----------                ------
 integer(1)                   08
 integer(2)                   16
 integer(4)                   32
 integer(8)                   64

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

BIT_SIZE (1_4) has the value 32, because the integer type with kind 4 (that is, a four-byte integer) contains 32 bits.

BTEST (I, POS)

Tests a bit of an integer value.

I

must be of type integer.

POS

must be of type integer. It must be nonnegative and be less than BIT_SIZE (I).

Class

Elemental function

Result Type and Attributes

The result is of type default logical.

Result Value

The result has the value .TRUE. if bit POS of I has the value 1 and the value .FALSE. if bit POS of I has the value 0.

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

BTEST (8, 3) has the value .TRUE..

If A has the value
   | 1 2 |
   | 3 4 |
the value of BTEST (A, 2) is
   | false false |
   | false true  |
and the value of BTEST (2, A) is
   | true  false |
   | false false |

See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
BTEST	any integer	default logical	yes

CEILING (A)

Returns the least integer greater than or equal to its argument.

A

must be of type real.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

The result has a value equal to the least integer greater than or equal to A. The result is undefined if this value cannot be represented in the default integer type.

Examples

CEILING (3.7) has the value 4. CEILING (-3.7) has the value -3.

CHAR (I, KIND)

Returns the character in the given position of the collating sequence associated with the specified kind type parameter. It is the inverse of the function ICHAR.

I

must be of type integer with a value in the range 0 <= I <= 127.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• Character of length one.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of the default character type.

Result Value

• The result is the character in position I of the collating sequence associated with the specified kind type parameter.

• ICHAR (CHAR (I, KIND (C))) must have the value I for 0 <= I <= 127 and CHAR (ICHAR (C), KIND (C)) must have the value C for any representable character.

Examples

CHAR (88) has the value 'X'.

Notes:

1. XL Fortran supports only the ASCII collating sequence.

Specific Name	Argument Type	Result Type	Pass As Arg?
CHAR	any integer	default character	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

CMPLX (X, Y, KIND)

Convert to complex type.

X

must be of type integer, real, or complex.

Y (optional)

must be of type integer or real. It must not be present if X is of type complex.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• It is of type complex.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of the default real type.

Result Value

• If Y is absent and X is not complex, it is as if Y were present with the value zero.

• If Y is absent and X is complex, it is as if Y were present with the value AIMAG(X).

• CMPLX(X, Y, KIND) has the complex value whose real part is REAL(X, KIND) and whose imaginary part is REAL(Y, KIND).

Examples

CMPLX (-3) has the value (-3.0, 0.0).

Specific Name	Argument Type	Result Type	Pass As Arg?
CMPLX	default real	default complex	no

Related Information

DCMPLX (X, Y), QCMPLX (X, Y).

CONJG (Z)

Conjugate of a complex number.

Z

must be of type complex.

Class

Elemental function

Result Type and Attributes

Same as Z.

Result Value

Given Z has the value (x, y), the result has the value (x, -y).

Examples

CONJG ((2.0, 3.0)) has the value (2.0, -3.0).

Specific Name	Argument Type	Result Type	Pass As Arg?
CONJG	default complex	default complex	yes
DCONJG	double complex	double complex	yes
QCONJG	COMPLEX(16)	COMPLEX(16)	yes

COS (X)

Cosine function.

X

must be of type real or complex.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It has a value that approximates cos(X).

• If X is of type real, X is regarded as a value in radians.

• If X is of type complex, the real part of X is regarded as a value in radians.

Examples

COS (1.0) has the value 0.54030231 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
COS	default real	default real	yes
DCOS	double precision real	double precision real	yes
QCOS	REAL(16)	REAL(16)	yes
CCOS (1)	default complex	default complex	yes
CDCOS (2)	double complex	double complex	yes
ZCOS (2)	double complex	double complex	yes
CQCOS (2)	COMPLEX(16)	COMPLEX(16)	yes

Given that X is a complex number in the form a + bi, where i = (-1)^½:

1. abs(b) must be less than or equal to 88.7228, a is any real value.

2. abs(b) must be less than or equal to 709.7827, a is any real value.

COSD (X)

Cosine function. Argument in degrees.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It approximates cos(X), where X has a value in degrees.

Examples

COSD (45.0) has the value 0.7071067691.

Specific Name	Argument Type	Result Type	Pass As Arg?
COSD	default real	default real	yes
DCOSD	double precision real	double precision real	yes
QCOSD	REAL(16)	REAL(16)	yes

COSH (X)

Hyperbolic cosine function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result value approximates cosh(X).

Examples

COSH (1.0) has the value 1.5430806 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
COSH (1)	default real	default real	yes
DCOSH (2)	double precision real	double precision real	yes
QCOSH (2)	REAL(16)	REAL(16)	yes

Notes:

1. abs(X) must be less than or equal to 89.4159.

2. abs(X) must be less than or equal to 709.7827.

COUNT (MASK, DIM)

Counts the number of true array elements in an entire logical array, or in each vector along a single dimension. Typically, the logical array is one that is used as a mask in another intrinsic.

MASK

is a logical array.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(mask). The corresponding actual argument must not be an optional dummy argument.

Class

Transformational function

Result Value

If DIM is present, the result is an integer array of rank rank(mask)-1. If dim is missing, or mask has a rank of one, the result is a scalar of type integer.

Each element of the resulting array (R(s₁, s₂, ..., s_(DIM-1), s_(DIM+1), ..., s_n)) equals the number of elements that are true in mask along the corresponding dimension (s₁, s₂, ..., s_(DIM-1), :, s_(DIM+1), ..., s_n).

If mask is a zero-sized array, the result equals zero.

Examples

! A is the array | T F F |, and B is the array | F F T |
!                | F T T |                     | T T T |
 
! How many corresponding elements in A and B
! are equivalent?
    RES = COUNT(A .EQV. B)        ! result RES is 3
 
! How many corresponding elements are equivalent
! in each column?
    RES = COUNT(A .EQV. B, DIM=1) ! result RES is (0,2,1)
 
! Same question, but for each row.
    RES = COUNT(A .EQV. B, DIM=2) ! result RES is (1,2)

CSHIFT (ARRAY, SHIFT, DIM)

Shifts the elements of all vectors along a given dimension of an array. The shift is circular; that is, elements shifted off one end are inserted again at the other end.

ARRAY

is an array of any type.

shift

must be a scalar integer if array has a rank of one; otherwise, it is a scalar integer or an integer expression of rank rank(array)-1.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array). If absent, it defaults to 1.

Class

Transformational function

Result Value

The result is an array with the same shape and the same data type as array.

If shift is a scalar, the same shift is applied to each vector. Otherwise, each vector array (s₁, s₂, ..., s_(DIM-1), :, s_(DIM+1), ..., s_n) is shifted according to the corresponding value in shift (s₁, s₂, ..., s_(DIM-1), s_(DIM+1), ..., s_n)

The absolute value of shift determines the amount of shift. The sign of shift determines the direction of the shift:

Positive shift

moves each element of the vector toward the beginning of the vector.

Negative shift

moves each element of the vector toward the end of the vector.

Zero shift

does no shifting. The value of the vector remains unchanged.

Examples

! A is the array | A D G |
!                | B E H |
!                | C F I |
 
! Shift the first column down one, the second column
! up one, and leave the third column unchanged.
       RES = CSHIFT (A, SHIFT = (/-1,1,0/), DIM = 1)
! The result is | C E G |
!               | A F H |
!               | B D I |
 
! Do the same shifts as before, but on the rows
! instead of the columns.
       RES = CSHIFT (A, SHIFT = (/-1,1,0/), DIM = 2)
! The result is | G A D |
!               | E H B |
!               | C F I |

CVMGx (TSOURCE, FSOURCE, MASK)

The conditional vector merge functions ( CVMGM, CVMGN, CVMGP, CVMGT, and CVMGZ) enable you to port existing code that contains these functions.

Calling them is very similar to calling

MERGE ( TSOURCE, FSOURCE, arith_expr .op. 0 )
or
MERGE ( TSOURCE, FSOURCE, logical_expr .op. .TRUE. )

TSOURCE

is a scalar or array expression of type LOGICAL, INTEGER, or REAL and any kind except 1.

FSOURCE

is a scalar or array expression with the same type and type parameters as TSOURCE.

MASK

is a scalar or array expression of type INTEGER or REAL (for CVMGM, CVMGN, CVMGP, and CVMGZ) or LOGICAL (for CVMGT), and any kind except 1. If it is an array, it must conform in shape to TSOURCE and FSOURCE.

If only one of TSOURCE and FSOURCE is typeless, the typeless argument acquires the type of the other argument. If both TSOURCE and FSOURCE are typeless, both arguments acquire the type of MASK. If MASK is also typeless, both TSOURCE and FSOURCE are treated as default integers. If MASK is typeless, it is treated as a default logical for the CVMGT function and as a default integer for the other CVMGx functions.

Class

Elemental function

Result Type and Attributes

Same as TSOURCE and FSOURCE.

Result Value

The function result is the value of either the first argument or second argument, depending on the result of the test performed on the third argument. If the arguments are arrays, the test is performed for each element of the MASK array and the result may contain some elements from TSOURCE and some elements from FSOURCE.

Table 15. Result Values for CVMGx Intrinsic Procedures

Explanation	Function Return Value	Generic Name
Test for positive or zero	TSOURCE if MASK>=0 FSOURCE if MASK<0	CVMGP
Test for negative	TSOURCE if MASK<0 FSOURCE if MASK>=0	CVMGM
Test for zero	TSOURCE if MASK=0 FSOURCE if MASK<>0	CVMGZ
Test for nonzero	TSOURCE if MASK<>0 FSOURCE if MASK=0	CVMGN
Test for true	TSOURCE if MASK= .true. FSOURCE if MASK=.false.	CVMGT

DATE_AND_TIME (DATE, TIME, ZONE, VALUES)

Returns data from the real-time clock and the date in a form compatible with the representations defined in ISO 8601:1988.

DATE (optional)

must be scalar and of type default character, and must have a length of at least eight to contain the complete value. It is an INTENT(OUT) argument. Its left-most eight characters are set to a value of the form CCYYMMDD, where CC is the century, YY the year within the century, MM the month within the year, and DD the day within the month. If no date is available, they are set to blank.

TIME (optional)

must be scalar and of type default character, and must have a length of at least ten in order to contain the complete value. It is an INTENT(OUT) argument. Its left-most ten characters are set to a value of the form hhmmss.sss, where hh is the hour of the day, mm is the minutes of the hour, and ss.sss is the seconds and milliseconds of the minute. If no is clock available, they are set to blank.

ZONE (optional)

must be scalar and of type default character, and must have a length at least five in order to contain the complete value. It is an INTENT(OUT) argument. Its left-most five characters are set to a value of the form ±hhmm, where hh and mm are the time difference with respect to Coordinated Universal Time (UTC) in hours and parts of an hour (4) expressed in minutes, respectively. If no clock is available, they are set to blank.

VALUES (optional)

must be of type default integer and of rank one. It is an INTENT(OUT) argument. Its size must be at least eight. The values returned in VALUES are as follows:

VALUES(1)

is the year (for example, 1995), or -HUGE (0) if no date is available.

VALUES(2)

is the month of the year, or -HUGE (0) if no date is available.

VALUES(3)

is the day of the month, or -HUGE (0) if no date is available.

VALUES(4)

is the time difference with respect to Coordinated Universal Time (UTC) in minutes, or -HUGE (0) if this information is not available.

VALUES(5)

is the hour of the day, in the range 0 to 23, or -HUGE (0) if there is no clock.

VALUES(6)

is the minutes of the hour, in the range 0 to 59, or -HUGE (0) if there is no clock.

VALUES(7)

is the seconds of the minute, in the range 0 to 60, or -HUGE (0) if there is no clock.

VALUES (8)

is the milliseconds of the second, in the range 0 to 999, or -HUGE (0) if there is no clock.

Class

Subroutine

Examples

The following program:

INTEGER DATE_TIME (8)
CHARACTER (LEN = 10) BIG_BEN (3)
CALL DATE_AND_TIME (BIG_BEN (1), BIG_BEN (2), &
                    BIG_BEN (3), DATE_TIME)

if executed in Geneva, Switzerland on 1985 April 12 at 15:27:35.5, would have assigned the value 19850412 to BIG_BEN(1), the value 152735.500 to BIG_BEN(2), the value +0100 to BIG_BEN(3), and the following values to DATE_TIME: 1985, 4, 12, 60, 15, 27, 35, 500.

Note that UTC is defined by CCIR Recommendation 460-2 (also known as Greenwich Mean Time).

DBLE (A)

Convert to double precision real type.

A

must be of type integer, real, or complex.

Class

Elemental function

Result Type and Attributes

Double precision real.

Result Value

• If A is of type double precision real, DBLE(A) = A.

• If A is of type integer or real, the result has as much precision of the significant part of A as a double precision real datum can contain.

• If A is of type complex, the result has as much precision of the significant part of the real part of A as a double precision real datum can contain.

Examples

DBLE (-3) has the value -3.0D0.

Specific Name	Argument Type	Result Type	Pass As Arg?
DFLOAT	any integer	double precision real	no
DBLE	default real	double precision real	no
DBLEQ	REAL(16)	REAL(8)	no

DCMPLX (X, Y)

Convert to double complex type.

X

must be of type integer, real, or complex.

Y (optional)

must be of type integer or real. It must not be present if X is of type complex.

Class

Elemental function

Result Type and Attributes

It is of type double complex.

Result Value

• If Y is absent and X is not complex, it is as if Y were present with the value of zero.

• If Y is absent and X is complex, it is as if Y were present with the value AIMAG(X).

• DCMPLX(X, Y) has the complex value whose real part is REAL(X, KIND=8) and whose imaginary part is REAL(Y, KIND=8).

Examples

DCMPLX (-3) has the value (-3.0D0, 0.0D0).

Specific Name	Argument Type	Result Type	Pass As Arg?
DCMPLX	double precision real	double complex	no

Related Information

CMPLX (X, Y, KIND), QCMPLX (X, Y).

DIGITS (X)

Returns the number of significant digits for numbers whose type and kind type parameter are the same as the argument.

X

must be of type integer or real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

• If X is of type integer, the number of the significant digits of X is:

      type                    bits
  -----------                ------
   integer(1)                   07
   integer(2)                   15
   integer(4)                   31
   integer(8)                   63
  

• If X is of type real, the number of significant bits of X is:

     type                    bits
  ----------                ------
  real(4)                      24
  real(8)                      53
  real(16)                    106
  

Examples

DIGITS (X) = 63, where X is of type integer(8) (see "Data Representation Models").

DIM (X, Y)

The difference X-Y if it is positive; otherwise zero.

X

must be of type integer or real.

Y

must be of the same type and kind type parameter as X.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• If X > Y, the value of the result is X - Y.

• If X <= Y, the value of the result is zero.

Examples

DIM (-3.0, 2.0) has the value 0.0. DIM (-3.0, -4.0) has the value 1.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
IDIM	any integer (1)	same as argument	yes
DIM	default real	default real	yes
DDIM	double precision real	double precision real	yes
QDIM	REAL(16)	REAL(16)	yes

Notes:

1. The extension is the ability to specify a nondefault integer argument.

DOT_PRODUCT (VECTOR_A, VECTOR_B)

Computes the dot product on two vectors.

VECTOR_A

is a vector with a numeric or logical data type.

VECTOR_B

must be of numeric type if VECTOR_A is of numeric type and of logical type if VECTOR_A is of logical type. It must be the same size as VECTOR_A.

Class

Transformational function

Result Value

The result is a scalar whose data type depends on the data type of the two vectors, according to the rules in Table 3 and Table 4.

If either vector is a zero-sized array, the result equals zero when it has a numeric data type, and false when it is of type logical.

If vctr_a is of type integer or real, the result value equals SUM(vctr_a * vctr_b).

If vctr_a is of type complex, the result equals SUM(CONJG(vctr_a) * vctr_b).

If vctr_a is of type logical, the result equals ANY(vctr_a .AND. vctr_b).

Examples

! A is (/ 3, 1, -5 /), and B is (/ 6, 2, 7 /).
      RES = DOT_PRODUCT (A, B)
! calculated as
!   ( (3*6) + (1*2) + (-5*7) )
! = (   18  +    2  +  (-35) )
! =  -15

DPROD (X, Y)

Double precision real product.

X

must be of type default real.

Y

must be of type default real.

Class

Elemental function

Result Type and Attributes

Double precision real.

Result Value

The result has a value equal to the product of X and Y.

Examples

DPROD (-3.0, 2.0) has the value -6.0D0.

Specific Name	Argument Type	Result Type	Pass As Arg?
DPROD	default real	double precision real	yes
QPROD	double precision real	REAL(16)	yes

EOSHIFT (ARRAY, SHIFT, BOUNDARY, DIM)

Shifts the elements of all vectors along a given dimension of an array. The shift is end-off; that is, elements shifted off one end are lost, and copies of boundary elements are shifted in at the other end.

ARRAY

is an array of any type.

SHIFT

is a scalar of type integer if array has a rank of 1; otherwise, it is a scalar integer or an integer expression of rank rank(array)-1.

BOUNDARY (optional)

is of the same type and type parameters as array. If array has a rank of 1, boundary must be scalar; otherwise, it is a scalar or an expression of rank rank(array)-1.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array).

Class

Transformational function

Result Value

The result is an array with the same shape and data type as array.

The absolute value of shift determines the amount of shift. The sign of shift determines the direction of the shift:

Positive shift

moves each element of the vector toward the beginning of the vector. If an element is taken off the beginning of a vector, its value is replaced by the corresponding value from boundary at the end of the vector.

Negative shift

moves each element of the vector toward the end of the vector. If an element is taken off the end of a vector, its value is replaced by the corresponding value from boundary at the beginning of the vector.

Zero shift

does no shifting. The value of the vector remains unchanged.

Result Value

If boundary is a scalar value, this value is used in all shifts.

If boundary is an array of values, the values of the array elements of boundary with subscripts (s₁, s₂, ..., s_(DIM-1), s_(DIM+1), ..., s_n) are used for that dimension.

If boundary is not specified, the following default values are used, depending on the data type of array:

character

' ' (one blank)

logical

false

integer

0

real

0.0

complex

(0.0, 0.0)

Examples

! A is | 1.1 4.4 7.7 |, SHIFT is S=(/0, -1, 1/),
!      | 2.2 5.5 8.8 |
!      | 3.3 6.6 9.9 |
! and BOUNDARY is the array B=(/-0.1, -0.2, -0.3/).
 
! Leave the first column alone, shift the second
! column down one, and shift the third column up one.
RES = EOSHIFT (A, SHIFT = S, BOUNDARY = B, DIM = 1)
! The result is | 1.1 -0.2  8.8 |
!               | 2.2  4.4  9.9 |
!               | 3.3  5.5 -0.3 |
 
! Do the same shifts as before, but on the
! rows instead of the columns.
RES = EOSHIFT (A, SHIFT = S, BOUNDARY = B, DIM = 2)
! The result is |  1.1  4.4  7.7 |
!               | -0.2  2.2  5.5 |
!               |  6.6  9.9 -0.3 |

EPSILON (X)

Returns a positive model number that is almost negligible compared to unity in the model representing numbers of the same type and kind type parameter as the argument.

X

must be of type real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Scalar of the same type and kind type parameter as X.

Result Value

The result is

2.0ei01 - DIGITS(X)

type                      EPSILON(X)
----                   ------------------
real(4)                   02E0 ** (-23)
real(8)                   02D0 ** (-52)
real(16)                  02Q0 ** (-105)

Examples

EPSILON (X) = 1.1920929E-07 for X of type real(4). See "Real Data Model".

ERF (X)

Error function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• The result value approximates erf(X).

• The result is in the range -1 <= ERF(X) <= 1

Examples

ERF (1.0) has the value 0.8427007794 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
ERF	default real	default real	yes
DERF	double precision real	double precision real	yes
QERF	REAL(16)	REAL(16)	yes

ERFC (X)

Complementary error function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• The result has a value equal to 1-ERF(X).

• The result is in the range 0 <= ERFC(X) <= 2

Examples

ERFC (1.0) has the value 0.1572992057 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
ERFC	default real	default real	yes
DERFC	double precision real	double precision real	yes
QERFC	REAL(16)	REAL(16)	yes

EXP (X)

Exponential.

X

must be of type real or complex.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• The result approximates e^x.

• If X is of type complex, its imaginary part is regarded as a value in radians.

Examples

EXP (1.0) has the value 2.7182818 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
EXP (1)	default real	default real	yes
DEXP (2)	double precision real	double precision real	yes
QEXP (2)	REAL(16)	REAL(16)	yes
CEXP (3a)	default complex	default complex	yes
CDEXP (3b)	double complex	double complex	yes
ZEXP (3b)	double complex	double complex	yes
CQEXP (3b)	COMPLEX(16)	COMPLEX(16)	yes

Notes:

1. X must be less than or equal to 88.7228.

2. X must be less than or equal to 709.7827.

3. When X is a complex number in the form a + bi, where i = (-1) ^½:

   1. a must be less than or equal to 88.7228, b is any real value.

   2. a must be less than or equal to 709.7827, b is any real value.

EXPONENT (X)

Returns the exponent part of the argument when represented as a model number.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

• If X <> 0, the result is the exponent of X (which is always within the range of a default integer).

• If X = 0, the exponent of X is zero.

Examples

EXPONENT (10.2) = 4. See "Real Data Model"

FLOOR (A)

Returns the greatest integer less than or equal to its argument.

A

must be of type real.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

The result has the value equal to the greatest integer less than or equal to A. The result is undefined if this value cannot be represented in the default integer type.

Examples

FLOOR (3.7) has the value 3. FLOOR (-3.7) has the value -4.

FRACTION (X)

Returns the fractional part of the model representation of the argument value.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result is:

X * 
(2.0-EXPONENT(X))

Examples

FRACTION(10.2) = 
2-4 * 10.2 &approx. 0.6375

GAMMA (X)

Gamma function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result has a value that approximates Gamma(X).

Examples

GAMMA (1.0) has the value 1.0.

GAMMA (10.0) has the value 362880.0 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
GAMMA (1)	default real	default real	yes
DGAMMA (2)	double precision real	double precision real	yes
QGAMMA (3)	REAL(16)	REAL(16)	yes

X must satisfy the inequality:

1. -2.0**23 < X <= 35.0401, except for nonpositive integral values

2. -2.0**52 < X <= 171.6243, except for nonpositive integral values

3. -2.0**105 < X <= 171.6243, except for nonpositive integral values

GETENV (NAME, VALUE)

Determines the value of the specified environment variable.

NAME

is a character string that identifies the name of the operating-system environment variable. The string is case-significant. It is an INTENT(IN) argument that must be scalar of type default character.

VALUE

holds the value of the environment variable when the subroutine returns. It is an INTENT(OUT) argument that must be scalar of type default character.

Class

Subroutine

Result Value

The result is returned in the VALUE argument, not as a function result variable.

If the environment variable specified in the NAME argument does not exist, the VALUE argument contains blanks.

Examples

      CHARACTER (LEN=16)   ENVDATA
      CALL GETENV('HOME', VALUE=ENVDATA)
! Print the value.
      PRINT *, ENVDATA
! Show how it is blank-padded on the right.
      WRITE(*, '(Z32)') ENVDATA
      END

The following is sample output generated by the above program:

 /home/mark
2F686F6D652F6D61726B202020202020

Related Information

See the getenv subroutine in the Technical Reference: Base Operating System and Extensions Volume 1 for details about the operating-system-level implementation.

HFIX (A)

Convert from REAL(4) to INTEGER(2).

This procedure is a specific function, not a generic function.

A

must be of type REAL(4).

Class

Elemental function

Result Type and Attributes

An INTEGER(2) scalar or array.

Result Value

• If |A| < 1, INT (A) has the value 0;

• If |A| >= 1, INT (A) is the integer whose magnitude is the largest integer that does not exceed the magnitude of A and whose sign is the same as the sign of A.

• The result is undefined if the result cannot be represented in an INTEGER(2).

Examples

HFIX (-3.7) has the value -3.

Specific Name	Argument Type	Result Type	Pass As Arg?
HFIX	REAL(4)	INTEGER(2)	no

HUGE (X)

Returns the largest number in the model representing numbers of the same type and kind type parameter as the argument.

X

must be of type integer or real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Scalar of the same type and kind type parameter as X.

Result Value

• If X is of any integer type, the result is:

  2DIGITS(X) - 1
  

• If X is of any real type, the result is:

  (1.0 - 2.0-DIGITS(X)) * 
  (2.0MAXEXPONENT(X))
  

Examples

HUGE (X) = (1D0 - 2D0**-53) * (2D0**1024) for X of type real(8).

HUGE (X) = (2**63) - 1 for X of type integer(8).

See "Data Representation Models".

IACHAR (C)

Returns the position of a character in the ASCII collating sequence.

C

must be of type default character and of length one.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

• If C is in the collating sequence defined by the codes specified in ISO 646:1983 (International Reference Version), the result is the position of C in that sequence and satisfies the inequality (0 <= IACHAR (C) <= 127). An undefined value is returned if C is not in the ASCII collating sequence.

• The results are consistent with the LGE, LGT, LLE, and LLT lexical comparison functions. For example, LLE (C, D) is true, so IACHAR (C) .LE. IACHAR (D) is true too.

Examples

IACHAR ('X') has the value 88.

IAND (I, J)

Performs a logical AND.

I

must be of type integer.

J

must be of type integer with the same kind type parameter as I.

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value obtained by combining I and J bit-by-bit according to the following table:

I   J   IAND (I,J)
------------------
1   1       1
1   0       0
0   1       0
0   0       0

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

IAND (1, 3) has the value 1. See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
IAND	any integer	same as argument	yes
AND	any integer	same as argument	yes

IBCLR (I, POS)

Clears one bit to zero.

I

must be of type integer.

POS

must be of type integer. It must be nonnegative and less than BIT_SIZE (I).

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value of the sequence of bits of I, except that bit POS of I is set to zero.

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

IBCLR (14, 1) has the result 12.

If V has the value (/1, 2, 3, 4/), the value of IBCLR (POS = V, I = 31) is (/29, 27, 23, 15/).

See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
IBCLR	any integer	same as argument	yes

IBITS (I, POS, LEN)

Extracts a sequence of bits.

I

must be of type integer.

POS

must be of type integer. It must be nonnegative and POS + LEN must be less than or equal to BIT_SIZE (I).

LEN

must be of type integer and nonnegative.

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value of the sequence of LEN bits in I beginning at bit POS, right-adjusted and with all other bits zero.

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

IBITS (14, 1, 3) has the value 7. See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
IBITS	any integer	same as argument	yes

IBSET (I, POS)

Sets one bit to one.

I

must be of type integer.

POS

must be of type integer. It must be nonnegative and less than BIT_SIZE (I).

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value of the sequence of bits of I, except that bit POS of I is set to one.

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

IBSET (12, 1) has the value 14.

If V has the value (/1, 2, 3, 4/), the value of IBSET (POS = V, I = 0) is (/2, 4, 8, 16/).

See .

Specific Name	Argument Type	Result Type	Pass As Arg?
IBSET	any integer	same as I	yes

ICHAR (C)

Returns the position of a character in the collating sequence associated with the kind type parameter of the character.

C

must be of type character and of length one. Its value must be that of a representable character.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

• The result is the position of C in the collating sequence associated with the kind type parameter of C and is in the range 0 <= ICHAR (C) <= 127.

• For any representable characters C and D, C .LE. D is true if and only if ICHAR (C) .LE. ICHAR (D) is true and C .EQ. D is true if and only if ICHAR (C) .EQ. ICHAR (D) is true.

Examples

ICHAR ('X') has the value 88 in the ASCII collating sequence.

Notes:

1. XL Fortran supports only the ASCII collating sequence.

Specific Name	Argument Type	Result Type	Pass As Arg?
ICHAR	default character	default integer	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

IEOR (I, J)

Performs an exclusive OR.

I

must be of type integer.

J

must be of type integer with the same kind type parameter as I.

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value obtained by combining I and J bit-by-bit according to the following truth table:

I   J  IEOR (I,J)
-----------------
1   1      0
1   0      1
0   1      1
0   0      0

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

IEOR (1, 3) has the value 2. See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
IEOR	any integer	same as argument	yes
XOR	any integer	same as argument	yes

ILEN (I)

Returns one less than the length, in bits, of the twos complement representation of an integer.

I

is of type integer

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

• If I is negative, ILEN(I)=CEILING(LOG2(-I))

• If I is nonnegative, ILEN(I)=CEILING(LOG2(I+1))

Examples

I=ILEN(4)  ! 3
J=ILEN(-4) ! 2

IMAG (Z)

Identical to AIMAG.

Related Information

AIMAG (Z), IMAG (Z).

INDEX (STRING, SUBSTRING, BACK)

Returns the starting position of a substring within a string.

STRING

must be of type character.

SUBSTRING

must be of type character with the same kind type parameter as STRING.

BACK (optional)

must be of type logical.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

• Case (i): If BACK is absent or present with the value .FALSE., the result is the minimum positive value of I such that STRING (I : I + LEN (SUBSTRING) - 1) = SUBSTRING or zero if there is no such value. Zero is returned if LEN (STRING) < LEN (SUBSTRING). One is returned if LEN (SUBSTRING) = 0.

• Case (ii): If BACK is present with the value .TRUE., the result is the maximum value of I less than or equal to LEN (STRING) - LEN (SUBSTRING) + 1, such that STRING (I : I + LEN (SUBSTRING) - 1) =  SUBSTRING or zero if there is no such value. Zero is returned if LEN (STRING) < LEN (SUBSTRING) and LEN (STRING) + 1 is returned if LEN (SUBSTRING) = 0.

Examples

INDEX ('FORTRAN', 'R') has the value 3.

INDEX ('FORTRAN', 'R', BACK = .TRUE.) has the value 5.

Specific Name	Argument Type	Result Type	Pass As Arg?
INDEX	default character	default integer	yes (1)

Note:

When this specific name is passed as an argument, the procedure can only be referenced without the BACK optional argument.

INT (A, KIND)

Convert to integer type.

A

must be of type integer, real, or complex.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• Integer.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of the default integer type.

Result Value

• Case (i): If A is of type integer, INT (A) = A.

• Case (ii): If A is of type real, there are two cases: if |A| < 1, INT (A) has the value 0; if |A| >= 1, INT (A) is the integer whose magnitude is the largest integer that does not exceed the magnitude of A and whose sign is the same as the sign of A.

• Case (iii): If A is of type complex, INT (A) is the value obtained by applying the case (ii) rule to the real part of A.

• The result is undefined if it cannot be represented in the specified integer type.

Examples

INT (-3.7) has the value -3.

Specific Name	Argument Type	Result Type	Pass As Arg?
INT	default real	default integer	no
IDINT	double precision real	default integer	no
IFIX	default real	default integer	no
IQINT	REAL(16)	default integer	no

IOR (I, J)

Performs an inclusive OR.

I

must be of type integer.

J

must be of type integer with the same kind type parameter as I.

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value obtained by combining I and J bit-by-bit according to the following truth table:

I   J   IOR (I,J)
-----------------
1   1      1
1   0      1
0   1      1
0   0      0

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

IOR (1, 3) has the value 3. See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
IOR	any integer	same as argument	yes
OR	any integer	same as argument	yes

ISHFT (I, SHIFT)

Performs a logical shift.

I

must be of type integer.

SHIFT

must be of type integer. The absolute value of SHIFT must be less than or equal to BIT_SIZE (I).

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

• The result has the value obtained by shifting the bits of I by SHIFT positions.

• If SHIFT is positive, the shift is to the left; if SHIFT is negative, the shift is to the right; and, if SHIFT is zero, no shift is performed.

• Bits shifted out from the left or from the right, as appropriate, are lost.

• Vacated bits are filled with zeros.

• The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

ISHFT (3, 1) has the result 6. See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
ISHFT	any integer	same as argument	yes

ISHFTC (I, SHIFT, SIZE)

Performs a circular shift of the right-most bits; that is, bits shifted off one end are inserted again at the other end.

I

must be of type integer.

SHIFT

must be of type integer. The absolute value of SHIFT must be less than or equal to SIZE.

SIZE (optional)

must be of type integer. The value of SIZE must be positive and must not exceed BIT_SIZE (I). If SIZE is absent, it is as if it were present with the value of BIT_SIZE (I).

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value obtained by shifting the SIZE right-most bits of I circularly by SHIFT positions. If SHIFT is positive, the shift is to the left; if SHIFT is negative, the shift is to the right; and, if SHIFT is zero, no shift is performed. No bits are lost. The unshifted bits are unaltered.

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

ISHFTC (3, 2, 3) has the value 5. See "Integer Bit Model".

Specific Name	Argument Type	Result Type	Pass As Arg?
ISHFTC	any integer	same as argument	yes (1)

Notes:

1. When this specific name is passed as an argument, the procedure can only be referenced with all three arguments.

KIND (X)

Returns the value of the kind type parameter of X.

X

may be of any intrinsic type.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result has a value equal to the kind type parameter value of X.

Kind type parameters supported by XL Fortran are defined in "Intrinsic Types".

Examples

KIND (0.0) has the kind type parameter value of the default real type.

LBOUND (ARRAY, DIM)

Returns the lower bound of each dimension in an array, or the lower bound of a specified dimension.

ARRAY

is the array whose lower bounds you want to determine. Its bounds must be defined; that is, it must not be a disassociated pointer or an allocatable array that is not allocated.

DIM (optional)

is an integer scalar in the range 1 <= DIM <=  rank(array). The corresponding actual argument must not be an optional dummy argument.

Class

Inquiry function

Result Type and Attributes

Default integer.

If DIM is present, the result is a scalar. If DIM is not present, the result is a one-dimensional array with one element for each dimension in array.

Result Value

Each element in the result corresponds to a dimension of array.

• If array is a whole array or array structure component, LBOUND(array, DIM) is equal to the lower bound for subscript DIM of array.

  The only exception is for a dimension that is zero-sized and ARRAY is not an assumed-size array of rank DIM, In such a case, the corresponding element in the result is one regardless of the value declared for the lower bound.

• If array is an array section or expression that is not a whole array or array structure component, each element has the value one.

Examples

        REAL A(1:10, -4:5, 4:-5)
 
        RES=LBOUND( A )
! The result is (/ 1, -4, 1 /).
 
        RES=LBOUND( A(:,:,:) )
        RES=LBOUND( A(4:10,-4:1,:) )
! The result in both cases is (/ 1, 1, 1 /)
! because the arguments are array sections.

LEADZ (I)

Returns the number of leading zero-bits in the binary representation of an integer.

I

must be of type integer.

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result is the count of zero-bits to the left of the left-most one-bit for an integer.

Examples

 I = LEADZ(0_4)  ! I=32
 J = LEADZ(4_4)  ! J=29
 K = LEADZ(-1_4) ! K=0

LEN (STRING)

Returns the length of a character entity. The argument to this function need not be defined.

STRING

must be of type character. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result has a value equal to the number of characters in STRING if it is scalar or in an element of STRING if it is array valued.

Examples

If C is declared by the statement

 CHARACTER (11) C(100)

LEN (C) has the value 11.

Specific Name	Argument Type	Result Type	Pass As Arg?
LEN	default character	default integer	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

LEN_TRIM (STRING)

Returns the length of the character argument without counting trailing blank characters.

STRING

must be of type character.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

The result has a value equal to the number of characters remaining after any trailing blanks in STRING are removed. If the argument contains no nonblank characters, the result is zero.

Examples

LEN_TRIM (' A B ') has the value 4. LEN_TRIM ('  ') has the value 0.

LGAMMA (X)

Log of gamma function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result has a value equal to log_eGamma(X).

Examples

LGAMMA (1.0) has the value 0.0.

LGAMMA (10.0) has the value 12.80182743 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
LGAMMA	default real	default real	yes
LGAMMA	double precision real	double precision real	yes
ALGAMA (1)	default real	default real	yes
DLGAMA (2)	double precision real	double precision real	yes
QLGAMA (3)	REAL(16)	REAL(16)	yes

X must satisfy the inequality:

1. 0 < X <= 4.0850E36.

2. 2.3561D-304 <= X <= 2¹⁰¹⁴.

3. 2.3561Q-304 <= X <= 2¹⁰¹⁴.

LGE (STRING_A, STRING_B)

Test whether a string is lexically greater than or equal to another string, based on the ASCII collating sequence.

STRING_A

must be of type default character.

STRING_B

must be of type default character.

Class

Elemental function

Result Type and Attributes

Default logical.

Result Value

• If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.

• If either string contains a character not in the ASCII character set, the result is undefined.

• The result is true if the strings are equal or if STRING_A follows STRING_B in the ASCII collating sequence; otherwise, the result is false. Note that the result is true if both STRING_A and STRING_B are of zero length.

Examples

LGE ('ONE', 'TWO') has the value .FALSE..

Specific Name	Argument Type	Result Type	Pass As Arg?
LGE	default character	default logical	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

LGT (STRING_A, STRING_B)

Test whether a string is lexically greater than another string, based on the ASCII collating sequence.

STRING_A

must be of type default character.

STRING_B

must be of type default character.

Class

Elemental function

Result Type and Attributes

Default logical.

Result Value

• If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.

• If either string contains a character not in the ASCII character set, the result is undefined.

• The result is true if STRING_A follows STRING_B in the ASCII collating sequence; otherwise, the result is false. Note that the result is false if both STRING_A and STRING_B are of zero length.

Examples

LGT ('ONE', 'TWO') has the value .FALSE..

Specific Name	Argument Type	Result Type	Pass As Arg?
LGT	default character	default logical	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

LLE (STRING_A, STRING_B)

Test whether a string is lexically less than or equal to another string, based on the ASCII collating sequence.

STRING_A

must be of type default character.

STRING_B

must be of type default character.

Class

Elemental function

Result Type and Attributes

Default logical.

Result Value

• If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.

• If either string contains a character not in the ASCII character set, the result is undefined.

• The result is true if the strings are equal or if STRING_A precedes STRING_B in the ASCII collating sequence; otherwise, the result is false. Note that the result is true if both STRING_A and STRING_B are of zero length.

Examples

LLE ('ONE', 'TWO') has the value .TRUE..

Specific Name	Argument Type	Result Type	Pass As Arg?
LLE	default character	default logical	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

LLT (STRING_A, STRING_B)

Test whether a string is lexically less than another string, based on the ASCII collating sequence.

STRING_A

must be of type default character.

STRING_B

must be of type default character.

Class

Elemental function

Result Type and Attributes

Default logical.

Result Value

• If the strings are of unequal length, the comparison is made as if the shorter string were extended on the right with blanks to the length of the longer string.

• If either string contains a character not in the ASCII character set, the result is undefined.

• The result is true if STRING_A precedes STRING_B in the ASCII collating sequence; otherwise, the result is false. Note that the result is false if both STRING_A and STRING_B are of zero length.

Examples

LLT ('ONE', 'TWO') has the value .TRUE..

Specific Name	Argument Type	Result Type	Pass As Arg?
LLT	default character	default logical	yes (1)

Notes:

1. The extension is the ability to pass the name as an argument.

LOC (X)

Returns the address of X that can then be used to define an integer POINTER.

X

is the data object whose address you want to find. It must not be an undefined or disassociated pointer, or be a parameter. If it is a zero-sized array, it must be storage associated with a non-zero-sized storage sequence. If it is an array section, the storage of the array section must be contiguous.

Class

Inquiry function

Result Type and Attributes

LOC returns INTEGER(4) in 32-bit and INTEGER(8) in 64-bit.

Result Value

The result is the address of the data object, or, if X is a pointer, the address of the associated target. The result is undefined if the argument is not valid.

Examples

INTEGER A,B
POINTER (P,I)
 
P=LOC(A)
P=LOC(B)
END

LOG (X)

Natural logarithm.

X

must be of type real or complex.

• If X is real, its value must be greater than zero.

• If X is complex, its value must not be zero.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It has a value approximating log_eX.

• For complex arguments, LOG ((a,b)) approximates LOG (ABS((a,b))) + ATAN2((b,a)).

  If the argument type is complex, the result is the principal value of the imaginary part &omega. in the range -PI < &omega. <= PI. If the real part of the argument is less than zero and its imaginary part is zero, the imaginary part of the result approximates PI.

Examples

LOG (10.0) has the value 2.3025851 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
ALOG	default real	default real	yes
DLOG	double precision real	double precision real	yes
QLOG	REAL(16)	REAL(16)	yes
CLOG	default complex	default complex	yes
CDLOG	double complex	double complex	yes
ZLOG	double complex	double complex	yes
CQLOG	COMPLEX(16)	COMPLEX(16)	yes

LOG10 (X)

Common logarithm.

X

must be of type real. The value of X must be greater than zero.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result has a value equal to log₁₀X.

Examples

LOG10 (10.0) has the value 1.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
ALOG10	default real	default real	yes
DLOG10	double precision real	double precision real	yes
QLOG10	REAL(16)	REAL(16)	yes

LOGICAL (L, KIND)

Converts between objects of type logical with different kind type parameter values.

L

must be of type logical.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• Logical.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of the default logical type.

Result Value

The value is that of L.

Examples

LOGICAL (L .OR. .NOT. L) has the value .TRUE. and is of type default logical, regardless of the kind type parameter of the logical variable L.

LSHIFT (I, SHIFT)

Performs a logical shift to the left.

I

must be of type integer.

SHIFT

must be of type integer. It must be non-negative and less than or equal to BIT_SIZE(I).

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

• The result has the value obtained by shifting the bits of I by SHIFT positions to the left.

• Vacated bits are filled with zeros.

• The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

LSHIFT (3, 1) has the result 6.

LSHIFT (3, 2) has the result 12.

Specific Name	Argument Type	Result Type	Pass As Arg?
LSHIFT	any integer	same as argument	yes

MATMUL (MATRIX_A, MATRIX_B, MINDIM)

Performs a matrix multiplication.

MATRIX_A

is an array with a rank of one or two and a numeric or logical data type.

MATRIX_B

is an array with a rank of one or two and a numeric or logical data type. It can be a different numeric type than matrix_a, but you cannot use one numeric matrix and one logical matrix.

MINDIM (optional)

is an integer that determines whether to do the matrix multiplication using the Winograd variation of the Strassen algorithm, which may be faster for large matrices. The algorithm recursively splits the operand matrices into four roughly equal parts, until any submatrix extent is less than MINDIM.

Note:

Strassen's method is not stable for certain row or column scalings of the input matrices. Therefore, for MATRIX_A and MATRIX_B with divergent exponent values, Strassen's method may give inaccurate results.

The significance of the value of MINDIM is:

<=0

does not use the Strassen algorithm at all. This is the default.

1

is reserved for future use.

>1

recursively applies the Strassen algorithm as long as the smallest extent of all dimensions in the argument arrays is greater than or equal to this value. To achieve optimal performance you should experiment with the value of MINDIM as the optimal value depends on your machine configuration, available memory, and the size, type, and kind type of the arrays.

By default, MATMUL employs the conventional O(N**3) method of matrix multiplication.

If you link the libxlf90_r.a library, a parallel implementation of matrix multiplication is employed which improves performance on SMP machines.

If you link the libxlf90.a or libxlf90_t.a library, the Winograd variation of the O(N**2.81) Strassen method is employed under these conditions:

1. MATRIX_A and MATRIX_B are both integer, both real, or both complex and have the same kind type.

2. The program can allocate the needed temporary storage, enough to hold approximately (2/3)*(N**2) elements for square matrices of extent N.

3. The MINDIM argument is less than or equal to the smallest of all extents of MATRIX_A and MATRIX_B.

At least one of the arguments must be of rank two. The size of the first or only dimension of matrix_b must be equal to the last or only dimension of matrix_a.

Class

Transformational function

Result Value

The result is an array. If one of the arguments is of rank one, the result has a rank of one. If both arguments are of rank two, the result has a rank of two.

The data type of the result depends on the data type of the arguments, according to the rules in Table 3 and Table 4.

If matrix_a and matrix_b have a numeric data type, the array elements of the result are:

Value of Element (i,j) = SUM( (row i of matrix_a) * (column j of matrix_b) )

If matrix_a and matrix_b are of type logical, the array elements of the result are:

Value of Element (i,j) = ANY( (row i of matrix_a) .AND. (column j of matrix_b) )

Examples

! A is the array  | 1 2 3 |, B is the array | 7 10 |
!                 | 4 5 6 |                 | 8 11 |
!                                           | 9 12 |
   RES = MATMUL(A, B)
! The result is |  50   68 |
!               | 122  167 |

! HUGE_ARRAY and GIGANTIC_ARRAY in this example are
! large arrays of real or complex type, so the operation
! might be faster with the Strassen algorithm.
 
   RES = MATMUL(HUGE_ARRAY, GIGANTIC_ARRAY, MINDIM=196)

Related Information

The numerical stability of Strassen's method for matrix multiplication is discussed in:

"Exploiting Fast Matrix Multiplication Within the Level 3 BLAS", Nicholas J. Higham, ACM Transactions on Mathematical Software, Vol. 16, No. 4, December 1990.

"GEMMW: A portable level 3 BLAS Winograd variant of Strassen's matrix-matrix multiply algorithm", Douglas, C. C., Heroux, M., Slishman, G., and Smith, R. M., Journal of Computational Physics, Vol. 110, No. 1, January 1994, pages 1-10.

MAX (A1, A2, A3, ...)

Maximum value.

• A3, ... are optional arguments. Any array that is itself an optional dummy argument must not be passed as an optional argument to this function unless it is present in the calling procedure.

• All the arguments must have the same type, either integer or real, and they all must have the same kind type parameter.

Class

Elemental function

Result Type and Attributes

Same as the arguments. (Some specific functions return results of a particular type.)

Result Value

The value of the result is that of the largest argument.

Examples

MAX (-9.0, 7.0, 2.0) has the value 7.0.

If you evaluate MAX (10, 3, A), where A is an optional array argument in the calling procedure, PRESENT(A) must be true in the calling procedure.

Specific Name	Argument Type	Result Type	Pass As Arg?
AMAX0	any integer (1)	default real	no
AMAX1	default real	default real	no
DMAX1	double precision real	double precision real	no
QMAX1	REAL(16)	REAL(16)	no
MAX0	any integer (1)	same as argument	no
MAX1	any real (2)	default integer	no

Notes:

1. The extension is the ability to specify a nondefault integer argument.

2. The extension is the ability to specify a nondefault real argument.

MAXEXPONENT (X)

Returns the maximum exponent in the model representing numbers of the same type and kind type parameter as the argument.

X

must be of type real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result is the following:

   type             MAXEXPONENT
----------          -----------
  real(4)                128
  real(8)               1024
  real(16)              1024

Examples

MAXEXPONENT(X) = 128 for X of type real(4).

See "Real Data Model".

MAXLOC (ARRAY, DIM, MASK)

Locates the first element of an array along a dimension that has the maximum value of all elements corresponding to the true values of the mask. MAXLOC will return the index referable to the position of the element using a positive integer.

ARRAY

is an array of type integer or real.

DIM (optional)

is a scalar integer in the range 1<=DIM<=rank(ARRAY). The corresponding actual argument must not be an optional dummy argument.

MASK (optional)

is of type logical and conforms to array in shape. If it is absent, the default mask evaluation is .TRUE.; that is, the entire array is evaluated.

Class

Transformational function

Result Type and Attributes

If DIM is absent, the result is an integer array of rank one with a size equal to the rank of ARRAY. If DIM is present, the result is an integer array of rank rank(ARRAY)-1, and the shape is (s₁, ..., s_DIM-1, s_DIM+1, ..., s_n), where n is the rank of ARRAY.

If there is no maximum value, perhaps because the array is zero-sized or the mask array has all .FALSE. values or there is no DIM argument, the return value is a zero-sized one-dimensional entity. If DIM is present, the result shape depends on the rank of ARRAY.

Result Value

The result indicates the subscript of the location of the maximum masked element of array. If more than one element is equal to this maximum value, the function finds the location of the first (in array element order). If DIM is specified, the result indicates the location of the maximum masked element along each vector of the dimension.

Because both DIM and MASK are optional, various combinations of arguments are possible. When the -qintlog option is specified with two arguments, the second argument refers to one of the following:

• MASK if it is an array of type integer, logical, byte or typeless

• DIM if it is a scalar of type integer, byte or typeless

• MASK if it is a scalar of type logical

The addition of the DIM argument modifies the behavior from XL Fortran Version 3.

Examples

! A is the array  |  4  9  8 -8 |
!                 |  2  1 -1  5 |
!                 |  9  4 -1  9 |
!                 | -7  5  7 -3 |
 
! Where is the largest element of A?
       RES = MAXLOC(A)
! The result is | 3 1 | because 9 is located at A(3,1).
! Although there are other 9s, A(3,1) is the first in
! column-major order.
 
! Where is the largest element in each column of A
! that is less than 7?
       RES = MAXLOC(A, DIM = 1, MASK = A .LT. 7)
! The result is | 1 4 2 2 | because these are the corresponding
! row locations of the largest value in each column
! that are less than 7 (the values being 4,5,-1,5).

Regardless of the defined upper and lower bounds of the array, MAXLOC will determine the lower bound index as '1'. Both MAXLOC and MINLOC index using positive integers. To find the actual index:

       INTEGER B(-100:100)
! Maxloc views the bounds as (1:201)
! If the largest element is located at index '-49'
       I = MAXLOC(B)
! Will return the index '52'
! To return the exact index for the largest element, insert:
       INDEX = LBOUND(B) - 1 + I
! Which is:  INDEX = (-100) - 1 + 52 = (-49)
       PRINT*, B(INDEX)

MAXVAL (ARRAY, DIM, MASK)

Returns the maximum value of the elements in the array along a dimension corresponding to the true elements of MASK.

ARRAY

is an array of type integer or real.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array). The corresponding actual argument must not be an optional dummy argument.

MASK (optional)

is an array or scalar of type logical that conforms to array in shape. If it is absent, the entire array is evaluated.

Class

Transformational function

Result Value

The result is an array of rank rank(ARRAY)-1, with the same data type as array. If dim is missing or if ARRAY is of rank one, the result is a scalar.

If dim is specified, each element of the result value contains the maximum value of all the elements that satisfy the condition specified by mask along each vector of the dimension dim. The array element subscripts in the result are (s₁, s₂, ..., s_(DIM-1), s_(DIM+1), ..., s_n), where n is the rank of array and DIM is the dimension specified by dim.

If dim is not specified, the function returns the maximum value of all applicable elements.

If ARRAY is zero-sized or the mask array has all .FALSE. values, the result value is the negative number of the largest magnitude, of the same type and kind type as ARRAY.

Examples

! A is the array  | -41  33 25 |
!                 |  12 -61 11 |
 
! What is the largest value in the entire array?
       RES = MAXVAL(A)
! The result is 33
 
! What is the largest value in each column?
       RES = MAXVAL(A, DIM=1)
! The result is | 12 33 25 |
 
! What is the largest value in each row?
       RES = MAXVAL(A, DIM=2)
! The result is | 33 12 |
 
! What is the largest value in each row, considering only
! elements that are less than 30?
       RES = MAXVAL(A, DIM=2, MASK = A .LT. 30)
! The result is | 25 12 |

MERGE (TSOURCE, FSOURCE, MASK)

Selects between two values, or corresponding elements in two arrays. A logical mask determines whether to take each result element from the first or second argument.

TSOURCE

is the source array to use when the corresponding element in the mask is true. It is an expression of any data type.

FSOURCE

is the source array to use when the corresponding element in the mask is false. It must have the same data type and type parameters as tsource. It must conform in shape to tsource.

MASK

is a logical expression that conforms to TSOURCE and FSOURCE in shape.

Class

Elemental function

Result Value

The result has the same shape and data type as tsource and fsource.

For each element in the result, the value of the corresponding element in mask determines whether the value is taken from tsource (if true) or fsource (if false).

Examples

! TSOURCE is | A D G |, FSOURCE is | a d g |,
!            | B E H |             | b e h |
!            | C F I |             | c f i |
!
! and MASK is the array | T T T |
!                       | F F F |
!                       | F F F |
 
! Take the top row of TSOURCE, and the remaining elements
! from FSOURCE.
       RES = MERGE(TSOURCE, FSOURCE, MASK)
! The result is  | A D G |
!                | b e h |
!                | c f i |
 
! Evaluate IF (X .GT. Y) THEN
!             RES=6
!          ELSE
!             RES=12
!          END IF
! in a more concise form.
       RES = MERGE(6, 12, X .GT. Y)

MIN (A1, A2, A3, ...)

Minimum value.

• A3, ... are optional arguments. Any array that is itself an optional dummy argument must not be passed as an optional argument to this function unless it is present in the calling procedure.

• All the arguments must have the same type, either integer or real, and they all must have the same kind type parameter.

Class

Elemental function

Result Type and Attributes

Same as the arguments. (Some specific functions return results of a particular type.)

Result Value

The value of the result is that of the smallest argument.

Examples

MIN (-9.0, 7.0, 2.0) has the value -9.0.

If you evaluate MIN (10, 3, A), where A is an optional array argument in the calling procedure, PRESENT(A) must be true in the calling procedure.

Specific Name	Argument Type	Result Type	Pass As Arg?
AMIN0	any integer	default real	no
AMIN1	default real	default real	no
DMIN1	double precision real	double precision real	no
QMIN1	REAL(16)	REAL(16)	no
MIN0	any integer	same as argument	no
MIN1	any real	default integer	no

MINEXPONENT (X)

Returns the minimum (most negative) exponent in the model representing the numbers of the same type and kind type parameter as the argument.

X

must be of type real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result is the following:

   type             MINEXPONENT
----------          -----------
  real(4)              - 125
  real(8)              -1021
  real(16)              -968

Examples

MINEXPONENT(X) = -125 for X of type real(4).

See "Real Data Model".

MINLOC (ARRAY, DIM, MASK)

Locates the first element of an array along a dimension that has the minimum value of all elements corresponding to the true values of the mask. MINLOC will return the index referable to the position of the element using a positive integer.

ARRAY

is an array of type integer or real.

DIM (optional)

is a scalar integer in the range 1<=DIM<=n, where n is the rank of ARRAY. The corresponding actual argument must not be an optional dummy argument.

MASK (optional)

is of type logical and conforms to array in shape. If it is absent, the default mask evaluation is .TRUE.; that is, the entire array is evaluated.

Class

Transformational function

Result Type and Attributes

If DIM is absent, the result is an integer array of rank one with a size equal to the rank of ARRAY. If DIM is present, the result is an integer array of rank rank(ARRAY)-1, and the shape is (s₁, ..., s_DIM-1, s_DIM+1, ..., s_n), where n is the rank of ARRAY.

If there is no minimum value, perhaps because the array is zero-sized or the mask array has all .FALSE. values or there is no DIM argument, the return value is a zero-sized one-dimensional entity. If DIM is present, the result shape depends on the rank of ARRAY.

Result Value

The result indicates the subscript of the location of the minimum masked element of array. If more than one element is equal to this minimum value, the function finds the location of the first (in array element order). If DIM is specified, the result indicates the location of the minimum masked element along each vector of the dimension.

Because both DIM and MASK are optional, various combinations of arguments are possible. When the -qintlog option is specified with two arguments, the second argument refers to one of the following:

• MASK if it is an array of type integer, logical, byte or typeless

• DIM if it is a scalar of type integer, byte or typeless

• MASK if it is a scalar or type logical

The addition of the DIM argument modifies the behavior from XL Fortran Version 3.

Examples

! A is the array  |  4  9  8 -8 |
!                 |  2  1 -1  5 |
!                 |  9  4 -1  9 |
!                 | -7  5  7 -3 |
 
! Where is the smallest element of A?
       RES = MINLOC(A)
! The result is | 1 4 | because -8 is located at A(1,4).
 
! Where is the smallest element in each row of A that
! is not equal to -7?
       RES = MINLOC(A, DIM = 2, MASK = A .NE. -7)
! The result is | 4 3 3 4 | because these are the
! corresponding column locations of the smallest value
! in each row not equal ! to -7 (the values being
! -8,-1,-1,-3).

Regardless of the defined upper and lower bounds of the array, MINLOC will determine the lower bound index as '1'. Both MAXLOC and MINLOC index using positive integers. To find the actual index:

       INTEGER B(-100:100)
! Minloc views the bounds as (1:201)
! If the smallest element is located at index '-49'
       I = MINLOC(B)
! Will return the index '52'
! To return the exact index for the smallest element, insert:
       INDEX = LBOUND(B) - 1 + I
! Which is:  INDEX = (-100) - 1 + 52 = (-49)
       PRINT*, B(INDEX)

MINVAL (ARRAY, DIM, MASK)

Returns the minimum value of the elements in the array along a dimension corresponding to the true elements of MASK.

ARRAY

is an array of type integer or real.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array). The corresponding actual argument must not be an optional dummy argument.

MASK (optional)

is an array or scalar of type logical that conforms to array in shape. If it is absent, the entire array is evaluated.

Class

Transformational function

Result Value

The result is an array of rank rank(ARRAY)-1, with the same data type as array. If dim is missing or if ARRAY is of rank one, the result is a scalar.

If dim is specified, each element of the result value contains the minimum value of all the elements that satisfy the condition specified by mask along each vector of the dimension dim. The array element subscripts in the result are (s₁, s₂, ..., s_(DIM-1), s_(DIM+1), ..., s_n), where n is the rank of array and DIM is the dimension specified by dim.

If dim is not specified, the function returns the minimum value of all applicable elements.

If ARRAY is zero-sized or the mask array has all .FALSE. values, the result value is the positive number of the largest magnitude, of the same type and kind type as ARRAY.

Examples

! A is the array  | -41  33 25 |
!                 |  12 -61 11 |
 
! What is the smallest element in A?
       RES = MINVAL(A)
! The result is -61
 
! What is the smallest element in each column of A?
       RES = MINVAL(A, DIM=1)
! The result is | -41 -61 11 |
 
! What is the smallest element in each row of A?
       RES = MINVAL(A, DIM=2)
! The result is | -41 -61 |
 
! What is the smallest element in each row of A,
! considering only those elements that are
! greater than zero?
       RES = MINVAL(A, DIM=2, MASK = A .GT.0)
! The result is | 25 11 |

MOD (A, P)

Remainder function.

A

must be of type integer or real.

P

must be of the same type and kind type parameter as A.

Class

Elemental function

Result Type and Attributes

Same as A.

Result Value

• If P <> 0, the value of the result is A - INT(A/P) * P.

• If P = 0, the result is undefined.

Examples

MOD (3.0, 2.0) has the value 1.0.

MOD (8, 5) has the value 3.

MOD (-8, 5) has the value -3.

MOD (8, -5) has the value 3.

MOD (-8, -5) has the value -3.

Specific Name	Argument Type	Result Type	Pass As Arg?
MOD	any integer	same as argument	yes
AMOD	default real	default real	yes
DMOD	double precision real	double precision real	yes
QMOD	REAL(16)	REAL(16)	yes

MODULO (A, P)

Modulo function.

A

must be of type integer or real.

P

must be of the same type and kind type parameter as A.

Class

Elemental function

Result Type and Attributes

Same as A.

Result Value

• Case (i): A is of type integer. If P <> 0, MODULO (A, P) has the value R such that A = Q * P + R, where Q is an integer.

  If P > 0, the inequalities 0 <= R < P hold.

  If P < 0, P < R <= 0 hold.

  If P = 0, the result is undefined.

• Case (ii): A is of type real. If P <> 0, the value of the result is A - FLOOR (A / P) * P.

  If P = 0, the result is undefined.

Examples

MODULO (8, 5) has the value 3.

MODULO (-8, 5) has the value 2.

MODULO (8, -5) has the value -2.

MODULO (-8, -5) has the value -3.

MVBITS (FROM, FROMPOS, LEN, TO, TOPOS)

Copies a sequence of bits from one data object to another.

FROM

must be of type integer. It is an INTENT(IN) argument.

FROMPOS

must be of type integer and nonnegative. It is an INTENT(IN) argument. FROMPOS + LEN must be less than or equal to BIT_SIZE (FROM).

LEN

must be of type integer and nonnegative. It is an INTENT(IN) argument.

TO

must be a variable of type integer with the same kind type parameter value as FROM and may be the same variable as FROM. It is an INTENT(INOUT) argument. TO is set by copying the sequence of bits of length LEN, starting at position FROMPOS of FROM to position TOPOS of TO. No other bits of TO are altered. On return, the LEN bits of TO starting at TOPOS are equal to the value that the LEN bits of FROM starting at FROMPOS had on entry.

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

TOPOS

must be of type integer and nonnegative. It is an INTENT(IN) argument. TOPOS + LEN must be less than or equal to BIT_SIZE (TO).

Class

Elemental subroutine

Examples

If TO has the initial value 6, the value of TO is 5 after the statement

CALL MVBITS (7, 2, 2, TO, 0)

See "Integer Bit Model".

NEAREST (X,S)

Returns the nearest different processor-representable number in the direction indicated by the sign of S (toward positive or negative infinity).

X

must be of type real.

S

must be of type real and not equal to zero.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result is the machine number different from and nearest to X in the direction of the infinity with the same sign as S.

Examples

NEAREST (3.0, 2.0) = 3.0 + 2.0^(-22). See "Real Data Model".

NINT (A, KIND)

Nearest integer.

A

must be of type real.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• Integer.

• If KIND is present, the kind type parameter is that specified by KIND; otherwise, the kind type parameter is that of the default integer type.

Result Value

• If A > 0, NINT (A) has the value INT (A + 0.5).

• If A <= 0, NINT (A) has the value INT (A - 0.5).

• The result is undefined if its value cannot be represented in the specified integer type.

Examples

NINT (2.789) has the value 3. NINT (2.123) has the value 2.

Specific Name	Argument Type	Result Type	Pass As Arg?
NINT	default real	default integer	yes
IDNINT	double precision real	default integer	yes
IQNINT	REAL(16)	default integer	yes

NOT (I)

Performs a logical complement.

I

must be of type integer.

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

The result has the value obtained by complementing I bit-by-bit according to the following table:

I NOT (I)
---------
1    0
0    1

The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Specific Name	Argument Type	Result Type	Pass As Arg?
NOT	any integer	same as argument	yes

NUMBER_OF_PROCESSORS (DIM)

Returns a scalar of type default integer whose value is always 1.

DIM (optional)

must be a scalar integer and have a value of 1 (the rank of the processor array).

Class

System inquiry function

Result Type and Attributes

Default scalar integer which always has a value of 1 in a uniprocessor environment.

Examples

I = NUMBER_OF_PROCESSORS()       ! 1
J = NUMBER_OF_PROCESSORS(DIM=1)  ! 1

NUM_PARTHDS

Returns the number of parallel Fortran threads the run time should create during execution of a program. This value is set by using the PARTHDS run-time option. If the user does not set the PARTHDS run-time option, the run time will set a default value for PARTHDS. In doing so, the run time may consider the following when setting the option:

• the number of processors on the machine

• the value specified in the run-time option USRTHDS

Class

Inquiry function

Result Value

Default scalar integer

If the compiler option -qsmp has not been specified, then NUM_PARTHDS will always return a value of 1.

Examples

I = NUM_PARTHDS()
IF (I == 1) THEN
   CALL SINGLE_THREAD_ROUTINE()
ELSE
   CALL MULTI_THREAD_ROUTINE() 

Specific Name	Argument Type	Result Type	Pass As Arg?
NUM_PARTHDS	default scalar integer	default scalar integer	no

Related Information

See the "PARTHDS" run-time option and the "XLSMPOPTS" run-time option in the User's Guide.

NUM_USRTHDS

Returns the number of threads that will be explicitly created by the user during execution of the program. This value is set by using the USRTHDS run-time option.

Class

Inquiry function

Result Value

Default scalar integer

If the value has not been explicitly set using the USRTHDS run-time option, the default value is 0.

Specific Name	Argument Type	Result Type	Pass As Arg?
NUM_USRTHDS	default scalar integer	default scalar integer	no

Related Information

See the "USRTHDS" run-time option and the "XLSMPOPTS" run-time option in the User's Guide.

PACK (ARRAY, MASK, VECTOR)

Takes some or all elements from an array and packs them into a one-dimensional array, under the control of a mask.

ARRAY

is the source array, whose elements become part of the result. It can have any data type.

MASK

must be of type logical and must be conformable with array. It determines which elements are taken from the source array. If it is a scalar, its value applies to all elements in array.

VECTOR (optional)

is a padding array whose elements are used to fill out the result if there are not enough elements selected by the mask. It is a one-dimensional array that has the same data type as array and at least as many elements as there are true values in mask. If mask is a scalar with a value of .TRUE., vector must have at least as many elements as there are array elements in array.

Class

Transformational function

Result Value

The result is always a one-dimensional array with the same data type as array.

The size of the result depends on the optional arguments:

• If vector is specified, the size of the resultant array equals the size of vector.

• Otherwise, it equals the number of true array elements in mask, or the number of elements in array if mask is a scalar with a value of .TRUE..

The array elements in array are taken in array element order to form the result. If the corresponding array element in mask is .TRUE., the element from array is placed at the end of the result.

If any elements remain empty in the result (because vector is present, and has more elements than there are .TRUE. values in mask), the remaining elements in the result are set to the corresponding values from vector.

Examples

! A is the array  |  0  7  0 |
!                 |  1  0  3 |
!                 |  4  0  0 |
 
! Take only the non-zero elements of this sparse array.
! If there are less than six, fill in -1 for the rest.
RES = PACK(A, MASK= A .NE. 0, VECTOR=(/-1,-1,-1,-1,-1,-1/)
! The result is (/ 1, 4, 7, 3, -1, -1 /).
 
! Elements 1, 4, 7, and 3 are taken in order from A
! because the value of MASK is true only for these
! elements. The -1s are added to the result from VECTOR
! because the length (6) of VECTOR exceeds the number
! of .TRUE. values (4) in MASK.

PRECISION (X)

Returns the decimal precision in the model representing real numbers with the same kind type parameter as the argument.

X

must be of type real or complex. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result is:

INT( (DIGITS(X) - 1) * LOG10(2) )

Therefore,

       Type               Precision
--------------------      ---------
 real(4) , complex(4)           6
 real(8) , complex(8)          15
real(16) , complex(16)         31

Examples

PRECISION (X) = INT( (24 - 1) * LOG10(2.) ) = INT(6.92 ...) = 6 for X of type real(4). See "Real Data Model".

PRESENT (A)

Determine whether an optional argument is present. If it is not present, you may only pass it as an optional argument to another procedure or pass it as an argument to PRESENT.

A

is the name of an optional dummy argument that is accessible in the procedure in which the PRESENT function reference appears.

Class

Inquiry function

Result Type and Attributes

Default logical scalar.

Result Value

The result is .TRUE. if the actual argument is present (that is, if it was passed to the current procedure in the specified dummy argument), and .FALSE. otherwise.

Examples

      SUBROUTINE SUB (X, Y)
        REAL, OPTIONAL :: Y
        IF (PRESENT (Y)) THEN
! In this section, we can use y like any other variable.
           X = X + Y
           PRINT *, SQRT(Y)
        ELSE
! In this section, we cannot define or reference y.
           X = X + 5
! We can pass it to another procedure, but only if
! sub2 declares the corresponding argument as optional.
           CALL SUB2 (Z, Y)
        ENDIF
      END SUBROUTINE SUB

Related Information

OPTIONAL

PROCESSORS_SHAPE ()

Returns a zero-sized array.

Class

System inquiry function

Result Type and Attributes

Default integer array of rank one, whose size is equal to the rank of the processor array. In a uniprocessor environment, the result is a zero-sized vector.

Result Value

The value of the result is the shape of the processor array.

Examples

I=PROCESSORS_SHAPE()
! Zero-sized vector of type default integer

PRODUCT (ARRAY, DIM, MASK)

Multiplies together all elements in an entire array, or selected elements from all vectors along a dimension.

ARRAY

is an array with a numeric data type.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array). The corresponding actual argument must not be an optional dummy argument.

MASK (optional)

is a logical expression that conforms with array in shape. If mask is a scalar, the scalar value applies to all elements in array.

Class

Transformational function

Result Value

If DIM is present, the result is an array of rank rank(array)-1 and the same data type as array. If dim is missing, or if mask has a rank of one, the result is a scalar.

The result is calculated by one of the following methods:

Method 1:

If only array is specified, the result is the product of all its array elements. If array is a zero-sized array, the result is equal to one.

Method 2:

If array and mask are both specified, the result is the product of those array elements of array that have a corresponding true array element in mask. If mask has no elements with a value of .TRUE., the result is equal to one.

Method 3:

If dim is also specified, the result value equals the product of the array elements of array along dimension dim that have a corresponding true array element in mask.

Examples

Method 1:

! Multiply all elements in an array.
       RES = PRODUCT( (/2, 3, 4/) )
! The result is 24 because (2 * 3 * 4) = 24.
 
! Do the same for a two-dimensional array.
       RES = PRODUCT( (/2, 3, 4/), (/4, 5, 6/) )
! The result is 2880.  All elements are multiplied.

Method 2:

! A is the array (/ -3, -7, -5, 2, 3 /)
! Multiply all elements of the array that are > -5.
       RES = PRODUCT(A, MASK = A .GT. -5)
! The result is -18 because (-3 * 2 * 3) = -18.

Method 3:

! A is the array | -2  5  7 |
!                |  3 -4  3 |
! Find the product of each column in A.
       RES = PRODUCT(A, DIM = 1)
! The result is | -6 -20 21 | because (-2 * 3) =  -6
!                                    ( 5 * -4 ) = -20
!                                    ( 7 *  3 ) = 21
 
! Find the product of each row in A.
       RES = PRODUCT(A, DIM = 2)
! The result is | -70 -36 |
! because (-2 *  5 * 7) = -70
!          (3 * -4 * 3) = -36
 
! Find the product of each row in A, considering
! only those elements greater than zero.
       RES = PRODUCT(A, DIM = 2, MASK = A .GT. 0)
! The result is | 35 9 | because ( 5 * 7) = 35
!                                 (3 * 3) =  9

QCMPLX (X, Y)

Convert to extended complex type.

X

must be of type integer, real, or complex.

Y (optional)

must be of type integer or real. It must not be present if X is of type complex.

Class

Elemental function

Result Type and Attributes

It is of type extended complex.

Result Value

• If Y is absent and X is not complex, it is as if Y were present with the value of zero.

• If Y is absent and X is complex, it is as if Y were present with the value AIMAG(X) and X were present with the value REAL(X).

• QCMPLX(X, Y) has the complex value whose real part is REAL(X, KIND=16) and whose imaginary part is REAL(Y, KIND=16).

Examples

QCMPLX (-3) has the value (-3.0Q0, 0.0Q0).

Specific Name	Argument Type	Result Type	Pass As Arg?
QCMPLX	REAL(16)	COMPLEX(16)	no

Related Information

CMPLX (X, Y, KIND), DCMPLX (X, Y).

QEXT (A)

Convert to extended precision real type.

A

must be of type integer, or real.

Class

Elemental function

Result Type and Attributes

Extended precision real.

Result Value

• If A is of type extended precision real, QEXT(A) = A.

• If A is of type integer or real, the result is the exact extended precision representation of A.

Examples

QEXT (-3) has the value -3.0Q0.

Specific Name	Argument Type	Result Type	Pass As Arg?
QFLOAT	any integer	REAL(16)	no
QEXT	default real	REAL(16)	no
QEXTD	double precision real	REAL(16)	no

RADIX (X)

Returns the base of the model representing numbers of the same type and kind type parameter as the argument.

X

must be of type integer or real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result is the base of the model representing numbers of the same kind and type as X. The result is always 2. See the models under "Data Representation Models".

RAND ()

Not recommended. Generates uniform random numbers, positive real numbers greater than or equal to 0.0 and less than 1.0. Instead, use the RANDOM_NUMBER intrinsic subroutine.

Class

None (does not correspond to any of the defined categories).

Result Type and Attributes

real(4) scalar.

Related Information

SRAND (SEED) can be used to specify a seed value for the random number sequence.

If the function result is assigned to an array, all array elements receive the same value.

Examples

The following is an example of a program using the RAND function.

DO I = 1, 5
   R = RAND()
   PRINT *, R
ENDDO
END

The following is sample output generated by the above program:

0.2251586914
0.8285522461
0.6456298828
0.2496948242
0.2215576172

Specific Names

This function only has a specific name.

RANDOM_NUMBER (HARVEST)

Returns one pseudorandom number or an array of pseudorandom numbers from the uniform distribution over the range 0 <= x < 1.

HARVEST

must be of type real. It is an INTENT(OUT) argument. It may be a scalar or array variable. It is set to pseudorandom numbers from the uniform distribution in the interval 0 <= x < 1.

Class

Subroutine

Examples

REAL X, Y (10, 10)
! Initialize X with a pseudorandom number
CALL RANDOM_NUMBER (HARVEST = X)
CALL RANDOM_NUMBER (Y)
! X and Y contain uniformly distributed random numbers

RANDOM_SEED (SIZE, PUT, GET, GENERATOR)

Restarts or queries the pseudorandom number generator used by RANDOM_NUMBER.

There must either be exactly one or no arguments present.

SIZE (optional)

must be scalar and of type default integer. It is an INTENT(OUT) argument. It is set to the number of default type integers (N) that are needed to hold the value of the seed, which is an 8-byte variable.

PUT (optional)

must be a default integer array of rank one and size >= N. It is an INTENT(IN) argument. The seed for the current generator is transferred from it.

GET (optional)

must be a default integer array of rank one and size >= N. It is an INTENT(OUT) argument. The seed for the current generator is transferred to it.

GENERATOR (optional)

must be a scalar and of type default integer. It is an INTENT(IN) argument. Its value determines the random number generator to be used subsequently. The value must be either 1 or 2.

Random_seed allows the user to toggle between two random number generators. Generator 1 is the default. Each generator maintains a private seed and normally resumes its cycle after the last number it generated.

Generator 1 uses the multiplicative congruential method, with

S(I+1) = ( 16807.0 * S(I) ) mod (2.0**31-1)

X(I+1) = S(I+1) / (2.0**31-1)

Generator 1 cycles after 2**31-2 (i.e., 2,147,483,646) random numbers.

Generator 2 also uses the multiplicative congruential method, with

S(I+1) = ( 44,485,709,377,909.0 * S(I) )
              mod (2.0**48)

X(I+1) = S(I+1) / (2.0**48)

Generator 2 cycles after (2**46)-1 (i.e., 70,368,744,177,663) random numbers. Although generator 1 is the default (for reasons of backwards compatibility) the use of generator 2 is recommended for new programs since it typically runs faster than generator 1 and has a longer period.

If no argument is present, the seed of the current generator is set to the default value 1d0.

Class

Subroutine

Examples

CALL RANDOM_SEED
   ! Current generator sets its seed to 1d0
CALL RANDOM_SEED (SIZE = K)
   ! Sets K = 64 / BIT_SIZE( 0 )
CALL RANDOM_SEED (PUT = SEED (1 : K))
   ! Transfer seed to current generator
CALL RANDOM_SEED (GET = OLD (1 : K))
   ! Transfer seed from current generator

RANGE (X)

Returns the decimal exponent range in the model representing integer or real numbers with the same kind type parameter as the argument.

X

must be of type integer, real, or complex. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

1. For an integer argument, the result is:

   INT( LOG10( HUGE(X) ) )
   

2. For a real or complex argument, the result is:

   INT( MIN( LOG10( HUGE(X) ), -LOG10( TINY(X) ) ) )
   

Thus:

Type                     RANGE
------------------------------
integer(1)                  2
integer(2)                  4
integer(4)                  9
integer(8)                 18
real(4) , complex(4)       37
real(8) , complex(8)      307
real(16) , complex(16)    291

Examples

X is of type real(4):

HUGE(X) = 0.34E+39

TINY(X) = 0.11E-37

RANGE(X) = 37

See "Data Representation Models".

REAL (A, KIND)

Convert to real type.

A

must be of type integer, real, or complex.

KIND (optional)

must be a scalar integer initialization expression.

Class

Elemental function

Result Type and Attributes

• Real.

• Case (i): If A is of type integer or real and KIND is present, the kind type parameter is that specified by KIND. If A is of type integer or real and KIND is not present, the kind type parameter is the kind type parameter of the default real type.

• Case (ii): If A is of type complex and KIND is present, the kind type parameter is that specified by KIND. If A is of type complex and KIND is not present, the kind type parameter is the kind type parameter of A.

Result Value

• Case (i): If A is of type integer or real, the result is equal to a kind-dependent approximation to A.

• Case (ii): If A is of type complex, the result is equal to a kind-dependent approximation to the real part of A.

Examples

REAL (-3) has the value -3.0. REAL ((3.2, 2.1)) has the value 3.2.

Specific Name	Argument Type	Result Type	Pass As Arg?
REAL	default integer	default real	no
FLOAT	any integer (1)	default real	no
SNGL	double precision real	default real	no
SNGLQ	REAL(16)	default real	no
DREAL	double complex	double precision real	no
QREAL	COMPLEX(16)	REAL(16)	no

Notes:

1. The extension is the ability to specify a nondefault integer argument.

REPEAT (STRING, NCOPIES)

Concatenate several copies of a string.

STRING

must be scalar and of type character.

NCOPIES

must be scalar and of type integer. Its value must not be negative.

Class

Transformational function

Result Type and Attributes

Character scalar with a length equal to NCOPIES * LENGTH(STRING), with the same kind type parameter as STRING.

Result Value

The value of the result is the concatenation of NCOPIES copies of STRING.

Examples

REPEAT ('H', 2) has the value 'HH'. REPEAT ('XYZ', 0) has the value of a zero-length string.

RESHAPE (SOURCE, SHAPE, PAD, ORDER)

Constructs an array of a specified shape from the elements of a given array.

SOURCE

is an array of any type, which supplies the elements for the result array.

SHAPE

defines the shape of the result array. It is an integer array of up to twenty elements, with rank one and of a constant size. All elements are either positive integers or zero.

PAD (optional)

is used to fill in extra values if source is reshaped into a larger array. It is an array of the same data type as source. If it is absent or is a zero-sized array, you can only make source into another array of the same size or smaller.

ORDER (optional)

is an integer array of rank one with a constant size. Its elements must be a permutation of (1, 2, ..., SIZE(SHAPE)). You can use it to insert elements in the result in an order of dimensions other than the normal (1, 2, ..., rank(result)).

Class

Transformational function

Result Value

The result is an array with shape shape. It has the same data type as source.

The array elements of source are placed into the result in the order of dimensions as specified by order, or in the usual order for array elements if order is not specified.

The array elements of source are followed by the array elements of pad in array element order, and followed by additional copies of pad until all of the elements of the result are set.

Examples

! Turn a rank-1 array into a 3x4 array of the
! same size.
RES= RESHAPE( (/A,B,C,D,E,F,G,H,I,J,K,L/), (/3,4/)
! The result is | A D G J |
!               | B E H K |
!               | C F I L |
 
! Turn a rank-1 array into a larger 3x5 array.
! Keep repeating -1 and -2 values for any
! elements not filled by the source array.
! Fill the rows first, then the columns.
RES= RESHAPE( (/1,2,3,4,5,6/), (/3,5/), &
  (/-1,-2/), (/2,1/) )
! The result is | 1  2  3  4  5  |
!               |  6 -1 -2 -1 -2 |
!               | -1 -2 -1 -2 -1 |

Related Information

SHAPE (SOURCE).

RRSPACING (X)

Returns the reciprocal of the relative spacing of the model numbers near the argument value.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result is:

ABS(FRACTION(X)) * FLOAT(RADIX(X))DIGITS(X)

Examples

RRSPACING (-3.0) = 0.75 * 2²⁴. See "Real Data Model".

RSHIFT (I, SHIFT)

Performs a logical shift to the right.

I

must be of type integer.

SHIFT

must be of type integer. It must be non-negative and less than or equal to BIT_SIZE(I).

Class

Elemental function

Result Type and Attributes

Same as I.

Result Value

• The result has the value obtained by shifting the bits of I by SHIFT positions to the right.

• Vacated bits are filled with the sign bit.

• The bits are numbered 0 to BIT_SIZE(I)-1, from right to left.

Examples

RSHIFT (3, 1) has the result 1.

RSHIFT (3, 2) has the result 0.

Specific Name	Argument Type	Result Type	Pass As Arg?
RSHIFT	any integer	same as argument	yes

SCALE (X,I)

Returns the scaled value: X * 2.0^I

X

must be of type real.

I

must be of type integer.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result is determined from the following:

X * 2.0^I

SCALE (X, I) = X * (2.0^I)

Examples

SCALE (4.0, 3) = 4.0 * (2³) = 32.0. See "Real Data Model".

SCAN (STRING, SET, BACK)

Scan a string for any one of the characters in a set of characters.

STRING

must be of type character.

SET

must be of type character with the same kind type parameter as STRING.

BACK (optional)

must be of type logical.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

• Case (i): If BACK is absent or is present with the value .FALSE. and if STRING contains at least one character that is in SET, the value of the result is the position of the left-most character of STRING that is in SET.

• Case (ii): If BACK is present with the value .TRUE. and if STRING contains at least one character that is in SET, the value of the result is the position of the right-most character of STRING that is in SET.

• Case (iii): The value of the result is zero if no character of STRING is in SET or if the length of STRING or SET is zero.

Examples

• Case (i): SCAN ('FORTRAN', 'TR') has the value 3.

• Case (ii): SCAN ('FORTRAN', 'TR', BACK = .TRUE.) has the value 5.

• Case (iii): SCAN ('FORTRAN', 'BCD') has the value 0.

SELECTED_INT_KIND (R)

Returns a value of the kind type parameter of an integer data type that represents all integer values n with -10^R < n < 10^R.

R

must be a scalar of type integer.

Class

Transformational function

Result Type and Attributes

Default integer scalar.

Result Value

• The result has a value equal to the value of the kind type parameter of an integer data type that represents all values n in the range values n with -10^R < n < 10^R, or if no such kind type parameter is available, the result is -1.

• If more than one kind type parameter meets the criteria, the value returned is the one with the smallest decimal exponent range.

Examples

SELECTED_INT_KIND (9) has the value 4, signifying that an INTEGER with kind type 4 can represent all values from 10^-9 to 10⁹.

Related Information

Kind type parameters supported by XL Fortran are defined in "Type Parameters and Specifiers".

SELECTED_REAL_KIND (P, R)

Returns a value of the kind type parameter of a real data type with decimal precision of at least P digits and a decimal exponent range of at least R.

P (optional)

must be scalar and of type integer.

R (optional)

must be scalar and of type integer.

Class

Transformational function

Result Type and Attributes

Default integer scalar.

Result Value

• The result has a value equal to a value of the kind type parameter of a real data type with decimal precision, as returned by the function PRECISION, of at least P digits and a decimal exponent range, as returned by the function RANGE, of at least R, or if no such kind type parameter is available,

  • If the precision is not available, the result is -1.

  • If the exponent range is not available, the result is -2.

  • If neither is available, the result is -3.

• If more than one kind type parameter value meets the criteria, the value returned is the one with the smallest decimal precision, unless there are several such values, in which case, the smallest of these kind values is returned.

Examples

SELECTED_REAL_KIND (6, 70) has the value 8.

Related Information

Kind type parameters supported by XL Fortran are defined in "Type Parameters and Specifiers".

SET_EXPONENT (X,I)

Returns the number whose fractional part is the fractional part of the model representation of X, and whose exponent part is I.

X

must be of type real.

I

must be of type integer.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• If X = 0 the result is zero.

• Otherwise, the result is:

  FRACTION(X) * 2.0I
  

Examples

SET_EXPONENT (10.5, 1) = 0.65625 * 2.0¹ = 1.3125

See "Real Data Model".

SHAPE (SOURCE)

Returns the shape of an array or scalar.

SOURCE

is an array or scalar of any data type. It must not be a disassociated pointer, allocatable array that is not allocated, or assumed-size array.

Class

Inquiry function

Result Value

The result is a one-dimensional default integer array whose elements define the shape of sources. The extent of each dimension in sources is returned in the corresponding element in the result array.

Related Information

RESHAPE (SOURCE, SHAPE, PAD, ORDER).

Examples

! A is the array  | 7 6 3 1 |
!                 | 2 4 0 9 |
!                 | 5 7 6 8 |
!
       RES = SHAPE( A )
! The result is | 3  4 | because A is a rank-2 array
! with 3 elements in each column and 4 elements in
! each row.

SIGN (A, B)

Absolute value of A times the sign of B.

A

must be of type integer or real.

B

must be of the same type and kind type parameter as A.

Class

Elemental function

Result Type and Attributes

Same as A.

Result Value

• The value of the result is |A| if B >= 0

• The value of the result is -|A| if B < 0

Examples

SIGN (-3.0, 2.0) has the value 3.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
SIGN	default real	default real	yes
ISIGN	any integer (1)	same as argument	yes
DSIGN	double precision real	double precision real	yes
QSIGN	REAL(16)	REAL(16)	yes

Notes:

1. The extension is the ability to specify a nondefault integer argument.

SIGNAL (I, PROC)

The SIGNAL procedure allows a program to specify a procedure to be invoked upon receipt of a specific operating-system signal.

I

is an integer that specifies the value of the signal to be acted upon. It is an INTENT(IN) argument. Available signal values are defined in the C include file signal.h; a subset of signal values is defined in the Fortran include file fexcp.h.

PROC

specifies the user-defined procedure to be invoked when the process receives the specified signal (I). It is an INTENT(IN) argument.

Class

Subroutine

Examples

      INCLUDE 'fexcp.h'
      INTEGER   SIGUSR1
      EXTERNAL  USRINT
! Set exception handler to produce the traceback code.
! The SIGTRAP is defined in the include file fexcp.h.
! xl__trce is a procedure in the XL Fortran
! run-time library.  It generates the traceback code.
      CALL SIGNAL(SIGTRAP, XL__TRCE)
      ...
! Use user-defined procedure USRINT to handle the signal
! SIGUSR1.
      CALL SIGNAL(SIGUSR1, USRINT)
      ...

Related Information

See the signal subroutine in the Technical Reference: Base Operating System and Extensions Volume 1 for details about the underlying implementation.

The "-qsigtrap Option" in the User's Guide allows you to set a handler for SIGTRAP signals through a compiler option.

SIN (X)

Sine function.

X

must be of type real or complex. If X is real, it is regarded as a value in radians. If X is complex, its real part is regarded as a value in radians.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

It approximates sin(X).

Examples

SIN (1.0) has the value 0.84147098 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
SIN	default real	default real	yes
DSIN	double precision real	double precision real	yes
QSIN	REAL(16)	REAL(16)	yes
CSIN (1)	default complex	default complex	yes
CDSIN (2)	double complex	double complex	yes
ZSIN (2)	double complex	double complex	yes
CQSIN (2)	COMPLEX(16)	COMPLEX(16)	yes

Given that X is a complex number in the form a + bi, where i = (-1)^½:

1. abs(b) must be less than or equal to 88.7228, a is any real value.

2. abs(b) must be less than or equal to 709.7827, a is any real value.

SIND (X)

Sine function. Argument in degrees.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It approximates sin(X), where X has a value in degrees.

Examples

SIND (90.0) has the value 1.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
SIND	default real	default real	yes
DSIND	double precision real	double precision real	yes
QSIND	REAL(16)	REAL(16)	yes

SINH (X)

Hyperbolic sine function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result has a value equal to sinh(x).

Examples

SINH (1.0) has the value 1.1752012 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
SINH (1)	default real	default real	yes
DSINH (2)	double precision real	double precision real	yes
QSINH (2)	REAL(16)	REAL(16)	yes

Notes:

1. abs(X) must be less than or equal to 89.4159.

2. abs(X) must be less than or equal to 709.7827.

SIZE (ARRAY, DIM)

Returns the extent of an array along a specified dimension or the total number of elements in the array.

ARRAY

is an array of any data type. It must not be a scalar, disassociated pointer, or allocatable array that is not allocated. It can be an assumed-size array if dim is present and has a value that is less than the rank of array.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array).

Class

Inquiry function

Result Type and Attributes

Default integer scalar.

Result Value

The result equals the extent of array along dimension dim; or, if dim is not specified, it is the total number of array elements in array.

Examples

! A is the array  | 1 -4  7 -10 |
!                 | 2  5 -8  11 |
!                 | 3  6  9 -12 |
 
       RES = SIZE( A )
! The result is 12 because there are 12 elements in A.
 
       RES = SIZE( A, DIM = 1)
! The result is 3 because there are 3 rows in A.
 
       RES = SIZE( A, DIM = 2)
! The result is 4 because there are 4 columns in A.

SPACING (X)

Returns the absolute spacing of the model numbers near the argument value.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

If X is not 0, the result is:

2.0^{EXPONENT(X) - DIGITS(X)}

If X is 0, the result is the same as that of TINY(X).

Examples

SPACING (3.0) = 2.0^{2 - 24} = 2.0^(-22) See "Real Data Model".

SPREAD (SOURCE, DIM, NCOPIES)

Replicates an array in an additional dimension by making copies of existing elements along that dimension.

SOURCE

can be an array or scalar. It can have any data type. The rank of source has a maximum value of 19.

DIM

is an integer scalar in the range 1 <= dim <= rank(source)+1. Unlike most other array intrinsic functions, SPREAD requires the dim argument.

NCOPIES

is an integer scalar. It becomes the extent of the extra dimension added to the result.

Class

Transformational function

Result Type and Attributes

The result is an array of rank rank(source)+1 and with the same type and type parameters as source.

Result Value

If source is a scalar, the result is a one-dimensional array with ncopies elements, each with value source.

If source is an array, the result is an array of rank rank(source) + 1. Along dimension dim, each array element of the result is equal to the corresponding array element in source.

If ncopies is less than or equal to zero, the result is a zero-sized array.

Examples

! A is the array (/ -4.7, 6.1, 0.3 /)
 
       RES = SPREAD( A, DIM = 1, NCOPIES = 3 )
! The result is   | -4.7 6.1 0.3 |
!                 | -4.7 6.1 0.3 |
!                 | -4.7 6.1 0.3 |
! DIM=1 extends each column.  Each element in RES(:,1)
! becomes a copy of A(1), each element in RES(:,2) becomes
! a copy of A(2), and so on.
 
       RES = SPREAD( A, DIM = 2, NCOPIES = 3 )
! The result is   | -4.7 -4.7 -4.7 |
!                 |  6.1  6.1  6.1 |
!                 |  0.3  0.3  0.3 |
! DIM=2 extends each row.  Each element in RES(1,:)
! becomes a copy of A(1), each element in RES(2,:)
! becomes a copy of A(2), and so on.
 
       RES = SPREAD( A, DIM = 2, NCOPIES = 0 )
! The result is (/ /) (a zero-sized array).

SQRT (X)

Square root.

X

must be of type real or complex. Unless X is complex, its value must be greater than or equal to zero.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It has a value equal to the square root of X.

• If the result type is complex, its value is the principal value with the real part greater than or equal to zero. If the real part is zero, the imaginary part is greater than or equal to zero.

Examples

SQRT (4.0) has the value 2.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
SQRT	default real	default real	yes
DSQRT	double precision real	double precision real	yes
QSQRT	REAL(16)	REAL(16)	yes
CSQRT (1)	default complex	default complex	yes
CDSQRT (1)	double complex	double complex	yes
ZSQRT (1)	COMPLEX(8)	COMPLEX(8)	yes
CQSQRT (1)	COMPLEX(16)	COMPLEX(16)	yes

Given that X is a complex number in the form a + bi, where i = (-1)^½:

1. abs(X) + abs(a) must be less than or equal to 1.797693 * 10³⁰⁸.

SRAND (SEED)

Provides the seed value used by the random number generator function RAND.

SEED

must be scalar. It must be of type REAL(4) when used to provide a seed value for the RAND function, or of type INTEGER(4) when used to provide a seed value for the IRAND service and utility function. It is an INTENT(IN) argument.

Class

Subroutine

Examples

The following is an example of a program using the SRAND subroutine.

CALL SRAND(0.5)
DO I = 1, 5
   R = RAND()
   PRINT *,R
ENDDO
END

The following is sample output generated by the above program:

0.3984375000
0.4048461914
0.1644897461
0.1281738281E-01
0.2313232422E-01

SUM (ARRAY, DIM, MASK)

Calculates the sum of selected elements in an array.

ARRAY

is an array of numeric type, whose elements you want to sum.

DIM (optional)

is an integer scalar in the range 1 <= dim <= rank(array). The corresponding actual argument must not be an optional dummy argument.

MASK (optional)

is a logical expression. If it is an array, it must conform with array in shape. If mask is a scalar, the scalar value applies to all elements in array.

Class

Transformational function

Result Value

If dim is present, the result is an array of rank rank(array)-1, with the same data type as array. If dim is missing, or if mask has a rank of one, the result is a scalar.

The result is calculated by one of the following methods:

Method 1:

If only array is specified, the result equals the sum of all the array elements of array. If array is a zero-sized array, the result equals zero.

Method 2:

If array and mask are both specified, the result equals the sum of the array elements of array that have a corresponding array element in mask with a value of .TRUE.. If mask has no elements with a value of .TRUE., the result is equal to zero.

Method 3:

If dim is also specified, the result value equals the sum of the array elements of array along dimension dim that have a corresponding true array element in mask.

Examples

Method 1:

! Sum all the elements in an array.
       RES = SUM( (/2, 3, 4 /) )
! The result is 9 because (2+3+4) = 9

Method 2:

! A is the array (/ -3, -7, -5, 2, 3 /)
! Sum all elements that are greater than -5.
       RES = SUM( A, MASK = A .GT. -5 )
! The result is 2 because (-3 + 2 + 3) = 2

Method 3:

! B is the array | 4 2 3 |
!                | 7 8 5 |
 
! Sum the elements in each column.
       RES = SUM(B, DIM = 1)
! The result is | 11 10 8 | because (4 + 7) = 11
!                                   (2 + 8) = 10
!                                   (3 + 5) =  8
 
! Sum the elements in each row.
       RES = SUM(B, DIM = 2)
! The result is | 9 20 | because (4 + 2 + 3) =  9
!                                (7 + 8 + 5) = 20
 
! Sum the elements in each row, considering only
! those elements greater than two.
       RES = SUM(B, DIM = 2, MASK = B .GT. 2)
! The result is | 7 20 | because (4 + 3) =  7
!                                (7 + 8 + 5) = 20

SYSTEM (CMD, RESULT)

Passes a command to the operating system for execution. The current process pauses until the command is completed and control is returned from the operating system. An added, optional argument to the subroutine will allow recovery of any return code information from the operating system.

CMD

must be scalar and of type character, specifying the command to execute and any command-line arguments. It is an INTENT(IN) argument.

RESULT

must be a scalar variable of type INTEGER(4). If the argument is not an INTEGER(4) variable, the compiler will generate an (S) level error message. It is an optional INTENT(OUT) argument. The format of the information returned in RESULT is the same as the format returned from the WAIT system call.

Class

Subroutine

Examples

      INTEGER        ULIMIT
      CHARACTER(32)  CMD
      ...
! Check the system ulimit.
      CMD = 'ulimit > ./fort.99'
      CALL SYSTEM(CMD)
      READ(99, *) ULIMIT
      IF (ULIMIT .LT. 2097151) THEN
         ...

     INTEGER RC
     RC=99
     CALL SYSTEM("/bin/test 1 -EQ 2",RC)
     IF (IAND(RC,'ff'z) .EQ. 0) then
       RC = IAND( ISHFT(RC,-8), 'ff'z )
     ELSE
       RC = -1
     ENDIF

Related Information

See the system subroutine in the Technical Reference: Base Operating System and Extensions Volume 1 for details about the underlying implementation.

SYSTEM_CLOCK(COUNT, COUNT_RATE, COUNT_MAX)

Returns integer data from a real-time clock.

COUNT (optional)

must be scalar and of type default integer. It is an INTENT(OUT) argument. It is set to a value based on the current value of the processor clock. The value is incremented by one for each clock count until the value COUNT_MAX is reached and is reset to zero at the next count. It lies in the range of 0 to COUNT_MAX if there is a clock.

COUNT_RATE (optional)

must be scalar and of type default integer. It is an INTENT(OUT) argument. It is set to the number of processor clock counts per second, or to zero if there is no clock.

COUNT_MAX (optional)

must be scalar and of type default integer. It is an INTENT(OUT) argument. It is set to the maximum value that COUNT can have, or to zero if there is no clock.

Class

Subroutine

Examples

! The following example shows how to interpret values
! returned by the subroutine SYSTEM_CLOCK. The processor
! clock is a 24-hour clock. After the call to SYSTEM_CLOCK,
! the COUNT contains the day time expressed in clock ticks
! per second. The number of ticks per second is available
! in the COUNT_RATE. The COUNT_RATE value is processor-
! dependent.
 
INTEGER, DIMENSION(8) :: IV
TIME_SYNC: DO
CALL DATE_AND_TIME(VALUES=IV)
IHR  = IV(5)
IMIN = IV(6)
ISEC = IV(7)
CALL SYSTEM_CLOCK(COUNT=IC, COUNT_RATE=IR, COUNT_MAX=IM)
CALL DATE_AND_TIME(VALUES=IV)
 
IF ((IHR == IV(5)) .AND. (IMIN == IV(6)) .AND. &
  (ISEC == IV(7))) EXIT TIME_SYNC
 
END DO TIME_SYNC
 
IDAY_SEC = 3600*IHR + IMIN*60 + ISEC
IDAY_TICKS = IDAY_SEC * IR
 
IF (IDAY_TICKS /= IC) THEN
  STOP 'clock error'
ENDIF
END

TAN (X)

Tangent function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result approximates tan(X), where X has a value in radians.

Examples

TAN (1.0) has the value 1.5574077 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
TAN	default real	default real	yes
DTAN	double precision real	double precision real	yes
QTAN	REAL(16)	REAL(16)	yes

TAND (X)

Tangent function. Argument in degrees.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

• It approximates tan(X), where X has a value in degrees.

Examples

TAND (45.0) has the value 1.0.

Specific Name	Argument Type	Result Type	Pass As Arg?
TAND	default real	default real	yes
DTAND	double precision real	double precision real	yes
QTAND	REAL(16)	REAL(16)	yes

TANH (X)

Hyperbolic tangent function.

X

must be of type real.

Class

Elemental function

Result Type and Attributes

Same as X.

Result Value

The result has a value equal to tanh(X).

Examples

TANH (1.0) has the value 0.76159416 (approximately).

Specific Name	Argument Type	Result Type	Pass As Arg?
TANH	default real	default real	yes
DTANH	double precision real	double precision real	yes
QTANH	REAL(16)	REAL(16)	yes

TINY (X)

Returns the smallest positive number in the model representing numbers of the same type and kind type parameter as the argument.

X

must be of type real. It may be scalar or array valued.

Class

Inquiry function

Result Type and Attributes

Scalar with the same type as X.

Result Value

The result is:

2.0(MINEXPONENT(X)-1) for real X

Examples

TINY (X) = float(2)^(-126) = 1.17549351e-38. See "Real Data Model".

TRANSFER (SOURCE, MOLD, SIZE)

Returns a result with a physical representation identical to that of SOURCE but interpreted with the type and type parameters of MOLD.

It performs a low-level conversion between types without any sign extension, rounding, blank padding, or other alteration that may occur using other methods of conversion.

SOURCE

is the data entity whose bitwise value you want to transfer to a different type. It may be of any type and may be scalar or array valued.

MOLD

is a data entity that has the type characteristics you want for the result. It may be of any type and may be scalar or array valued. Its value is not used, only its type characteristics.

SIZE (optional)

is the number of elements for the output result. It must be a scalar integer. The corresponding actual argument must not be an optional dummy argument.

Class

Transformational function

Result Type and Attributes

The same type and type parameters as MOLD.

If MOLD is a scalar and SIZE is absent, the result is a scalar.

If MOLD is array valued and SIZE is absent, the result is array valued and of rank one, with the smallest size that is physically large enough to hold SOURCE.

If SIZE is present, the result is array valued of rank one and size SIZE.

Result Value

The physical representation of the result is the same as SOURCE, truncated if the result is smaller or with an undefined trailing portion if the result is larger.

Because the physical representation is unchanged, it is possible to undo the results of TRANSFER as long as the result is not truncated:

      REAL(4) X = 3.141
      DOUBLE PRECISION I, J(6) = (/1,2,3,4,5,6/)
 
! Because x is transferred to a larger representation
! and then back, its value is unchanged.
      X = TRANSFER( TRANSFER( X, I ), X )
 
! j is transferred into a real(4) array large enough to
! hold all its elements, then back into an array of
! its original size, so its value is unchanged too.
      J = TRANSFER( TRANSFER( J, X ), J, SIZE=SIZE(J) )

Examples

TRANSFER (1082130432, 0.0) is 4.0.

TRANSFER ((/1.1,2.2,3.3/), (/(0.0,0.0)/)) is a complex rank-one array of length two whose first element has the value (1.1, 2.2) and whose second element has a real part with the value 3.3. The imaginary part of the second element is undefined.

TRANSFER ((/1.1,2.2,3.3/), (/(0.0,0.0)/), 1) has the value (/(1.1,2.2)/).

TRANSPOSE (MATRIX)

Transposes a two-dimensional array, turning each column into a row and each row into a column.

MATRIX

is an array of any data type, with a rank of two.

Class

Transformational function

Result Value

The result is a two-dimensional array of the same data type as matrix.

The shape of the result is (n,m) where the shape of matrix is (m,n). For example, if the shape of matrix is (2,3), the shape of the result is (3,2).

Each element (i,j) in the result has the value MATRIX (j,i) for i in the range 1-n and j in the range 1-m.

Examples

! A is the array  | 0 -5  8 -7 |
!                 | 2  4 -1  1 |
!                 | 7  5  6 -6 |
! Transpose the columns and rows of A.
       RES = TRANSPOSE( A )
! The result is   |  0  2  7 |
!                 | -5  4  5 |
!                 |  8 -1  6 |
!                 | -7  1 -6 |

TRIM (STRING)

Returns the argument with trailing blank characters removed.

STRING

must be of type character and must be a scalar.

Class

Transformational function

Result Type and Attributes

Character with the same kind type parameter value as STRING and with a length that is the length of STRING less the number of trailing blanks in STRING.

Result Value

• The value of the result is the same as STRING, except trailing blanks are removed.

• If STRING contains no nonblank characters, the result has zero length.

Examples

TRIM (' A B  ') has the value ' A B'.

UBOUND (ARRAY, DIM)

Returns the upper bounds of each dimension in an array, or the upper bound of a specified dimension.

ARRAY

is the array whose upper bounds you want to determine. Its bounds must be defined; that is, it must not be a disassociated pointer or an allocatable array that is not allocated, and if its size is assumed, you can only examine one dimension.

DIM (optional)

is an integer scalar in the range 1 <= DIM <=  rank(array). The corresponding actual argument must not be an optional dummy argument.

Class

Inquiry function

Result Type and Attributes

Default integer.

If DIM is present, the result is a scalar. If DIM is not present, the result is a one-dimensional array with one element for each dimension in array.

Result Value

Each element in the result corresponds to a dimension of array. If array is a whole array or array structure component, these values are equal to the upper bounds. If array is an array section or expression that is not a whole array or array structure component, the values represent the number of elements in each dimension, which may be different than the declared upper bounds of the original array. If a dimension is zero-sized, the corresponding element in the result is zero, regardless of the value of the upper bound.

Examples

! This array illustrates the way UBOUND works with
! different ranges for dimensions.
        REAL A(1:10, -4:5, 4:-5)
 
        RES=UBOUND( A )
! The result is (/ 10, 5, 0 /).
 
        RES=UBOUND( A(:,:,:) )
! The result is (/ 10, 10, 0 /) because the argument
! is an array section.
 
        RES=UBOUND( A(4:10,-4:1,:) )
! The result is (/ 7, 6, 0 /), because for an array section,
! it is the number of elements that is significant.

UNPACK (VECTOR, MASK, FIELD)

Takes some or all elements from a one-dimensional array and rearranges them into another, possibly larger, array.

VECTOR

is a one-dimensional array of any data type. There must be at least as many elements in vector as there are .TRUE. values in mask.

MASK

is a logical array that determines where the elements of vector are placed when they are unpacked.

FIELD

must have the same shape as the mask argument, and the same data type as vector. Its elements are inserted into the result array wherever the corresponding mask element has the value .FALSE..

Class

Transformational function

Result Value

The result is an array with the same shape as mask and the same data type as vector.

The elements of the result are filled in array-element order: if the corresponding element in mask is .TRUE., the result element is filled by the next element of vector; otherwise, it is filled by the corresponding element of field.

Examples

! VECTOR is the array (/ 5, 6, 7, 8 /),
! MASK is | F T T |, FIELD is | -1 -4 -7 |
!         | T F F |           | -2 -5 -8 |
!         | F F T |           | -3 -6 -9 |
 
! Turn the one-dimensional vector into a two-dimensional
! array.  The elements of VECTOR are placed into the .TRUE.
! positions in MASK, and the remaining elements are
! made up of negative values from FIELD.
       RES = UNPACK( VECTOR, MASK, FIELD )
! The result is | -1  6  7 |
!               |  5 -5 -8 |
!               | -3 -6  8 |
 
! Do the same transformation, but using all zeros for the
! replacement values of FIELD.
        RES = UNPACK( VECTOR, MASK, FIELD = 0 )
! The result is | 0 6 7 |
!               | 5 0 0 |
!               | 0 0 8 |

VERIFY (STRING, SET, BACK)

Verify that a set of characters contains all the characters in a string by identifying the position of the first character in a string of characters that does not appear in a given set of characters.

STRING

must be of type character.

SET

must be of type character with the same kind type parameter as STRING.

BACK (optional)

must be of type logical.

Class

Elemental function

Result Type and Attributes

Default integer.

Result Value

• Case (i): If BACK is absent or present with the value .FALSE. and if STRING contains at least one character that is not in SET, the value of the result is the position of the left-most character of STRING that is not in SET.

• Case (ii): If BACK is present with the value .TRUE. and if STRING contains at least one character that is not in SET, the value of the result is the position of the right-most character of STRING that is not in SET.

• Case (iii): The value of the result is zero if each character in STRING is in SET or if STRING has zero length.

Examples

• Case (i): VERIFY ('ABBA', 'A') has the value 2.

• Case (ii): VERIFY ('ABBA', 'A', BACK = .TRUE.) has the value 3.

• Case (iii): VERIFY ('ABBA', 'AB') has the value 0.

(4) The value of ZONE may be incorrect if you have not set up the machine through the smit chtz fastpath, or if you are in a timezone not configurable through smit. You can manually set the TZ environment variable or use the chtz command to ensure the time zone is correctly set up. The format of the TZ variable is documented under the /etc/environment file in the Files Reference