Preventive Service Planning
Abstract
This page contains corrections and additions to the product documentation shipped with IBM XL Fortran for AIX, V13.1.
Content
Quickstart Guide
The following corrections and additions apply to the IBM XL Fortran for AIX, V13.1 Quickstart Guide:
A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.
Getting Started
The following corrections and additions apply to the IBM XL Fortran for AIX, V13.1 Getting Started:
Topic location: What's new for IBM XL Fortran for AIX 13.1 > New or changed compiler options and directives
-qmkshrobji should read -qmkshrobj (PDF version only)
-qprefectch=assistthread should read -qprefetch=assistthread
Installation Guide
The following corrections and additions apply to the IBM XL Fortran for AIX, V13.1 Installation Guide:
Topic location: Update installation > Updating an advanced installation using xlfndi
The example in the second step:
ls /compiler/update/ > /home/user/update.list
Should read:
ls /compiler/update/*.bff > /home/user/update.list
Language Reference
The following corrections and additions apply to the IBM XL Fortran for AIX, V13.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: Directives (IBM extension) > 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)
...
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: Hardware-specific directives > PREFETCH > UNLIMITED_PROTECTED_STREAM_DEPTH
Syntax should read:
>>-UNLIMITED_PROTECTED_STREAM_DEPTH--(--unit_count, -prefetch_depth, -stream_id--)-><
Topic location: Intrinsic procedures > IBM2GCCLDBL(A)
This topic should be removed.
Topic location: Intrinsic procedures > IBM2GCCLDBL_CMPLX(A)
This topic should be removed.
Topic location: Intrinsic procedures > MOD(A, P)
| Specific Name | Argument Type | Result Type | Pass As Arg? |
| MOD | any integer | same as argument | yes |
Should read:
| Specific Name | Argument Type | Result Type | Pass As Arg? |
| MOD | default integer | default integer | yes |
Topic location: Hardware-specific intrinsic procedures (IBM extension) > SWDIV(X,Y)
Result value should read as follows:
The result has a value equal to X/Y.
If programs are compiled with the -qarch=pwr6 option (or earlier) and run on a POWER6™ processor (or earlier):
- For REAL(4) arguments, the result is bitwise identical to IEEE division.
- For REAL(8) arguments with -qstrict=ieeefp or -qstrict=exceptions in effect, the result is bitwise identical to IEEE division.
- For REAL(8) arguments with -qstrict=noieeefp or -qstrict=noexceptions in effect, the result can differ slightly from the IEEE result.
If programs are compiled with the -qarch=pwr7 option and run on a POWER7™ processor:
- With -qstrict=ieeefp or -qstrict=exceptions in effect, the result is bitwise identical to IEEE division.
- With -qstrict=noieeefp or -qstrict=noexceptions in effect, the result can differ slightly from the IEEE result.
Topic location: Hardware-specific intrinsic procedures (IBM extension) > SWDIV_NOCHK(X,Y)
Argument type and attributes should read as follows:
X
can be of type REAL(4) or REAL(8).
Y
must be of the same type and kind type parameter as X.
For correct operation, REAL(4) arguments must satisfy the following conditions:
- 2**(-125) <= |Y| <= 2**124
- If X is not zero, then:
- 2**(-102) <= |X| < Inf
- 2**(-124) <= |X/Y| <= 2**126
For correct operation, REAL(8) arguments must satisfy the following conditions:
- 2**(-1021) <= |Y| <= 2**1020
- If X is not zero, then:
- 2**(-969) <= |X| < Inf
- 2**(-1020) <= |X/Y| <= 2**1022
Result value should read as follows:
The result has a value equal to X/Y.
If programs are compiled with the -qarch=pwr6 option (or earlier) and run on a POWER6 processor (or earlier):
- For REAL(4) arguments, the result is bitwise identical to IEEE division.
- For REAL(8) arguments with -qstrict=ieeefp or -qstrict=exceptions in effect, the result is bitwise identical to IEEE division.
- For REAL(8) arguments with -qstrict=noieeefp or -qstrict=noexceptions in effect, the result can differ slightly from the IEEE result.
If programs are compiled with the -qarch=pwr7 option and run on a POWER7 processor:
- With -qstrict=ieeefp or -qstrict=exceptions in effect, the result is bitwise identical to IEEE division.
- With -qstrict=noieeefp or -qstrict=noexceptions in effect, the result can differ slightly from the IEEE result.
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 AIX, V13.1 Compiler Reference:
Topic location: Setting up and customizing XL Fortran > Correct settings for environment variables > PDF environment variables
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 | /usr/bin | FORTRAN 77 | libxlf90.a |
| xlf_r | /usr/bin | Threadsafe FORTRAN 77, operating system default POSIX pthreads API | libxlf90.a |
| xlf_r7 | /usr/bin | Threadsafe FORTRAN 77, Draft 7 POSIX pthreads API | libxlf90.a |
Should read:
Driver Invocation | Path or Location | Chief Functionality | Linked Libraries |
| xlf | /usr/bin | Selected Fortran language level | libxlf90.a |
| xlf_r | /usr/bin | The threadsafe version of the selected language level, operating system default POSIX pthreads API. | libxlf90.a |
| xlf_r7 | /usr/bin | The threadsafe version of the selected language level, Draft 7 POSIX pthreads API. | libxlf90.a |
Topic location:
- Editing, compiling, linking, and running XL Fortran programs > Linking XL Fortran programs > Linking 32–bit SMP object files using the ld command
- Editing, compiling, linking, and running XL Fortran programs > Linking XL Fortran programs > Linking 64-bit SMP object files using the ld command
- Editing, compiling, linking, and running XL Fortran programs > Linking XL Fortran programs > Linking 32–bit non-SMP object files using the ld command
- Editing, compiling, linking, and running XL Fortran programs > Linking XL Fortran programs > Linking 64-bit non-SMP object files using the ld command
If you use the -qpdf1 compiler option, specify -lxlopt.
Should read:
If you use the -qpdf1 compiler option, specify -lxlipa.
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 > -qalias_size
Syntax
Should read:
@PROCESS:
@PROCESS ALIAS_SIZE(size)
Usage
Should read:
Compiling very large programs with optimization can cause aliasing tables to get very large, which may result in memory fragmentation. Use this option only when the compiler issues an error message with a suggested value for size. Specifying this option in other situations, or with values not recommended by the compiler, may cause the compiler to run out of memory.
Topic location: Detailed descriptions of the XL Fortran compiler options > -qfunctrace
The following paragraph should be added under Usage:
This option inserts calls to user-defined tracing procedures. These procedures must be provided at the link step. For details about the interface of tracing procedures, as well as when they are called, see the "Tracing procedures in your code" section in the XL Fortran Optimization and Programming Guide.
Topic location: Detailed descriptions of the XL Fortran compiler options > -qtune
The following rows in the Acceptable -qarch/-qtune combinations table:
| -qarch option | Default -qtune setting | Available -qtune settings |
| pwr4 | pwr4 | auto | pwr4 | pwr5 | pwr7 | ppc970 | balanced |
| pwr5 | pwr5 | auto | pwr5 | pwr7 | balanced |
| pwr5x | pwr5 | auto | pwr5 | pwr7 | balanced |
Should read:
| -qarch option | Default -qtune setting | Available -qtune settings |
| pwr4 | pwr4 | auto | pwr4 | pwr5 | pwr6 | pwr7 | ppc970 | balanced |
| pwr5 | pwr5 | auto | pwr5 | pwr6 | pwr7 | balanced |
| pwr5x | pwr5 | auto | pwr5 | pwr6 | pwr7 | balanced |
Topic location: Tracking and reporting compiler usage > Generating usage reports
In "Understanding usage reports", the following sample reports should be listed:
Here are the sample reports generated with the two different report types:
Sample 1: A sample report generated with -qreporttype=detail
Sample 2: A sample report generated with -qreporttype=maxconcurrent
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.
Optimization and Programming Guide
The following corrections and additions apply to the IBM XL Fortran for AIX, V13.1 Optimization and Programming Guide:
Topic location: Optimizing your applications > Tracing procedures in your code
The whole topic should read as follows:
You can instruct the compiler to insert calls to user-defined tracing procedures to aid in debugging or timing the execution of other procedures.
To trace procedures in your program, you must specify which procedures to trace. You must also provide your own user-defined tracing procedures. If you enable tracing without providing tracing procedures, you will get linker errors about undefined symbols called __func_trace_enter, __func_trace_exit, and possibly __func_trace_catch .
Specifying which procedures to trace
The -qfunctrace compiler option controls tracing for all non-inlined user-defined procedures, and all outlined compiler-generated procedures in your program. To trace specific external or modules procedures, you can use the -qfunctrace+ and -qfunctrace- compiler options. You can also specify the NOFUNCTRACE directive to disable the tracing of entire modules, external procedures, module procedures, or internal procedures.
What can be traced
Tracing applies to programs, external procedures, module procedures, and internal procedures.
Compiler-generated procedures are not traced unless they were generated for outlined user code, such as an OpenMP program. In those cases, the name of the outlined procedure contains the name of the original user procedure as a prefix.
Because inlined procedures do not exist in the final program, they cannot be traced. Statement functions also do not exist in the final program, and therefore cannot be traced.
To avoid infinite recursion, user-defined tracing procedures cannot be traced. Similarly, tracing must be disabled for procedures called from user-defined tracing procedures.
How to write tracing procedures
You can implement the tracing procedures in Fortran, C, or C++.
To implement the tracing procedures in Fortran, the characteristics of the procedures must be the same as those specified in the following interface:
SUBROUTINE routine_name(procedure_name, file_name, line_number, id)
USE, INTRINSIC :: iso_c_binding
CHARACTER(*), INTENT(IN) :: procedure_name
CHARACTER(*), INTENT(IN) :: file_name
INTEGER(C_INT), INTENT(IN) :: line_number
TYPE(C_PTR), INTENT(INOUT) :: id
END SUBROUTINE
where routine_name is the name of an external or module procedure.
You must then tell the compiler to use your subroutine as a tracing procedure in one of the following ways:
- Using the -qfunctrace_xlf_enter, -qfunctrace_xlf_exit, or -qfunctrace_xlf_catch compiler options.
- Using the FUNCTRACE_XLF_ENTER, FUNCTRACE_XLF_EXIT, or FUNCTRACE_XLF_CATCH directives.
When you specify these options or directives, XL Fortran generates wrapper procedures called __func_trace_enter, __func_trace_exit, and __func_trace_catch that call your corresponding tracing procedure. These wrappers allow interoperability with C and C++ by converting the dummy arguments from the C prototype to the interface described earlier. routine_name must therefore not be named __func_trace_enter, __func_trace_exit, or __func_trace_catch. In addition, your program must not contain more than one of each of the tracing procedures.
Writing the tracing procedures in C or C++ requires that you provide the __func_trace_enter, __func_trace_exit, and __func_trace_catch procedures directly. They must have the following prototypes:
- void __func_trace_enter(const char *const procedure_name, const char *const file_name, int line_number, void **const id);
- void __func_trace_exit(const char *const procedure_name, const char *const file_name, int line_number, void **const id);
- void __func_trace_catch(const char *const procedure_name, const char *const file_name, int line_number, void **const id);
Note: If you write the tracing procedures in C++, they must be declared extern "C".
XL Fortran inserts calls to your tracing procedures on procedure entry and exit. It passes the name of the procedure being traced, the name of the file containing the entry or exit point being traced, and the line number. It also passes the address of a static pointer that is initialized to C_NULL_PTR at the beginning of the program. This pointer allows you to store arbitrary data in the entry tracing procedure and access this data in the exit and catch procedures. See the Examples section later on this page for an example. Because this pointer resides in static memory, extra steps might be needed when tracing threaded or recursive procedures.
Sample tracing procedures
XL Fortran provides sample tracing procedures in the /usr/lpp/xlf/samples/functrace directory. You can use these procedures for simple tracing, or you can modify them for more complex tracing.
- tracing_routines.c: Provides tracing procedures written in C. This file is useful when you do not require access to Fortran modules, and when there is a possibility of recursive input / output.
- tracing_routines.f90: Provides tracing procedures written in Fortran. This file is useful when you need access to Fortran modules or intrinsics in your tracing procedures.
The following example illustrates the use of the samples for simple tracing:
> cat helloworld.f
print *, 'hello world'
end
> cc -c /usr/lpp/xlf/samples/functrace/tracing_routines.c
> xlf95 helloworld.f -qfunctrace tracing_routines.o
** _main === End of Compilation 1 ===
1501-510 Compilation successful for file helloworld.f.
> ./a.out
{ _main (helloworld.f:1)
hello world
} _main (helloworld.f:2)
>
Tracing limitations
A procedure cannot be traced separately from its ENTRY points. Either all are traced or none are. The name of the procedure is passed to the tracing procedure even when tracing the ENTRY point. The line number helps distinguish what is being traced in this case.
The Fortran standard requires pure procedures to not have any side effects. The compiler uses this assumption when optimizing your program. If you enable tracing of a pure procedure, your tracing procedure must not change the program state in a way that creates a side effect.
The Fortran standard imposes limits on recursive input / output. If you write your tracing procedures in Fortran, you must be careful not to break these rules.
The following example has a print statement where an I/O item is the result of a function call (foo). It is illegal for the tracing procedure in this case to have I/O on an external file:
> cat recursive.f
integer function foo()
foo = 1
end function
integer foo
print *, foo() ! foo must not have I/O on external unit
end
> xlf95 -c /usr/lpp/xlf/samples/functrace/tracing_routines.f90
** my__func_trace_enter === End of Compilation 1 ===
** my__func_trace_exit === End of Compilation 2 ===
** my__func_trace_catch === End of Compilation 3 ===
1501-510 Compilation successful for file tracing_routines.f90.
> xlf95 recursive.f tracing_routines.o -qfunctrace
** foo === End of Compilation 1 ===
** _main === End of Compilation 2 ===
1501-510 Compilation successful for file recursive.f.
> ./a.out
{ _main (recursive.f:6)
XL Fortran (I/O initialization): I/O recursion detected.
IOT/Abort trap
>
Note: You can work around this by writing the tracing procedure in C (see the tracing_routines.c sample file for an example).
When optimizing your program, the compiler reorders code and removes dead code. As a result, the line number passed to the tracing procedure might not be accurate when optimization is enabled.
Examples
In the following example, -qfunctrace is used to measure the time spent in each external procedure. The FUNCTRACE_XLF_ENTER and FUNCTRACE_XLF_EXIT directives are used to specify procedures my_enter and my_exit as the tracing procedures. The NOFUNCTRACE directive is used to disable tracing of main_program:
> cat example.f
! Designate my_enter as a tracing procedure that should be called
! on procedure entry
!ibm* functrace_xlf_enter
subroutine my_enter(procedure_name, file_name, line_number, id)
use, intrinsic :: iso_c_binding
use, intrinsic :: xlfutility
character(*), intent(in) :: procedure_name, file_name
integer(c_int), intent(in) :: line_number
type(c_ptr), intent(inout) :: id
integer(kind=time_size), pointer :: enter_count
! Store the time we entered the procedure being traced into id.
if (.not. c_associated(id)) then
allocate(enter_count)
enter_count = time_()
id = c_loc(enter_count)
end if
print *, 'Entered procedure ', procedure_name, ' at ( ', &
file_name, ' :', line_number, ').'
end subroutine
! Designate my_exit as a tracing procedure that should be called
! on procedure exit
!ibm* functrace_xlf_exit
subroutine my_exit(procedure_name, file_name, line_number, id)
use, intrinsic :: iso_c_binding
use, intrinsic :: xlfutility
character(*), intent(in) :: procedure_name, file_name
integer(c_int), intent(in) :: line_number
type(c_ptr), intent(inout) :: id
integer(kind=time_size), pointer :: enter_count
integer(kind=time_size) exit_count, duration
! id should have been associated in my_enter with the time we
! entered the procedure being traced. Find the elapsed time.
if (c_associated(id)) then
exit_count = time_()
call c_f_pointer(id, enter_count)
duration = exit_count - enter_count
else
stop "error!"
endif
print *, 'Leaving procedure ', procedure_name, ' at ( ', &
file_name, ' :', line_number, ').'
print *, 'Spent', duration, 'seconds in ', procedure_name, '.'
end subroutine
! sub2 will be traced
subroutine sub2
call sleep_(3)
end subroutine
! sub1 will be traced
subroutine sub1
call sleep_(5)
call sub2
end subroutine
! Do not want to trace main_program
!ibm* nofunctrace
program main_program
call sub1
end program
> xlf95 example.f -qfunctrace
** my_enter === End of Compilation 1 ===
** my_exit === End of Compilation 2 ===
** sub2 === End of Compilation 3 ===
** sub1 === End of Compilation 4 ===
** main_program === End of Compilation 5 ===
1501-510 Compilation successful for file example.f.
> ./a.out
Entered procedure sub1 at ( example.f : 59 ).
Entered procedure sub2 at ( example.f : 54 ).
Leaving procedure sub2 at ( example.f : 55 ).
Spent 3 seconds in sub2.
Leaving procedure sub1 at ( example.f : 61 ).
Spent 8 seconds in sub1.
>
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.
Man pages
The following corrections and additions apply to the IBM XL Fortran for AIX, V13.1 man pages:
-qipa[=<suboptions_list>] | -qnoipa
Related Information
[{"Product":{"code":"SSGH4D","label":"XL Fortran for AIX"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"Documentation","Platform":[{"code":"PF002","label":"AIX"}],"Version":"13.1","Edition":"","Line of Business":{"code":"LOB57","label":"Power"}}]
Was this topic helpful?
Document Information
Modified date:
08 August 2018
UID
swg21419628