cvmg(3I)

NAME
     CVMGM, CVMGN, CVMGP, CVMGT, CVMGZ - Conditional vector merge functions

SYNOPSIS
     CVMGM ([I=]i, [J=]j, [K=]k)

     CVMGN ([I=]i, [J=]j, [K=]k)

     CVMGP ([I=]i, [J=]j, [K=]k)

     CVMGT ([I=]i, [J=]j, [K=]k)

     CVMGZ ([I=]i, [J=]j, [K=]k)

IMPLEMENTATION
     UNICOS, UNICOS/mk, IRIX systems

     CF90, MIPSpro 7 Fortran 90

STANDARDS
     Fortran extension

DESCRIPTION
     At run time, k is tested.  You can use the conditional vector merge
     (CVMG) functions when an IF statement involving arrays prevents
     vectorization of a loop.  The compiler can vectorize almost all such
     loops, but these functions can be used in older codes.  Scalar
     arguments can also be used with these functions.

     CVMG functions cannot be passed as arguments.  They are elemental
     functions.

     These functions test for the following:

     * CVMGM tests for minus (negative).  i is returned if k < 0.  j is
       returned if k >= 0.

     * CVMGN tests for nonzero.  i is returned if k is not equal to 0.  j
       is returned if k = 0.

     * CVMGP tests for positive or zero.  i is returned if k >= 0.  j is
       returned if k < 0.

     * CVMGT tests for true.  i is returned if k is true.  j is returned if
       k is false.

     * CVMGZ tests for zero.  i is returned if k = 0.  j is returned if k
       is not equal to 0.

     These functions accept the following arguments:

     i     Can be of type logical, Boolean, integer, real, or Cray pointer.

           See the RETURN VALUES section of this man page for more
           information on how the type of i affects the return value.

     j     Can be of type logical, Boolean, integer, real, or Cray pointer.

           See the RETURN VALUES section of this man page for more
           information on how the type of j affects the return value.

     k     Can be of type logical, Boolean, integer, real, or Cray pointer.

           See the RETURN VALUES section of this man page for more
           information on how the type of k affects the return value.

     If k satisfies the condition tested by the function (for example, in
     CVMGP, if k is positive), the first argument (i) is returned as the
     function result.  If k does not satisfy the condition tested by the
     function, j is returned as the function result.

     For operands other than type logical, the vector merge functions are
     not generic with respect to data typing.  They accept arithmetic
     values of different types but interpret them as Boolean type (that is,
     as bit patterns).  The returned function value is also Boolean.
     Therefore, the function reference CVMGT(1.0,2.0,.TRUE.) is not type
     real, with a value of 1.0, but a Boolean value that acts the same as
     1.0 in a floating-point operation.

     A problem can arise if you assume that the function reference is type
     real and use it in an expression or assignment that causes automatic
     type conversion.  For example, if you use the function reference in a
     context where an integer is needed, the result is not valid because
     1.0 and 1 have different bit patterns.

     Because CVMG function values are Boolean, a binary operation involving
     two CVMG functions uses integer arithmetic.  This can produce
     unexpected results in assignments such as the following in which A, B,
     C, and D are real:

          X = CVMGT(A,B,LOGIC1) + CVMGT(C,D,LOCIC2)
                         ! Integer arithmetic, invalid results

     However, when used in an expression with another operand, a CVMG
     function value takes on the type of the other operand, without any
     explicit type conversion.  For example, the following expression uses
     real arithmetic:

          X = 1.0 + CVMGT(2.0,3.0,LEXP)  ! Valid (types agree)

     The following suggestions explain how to prevent bugs when using these
     functions:

     * Use only one CVMG function in a given expression.  If you use more
       than one CVMG function in an expression, use explicit type
       conversion.  This does not generate any additional code.  For
       example:

          X = REAL(CVMGT(1.0,2.0,LTEST)) + REAL(CVMGT(X,Y,LTEST2))

     * Ensure that the assignment type matches the function argument.
       Example:

         X = CVMGT(1.0,2.0,LTEST) ! Valid
         X = REAL(CVMGT(1,2,LTEST)) ! Valid (uses explicit type conversion)
         X = CVMGT(1,2,LTEST) ! Invalid (type mismatch)

     * Never use mixed typing in the first two arguments of a CVMGT
       function.  Example:

          CVMGT(1,2.0,LTEST)  ! DO NOT DO THIS

     The names of these intrinsics cannot be passed as arguments.

NOTES
     The CVMG intrinsic functions are outmoded.  Refer to the Fortran
     Language Reference Manual, Volume 3, for information on outmoded
     features and their preferred standard alternatives.

RETURN VALUES
     For CVMGM, CVMGN, CVMGP, CVMGT, and CVMGZ, the return value is either
     type Boolean, logical, integer, or real, depending on the type of i
     and j.

     On UNICOS and UNICOS/mk systems, type logical is returned if i is of
     type logical; otherwise it is of type Boolean.

     On IRIX systems, if i and j are both of type real, the result type is
     also real.  If i is of type logical, type logical is returned.  In all
     other cases, the return value is of type integer.

EXAMPLES
     Consider the following code:

          DO I = N,M
             X(I) = A(I)
             IF (B(I) .GT. C(I)) X(I) = D(I)
          END DO

     This could be rewritten as follows:

          DO  I = N,M
             X(I) = CVMGT(D(I), A(I), B(I).GT.C(I))
          END DO

     The following rewrite would also be valid:

          DO I = N,M
             X(I) = CVMGP( D(I), A(I), B(I) - C(I))
          END DO

SEE ALSO
     Intrinsic Procedures Reference Manual for the printed version of this
     man page.