The -ignoreoptions switch directs KAP to ignore any !*$*options or *$*options line that may appear at the top of the input file. Normally, KAP reads the !*$*options or *$*options instruction for further command switches.

Setting -noignoreoptions directs KAP not to ignore the !*$*options line in the source program. That is, KAP will process a !*$*options instruction.

5.8 Input-Output Switches for kapf90

The following sections explain the function of each switch that affects KAP input-output file selection. See Chapter 2 for more details about file name defaults and special cases.

5.8.1 -cmp, (<file>.cmp.f90), (<file>.cmp.f), -nocmp, -ncmp

The -cmp switch causes KAP to save the optimized source program under the file name of your choice. By default kf90 names the optimized source the same name as the input file with an extension determined by the input file extension, as follows:

File Extension of Input	File Extension of Transformed Source
.f90	.cmp.f90
.f, .for, .FOR	.cmp.f

The kapf90 default is to name the optimized source the same name as the input file with the extension .cmp, regardless of the input file extension. Because the Compaq Fortran compiler will not process a file with the default .cmp extension, you should override the default. For example, use the -cmp switch in the kapf90 command line to rename the optimized source file_name.cmp.f90. See the examples in Section 2.7.

Both kf90 and kapf90 place the optimized source file in the current directory. To disable generation of the optimized Fortran 90 output file, enter -nocmp on the command line.

5.8.2 -include, -inc, (-noinclude), ninc

The -include switch allows you to specify an alternate directory for locating the files specified in INCLUDE statements. An INCLUDE file whose name does not begin with a hyphen (-) is sought first in the directory containing the file that contains the INCLUDE statement or directive, then in the directory named in the -include switch.

5.8.3 -list, -l, (<file>.out), -nolist, -nl

The -list switch informs KAP where to place the listing file. If -list=<file> is given, the listing is written to the specified file. To disable generation of the listing file, include -nolist on the command line.

The default for executing the unqualified kf90 command alone is -nolist, because it deletes all intermediate files.

5.9 Listing Switches for kapf90

The following sections explain the function of each listing switch.

5.9.1 -cmpoptions, -cp, -cmpoptions=n, (-nocmpoptions), -ncp

The -cmpoptions switch specifies optional additional information or formatting for a transformed code (.cmp) file. The additional information currently selectable is consistent indentation (-cmpoptions=n).

Specifying -cmpoptions=n tells KAP to create the transformed code from its internal data structures. Specifying -nocmpoptions tells KAP to use lines from the source file, where feasible. Using the internal data structures for the code provides consistent indentation and formatting, but also gives all new labels and other changes from the source code. This may make relating source and transformed code more difficult.

5.9.2 -lines, -ln, (-lines=55)

The -lines switch enables the KAP listing to be paginated for printing on different line printers. You can change the number of lines per page on the listing by using the -lines=number. The -lines=0 switch tells KAP to paginate only at subroutine boundaries.

5.9.3 -listingwidth, -lw, (-listingwidth=132)

The -listingwidth switch sets the maximum line length for the listing file produced by KAP. This setting affects the format of the loop summary table -listoptions=l, KAP options table -listoptions=k, and program listings -listoptions=o,t. The fixed setting, 132, is optimal for most line printers. No other values are allowed.

5.9.4 -listoptions, -lo, (-listoptions=o)

The -listoptions switch tells KAP what optional information to include in the listing, transformed code, and error files.

You can select any of the following information:

Value	Prints
c	Calling tree at the end of the program listing
k	KAP switches used, printed at the end of each program unit
l	Loop-by-loop optimization table
n	Program unit names, as processed, to the error file
o	Annotated listing of the original program
p	Performance statistics
s	Summary of the loop optimizations performed
t	Annotated listing of the transformed program

The transformed program displayed by t is recorded in the transformed code file regardless of whether you request -listoptions=t.

To disable all of the previous switches and produce no listing file, include -nolist on the command line.

