Detailed descriptions of the XL Fortran compiler options

The following alphabetical list of options provides all the information you should need to use each option effectively.

How to read the syntax information:

-# option

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. (If you 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.

-1 option

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.

-B option

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/9.1/exe. To test the upgraded product before making it available to everyone, the system administrator restores the latest install image under the directory /home/jim and then tries it out with commands similar to:

/home/jim/xlf/10.1/bin/xlf95 -tchIbdz -B/home/jim/xlf/9.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/10.1.

Related information

See -t option , -F option , Customizing the configuration file, and Running two levels of XL Fortran.

-C option

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. This is expected behavior and does not indicate there is a defect in the compiler product.

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.

-c option

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 .

-D 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.

Note that in order to pass C-style -D macro definitions to the C preprocessor, for example, compiling a file that ends with .F, use the -W option. For example:

-WF,-DDEFINE_THIS

Related information

-qdlines is the long form of -D.

-d option

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.

-F option

Syntax

-F{config_file | config_file:stanza | :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/10.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/10.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 /home/fred/xlf.cfg.
   xlf95 -F/home/fred/xlf.cfg t.f

# Use stanza myxlf in /home/fred/xlf.cfg.
   xlf95 -F/home/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.

-g option

Syntax

-g
DBG | NODBG

Generates debug information for use by a symbolic debugger.

-qdbg is the long form of -g.

-g implies the -Q! option.

Related information

-I option

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:

  1. The current directory (from which the compiler is executed)
  2. The directory where the source file is (if different from 1)
  3. /usr/include.

Also, the compiler will search /opt/ibmcmp/xlf/10.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.

-k option

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 Language Reference.

This option is the short form of -qfree=f90.

-L option

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/10.1/lib or /opt/ibmcmp/xlf/10.1/lib64, you can specify one or more -L options that point to the locations of the other libraries. You can also specify the LD_LIBRARY_PATH and LD_RUN_PATH environment variables for search paths for 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.

-l option

Syntax

-lkey

Searches the specified library file, where key selects the library libkey.so 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.

-NS option

Syntax

-NSbytes
SPILLSIZE(bytes)

Specifies the size (in bytes) of the register spill space; the internal program storage areas used by the optimizer for register spills to storage.

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.

-O option

Syntax

-O[level]
OPTimize[(level)] | NOOPTimize

Specifies whether to optimize code during compilation and, if so, at which level:

Arguments

not specified
Almost all optimizations are disabled. (This is equivalent to specifying -O0 or -qnoopt.
-O
For each release of XL Fortran, -O enables the level of optimization that represents the best tradeoff between compilation speed and run-time performance. If you need a specific level of optimization, specify the appropriate numeric value. Currently, -O is equivalent to -O2.
-O0
Almost all optimizations are disabled. This option is equivalent to -qnoopt.
-O1
Reserved for future use. This form does not currently do any optimization and is ignored.
-O2
Performs a set of optimizations that are intended to offer improved performance without an unreasonable increase in time or storage that is required for compilation.
-O3
Performs additional optimizations that are memory intensive, compile-time intensive, and may change the semantics of the program slightly, unless -qstrict is specified. We recommend these optimizations when the desire for run-time speed improvements outweighs the concern for limiting compile-time resources.

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.

Specifying -O3 implies -qhot=level=0 unless you explicitly specify -qhot or -qhot=level=1.

-O4
Aggressively optimizes the source program, trading off additional compile time for potential improvements in the generated code. You can specify the option at compile time or at link time. If you specify it at link time, it will have no effect unless you also specify it at compile time for at least the file that contains the main program.

-O4 implies the following other options:

  • -qhot
  • -qipa
  • -O3 (and all the options and settings that it implies)
  • -qarch=auto
  • -qtune=auto
  • -qcache=auto

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. For example, specifying -O4 -qarch=com allows aggressive intraprocedural optimization while maintaining code portability.

-O5
Provides all of the functionality of the -O4 option, but also provides the functionality of the -qipa=level=2 option.
Note:
Combining -O2 and higher optimizations with -qsmp=omp invokes additional optimization algorithms, including interprocedural analysis (IPA). IPA optimizations provide opportunities for the compiler to generate additional fmadd instructions.

To obtain the same floating-point accuracy for optimized and non-optimized applications, you must specify the -qfloat=nomaf compiler option. In cases where differences in floating-point accuracy still occur after specifying -qfloat=nomaf, the -qstrict compiler option allows you to exert greater control over changes that optimization can cause in floating-point semantics.

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.

If the -O option is used in an @PROCESS statement, only an optimization level of 0, 2, or 3 is allowed.

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 compiler 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.

-o option

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. For an assembler source file, use it in combination with the -S option.

Defaults

The default name for an executable file is a.out. The default name for an object or assembler source file is the same as the source file except that it has a .o or .s extension.

Rules

Except when you specify the -c or -S 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"
xlf95 -S -o t2.s t.f         # Produces "t2.s"

-p option

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.

-Q option

Syntax

-Q+names | -Q-names | -Q | -Q!

Specifies whether Fortran 90 or Fortran 95 procedures are inlined and/or the names of particular procedures that should or should not be inlined. names is a list of procedure names that are separated by colons.

Rules

By default, -Q only affects internal or module procedures. To turn on inline expansion for calls to procedures in different scopes, you must also use the -qipa option.

Arguments

The -Q option without any list inlines all appropriate procedures, subject to limits on the number of inlined calls and the amount of code size increase as a result. +names specifies the names, separated by colons, of procedures to inline and raises these limits for those procedures. -names specifies the names, separated by colons, of procedures not to inline. You can specify more than one of these options to precisely control which procedures are most likely to be inlined.

The -Q! option turns off inlining.

A procedure is not inlined by the basic -Q option unless it is quite small. In general, this means that it contains no more than several source statements (although the exact cutoff is difficult to determine). A procedure named by -Q+ can be up to approximately 20 times larger and still be inlined.

Restrictions

You must specify at least an optimization level of -O2 for inlining to take effect with -Q.

If you specify inlining for a procedure, the following @PROCESS compiler directives are only effective if they come before the first compilation unit in the file: ALIAS, ALIGN, ATTR, COMPACT, DBG, EXTCHK, EXTNAME, FLOAT, FLTTRAP, HALT, IEEE, LIST, MAXMEM, OBJECT, OPTIMIZE, PHSINFO, SPILLSIZE, STRICT, and XREF.

Examples

xlf95  -O -Q many_small_subprogs.f   # Compiler decides what to inline.
xlf95  -O -Q+bigfunc:hugefunc test.f # Inline even though these are big.
xlf95  -O -Q -Q-only_once pi.f       # Inline except for this one procedure.

Related information

-q32 option

Syntax

-q32

Enables 32-bit compilation mode (or, more briefly, 32-bit mode) support in a 64-bit environment. The -q32 option indicates the compilation bit mode and, together with the -qarch option, determines the target machines that the 32-bit executable will run on.

Rules

Examples

Related information

-q64 option

Syntax

-q64

Indicates the 64-bit compilation bit mode and, together with the -qarch option, determines the target machines on which the 64-bit executable will run. The -q64 option indicates that the object module will be created in 64-bit object format and that the 64-bit instruction set will be generated. Note that you may compile in a 32-bit environment to create 64-bit objects, but you must link them in a 64-bit environment with the -q64 option.

Rules

Examples

This example targets the RS64II (also known as RS64b) in 64-bit mode:

-q32 -qarch=rs64b -q64

In this example 64-bit compilation that targets the common group of 64-bit architectures (which currently consists only of the RS64II, RS64III, POWER3, POWER4, POWER5, POWER5+, and PowerPC 970):

-q64 -qarch=com
The arch setting is silently upgraded to ppc64grsq, the most "common" 64-bit mode compilation target.

Related information

-qalias option

Syntax

-qalias={argument_list}
ALIAS( {ARGUMENT_LIST} )

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. See Optimizing XL compiler programs for information on aliasing strategies you should consider.

Arguments

aryovrlp | noaryovrlp
Indicates whether the compilation units contain any array assignments between storage-associated arrays. If not, specify noaryovrlp to improve performance.
intptr | nointptr
Indicates whether the compilation units contain any integer POINTER statements. If so, specify INTPTR.
pteovrlp | nopteovrlp
Indicates whether any pointee variables may be used to refer to any data objects that are not pointee variables, or whether two pointee variables may be used to refer to the same storage location. If not, specify NOPTEOVRLP.
std | nostd
Indicates whether the compilation units contain any nonstandard aliasing (which is explained below). If so, specify nostd.

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:

Examples

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, xlf95_r, f90, and f95 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).

-qalign option

Syntax

-qalign={[no]4k|struct={suboption}|bindc={suboption}}
ALIGN({[NO]4K|STRUCT{(suboption)}|BINDC{(suboption)}})

Specifies the alignment of data objects in storage, which avoids performance problems with misaligned data. The [no]4k, bindc, and struct options can be specified and are not mutually exclusive. The [no]4k option is useful primarily in combination with logical volume I/O and disk striping.

Defaults

The default setting is -qalign= no4k:struct=natural:bindc=linuxppc.

Arguments

[no]4k
Specifies whether to align large data objects on page (4 KB) boundaries, for improved performance with data-striped I/O. Objects are affected depending on their representation within the object file. The affected objects are arrays and structures that are 4 KB or larger and are in static or bss storage and also CSECTs (typically COMMON blocks) that are 8 KB or larger. A large COMMON block, equivalence group containing arrays, or structure is aligned on a page boundary, so the alignment of the arrays depends on their position within the containing object. Inside a structure of non-sequence derived type, the compiler adds padding to align large arrays on page boundaries.
bindc={suboption}
Specifies that the alignment and padding for an XL Fortran derived type with the BIND(C) attribute is compatible with a C struct type that is compiled with the corresponding XL C alignment option. The compatible alignment options include:
XL Fortran Option
Corresponding
XL C Option
-qalign=bindc=bit_packed -qalign=bit_packed
-qalign=bindc=linuxppc -qalign=linuxppc
struct={suboption}
The struct option specifies how objects or arrays of a derived type declared using a record structure are stored, and whether or not padding is used between components. All program units must be compiled with the same settings of the -qalign=struct option. The three suboptions available are:
packed
If the packed suboption of the struct option is specified, objects of a derived type are stored with no padding between components, other than any padding represented by %FILL components. The storage format is the same as would result for a sequence structure whose derived type was declared using a standard derived type declaration.
natural
If the natural suboption of the struct option is specified, objects of a derived type are stored with sufficient padding such that components will be stored on their natural alignment boundaries, unless storage association requires otherwise. The natural alignment boundaries for objects of a type that appears in the left-hand column of the following table is shown in terms of a multiple of some number of bytes in the corresponding entry in the right-hand column of the table.
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.

port

If the port suboption of the struct option is specified,

  • Storage padding is the same as described above for the natural suboption, with the exception that the alignment of components of type complex is the same as the alignment of components of type real of the same kind.
  • The padding for an object that is immediately followed by a union is inserted at the beginning of the first map component for each map in that union.

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.

-qarch option

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.

In general, the -qarch option allows you to target a specific architecture for the compilation. For any given -qarch setting, the compiler defaults to a specific, matching -qtune setting, which can provide additional performance improvements. The resulting code may not run on other architectures, but it will provide the best performance for the selected architecture. To generate code that can run on more than one architecture, specify a -qarch suboption that supports a group of architectures, such as com, ppc, or ppc64; doing this will generate code that runs on all supported architectures, all PowerPC architectures, or all 64-bit PowerPC architectures, respectively. When a -qarch suboption is specified with a group argument, you can specify -qtune as either auto, or provide a specific architecture in the group. In the case of -qtune=auto, the compiler will generate code that runs on all architectures in the group specified by the -qarch suboption, but select instruction sequences that have best performance on the architecture of the machine used to compile. Alternatively you can target a specific architecture for tuning performance.

Arguments

Otherwise, the choices for architecture are:

auto
Automatically detects the specific architecture of the compiling machine. It assumes that the execution environment will be the same as the compilation environment. This option is implied if the -O4 or -O5 option is set or implied.
com
You can run the executable file that the compiler generated on any hardware platform supported by the compiler, because the file contains only instructions that are common to all machines. This choice is the same as the default, -qarch=ppc64grsq.

If you specify the -q64 and -qarch=com options together, the target platform is 64-bit, and the -qarch option is silently upgraded to ppc64grsq. The instruction set will be restricted to those instructions common to all 64-bit machines. See Using XL Fortran in a 64-Bit Environment for details.

ppc
You can run the executable file on any PowerPC hardware platform, including those that are based on the RS64II, RS64III, POWER3, POWER4, POWER5, PowerPC 970, and future PowerPC chips. If you specify the compiler option -q64, the target platform is 64-bit PowerPC, and the compiler silently upgrades the -qarch setting to ppc64grsq. See Using XL Fortran in a 64-Bit Environment for details.
ppcgr
In 32-bit mode, produces object code that may contain optional graphics instructions for PowerPC hardware platforms.

In 64-bit mode, produces object code containing optional graphics instructions that will run on 64-bit PowerPC platforms, but not on 32-bit-only platforms, and the -qarch option will be silently upgraded to -qarch=ppc64grsq.

ppc64
You can run the executable file on any 64-bit PowerPC hardware platform. This suboption can be selected when compiling in 32-bit mode, but the resulting object code may include instructions that are not recognized or behave differently when run on PowerPC platforms that do not support 64-bit mode.
ppc64gr
You can run the executable file on any 64-bit PowerPC hardware platform that supports the optional graphics instructions.
ppc64grsq
You can run the executable file on any 64-bit PowerPC hardware platform that supports the optional graphics and square root instructions. This is the default option.
rs64b
You can run the executable file on any RS64II machine.
rs64c
You can run the executable file on any RS64III machine.
pwr3
You can run the executable file on any POWER3, POWER4, POWER5, POWER5+, or PowerPC 970 hardware platform. In previous releases, the pwr3 setting was used to target the POWER3 and POWER4 group of processors. To have your compilation target a more general processor group, use the ppc64grsq setting, which includes the POWER3, POWER4, POWER5, POWER5+ or PowerPC 970 group of processors. Because executable files for these platforms may contain instructions that are not available on other PowerPC systems, they may be incompatible with those systems.
pwr4
You can run the executable file on any POWER4, POWER5, POWER5+ or PowerPC 970 hardware platform. Use of -qarch=pwr4 will result in binaries that will not run on most previous PowerPC implementations.
pwr5
You can run the executable file on any POWER5 or POWER5+ hardware platform.
pwr5x
You can run the executable file on any POWER5+ hardware platform.
ppc64v
You can run the executable file on any 64-bit PowerPC hardware platform that supports the optional VMX instructions, such as a PowerPC 970.
ppc970
You can run the executable file on any PowerPC 970 hardware platform.
Notes:
  1. The -qarch setting determines the allowed choices and defaults for the -qtune setting. You can use -qarch and -qtune to target your program to particular machines.
  2. Specifying -q64 with -qarch=com, -qarch=ppc, or -qarch= ppcgr silently upgrades the setting -qarch=ppc64grsq.

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=pwr3 to indicate that your program will be executed on POWER3 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:

Other considerations

The PowerPC instruction set includes two optional instruction groups that may be implemented by a particular hardware platform, but are not required. These two groups are the graphics instruction group and the sqrt instruction group. Code compiled with specific -qarch options (all of which refer to specific PowerPC machines) will run on any equivalent PowerPC machine that has an identical instruction group. The following table illustrates the instruction groups that are included for the various PowerPC machines.

Table 14. Instruction groups for PowerPC platforms
Processor Graphics group sqrt group 64-bit
ppc no no no
ppcgr yes no no
ppc64 no no yes
ppc64v yes yes yes
ppc64gr yes no yes
ppc64grsq yes yes yes
rs64b yes yes yes
rs64c yes yes yes
pwr3 yes yes yes
pwr4 yes yes yes
pwr5 yes yes yes
pwr5x yes yes yes
ppc970 yes yes yes

Related information

-qassert option

Syntax

-qassert={deps | nodeps | itercnt=n}
ASSERT(DEPS) | NODEPS | ITERCNT(N))

Provides information about the characteristics of the files that can help to fine-tune optimizations.

Arguments

deps | nodeps
Specifies whether or not any loop-carried dependencies exist.
itercnt=n
Specifies a value for unknown loop iteration counts.

Related information

See the following:

-qattr option

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.

-qautodbl option

Syntax

-qautodbl=setting
AUTODBL(setting)

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.

Arguments

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:

none
Does not promote or pad any objects that share storage. This setting is the default.
dbl4
Promotes floating-point objects that are single-precision (4 bytes in size) or that are composed of such objects (for example, COMPLEX or array objects):
  • REAL(4) is promoted to REAL(8).
  • COMPLEX(4) is promoted to COMPLEX(8).

This suboption requires the libxlfpmt4.a library during linking.

dbl8
Promotes floating-point objects that are double-precision (8 bytes in size) or that are composed of such objects:
  • REAL(8) is promoted to REAL(16).
  • COMPLEX(8) is promoted to COMPLEX(16).

This suboption requires the libxlfpmt8.a library during linking.

dbl
Combines the promotions that dbl4 and dbl8 perform.

This suboption requires the libxlfpmt4.a and libxlfpmt8.a libraries during linking.

dblpad4
Performs the same promotions as dbl4 and pads objects of other types (except CHARACTER) if they could possibly share storage with promoted objects.

This suboption requires the libxlfpmt4.a and libxlfpad.a libraries during linking.

dblpad8
Performs the same promotions as dbl8 and pads objects of other types (except CHARACTER) if they could possibly share storage with promoted objects.

This suboption requires the libxlfpmt8.a and libxlfpad.a libraries during linking.

dblpad
Combines the promotions done by dbl4 and dbl8 and pads objects of other types (except CHARACTER) if they could possibly share storage with promoted objects.

This suboption requires the libxlfpmt4.a, libxlfpmt8.a, and libxlfpad.a libraries during linking.

Rules

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.

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.

-qbigdata option

Syntax

-qbigdata | -qnobigdata

In 32-bit mode, use this compiler option for programs that exceed 16MB of initialized data (a gcc limitation) and call routines in shared libraries (like open, close, printf and so on).

-qcache 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 the -qhot option or an option that implies -qhot.

Arguments

assoc=number
Specifies the set associativity of the cache:
0
Direct-mapped cache
1
Fully associative cache
n > 1
n-way set-associative cache
auto
Automatically detects the specific cache configuration of the compiling machine. It assumes that the execution environment will be the same as the compilation environment.
cost=cycles
Specifies the performance penalty that results from a cache miss so that the compiler can decide whether to perform an optimization that might result in extra cache misses.
level=level
Specifies which level of cache is affected:
1
Basic cache
2
Level-2 cache or the table lookaside buffer (TLB) if the machine has no level-2 cache
3
TLB in a machine that does have a level-2 cache
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.
line=bytes
Specifies the line size of the cache.
size=Kbytes
Specifies the total size of this cache.
type={C|c| D|d|I|i}
Specifies the type of cache that the settings apply to, as follows:
  • C or c for a combined data and instruction cache
  • D or d for the data cache
  • I or i for the instruction cache

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.

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 .

-qcclines 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 -qcclines if the -qsmp=omp option is turned on; otherwise, the default is -qnocclines.

Related information

See Conditional Compilation in the Language Elements section of the XL Fortran Language Reference.

-qcheck option

Syntax

-qcheck | -qnocheck
CHECK | NOCHECK

-qcheck is the long form of the -C option .

-qci 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 Language Reference.

-qcompact option

Syntax

-qcompact | -qnocompact
COMPACT | NOCOMPACT

Reduces optimizations that increase code size.

By default, some techniques the optimizer uses to improve performance, such as loop unrolling and array vectorization, may also make the program larger. For systems with limited storage, you can use -qcompact to reduce the expansion that takes place. If your program has many loop and array language constructs, using the -qcompact option will affect your application's overall performance. You may want to restrict using this option to those parts of your program where optimization gains will remain unaffected.

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.

-qcr option

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.

-qctyplss option

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

arg | noarg
Suboptions retain the behavior of -qctyplss. Additionally, arg specifies that Hollerith constants used as actual arguments will be treated as integer actual 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 and Passing arguments by reference or by value.

-qdbg option

Syntax

-qdbg | -qnodbg
DBG | NODBG

-qdbg is the long form of the -g option .

-qddim 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

-qdirective option

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 compiler comment directive is a line that is not a Fortran statement but is recognized and acted on by the compiler. 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*. Specification of -qsmp implies -qdirective=smp\$:\$omp:ibmp, and, by default, the trigger constants SMP$, $OMP, and IBMP are also turned on. If you specify -qsmp=omp, the compiler ignores all trigger constants that you have specified up to that point and recognizes only the $OMP trigger constant. Specification of -qthreaded implies -qdirective=ibmt, and, by default, the trigger constant IBMT is also turned on.

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

Examples

! This program is written in Fortran free source form.
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.
      INCLUDE 'set_c_and_d.inc'
!IBM* SOURCEFORM(FREE)
! Switch back to free source form.
E = 5
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 processing the include-file line, the program reverts back to free source form, after the SOURCEFORM(FREE) statement.

Related information

See the section on the SOURCEFORM directive in the XL Fortran 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 Language Reference for the suitable associated trigger constant.

-qdirectstorage option

Syntax

-qdirectstorage | -qnodirectstorage

Informs the compiler that a given compilation unit may reference write-through-enabled or cache-inhibited storage.

Use this option with discretion. It is intended for programmers who know how the memory and cache blocks work, and how to tune their applications for optimal performance. For a program to execute correctly on all PowerPC implementations of cache organization, the programmer should assume that separate instruction and data caches exist, and should program to the separate cache model.

Note:
Using the -qdirectstorage option together with the CACHE_ZERO directive may cause your program to fail, or to produce incorrect results..

-qdlines option

Syntax

-qdlines | -qnodlines
DLINES | NODLINES

-qdlines is the long form of the -D option .

-qdpc 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.

-qenablevmx option

Syntax

-qenablevmx | -qnoenablevmx

Enables the generation of Vector Multimedia eXtension (VMX) instructions. These instructions can offer higher performance when used with algorithmic-intensive tasks such as multimedia applications.

-qenablevmx must be on in order for the compiler to enable both the VMX intrinsic functions and -qhot=simd optimizations. -qenablevmx is only compatible with -qarch targets that support VMX instructions, like PowerPC 970 processors.

Related information

-qenum option

Syntax

-qenum=value

Specifies the range of the enumerator constant and enables storage size to be determined.

Arguments

Regardless of its storage size, the enumerator's value will be limited by the range that corresponds to value. If the enumerator value exceeds the range specified, a warning message is issued and truncation is performed as necessary. The range limit and kind type parameter corresponding to each value is as follows:

Table 15. Enumerator sizes and types
Value Valid range of enumerator constant value Kind type parameter
1 -128 to 127 4
2 -32768 to 32767 4
4 -2147483648 to 2147483647 4
8 -9223372036854775808 to 9223372036854775807 8

Related information

-qescape option

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 Escape sequences for character strings.

-qessl Option

Syntax

-qessl | -qnoessl

Allows the use of the Engineering and Scientific Subroutine Library (ESSL) routines in place of Fortran 90 intrinsic procedures.

The ESSL is a collection of subroutines that provides a wide range of mathematical functions for various scientific and engineering applications. The subroutines are tuned for performance on specific architectures. Some of the Fortran 90 intrinsic procedures have similar counterparts in ESSL. Performance is improved when these Fortran 90 intrinsic procedures are linked with ESSL. In this case, you can keep the interface of Fortran 90 intrinsic procedures, and get the added benefit of improved performance using ESSL.

Rules

Use the ESSL Serial Library when linking with -lessl. Use the ESSL SMP Library when linking with -lesslsmp.

Either -lessl or -lesslsmp must be used whenever code is being compiled with -qessl. ESSL V4.1.1 or above is recommended. It supports both 32-bit and 64-bit environments.

Also, since libessl.so and libesslsmp.so have a dependency on libxlf90_r.so, compile with xlf_r, xlf90_r, or xlf95_r, which use libxlf90_r.so as the default to link. You can also specify -lxlf90_r on the link command line if you use the linker directly, or other commands to link.

The following MATMUL function calls may use ESSL routines when -qessl is enabled:

 real a(10,10), b(10,10), c(10,10)
   c=MATMUL(a,b)

Related information

The ESSL libraries are not shipped with the XL Fortran compiler. For more information on these libraries, see the following URL: http://publib.boulder.ibm.com/clresctr/windows/public/esslbooks.html.

-qextern option

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.

-qextname option

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 , -Q option , and -qsigtrap option .

-qfixed 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 f90, f95, 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 Language Reference.

-qflag option

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:

i
Informational messages. They explain things that you should know, but they usually do not require any action on your part.
l
Language-level messages, such as those produced under the -qlanglvl option. They indicate possible nonportable language constructs.
w
Warning messages. They indicate error conditions that might require action on your part, but the program is still correct.
e
Error messages. They indicate error conditions that require action on your part to make the program correct, but the resulting program can probably still be executed.
s
Severe error messages. They indicate error conditions that require action on your part to make the program correct, and the resulting program will fail if it reaches the location of the error. You must change the -qhalt setting to make the compiler produce an object file when it encounters this kind of error.
u
Unrecoverable error messages. They indicate error conditions that prevent the compiler from continuing. They require action on your part before you can compile your program.
q
No messages. A severity level that can never be generated by any defined error condition. Specifying it prevents the compiler from displaying messages, even if it encounters unrecoverable errors.

The -qflag option overrides any -qlanglvl or -qsaa options specified.

Defaults

The default for this option is i:i, which will show all compiler messages.

Related information

See -qlanglvl option and Understanding XL Fortran error messages.

-qfloat option

Syntax

-qfloat=options
FLOAT(options)

Selects different strategies for speeding up or improving the accuracy of floating-point calculations.

You should be familiar with the information in Implementation details of 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, nohsflt, 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 nohsflt, or 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:

complexgcc | nocomplexgcc
Use Linux conventions when passing or returning complex numbers. This option preserves compatibility with gcc-compiled code and the default setting of IBM XL C/C++ compilers on Linux.
Note:
For this suboption, restrict intermixing of XL Fortran-compiled code with non XL Fortran-compiled code to small, self-contained, mathematically-oriented subprograms that do not rely on any run-time-library information or global data, such as module variables. Do not expect exception handling or I/O to work smoothly across programs compiled from different environments.
fltint | nofltint
Speeds up floating-point-to-integer conversions by using an inline sequence of code instead of a call to a library function.

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.

fold | nofold
Evaluates constant floating-point expressions at compile time, which may yield slightly different results from evaluating them at run time. The compiler always evaluates constant expressions in specification statements, even if you specify nofold.
hsflt | nohsflt
Speeds up calculations by preventing rounding for single-precision expressions and by replacing floating-point division by multiplication with the reciprocal of the divisor. It also uses the same technique as the fltint suboption for floating-point-to-integer conversions.
Note:
Use -qfloat=hsflt on applications that perform complex division and floating-point conversions where floating-point calculations have known characteristics. In particular, all floating-point results must be within the defined range of representation of single precision. The use of this option when compiling other application programs may produce unexpected results without warning. Use with discretion. See Technical details of the -qfloat=hsflt option for details.
maf | nomaf
Makes floating-point calculations faster and more accurate by using multiply-add instructions where appropriate. The possible disadvantage is that results may not be exactly equivalent to those from similar calculations that are performed at compile time or on other types of computers. Also, negative zero may be produced.
nans | nonans
Allows you to use the -qflttrap=invalid:enable option to detect and deal with exception conditions that involve signaling NaN (not-a-number) values. Use this suboption only if your program explicitly creates signaling NaN values, because these values never result from other floating-point operations.
rrm | norrm
Turns off compiler optimizations that require the rounding mode to be the default, round-to-nearest, at run time. Use this option if your program changes the rounding mode by any means, such as by calling the fpsets procedure. Otherwise, the program may compute incorrect results.
rsqrt | norsqrt
Speeds up some calculations by replacing division by the result of a square root with multiplication by the reciprocal of the square root.

Although this suboption is turned off by default, specifying -O3 turns it on unless you also specify -qstrict.

strictnmaf | nostrictnmaf
Turns off floating-point transformations that are used to introduce negative MAF instructions, as these transformations do not preserve the sign of a zero value. By default, the compiler enables these types of transformations.

To ensure strict semantics, specify both -qstrict and -qfloat=strictnmaf.

-qflttrap option

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

ENable
Turn on checking for the specified exceptions in the main program so that the exceptions generate SIGFPE signals. You must specify this suboption if you want to turn on exception trapping without modifying your source code.
IMPrecise
Only check for the specified exceptions on subprogram entry and exit. This suboption improves performance, but it can make the exact spot of the exception difficult to find.
INEXact
Detect and trap on floating-point inexact if exception-checking is enabled. Because inexact results are very common in floating-point calculations, you usually should not need to turn this type of exception on.
INValid
Detect and trap on floating-point invalid operations if exception-checking is enabled.
NANQ
Detect and trap all quiet not-a-number values (NaNQs) and signaling not-a-number values (NaNSs). Trapping code is generated regardless of specifying the enable or imprecise suboption. This suboption detects all NaN values handled by or generated by floating point instructions, including those not created by invalid operations. This option can impact performance.
OVerflow
Detect and trap on floating-point overflow if exception-checking is enabled.
UNDerflow
Detect and trap on floating-point underflow if exception-checking is enabled.
ZEROdivide
Detect and trap on floating-point division by zero if exception-checking is enabled.

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.

The -qflttrap option is recognized during linking with IPA. Specifying the option at the link step overrides the compile-time setting.

Examples

When you compile this program:

        REAL X, Y, Z
        DATA X /5.0/, Y /0.0/
        Z = X / Y
        PRINT	*, Z
        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

-qfree option

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 f90, f95, 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 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 Language Reference.

-qfullpath option

Syntax

-qfullpath | -qnofullpath

Records the full, or absolute, path names of source and include files in object files compiled with debugging information. (Debug information is produced when you compile with the -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 .

-qhalt 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:

i
Informational messages. They explain things that you should know, but they usually do not require any action on your part.
l
Language-level messages, such as those produced under the -qlanglvl option. They indicate possible nonportable language constructs.
w
Warning messages. They indicate error conditions that might require action on your part, but the program is still correct.
e
Error messages. They indicate error conditions that require action on your part to make the program correct, but the resulting program can probably still be executed.
s
Severe error messages. They indicate error conditions that require action on your part to make the program correct, and the resulting program will fail if it reaches the location of the error. You must change the -qhalt setting to make the compiler produce an object file when it encounters this kind of error.
u
Unrecoverable error messages. They indicate error conditions that prevent the compiler from continuing. They require action on your part before you can compile your program.
q
No messages. A severity level that can never be generated by any defined error condition. Specifying it prevents the compiler from displaying messages, even if it encounters unrecoverable errors.

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.

Related information

-qhot option

Syntax

-qhot[=suboptions] | -qnohot
HOT[=suboptions] | NOHOT

Instructs the compiler to perform high-order loop analysis and transformations during optimization.

The -qhot compiler option is a powerful alternative to hand tuning that provides opportunities to optimize loops and array language. This compiler option will always attempt to optimize loops, regardless of the suboptions you specify.

If you do not specify an optimization level of 2 or higher when using -O and -qhot, the compiler implies -O2.

If you specify -O3, the compiler assumes -qhot=level=0. To prevent all HOT optimizations with -O3, you must specify -qnohot.

Specifying -qhot without suboptions implies -qhot=nosimd, -qhot=noarraypad, -qhot=vector, and -qhot=level=1. These suboptions are also implied by the options -qsmp, -O4, or -O5.

If you specify -qhot, -qenablevmx, and either -qarch=ppc970 or -qarch=ppc64v, -qhot=simd will be set as the default.

Array padding

In XL Fortran, array dimensions that are powers of two can lead to a decrease in cache utilization. The arraypad suboption allows the compiler to increase the dimensions of arrays where doing so could improve the efficiency of array-processing loops. This can reduce cache misses and page faults that slow your array processing programs.

Specify -qhot=arraypad when your source includes large arrays with dimensions that are powers of 2. This can be particularly effective when the first dimension is a power of 2.

The -C option turns off some array optimizations.

Vectorization

The -qhot compiler option supports the simd and vector suboptions that can optimize loops in source code for operations on array data, by ensuring that operations run in parallel where applicable. Though both suboptions can provide an increase in performance, each suboption best applies to a particular type of vectorization.

Short vectorization: -qhot=simd

The simd suboption optimizes array data to run mathematical operations in parallel where the target architecture allows such operations. Parallel operations occur in 16-byte vector registers. The compiler divides vectors that exceed the register length into 16-byte units to facilitate optimization. A 16-byte unit can contain one of the following types of data:

Short vectorization does not support double-precision floating point mathematics, and you must specify an architecture that supports VMX instructions, like -qarch=ppc970. Users can typically see benefit when applying the -qhot=simd optimization to image processing applications, for example.

Long vectorization: -qhot=vector

The vector suboption, when used in conjunction with -qnostrict or an optimization level of -O3 or higher, optimizes array data to run mathematical operations in parallel where applicable. The compiler uses standard registers with no vector size restrictions. Supporting single and double-precision floating-point mathematics, users can typically see benefit when applying -qhot=vector to applications with significant mathematical requirements.

Arguments

arraypad
The compiler pads any arrays where there could be an increase in cache utilization. Not all arrays will necessarily be padded, and the compiler can pad different arrays by different amounts.
arraypad=n
The compiler pads each array in the source. The pad amount must be a positive integer value. Each array will be padded by an integral number of elements. The integral value n must be multiples of the largest array element size for effective use of arraypad. This value is typically 4, 8, or 16.

When you specify the arraypad and arraypad=n options, the compiler does not check for reshaping or equivalences. If padding takes place, your program can produce unexpected results.

level={0 | 1}
level=0
The compiler performs a subset of the of high-order transformations. Some of these include early distribution, loop interchange, and loop tiling, as examples.

Optimization level -O3 implies -qhot=level=0.

level=1
-qhot=level=1 is equivalent to -qhot and the compiler options that imply -qhot also imply -qhot=level=1, unless-qhot=level=0 is explicitly specified.

The default hot level for all -qhot suboptions other than level is 1. For example specifying -O3 -qhot=novector sets the hot level to 1.

Specifying -O3 implies -qhot=level=0, unless you explicitly specify -qhot or -qhot=level=1.

Any of -O4, -O5, or -qsmp implies -qhot=level=1, unless you explicitly specify -qhot=level=0.

simd | nosimd
The compiler converts certain operations in a loop that apply to successive elements of an array into a call to a VMX (Vector Multimedia eXtension) instruction. This call calculates several results at one time, which is faster than calculating each result sequentially.

If you specify -qhot=nosimd, the compiler performs optimizations on loops and arrays, but avoids replacing certain code with calls to VMX instructions.

This suboption has effect only when the specified architecture supports VMX instructions and -qenablevmx is in effect.

vector | novector
When specified with -qnostrict or an optimization level of -O3 or higher, the compiler converts certain operations (for example, square root, reciprocal square root) into a call to a MASS library routine that is in the libxlopt.a library. If the operations are in a loop, the vector version of the routine is called. If the operations are scalar, the scalar version of the routine is called. This call will calculate several results at one time, which is faster than calculating each result sequentially.

Since vectorization can affect the precision of your program's results if you are using -O4 or higher, you should specify -qhot=novector if the change in precision is unacceptable.

Related information

-qieee option

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:

Near
Round to nearest representable number.
Minus
Round toward minus infinity.
Plus
Round toward plus infinity.
Zero
Round toward zero.

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.

Note:
Compile-time arithmetic is most extensive when you also specify the -O option.

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

-qinit option

Syntax

-qinit=f90ptr
INIT(F90PTR)

Makes the initial association status of pointers disassociated. Note that this applies to Fortran 90 and above.

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 Language Reference.

-qinitauto option

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 Language Reference.

-qinlglue option

Syntax

-qinlglue | -qnoinlglue
INLGLUE | NOINLGLUE

This option inlines glue code that optimizes external function calls in your application, when compiling at -q64 and -O2 and higher.

Glue code, generated by the linker, is used for passing control between two external functions. To aid performance, the optimizer automatically inlines glue code when you compile with -qtune=pwr4, -qtune=pwr5, -qtune=ppc970, or -qtune=auto on a machine with the appropriate processor. -qnoinlglue prevents the automatic inlining of glue code on these architectures.

The inlining of glue code can increase the size of your code. Specifying -qcompact overrides -qinlglue to prevent code growth.

Specifying -qnoinlglue or -qcompact can degrade performance; use these options with discretion.

Related information

-qintlog option

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:

Related information

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.

-qintsize option

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 size1 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. Note that specifying the -q64 compiler option does not affect the default setting for -qintsize.

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 Language Reference.

-qipa option

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.) For additional performance benefits, you can also specify the -Q option. 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:

  1. Do preliminary performance analysis and tuning before compiling with the -qipa option. This is necessary because interprocedural analysis uses a two-phase mechanism, a compile-time and a link-time phase, which increases link time. (You can use the noobject suboption to reduce this overhead.)
  2. Specify the -qipa option on both the compile and link steps of the entire application or on as much of it as possible. Specify suboptions to indicate what assumptions to make about the parts of the program that are not compiled with -qipa. If your application contains C or C++ code compiled with IBM XL C/C++ compilers, you should also compile the C or C++ code with the -qipa option to allow for additional optimization opportunities at link time.)

    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

