IBM Support

Documentation errata for IBM XL Fortran for Linux, V13.1

Preventive Service Planning


Abstract

This page contains corrections and additions to the product documentation shipped with IBM XL Fortran for Linux, V13.1.

Content

Getting Started
The following corrections and additions apply to the IBM XL Fortran for Linux 13.1 Getting Started:

Topic location: What's new for IBM XL Fortan for Linux 13.1 > Performance and optimization

The three new -qpdf suboptions are:

level
Supports multiple-pass profiling, block counter profiling, call counter profiling, and extended value profiling. You can compile your application with -qpdf1=level=0|1|2 to generate profiling data with different levels of optimization.

Should read:

These new suboptions are as follows:

level
Supports multiple-pass profiling, single-pass profiling, cache-miss profiling, value profiling, block-counter profiling, and call-counter profiling. You can compile your program with -qpdf1=level=0|1|2 to specify the type of profiling information to be generated by the resulting application.


Installation Guide
The following corrections and additions apply to the IBM XL Fortran for Linux 13.1 Installation Guide:

Topic location: After installing IBM XL Fortran for Linux 13.1 > Accessing the local documentation > Viewing the HTML documentation

This information center can be installed on any RHEL 5.5 or SLES 10 SP2 system.

Should read:

This information center can be installed on any supported operating systems of XL Fortran for Linux 13.1.


Language Reference
The following corrections and additions apply to the IBM XL Fortran for Linux 13.1 Language Reference:

Topic location: Program units and procedures > Scope > The scope of a name > Local entity

If two local entities of class 1, one of which is a derived type, are accessible in a scoping unit, any PUBLIC or PRIVATE statement that specifies the name of the entities applies to both entities.

Should read:

If two local entities of class 1, one of which is a derived type, have the same name identifier and are accessible in a scoping unit, any PUBLIC or PRIVATE statement that specifies the name of the entities applies to both entities. The PUBLIC or PRIVATE attribute that is specified in the derived type declaration statement also applies to both entities.


Topic location: Directives (IBM extension) > Directives and optimization > Assertive directives

EXPECTED_VALUE should be added.


Topic location: Detailed directive descriptions

The following topic should be added:

EXPECTED_VALUE

Purpose
Specifies the value that a dummy argument is most likely to have at run time. The compiler can use this information to perform certain optimizations, such as procedure cloning and inlining.

Syntax
>>-EXPECTED_VALUE--(--argument--,--value--)--------------------><

argument

    The name of the dummy argument for which you want to provide the expected value. The dummy argument must be a scalar of REAL, INTEGER, LOGICAL, or BYTE type. It must not have the ALLOCATABLE or POINTER attribute.

value
    An initialization expression representing the value that the dummy argument is most likely to take at run time.

Rules
Use the EXPECTED_VALUE directive only in the specification part of a procedure. Do not use more than one EXPECTED_VALUE directive for a dummy argument.

Examples
In the following example, the EXPECTED_VALUE directives indicate to the compiler that the most likely value is 1 for a, and 0 for b.

integer function func(a, b)
    integer a, b
    !IBM* EXPECTED_VALUE(a, 1)
    !IBM* EXPECTED_VALUE(b, 0)
    ...
end function func


Topic location: Hardware-specific directives > PREFETCH > PROTECTED_UNLIMITED_STREAM_SET_GO

The notes under both syntax diagrams:

Note: Valid for PowerPC 970 and POWER5 processors.

Should read:

Note: Valid for PowerPC 970 and POWER5 processors or higher.

stream_id
is the ID for the prefetched stream. It must be scalar and of type integer. For POWER5 processors, it can be any number from 0 to 7.

Should read:

stream_id
is the ID for the prefetched stream. It must be scalar and of type integer. For PowerPC 970 and POWER5 processors, it can be any number from 0 to 7. For POWER6 processors, it can be any number from 0 to 15. For POWER7 processors, it can be any number from 0 to 11.


Topic location: Intrinsic procedures > MOD(A, P)

Specific NameArgument TypeResult TypePass As Arg?
MODany integersame as argumentyes

Should read:

Specific NameArgument TypeResult TypePass As Arg?
MODdefault integerdefault integeryes


Topic location: Vector intrinsic procedures (IBM extension) > VEC_PROMOTE(ARG1, ARG2)

ARG2
    An INTENT(IN) integer vector

Should read:

ARG2
    An INTENT(IN) integer


