*========================================================================== * IBM(R) XL Fortran Advanced Edition V9.1 for Linux(R) 5724-K76 * (C) COPYRIGHT International Business Machines Corp. 1990, 2005 * 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. * IBM, BladeCenter, iSeries, and pSeries are trademarks of IBM Corp. * * Linux is a trademark of Linus Torvalds in the United States, other * countries, or both. * * 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 Advanced Edition V9.1 for Linux that was not available for our online help and documentation. By using IBM XL Fortran Advanced Edition V9.1 for Linux, 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: /opt/ibmcmp/xlf/9.1 with the following names: - LicenseAgreement.pdf - license.pdf You will need a Portable Document Format (PDF) viewer to view these files. Note: IBM XL Fortran Advanced Edition V9.1 for Linux 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 Advanced Edition V9.1 for Linux 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 Linux II. Installation Issues III. February 2005 XL Fortran Advanced Edition V9.1 for Linux Update IV. Known Limitations for IBM XL Fortran Advanced Edition V9.1 for Linux V. IBM XL Fortran Advanced Edition V9.1 for Linux and GDB VI. Documentation Additions and Corrections VII. SUSE Linux Enterprise Server Considerations VIII. Support Information I. Viewing Documentation on Linux ================================= Documentation on installing and using IBM XL Fortran Advanced Edition V9.1 for Linux can be found in the .pdf and .htm files included as part of this package. To view the documentation remotely, you must have the X-server running on your local 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 gv or Xpdf installed on your system. II. Installation Issues ======================= Operating System Support ------------------------ IBM XL Fortran Advanced Edition V9.1 for Linux is supported on the following Linux distributions, running on IBM BladeCenter(TM), iSeries(TM) or pSeries(TM) computers: - Red Hat Enterprise Linux AS for POWER V3 (RHEL 3), Update 3 - SUSE LINUX Enterprise Server 9 for POWER (SLES 9) See the "IBM XL Fortran Advanced Edition V9.1 for Linux Installation Guide" for installation instructions. Uninstalling Evaluation or Beta Versions ----------------------------------------- Before installing the fully-licensed version of the product, you must uninstall any Beta or Evaluation version of the product you have on your system. Beta Uninstallation Instructions -------------------------------- rpm -e xlf.cmp-8.1.9999-0 rpm -e xlf.lic-8.1.9999-0 rpm -e xlf.rte.lnk-8.1.9999-0 rpm -e xlf.rte-8.1.9999-0 rpm -e xlf.msg.rte-8.1.9999-0 rpm -e xlsmp.lib-1.3.9999-0 rpm -e xlsmp.rte-1.3.9999-0 rpm -e xlsmp.msg.rte-1.3.9999-0 rpm -e xlf.help-8.1.9999-0 rpm -e xlf.samples-8.1.9999-0 Evaluation Uninstallation Instructions -------------------------------------- rpm -e xlf.cmp-9.1.0-0 rpm -e xlf.lib-9.1.0-0 rpm -e xlf.rte.lnk-9.1.0-0 rpm -e xlf.rte-9.1.0-0 rpm -e xlf.msg.rte-9.1.0-0 rpm -e xlf.help-9.1.0-0 rpm -e xlf.samples-9.1.0-0 rpm -e xlmass.lib-4.1.0-0 rpm -e xlsmp.lib-1.5.0-0 rpm -e xlsmp.rte-1.5.0-0 rpm -e xlsmp.msg.rte-1.5.0-0 Upgrading the Operating System or GCC ------------------------------------- If you upgrade the operating system or the GCC compiler after installing XL Fortran, you may need to update the default configuration file (and any configuration files you created) to reflect changes in file names and paths. After you upgrade the operating system or GCC, do the following: 1. Locate the default configuration file: /etc/opt/ibmcmp/xlf/9.1/xlf.cfg 2. Change the name of this file or move it to a different path. 3. Run the new_install or xlf_configure executable, as described in the "IBM XL Fortran Advanced Edition for Linux Installation Guide". This will create a new default configuration file. 4. If you have created any other configuration files, you must manually update these files to reflect any changes in the default configuration file. III. February 2005 XL Fortran Advanced Edition V9.1 for Linux Update ==================================================================== Compiler Options ---------------- The following new compiler options were introduced in this update: -qsmallstack=dynlenonheap, -qipa=threads, -qfloat=hsflt, and -qfloat=hssngl. Please refer to the XL Fortran Advanced Edition V9.1 for Linux User's Guide for more information. -qinlglue --------- Syntax: -qinlglue | -qnoinlglue ----------- Specifying this compiler option inlines glue code that optimizes external function calls in your application, when compiling at -q64 and -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; please use with discretion. -qoldmod Option --------------- Syntax: -qoldmod=compat This option specifies that object files containing module data compiled using earlier versions of XL Fortran for Linux either do not contain uninitialized module data or were ported using the convert_syms script provided below. The mangling scheme that XL Fortran uses for uninitialized module variables was changed in the February 2005 PTF Update. The old 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, Fortran modules containing uninitialized module variables and any compilation units using these modules need to be recompiled with the February 2005 XL Fortran for Linux 9.1 Update or later. If recompilation is not feasible, you can port the object files created by older compilers 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. Exmaple: # 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. > C_LONG_DOUBLE, and C_LONG_DOUBLE_COMPLEX Constants -------------------------------------------------- The value of the C_LONG_DOUBLE, and C_LONG_DOUBLE_COMPLEX constants as provided by the ISO_C_BINDING module have been changed to 16 from the previous value of 8. 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 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. Please note that the IBM XL Fortran Advanced Edition V9.1 for Linux extended-precision floating-point values are currently in a format that is not fully compatible with the format used by gcc 16-byte long doubles and long double _Complex. SWDIV and SWDIV_NOCHK intrinsic procedures ------------------------------------------ Documentation on the hardware-specific intrinsic procedures SWDIV and SWDIV_NOCHK has been updated. Please refer to the Language Reference for further information. SNAPSHOT Directive ------------------ The following is an added consideration for users of the SNAPSHOT directive: At high optimization levels, SNAPSHOT does not consistently preserve the contents of variables with a static storage class. Documentation Errata -------------------- Please note that all errata have been included in the February 2005 XL Fortran Advanced Edition V9.1 for Linux Update documentation. IV. Known Limitations for IBM XL Fortran Advanced Edition V9.1 for Linux ======================================================================== The following are known limitations for IBM XL Fortran Advanced Edition V9.1 for Linux running on any supported Linux distribution: -qflttrap=enable ---------------- The compiler option -qflttrap=enable does not need to be specified for trapping to occur. CPU_TIME -------- Due to a known limitation of threads on Linux, an application calling the CPU_TIME intrinsic procedure may give unexpected results when compiled using the -qsmp compiler option. Disassembling/Re-assembling Code with VMX Instructions ------------------------------------------------------ The disassembler on the BladeCenter JS20 server running SLES 9 does not yet provide VMX support. Thus, the disassembler will not be able to decipher VMX instructions and will leave them hex-encoded. Any relocations associated with VMX instructions will also be lost, so passing a disassembled file containing VMX instructions through an assembler may not produce a working program. Version and Linker Scripts -------------------------- When you specify the compiler options "-qipa", "-O4", "-O5", "-qpdf1 -O2", "-qpdf2 -O2", "-qpdf1 -O3", or "-qpdf2 -O3", version/linker scripts are not supported except linker scripts containing only the 'group' keyword. V. IBM XL Fortran Advanced Edition V9.1 for Linux and GDB ========================================================= Currently GDB offers debugging support for Fortran. However, GDB does not support all of the features found in IBM XL Fortran Advanced Edition V9.1 for Linux. VI. Documentation Additions and Corrections =========================================== User's Guide Errata ------------------- The following corrections and additions apply to the IBM XL Fortran Advanced Edition V9.1 for Linux User's Guide: 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 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 ------ -qarch=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 ppc64. See Using XL Fortran in a 64-Bit Environment for details. Now reads: 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. -qarch=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=ppc64gr. Now reads: 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. -qessl Option -------------- Syntax: -qessl | -qnoessl -------- Specifying -qessl allows the use of the Engineering and Scientific Subroutine Library (ESSL) routines in place of the XLF V9.1 run-time library routines for certain 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. Use the ESSL Serial Library when linking with -lessl. Use the ESSL SMP Library when linking with -lesslsmp. Either -lessl or -lesslsmp must be specified on the link command line 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) 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 -qfloat Option -------------- Syntax: -qfloat=hsflt | nohsflt ------- This suboption speeds up calculations by preventing rounding for single-precision expressions, and replacing floating-point division by multiplication with the reciprocal of the divisor. The hsflt suboption also uses the same technique as the fltint suboption for floating-point-to-integer conversions. 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 can produce unexpected results without warning. Use with discretion. Technical Details of -qfloat=hsflt The -qfloat=hsflt option is unsafe for optimized programs that compute floating-point values outside the range of representation of single precision, not just outside the range of the result type. The range of representation includes both the precision and the exponent range. Even when you follow the rules that are stated in the preceding paragraph and as documented under the -qfloat=hsflt suboption, programs that are sensitive to precision differences will not always produce expected results. Because -qfloat=hsflt is not compliant with IEEE, programs will not always run as expected. For example, in the following program, X.EQ.Y can be true or false: REAL X, Y, A(2) DOUBLE PRECISION Z LOGICAL SAME READ *, Z X = Z Y = Z IF (X.EQ.Y) SAME = .TRUE. ! ... ! ... Calculations that do not change X or Y ! ... CALL SUB(X) ! X is stored in memory with truncated fraction. IF (X.EQ.Y) THEN ! The result can be different than before. ... A(1) = Z X = Z A(2) = 1. ! A(1) is stored in memory with truncated fraction. IF (A(1).EQ.X) THEN ! The result can be different than expected. ... If the value of Z has fractional bits that are outside the precision of a single-precision variable, these bits can be preserved in some cases and lost in others. This makes the exact results unpredictable when the double-precision value of Z is assigned to single-precision variables. For example, passing the variable as a dummy argument causes its value to be stored in memory with a fraction that is truncated rather than rounded. -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 handler function is called. This option is only effective when you specify an optimization level of -O or higher. Interlanguage Calls ------------------- In the section "Passing Data From One Language to Another" under the heading "Passing Arguments Between Languages", the first note for Table 20: Requires a C compiler that supports 128-bit long double. Now reads: Requires a C compiler that supports 128-bit long double. XL C does not officially support -qldbl128 on Linux. Use with discretion. Language Reference Errata ------------------------- The following corrections and additions apply to the IBM XL Fortran Advanced Edition V9.1 for Linux 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 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 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. 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) VII. SUSE Linux Enterprise Server Considerations ================================================ Passing Complex Values and GCC 3.3 on SLES9 ------------------------------------------- GCC 3.3 on SLES 9 has changed the conventions for passing or returning complex numbers in 64-bit mode. Object files that: - Are compiled for 64-bit mode; and - Pass complex type arguments or return values; and - Are compiled for 64-bit mode by GCC 3.2 or earlier, or by XL Fortran that was configured for GCC 3.2 or earlier, with the -qfloat=complexgcc compiler option will need to be recompiled by GCC 3.3 or the XL Fortran V9.1 Beta that is configured for GCC 3.3. VIII. Support Information ========================= The following site contains support information for the IBM XL Fortran Advanced Edition V9.1 for Linux product: http://www.ibm.com/software/awdtools/fortran/xlfortran/support In addition, this support site includes information and guidelines on any Linux operating system considerations that can impact compiler behavior or performance. Check this site for a list of known considerations and solutions. For additional information on the MASS libraries, see the following site: http://www.ibm.com/software/awdtools/vacpp/mass