Compile-time suboptions

IPA uses the following suboptions during its compile-time phase:

object | noobject
Specifies whether to include standard object code in the object files. Specifying the noobject suboption can substantially reduce overall compilation time, by not generating object code during the first IPA phase. Note that if you specify -S with noobject, noobject will be ignored.

If compiling and linking are performed in the same step and you do not specify the -S or 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.

Link-time suboptions

IPA uses the following suboptions during its link-time phase:

clonearch=arch{,arch} | noclonearch
Specifies the architectures for which multiple versions of the same instruction set are produced. Use this suboption if you require optimal performance on multiple differing machines running the same copy of your application.

The compiler generates a generic version of the instruction set based on the -qarch setting in effect, and if appropriate, clones specialized versions of the instruction set for the architectures you specify in the clonearch suboption. The compiler inserts code into your application to check for the processor architecture at run time. When run, the application's version of the instruction set that is best optimized for the run-time environment is selected.

arch is a comma-separated list of architecture values. The supported clonearch values are pwr4, pwr5, and ppc970. If you specify no value, an invalid value, or a value equal to the -qarch setting, no function versioning will be performed for this option.

Notes:
  1. To ensure compatibility across multiple platforms, the -qarch value must be the subset of the architecture specified by -qarch=clonearch=arch.
  2. When -qcompact is in effect, -qarch=clonearch=arch is disabled.