See Chapter 10 for examples of the different types of KAP listing output.

5.9.5 -suppress, -su, (off)

The -suppress switch allows you to individually disable the printing of classes of KAP messages. These message classes range from syntax warning and error messages to messages about the optimizations performed. The allowed values of the -suppress switch are as follows:

Value	Disables
d	Data Dependence messages
e	Syntax Error messages
i	Informational messages
n	Not optimized messages
q	Questions
s	Standardized messages
w	Syntax Warning messages

The default tells KAP to give all message types listed.

See Appendix F for examples of KAP listing messages.

5.10 !*$* options

When you determine that a file must always be run with the same command switches, you can use the first line of the file to specify these switches. The format of this line is as follows:

!*$*options -switch[=value] [-switch[=value]]...

The !*$*options (or *$*options) must appear in columns 1 through 11 (or 1 through 10) with a character space between this command and the options that follow, such as:

!*$*options -lines=60 -optimize=4 -scalaropt=2

Only the first line may be used for !*$*options. Short or long switch names may be used on this line. The leading C, the keyword options, and the command-line switches can be uppercase or lowercase.

Switches of the form -switch=<name> (for example, -fortran or -inline) cannot be specified on the !*$*options line of the source file. These switches can be specified on the command line only.

If conflicting switches are specified on the command line and on the !*$*options line, the !*$*options line takes precedence. If additional options are specified on the !*$*options line, these are used in addition to those specified on the command line. If the command switch -ignoreoptions is set, the !*$*options line in the program is treated as a comment.

KAP directives enable, disable, or modify a feature of KAP. Directives function as command switches used within the input file rather than on the command line. To invoke a directive, you must either toggle the directive on, or set a desired value for its level.

With the exception of the !*$* assertions directive, using KAP directives will not affect the correctness of a program. Enabling KAP assertions allows you, through the use of specific assertions, to provide KAP with false information that might lead KAP to perform incorrect transformations. See Chapter 7.

Most KAP directives have corresponding command switches. If conflicting settings are given on the command line and in a directive, KAP uses the value specified on the directive. If command-line control is desired, directives can be disabled (treated as comments) with the -nodirectives switch.

The !*$* inline and !*$* ipa directives are disabled by default. When they are enabled, they take precedence over the inlining and IPA switches.

See Chapter 5 for the command switches related to these directives.

KAP recognizes the Fortran 90 CDEC$ directive. Except for the cpar$ do_parallel directive, KAP copies them to the transformed code file but otherwise ignores them. A cpar$ do_parallel directive is copied to the transformed code file and the immediately following loop nest is left unchanged.

6.1 Directive Usage and Syntax

Directives placed inside a program unit remain in effect from the point of their appearance in the code until the end of the program unit. At the end of the program unit, the directive value defaults to the value set by the command-line switch. You can temporarily override directives in a program unit by partitioning sections of code into directive blocks. Directive blocks allow you to do the following:

• Use directives inside the directive block to override those outside the block
• Use loop directives with arrays
• Use directives to affect code only inside the directive block

The following example shows how command-line switches, directives used outside directive blocks, and directives used inside directive blocks differ in their effective durations:

Command-line switch | | Program Unit A | | !*$* directive | | | | !*$* beginblock | | !*$* directive | | | loop | | | array | | | loop | | -> !*$*endblock | | | | !*$* beginblock | | !*$* directive | | | loop | | | array | | | loop | | -> !*$*endblock | | | -> End | | Program Unit B | | loop A | | !*$* directive | | | | loop B | | | | !*$* beginblock | | !*$* directive | | | loop | | | array | | | loop | | -> !*$*endblock | | | -> End | ->End of source file

Loop directives used inside directive blocks must immediately follow the !*$* beginblock directive. Loop directives used outside of directive blocks must immediately precede the loop they are to affect. In the following example, KAP issues an error message when the loop optimization directive !*$* OPTIMIZE(0) does not immediately precede the DO loop:

!*$* OPTIMIZE( 0 ) nbeg = M-((nn-1)*nstep) nend = max(1,nbeg-nstep+1) DO I=1,N colonne(1,i,nn)=c(1,i,nbeg) colonne(5,i,nn)=c(5,i,nbeg) colonne(8,i,nn)=c(8,i,nbeg) ENDDO

Error message:

### !*$* OPTIMIZE( 0 ) ### in line 6 procedure MOVE2D_PRE of file directive.f90 ### This directive is not adjacent to the loop it applies to. 0 errors in file directive.f KAP -- Syntax Warnings Detected

To correct the error, !*$* OPTIMIZE( 0 ) should immediately precede DO I=1,N.

To use a loop directive with an array, you must enclose the array in a directive block. In the following example, KAP issues an error message when it sees the parallel loop directive !*$* MINCONCURRENT (999999) and the array ddx outside a directive block:

!*$* MINCONCURRENT ( 999999 ) ddx(2:I-1,1:J) = array(3:I,1:J)-array(1:I-2,1:J) ddx(1,1:J) = 2*(array(2,1:J)-array( 1,1:J)) ddx(I,1:J) = 2*(array(I,1:J)-array(I-1,1:J))

Error message:

### !*$* minconcurrent (999999) ### in line 246 procedure DDX of file channel90.f90 ### This directive does not apply to any loop and has been ignored. 0 errors in file channel90.f90 KAP -- Syntax Warnings Detected

To correct the error, enclose the directive and the array with !*$* beginblock and !*$* endblock.

You begin KAP directives with either !*$* or C*$* based on whether the source file is free or fixed format. In free format source files, precede directives with !*$*. Use C*$* in fixed format source files. When the kf90 driver sees a fixed format directive, for example, C*$* minconcurrent (999999), inside a free format source file, channel90.f90, KAP issues an error message, as follows:

Error message:

kf90 channel90.f90 ### C*$* minconcurrent (999999) ### in line 246 procedure DDX of file channel90.f90 ### Statement unrecognizable as any known statement type.

To correct the error precede the minconcurrent directive with !*$*.

6.2 KAP Directives

Table 6-1 lists KAP directives using free format syntax that begins each directive with !*$*. Use C!*$* in fixed format source files.

The first column lists the categories of functions: general optimization, parallel processing, inlining/IPA, assertions, and memory management. The directive name and its range of values are listed in columns one and two.

Table 6-1 KAP Directives

Directive	Range of Values
General Optimization
!*$* arclimit(n) Section 6.3.1	(0-5000)
!*$* beginblock Section 6.3.2	<directive block>
!*$* endblock
!*$* each_invariant_if_growth(n) Section 6.3.3	(0-20)
!*$* limit(n) Section 6.3.4	(_> 0)
!*$* max_invariant_if_growth(n) Section 6.3.5	(0-500)
!*$* optimize(n) Section 6.3.6	(0-5)
!*$* roundoff(n) Section 6.3.7	(0-3)
!*$* scalar optimize(n) Section 6.3.8	(0-3)
!*$* unroll(n1[,n2]) Section 6.3.9	( _> 0 [, _> 0] )
Parallel Processing Directives to Guide Automatic Parallelization
!*$* [no]concurrentize Section 6.4.1	on/off
!*$* minconcurrent Section 6.4.2	(>0)
Inlining and IPA
!*$* [no]inline [scope] [(name)] Section 6.5.1	on/off
!*$* [no]ipa [scope] [(name)] Section 6.5.2	on/off
Assertions
!*$* [no]assertions Section 6.6.1	on/off
Memory Management
!*$* padding (names) (var-list) Section 6.7.1
!*$* storage order (names) (var-list) Section 6.7.2

Each subheading in the following sections lists the directive followed by its range of values in parentheses.

6.3 General Optimization Directives

The following sections explain the function of the general optimization directives.

6.3.1 !*$* arclimit (0--5000)

