From: Mike Stewart (pmstewart_at_lbl_dot_gov)
Date: 07/07/2005
The default version of the IBM Fortran compiler will be upgraded on
Seaborg on Tuesday, July 12, 2005.
This new version of Fortran is release 9.1.0.2. This version is
currently contained in the xlf module on seaborg, and can be tested by
loading this module before compiling and linking Fortran programs.
New features, fixes, and documentation addeneda are described in the
attached README file.
--
=========================
Michael Stewart
Consultant
NERSC User Services Group
510-486-6648
pmstewart_at_lbl_dot_gov
=========================
*=======================================================================
* IBM(R) XL Fortran Enterprise Edition V9.1 for AIX(R) 5724-I08
* (C) COPYRIGHT International Business Machines Corp. 1990, 2004
* All Rights Reserved
* Licensed Materials - Property of IBM
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
* AIX, IBM, and i5/OS are trademarks of IBM Corp.
*
* Other company, product, and service names may be trademarks or service
* marks of others.
*=======================================================================
This README file contains the latest information about IBM XL Fortran
Enterprise Edition V9.1 for AIX, that was not available for our online
help and documentation.
By using IBM XL Fortran Enterprise Edition V9.1 for AIX, you agree
to the terms of the license as specified in the following files:
- LicAgree.pdf
- LicInfo.pdf
These files are located in the root directory of the installation CD.
After installation, they are located in the following directory:
/usr/lpp/xlf/
with the following names:
- LicenseAgreement.pdf
- license.pdf
You will need a PDF viewer to view the license agreement.
Note:
IBM XL Fortran Enterprise Edition V9.1 for AIX is licensed based on a
charge unit of one authorized user per operating system. Separate user
authorizations are required by individual users for each operating system
on which the program is used. For each user authorization on a given
operating system, the program may be stored on more than one machine,
provided that the program is not in active use by that individual user on
more than one machine at the same time.
An authorized user is an individual or specific named user authorized to
have access to the program or any portion of the program on a single
operating system. The Proof of Entitlement for this program is evidence of
your authorization. Each individual or specific named user must obtain a
Proof of Entitlement for each operating system on which the program is
used.
When IBM XL Fortran Enterprise Edition V9.1 for AIX is ordered, its
run-time component is shipped with the compiler on the same media. The XL
Fortran Run-Time component must be installed on the machine where the
Fortran program will be compiled and executed.
This document contains the following sections:
I. Viewing Documentation on AIX
II. Installation Issues
III. April 2005 XL Fortran Enterprise Edition V9.1 for AIX Update
IV. November 2004 XL Fortran Enterprise Edition V9.1 for AIX Update
V. Documentation Additions and Corrections
VI. Support Information
VII. Further Updates
I. Viewing Documentation on AIX
===============================
Documentation on installing and using IBM XL Fortran Enterprise Edition
V9.1 for AIX can be found in the .pdf files included as part of this
package and the XHTML-based information center.
To view the documentation, you must have X-Windows working on your
system. In addition, you need to have the appropriate viewers, such as a
frames-capable HTML browser like Mozilla or a PDF viewer, such as the
Adobe Reader.
To start the XHTML-based information center, first launch the
Eclipse server by logging in as root, and executing the following
command:
/usr/xlhelp/bin/xlhelp
After the Eclipse server starts, you can view the information center
from the server machine, or any client. For more information,
see the XL Fortran Enterprise Edition V9.1 for AIX Installation Guide.
II. Installation Issues
=======================
Operating System Support
------------------------
IBM XL Fortran Enterprise Edition V9.1 for AIX is supported on the
following AIX operating systems:
- AIX 5L V5.1, AIX 5L V5.2, or AIX 5L for POWER V5.3
See the IBM XL Fortran Enterprise Edition V9.1 for AIX Installation
Guide for installation instructions.
Deinstalling Beta or Evaluation Versions
----------------------------------------
Before installing the fully-licensed version of the product, you must
deinstall any Beta or Evaluation version of the product you have on
your system.
To do so enter the following command as root:
installp -ug xlf* memdbg* xlsmp* xlhelp* xlf.adt.include xlf.msg*
Note that deinstalling common components such as xlsmp*, xlhelp*, xlC.*,
and memdbg* will also make any fully-licensed version of the
C/C++ product you have installed unable to function. Use with discretion.
Additional MASS Filesets
------------------------
The MASS libraries and include files are packaged in three additional
filesets:
Fileset Name Fileset Description
xlmass.lib IBM Mathematical Acceleration Subsystem Libraries
xlmass.aix51.lib IBM Mathematical Acceleration Subsystem Libraries
for AIX 5.1
xlmass.adt.include IBM Mathematical Acceleration Subsystem Include
Files
For instructions on installing compiler filesets, see the XL Fortran
Enterprise Edition V9.1 for AIX Installation Guide.
Note: Do not overwrite the MASS files installed as part of the compiler
with MASS files available on the Web. The XL Fortran installation
creates the symbolic links necessary to compile and link the MASS
include files and libraries automatically.
Location of MASS Components
---------------------------
The default directories and symbolic links that are created for the MASS
components are as follows:
Component Default Location Symbolic Link
libmass.a /usr/xlmass/lib/aix51/ /usr/lib/
libmassv.a /usr/xlmass/lib/aix51/ /usr/lib/
libmassvp3.a /usr/xlmass/lib/aix51/ /usr/lib/
libmassvp4.a /usr/xlmass/lib/aix51/ /usr/lib/
mass.h /usr/xlmass/include/ /usr/include/
massv.h /usr/xlmass/include/ /usr/include/
mass.include /usr/xlmass/include/ /usr/include/
massv.include /usr/xlmass/include/ /usr/include/
Note that both XL C/C++ Enterprise Edition V7.0 for AIX and XL Fortran
Enterprise Edition V9.1 for AIX install the MASS components to the same
directories, so if you are using both products, the MASS components will
be located in a single common directory.
License Use Management
----------------------
It is no longer necessary to enroll your product license with the AIX
License Use Management (LUM) utility after you have installed XL Fortran.
You can begin to use XL Fortran Enterprise Edition V9.1 for AIX
immediately after installation and system configuration.
Ignore all LUM-related information presented in the User's Guide, such as,
Tracking Use of the Compiler, found in the Editing, Compiling, Linking,
and Running XL Fortran Programs section, and the -qlm option, found in the
XL Fortran Compiler-Option Reference section.
The IBM Distributed Debugger
----------------------------
The technology preview for The IBM Distributed Debugger (idebug) is not
available in XL Fortran Enterprise Edition V9.1 for AIX. Please disregard
all references to idebug in the documentation.
Portable Application Solutions Environment (i5/OS PASE) Support
---------------------------------------------------------------
IBM XL Fortran Enterprise Edition V9.1 for AIX can be installed and
operated in the i5/OS PASE on iSeries with V5R2 OS/400 or V5R3 i5/OS.
III. April 2005 XL Fortran Enterprise Edition V9.1 for AIX Update
=================================================================
Language Reference Errata
-------------------------
The following corrections and additions apply to the IBM XL Fortran
Enterprise Edition V9.1 for AIX Language Reference:
ALLOCATABLE Attribute
---------------------
The ALLOCATABLE attribute is no longer marked as Fortran 2003 standard
item in the applicable THREADPRIVATE and COPYIN descriptions.
SAVE Attribute
--------------
The following description of SAVE attribute behavior:
---------------- IBM Extension ------------------
XL Fortran permits function results to have the SAVE attribute.
To indicate that a function result is to have the SAVE attribute, the
function result name must be explicitly specified with the SAVE attribute.
That is, a SAVE statement without a list does not provide the SAVE
attribute for the function result.
---------------- End of IBM Extension -----------
Now reads:
---------------- IBM Extension ------------------
XL Fortran permits function results to have the SAVE attribute for
intrinsic types. To indicate that a function result is to have the
SAVE attribute, the function result name must be explicitly specified with
the SAVE attribute. That is, a SAVE statement without a list does not
provide the SAVE attribute for the function result.
---------------- End of IBM Extension -----------
PREFETCH_FOR_LOAD Directive
---------------------------
This directive is valid for any PowerPC architecture.
PROTECTED_STREAM_COUNT Directive
--------------------------------
The syntax for this directive now reads:
PROTECTED_STREAM_COUNT(unit_count, stream_id)
This directive sets the number of cache lines to unit_count for the
limited length protected stream with idetifier stream_id.
FCFI(I) and FCTID(X) Intrinsics
------------------------------
The PowerPC requirements in the purpose section of the FCFI(I) and
FCTID(X) intrinsics, now reads:
This intrinsic is valid on any 64-bit PowerPC architecture.
ROTATELM(RS, SHIFT, MASK) Hardware Intrinsic
--------------------------------------------
The RS type description incorrectly states that integers must be less
than 8 bytes. 8-byte integers are supported provided that the target
architecture is a 64-bit capable Power PC. Specify -qarch=ppc64 as a
minimum.
C_LONG_DOUBLE, and C_LONG_DOUBLE_COMPLEX Constants
--------------------------------------------------
The value of the C_LONG_DOUBLE, and C_LONG_DOUBLE_COMPLEX constants
provided by the ISO_C_BINDING module have been change from 8 to 16.
The C parts of new programs using these constants must be compiled
with an option that enables 16-byte long doubles.
Existing programs using C_LONG_DOUBLE or C_LONG_DOUBLE_COMPLEX will
continue to work as long as the parts dependent on the value of these
constants are not recompiled. If you are recompiling, and a type
interoperable with an 8-byte long double, or long double _Complex is
expected, you can use the C_DOUBLE and C_DOUBLE_COMPLEX constants,
respectively.
User's Guide Errata
-------------------
The following corrections and additions apply to the IBM XL Fortran
Enterprise Edition V9.1 for AIX User's Guide:
-qsmallstack Option
-------------------
-qsmallstack[=dynlenonheap] | -qnosmallstack
--------------
Specifies that the compiler will minimize stack usage where possible.
The -qsmallstack=dynlenonheap suboption affects automatic objects that
have nonconstant character lengths or a nonconstant array bound. When
specified, automatic variables are allocated on the heap. When this
suboption is not specified, automatic variables are allocated on the
stack.
-qtune Option
-------------
The default -qtune setting when compiling with -qarch=pwr is -qtune=pwr.
IV. November 2004 XL Fortran Enterprise Edition V9.1 for AIX Update
===================================================================
Language Reference errata
-------------------------
Expressions and Assignment
--------------------------
The section on Initialization Expressions now contains an additional
rule:
The transformational function IEEE_SELECTED_REAL_KIND from the
intrinsic module IEEE_ARITHMETIC can also be referenced.
Hardware-Specific Intrinsic Procedures
--------------------------------------
SWDIV(X,Y)
In addition to the existing documentation, please note the following:
-> For REAL(4) arguments, the result is bitwise identical to IEEE
division.
-> For REAL(8) arguments with -qstrict in effect, the result is bitwise
identical to IEEE division.
-> For REAL(8) arguments with -qnostrict in effect, the result can differ
slightly from the IEEE result.
-> This function can increase performance over the normal divide operator
where division is performed repeatedly within a loop.
SWDIV_NOCHK(X,Y)
In addition to the existing documentation, please note the following:
-> For REAL(4) arguments, the result is bitwise identical to IEEE
division.
You must not specify the following arguments:
-> |numerator| equal to infinity
-> |denominator| equal to infinity
-> |denominator|< 2**(-1022)
-> |numerator/denominator| equal to infinity
-> For REAL (8) arguments with -qstrict in effect, the result is bitwise
identical to IEEE division. For correct operation, the arguments must
satisfy the following conditions:
-> 2**(-970) < |numerator| < Inf
-> 2**(-1022) <= |denominator| < 2**1021
-> 2**(-1021) < |numerator/denominator| < 2**1023
With -qnostrict in effect, the result can differ slightly from the
IEEE result.
-> This function can increase performance over the normal divide
operator or the SWDIV built-in function where division is performed
repeatedly within a loop, and arguments are within the permitted range.
V. Documentation Additions and Corrections
==========================================
Installation Guide Errata
-------------------------
XL Fortran Packaging and Filesets
---------------------------------
Separate filesets for the MASS components have been added to the
installation package. See Installation Issues in this README.
Locations of XLOPT and MASS Components
--------------------------------------
The installation directories and symbolic links for MASS components have
changed. See Installation Issues in this README.
Viewing the HTML Documentation
------------------------------
To launch the Eclipse server, you must have root authority.
For more information, see Viewing Documentation on AIX in this README.
User's Guide Errata
-------------------
The following corrections and additions apply to the IBM XL Fortran
Enterprise Edition V9.1 for AIX User's Guide:
What's New
----------
- Ignore references to the "2003pure" run-time option. The related
"What's New" item now reads:
The 2003std run-time option provides conformance checking of code for
adherence to the draft standard.
- XL Fortran does not support auto-SIMD vectorization on AIX. The
auto-vectorization "What's New" item now reads:
The NOVECTOR directive and ALIGNX built-in subroutine provide
fine-grain control of the auto-vectorization.
- XL Fortran ships the MASS scalar and vector libraries.
The "What's New" item now reads:
XL Fortran includes the MASS scalar library of tuned mathematical
intrinsic functions and a set of vector libraries for use with
vectorized applications.
Editing, Compiling, Linking, and Running XL Fortran Programs
------------------------------------------------------------
In the "Setting Run-Time Options" section, under the "XLFRTEOPTS
Environment Variable" heading, the example for the "buffering="
run-time option now reads:
Fortran main program:
integer(4) p1,p2,p3
print *,'Reading p1 in Fortran...'
read(5,*) p1
call c_func(p2)
print *,'Reading p3 in Fortran...'
read(5,*) p3
print *,'p1 p2 p3 Read: ',p1,p2,p3
end
C subroutine (c_func.c):
#include <stdio.h>
void
c_func(int *p2)
{
int n1 = -1;
printf("Reading p2 in C...\n");
setbuf(stdin, NULL); /* Specifies no buffering for stdin */
fscanf(stdin,"%d",&n1);
*p2=n1;
fflush(stdout);
}
Input data file (infile):
11111
22222
33333
44444
The main program runs by using infile as redirected standard input, as
follows:
$ main < infile
If you turn on buffering=disable_preconn the results are as follows:
Reading p1 in Fortran...
Reading p2 in C...
Reading p3 in Fortran...
p1 p2 p3 Read: 11111 22222 33333
If you turn on buffering=enable the results are unpredictable.
-qarch=com
----------
The first sentence of the second paragraph under the com suboption for
the -qarch compiler option:
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.
Now reads:
If you specify the -q64 and -qarch=com options together, the target
platform is 64-bit, and the -qarch option is silently upgraded to
ppc64.
-qinlglue
---------
-qinlglue | -qnoinlglue
-----------
Specifying this compiler option inlines glue code that optimizes external
function calls in your application, when compiling at -O2 and higher.
The optimizer automatically inlines glue code when you compile with
-qtune=pwr4, pwr5, ppc970, or -qtune=auto when compiling on a machine
with the appropriate processor. Use the -qnoinlglue option to prevent
the compiler from automatically inlining 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 with
discretion.
-qipa=threads
-------------
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.
-qxflag=dvz
-----------
Specifying -qxflag=dvz causes the compiler to generate code to detect
floating-point divide-by-zero operations. 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 __xl_dzx
handler function is called
This option is only effective when you specify an optimization level
of -O or higher.
Using the Mathematical Acceleration Subsystem (MASS)
----------------------------------------------------
With the exception of rsqrt, all the MASS scalar functions have the same
names as the corresponding Fortran intrinsic functions, so interface
blocks are not necessary. Since rsqrt is not a Fortran intrinsic
function, you must include the file mass.include in the calling program
to provide the appropriate interface block.
Technical Details of the -qfloat=hsflt Option
----------------------------------------------
The speedup from this option is primarily for POWER and POWER2 machines.
We recommend that it not be used for programs targeted
(through the -qarch option) for PowerPC machines.
Now reads
Using -qfloat=hsflt can show a performance benefit for applications that
perform COMPLEX division and floating-point conversions. Additionally,
specifying -qfloat=hsflt when compiling applications targeting COMMON,
POWER, and POWER2 architectures, can achieve a broader range of
performance improvements unique to those targets.
Language Reference Errata
-------------------------
The following corrections and additions apply to the IBM XL Fortran
Enterprise Edition V9.1 for AIX Language Reference:
Expressions and Assignment
--------------------------
In the section on Specification Expressions, the following bullet:
A reference to an array inquiry function (except ALLOCATED), the bit
inquiry function BIT_SIZE, the character inquiry functions LEN and
NEW_LINE, the kind inquiry function KIND, or a numeric inquiry function.
Each argument is either a restricted expression, or it is a variable
whose properties inquired about are not dependent on the upper bound of
the last dimension of an assumed-size array, not defined by an expression
that is not a restricted expression, or not definable by an ALLOCATE
statement or by a pointer assignment statement.
now reads:
A reference to an array inquiry function (except ALLOCATED), the bit
inquiry function BIT_SIZE, the character inquiry functions LEN and
NEW_LINE, the kind inquiry function KIND, an IEEE inquiry function, or a
numeric inquiry function. Each argument is either a restricted
expression, or it is a variable whose properties inquired about are not
dependent on the upper bound of the last dimension of an assumed-size
array, not defined by an expression that is not a restricted expression,
or not definable by an ALLOCATE statement or by a pointer assignment
statement.
Comma-Separated Input/Output
----------------------------
Note: This function is an IBM extension.
When reading floating-point data using format-directed input/output,
a comma that appears in the input terminates the field. This can be
useful for reading files containing comma-separated values.
Example:
The following program reads two reals using the E edit descriptor.
It requires that the field width be 16 characters. The program attempts
to read the remaining characters in the record as a character string.
> cat read.f
real a,b
character*10 c
open(11, access='sequential', form='formatted')
read(11, '(2e16.10, A)') a,b,c
print *, a
print *, b
print *, c
end
If the floating-point fields are 16 characters wide, as the format
specifies, the program executes correctly.
(0.4000000000E+02 is 16 characters long)
> cat fort.11
0.4000000000E+020.3000000000E+02hello
> a.out
40.00000000
30.00000000
hello
But if the floating-point input contains less than 16 characters, errors
occur because parts of the next field are read.
(0.400000E+02 is 12 characters long)
> cat fort.11
0.400000E+020.3000000E+02hello
> a.out
1525-097 A READ statement using decimal base input found the invalid digit
'.' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'h' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'e' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'l' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'l' in the input file.
The program will recover by assuming a zero in its place.
1525-097 A READ statement using decimal base input found the invalid digit
'o' in the input file.
The program will recover by assuming a zero in its place.
INF
0.0000000000E+00
If you use commas to terminate the fields, the floating-point values
are read correctly.
(0.400000E+02 is 12 characters long, but the fields are separated by
commas.)
> cat fort.11
0.400000E+02,0.3000000E+02,hello
> a.out
40.00000000
30.00000000
hello
Directives
----------
STREAM_UNROLL, UNROLL, UNROLL_AND_FUSE
--------------------------------------
The -qipa=level=2 option is not sufficient to enable user-directed loop
unrolling as stated under the STREAM_UNROLL directive.
In order to enable user-directed loop unrolling, you must specify one of
the following compiler options:
-O4 or higher
-qhot
-qsmp
Note that if the -qstrict option is in effect, no stream unrolling will
occur. If you want to enable stream unrolling with the -qhot option
alone, you must also specify -qnostrict.
Hardware Specific Directives
----------------------------
In the PROTECTED STREAM section, that details the PROTECTED STREAM
directive set, the following keywords:
PROTECTED_STREAM_SET_GO_FORWARD
PROTECTED_STREAM_SET_GO_BACKWARD
Now read:
PROTECTED_STREAM_SET_FORWARD
PROTECTED_STREAM_SET_BACKWARD
SWDIV(X,Y) and SWDIV_NOCHK(X,Y) Built-In Functions
--------------------------------------------------
Arguments for which the numerator divided by the denominator equals
positive or negative infinity are not permitted.
Interoperability of Procedures
-------------------------------
The example in this section contains incorrect syntax. There should not
be a comma between "FUNC(...)" and "BIND(C)". The statement should read:
FUNCTION FUNC(I, J, K, L, M) BIND(C)
VI. Support Information
=======================
The following site contains support information for the IBM XL Fortran
Enterprise Edition V9.1 for AIX product:
http://www.ibm.com/software/awdtools/fortran/xlfortran/support
For the latest documentation XL Fortran, see the AIX Compiler Information
Center at:
http://publib.boulder.ibm.com/infocenter/comphelp/index.jsp
VII. Further Updates
====================
Additional information and documentation errata for the April 2005 XL
Fortran Enterprise Edition V9.1 for AIX Update and all future XL Fortran
Enterprise Edition V9.1 for AIX Updates can be found at the following url:
http://www.ibm.com/support/docview.wss?uid=swg1203115