Table 16. Compatible architecture and clonearch settings
-qarch setting Allowed clonearch value
com, ppc, pwr3, ppc64, ppcgr, ppc64gr, ppc64grsq pwr4, pwr5, ppc970
pwr4 pwr5, ppc970
ppc64v ppc970
cloneproc=name{,name} | nocloneproc[=name{,name}]
Specifies the name of the functions to clone for the architectures specified by the clonearch suboption. Where name is a comma-separated list of function names.
Note:
If you do not specify -qipa=clonearch=arch or specify -qipa=noclonearch, -qipa=cloneproc=name and -qipa=nocloneproc=name have no effect.
exits=procedure_names
Specifies a list of procedures, each of which always ends the program. The compiler can optimize calls to these procedures (for example, by eliminating save/restore sequences), because the calls never return to the program. These procedures must not call any other parts of the program that are compiled with -qipa.
inline=inline-options
The -qipa=inline= command can take a colon-separated list of inline options, as listed below:
auto | noauto
Specifies whether to automatically inline procedures.
limit=number
Changes the size limits that the inline=auto option uses to determine how much inline expansion to do. This established "limit" is the size below which the calling procedure must remain. number is the optimizer's approximation of the number of bytes of code that will be generated. Larger values for this number allow the compiler to inline larger subprograms, more subprogram calls, or both. This argument is implemented only when inline=auto is on.
procedure_names
Specifies a list of procedures to try to inline.
threshold=number
Specifies the upper size limit on procedures to be inlined, where number is a value as defined under the inline suboption "limit". This argument is implemented only when "inline=auto" is on.
Note:
By default, the compiler will try to inline all procedures, not just those that you specified with the inline=procedure_names suboption. If you want to turn on inlining for only certain procedures, specify inline=noauto after you specify inline=procedure_names. (You must specify the suboptions in this order.) For example, to turn off inlining for all procedures other than for sub1, specify -qipa=inline=sub1:inline=noauto.
isolated=procedure_names
Specifies a comma-separated list of procedures that are not compiled with -qipa. Procedures that you specify as "isolated" or procedures within their call chains cannot refer directly to any global variable.
level=level
Determines the amount of interprocedural analysis and optimization that is performed:
0
Does only minimal interprocedural analysis and optimization.
1
Turns on inlining, limited alias analysis, and limited call-site tailoring.
2
Full interprocedural data flow and alias analysis. Specifying -O5 is equivalent to specifying -O4 and -qipa=level=2.
The default level is 1.
list[=filename | short | long]

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.