The arclimit value sets the maximum size of a data structure that KAP uses for data dependence analysis. A larger number means that KAP can keep more information on complex loop nests. The maximum value is 5000. The default value is 5000.

6.3.2 !*$* beginblock <directive block> !*$* endblock

Use the !*$* beginblock and !*$* endblock directives to enclose a segment of source code, called a directive block, where you can declare KAP directives. Place directives immediately following the !*$* beginblock directive. Directives in a directive block remain active until the end of the block and override directives used outside the block.

Directive blocks allow you to use loop directives with Fortran 90 arrays. For example, in the following directive block, KAP first transforms the three arrays into Fortran DO loops. Next, KAP applies the !*$* minconcurrent ( 999999 ) directive to the loops.

!*$* BEGINBLOCK !*$* MINCONCURRENT ( 999999 ) ddx(2:I-1,1:J) = array(3:I,1:J)-array(1:I-2,1:J) ddx(1,1:J) = 2*(array(2,1:J)-array( 1,1:J)) ddx(I,1:J) = 2*(array(I,1:J)-array(I-1,1:J)) !*$* ENDBLOCK

Do not nest directive blocks.

6.3.3 !*$* each_invariant_if_growth (0--100)

When a loop contains an IF statement whose condition does not change from one iteration to another, the same test must be repeated for every iteration. The code can often be made more efficient by floating the IF outside the loop and putting the THEN and ELSE sections into their own loops.

This gets more complicated when there is other code in the loop, because a copy of it must be included in both the THEN and ELSE loops. The !*$* each_invariant_if_growth directive allows you to limit the total additional lines of code generated through invariant-IF restructuring in each loop.

This can be controlled globally with the -each_invariant_if_growth command switch. The maximum amount of additional code generated in a program unit through invariant-IF floating can be limited with the -max_invariant_if_growth switch and directive (see Section 6.3.5).

This directive is in effect to the end of the routine, or until it is reset by a succeeding directive of the same type.

6.3.4 !*$* limit (> 0)

The !*$* limit directive sets the maximum effort KAP will expend on optimizing a loop nest.

The value is a dial to control how much time KAP is to spend optimizing loops; a larger number means that KAP tries to optimize more deeply nested loop structures. The default value is 20000. The -limit command switch sets this first value globally. Setting -limit=0 turns off loop optimization, allowing dusty-deck and other straight-line transformations only.

6.3.5 !*$* max_invariant_if_growth (0--1000)

When a loop contains an IF statement whose condition does not change from one iteration to another, the same test must be repeated for every iteration. The code can often be made more efficient by floating the IF outside the loop and putting the THEN and ELSE sections into their own loops.

This gets more complicated when there is other code in the loop, because a copy of it must be included in both the THEN and ELSE loops. The !*$* max_invariant_if_growth directive allows you to limit the total additional lines of code generated through invariant-IF restructuring in each program unit.

This can be controlled globally with the -max_invariant_if_growth command switch. The maximum amount of additional code generated in a single loop through invariant-IF floating can be limited with the -each_invariant_if_growth switch and directive.

This directive is in effect to the end of the routine, or until it is reset by a succeeding directive of the same type, for example:

!*$*each_invariant_if_growth(<integer>) !*$*max_invariant_if_growth(<integer>) DO I = ... !*$*each_invariant_if_growth(<integer>) !*$*max_invariant_if_growth(<integer>) DO J = ... !*$*each_invariant_if_growth(<integer>) !*$*max_invariant_if_growth(<integer>) DO K = ... section-1 IF ( ) THEN section-2 ELSE section-3 ENDIF section-4 ENDDO ENDDO ENDDO

In floating the invariant-IF out of the loop nest, the constraints set by the innermost directives are honored first. If those constraints are satisfied, then the invariant-IF is floated from the inner loop. The middle pair of directives is tested and the invariant-IF will be floated from the middle loop provided that there is no violation of the restrictions established by these directives. The process of floating continues as long as the directive constraints are satisfied.