The following alphabetical list of options provides all the information you should need to use each option effectively.
How to read the syntax information:
Syntax
-#
Generates information on the progress of the compilation without actually running the individual components.
Rules
At the points where the compiler executes commands to perform different compilation steps, this option displays a simulation of the system calls it would do and the system argument lists it would pass, but it does not actually perform these actions.
Examining the output of this option can help you quickly and safely determine the following information for a particular compilation:
It avoids the overhead of compiling the source code and avoids overwriting any existing files, such as .lst files. (For those who are familiar with the make command, it is similar to make -n.)
Note that if you specify this option with -qipa, the compiler does not display linker information subsequent to the IPA link step. This is because the compiler does not actually call IPA.
Related Information
The -v Option and -V Option produce the same output but also performs the compilation.
Syntax
-1 ONETRIP | NOONETRIP
Executes each DO loop in the compiled program at least once if its DO statement is executed, even if the iteration count is 0. This option provides compatibility with FORTRAN 66. The default is to follow the behavior of later Fortran standards, where DO loops are not performed if the iteration count is 0.
Restrictions
It has no effect on FORALL statements, FORALL constructs, or array constructor implied-DO loops.
Related Information
-qonetrip is the long form of -1.
Syntax
-Bprefix
Determines a substitute path name for executable files used during compilation, such as the compiler or linker. It can be used in combination with the -t option, which determines which of these components are affected by -B.
Arguments
prefix is the name of a directory where the alternative executable files reside. It must end in a / (slash).
Rules
To form the complete path name for each component, the driver program adds prefix to the standard program names. You can restrict the components that are affected by this option by also including one or more -tmnemonic options.
You can also specify default path names for these commands in the configuration file.
This option allows you to keep multiple levels of some or all of the XL Fortran components or to try out an upgraded component before installing it permanently. When keeping multiple levels of XL Fortran available, you might want to put the appropriate -B and -t options into a configuration-file stanza and to use the -F option to select the stanza to use.
Examples
In this example, an earlier level of the XL Fortran components is installed in the directory /opt/ibmcmp/xlf/8.1/exe. To test the upgraded product before making it available to everyone, the system administrator restores the latest install image under the directory /Users/jim and then tries it out with commands similar to:
/Users/jim/opt/ibmcmp/xlf/8.1/bin/xlf95 \
-tFcbhIz -B/Users/jim/opt/ibmcmp/xlf/8.1/exe/ test_suite.f
Once the upgrade meets the acceptance criteria, the system administrator installs it over the old level in /opt/ibmcmp/xlf/8.1.
Related Information
See -t Option, -F Option, and Customizing the Configuration File.
Syntax
-C CHECK | NOCHECK
Checks each reference to an array element, array section, or character substring for correctness.
Rules
At compile time, if the compiler can determine that a reference goes out of bounds, the severity of the error reported is increased to S (severe) when this option is specified.
At run time, if a reference goes out of bounds, the program generates a SIGTRAP signal. By default, this signal ends the program and produces a core dump.
Because the run-time checking can slow execution, you should decide which is the more important factor for each program: the performance impact or the possibility of incorrect results if an error goes undetected. You might decide to use this option only while testing and debugging a program (if performance is more important) or also for compiling the production version (if safety is more important).
Related Information
The -C option prevents some of the optimizations that the -qhot Option performs. You may want to remove the -C option after debugging of your code is complete and to add the -qhot option to achieve a more thorough optimization.
The valid bounds for character substring expressions differ depending on the setting of the -qzerosize option. See -qzerosize Option.
-qsigtrap Option and Installing an Exception Handler describe how to detect and recover from SIGTRAP signals without ending the program.
-qcheck is the long form of -C.
Syntax
-c
Prevents the completed object file from being sent to the ld command for link-editing. With this option, the output is a .o file for each source file.
Using the -o option in combination with -c selects a different name for the .o file. In this case, you can only compile one source file at a time.
Related Information
See -o Option.
Syntax
-D DLINES | NODLINES
Specifies whether the compiler compiles fixed source form lines with a D in column 1 or treats them as comments.
If you specify -D, the fixed source form lines that have a D in column 1 are compiled. The default action is to treat these lines as comment lines. They are typically used for sections of debugging code that need to be turned on and off.
Related Information
-qdlines is the long form of -D.
Syntax
-d
Causes preprocessed source files that are produced by cpp to be kept rather than to be deleted.
Rules
The files that this option produces have names of the form Ffilename.f, derived from the names of the original source files.
Related Information
See Passing Fortran Files through the C Preprocessor.
Syntax
-Fconfig_file | -Fconfig_file:stanza | -F:stanza
Specifies an alternative configuration file, which stanza to use within the configuration file, or both.
The configuration file specifies different kinds of defaults, such as options for particular compilation steps and the locations of various files that the compiler requires. A default configuration file (/etc/opt/ibmcmp/xlf/8.1/xlf.cfg) is supplied at installation time. The default stanza depends on the name of the command used to invoke the compiler (xlf90, xlf90_r, xlf95, xlf95_r, xlf, xlf_r, f77, or fort77).
A simple way to customize the way the compiler works, as an alternative to writing complicated compilation scripts, is to add new stanzas to /etc/opt/ibmcmp/xlf/8.1/xlf.cfg, giving each stanza a different name and a different set of default compiler options. You may find the single, centralized file easier to maintain than many scattered compilation scripts and makefiles.
By running the compiler with an appropriate -F option, you can select the set of options that you want. You might have one set for full optimization, another set for full error checking, and so on.
Restrictions
Because the default configuration file is replaced each time a new compiler release is installed, make sure to save a copy of any new stanzas or compiler options that you add.
Examples
# Use stanza debug in default xlf.cfg. xlf95 -F:debug t.f # Use stanza xlf95 in /Users/fred/xlf.cfg. xlf95 -F/Users/fred/xlf.cfg t.f # Use stanza myxlf in /Users/fred/xlf.cfg. xlf95 -F/Users/fred/xlf.cfg:myxlf t.f
Related Information
Customizing the Configuration File explains the contents of a configuration file and tells how to select different stanzas in the file without using the -F option.
Syntax
-g DBG | NODBG
Generates debug information for use by a symbolic debugger.
Related Information
See Debugging a Fortran 90 or Fortran 95 Program and Symbolic Debugger Support.
-qdbg is the long form of -g.
Syntax
-Idir
Adds a directory to the search path for include files and .mod files. If XL Fortran calls cpp, this option adds a directory to the search path for #include files. Before checking the default directories for include and .mod files, the compiler checks each directory in the search path. For include files, this path is only used if the file name in an INCLUDE line is not provided with an absolute path. For #include files, refer to the cpp documentation for the details of the -I option.
Arguments
dir must be a valid path name (for example, /home/dir, /tmp, or ./subdir).
Rules
The compiler appends a / to the dir and then concatenates that with the file name before making a search. If you specify more than one -I option on the command line, files are searched in the order of the dir names as they appear on the command line.
The following directories are searched, in this order, after any paths that are specified by -I options:
Also, the compiler will search /opt/ibmcmp/xlf/8.1/include where include and .mod files shipped with the compiler are located.
Related Information
The -qmoddir Option puts .mod files in a specific directory when you compile a file that contains modules.
Syntax
-k FREE(F90)
Specifies that the program is in free source form.
Applicable Product Levels
The meaning of this option has changed from XL Fortran Version 2. To get the old behavior of -k, use the option -qfree=ibm instead.
Related Information
See -qfree Option and Free Source Form in the XL Fortran Advanced Edition for Mac OS X Language Reference.
This option is the short form of -qfree=f90.
Syntax
-Ldir
Looks in the specified directory for libraries that are specified by the -l option. If you use libraries other than the default ones in /opt/ibmcmp/xlf/8.1/lib, you can specify one or more -L options that point to the locations of the other libraries.
Rules
This option is passed directly to the ld command and is not processed by XL Fortran at all.
Related Information
See Options That Control Linking and Linking XL Fortran Programs.
Syntax
-lkey
Searches the specified library file, where key selects the library libkey.dylib or libkey.a.
Rules
This option is passed directly to the ld command and is not processed by XL Fortran at all.
Related Information
See Options That Control Linking and Linking XL Fortran Programs.
Syntax
-NSbytes SPILLSIZE(bytes)
Specifies the size of internal program storage areas.
Rules
It defines the number of bytes of stack space to reserve in each subprogram, in case there are too many variables to hold in registers and the program needs temporary storage for register contents.
Defaults
By default, each subprogram stack has 512 bytes of spill space reserved.
If you need this option, a compile-time message informs you of the fact.
Related Information
-qspillsize is the long form of -NS.
Syntax
-O[level] OPTimize[(level)] | NOOPTimize
Specifies whether to optimize code during compilation and, if so, at which level:
Arguments
This level of optimization also affects the setting of the -qfloat option, turning on the fltint and rsqrt suboptions by default, and sets -qmaxmem=-1.
-O4 implies the following other options:
Note that the auto setting of -qarch, -qtune, and -qcache implies that the execution environment will be the same as the compilation environment.
This option follows the "last option wins" conflict resolution rule, so any of the options that are modified by -O4 can be subsequently changed. Specifying -O4 -qarch=ppcv allows aggressive intraprocedural optimization while maintaining code portability.
Restrictions
Generally, use the same optimization level for both the compile and link steps. This is important when using either the -O4 or -O5 optimization level to get the best run-time performance. For the -O5 level, all loop transformations (as specified via the -qhot option) are done at the link step.
Increasing the level of optimization may or may not result in additional performance improvements, depending on whether the additional analysis detects any further optimization opportunities.
An optimization level of -O3 or higher can change the behavior of the program and potentially cause exceptions that would not otherwise occur. Use of the -qstrict option can eliminate potential changes and exceptions.
Compilations with optimization may require more time and machine resources than other compilations.
The more the compiler optimizes a program, the more difficult it is to debug the program with a symbolic debugger.
Related Information
-qstrict Option shows how to turn off the effects of -O3 that might change the semantics of a program.
-qipa Option, -qhot Option, and -qpdf Option turn on additional optimizations that may improve performance for some programs.
Optimizing XL Fortran Programs discusses technical details of the optimization techniques the compiler uses and some strategies you can use to get maximum performance from your code.
-qOPTimize is the long form of -O.
Syntax
-o name
Specifies a name for the output object, executable, or assembler source file.
To choose the name for an object file, use this option in combination with the -c option.
Defaults
The default name for an executable file is a.out. The default name for an object source file is the same as the source file except that it has a .o extension.
Rules
Except when you specify the -c option, the -o option is passed directly to the ld command, instead of being processed by XL Fortran.
Examples
xlf95 t.f # Produces "a.out" xlf95 -c t.f # Produces "t.o" xlf95 -o test_program t.f # Produces "test_program"
Syntax
-p[g]
Sets up the object file for profiling.
-p or -pg prepares the program for profiling. When you execute the program, it produces a gmon.out file with the profiling information. You can then use the gprof command to generate a run-time profile.
Rules
For profiling, the compiler produces monitoring code that counts the number of times each routine is called. The compiler replaces the startup routine of each subprogram with one that calls the monitor subroutine at the start. When the program ends normally, it writes the recorded information to the gmon.out file.
Examples
$ xlf95 -pg needs_tuning.f $ a.out $ gprof . . . detailed and verbose profiling data . . .
Related Information
For more information on profiling and the gprof command, see the man pages for this command.
Syntax
-qalias={[no]aryovrlp | [no]intptr | [no]pteovrlp | [no]std}...
ALIAS( {[NO]ARYOVRLP | [NO]INTPTR | [NO]PTEOVRLP | [NO]STD}... )
Indicates whether a program contains certain categories of aliasing. The compiler limits the scope of some optimizations when there is a possibility that different names are aliases for the same storage locations.
Arguments
Rules
An alias exists when an item in storage can be referred to by more than one name. The Fortran 90 and Fortran 95 standards allow some types of aliasing and disallow some others. The sophisticated optimizations that the XL Fortran compiler performs increase the likelihood of undesirable results when nonstandard aliasing is present, as in the following situations:
Applicable Product Levels
The introduction of the -qipa option does not remove the need for -qalias.
Examples of aryovrlp/noaryovrlp/pteovrlp
If the following subroutine is compiled with -qalias=nopteovrlp, the compiler may be able to generate more efficient code. You can compile this subroutine with -qalias=nopteovrlp, because the integer pointers, ptr1 and ptr2, point at dynamically allocated memory only.
subroutine sub(arg)
real arg
pointer(ptr1, pte1)
pointer(ptr2, pte2)
real pte1, pte2
ptr1 = malloc(%val(4))
ptr2 = malloc(%val(4))
pte1 = arg*arg
pte2 = int(sqrt(arg))
arg = pte1 + pte2
call free(%val(ptr1))
call free(%val(ptr2))
end subroutine
If most array assignments in a compilation unit involve arrays that do not overlap but a few assignments do involve storage-associated arrays, you can code the overlapping assignments with an extra step so that the NOARYOVRLP suboption is still safe to use.
@PROCESS ALIAS(NOARYOVRLP)
! The assertion that no array assignments involve overlapping
! arrays allows the assignment to be done without creating a
! temporary array.
program test
real(8) a(100)
integer :: j=1, k=50, m=51, n=100
a(1:50) = 0.0d0
a(51:100) = 1.0d0
! Timing loop to achieve accurate timing results
do i = 1, 1000000
a(j:k) = a(m:n) ! Here is the array assignment
end do
print *, a
end program
In Fortran, this aliasing is not permitted if J or K are updated, and, if it is left undetected, it can have unpredictable results.
! We cannot assert that this unit is free
! of array-assignment aliasing because of the assignments below.
subroutine sub1
integer a(10), b(10)
equivalence (a, b(3))
a = b ! a and b overlap.
a = a(10:1:-1) ! The elements of a are reversed.
end subroutine
! When the overlapping assignment is recoded to explicitly use a
! temporary array, the array-assignment aliasing is removed.
! Although ALIAS(NOARYOVRLP) does not speed up this assignment,
! subsequent assignments of non-overlapping arrays in this unit
! are optimized.
@PROCESS ALIAS(NOARYOVRLP)
subroutine sub2
integer a(10), b(10), t(10)
equivalence (a, b(3))
t = b; a = t
t = a(10:1:-1); a = t
end subroutine
When SUB1 is called, an alias exists between J and K. J and K refer to the same item in storage.
CALL SUB1(I,I)
...
SUBROUTINE SUB1(J,K)
In the following example, the program might store 5 instead of 6 into J unless -qalias=nostd indicates that an alias might exist.
INTEGER BIG(1000)
INTEGER SMALL(10)
COMMON // BIG
EQUIVALENCE(BIG,SMALL)
...
BIG(500) = 5
SMALL (I) = 6 ! Where I has the value 500
J = BIG(500)
Restrictions
Because this option inhibits some optimizations of some variables, using it can lower performance.
Programs that contain nonstandard or integer POINTER aliasing may produce incorrect results if you do not compile them with the correct -qalias settings. The xlf90, xlf90_r, xlf95, and xlf95_r commands assume that a program contains only standard aliasing (-qalias=aryovrlp:pteovrlp:std:nointptr), while the xlf_r, xlf, and f77/fort77 commands assume that integer POINTERs may be present (-qalias=aryovrlp:pteovrlp:std:intptr).
Syntax
-qalign={[no]4k|struct={natural|packed|port}}
ALIGN({[NO]4K|STRUCT{(natural)|(packed)|(port)}})
Specifies the alignment of data objects in storage, which avoids performance problems with misaligned data. Both the [no]4k and struct options can be specified and are not mutually exclusive. The default setting is -qalign=no4k:struct=natural. The [no]4K option is useful primarily in combination with logical volume I/O and disk striping.
Arguments
| Type | Natural Alignment (in multiples of bytes) |
|---|---|
| INTEGER(1), LOGICAL(1), BYTE, CHARACTER | 1 |
| INTEGER(2), LOGICAL(2) | 2 |
| INTEGER(4), LOGICAL(4), REAL(4) | 4 |
| INTEGER(8), LOGICAL(8), REAL(8), COMPLEX(4) | 8 |
| REAL(16), COMPLEX(8), COMPLEX(16) | 16 |
| Derived | Maximum alignment of its components |
If the natural suboption of the struct option is specified, arrays of derived type are stored so that each component of each element is stored on its natural alignment boundary, unless storage association requires otherwise.
If the port suboption of the struct option is specified,
Restrictions
The port suboption does not affect any arrays or structures with the AUTOMATIC attribute or arrays that are allocated dynamically. Because this option may change the layout of non-sequence derived types, when compiling programs that read or write such objects with unformatted files, use the same setting for this option for all source files.
Related Information
You can tell if an array has the AUTOMATIC attribute and is thus unaffected by -qalign=4k if you look for the keywords AUTOMATIC or CONTROLLED AUTOMATIC in the listing of the -qattr Option. This listing also shows the offsets of data objects.
Syntax
-qarch=architecture
Controls which instructions the compiler can generate. Changing the default can improve performance but might produce code that can only be run on specific machines.
Arguments
The choices for architecture are:
If you intend your program to run only on a particular architecture, you can use the -qarch option to instruct the compiler to generate code specific to that architecture. This allows the compiler to take advantage of machine-specific instructions that can improve performance. The -qarch option provides arguments for you to specify certain chip models; for example, you can specify -qarch=ppc970 to indicate that your program will be executed on Power PC 970 hardware platforms.
For a given application program, make sure that you specify the same -qarch setting when you compile each of its source files.
You can further enhance the performance of programs intended for specific machines by using other perfomance-related options like the -qcache and -qhot options.
Use these guidelines to help you decide whether to use this option:
Related Information
See Compiling for PowerPC Systems, -qtune Option, and -qcache Option.
Syntax
-qassert={
deps | nodeps |
itercnt=n}
Provides information about the characteristics of the files that can help to fine-tune optimizations.
Arguments
Related Information
See Cost Model for Loop Transformations for background information and instructions for using these assertions. See also the description of the ASSERT directive in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qattr[=full] | -qnoattr ATTR[(FULL)] | NOATTR
Specifies whether to produce the attribute component of the attribute and cross-reference section of the listing.
Arguments
If you specify only -qattr, only identifiers that are used are reported. If you specify -qattr=full, all identifiers, whether referenced or not, are reported.
If you specify -qattr after -qattr=full, the full attribute listing is still produced.
You can use the attribute listing to help debug problems caused by incorrectly specified attributes or as a reminder of the attributes of each object while writing new code.
Related Information
See Options That Control Listings and Messages and Attribute and Cross-Reference Section.
Syntax
-qautodbl=setting AUTODBL(setting
Compatibility Benefits
Provides an automatic means of converting single-precision floating-point calculations to double-precision and of converting double-precision calculations to extended-precision.
You might find this option helpful in porting code where storage relationships are significant and different from the XL Fortran defaults. For example, programs that are written for the IBM VS FORTRAN compiler may rely on that compiler's equivalent option.
Suboptions
The -qautodbl suboptions offer different strategies to preserve storage relationships between objects that are promoted or padded and those that are not.
The settings you can use are as follows:
This suboption requires the libxlfpmt4.a library during linking.
This suboption requires the libxlfpmt8.a library during linking.
This suboption requires the libxlfpmt4.a and libxlfpmt8.a libraries during linking.
This suboption requires the libxlfpmt4.a and libxlfpad.a libraries during linking.
This suboption requires the libxlfpmt8.a and libxlfpad.a libraries during linking.
This suboption requires the libxlfpmt4.a, libxlfpmt8.a, and libxlfpad.a libraries during linking.
Linking
If the appropriate -qautodbl option is specified during linking, the program is automatically linked with the necessary extra libraries. Otherwise, you must link them in manually.
Usage
By using dbl4 or dblpad4, you can increase the size of REAL(4) objects without turning REAL(8) objects into REAL(16)s. REAL(16) is less efficient in calculations than REAL(8) is.
The -qautodbl option handles calls to intrinsics with arguments that are promoted; when necessary, the correct higher-precision intrinsic function is substituted. For example, if single-precision items are being promoted, a call in your program to SIN automatically becomes a call to DSIN.
Restrictions
Related Information
For background information on promotion, padding, and storage/value relationships and for some source examples, see Implementation Details for -qautodbl Promotion and Padding.
-qrealsize Option describes another option that works like -qautodbl, but it only affects items that are of default kind type and does not do any padding. If you specify both the -qrealsize and the -qautodbl options, only -qautodbl takes effect. Also, -qautodbl overrides the -qdpc option.
Syntax
-qcache=
{
assoc=number |
auto |
cost=cycles |
level=level |
line=bytes |
size=Kbytes |
type={C|c|D|d|I|i}
}[:...]
Specifies the cache configuration for a specific execution machine. The compiler uses this information to tune program performance, especially for loop operations that can be structured (or blocked) to process only the amount of data that can fit into the data cache.
If you know exactly what type of system a program is intended to be executed on and that system has its instruction or data cache configured differently from the default case (as governed by the -qtune setting), you can specify the exact characteristics of the cache to allow the compiler to compute more precisely the benefits of particular cache-related optimizations.
For the -qcache option to have any effect, you must include the level and type suboptions and specify at least level 2 of -O.
Guidelines
Suboptions
Other levels are possible but are currently undefined. If a system has more than one level of cache, use a separate -qcache option to describe each level.
Restrictions
If you specify the wrong values for the cache configuration or run the program on a machine with a different configuration, the program may not be as fast as possible but will still work correctly. Remember, if you are not sure of the exact values for cache sizes, use a conservative estimate.
Currently, the -qcache option only has an effect when you also specify the -qhot option.
Examples
To tune performance for a system with a combined instruction and data level-1 cache where the cache is two-way associative, 8 KB in size, and has 64-byte cache lines:
xlf95 -O3 -qhot -qcache=type=c:level=1:size=8:line=64:assoc=2 file.f
To tune performance for a system with two levels of data cache, use two -qcache options:
xlf95 -O3 -qhot -qcache=type=D:level=1:size=256:line=256:assoc=4 \
-qcache=type=D:level=2:size=512:line=256:assoc=2 file.f
To tune performance for a system with two types of cache, again use two -qcache options:
xlf95 -O3 -qhot -qcache=type=D:level=1:size=256:line=256:assoc=4 \
-qcache=type=I:level=1:size=512:line=256:assoc=2 file.f
Related Information
See -qtune Option, -qarch Option, and -qhot Option.
Syntax
-qcclines | -qnocclines CCLINES | NOCCLINES
Determines whether the compiler recognizes conditional compilation lines in fixed source form and F90 free source form. IBM free source form is not supported.
Defaults
The default is -qnocclines.
Related Information
See Conditional Compilation in the Language Elements section of the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qcharlen=length CHARLEN(length)
Obsolete. It is still accepted, but it has no effect. The maximum length for character constants and subobjects of constants is 32 767 bytes (32 KB). The maximum length for character variables is 268 435 456 bytes (256 MB).
Syntax
-qcheck | -qnocheck CHECK | NOCHECK
-qcheck is the long form of the -C Option.
Syntax
-qci=numbers CI(numbers)
Specifies the identification numbers (from 1 to 255) of the INCLUDE lines to process. If an INCLUDE line has a number at the end, the file is only included if you specify that number in a -qci option. The set of identification numbers that is recognized is the union of all identification numbers that are specified on all occurrences of the -qci option.
This option allows a kind of conditional compilation because you can put code that is only sometimes needed (such as debugging WRITE statements, additional error-checking code, or XLF-specific code) into separate files and decide for each compilation whether to process them.
Examples
REAL X /1.0/ INCLUDE 'print_all_variables.f' 1 X = 2.5 INCLUDE 'print_all_variables.f' 1 INCLUDE 'test_value_of_x.f' 2 END
In this example, compiling without the -qci option simply declares X and assigns it a value. Compiling with -qci=1 includes two instances of an include file, and compiling with -qci=1:2 includes both include files.
Restrictions
Because the optional number in INCLUDE lines is not a widespread Fortran feature, using it may restrict the portability of a program.
Related Information
See the section on the INCLUDE directive in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qcommon | -qnocommon COMMON| NOCOMMON
Controls whether global variables are allocated in the common or data section of object file.
By default, all uninitialized global variables are allocated in the common section. When -qnocommon is set, global variables are allocated in the data section of the object file. Setting -qnocommon prevents global variables from being simultaneously defined in different object files. Common symbols cannot be used in shared libraries.
Syntax
-qcompact | -qnocompact COMPACT | NOCOMPACT
Reduces optimizations that increase code size.
By default, some techniques the optimizer uses to improve performance may also make the program larger. For systems with limited storage, you can use -qcompact to reduce the expansion that takes place.
Rules
With -qcompact in effect, other optimization options still work; the reductions in code size come from limiting code replication that is done automatically during optimization.
Syntax
-qcr | -qnocr
Allows you to control how the compiler interprets the CR (carriage return) character. By default, the CR (Hex value X'0d') or LF (Hex value X'0a') character, or the CRLF (Hex value X'0d0a') combination indicates line termination in a source file. This allows you to compile code written using a Mac OS or DOS/Windows editor.
If you specify -qnocr, the compiler recognizes only the LF character as a line terminator. You must specify -qnocr if you use the CR character for a purpose other than line termination.
Syntax
-qctyplss[(=[no]arg)] | -qnoctyplss CTYPLSS[([NO]ARG)]| NOCTYPLSS
Specifies whether character constant expressions are allowed wherever typeless constants may be used. This language extension might be needed when you are porting programs from other platforms.
Arguments
Rules
With -qctyplss, character constant expressions are treated as if they were Hollerith constants and thus can be used in logical and arithmetic expressions.
Restrictions
Examples
Example 1: In the following example, the compiler option -qctyplss allows the use of a character constant expression.
@PROCESS CTYPLSS
INTEGER I,J
INTEGER, PARAMETER :: K(1) = (/97/)
CHARACTER, PARAMETER :: C(1) = (/'A'/)
I = 4HABCD ! Hollerith constant
J = 'ABCD' ! I and J have the same bit representation
! These calls are to routines in other languages.
CALL SUB(%VAL('A')) ! Equivalent to CALL SUB(97)
CALL SUB(%VAL(1HA)) ! Equivalent to CALL SUB(1627389952)"
! These statements are not allowed because of the constant-array
! restriction.
! I = C // C
! I = C(1)
! I = CHAR(K(1))
END
Example 2: In the following example, the variable J is passed by reference. The suboption arg specifies that the Hollerith constant is passed as if it were an integer actual argument.
@PROCESS CTYPLSS(ARG)
INTEGER :: J
J = 3HIBM
! These calls are to routines in other languages.
CALL SUB(J)
CALL SUB(3HIBM) ! The Hollerith constant is passed as if
! it were an integer actual argument
Related Information
See Hollerith Constants in the XL Fortran Advanced Edition for Mac OS X Language Reference and Passing Arguments By Reference or By Value.
Syntax
-qdbg | -qnodbg DBG | NODBG
-qdbg is the long form of the -g Option.
Syntax
-qddim | -qnoddim DDIM | NODDIM
Specifies that the bounds of pointee arrays are re-evaluated each time the arrays are referenced and removes some restrictions on the bounds expressions for pointee arrays.
Rules
By default, a pointee array can only have dimension declarators containing variable names if the array appears in a subprogram, and any variables in the dimension declarators must be dummy arguments, members of a common block, or use- or host-associated. The size of the dimension is evaluated on entry to the subprogram and remains constant during execution of the subprogram.
With the -qddim option:
Examples
@PROCESS DDIM INTEGER PTE, N, ARRAY(10) POINTER (P, PTE(N)) DO I=1, 10 ARRAY(I)=I END DO N = 5 P = LOC(ARRAY(2)) PRINT *, PTE ! Print elements 2 through 6. N = 7 ! Increase the size. PRINT *, PTE ! Print elements 2 through 8. END
Syntax
-qdirective[=directive_list] | -qnodirective[=directive_list] DIRECTIVE[(directive_list)] | NODIRECTIVE[(directive_list)]
Specifies sequences of characters, known as trigger constants, that identify comment lines as compiler comment directives.
Background Information
A directive is a line that is not a Fortran statement but is recognized and acted on by the compiler. The compiler always recognizes some directives, such as @PROCESS. To allow you maximum flexibility, any new directives that might be provided with the XL Fortran compiler in the future will be placed inside comment lines. This avoids portability problems if other compilers do not recognize the directives.
Defaults
The compiler recognizes the default trigger constant IBM*.
Arguments
The -qnodirective option with no directive_list turns off all previously specified directive identifiers; with a directive_list, it turns off only the selected identifiers.
-qdirective with no directive_list turns on the default trigger constant IBM* if it has been turned off by a previous -qnodirective.
Notes
xlf95 -qdirective='dbg*' -qnodirective='IBM*' directives.f
Examples
@PROCESS FREE
PROGRAM DIRECTV
INTEGER A, B, C, D, E, F
A = 1 ! Begin in free source form.
B = 2
!OLDSTYLE SOURCEFORM(FIXED)
! Switch to fixed source form for this include file that has not
! been converted yet.
INCLUDE 'set_c_and_d.inc'
!IBM* SOURCEFORM(FREE)
E = 5 ! Back to free source form.
F = 6
END
For this example, compile with the option -qdirective=oldstyle to ensure that the compiler recognizes the SOURCEFORM directive before the INCLUDE line. After converting the include file to use free source form, you can compile with the -qnodirective option, and the SOURCEFORM(FIXED) directive is ignored.
Related Information
See the section on the SOURCEFORM directive in the XL Fortran Advanced Edition for Mac OS X Language Reference.
As the use of incorrect trigger constants can generate warning messages or error messages or both, you should check the particular directive statement in the Directives section of the XL Fortran Advanced Edition for Mac OS X Language Reference for the suitable associated trigger constant.
Syntax
-qdlines | -qnodlines DLINES | NODLINES
-qdlines is the long form of the -D Option.
Syntax
-qdpc[=e] | -qnodpc DPC[(E)] | NODPC
Increases the precision of real constants, for maximum accuracy when assigning real constants to DOUBLE PRECISION variables. This language extension might be needed when you are porting programs from other platforms.
Rules
If you specify -qdpc, all basic real constants (for example, 1.1) are treated as double-precision constants; the compiler preserves some digits of precision that would otherwise be lost during the assignment to the DOUBLE PRECISION variable. If you specify -qdpc=e, all single-precision constants, including constants with an e exponent, are treated as double-precision constants.
This option does not affect constants with a kind type parameter specified.
Examples
@process nodpc
subroutine nodpc
real x
double precision y
data x /1.000000000001/ ! The trailing digit is lost
data y /1.000000000001/ ! The trailing digit is lost
print *, x, y, x .eq. y ! So x is considered equal to y
end
@process dpc
subroutine dpc
real x
double precision y
data x /1.000000000001/ ! The trailing digit is lost
data y /1.000000000001/ ! The trailing digit is preserved
print *, x, y, x .eq. y ! So x and y are considered different
end
program testdpc
call nodpc
call dpc
end
When compiled, this program prints the following:
1.000000000 1.00000000000000000 T 1.000000000 1.00000000000100009 F
showing that with -qdpc the extra precision is preserved.
Related Information
-qautodbl Option and -qrealsize Option are more general-purpose options that can also do what -qdpc does. -qdpc has no effect if you specify either of these options.
Syntax
-qescape | -qnoescape ESCAPE | NOESCAPE
Specifies how the backslash is treated in character strings, Hollerith constants, H edit descriptors, and character string edit descriptors. It can be treated as an escape character or as a backslash character. This language extension might be needed when you are porting programs from other platforms.
Defaults
By default, the backslash is interpreted as an escape character in these contexts. If you specify -qnoescape, the backslash is treated as the backslash character.
The default setting is useful for the following:
If you are writing or porting code that depends on backslash characters being passed through unchanged, specify -qnoescape so that they do not get any special interpretation. You could also write \\ to mean a single backslash character under the default setting.
Examples
$ # Demonstrate how backslashes can affect the output
$ cat escape.f
PRINT *,'a\bcde\fg'
END
$ xlf95 escape.f
** _main === End of Compilation 1 ===
1501-510 Compilation successful for file escape.f.
$ a.out
cde
g
$ xlf95 -qnoescape escape.f
** _main === End of Compilation 1 ===
1501-510 Compilation successful for file escape.f.
$ a.out
a\bcde\fg
In the first compilation, with the default setting of -qescape, \b is printed as a backspace, and \f is printed as a formfeed character. With the -qnoescape option specified, the backslashes are printed like any other character.
Related Information
The list of escape sequences that XL Fortran recognizes is shown in Table 19.
Syntax
-qextern=names
Allows user-written procedures to be called instead of XL Fortran intrinsics. names is a list of procedure names separated by colons. The procedure names are treated as if they appear in an EXTERNAL statement in each compilation unit being compiled. If any of your procedure names conflict with XL Fortran intrinsic procedures, use this option to call the procedures in the source code instead of the intrinsic ones.
Arguments
Separate the procedure names with colons.
Applicable Product Levels
Because of the many Fortran 90 and Fortran 95 intrinsic functions and subroutines, you might need to use this option even if you did not need it for FORTRAN 77 programs.
Examples
subroutine matmul(res, aa, bb, ext)
implicit none
integer ext, i, j, k
real aa(ext, ext), bb(ext, ext), res(ext, ext), temp
do i = 1, ext
do j = 1, ext
temp = 0
do k = 1, ext
temp = temp + aa(i, k) * bb(k, j)
end do
res(i, j) = temp
end do
end do
end subroutine
implicit none
integer i, j, irand
integer, parameter :: ext = 100
real ma(ext, ext), mb(ext, ext), res(ext, ext)
do i = 1, ext
do j = 1, ext
ma(i, j) = float(irand())
mb(i, j) = float(irand())
end do
end do
call matmul(res, ma, mb, ext)
end
Compiling this program with no options fails because the call to MATMUL is actually calling the intrinsic subroutine, not the subroutine defined in the program. Compiling with -qextern=matmul allows the program to be compiled and run successfully.
Syntax
-qextname[=name1[:name2...]] | -qnoextname EXTNAME[(name1: name2:...)] | NOEXTNAME
Adds an underscore to the names of all global entities, which helps in porting programs from systems where this is a convention for mixed-language programs. Use -qextname=name1[:name2...] to identify a specific global entity (or entities). For a list of named entities, separate each name with a colon.
The name of a main program is not affected.
The -qextname option helps to port mixed-language programs to XL Fortran without modifications. Use of this option avoids naming problems that might otherwise be caused by:
Restrictions
You must compile all the source files for a program, including the source files of any required module files, with the same -qextname setting.
If you use the xlfutility module to ensure that the Service and Utility subprograms are correctly declared, you must change the name to xlfutility_extname when compiling with -qextname.
If there is more than one Service and Utility subprogram referenced in a compilation unit, using -qextname with no names specified and the xlfutility_extname module may cause the procedure declaration check not to work accurately.
Examples
@PROCESS EXTNAME
SUBROUTINE STORE_DATA
CALL FLUSH(10) ! Using EXTNAME, we can drop the final underscore.
END SUBROUTINE
@PROCESS(EXTNAME(sub1)) program main external :: sub1, sub2 call sub1() ! An underscore is added. call sub2() ! No underscore is added. end program
Related Information
This option also affects the names that are specified in several other options, so you do not have to include underscores in their names on the command line. The affected options are -qextern Option and -qsigtrap Option.
Syntax
-qfixed[=right_margin] FIXED[(right_margin)]
Indicates that the input source program is in fixed source form and optionally specifies the maximum line length.
The source form specified when executing the compiler applies to all of the input files, although you can switch the form for a compilation unit by using a FREE or FIXED @PROCESS directive or switch the form for the rest of the file by using a SOURCEFORM comment directive (even inside a compilation unit).
For source code from some other systems, you may find you need to specify a right margin larger than the default. This option allows a maximum right margin of 132.
Defaults
-qfixed=72 is the default for the xlf, xlf_r, f77, and fort77 commands. -qfree=f90 is the default for the xlf90, xlf90_r, xlf95, and xlf95_r commands.
Related Information
See -qfree Option.
For the precise specifications of this source form, see Fixed Source Form in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qflag=listing_severity:terminal_severity FLAG(listing_severity,terminal_severity)
You must specify both listing_severity and terminal_severity.
Limits the diagnostic messages to those of a specified level or higher. Only messages with severity listing_severity or higher are written to the listing file. Only messages with severity terminal_severity or higher are written to the terminal. -w is a short form for -qflag=e:e.
Arguments
The severity levels (from lowest to highest) are:
The -qflag option overrides any -qlanglvl or -qsaa options specified.
Defaults
The default for this option is i:i so that you do not miss any important informational messages.
Related Information
See -qlanglvl Option and Understanding XL Fortran Error Messages.
Syntax
-qfloat=options FLOAT(options)
Selects different strategies for speeding up or improving the accuracy of floating-point calculations.
This option replaces several separate options. For any new code, you should use it instead of -qfold, -qmaf, or related options.
You should be familiar with the information in XL Fortran Floating-Point Processing and the IEEE standard before attempting to change any -qfloat settings.
Defaults
The default setting uses the suboptions nocomplexgcc, nofltint, fold, maf, nonans, norrm, norsqrt, and nostrictnmaf. Some options change this default, as explained below.
The default setting of each suboption remains in effect unless you explicitly change it. For example, if you select -qfloat=nofold, the settings for related options are not affected.
Arguments
The available suboptions each have a positive and negative form, such as fold and nofold, where the negative form is the opposite of the positive.
The suboptions are as follows:
The library function, which is called by default if -qfloat=fltint is not specified or implied by another option, checks for floating-point values outside the representable range of integers and returns the minimum or maximum representable integer if passed an out-of-range floating-point value.
The Fortran language does not require checking for floating-point values outside the representable range of integers. In order to improve efficiency, the inline sequence used by -qfloat=fltint does not perform this check. If passed a value that is out of range, the inline sequence will produce undefined results.
Although this suboption is turned off by default, it is turned on by the -O3 optimization level unless you also specify -qstrict.
Although this suboption is turned off by default, specifying -O3 turns it on unless you also specify -qstrict.
To ensure strict semantics, specify both -qstrict and -qfloat=strictnmaf.
Syntax
-qflttrap[=suboptions] | -qnoflttrap FLTTRAP[(suboptions)] | NOFLTTRAP
Determines what types of floating-point exception conditions to detect at run time. The program receives a SIGFPE signal when the corresponding exception occurs.
Arguments
Defaults
The -qflttrap option without suboptions is equivalent to -qflttrap=ov:und:zero:inv:inex. However, because this default does not include enable, it is probably only useful if you already use fpsets or similar subroutines in your source. If you specify -qflttrap more than once, both with and without suboptions, the -qflttrap without suboptions is ignored.
Examples
When you compile this program:
REAL X, Y, Z
DATA X /5.0/, Y /0.0/
Z = X / Y
END
with the command:
xlf95 -qflttrap=zerodivide:enable -qsigtrap divide_by_zero.f
the program stops when the division is performed.
The zerodivide suboption identifies the type of exception to guard against. The enable suboption causes a SIGFPE signal when the exception occurs. The -qsigtrap option produces informative output when the signal stops the program.
Related Information
See -qsigtrap Option.
See Detecting and Trapping Floating-Point Exceptions for full instructions on how and when to use the -qflttrap option, especially if you are just starting to use it.
Syntax
-qfree[={f90|ibm}]
FREE[({F90|IBM})]
Indicates that the source code is in free source form. The ibm and f90 suboptions specify compatibility with the free source form defined for VS FORTRAN and Fortran 90, respectively. Note that the free source form defined for Fortran 90 also applies to Fortran 95.
The source form specified when executing the compiler applies to all of the input files, although you can switch the form for a compilation unit by using a FREE or FIXED @PROCESS directive or for the rest of the file by using a SOURCEFORM comment directive (even inside a compilation unit).
Defaults
-qfree by itself specifies Fortran 90 free source form.
-qfixed=72 is the default for the xlf, xlf_r, f77, and fort77 commands. -qfree=f90 is the default for the xlf90, xlf90_r, xlf95, and xlf95_r commands.
Related Information
See -qfixed Option.
-k is equivalent to -qfree=f90.
Fortran 90 free source form is explained in Free Source Form in the XL Fortran Advanced Edition for Mac OS X Language Reference. It is the format to use for maximum portability across compilers that support Fortran 90 and Fortran 95 features now and in the future.
IBM free source form is equivalent to the free format of the IBM VS FORTRAN compiler, and it is intended to help port programs from the z/OS(R) platform. It is explained in IBM Free Source Form in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qfullpath | -qnofullpath
Records the full, or absolute, path names of source and include files in object files compiled with debugging information (-g option).
If you need to move an executable file into a different directory before debugging it or have multiple versions of the source files and want to ensure that the debugger uses the original source files, use the -qfullpath option in combination with the -g option so that source-level debuggers can locate the correct source files.
Defaults
By default, the compiler records the relative path names of the original source file in each .o file. It may also record relative path names for include files.
Restrictions
Although -qfullpath works without the -g option, you cannot do source-level debugging unless you also specify the -g option.
Examples
In this example, the executable file is moved after being created, but the debugger can still locate the original source files:
$ xlf95 -g -qfullpath file1.f file2.f file3.f -o debug_version ... $ mv debug_version $HOME/test_bucket $ cd $HOME/test_bucket $ gdb debug_version
Related Information
See -g Option.
Syntax
-qhalt=severity HALT(severity)
Stops before producing any object, executable, or assembler source files if the maximum severity of compile-time messages equals or exceeds the specified severity. severity is one of i, l, w, e, s, u, or q, meaning informational, language, warning, error, severe error, unrecoverable error, or a severity indicating "don't stop".
Arguments
The severity levels (from lowest to highest) are:
Defaults
The default is -qhalt=s, which prevents the compiler from generating an object file when compilation fails.
Restrictions
The -qhalt option can override the -qobject option, and -qnoobject can override -qhalt.
Syntax
-qhot[=suboptions] | -qnohot HOT[=suboptions] | NOHOT
Determines whether to perform high-order transformations on loops and array language during optimization and whether to pad array dimensions and data objects to avoid cache misses.
Because of the implementation of the cache architecture, array dimensions that are powers of two can lead to decreased cache utilization. The optional arraypad suboption permits the compiler to increase the dimensions of arrays where doing so might improve the efficiency of array-processing loops. If you have large arrays with some dimensions (particularly the first one) that are powers of 2 or if you find that your array-processing programs are slowed down by cache misses or page faults, consider specifying -qhot=arraypad.
If you do not specify at least level 2 of -O for -qhot, the compiler assumes -O2.
Arguments
Because n is an integral value, we recommend that pad values be multiples of the largest array element size, typically 4, 8, or 16.
For both the arraypad and arraypad=n options, no checking for reshaping or equivalences is performed. If padding takes place, your compiled program may produce unpredictable results.
Restrictions
The -C option turns off the transformations.
Related Information
Optimizing Loops and Array Language lists the transformations that are performed.
Syntax
-qieee={Near | Minus | Plus | Zero}
IEEE({Near | Minus | Plus | Zero})
Specifies the rounding mode for the compiler to use when it evaluates constant floating-point expressions at compile time.
Arguments
The choices are:
This option is intended for use in combination with the XL Fortran subroutine fpsets or some other method of changing the rounding mode at run time. It sets the rounding mode that is used for compile-time arithmetic (for example, evaluating constant expressions such as 2.0/3.5). By specifying the same rounding mode for compile-time and run-time operations, you can avoid inconsistencies in floating-point results.
If you change the rounding mode to other than the default (round-to-nearest) at run time, be sure to also specify -qfloat=rrm to turn off optimizations that only apply in the default rounding mode.
Related Information
See Selecting the Rounding Mode, -O Option, and -qfloat Option.
Syntax
-qinit=f90ptr INIT(F90PTR)
Makes the initial association status of pointers disassociated. Note that this applies to Fortran 95 as well as Fortran 90.
You can use this option to help locate and fix problems that are due to using a pointer before you define it.
Related Information
See Pointer Association in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qinitauto[=hex_value] | -qnoinitauto
Initializes each byte or word (4 bytes) of storage for automatic variables to a specific value, depending on the length of the hex_value. This helps you to locate variables that are referenced before being defined. For example, by using both the -qinitauto option to initialize REAL variables with a signaling NAN value and the -qflttrap option, it is possible to identify references to uninitialized REAL variables at run time.
Setting hex_value to zero ensures that all automatic variables are cleared before being used. Some programs assume that variables are initialized to zero and do not work when they are not. Other programs may work if they are not optimized but fail when they are optimized. Typically, setting all the variables to all zero bytes prevents such run-time errors. It is better to locate the variables that require zeroing and insert code in your program to do so than to rely on this option to do it for you. Using this option will generally zero more things than necessary and may result in slower programs.
To locate and fix these errors, set the bytes to a value other than zero, which will consistently reproduce incorrect results. This method is especially valuable in cases where adding debugging statements or loading the program into a symbolic debugger makes the error go away.
Setting hex_value to FF (255) gives REAL and COMPLEX variables an initial value of "negative not a number", or -quiet NAN. Any operations on these variables will also result in quiet NAN values, making it clear that an uninitialized variable has been used in a calculation.
This option can help you to debug programs with uninitialized variables in subprograms; for example, you can use it to initialize REAL variables with a signaling NAN value. You can initialize 8-byte REAL variables to double-precision signaling NAN values by specifying an 8-digit hexadecimal number, that, when repeated, has a double-precision signaling NAN value. For example, you could specify a number such as 7FBFFFFF, that, when stored in a REAL(4) variable, has a single-precision signaling NAN value. The value 7FF7FFFF, when stored in a REAL(4) variable, has a single-precision quiet NAN value. If the same number is stored twice in a REAL(8) variable (7FF7FFFF7FF7FFFF), it has a double-precision signaling NAN value.
Arguments
Defaults
Restrictions
Examples
The following example shows how to perform word initialization of automatic variables:
subroutine sub() integer(4), automatic :: i4 character, automatic :: c real(4), automatic :: r4 real(8), automatic :: r8 end subroutine
When you compile the code with the following option, the compiler performs word initialization, as the hex_value is longer than 2 digits:
-qinitauto=0cf
The compiler initializes the variables as follows, padding the
hex_value with zeros in the cases of the i4,
r4, and r8 variables and truncating the first
hexadecimal digit in the case of the c variable:
| Variable | Value |
|---|---|
| i4 | 000000CF |
| c | CF |
| r4 | 000000CF |
| r8 | 000000CF000000CF |
Related Information
See -qflttrap Option and the section on the AUTOMATIC directive in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qintlog | -qnointlog INTLOG | NOINTLOG
Specifies that you can mix integer and logical data entities in expressions and statements. Logical operators that you specify with integer operands act upon those integers in a bit-wise manner, and integer operators treat the contents of logical operands as integers.
Restrictions
The following operations do not allow the use of logical variables:
Examples
INTEGER I, MASK, LOW_ORDER_BYTE, TWOS_COMPLEMENT I = 32767 MASK = 255 ! Find the low-order byte of an integer. LOW_ORDER_BYTE = I .AND. MASK ! Find the twos complement of an integer. TWOS_COMPLEMENT = .NOT. I END
Related Information
You can also use the intrinsic functions IAND, IOR, IEOR, and NOT to perform bitwise logical operations.
Syntax
-qintsize=bytes INTSIZE(bytes)
Sets the size of default INTEGER and LOGICAL data entities (that is, those for which no length or kind is specified).
Background Information
The specified size 1 applies to these data entities:
Allowed sizes for bytes are:
This option is intended to allow you to port programs unchanged from systems that have different default sizes for data. For example, you might need -qintsize=2 for programs that are written for a 16-bit microprocessor or -qintsize=8 for programs that are written for a CRAY computer. The default value of 4 for this option is suitable for code that is written specifically for many 32-bit computers.
Restrictions
This option is not intended as a general-purpose method for increasing the sizes of data entities. Its use is limited to maintaining compatibility with code that is written for other systems.
You might need to add PARAMETER statements to give explicit lengths to constants that you pass as arguments.
Examples
In the following example, note how variables, literal constants, intrinsics, arithmetic operators, and input/output operations all handle the changed default integer size.
@PROCESS INTSIZE(8)
PROGRAM INTSIZETEST
INTEGER I
I = -9223372036854775807 ! I is big enough to hold this constant.
J = ABS(I) ! So is implicit integer J.
IF (I .NE. J) THEN
PRINT *, I, '.NE.', J
END IF
END
The following example only works with the default size for integers:
CALL SUB(17)
END
SUBROUTINE SUB(I)
INTEGER(4) I ! But INTSIZE may change "17"
! to INTEGER(2) or INTEGER(8).
...
END
If you change the default value, you must either declare the variable I as INTEGER instead of INTEGER(4) or give a length to the actual argument, as follows:
@PROCESS INTSIZE(8)
INTEGER(4) X
PARAMETER(X=17)
CALL SUB(X) ! Use a parameter with the right length, or
CALL SUB(17_4) ! use a constant with the right kind.
END
Related Information
See -qrealsize Option and Type Parameters and Specifiers in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qipa[=suboptions] -qnoipa
Enhances -O optimization by doing detailed analysis across procedures (interprocedural analysis or IPA).
You must also specify the -O, -O2, -O3, -O4, or -O5 option when you specify -qipa. (Specifying the -O5 option is equivalent to specifying the -O4 option plus -qipa=level=2.) The -qipa option extends the area that is examined during optimization and inlining from a single procedure to multiple procedures (possibly in different source files) and the linkage between them.
You can fine-tune the optimizations that are performed by specifying suboptions.
To use this option, the necessary steps are:
During compilation, the compiler stores interprocedural analysis information in the .o file. During linking, the -qipa option causes a complete reoptimization of the entire application.
Note that if you specify this option with -#, the compiler does not display linker information subsequent to the IPA link step. This is because the compiler does not actually call IPA.
Arguments
IPA uses the following suboptions during its compile-time phase:
If compiling and linking are performed in the same step and you do not specify any listing option, -qipa=noobject is implied.
If your program contains object files created with the noobject suboption, you must use the -qipa option to compile any files containing an entry point (the main program for an executable program or an exported procedure for a library) before linking your program with -qipa.
IPA uses the following suboptions during its link-time phase:
The default level is 1.
Specifies an output listing file name during the link phase, in the event that an object listing has been requested using either the -qlist or the -qipa=list compiler option and allows the user to direct the type of output. If you do not specify the filename suboption, the default file name is "a.lst".
If you specify short, the Object File Map, Source File Map, and Global Symbols Map sections are included. If you specify long, the preceding sections appear in addition to the Object Resolution Warnings, Object Reference Map, Inliner Report, and Partition Map sections.
If you specify the -qipa and -qlist options together, IPA generates an a.lst file that overwrites any existing a.lst file. If you have a source file named a.f, the IPA listing will overwrite the regular compiler listing a.lst. You can use the list=filename suboption to specify an alternative listing file name.
Specifies the name of the profile data file containing the PDF profiling information. If you do not specify a filename, the default file name is __pdf. The profile is placed in the current working directory or in the directory that the PDFDIR environment variable names. This allows the programmer to do simultaneous runs of multiple executables using the same PDFDIR. This is especially useful when tuning with PDF on dynamic libraries. (See -qpdf Option for more information on tuning optimizations.)
The primary use of isolated, missing, pure, safe, and unknown is to specify how much optimization can safely be performed on calls to library routines that are not compiled with -qipa.
The following compiler options have an effect on the link-time phase of -qipa:
Rules
Regular expressions are supported for the following suboptions:
Syntax rules for regular expressions are described below.
Table 13. Regular expression syntax
| Expression | Description |
|---|---|
| string | Matches any of the characters specified in string. For example, test will match testimony, latest, intestine. |
| ^string | Matches the pattern specified by string only if it occurs at the beginning of a line. |
| string$ | Matches the pattern specified by string only if it occurs at the end of a line. |
| str.ing | Matches any character. For example, t.st will match test, tast, tZst, and t1st. |
| string\.$ | The backslash (\) can be used to escape special characters so that you can match for the character. For example, if you want to find those lines ending with a period, the expression .$ would show all lines that had at least one character. Specify \.$ to escape the period (.). |
| [string] | Matches any of the characters specified in string. For example, t[a-g123]st matches tast and test, but not t-st or tAst. |
| [^string] | Does not match any of the characters specified in string. For example, t[^a-zA-Z]st matches t1st, t-st, and t,st but not test or tYst. |
| string* | Matches zero or more occurrences of the pattern specified by string. For example, te*st will match tst, test, and teeeeeest. |
| string+ | Matches one or more occurrences of the pattern specified by string. For example, t(es)+t matches test, tesest, but not tt. |
| string? | Matches zero or more occurrences of the pattern specified by string. For example, te?st matches either tst or test. |
| string{m,n} | Matches between m and n occurrence(s) of the pattern specified by string. For example, a{2} matches aa, b{1,4} matches b, bb, bbb, and bbbb. |
| string1 | string2 | Matches the pattern specified by either string1 or string2. For example, s | o matches both characters s and o. |
Since only function names are being considered, the regular expressions are automatically bracketed with the ^ and $ characters. For example, -qipa=noinline=^foo$ is equivalent to -qipa=noinline=foo. Therefore, -qipa=noinline=bar ensures that bar is never inlined but bar1, teebar, and barrel may be inlined.
Examples
The following example shows how you might compile a set of files with interprocedural analysis:
xlf95 -O -qipa f.f xlf95 -c -O3 *.f -qipa=noobject xlf95 -o product *.o -qipa -O
The following example shows how you might link these same files with interprocedural analysis, using regular expressions to improve performance. This example assumes that function user_abort exits the program, and that routines user_trace1, user_trace2, and user_trace3 are rarely called.
xlf95 -o product *.o -qipa=exit=user_abort:lowfreq=user_trace[123] -O
Related Information
See the -O Option and -p Option.
Syntax
-qkeepparm
Background Information
A procedure usually stores its incoming parameters on the stack at the entry point. When you compile code with -O, however, the optimizer may remove the stores into the stack if it sees opportunities to do so.
Specifying the -qkeepparm compiler option ensures that the parameters are stored on the stack even when optimizing. This may negatively impact execution performance. This option then provides access to the values of incoming parameters to tools, such as debuggers, simply by preserving those values on the stack.
Syntax
-qlanglvl={suboption}
LANGLVL({suboption})
Determines which language standard (or superset, or subset of a standard) to consult for nonconformance. It identifies nonconforming source code and also options that allow such nonconformances.
Rules
The compiler issues a message with severity code L if it detects syntax that is not allowed by the language level that you specified.
Arguments
Defaults
The default is -qlanglvl=extended.
Restrictions
The -qflag option can override this option.
Examples
The following example contains source code that conforms to a mixture of Fortran standards:
!----------------------------------------------------------
! in free source form
program tt
integer :: a(100,100), b(100), i
real :: x, y
...
goto (10, 20, 30), i
10 continue
pause 'waiting for input'
20 continue
y= gamma(x)
30 continue
b = maxloc(a, dim=1, mask=a .lt 0)
end program
!----------------------------------------------------------
The following chart shows examples of how some -qlanglvl
suboptions affect this sample program:
| -qlanglvl Suboption Specified | Result | Reason |
|---|---|---|
| 95pure |
Flags PAUSE statement
|
Deleted feature in Fortran 95 Obsolescent feature in Fortran 95 Extension to Fortran 95 |
| 95std |
Flags PAUSE statement
|
Deleted feature in Fortran 95 Extension to Fortran 95 |
| extended | No errors flagged |
|
Related Information
See -qflag Option, -qhalt Option, and -qsaa Option.
The langlvl run-time option, which is described in Setting Run-Time Options, helps to locate run-time extensions that cannot be checked for at compile time.
Related Information
See -qipa Option.
Related Information
See -qipa Option.
Syntax
-qlist | -qnolist LIST | NOLIST
Specifies whether to produce the object section of the listing.
You can use the object listing to help understand the performance characteristics of the generated code and to diagnose execution problems.
If you specify the -qipa and -qlist options together, IPA generates an a.lst file that overwrites any existing a.lst file. If you have a source file named a.f, the IPA listing will overwrite the regular compiler listing a.lst. To avoid this, use the list=filename suboption of -qipa to generate an alternative listing.
Related Information
See Options That Control Listings and Messages and Object Section.
Syntax
-qlistopt | -qnolistopt LISTOPT | NOLISTOPT
Determines whether to show the setting of every compiler option in the listing file or only selected options. These selected options include those specified on the command line or directives plus some that are always put in the listing.
You can use the option listing during debugging to check whether a problem occurs under a particular combination of compiler options or during performance testing to record the optimization options in effect for a particular compilation.
Rules
Options that are always displayed in the listing are:
Related Information
See Options That Control Listings and Messages and Options Section.
Syntax
-qlog4 | -qnolog4 LOG4 | NOLOG4
Specifies whether the result of a logical operation with logical operands is a LOGICAL(4) or is a LOGICAL with the maximum length of the operands.
You can use this option to port code that was originally written for the IBM VS FORTRAN compiler.
Arguments
-qlog4 makes the result always a LOGICAL(4), while -qnolog4 makes it depend on the lengths of the operands.
Restrictions
If you use -qintsize to change the default size of logicals, -qlog4 is ignored.
Syntax
-qmaxmem=Kbytes MAXMEM(Kbytes)
Limits the amount of memory that the compiler allocates while performing specific, memory-intensive optimizations to the specified number of kilobytes. A value of -1 allows optimization to take as much memory as it needs without checking for limits.
Defaults
At the -O2 optimization level, the default -qmaxmem setting is 2048 KB. At the -O3 optimization level, the default setting is unlimited (-1).
Rules
If the specified amount of memory is insufficient for the compiler to compute a particular optimization, the compiler issues a message and reduces the degree of optimization.
This option has no effect except in combination with the -O option.
When compiling with -O2, you only need to increase the limit if a compile-time message instructs you to do so. When compiling with -O3, you might need to establish a limit if compilation stops because the machine runs out of storage; start with a value of 2048 or higher, and decrease it if the compilation continues to require too much storage.
Notes:
Restrictions
Depending on the source file being compiled, the size of subprograms in the source code, the machine configuration, and the workload on the system, setting the limit too high might fill up the paging space. In particular, a value of -1 can fill up the storage of even a well-equipped machine.
Related Information
See -O Option and Optimizing XL Fortran Programs.
Syntax
-qmbcs | -qnombcs MBCS | NOMBCS
Indicates to the compiler whether character literal constants, Hollerith constants, H edit descriptors, and character string edit descriptors can contain Multibyte Character Set (MBCS) or Unicode characters.
This option is intended for applications that must deal with data in a multibyte language, such as Japanese.
To process the multibyte data correctly at run time, set the locale (through the LANG environment variable or a call to the libc setlocale routine) to the same value as during compilation.
Rules
Each byte of a multibyte character is counted as a column.
Restrictions
To read or write Unicode data, set the locale value to UNIVERSAL at run time. If you do not set the locale, you might not be able to interchange data with Unicode-enabled applications.
Syntax
-qmixed | -qnomixed MIXED | NOMIXED
This is the long form of the -U Option.
Syntax
-qmoddir=directory
Specifies the location for any module (.mod) files that the compiler writes.
Defaults
If you do not specify -qmoddir, the .mod files are placed in the current directory.
Related Information
Modules are a Fortran 90/95 feature and are explained in the XL Fortran Advanced Edition for Mac OS X Language Reference.
To read the .mod files from this directory when compiling files that reference the modules, use the -I Option.
Syntax
-qnoprint
Prevents the compiler from creating the listing file, regardless of the settings of other listing options.
Specifying -qnoprint on the command line enables you to put other listing options in a configuration file or on @PROCESS directives and still prevent the listing file from being created.
Rules
A listing file is usually created when you specify any of the following options: -qattr, -qlist, -qlistopt, -qphsinfo, -qsource, -qreport, or -qxref. -qnoprint prevents the listing file from being created by changing its name to /dev/null, a device that discards any data that is written to it.
Related Information
See Options That Control Listings and Messages.
Syntax
-qnullterm | -qnonullterm NULLTERM | NONULLTERM
Appends a null character to each character constant expression that is passed as a dummy argument, to make it more convenient to pass strings to C functions.
This option allows you to pass strings to C functions without having to add a null character to each string argument.
Background Information
This option affects arguments that are composed of any of the following objects: basic character constants; concatenations of multiple character constants; named constants of type character; Hollerith constants; binary, octal, or hexadecimal typeless constants when an interface block is available; or any character expression composed entirely of these objects. The result values from the CHAR and ACHAR intrinsic functions also have a null character added to them if the arguments to the intrinsic function are initialization expressions.
Rules
This option does not change the length of the dummy argument, which is defined by the additional length argument that is passed as part of the XL Fortran calling convention.
Restrictions
This option affects those arguments that are passed with or without the %REF built-in function, but it does not affect those that are passed by value. This option does not affect character expressions in input and output statements.
Examples
Here are two calls to the same C function, one with and one without the option:
@PROCESS NONULLTERM
SUBROUTINE CALL_C_1
CHARACTER*9, PARAMETER :: HOME = "/home/luc"
! Call the libc routine mkdir() to create some directories.
CALL mkdir ("/home/luc/testfiles\0", %val(448))
! Call the libc routine unlink() to remove a file in the home directory.
CALL unlink (HOME // "/.hushlogin" // CHAR(0))
END SUBROUTINE
@PROCESS NULLTERM
SUBROUTINE CALL_C_2
CHARACTER*9, PARAMETER :: HOME = "/home/luc"
! With the option, there is no need to worry about the trailing null
! for each string argument.
CALL mkdir ("/home/luc/testfiles", %val(448))
CALL unlink (HOME // "/.hushlogin")
END SUBROUTINE
!
Related Information
See Passing Character Types Between Languages.
Syntax
-qOBJect | -qNOOBJect OBJect | NOOBJect
Specifies whether to produce an object file or to stop immediately after checking the syntax of the source files.
When debugging a large program that takes a long time to compile, you might want to use the -qnoobject option. It allows you to quickly check the syntax of a program without incurring the overhead of code generation. The .lst file is still produced, so you can get diagnostic information to begin debugging.
After fixing any program errors, you can change back to the default (-qobject) to test whether the program works correctly. If it does not work correctly, compile with the -g option for interactive debugging.
Restrictions
The -qhalt option can override the -qobject option, and -qnoobject can override -qhalt.
Related Information
See Options That Control Listings and Messages and Object Section.
The Compiler Phases gives some technical information about the compiler phases.
Syntax
-qonetrip | -qnoonetrip ONETRIP | NOONETRIP
This is the long form of the -1 Option.
Syntax
-qOPTimize[=level] | -qNOOPTimize OPTimize[(level)] | NOOPTimize
This is the long form of the -O Option.
Syntax
-qpdf{1|2}
Tunes optimizations through profile-directed feedback (PDF), where results from sample program execution are used to improve optimization near conditional branches and in frequently executed code sections.
To use PDF, follow these steps:
In a large application, concentrate on those areas of the code that can benefit most from optimization. You do not need to compile all of the application's code with the -qpdf1 option.
For best performance, use the -O3, -O4, or -O5 option with all compilations when you use PDF (as in the example above). If your application contains C or C++ code compiled with IBM C/C+ compilers, you can achieve additional PDF optimization by specifying the -qpdf1 and -qpdf2 options available on those compilers. Combining -qpdf1/-qpdf2 and -qipa or -O5 options (that is, link with IPA) on all Fortran and C/C++ code will lead to maximum PDF information being available for optimization.
Rules
The profile is placed in the current working directory or in the directory that the PDFDIR environment variable names, if that variable is set.
To avoid wasting compilation and execution time, make sure that the PDFDIR environment variable is set to an absolute path. Otherwise, you might run the application from the wrong directory, and it will not be able to locate the profile data files. When that happens, the program may not be optimized correctly or may be stopped by a segmentation fault. A segmentation fault might also happen if you change the value of the PDFDIR variable and execute the application before finishing the PDF process.
Background Information
Because this option requires compiling the entire application twice, it is intended to be used after other debugging and tuning is finished, as one of the last steps before putting the application into production.
Restrictions
Examples
Here is a simple example:
# Set the PDFDIR variable. export PDFDIR=$HOME/project_dir # Compile all files with -qpdf1. xlf95 -qpdf1 -O3 file1.f file2.f file3.f # Run with one set of input data. a.out <sample.data # Recompile all files with -qpdf2. xlf95 -qpdf2 -O3 file1.f file2.f file3.f # The program should now run faster than without PDF if # the sample data is typical.
Here is a more elaborate example:
# Set the PDFDIR variable. export PDFDIR=$HOME/project_dir # Compile most of the files with -qpdf1. xlf95 -qpdf1 -O3 -c file1.f file2.f file3.f # This file is not so important to optimize. xlf95 -c file4.f # Non-PDF object files such as file4.o can be linked in. xlf95 -qpdf1 file1.o file2.o file3.o file4.o # Run several times with different input data. a.out <polar_orbit.data a.out <elliptical_orbit.data a.out <geosynchronous_orbit.data # Do not need to recompile the source of non-PDF object files (file4.f). xlf95 -qpdf2 -O3 file1.f file2.f file3.f # Link all the object files into the final application. xlf95 file1.o file2.o file3.o file4.o
Related Information
See XL Fortran Input Files, XL Fortran Output Files, and Optimizing Conditional Branching.
The following commands, in the directory /opt/ibmcmp/xlf/8.1/bin, are available for managing the PDFDIR directory:
| resetpdf [pathname] | Sets to zeros all profiling information (but does not remove the data
files) from the pathname directory, or from the PDFDIR
directory if pathname is not specified, or from the current directory
if PDFDIR is not set.
When you make changes to the application and recompile some files, the profiling information for those files is automatically reset because the changes may alter the program flow. Run resetpdf to reset the profiling information for the entire application after you make significant changes that may change execution counts for parts of the program that were not recompiled. |
| cleanpdf [pathname] | Removes all profiling information from the pathname directory,
or from the PDFDIR directory if pathname is not specified,
or from the current directory if PDFDIR is not set.
Removing the profiling information reduces the run-time overhead if you change the program and then go through the PDF process again. Run this program after compiling with -qpdf2 or after finishing with the PDF process for a particular application. If you continue using PDF with an application after running cleanpdf, you must recompile all the files with -qpdf1. |
Syntax
-qphsinfo | -qnophsinfo PHSINFO | NOPHSINFO
The -qphsinfo compiler option displays timing information on the terminal for each compiler phase.
Related Information
Syntax
qpic|qnopic
The -qpic compiler option generates Position Independent Code (PIC) that can be used in shared libraries.
Syntax
-qport[=suboptions]| -qnoport PORT[(suboptions)]| NOPORT
The -qport compiler option increases flexibility when porting programs to XL Fortran, providing a number of options to accommodate other Fortran language extensions. A particular suboption will always function independently of other -qport and compiler options.
Arguments
Using this option may cause some intrinsic procedures to become mismatched in kinds. Specify -qxlf77=intarg to convert the kind to that of the longest argument.
Related Information
See the section on the INT and MOD intrinsic functions in the XL Fortran Advanced Edition for Mac OS X Language Reference for further information.
Syntax
-qposition={appendold | appendunknown} ...
POSITION({APPENDOLD | APPENDUNKNOWN} ...)
Positions the file pointer at the end of the file when data is written after an OPEN statement with no POSITION= specifier and the corresponding STATUS= value (OLD or UNKNOWN) is specified.
Rules
The position becomes APPEND when the first I/O operation moves the file pointer if that I/O operation is a WRITE or PRINT statement. If it is a BACKSPACE, ENDFILE, READ, or REWIND statement instead, the position is REWIND.
Examples
In the following example, OPEN statements that do not specify a POSITION= specifier, but specify STATUS='old' will open the file as if POSITION='append' was specified.
xlf95 -qposition=appendold opens_old_files.f
In the following example, OPEN statements that do not specify a POSITION= specifier, but specify STATUS='unknown' will open the file as if POSITION='append' was specified.
xlf95 -qposition=appendunknown opens_unknown_files.f
In the following example, OPEN statements that do not specify a POSITION= specifier, but specify either STATUS='old' or STATUS='unknown' will open the file as if POSITION='append' was specified.
xlf95 -qposition=appendold:appendunknown opens_many_files.f
Related Information
See File Positioning and the section on the OPEN statement in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qprefetch | -qnoprefetch
Instructs the compiler to insert the prefetch instructions automatically where there are opportunities to improve code performance.
Related Information
For more information on prefetch directives, see PREFETCH directives in the XL Fortran Advanced Edition for Mac OS X Language Reference. To selectively control prefetch directives using trigger constants, see the -qdirective option.
Syntax
-qqcount | -qnoqcount QCOUNT | NOQCOUNT
Accepts the Q character-count edit descriptor (Q) as well as the extended-precision Q edit descriptor (Qw.d). With -qnoqcount, all Q edit descriptors are interpreted as the extended-precision Q edit descriptor.
Rules
The compiler interprets a Q edit descriptor as one or the other depending on its syntax and issues a warning if it cannot determine which one is specified.
Related Information
See Q (Character Count) Editing in the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qrealsize=bytes REALSIZE(bytes)
Sets the default size of REAL, DOUBLE PRECISION, COMPLEX, and DOUBLE COMPLEX values.
This option is intended for maintaining compatibility with code that is written for other systems. You may find it useful as an alternative to -qautodbl in some situations.
Rules
The option affects the sizes 2 of constants, variables, derived type components, and functions (which include intrinsic functions) for which no kind type parameter is specified. Objects that are declared with a kind type parameter or length, such as REAL(4) or COMPLEX*16, are not affected.
Arguments
The allowed values for bytes are:
Results
This option determines the sizes of affected objects as follows:
Data Object REALSIZE(4) in Effect REALSIZE(8) in Effect ------------------------------------------------------------------- 1.2 REAL(4) REAL(8) 1.2e0 REAL(4) REAL(8) 1.2d0 REAL(8) REAL(16) 1.2q0 REAL(16) REAL(16) REAL REAL(4) REAL(8) DOUBLE PRECISION REAL(8) REAL(16) COMPLEX COMPLEX(4) COMPLEX(8) DOUBLE COMPLEX COMPLEX(8) COMPLEX(16)
Similar rules apply to intrinsic functions:
This option is intended to allow you to port programs unchanged from systems that have different default sizes for data. For example, you might need -qrealsize=8 for programs that are written for a CRAY computer. The default value of 4 for this option is suitable for programs that are written specifically for many 32-bit computers.
Setting -qrealsize to 8 overrides the setting of the -qdpc option.
Examples
This example shows how changing the -qrealsize setting transforms some typical entities:
@PROCESS REALSIZE(8)
REAL R ! treated as a real(8)
REAL(8) R8 ! treated as a real(8)
DOUBLE PRECISION DP ! treated as a real(16)
DOUBLE COMPLEX DC ! treated as a complex(16)
COMPLEX(4) C ! treated as a complex(4)
PRINT *,DSIN(DP) ! treated as qsin(real(16))
! Note: we cannot get dsin(r8) because dsin is being treated as qsin.
END
Specifying -qrealsize=8 affects intrinsic functions, such as DABS, as follows:
INTRINSIC DABS ! Argument and return type become REAL(16).
DOUBLE PRECISION DABS ! OK, because DOUBLE PRECISION = REAL(16)
! with -qrealsize=8 in effect.
REAL(16) DABS ! OK, the declaration agrees with the option setting.
REAL(8) DABS ! The declaration does not agree with the option
! setting and is ignored.
Related Information
-qintsize Option is a similar option that affects integer and logical objects. -qautodbl Option is related to -qrealsize, although you cannot combine the options. When the -qautodbl option turns on automatic doubling, padding, or both, the -qrealsize option has no effect.
Type Parameters and Specifiers in the XL Fortran Advanced Edition for Mac OS X Language Reference discusses kind type parameters.
Syntax
-qrecur | -qnorecur RECUR | NORECUR
Not recommended. Specifies whether external subprograms may be called recursively. For new programs, use the RECURSIVE keyword, which provides a standard-conforming way of using recursive procedures. If you specify the -qrecur option, the compiler must assume that any procedure could be recursive. Code generation for recursive procedures may be less efficient. Using the RECURSIVE keyword allows you to specify exactly which procedures are recursive.
Examples
! The following RECUR recursive function:
@process recur
function factorial (n)
integer factorial
if (n .eq. 0) then
factorial = 1
else
factorial = n * factorial (n-1)
end if
end function factorial
! can be rewritten to use F90/F95 RECURSIVE/RESULT features:
recursive function factorial (n) result (res)
integer res
if (n .eq. 0) then
res = 1
else
res = n * factorial (n-1)
end if
end function factorial
Restrictions
If you use the xlf, xlf_r, f77, or fort77 command to compile programs that contain recursive calls, specify -qnosave to make the default storage class automatic.
Syntax
-qreport[={hotlist}...]
-qnoreport
REPORT[({HOTLIST}...)] NOREPORT
Determines whether to produce transformation reports showing how loops are optimized.
You can see how the program deals with data and the automatic parallelization of loops. Comments within the listing tell you how the transformed program corresponds to the original source code and include information as to why certain loops were not parallelized.
You can use the hotlist suboption to generate a report showing how loops are transformed.
Arguments
Background Information
The transformation listing is part of the compiler listing file.
Restrictions
Loop transformation is done on the link step at a -O5 (or -qipa=level=2) optimization level. The -qreport option will generate the report in the listing file on the link step.
You must specify the -qhot option to generate a loop transformation listing.
The code that the listing shows is not intended to be compilable. Do not include any of this code in your own programs or explicitly call any of the internal routines whose names appear in the listing.
Examples
To produce a listing file that you can use to tune the performance of loops:
xlf95 -O3 -qhot -qreport=hotlist needs_tuning.f
Related Information
See Options That Control Listings and Messages and Transformation Report Section.
Syntax
-qsaa | -qnosaa SAA | NOSAA
Checks for conformance to the SAA FORTRAN language definition. It identifies nonconforming source code and also options that allow such nonconformances.
Rules
These warnings have a prefix of (L), indicating a problem with the language level.
Restrictions
The -qflag option can override this option.
Related Information
Use the -qlanglvl Option to check your code for conformance to international standards.
Syntax
-qsave[={all|defaultinit}] | -qnosave
SAVE[({all|defaultinit})] NOSAVE
This specifies the default storage class for local variables.
If -qsave=all is specified, the default storage class is STATIC; if -qnosave is specified, the default storage class is AUTOMATIC; if -qsave=defaultinit is specified, the default storage class is STATIC for variables of derived type that have default initialization specified, and AUTOMATIC otherwise. The default suboption for the -qsave option is all. The two suboptions are mutually exclusive.
The default for this option depends on the invocation used. For example, you may need to specify -qsave to duplicate the behavior of FORTRAN 77 programs. The xlf, xlf_r, f77, and fort77 commands have -qsave listed as a default option in /etc/opt/ibmcmp/xlf/8.1/xlf.cfg to preserve the previous behavior.
The following example illustrates the impact of the -qsave option on derived data type:
PROGRAM P
CALL SUB
CALL SUB
END PROGRAM P
SUBROUTINE SUB
LOGICAL, SAVE :: FIRST_TIME = .TRUE.
STRUCTURE /S/
INTEGER I/17/
END STRUCTURE
RECORD /S/ LOCAL_STRUCT
INTEGER LOCAL_VAR
IF (FIRST_TIME) THEN
LOCAL_STRUCT.I = 13
LOCAL_VAR = 19
FIRST_TIME = .FALSE.
ELSE
! Prints " 13" if compiled with -qsave or -qsave=all
! Prints " 13" if compiled with -qsave=defaultinit
! Prints " 17" if compiled with -qnosave
PRINT *, LOCAL_STRUCT
! Prints " 19" if compiled with -qsave or -qsave=all
! Value of LOCAL_VAR is undefined otherwise
PRINT *, LOCAL_VAR
END IF
END SUBROUTINE SUB
Related Information
The -qnosave option is usually necessary for multi-threaded applications and subprograms that are compiled with the -qrecur Option.
See Storage Classes for Variables in the XL Fortran Advanced Edition for Mac OS X Language Reference for information on how this option affects the storage class of variables.
Syntax
-qsigtrap[=trap_handler]
When you are compiling a file that contains a main program, this option sets up the specified trap handler to catch SIGTRAP and SIGFPE exceptions. This option enables you to install a handler for SIGTRAP or SIGFPE signals without calling the SIGNAL subprogram in the program.
Arguments
To enable the xl__trce trap handler, specify -qsigtrap without a handler name. To use a different trap handler, specify its name with the -qsigtrap option.
If you specify a different handler, ensure that the object module that contains it is linked with the program.
Related Information
The possible causes of exceptions are described in XL Fortran Run-Time Exceptions. Detecting and Trapping Floating-Point Exceptions describes a number of methods for dealing with exceptions that result from floating-point computations. Installing an Exception Handler lists the exception handlers that XL Fortran supplies.
Syntax
-qsmallstack | -qnosmallstack
Specifies that the compiler will minimize stack usage where possible.
Syntax
-qsource | -qnosource SOURCE | NOSOURCE
Determines whether to produce the source section of the listing.
This option displays on the terminal each source line where the compiler detects a problem, which can be very useful in diagnosing program errors in the Fortran source files.
You can selectively print parts of the source code by using SOURCE and NOSOURCE in @PROCESS directives in the source files around those portions of the program you want to print. This is the only situation where the @PROCESS directive does not have to be before the first statement of a compilation unit.
Examples
In the following example, the point at which the incorrect call is made is identified more clearly when the program is compiled with the -qsource option:
$ cat argument_mismatch.f
subroutine mult(x,y)
integer x,y
print *,x*y
end
program wrong_args
interface
subroutine mult(a,b) ! Specify the interface for this
integer a,b ! subroutine so that calls to it
end subroutine mult ! can be checked.
end interface
real i,j
i = 5.0
j = 6.0
call mult(i,j)
end
$ xlf95 argument_mismatch.f
** mult === End of Compilation 1 ===
"argument_mismatch.f", line 16.12: 1513-061 (S) Actual argument attributes
do not match those specified by an accessible explicit interface.
** wrong_args === End of Compilation 2 ===
1501-511 Compilation failed for file argument_mismatch.f.
$ xlf95 -qsource argument_mismatch.f
** mult === End of Compilation 1 ===
16 | call mult(i,j)
............a...
a - 1513-061 (S) Actual argument attributes do not match those specified by
an accessible explicit interface.
** wrong_args === End of Compilation 2 ===
1501-511 Compilation failed for file argument_mismatch.f.
Related Information
See Options That Control Listings and Messages and Source Section.
Syntax
-qspillsize=bytes SPILLSIZE(bytes)
-qspillsize is the long form of -NS. See -N Option.
Syntax
-qstrict | -qnostrict STRICT | NOSTRICT
Ensures that optimizations done by default with the -O3, -O4, -O5, -qhot, and -qipa options, and optionally with the -O2 option, do not alter the semantics of a program.
Defaults
For -O3, -O4, -O5, -qhot, and -qipa, the default is -qnostrict. For -O2, the default is -qstrict. This option is ignored for -qnoopt. With -qnostrict, optimizations may rearrange code so that results or exceptions are different from those of unoptimized programs.
This option is intended for situations where the changes in program execution in optimized programs produce different results from unoptimized programs. Such situations are likely rare because they involve relatively little-used rules for IEEE floating-point arithmetic.
Rules
With -qnostrict in effect, the following optimizations are turned on, unless -qstrict is also specified:
Related Information
See -O Option, -qhot Option, and -qfloat Option.
Syntax
-qstrictieeemod | -qnostrictieeemod STRICTIEEEMOD | NOSTRICTIEEEMOD
Specifies whether the compiler will adhere to the draft Fortran 2000 IEEE arithmetic rules for the ieee_arithmetic and ieee_exceptions intrinsic modules. When you specify -qstrictieeemod, the compiler adheres to the following rules:
Since the above rules can impact performance, specifying -qnostrictieeemod will relax the rules on saving and restoring floating-point status. This prevents any associated impact on performance.
Syntax
-qSTRICT_INDUCtion | -qNOSTRICT_INDUCtion
Prevents the compiler from performing induction (loop counter) variable optimizations. These optimizations may be unsafe (may alter the semantics of your program) when there are integer overflow operations involving the induction variables.
You should avoid specifying -qstrict_induction unless absolutely necessary, as it may cause performance degradation.
Examples
Consider the following two examples:
Example 1
integer(1) :: i, j ! Variable i can hold a
j = 0 ! maximum value of 127.
do i = 1, 200 ! Integer overflow occurs when 128th
j = j + 1 ! iteration of loop is attempted.
enddo
Example 2
integer(1) :: i
i = 1_1 ! Variable i can hold a maximum
! value of 127.
100 continue
if (i == -127) goto 200 ! Go to label 200 once decimal overflow
i = i + 1_1 ! occurs and i == -127.
goto 100
200 continue
print *, i
end
If you compile these examples with the -qstrict_induction option, the compiler does not perform induction variable optimizations, but the performance of the code may be affected. If you compile the examples with the -qnostrict_induction option, the compiler may perform optimizations that may alter the semantics of the programs.
Syntax
-qsuffix=option=suffix
Specifies the source-file suffix on the command line instead of in the xlf.cfg file. This option saves time for the user by permitting files to be used as named with minimal makefile modifications and removes the risk of problems associated with modifying the xlf.cfg file. Only one setting is supported at any one time for any particular file type.
Arguments
Rules
Examples
For instance,
xlf a.f90 -qsuffix=f=f90:cpp=F90
will cause these effects:
Syntax
-qsuppress[=nnnn-mmm[:nnnn-mmm ...] | cmpmsg] -qnosuppress
Arguments
This sub-option has no effect on any error messages that are emitted.
Background Information
In some situations, users may receive an overwhelming number of compiler messages. In many cases, these compiler messages contain important information. However, some messages contain information that is either redundant or can be safely ignored. When multiple error or warning messages appear during compilation, it can be very difficult to distinguish which messages should be noted. By using -qsuppress, you can eliminate messages that do not interest you.
Restrictions
Examples
@process nullterm
i = 1; j = 2;
call printf("i=%d\n",%val(i));
call printf("i=%d, j=%d\n",%val(i),%val(j));
end
Compiling this sample program would normally result in the following output:
"t.f", line 4.36: 1513-029 (W) The number of arguments to "printf" differ from the number of arguments in a previous reference. You should use the OPTIONAL attribute and an explicit interface to define a procedure with optional arguments. ** _main === End of Compilation 1 === 1501-510 Compilation successful for file t.f.
When the program is compiled with -qsuppress=1513-029, the output is:
** _main === End of Compilation 1 === 1501-510 Compilation successful for file t.f.
Related Information
For another type of message suppression, see -qflag Option.
Syntax
-qthreaded
Used by the compiler to determine when it must generate thread-safe code.
The -qthreaded option does not imply the -qnosave option. The -qnosave option specifies a default storage class of automatic for user local variables. In general, both of these options need to be used to generate thread-safe code.
Defaults
-qthreaded is the default for the xlf90_r, xlf95_r, and xlf_r commands.
Specifying the -qthreaded option implies -qdirective=ibmt, and by default, the trigger_constant IBMT is recognized.
Syntax
-qtune=implementation
Tunes instruction selection, scheduling, and other implementation-dependent performance enhancements for a specific implementation of a hardware architecture.
Arguments
If you want your program to run on more than one architecture, but to be tuned to a particular architecture, you can use a combination of the -qarch and -qtune options. These options are primarily of benefit for floating-point intensive programs.
By arranging (scheduling) the generated machine instructions to take maximum advantage of hardware features such as cache size and pipelining, -qtune can improve performance. It only has an effect when used in combination with options that enable optimization.
Although changing the -qtune setting may affect the performance of the resulting executable, it has no effect on whether the executable can be executed correctly on a particular hardware platform.
Related Information
See -qarch Option, -qcache Option, and Compiling for PowerPC Systems.
Syntax
-qundef | -qnoundef UNDEF | NOUNDEF
-qundef is the long form of the -u Option.
Syntax
-qunroll[=auto | yes] | -qnounroll
Specifies whether unrolling a DO loop is allowed in a program. Unrolling is allowed on outer and inner DO loops.
Arguments
If you decide to unroll a loop, specifying one of the above suboptions does not automatically guarantee that the compiler will perform the operation. Based on the performance benefit, the compiler will determine whether unrolling will be beneficial to the program. Experienced compiler users should be able to determine the benefit in advance.
Rules
The -qnounroll option prohibits unrolling unless you specify the STREAM_UNROLL, UNROLL, or UNROLL_AND_FUSE directive for a particular loop. These directives always override the command line options.
Examples
In the following example, the UNROLL(2) directive is used to tell the compiler that the body of the loop can be replicated so that the work of two iterations is performed in a single iteration. Instead of performing 1000 iterations, if the compiler unrolls the loop, it will only perform 500 iterations.
!IBM* UNROLL(2)
DO I = 1, 1000
A(I) = I
END DO
If the compiler chooses to unroll the previous loop, the compiler translates the loop so that it is essentially equivalent to the following:
DO I = 1, 1000, 2
A(I) = I
A(I+1) = I + 1
END DO
Related Information
See the appropriate directive on unrolling loops in the XL Fortran Advanced Edition for Mac OS X Language Reference.
See Optimizing Loops and Array Language.
Syntax
-qunwind |-qnounwind UNWIND | NOUNWIND
Specifies that the compiler will preserve the default behavior for saves and restores to volatile registers during a procedure call. If you specify -qnounwind, the compiler rearranges subprograms to minimize saves and restores to volatile registers.
While code semantics are preserved, applications such as exception handlers that rely on the default behavior for saves and restores can produce undefined results. When using -qnounwind in conjunction with the -g compiler option, debug information regarding exception handling when unwinding the program's stack can be inaccurate.
Syntax
-qxflag=oldtab XFLAG(OLDTAB)
Interprets a tab in columns 1 to 5 as a single character (for fixed source form programs).
Defaults
By default, the compiler allows 66 significant characters on a source line after column 6. A tab in columns 1 through 5 is interpreted as the appropriate number of blanks to move the column counter past column 6. This default is convenient for those who follow the earlier Fortran practice of including line numbers or other data in columns 73 through 80.
Rules
If you specify the option -qxflag=oldtab, the source statement still starts immediately after the tab, but the tab character is treated as a single character for counting columns. This setting allows up to 71 characters of input, depending on where the tab character occurs.
Syntax
-qxlf77=settings XLF77(settings)
Provides compatibility with XL Fortran for AIX Versions 1 and 2 aspects of language semantics and I/O data format that have changed. Most of these changes are required by the Fortran 90 standard.
Defaults
By default, the compiler uses settings that apply to Fortran 95, Fortran 90, and the most recent compiler version in all cases; the default suboptions are blankpad, nogedit77, nointarg, nointxor, leadzero, nooldboz, nopersistent, and nosofteof. However, these defaults are only used by the xlf95, xlf95_r, xlf90, and xlf90_r commands, which you should use to compile new programs.
If you only want to compile and run old programs unchanged, you can continue to use the appropriate invocation command and not concern yourself with this option. You should only use this option if you are using existing source or data files with Fortran 90 or Fortran 95 and the xlf90, xlf90_r, xlf95, or xlf95_r command and find some incompatibility because of behavior or data format that has changed. Eventually, you should be able to recreate the data files or modify the source files to remove the dependency on the old behavior.
Arguments
To get various aspects of XL Fortran Version 2 behavior, select the nondefault choice for one or more of the following suboptions. The descriptions explain what happens when you specify the nondefault choices.
Otherwise, the .XOR. operator is only recognized as a defined operator. The intrinsic operation is not accessible, and the precedence depends on whether the operator is used in a unary or binary context.
Syntax
-qxlf90={settings}
XLF90({settings})
Provides compatibility with XL Fortran for AIX Version 5 and the Fortran 90 standard for certain aspects of the Fortran language.
Defaults
The default suboptions for -qxlf90 depend on the invocation command that you specify. For the xlf95 or xlf95_r command, the default suboptions are signedzero and autodealloc. For all other invocation commands, the defaults are nosignedzero and noautodealloc.
Arguments
This suboption also determines whether a minus sign is printed in the following cases:
Examples
Consider the following program:
PROGRAM TESTSIGN REAL X, Y, Z X=1.0 Y=-0.0 Z=SIGN(X,Y) PRINT *,Z END PROGRAM TESTSIGN
The output from this example depends on the invocation command and the
-qxlf90 suboption that you specify. For example:
| Invocation Command/xlf90 Suboption | Output |
|---|---|
| xlf95 | -1.0 |
| xlf95 -qxlf90=signedzero | -1.0 |
| xlf95 -qxlf90=nosignedzero | 1.0 |
| xlf90 | 1.0 |
| xlf | 1.0 |
Related Information
See the section on SIGN in the Intrinsic Procedures section and the Arrays Concepts section of the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qxlines | -qnoxlines XLINES | NOXLINES
Specifies whether fixed source form lines with a X in column 1 are compiled or treated as comments. This option is similar to the recognition of the character 'd' in column 1 as a conditional compilation (debug) character. The -D option recognizes the character 'x' in column 1 as a conditional compilation character when this compiler option is enabled. The 'x' in column 1 is interpreted as a blank, and the line is handled as source code.
Defaults
This option is set to -qnoxlines by default, and lines with the character 'x' in column 1 in fixed source form are treated as comment lines. While the -qxlines option is independent of -D, all rules for debug lines that apply to using 'd' as the conditional compilation character also apply to the conditional compilation character 'x'. The -qxlines compiler option is only applicable to fixed source form.
The conditional compilation characters 'x' and 'd' may be mixed both within a fixed source form program and within a continued source line. If a conditional compilation line is continued onto the next line, all the continuation lines must have 'x' or 'd' in column 1. If the initial line of a continued compilation statement is not a debugging line that begins with either 'x' or 'd' in column 1, subsequent continuation lines may be designated as debug lines as long as the statement is syntactically correct.
Examples
An example of a base case of -qxlines:
C2345678901234567890
program p
i=3 ; j=4 ; k=5
X print *,i,j
X + ,k
end program p
<output>: 3 4 5 (if -qxlines is on)
no output (if -qxlines is off)
In this example, conditional compilation characters 'x' and 'd' are mixed, with 'x' on the initial line:
C2345678901234567890
program p
i=3 ; j=4 ; k=5
X print *,i,
D + j,
X + k
end program p
<output>: 3 4 5 (if both -qxlines and -qdlines are on)
3 5 (if only -qxlines is turned on)
Here, conditional compilation characters 'x' and 'd' are mixed, with 'd' on the initial line:
C2345678901234567890
program p
i=3 ; j=4 ; k=5
D print *,i,
X + j,
D + k
end program p
<output>: 3 4 5 (if both -qxlines and -qdlines are on)
3 5 (if only -qdlines is turned on)
In this example, the initial line is not a debug line, but the continuation line is interpreted as such, since it has an 'x' in column 1:
C2345678901234567890
program p
i=3 ; j=4 ; k=5
print *,i
X + ,j
X + ,k
end program p
<output>: 3 4 5 (if -qxlines is on)
3 (if -qxlines is off)
Related Information
See -D Option and Conditional Compilation in the Language Elements section of the XL Fortran Advanced Edition for Mac OS X Language Reference.
Syntax
-qxref[=full] | -qnoxref XREF[(FULL)] | NOXREF
Determines whether to produce the cross-reference component of the attribute and cross-reference section of the listing.
If you specify only -qxref, only identifiers that are used are reported. If you specify -qxref=full, the listing contains information about all identifiers that appear in the program, whether they are used or not.
If -qxref is specified after -qxref=full, the full cross-reference listing is still produced.
You can use the cross-reference listing during debugging to locate problems such as using a variable before defining it or entering the wrong name for a variable.
Related Information
See Options That Control Listings and Messages and Attribute and Cross-Reference Section.
Syntax
-qzerosize | -qnozerosize ZEROSIZE | NOZEROSIZE
Improves performance of FORTRAN 77 and some Fortran 90 and Fortran 95 programs by preventing checking for zero-sized character strings and arrays.
For Fortran 90 and Fortran 95 programs that might process such objects, use -qzerosize. For FORTRAN 77 programs, where zero-sized objects are not allowed, or for Fortran 90 and Fortran 95 programs that do not use them, compiling with -qnozerosize can improve the performance of some array or character-string operations.
Defaults
The default setting depends on which command invokes the compiler: -qzerosize for the xlf90, xlf90_r, xlf95, andxlf95_r commands and -qnozerosize for the xlf, xlf_r, and f77/fort77 commands (for compatibility with FORTRAN 77).
Rules
Run-time checking performed by the -C option takes slightly longer when -qzerosize is in effect.
Syntax
-tcomponents
Applies the prefix specified by the -B option to the designated components. components can be one or more of F, c, h, I, a, b, l, or z with no separators, corresponding to the C preprocessor, the compiler, the array language optimizer, the interprocedural analysis (IPA) tool/loop optimizer, the assembler, the code generator, the linker, and the binder, respectively.
Rules
If -t is not specified, any -B prefix is applied to all components.
Component -t Standard Program Name
Mnemonic
C preprocessor F cpp
compiler front end c xlfentry
array language optimizer h xlfhot
IPA/loop optimizer I ipa
assembler a as
code generator b xlfcode
linker l ld
binder z bolt
Related Information
See -B Option (which includes an example).
Syntax
-U MIXED | NOMIXED
Makes the compiler sensitive to the case of letters in names.
You can use this option when writing mixed-language programs, because Fortran names are all lowercase by default, while names in C and other languages may be mixed-case.
Rules
If -U is specified, case is significant in names. For example, the names Abc and ABC refer to different objects.
The option changes the link names used to resolve calls between compilation units. It also affects the names of modules and thus the names of their .mod files.
Defaults
By default, the compiler interprets all names as if they were in lowercase. For example, Abc and ABC are both interpreted as abc and so refer to the same object.
Restrictions
The names of intrinsics must be all in lowercase when -U is in effect. Otherwise, the compiler may accept the names without errors, but the compiler considers them to be the names of external procedures, rather than intrinsics.
Related Information
This is the short form of -qmixed. See -qmixed Option.
Syntax
-u UNDEF | NOUNDEF
Specifies that no implicit typing of variable names is permitted. It has the same effect as using the IMPLICIT NONE statement in each scope that allows implicit statements.
Defaults
By default, implicit typing is allowed.
Related Information
See IMPLICIT in the XL Fortran Advanced Edition for Mac OS X Language Reference.
This is the short form of -qundef. See -qundef Option.
Syntax
-v
Generates information on the progress of the compilation.
Rules
As the compiler executes commands to perform different compilation steps, this option displays a simulation of the commands it calls and the system argument lists it passes.
For a particular compilation, examining the output that this option produces can help you determine:
Related Information
-# Option is similar to -v, but it does not actually execute any of the compilation steps.
Syntax
-V
This option is the same as -v except that you can cut and paste directly from the display to create a command.
Syntax
-Wcomponent,options
Passes the listed options to a component that is executed during compilation. component is F, c, I, a, z, or l, corresponding to the C preprocessor, the compiler, the interprocedural analysis (IPA) tool, the assembler, the binder, and the linker, respectively.
In the string following the -W option, use a comma as the separator, and do not include any spaces.
Background Information
The primary purpose of this option is to construct sequences of compiler options to pass to one of the optimizing preprocessors. It can also be used to fine-tune the link-edit step by passing parameters to the ld command.
Defaults
You do not need the -W option to pass most options to the linker: unrecognized command-line options, except -q options, are passed to it automatically.
If you need to include a character that is special to the shell in the option string, precede the character with a backslash.
Examples
See Passing Command-Line Options to the ld or as Commands.
Syntax
-w
A synonym for the -qflag Option. It sets -qflag=e:e, suppressing warning and informational messages and also messages generated by language-level checking.
Syntax
-y{n | m | p | z}
IEEE(Near | Minus | Plus | Zero)
Specifies the rounding mode for the compiler to use when evaluating constant floating-point expressions at compile time. It is equivalent to the -qieee option.
Arguments
Related Information
See -O Option and -qfloat Option.
-y is the short form of -qieee Option.