lowfreq=procedure_names
Specifies a list of procedures that are likely to be called infrequently during the course of a typical program run. For example, procedures for initialization and cleanup might only be called once, and debugging procedures might not be called at all in a production-level program. The compiler can make other parts of the program faster by doing less optimization for calls to these procedures.
missing={unknown | safe | isolated | pure}
Specifies the interprocedural behavior of procedures that are not compiled with -qipa and are not explicitly named in an unknown, safe, isolated, or pure suboption. The default is to assume unknown, which greatly restricts the amount of interprocedural optimization for calls to those procedures.
noinline=procedure_names
Specifies a list of procedures that are not to be inlined.
partition={small | medium | large}
Specifies the size of the regions within the program to analyze. Larger partitions contain more procedures, which result in better interprocedural analysis but require more storage to optimize. Reduce the partition size if compilation takes too long because of paging.
pdfname=[filename]

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 you 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.)

pure=procedure_names
Specifies a list of procedures that are not compiled with -qipa. Any procedure that you specified as "pure" must be "isolated" and "safe". It must not alter the internal state nor have side-effects, which are defined as potentially altering any data object visible to the caller.
safe=procedure_names
Specifies a list of procedures that are not compiled with -qipa. Any procedure that you specified as "safe" may modify global variables and dummy arguments. No calls to procedures that are compiled with -qipa may be made from within a "safe" procedure's call chain.
stdexits | nostdexits
Specifies that certain predefined routines can be optimized as with the exits suboption. The procedures are: abort, exit, _exit, and _assert.
threads[=N] | nothreads
threads[=N] runs the number of parallel threads that are available, or as specified by N. N must be a positive integer. nothreads does not run any parallel threads. This is equivalent to running one serial thread.

Specifying -qipa=threads can reduce IPA optimization time. The threads suboption allows the IPA optimizer to run portions of the optimization process in parallel threads, which can speed up the compilation process on multi-processor systems.

unknown=procedure_names
Specifies a list of procedures that are not compiled with -qipa. Any procedure specified as "unknown" may make calls to other parts of the program compiled with -qipa and modify global variables and dummy arguments.

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:

-qlibansi | -qnolibansi
Assumes that all functions with the name of an ANSI C defined library function are, in fact, the library functions.
-qlibposix | -qnolibposix
Assumes that all functions with the name of an IEEE 1003.1-2001 (POSIX) defined library function are, in fact, the system functions.
-qthreaded
Assumes that the compiler will attempt to generate thread-safe code.

Rules

Regular expressions are supported for the following suboptions:

Syntax rules for regular expressions are described below.

Table 17. 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 , -p option , and -Q option .

-qkeepparm option

Syntax

-qkeepparm | -qnokeepparm

Background information

A procedure usually stores its incoming parameters on the stack at the entry point. When you compile code with optimization, 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.

-qlanglvl option

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

77std
Accepts the language that the ANSI FORTRAN 77 standard specifies and reports anything else as an error.
90std
Accepts the language that the ISO Fortran 90 standard specifies and reports anything else as an error.
90pure
The same as 90std except that it also reports errors for any obsolescent Fortran 90 features used.
95std
Accepts the language that the ISO Fortran 95 standard specifies and reports anything else as an error.
95pure
The same as 95std except that it also reports errors for any obsolescent Fortran 95 features used.
2003std
Accepts the language that the ISO Fortran 95 standard specifies, as well as all Fortran 2003 features supported by XL Fortran, and reports anything else as an error.
2003pure
The same as 2003std except that it also reports errors for any obsolescent Fortran 2003 features used.
extended
Accepts the full Fortran 95 language standard, all Fortran 2003 features supported by XL Fortran, and all extensions, effectively turning off language-level checking.

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

Flags computed GOTO
  statement
Flags GAMMA intrinsic
Deleted feature in
  Fortran 95
Obsolescent feature in
  Fortran 95
Extension to Fortran 95
95std
Flags PAUSE statement

Flags GAMMA intrinsic
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.

-qlibansi option

Syntax

-qlibansi | -qnolibansi

Assumes that all functions with the name of an ANSI C library function are, in fact, the system functions.

This option will allow the optimizer to generate better code because it will know about the behavior of a given function, such as whether or not it has any side effects.

Note:
Do not use this option if your application contains your own version of a C library function that is incompatible with the standard one

Related information

See -qipa option .

-qlibposix option

Related information

See -qipa option .

-qlinedebug option

Syntax

-qlinedebug | -qnolinedebug
LINEDEBUG | NOLINEDEBUG

Generates line number and source file name information for the debugger.

This option produces minimal debugging information, so the resulting object size is smaller than that produced if the -g debugging option is specified. You can use the debugger to step through the source code, but you will not be able to see or query variable information. The traceback table, if generated, will include line numbers.

As with -g, the higher the optimization level used, the more likely that debug information, including line numbers, will be misleading.

If you specify the -qlinedebug option, the inlining option defaults to -Q! (no functions are inlined).

The -qnolinedebug option has no effect on -g.

Related information

-qlist option

Syntax

-qlist[=offset | nooffset] | -qnolist
LIST[([NO]OFFSET)] | NOLIST

Produces a compiler listing that includes an object 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.

Notes

The -qlist=offset option is relevant only if there are multiple procedures in a compilation unit. For example, this may occur if nested procedures are used in a program.

If you specify -qlist=offset, the listing will show the offset from the start of the procedure rather than the offset from the start of code generation.

The offset of the PDEF header will contain the offset from the start of the text area. This allows any program reading the .lst file to add the value of the PDEF and the line in question, and produce the same value whether -qlist=offset or -qlist=nooffset is specified.

