Fortran User's Guide

Directives

Use a source code directive, a form of Fortran comment, to pass specific information to the compiler regarding special optimization or parallelization choices. Compiler directives are also called pragmas.

Directives unique to f90 are described in Appendix C.

Note -

Directives are not part of the Fortran standard.

General Directives

The various forms of a Sun general Fortran directive are:

C$PRAGMA keyword
C$PRAGMA keyword
 ( a [ , a
 ]  ) [ , keyword ( a [ , a
 ]  ) ] , 
C$PRAGMA SUN keyword

The variable keyword identifies the specific directive; the a's are arguments.

The general directives recognized only by f77 are:

C(...) -- The listed arguments are external functions written in C.
WEAK (name1[=name2]) -- Define weak symbol bindings.
OPT=n -- Compile subprogram at specified optimization level n.

Other general directives recognized by both f77 and f90 are:

UNROLL=n -- Request optimizer to attempt loop unrolling to depth n.
PIPELOOP=n -- Assert to the optimizer that a loop can be pipelined to a length n.

A general directive has the following syntax:

In column one, any of the comment-indicator characters c, C, !, or *
The next seven characters are $PRAGMA, no blanks, any uppercase or lowercase
In any column, the ! comment-indicator character

Observe the following restrictions:

After the first eight characters, blanks are ignored, and uppercase and lowercase are equivalent, as in Fortran text.
Because it is a comment, a directive cannot be continued, but you can have many C$PRAGMA lines, one after the other, as needed.
If a comment satisfies the above syntax, it is expected to contain one or more directives recognized by the compiler; if it does not, a warning is issued.
The C preprocessor, cpp, will expand macro symbol definitions within a comment or directive line; the Fortran preprocessor, fpp, will not expand macros in comment lines, and will recognizes legitimate f77 and f90 directives and allows limited substitution outside directive keywords. However, be careful with directives that require the keyword SUN. cpp will replace lower-case sun with a predefined value. Also, if you define a cpp macro SUN it may interfere with the SUN directive keyword. A general rule might be to spell those pragmas in mixed case if the source will be processed by cpp or fpp, as in:

C$PRAGMA Sun UNROLL=3

The C Directive (`f77`)

The C() directive specifies that its arguments are external functions written in the C language. It is equivalent to an EXTERNAL declaration except that unlike ordinary external names, the Fortran compiler will not append an underscore to these argument names. See the Sun Fortran Programming Guide for more details.

The C() directive for a particular function should appear before the first reference to that function in each subprogram that contains such a reference.

Example - compiling ABC and XYZ for C:

       EXTERNAL ABC, XYZ  
C$PRAGMA C(ABC, XYZ)

The `UNROLL` Directive

The UNROLL directive requires that you specify SUN after C$PRAGMA.

The C$PRAGMA SUN UNROLL=n directive instructs the compiler to unroll loops n times during its optimization pass.

n is a positive integer. The choices are:

If n=1, this directive directs the optimizer not to unroll any loops.
If n>1, this directive suggests to the optimizer that it unroll loops n times.

If any loops are actually unrolled, the executable file becomes larger. For further information, see the Fortran Programming Guide chapter on performance and optimization.

Example - unrolling loops two times:

C$PRAGMA SUN UNROLL=2

The `WEAK` Directive (`f77`)

The WEAK directive defines a symbol to have less precedence than an earlier definition of the same symbol. This pragma is used mainly in sources files for building libraries. The linker does not produce an error message if it is unable to resolve a weak symbol.

C$PRAGMA WEAK (name1 [=name2])

WEAK (name1) defines name1 to be a weak symbol. The linker does not produce an error message if it does not find a definition for name1.

WEAK (name1=name2) defines name1 to be a weak symbol and an alias for name2.

If your program calls but does not define name1, the linker uses the definition from the library. However, if your program defines its own version of name1, then the program's definition is used and the weak global definition of name1 in the library is not used. If the program directly calls name2, the definition from library is used; a duplicate definition of name2 causes and error. See the Solaris Linker and Libraries Guide for more information.

The `OPT` Directive `(f77)`

The OPT directive requires that you specify SUN after C$PRAGMA.

The OPT directive sets the optimization level for a subprogram, overriding the level specified on the compilation command line. The directive must appear immediately before the target subprogram, and only applies to that subprogram. For example:

C$PRAGMA SUN OPT=2
        SUBROUTINE smart(a,b,c,d,e)
        ...etc

When the above is compiled with an f77 command that specifies -O4, the directive will override this level and compile the subroutine at -O2. Unless there is another directive following this routine, the next subprogram will be compiled at -O4.

The routine must also be compiled with the -xmaxopt=n option for the directive to be recognized. This compiler option specifies a maximum optimization value for PRAGMA OPT directives: if a PRAGMA OPT specifies an optimization level greater than the -xmaxopt level, the -xmaxopt level is used.

(SPARC Only) The `PIPELOOP=n` Directive

The PIPELOOP=n directive requires that you specify SUN after C$PRAGMA.

This directive must appear immediately before a DO loop. n is a positive integer constant, or zero, and asserts to the optimizer a dependency between loop iterations. A value of zero indicates that the loop has no inter-iteration dependencies and can be freely pipelined by the optimizer. A positive n value implies that the I-th iteration of the loop has a dependency on the (I-n)-th iteration, and can be pipelined at best for only n iterations at a time.

C    We know that the value of K is such that there can be no
C    cross-iteration dependencies (E.g. K>N)
C$PRAGMA SUN PIPELOOP=0
      DO I=1,N
       A(I)=A(I+K) + D(I)
       B(I)=B(I) + A(I)
      END DO

For more information on optimization, see the Fortran Programming Guide.

Parallelization Directives

Parallelization directives explicitly request the compiler attempt to parallelize the DO loop that follows the directive. The syntax differs from general directives. Parallelization directives are only recognized when compilation options -parallel or -explicitpar are used. ( expanded f90 parallelization directives are described in Appendix C; details of Fortran parallelization can be found in the Fortran Programming Guide.)

Parallelization directives have the following syntax:

The first character must be in column one.
The first character can be any one of c, C, *, or !.
The next four characters are $PAR, no blanks, either upper or lower case.
Next follows the directive keyword and options, separated by blanks. The explicit parallelization directive keywords are:

TASKCOMMON, DOALL, DOSERIAL, and DOSERIAL*

Each parallelization directive has its own set of optional qualifiers that follow the keyword.

Example: Specifying a loop with a shared variable:

C$PAR DOALL SHARED(yvalue)

See the Fortran Programming Guide for details about parallelization and these directives.

Directives

General Directives

The C Directive (f77)

The UNROLL Directive

The WEAK Directive (f77)