Compiler Reference
The following corrections and additions apply to the IBM XL Fortran for Linux 13.1 Compiler Reference:

Topic location: Setting up and customizing XL Fortran > Correct settings for environment variables > PDF environment variables

The following variable should be added:

PDF_PM_EVENT:
When you run an application compiled with -qpdf1=level=2, you can set the value of the environment variable PDF_PM_EVENT to L1MISS, L2MISS or L3MISS to gather cache-miss profiling information at the specified cache level.

Store the profiling information for each application in a different directory, or use the -qpdf1=pdfname, -qpdf2=pdfname option to explicitly name the temporary profiling files according to the template provided.

Should read:

Store the profiling information for each application in a different directory, or use the -qpdf1=pdfname, -qpdf1=exename option to explicitly name the temporary profiling files according to the template provided.

Topic location: Editing, compiling, linking, and running XL Fortran programs > Compiling XL Fortran programs

In the XL Fortran Invocation commandstable, the following rows:

Driver Invocation
Path or Location
Chief Functionality
Linked Libraries
xlf/opt/ibmcmp/xlf/13.1/bin FORTRAN 77libxlf90.so
xlf_r/opt/ibmcmp/xlf/13.1/bin Threadsafe FORTRAN 77libxlf90_r.so

Should read:

Driver Invocation
Path or Location
Chief Functionality
Linked Libraries
xlf/opt/ibmcmp/xlf/13.1/bin Selected Fortran language level libxlf90.so
xlf_r/opt/ibmcmp/xlf/13.1/bin The threadsafe version of the selected language levellibxlf90_r.so

Topic location: Detailed descriptions of the XL Fortran compiler options > -O

The following statement should be added under "Usage":

If optimization level -O3 or higher is specified on the command line, the -qhot and -qipa options that are set by the optimization level cannot be overridden by @PROCESS OPT(0) or @PROCESS OPT(2).


Topic location: Detailed descriptions of the XL Fortran compiler options > -qpdf1, -qpdf2

Syntax should read:

.-nopdf2-----------------------------.   
        +-nopdf1-----------------------------+   
>>- -q--+-pdf1--+--------------------------+-+-----------------><
        |       +-=--pdfname--=--
file_path-+ |   
        |       +-=--exename---------------+ |   
        |       +-=--defname---------------+ |   
        |       '-=--level--=--
0--1--2-----' |   
        '-pdf2--+--------------------------+-'   
                +-=--pdfname--=--
file_path-+     
                +-=--exename---------------+     
                '-=--defname---------------'


level=0 | 1 | 2 should read:

level=0 | 1 | 2

Specifies different levels of profiling information to be generated by the resulting application. The following table provides information about the type of profiling supported on each level (The symbol + indicates that the profiling type is supported):

Profiling type supported on each -qpdf1 level

Profiling type
Level
0
1
2
block-counter profiling
+
+
+
call-counter profiling
+
+
+
single-pass profiling
+
+

value profiling
+
+
multiple-pass profiling

+
cache-miss profiling

+
  • -qpdf1=level=0 is the basic compiler instrumentation that results in smaller file size and faster compilation than -qpdf1=level=1.
  • -qpdf1=level=1 is the default compiler instrumentation. It is equivalent to -qpdf1 in the releases before IBM® XL Fortran for Linux®, 13.1.
  • -qpdf1=level=2 is a more aggressive compiler instrumentation than -qpdf1=level=0 and -qpdf1=level=1. It is supported at all optimization levels where PDF is enabled.

Notes:
  • Cache-miss profiling is enabled on SLES11 SP1.
  • You can set the value of the environment variable PDF_PM_EVENT to L1MISS, L2MISS or L3MISS (if applicable) to gather different levels of cache-miss profiling information.
  • You can set the environment variable PDF_BIND_PROCESSOR to bind your application to the specified processor for cache-miss profiling. Cache-miss profiling information is only available on the POWER5™, POWER6®, and POWER7™ processors.

The following example should be added for -qpdf1, -qpdf2:

Here is an example that gathers cache-miss profiling information. Block-counter profiling and value profiling information are also gathered:

#Compile all files with -qpdf1=level=2.
xlf -qpdf1=level=2 –O5 file1.f file2.f file3.f

#set PM_EVENT=L2MISS to gather L2 cache misses
export PDF_PM_EVENT=L2MISS

#Run with one set of input data
./a.out < sample.data