Specifying the -qlist option implies -qlist=nooffset.

Related information

-qlistopt option

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.

-qlog4 option

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.

-qmaxmem option

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 8192 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 8192 or higher, and decrease it if the compilation continues to require too much storage.

Notes:
  1. Reduced optimization does not necessarily mean that the resulting program will be slower. It only means that the compiler cannot finish looking for opportunities to improve performance.
  2. Increasing the limit does not necessarily mean that the resulting program will be faster. It only means that the compiler is better able to find opportunities to improve performance if they exist.
  3. Setting a large limit has no negative effect when compiling source files for which the compiler does not need to use so much memory during optimization.
  4. As an alternative to raising the memory limit, you can sometimes move the most complicated calculations into procedures that are then small enough to be fully analyzed.
  5. Not all memory-intensive compilation stages can be limited.
  6. Only the optimizations done for -O2 and -O3 can be limited; -O4 and -O5 optimizations cannot be limited.
  7. The -O4 and -O5 optimizations may also use a file in the /tmp directory. This is not limited by the -qmaxmem setting.
  8. Some optimizations back off automatically if they would exceed the maximum available address space, but not if they would exceed the paging space available at that time, which depends on machine workload.

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

-qmbcs option

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.

-qminimaltoc option

Syntax

-qminimaltoc | -qnominimaltoc

This compiler option can change the generation of the table of contents (TOC), which the compiler creates for every executable file when you compile in 64-bit mode. By default, the compiler will allocate at least one TOC entry for each unique, non-automatic variable reference in your program. Currently, only 8192 TOC entries are available and duplicate entries are not discarded. This can cause errors when linking large programs in 64-bit mode if your program exceeds 8192 TOC entries.

Specifying -qminimaltoc ensures that the compiler creates only one TOC entry for each compilation unit. Specifying this option can minimize the use of available TOC entries, but its use impacts performance. Use the -qminimaltoc option with discretion, particularly with files that contain frequently executed code.

-qmixed option

Syntax

-qmixed | -qnomixed
MIXED | NOMIXED

This is the long form of the -U option .

-qmoddir 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.

To read the .mod files from this directory when compiling files that reference the modules, use the -I option .

Related information

See XL Fortran Output files.

Modules are a Fortran 90/95 feature and are explained in the Modules section of the XL Fortran Language Reference.

-qmodule option

Syntax

-qmodule=mangle81

Specifies that the compiler should use the XL Fortran Version 8.1 naming convention for non-intrinsic module files.

This option allows you to produce modules and their associated object files with the Version 10.1 compiler and link these object files with others compiled with the Version 8.1 compiler.

Use this option only if you need to link applications that were compiled with the Version 8.1 compiler. It is recommended that you avoid using this compiler switch and rebuild old code and modules with the new version of the compiler, if possible. Doing so will avoid any naming conflicts between your modules and intrinsic compiler modules.

Related information

-qnoprint 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.

-qnullterm option

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.

-qobject option

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.

-qoldmod option

Syntax

-qoldmod=compat

This option specifies that object files containing module data compiled with versions of XL Fortran earlier than V9.1.1 either do not contain uninitialized module data or were ported using the convert_syms script.

The mangling scheme that XL Fortran uses for uninitialized module variables was changed with Version 9.1.1. The previous mangling scheme used the @ sign, which confused the Linux linker when creating shared libraries. The Linux linker reserves the @ sign for symbol versioning.

As a result of this change, XL Fortran modules containing uninitialized module variables and any compilation units using these modules need to be recompiled with the -qoldmod=compat option.

If recompilation is not feasible, you can port the object files created by older compilers by using the following script:

> cat convert_syms
#!/bin/bash
if [[ $# = 0 || "$1" = "-?" ]]
then
  echo "Usage: $0 object-files"
  echo "e.g.   $0 *.o *.a"
  exit
fi

for file in $*
do
  XLFSYMS=""
  for i in `nm $file | grep -o "&&\([NI]&\)\?@.*$" | sort -u`
  do
     XLFSYMS="$XLFSYMS --redefine-sym $i=`echo $i | sed -e 's/@/\&/'`"
  done
  if [[ -n "$XLFSYMS" ]]; then
    echo Converting symbols in $file...
    objcopy $XLFSYMS $file
  fi
done

Module symbol files (*.mod) do not need to be ported.

Examples

# If old_module.o and old_module.mod were produced using the original
# release of XL Fortran Advanced Edition V9.1 for Linux, you'll get
# the following error when you try to use them in new programs:
#
> xlf95 new_program.f old_module.o
"new_program.f", line 1.5: 1517-022 (S) Module old_module was compiled 
using an incompatible version of the compiler.  Please see the -qoldmod
option for information on recovery.
1501-511  Compilation failed for file new_program.f.

# Convert the object file.  This needs to be done only once.
#
> ./convert_syms old_module.o
>

# You can now use the updated object file safely.
# Specify -qoldmod=compat
#
> xlf95 new_program.f old_module.o -qoldmod=compat
** _main   === End of Compilation 1 ===
1501-510  Compilation successful for file new_program.f.
>

-qonetrip option

Syntax

-qonetrip | -qnoonetrip
ONETRIP | NOONETRIP

This is the long form of the -1 option.

-qoptimize option

Syntax

-qOPTimize[=level] | -qNOOPTimize
OPTimize[(level)] | NOOPTimize

This is the long form of the -O option .

-qpdf 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:

  1. Compile some or all of the source files in a program with the -qpdf1 option. You need to specify the -O2 option, or preferably the -O3, -O4, or -O5 option, for optimization. Pay special attention to the compiler options that you use to compile the files, because you will need to use the same options later.

    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.

    If you want to avoid full recompilation in the -qpdf2 step, first compile with -qpdf1 but with no linking, so that the object files are saved. Then link the object files into an executable. To use this procedure, issue commands similar to the following:

    xlf -c -qpdf1 -O2 file1.f file2.f 
    xlf -qpdf2 -O2 file1.o file2.o 
  2. Run the program all the way through using a typical data set. The program records profiling information when it finishes. You can run the program multiple times with different data sets, and the profiling information is accumulated to provide an accurate count of how often branches are taken and blocks of code are executed.
    Important:
    Use data that is representative of the data that will be used during a normal run of your finished program.
  3. Recompile and relink your program using the same compiler options as before, but change -qpdf1 to -qpdf2. Remember that -L, -l, and some others are linker options, and you can change them at this point. In this second compilation, the accumulated profiling information is used to fine-tune the optimizations. The resulting program contains no profiling overhead and runs at full speed.

    Alternatively, if you saved the object files from 1, you can simply relink them. For example, issue the following command:

    xlf -qpdf2 -O2 file1.o file2.o 

    This can save considerable time and help fine tune large applications for optimization. You can create and test different flavors of PDF optimized binaries by using different options on the -qpdf2 pass.

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 XL 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

The following commands, in the directory /opt/ibmcmp/xlf/10.1/bin, are available for managing the PDFDIR directory:

cleanpdf [pathname] Removes all profiling information from the pathname directory; or if pathname is not specified, from the PDFDIR directory; or if PDFDIR is not set, from the current directory.

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.

mergepdf Generates a single pdf record from 2 or more input pdf records. All pdf records must come from the same executable.

mergepdf automatically scales each pdf record (that is, file) based on its "weight". A scaling ratio can be specified for each pdf record, so that more important training runs can be weighted heavier than less important ones. The syntax for mergepdf is:

mergepdf [-r1] record1 [-r2] record2 ... -outputrecname [-n] [-v]

where:

-r
The scaling ratio for the pdf record. If -r is not specified for an input record, the default ratio is 1.0 and no external scaling is applied. The scaling ratio must be greater than or equal to zero, and can be a floating point number or an integer.
record
The input file, or the directory that contains the pdf profile.
-o output_recordname
The pdf output directory name, or a file name that mergepdf will write the merged pdf record to. If a directory is specified, it must exist before you run the command.
-n
Do not normalize the pdf records. By default, records are normalized based on an internally calculated ratio for each profile before applying any user-specified ratio with -r. When -n is specified, the pdf records are scaled by the user-specified ratio -r. If -r is not specified, the pdf records are not scaled at all.
-v
Verbose mode displays the internal and user-specified scaling ratio used.
resetpdf [pathname] Same as cleanpdf [pathname], described above. This command is provided for compatibility with the previous version.
showpdf Displays the call and block counts for all procedures executed in a program run. To use this command, you must first compile your application specifying both -qpdf1 and -qshowpdf compiler options

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 -O3 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 -qpdf2 -O3 file1.o file2.o file3.o file4.o

Here is an example that bypasses recompiling the source with -qpdf2:

# Set the PDFDIR variable.
  export PDFDIR=$HOME/project_dir
# Compile source with -qpdf1.
  xlf -O3 -qpdf1 -c file.f
# Link in object file.
  xlf -O3 -qpdf1 file.o
# Run with one set of input data.
  a.out <sample.data
# Link in object file from qpdf1 pass.
# (Bypass source recompilation with -qpdf2.)
  xlf -O3 -qpdf2 file.o

Here is an example of using pdf1 and pdf2 objects:

# Set the PDFDIR variable.
  export PDFDIR=$HOME/project_dir
# Compile source with -qpdf1.
  xlf -c -qpdf1 -O3 file1.f file2.f
# Link in object files.
  xlf -qpdf1 -O3 file1.o file2.o
# Run with one set of input data.
  a.out <sample.data
# Link in the mix of pdf1 and pdf2 objects.
  xlf -qpdf2 -O3 file1.o file2.o

Related information

-qphsinfo option

Syntax

-qphsinfo | -qnophsinfo
PHSINFO | NOPHSINFO

The -qphsinfo compiler option displays timing information on the terminal for each compiler phase.

The output takes the form number1/number2 for each phase where number1 represents the CPU time used by the compiler and number2 represents the total of the compiler time and the time that the CPU spends handling system calls.

Examples

To compile app.f, which consists of 3 compilation units, and report the time taken for each phase of the compilation, enter:

xlf90 app.f  -qphsinfo

The output will look similar to:

FORTRAN phase 1 ftphas1      TIME =  0.000 / 0.000
** m_module   === End of Compilation 1 ===
FORTRAN phase 1 ftphas1      TIME =  0.000 / 0.000
** testassign   === End of Compilation 2 ===
FORTRAN phase 1 ftphas1      TIME =  0.000 / 0.010
** dataassign   === End of Compilation 3 ===
HOT       - Phase Ends;   0.000/  0.000
HOT       - Phase Ends;   0.000/  0.000
HOT       - Phase Ends;   0.000/  0.000
W-TRANS   - Phase Ends;   0.000/  0.010
OPTIMIZ   - Phase Ends;   0.000/  0.000
REGALLO   - Phase Ends;   0.000/  0.000
AS        - Phase Ends;   0.000/  0.000
W-TRANS   - Phase Ends;   0.000/  0.000
OPTIMIZ   - Phase Ends;   0.000/  0.000
REGALLO   - Phase Ends;   0.000/  0.000
AS        - Phase Ends;   0.000/  0.000
W-TRANS   - Phase Ends;   0.000/  0.000
OPTIMIZ   - Phase Ends;   0.000/  0.000
REGALLO   - Phase Ends;   0.000/  0.000
AS        - Phase Ends;   0.000/  0.000
1501-510  Compilation successful for file app.f.

Each phase is invoked three times, corresponding to each compilation unit. FORTRAN represents front-end parsing and semantic analysis, HOT loop transformations, W-TRANS intermediate language translation, OPTIMIZ high-level optimization, REGALLO register allocation and low-level optimization, and AS final assembly.

Compile app.f at the -O4 optimization level with -qphsinfo specified:

xlf90 myprogram.f  -qphsinfo -O4

The following output results:

FORTRAN phase 1 ftphas1      TIME =  0.010 / 0.020
** m_module   === End of Compilation 1 ===
FORTRAN phase 1 ftphas1      TIME =  0.000 / 0.000
** testassign   === End of Compilation 2 ===
FORTRAN phase 1 ftphas1      TIME =  0.000 / 0.000
** dataassign   === End of Compilation 3 ===
HOT       - Phase Ends;   0.000/  0.000
HOT       - Phase Ends;   0.000/  0.000
HOT       - Phase Ends;   0.000/  0.000
IPA       - Phase Ends;   0.080/  0.100
1501-510  Compilation successful for file app.f.
IPA       - Phase Ends;   0.050/  0.070
W-TRANS   - Phase Ends;   0.010/  0.030
OPTIMIZ   - Phase Ends;   0.020/  0.020
REGALLO   - Phase Ends;   0.040/  0.040
AS        - Phase Ends;   0.000/  0.000

Note that during the IPA (interprocedural analysis) optimization phases, the program has resulted in one compilation unit; that is, all procedures have been inlined.

Related information

The compiler phases.

-qpic option

Syntax

-qpic[=small|large]| -qnopic (in 32-bit mode)
-qpic[=small|large]| -qnopic (in 64-bit mode)

The -qpic compiler option generates Position Independent Code (PIC) that can be used in shared libraries.

Arguments

small | large
The small suboption tells the compiler to assume that the size of the Global Offset Table be at most, 64K. The large suboption allows the size of the Global Offset Table to be larger than 64K. This suboption allows more addresses to be stored in the Global Offset Table. However, it does generate code that is usually larger than that generated by the small suboption.

In 64-bit mode, -qpic=small is the default.

-qnopic
The compiler does not generate Position Independent Code.

In 32-bit mode, -qnopic is the default.

Related information

For more information on linker options, refer to the man pages for the ld command.

-qport option

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

clogicals | noclogicals
If you specify this option, the compiler treats all non-zero integers that are used in logical expressions as TRUE. You must specify -qintlog for -qport=clogicals to take effect.

The -qport=clogicals option is useful when porting applications from other Fortran compilers that expect this behavior. However, it is unsafe to mix programs that use different settings for non-zero integers if they share or pass logical data between them. Data files already written with the default -qintlog setting will produce unexpected behavior if read with the -qport=clogicals option active.

hexint | nohexint
If you specify this option, typeless constant hexadecimal strings are converted to integers when passed as an actual argument to the INT intrinsic function. Typeless constant hexadecimal strings not passed as actual arguments to INT remain unaffected.
mod | nomod
Specifying this option relaxes existing constraints on the MOD intrinsic function, allowing two arguments of the same data type parameter to be of different kind type parameters. The result will be of the same type as the argument, but with the larger kind type parameter value.
nullarg | nonullarg
For an external or internal procedure reference, specifying this option causes the compiler to treat an empty argument, which is delimited by a left parenthesis and a comma, two commas, or a comma and a right parenthesis, as a null argument. This suboption has no effect if the argument list is empty.

Examples of empty arguments are:

call foo(,,z)

call foo(x,,z)

call foo(x,y,)

The following program includes a null argument.

Fortran program:
program nularg
real(4) res/0.0/
integer(4) rc
integer(4), external :: add
rc = add(%val(2), res, 3.14, 2.18,) ! The last argument is a
                                    ! null argument.
if (rc == 0) then
print *, "res = ", res
else
print *, "number of arguments is invalid."
endif
end program
C program:
int add(int a, float *res, float *b, float *c, float *d)
{
   int ret = 0;
   if (a == 2)
     *res = *b + *c;
   else if (a == 3)
     *res = (*b + *c + *d);
   else
     ret = 1;
   return (ret);
}
sce | nosce
By default, the compiler performs short circuit evaluation in selected logical expressions using XL Fortran rules. Specifying sce allows the compiler to use non-XL Fortran rules. The compiler will perform short circuit evaluation if the current rules allow it.
typestmt | notypestmt
The TYPE statement, which behaves in a manner similar to the PRINT statement, is supported whenever this option is specified.
typlssarg | notyplssarg
Converts all typeless constants to default integers if the constants are actual arguments to an intrinsic procedure whose associated dummy arguments are of integer type. Dummy arguments associated with typeless actual arguments of noninteger type remain unaffected by this option.

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 Language Reference for further information.

-qposition option

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.

The default setting depends on the I/O specifiers in the OPEN statement and on the compiler invocation command: -qposition=appendold for the xlf, xlf_r, and f77/fort77 commands and the defined Fortran 90 and Fortran 95 behaviors for the xlf90, xlf90_r, xlf95, xlf95_r, f90, and f95 commands.

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

-qprefetch option

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 Language Reference and The POWER4 Processor Introduction and Tuning Guide. To selectively control prefetch directives using trigger constants, see the -qdirective option.

-qqcount 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 Language Reference.

-qrealsize option

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 sizes2 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 Language Reference discusses kind type parameters.

-qrecur option

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.

-qreport option

Syntax

-qreport[={smplist | hotlist}...]
-qnoreport
REPORT[({SMPLIST | HOTLIST}...)] NOREPORT

Determines whether to produce transformation reports showing how the program is parallelized and how loops are optimized.

You can use the smplist suboption to debug or tune the performance of SMP programs by examining the low-level transformations. 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

smplist
Produces a pseudo-Fortran listing that shows how the program is parallelized. This listing is produced before loop and other optimizations are performed. It includes messages that point out places in the program that can be modified to be more efficient. This report will only be produced if the -qsmp option is in effect.
hotlist
Produces a pseudo-Fortran listing that shows how loops are transformed, to assist you in tuning the performance of all loops. This suboption is the default if you specify -qreport with no suboptions.

In addition, if you specify the -qreport=hotlist option when the -qsmp option is in effect, a pseudo-Fortran listing will be produced that shows the calls to the SMP runtime and the procedures created for parallel constructs.

Background information

The transformation listing is part of the compiler listing file.

Restrictions

Loop transformation and auto parallelization are 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 -qsmp orthe -qhot option to generate a loop transformation listing. You must specify the -qsmp option to generate a parallel transformation listing or parallel performance messages.

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 parallelization:

    xlf_r -qsmp -O3 -qhot -qreport=smplist needs_tuning.f

To produce a listing file that you can use to tune both parallelization and loop performance:

    xlf_r -qsmp -O3 -qhot -qreport=smplist:hotlist needs_tuning.f

To produce a listing file that you can use to tune only the performance of loops:

    xlf95_r -O3 -qhot -qreport=hotlist needs_tuning.f

Related information

See -qpdf option .

-qsaa option

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.

-qsave option

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/10.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 Language Reference for information on how this option affects the storage class of variables.

-qsaveopt option

Syntax

-qsaveopt | -qnosaveopt

Saves the command-line options used for compiling a source file, and other information, in the corresponding object file. The compilation must produce an object file for this option to take effect. Only one copy of the command-line options is saved, even though each object may contain multiple compilation units.

To list the options used, issue the strings -a command on the object file. The following is listed:

opt source_type invocation_used compilation_options

For example, if the object file is t.o, the strings -a t.o command may produce information similar to the following:

@(#) opt f /opt/ibmcmp/xlf/10.1/bin/xlf90 -qlist -qsaveopt t.f

where f identifies the source used as Fortran, /opt/ibmcmp/xlf/10.1/bin/xlf90 shows the invocation command used, and -qlist -qsaveopt shows the compilation options.

-qsclk option

Syntax

-qsclk[={centi | micro}]

Specifies the resolution that the SYSTEM_CLOCK intrinsic procedure uses in a program. The default is centisecond resolution (-qsclk=centi). To use microsecond resolution, specify -qsclk=micro.

Related information

See SYSTEM_CLOCK in the XL Fortran Language Reference for more information on returning integer data from a real-time clock.

-qshowpdf option

Syntax

-qshowpdf | -qnoshowpdf

Used together with -qpdf1 and a minimum optimization level of -O to add additional call and block count profiling information to an executable.

When specified together with -qpdf1, the compiler inserts additional profiling information into the compiled application to collect call and block counts for all procedures in the application. Running the compiled application will record the call and block counts to the ._pdf file.

After you run your application with training data, you can retrieve the contents of the ._pdf file with the showpdf utility. This utility is described in -qpdf option .

-qsigtrap option

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. To show more detailed information in the tracebacks generated by the trap handlers provided by XL Fortran (such as xl__trce), specify the -qlinedebug or -g option.

Related information

-qsmallstack option

Syntax

-qsmallstack[=[no]dynlenonheap]
 | -qnosmallstack

Specifies that the compiler will minimize stack usage where possible.

This compiler option controls two distinct, but related sets of transformations: general small stack transformations and dynamic length variable allocation transformations. These two kinds of transformations can be controlled independently of each other.

The default, -qnosmallstack, implies that all suboptions are off.

The -qsmallstack=dynlenonheap suboption affects automatic objects that have nonconstant character lengths or a nonconstant array bound (DYNamic LENgth ON HEAP). When specified, those automatic variables are allocated on the heap. When this suboption is not specified, those automatic variables are allocated on the stack.

Using this option may adversely affect program performance; it should be used only for programs that allocate large amounts of data on the stack.

Rules

Related information

-qsmp option

Syntax

-qsmp[=suboptions]
-qnosmp

Indicates that code should be produced for an SMP system. The default is to produce code for a uniprocessor machine. When you specify this option, the compiler recognizes all directives with the trigger constants SMP$, $OMP, and IBMP (unless you specify the omp suboption).

Only the xlf_r, xlf90_r, and xlf95_r invocation commands automatically link in all of the thread-safe components. You can use the -qsmp option with the xlf, xlf90, xlf95, f77, and fort77 invocation commands, but you are responsible for linking in the appropriate components. . If you use the -qsmp option to compile any source file in a program, then you must specify the -qsmp option at link time as well, unless you link by using the ld command.

Arguments

auto | noauto
This suboption controls automatic parallelization. By default, the compiler will attempt to parallelize explicitly coded DO loops as well as those that are generated by the compiler for array language. If you specify the suboption noauto, automatic parallelization is turned off, and only constructs that are marked with prescriptive directives are parallelized. If the compiler encounters the omp suboption and the -qsmp or -qsmp=auto suboptions are not explicitly specified on the command line, the noauto suboption is implied. Also, note that -qsmp=noopt implies -qsmp=noauto. No automatic parallelization occurs under -qsmp=noopt; only user-directed parallelization will occur.
nested_par | nonested_par
If you specify the nested_par suboption, the compiler parallelizes prescriptive nested parallel constructs (PARALLEL DO, PARALLEL SECTIONS). This includes not only the loop constructs that are nested within a scoping unit but also parallel constructs in subprograms that are referenced (directly or indirectly) from within other parallel constructs. By default, the compiler serializes a nested parallel construct. Note that this option has no effect on loops that are automatically parallelized. In this case, at most one loop in a loop nest (in a scoping unit) will be parallelized.

Note that the implementation of the nested_par suboption does not comply with the OpenMP API. If you specify this suboption, the run-time library uses the same threads for the nested PARALLEL DO and PARALLEL SECTIONS constructs that it used for the enclosing PARALLEL constructs.

omp | noomp
If you specify -qsmp=omp, the compiler enforces compliance with the OpenMP API. Specifying this option has the following effects:
  • Automatic parallelization is turned off.
  • All previously recognized directive triggers are ignored.
  • The -qcclines compiler option is turned on if you specify -qsmp=omp.
  • The -qcclines compiler option is not turned on if you specify -qnocclines and -qsmp=omp.
  • The only recognized directive trigger is $OMP. However, you can specify additional triggers on subsequent -qdirective options.
  • The compiler issues warning messages if your code contains any language constructs that do not conform to the OpenMP API.

Specifying this option when the C preprocessor is invoked also defines the _OPENMP C preprocessor macro automatically, with the value 200505, which is useful in supporting conditional compilation. This macro is only defined when the C preprocessor is invoked.

See Conditional Compilation in the Language Elements section of the XL Fortran Language Reference for more information.

opt | noopt
If the -qsmp=noopt suboption is specified, the compiler will do the smallest amount of optimization that is required to parallelize the code. This is useful for debugging because -qsmp enables the -O2 and -qhot options by default, which may result in the movement of some variables into registers that are inaccessible to the debugger. However, if the -qsmp=noopt and -g options are specified, these variables will remain visible to the debugger.
rec_locks | norec_locks
This suboption specifies whether recursive locks are used to avoid problems associated with CRITICAL constructs. If you specify the rec_locks suboption, a thread can enter a CRITICAL construct from within the dynamic extent of another CRITICAL construct that has the same name. If you specify norec_locks, a deadlock would occur in such a situation.

The default is norec_locks, or regular locks.

schedule=option
The schedule suboption can take any one of the following subsuboptions:
affinity[=n]
The iterations of a loop are initially divided into number_of_threads partitions, containing CEILING(number_of_iterations / number_of_threads) iterations. Each partition is initially assigned to a thread and is then further subdivided into chunks that each contain n iterations. If n has not been specified, then the chunks consist of CEILING(number_of_iterations_left_in_partition / 2) loop iterations.

When a thread becomes free, it takes the next chunk from its initially assigned partition. If there are no more chunks in that partition, then the thread takes the next available chunk from a partition initially assigned to another thread.

The work in a partition initially assigned to a sleeping thread will be completed by threads that are active.

dynamic[=n]
The iterations of a loop are divided into chunks containing n iterations each. If n has not been specified, then the chunks consist of CEILING(number_of_iterations / number_of_threads) iterations.

Active threads are assigned these chunks on a "first-come, first-do" basis. Chunks of the remaining work are assigned to available threads until all work has been assigned.

If a thread is asleep, its assigned work will be taken over by an active thread once that thread becomes available.

guided[=n]
The iterations of a loop are divided into progressively smaller chunks until a minimum chunk size of n loop iterations is reached. If n has not been specified, the default value for n is 1 iteration.

The first chunk contains CEILING(number_of_iterations / number_of_threads) iterations. Subsequent chunks consist of CEILING(number_of_iterations_left / number_of_threads) iterations. Active threads are assigned chunks on a "first-come, first-do" basis.

runtime
Specifies that the chunking algorithm will be determined at run time.
static[=n]
The iterations of a loop are divided into chunks containing n iterations each. Each thread is assigned chunks in a "round-robin" fashion. This is known as block cyclic scheduling. If the value of n is 1, then the scheduling type is specifically referred to as cyclic scheduling.

If you have not specified n, the chunks will contain CEILING(number_of_iterations / number_of_threads) iterations. Each thread is assigned one of these chunks. This is known as block scheduling.

If a thread is asleep and it has been assigned work, it will be awakened so that it may complete its work.

For more information on chunking algorithms and SCHEDULE, refer to the Directives section in the XL Fortran Language Reference.

threshold=n
Controls the amount of automatic loop parallelization that occurs. The value of n represents the lower limit allowed for parallelization of a loop, based on the level of "work" present in a loop. Currently, the calculation of "work" is weighted heavily by the number of iterations in the loop. In general, the higher the value specified for n, the fewer loops are parallelized. If this suboption is not specified, the program will use the default value n=100.

Rules

Restrictions

The -qsmp=noopt suboption may affect the performance of the program.

Within the same -qsmp specification, you cannot specify the omp suboption before or after certain suboptions. The compiler issues warning messages if you attempt to specify them with omp:

auto
This suboption controls automatic parallelization, but omp turns off automatic parallelization.
nested_par
Note that the implementation of the nested_par suboption does not comply with the OpenMP API. If you specify this suboption, the run-time library uses the same threads for the nested PARALLEL DO and PARALLEL SECTIONS constructs that it used for the enclosing PARALLEL constructs.
rec_locks
This suboption specifies a behavior for CRITICAL constructs that is inconsistent with the OpenMP API.
schedule=affinity=n
The affinity scheduling type does not appear in the OpenMP API standard.

Examples

The -qsmp=noopt suboption overrides performance optimization options anywhere on the command line unless -qsmp appears after -qsmp=noopt. The following examples illustrate that all optimization options that appear after -qsmp=noopt are processed according to the normal rules of scope and precedence.

Example 1

     xlf90 -qsmp=noopt -O3...
is equivalent to
     xlf90 -qsmp=noopt...
   

Example 2

     xlf90 -qsmp=noopt -O3 -qsmp...
is equivalent to
     xlf90 -qsmp -O3...
   

Example 3

     xlf90 -qsmp=noopt -O3 -qhot -qsmp -O2...
is equivalent to
     xlf90 -qsmp -qhot -O2...
   

If you specify the following, the compiler recognizes both the $OMP and SMP$ directive triggers and issues a warning if a directive specified with either trigger is not allowed in OpenMP.

-qsmp=omp -qdirective=SMP$

If you specify the following, the noauto suboption is used. The compiler issues a warning message and ignores the auto suboption.

-qsmp=omp:auto

In the following example, you should specify -qsmp=rec_locks to avoid a deadlock caused by CRITICAL constructs.

   program t
     integer  i, a, b

     a = 0
     b = 0
!smp$ parallel do
     do i=1, 10
!smp$ critical
     a = a + 1
!smp$ critical
     b = b + 1
!smp$ end critical
!smp$ end critical
     enddo
   end

Related information

If you use the xlf, xlf_r, f77, or fort77 command with the -qsmp option to compile programs, specify -qnosave to make the default storage class automatic, and specify -qthreaded to tell the compiler to generate thread-safe code.

-qsource option

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.

-qspillsize option

Syntax

-qspillsize=bytes
SPILLSIZE(bytes)

-qspillsize is the long form of -NS. See -NS option .

-qstacktemp option

Syntax

-qstacktemp={0 | -1 | positive signed integer value}
STACKTEMP={0 | -1 | positive signed integer value}

Determines where to allocate applicable XL Fortran compiler temporaries at run time.

Applicable compiler temporaries are the set of temporary variables created by the compiler for its own use when it determines it can safely apply these. Most typically, the compiler creates these kinds of temporaries to hold copies of XL Fortran arrays for array language semantics, especially in conjunction with calls to intrinsic functions or user subprograms. If you have programs that make use of large arrays, you may need to use this option to help prevent stack space overflow when running them. For example, for SMP or OpenMP applications that are constrained by stack space, you can use this option to move some compiler temporaries onto the heap from the stack.

The compiler cannot detect whether or not the stack limits will be exceeded when an application runs. You will need to experiment with several settings before finding the one that works for your application. To override an existing setting, you must specify a new setting.

Note:
The -qstacktemp option can take precedence over the -qsmallstack option for certain compiler-generated temporaries.

Arguments

The possible suboptions are:

0
Based on the target environment, the compiler determines whether it will allocate applicable temporaries on the heap or the stack. If this setting causes your program to run out of stack storage, try specifying a nonzero value instead, or try using the -qsmallstack option.
-1
Allocates applicable temporaries on the stack. Generally, this is the best performing setting but uses the most amount of stack storage.
positive signed integer value
Allocates applicable temporaries less than this value on the stack and those greater than or equal to this value on the heap. A value of 1 Mb has been shown to be a good compromise between stack storage and performance for many programs, but you may need to adjust this number based on your application's characteristics.

-qstrict option

Syntax

-qstrict | -qnostrict
STRICT | NOSTRICT

Ensures that optimizations done by default with the -O3, -O4, and -O5 options, and optionally with the -O2 option, do not alter the semantics of a program.

Defaults

For -O3, -O4, and -O5, 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 .

-qstrictieeemod option

Syntax

-qstrictieeemod | -qnostrictieeemod
STRICTIEEEMOD | NOSTRICTIEEEMOD

Specifies whether the compiler will adhere to the Fortran 2003 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.

-qstrict_induction option

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.

-qsuffix option

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

f=suffix
Where suffix represents the new source-file-suffix
o=suffix
Where suffix represents the new object-file-suffix
s=suffix
Where suffix represents the new assembler-source-file-suffix
cpp=suffix
Where suffix represents the new preprocessor-source-file-suffix

Rules

Examples

For instance,

     xlf a1.f2k a2.F2K -qsuffix=f=f2k:cpp=F2K

will cause these effects:

-qsuppress option

Syntax

-qsuppress[=nnnn-mmm[:nnnn-mmm ...] | cmpmsg]
-qnosuppress

Arguments

nnnn-mmm[:nnnn-mmm ...]
Suppresses the display of a specific compiler message (nnnn-mmm) or a list of messages (nnnn-mmm[:nnnn-mmm ...]). nnnn-mmm is the message number. To suppress a list of messages, separate each message number with a colon.
cmpmsg
Suppresses the informational messages that report compilation progress and a successful completion.

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 .

-qswapomp option

Syntax

-qswapomp | -qnoswapomp
SWAPOMP | NOSWAPOMP

Specifies that the compiler should recognize and substitute OpenMP routines in XL Fortran programs.

The OpenMP routines for Fortran and C have different interfaces. To support multi-language applications that use OpenMP routines, the compiler needs to recognize OpenMP routine names and substitute them with the XL Fortran versions of these routines, regardless of the existence of other implementations of such routines.

The compiler does not perform substitution of OpenMP routines when you specify the -qnoswapomp option.

Restrictions

The -qswapomp and -qnoswapomp options only affect Fortran sub-programs that reference OpenMP routines that exist in the program.

Rules

Examples

In the following example, the OpenMP routines are declared in an INTERFACE statement.

@PROCESS SWAPOMP

         INTERFACE
            FUNCTION OMP_GET_THREAD_NUM()
                INTEGER OMP_GET_THREAD_NUM
            END FUNCTION OMP_GET_THREAD_NUM

            FUNCTION OMP_GET_NUM_THREADS()
                INTEGER OMP_GET_NUM_THREADS
            END FUNCTION OMP_GET_NUM_THREADS
         END INTERFACE

         IAM = OMP_GET_THREAD_NUM()
         NP = OMP_GET_NUM_THREADS()
         PRINT *, IAM, NP
         END

Related information

See the OpenMP Execution Environment Routines and Lock Routines section in the XL Fortran Language Reference.

-qtbtable option

Syntax

-qtbtable={none | small | full}
Note:
Applies to the 64-bit environment only.

Limits the amount of debugging traceback information in object files, which reduces the size of the program.

You can use this option to make your program smaller, at the cost of making it harder to debug. When you reach the production stage and want to produce a program that is as compact as possible, you can specify -qtbtable=none. Otherwise, the usual defaults apply: code compiled with -g or without -O has full traceback information (-qtbtable=full), and code compiled with -O contains less (-qtbtable=small).

Arguments

none
The object code contains no traceback information at all. You cannot debug the program, because a debugger or other code-examination tool cannot unwind the program's stack at run time. If the program stops because of a run-time exception, it does not explain where the exception occurred.
small
The object code contains traceback information but not the names of procedures or information about procedure parameters. You can debug the program, but some non-essential information is unavailable to the debugger. If the program stops because of a run-time exception, it explains where the exception occurred but reports machine addresses rather than procedure names.
full
The object code contains full traceback information. The program is debuggable, and if it stops because of a run-time exception, it produces a traceback listing that includes the names of all procedures in the call chain.

Background information

This option is most suitable for programs that contain many long procedure names, such as the internal names constructed for module procedures. You may find it more applicable to C++ programs than to Fortran programs.

Related information

-qthreaded 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. Specifying these options ensures that variables and code created by the compiler are threadsafe; it does not guarantee the thread safety of user-written code. If you use the ENTRY statement to have an alternate entry point for a subprogram and the xlf_r command to compile, also specify the -qxlf77=nopersistent option to be thread-safe. You should implement the appropriate locking mechanisms, as well.

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.

-qtune option

Syntax

-qtune=implementation

Tunes instruction selection, scheduling, and other implementation-dependent performance enhancements for a specific implementation of a hardware architecture. The compiler will use a -qtune setting that is compatible with the target architecture, which is controlled by the -qarch, -q32, and -q64 options.

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.

Arguments

The choices are:

auto
Automatically detects the specific processor type of the compiling machine. It assumes that the execution environment will be the same as the compilation environment.
rs64b
The optimizations are tuned for the RS64II processor.
rs64c
The optimizations are tuned for the RS64III processor.
pwr3
The optimizations are tuned for the POWER3 processors.
pwr4
The optimizations are tuned for the POWER4 processors.
pwr5
The optimizations are tuned for the POWER5 processors.
ppc970
The optimizations are tuned for the PowerPC 970 processors.

If you do not specify -qtune, its setting is determined by the setting of the -qarch option, as follows:

-qarch Setting Allowed -qtune Settings Default -qtune Setting
ppc
See the list of acceptable -qtune settings under the -qarch=ppc64 entry.
pwr4
ppcgr
See the list of acceptable -qtune settings under the -qarch=ppc64gr entry.
pwr4
ppc64 rs64b, rs64c, pwr3, pwr4, pwr5, ppc970, auto pwr4
ppc64gr rs64b, rs64c, pwr3, pwr4, pwr5, ppc970, auto pwr4
ppc64grsq rs64b, rs64c, pwr3, pwr4, pwr5, ppc970, auto pwr4
rs64b rs64b, auto rs64b
rs64c rs64c, auto rs64c
pwr3 pwr3, pwr4, pwr5, ppc970, auto pwr3
pwr4 pwr4, pwr5, ppc970, auto pwr4
pwr5 pwr5, auto pwr5
pwr5x pwr5, auto pwr5
ppc970 ppc970, auto ppc970

Note that you can specify any -qtune suboption with -qarch=auto as long as you are compiling on a machine that is compatible with the -qtune suboption. For example, if you specify -qarch=auto and -qtune=pwr5, you must compile on a POWER3, POWER4, or POWER5 machine.

Related information

-qundef option

Syntax

-qundef | -qnoundef
UNDEF | NOUNDEF

-qundef is the long form of the -u option .

-qunroll option

Syntax

-qunroll[=auto | yes] | -qnounroll

Specifies whether unrolling DO loops is allowed in a program. Unrolling is allowed on outer and inner DO loops.

Arguments

auto
The compiler performs basic loop unrolling. This is the default if -qunroll is not specified on the command line.
yes
The compiler looks for more opportunities to perform loop unrolling than that performed with -qunroll=auto. Specifying -qunroll with no suboptions is equivalent to -qunroll=yes. In general, this suboption has more chances to increase compile time or program size than -qunroll=auto processing, but it may also improve your application's performance.

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:

See Benefits of High Order Transformation.

-qunwind option

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. This rearrangement may make it impossible for the program or debuggers to walk through or "unwind" subprogram stack frame chains.

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.

-qversion option

Syntax

-qversion | -qnoversion

Displays the version and release of the compiler being invoked.

Specify this option on its own with the compiler command. For example:

xlf90 -qversion

-qwarn64 option

Syntax

-qwarn64 | -qnowarn64

Aids in porting code from a 32-bit environment to a 64-bit environment by detecting the truncation of an 8-byte integer pointer to 4 bytes. The -qwarn64 option uses informational messages to identify statements that may cause problems with the 32-bit to 64-bit migration.

Rules

Related information

-qxflag=dvz option

Syntax

-qxflag=dvz

Specifying -qxflag=dvz causes the compiler to generate code to detect floating-point divide-by-zero operations.

This option is only effective when you specify an optimization level of -O or higher.

With this option on, the extra code calls the external handler function __xl_dzx when the divisor is zero. The return value of this function is used as the result of the division. Users are required to provide the function to handle the divide-by-zero operations. Specifying -qxflag=dvz handles only single-precision (REAL*4) and double-precision (REAL*8) division.

The interface of the function is as follows:

 real(8) function __xl_dzx(x, y, kind_type)
   real(8), value :: x, y
   integer, value :: kind_type
 end function

where:

x
is the dividend value
y
is the divisor value
kind_type
specifies the size of the actual arguments associated with x and y.

A kind_type value equal to zero indicates that the actual arguments associated with x and y are of type REAL(8). A kind_type value equal to one indicates that the actual arguments associated with x and y are of type REAL(4).

The division always executes before the handler routine is called. This means that any exception is posted and handled before the handler function is called.

Related information

-qxflag=oldtab option

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.

-qxlf77 option

Syntax

-qxlf77=settings
XLF77(settings)

Provides compatibility with FORTRAN 77 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, xlf90_r, f90, and f95 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, xlf95_r, f90, or f95 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.

blankpad | noblankpad
For internal, direct-access, and stream-access files, uses a default setting equivalent to pad='no'. This setting produces conversion errors when reading from such a file if the format requires more characters than the record has. This suboption does not affect direct-access or stream-access files opened with a pad= specifier.
gedit77 | nogedit77
Uses FORTRAN 77 semantics for the output of REAL objects with the G edit descriptor. Between FORTRAN 77 and Fortran 90, the representation of 0 for a list item in a formatted output statement changed, as did the rounding method, leading to different output for some combinations of values and G edit descriptors.
intarg | nointarg
Converts all integer arguments of an intrinsic procedure to the kind of the longest argument if they are of different kinds. Under Fortran 90/95 rules, some intrinsics (for example, IBSET) determine the result type based on the kind of the first argument; others (for example, MIN and MAX) require that all arguments be of the same kind.
intxor | nointxor
Treats .XOR. as a logical binary intrinsic operator. It has a precedence equivalent to the .EQV. and .NEQV. operators and can be extended with an operator interface. (Because the semantics of .XOR. are identical to those of .NEQV., .XOR. does not appear in the Fortran 90 or Fortran 95 language standard.)

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.

leadzero | noleadzero
Produces a leading zero in real output under the D, E, L, F, and Q edit descriptors.
oldboz | nooldboz
Turns blanks into zeros for data read by B, O, and Z edit descriptors, regardless of the BLANK= specifier or any BN or BZ control edit descriptors. It also preserves leading zeros and truncation of too-long output, which is not part of the Fortran 90 or Fortran 95 standard.
persistent | nopersistent
Saves the addresses of arguments to subprograms with ENTRY statements in static storage. This is an implementation choice that has been changed for increased performance.
softeof | nosofteof
Allows READ and WRITE operations when a unit is positioned after its endfile record unless that position is the result of executing an ENDFILE statement. This suboption reproduces a FORTRAN 77 extension of earlier versions of XL Fortran that some existing programs rely on.

-qxlf90 option

Syntax

-qxlf90={settings}
XLF90({settings})

Provides compatibility with 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 f95, xlf95 or xlf95_r command, the default suboptions are signedzero and autodealloc. For all other invocation commands, the defaults are nosignedzero and noautodealloc.

Arguments

signedzero | nosignedzero
Determines how the SIGN(A,B) function handles signed real 0.0.If you specify the -qxlf90=signedzero compiler option, SIGN(A,B) returns -|A| when B=-0.0. This behavior conforms to the Fortran 95 standard and is consistent with the IEEE standard for binary floating-point arithmetic. Note that for the REAL(16) data type, XL Fortran never treats zero as negative zero.

This suboption also determines whether a minus sign is printed in the following cases:

  • For a negative zero in formatted output. Again, note that for the REAL(16) data type, XL Fortran never treats zero as negative zero.
  • For negative values that have an output form of zero (that is, where trailing non-zero digits are truncated from the output so that the resulting output looks like zero). Note that in this case, the signedzero suboption does affect the REAL(16) data type; non-zero negative values that have an output form of zero will be printed with a minus sign.
autodealloc | noautodealloc
Determines whether the compiler deallocates allocatable objects that are declared locally without either the SAVE or the STATIC attribute and have a status of currently allocated when the subprogram terminates. This behavior conforms with the Fortran 95 standard. If you are certain that you are deallocating all local allocatable objects explicitly, you may wish to turn off this suboption to avoid possible performance degradation.

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 SIGN information in the Intrinsic Procedures section and the Arrays Concepts section of the XL Fortran Language Reference.

-qxlines option

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.

The OMP conditional compilation characters '!$', 'C$', and '*$' may be mixed with the conditional characters 'x' and 'd' both in fixed source form and within a continued source line. The rules for OMP conditional characters will still apply in this instance.

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 Language Reference.

-qxref option

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.

-qzerosize option

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, xlf95_r, f90, and f95 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.

-S option

Syntax

-S

Produces one or more .s files that show equivalent assembler source for each Fortran source file.

Rules

When this option is specified, the compiler produces the assembler source files as output instead of an object or an executable file.

Restrictions

The generated assembler files do not include all the data that is included in a .o file by -qipa or -g.

Examples

xlf95 -O3 -qhot -S test.f               # Produces test.s

Related information

The -o option can be used to specify a name for the resulting assembler source file.

For information about the assembler-language format, see the Assembler Language Reference.

-t option

Syntax

-tcomponents

Applies the prefix specified by the -B option to the designated components. components can be one or more of a, F, c, h, I, b, z, l, or d with no separators, corresponding to the assembler, the C preprocessor, the compiler, the array language optimizer, the interprocedural analysis (IPA) tool/loop optimizer, the code generator, the binder, the linker, and the -S disassembler, respectively.

Rules

If -t is not specified, any -B prefix is applied to all components.

Component                -t              Standard Program Name
                          Mnemonic
 

assembler                 a              as
C preprocessor            F              cpp
compiler front end        c              xlfentry
array language optimizer  h              xlfhot
IPA/loop optimizer        I              ipa
code generator            b              xlfcode
binder                    z              bolt
linker                    l              ld
disassembler              d              dis

Related information

See -B option (which includes an example).

-U option

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 .

-u 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 Language Reference.

This is the short form of -qundef. See -qundef option .

-v 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.

-V option

Syntax

-V

This option is the same as -v except that you can cut and paste directly from the display to create a command.

-W option

Syntax

-Wcomponent,options

Passes the listed options to a component that is executed during compilation. component is one of a, F, c, h, I, b, z, l, or d, corresponding to the assembler, the C preprocessor, the compiler, the array language optimizer, the interprocedural analysis (IPA) tool/loop optimizer, the code generator, the binder, the linker, and the -S disassembler, respectively.

Component                -W              Standard Program Name
                          Mnemonic
 

assembler                 a              as
C preprocessor            F              cpp
compiler front end        c              xlfentry
array language optimizer  h              xlfhot
IPA/loop optimizer        I              ipa
code generator            b              xlfcode
binder                    z              bolt
linker                    l              ld
disassembler              d              dis

In the string following the -W option, use a comma as the separator for each option, and do not include any spaces. For example:

-Wcomponent,option_1[,option_2,...,option_n]

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. Only linker options with the same letters as compiler options, such as -v or -S, strictly require -W (or the ldopts stanza in the configuration file).

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.

You can use \, to embed a literal comma in the string supplied to the -W option.

In the following example, the \, embeds a literal comma in the -WF string and causes three arguments, rather than four, to be supplied to the C preprocessor.

  $ xlf -qfree=f90  '-WF,-Dint1=1,-Dint2=2,-Dlist=3\,4'  a.F
  $ cat a.F
  print *, int1
  print *, int2
  print *, list
  end

The output from the program will be:

$ ./a.out
 1
 2
 3 4

-w option

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.

-y option

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

n
Round to nearest.
m
Round toward minus infinity.
p
Round toward plus infinity.
z
Round toward zero.

Related information

See -O option and -qfloat option .

-y is the short form of -qieee option .


1.
In Fortran 90/95 terminology, these values are referred to as kind type parameters.
2.
In Fortran 90/95 terminology, these values are referred to as kind type parameters.