#Recompile all files with -qpdf2.
xlf -qpdf2 -O5 file1.f file2.f file3.f

#The program should now run faster than
#without PDF if the sample data is typical.

Topic location: Detailed descriptions of the XL Fortran compiler options > -qtune

The following rows in the Acceptable -qarch/-qtune combinations table:

-qarch optionDefault -qtune settingAvailable -qtune settings
pwr4pwr4auto | pwr4 | pwr5 | pwr7 | ppc970 | balanced
pwr5pwr5auto | pwr5 | pwr7 | balanced
pwr5xpwr5auto | pwr5 | pwr7 | balanced

Should read:

-qarch optionDefault -qtune settingAvailable -qtune settings
pwr4pwr4auto | pwr4 | pwr5 | pwr6 | pwr7 | ppc970 | balanced
pwr5pwr5auto | pwr5 | pwr6 | pwr7 | balanced
pwr5xpwr5auto | pwr5 | pwr6 | pwr7 | balanced


Topic location: Detailed descriptions of the XL Fortran compiler options > -qwarn64

Under Usage

You can use the -qextchk option and interface blocks for argument checking.

Should read:

You can use interface blocks for argument checking.


Topic location: Problem determination and debugging > Understanding XL Fortran error messages > Fixing compile-time problems

The following problem should be added:

Compilation failure because of internal alias table overflow

At an optimization level of -O2 or higher, XL Fortran compiler computes alias information to ensure that the optimizer preserves the semantics of the application. Alias computation might be an expensive process in terms of space usage, depending on the object definitions and language constructs used in an application. In rare occasions, the internal alias table might overflow, which causes the compilation to fail. Such overflow might occur when a module defines or uses derived-type objects that contain a large number of ultimate components, and passes the objects as dummy arguments to a large number of procedures that are defined in the same module. Partitioning the set of module procedures and placing each partition in a separate module might resolve the overflow problem.

Topic location: Problem determination and debugging > Debugging a Fortran program

You can use dbx and other symbolic debuggers to debug your programs. For instructions on using your chosen debugger, consult the online help within the debugger or its documentation.

should read:

You can use gdb or other symbolic debuggers to debug your programs. For instructions on using your chosen debugger, consult the online help within the debugger or its documentation.


Optimization and Programming Guide
The following corrections and additions apply to the IBM XL Fortran for Linux 13.1 Optimization and Programming Guide:

Topic location: Optimizing your applications > Specialized optimization techniques > Profile-directed feedback (PDF)

The following paragraph should be removed:

You can use the following -qpdf suboption to collect specific data to further improve the performance.

level
Supports multiple-pass profiling, block counter, call counter and extended value profiling. You can compile your application with -qpdf1=level=0|1|2 to generate profiling data with different levels of optimization. -qpdf=level=0 and -qpdf=level=1 support single-pass profiling, whereas -qpdf=level=2 supports multiple-pass profiling. If you want to bind the process to a particular processor, you can set the environment variable to PDF_BIND_PROCESSOR. Processor 0 is set by default.

Topic location: Tuning XL compiler applications > Further option driven tuning > Options to assist with performance analysis

-qshowpdf
    If you specify this option with -qpdf1 and a minimum of -O optimization, the optimization process inserts additional information into your application that the showpdf utility can make use of when analyzing the result of a PDF run.

Should read:
    If you specify this option with -qpdf1 and a minimum of -O2 optimization, the optimization process inserts additional information into your application that the showpdf utility can make use of when analyzing the result of a PDF run.

Topic location: Parallel programming with XL Fortran > Setting OMP and SMP run time options > OpenMP environment variables> OMP_STACKSIZE environment variable

If the value of OMP_STACKSIZE is not set, the initial value is set to the default value (256 M for 32-bit mode, or up to the limit imposed by system resources for 64-bit mode).

Should read:

If the value of OMP_STACKSIZE is not set, the initial value is set to the default value. The default value is 4194304B. The maximum value for 32-bit mode is 256M. For 64-bit mode, the maximum is up to the limit imposed by system resources.

[{"Product":{"code":"SSAT4T","label":"XL Fortran for Linux"},"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Component":"Documentation","Platform":[{"code":"PF016","label":"Linux"}],"Version":"13.1","Edition":"","Line of Business":{"code":"LOB17","label":"Mainframe TPS"}}]

Document Information

Modified date:
08 August 2018

UID

swg21431754