Cray Fortran Compiler Commands and Directives Reference Manual S

Transcription

1 Cray Fortran Compiler Commands and Directives Reference Manual S

2 1993, 1995, 1997, Cray Inc. All Rights Reserved. This manual or parts thereof may not be reproduced in any form unless permitted by contract or by written permission of Cray Inc. The Cray Fortran Compiler includes United States software patents 5,247,696, 5,257,372, and 5,361,354. U.S. GOVERNMENT RESTRICTED RIGHTS NOTICE The Computer Software is delivered as "Commercial Computer Software" as defined in DFARS 48 CFR All Computer Software and Computer Software Documentation acquired by or for the U.S. Government is provided with Restricted Rights. Use, duplication or disclosure by the U.S. Government is subject to the restrictions described in FAR 48 CFR or DFARS 48 CFR , as applicable. Technical Data acquired by or for the U.S. Government, if any, is provided with Limited Rights. Use, duplication or disclosure by the U.S. Government is subject to the restrictions described in FAR 48 CFR or DFARS 48 CFR , as applicable. Autotasking, CF77, Cray, Cray Ada, Cray Channels, Cray Chips, CraySoft, Cray Y-MP, Cray-1, CRInform, CRI/TurboKiva, HSX, LibSci, MPP Apprentice, SSD, SuperCluster, UNICOS, UNICOS/mk, and X-MP EA are federally registered trademarks and Because no workstation is an island, CCI, CCMT, CF90, CFT, CFT2, CFT77, ConCurrent Maintenance Tools, COS, Cray Animation Theater, Cray APP, Cray C90, Cray C90D, Cray CF90, Cray C++ Compiling System, CrayDoc, Cray EL, Cray Fortran Compiler, Cray J90, Cray J90se, Cray J916, Cray J932, CrayLink, Cray MTA, Cray MTA-2, Cray MTX, Cray NQS, Cray/REELlibrarian, Cray S-MP, Cray SSD-T90, Cray SV1, Cray SV1ex, Cray SV2, Cray SX-5, Cray SX-6, Cray T90, Cray T94, Cray T916, Cray T932, Cray T3D, Cray T3D MC, Cray T3D MCA, Cray T3D SC, Cray T3E, CrayTutor, Cray X-MP, Cray XMS, Cray-2, CSIM, CVT, Delivering the power..., DGauss, Docview, EMDS, GigaRing, HEXAR, IOS, ND Series Network Disk Array, Network Queuing Environment, Network Queuing Tools, OLNET, RQS, SEGLDR, SMARTE, SUPERLINK, System Maintenance and Remote Testing Environment, Trusted UNICOS, and UNICOS MAX are trademarks of Cray Inc. OpenMP is a trademark of the OpenMP Architecture Review Board. Portions of this product/publication may have been derived from the OpenMP Language Application Program Interface Specification. SPARC is a trademark of SPARC International, Inc. All SPARC trademarks are used under licensing agreements and are trademarks or registered trademarks of SPARC International, Inc. Products bearing SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc. TotalView is a trademark of Bolt Baranek and Newman Inc. UNIX, the X device, X Window System, and X/Open are trademarks of The Open Group in the United States and other countries. All other trademarks are the property of their respective owners. Adapted with permission of McGraw-Hill, Inc. from the FORTRAN 90 HANDBOOK, Copyright 1992 by Walter S. Brainerd, Jeanne C. Adams, Jeanne T. Martin, Brian T. Smith, and Jerrold L. Wagener. All rights reserved. Cray Inc. is solely responsible for the content of this work. The UNICOS operating system is derived from UNIX System V. The UNICOS operating system is also based in part on the Fourth Berkeley Software Distribution (BSD) under license from The Regents of the University of California.

3 New Features Cray Fortran Compiler Commands and Directives Reference Manual S Changes were made to this manual to support the following features of the Cray Fortran Compiler release 3.6: ftn: The ftn command replaces the f90 command as the default compiler command. -d y/-e y: This new option adds information into the binary files that allows the loader to find the modules. Refer to Section 2.2.6, page 9. -O inline4: This option s functionality has changed from aggressive inlining to attempting to inline call sites that contain constant actual arguments. Therefore, aggressive inlining is now performed by the new inline5 option. Refer to Section , page 35. -Q path: This new option specifies the directory for all non-temporary files (for example, a.out and.mod files) created by the Cray Fortran Compiler. Refer to Section , page 58. Vector optimization: The new features for vector optimization consists of a new INFINITEVL clause for the IVDEP directive and a new -O [no]infinitevl compiler option. Both features control the infinite vector length. Refer to Section , page 38 and Section 3.2.3, page 98. Cloning optimization: This new feature attempts to clone a procedure and replace its dummy arguments with associated constant actual arguments throughout the cloned procedure The feature adds the following to the compiler: the -O clonex option and the CLONE and NOCLONE directives. Refer to Section , page 21 for the option and Section 3.4.1, page 112 for the directives. Combined inlining: This new inlining mode is invoked when using the -O inlinen and -O inlinefrom=source options together on the command line. The inlining mode will look only in source for potential targets to expand, while applying the selected inlining heuristics (-O inlinen). FORTRAN_MODULE_PATH: This new environment variable allows you to specify the files or directories that contain Fortran modules to load so the compiler can satisfy the USE statements. Refer to Section 2.3.5, page 76. New Fortran source file extensions: The.ftn and.ftn file extensions specify Fortran source files and imply free form formatting. The.FTN extension invokes the source preprocessor. New Fortran options environment variable: The CRAY_FTN_OPTIONS environment replaces the CRI_F90_OPTIONS environment variable, but CRI_F90_OPTIONS can still be used to specify additional compiler options. Refer to Section 2.3.3, page 75.

4 The following note was added to the general rules about the preprocessor: Directive syntax allows an identifier to contain the! character. Hence, placing the! character to signal a Fortran 90 comment on the same line as the directive should be avoided. Table Table 6, page 83 was corrected to show that the CONCURRENT directive is supported on Cray SV1 series systems.

5 Record of Revision Version Description 1.0 December 1993 Original Printing. This document supports the CF90 compiler release 1.0 running on Cray Y-MP systems. 1.1 June 1994 This document supports the CF90 compiler release 1.0 running on both Cray Y-MP systems and on SPARC systems, including those from CRS. 2.0 November 1995 This document supports the CF90 compiler release 2.0 running on Cray PVP systems, Cray T3E systems, and SPARC systems. The implementation of features on Cray T3E systems is deferred. 3.0 May 1997 This printing supports the CF release running on UNICOS and UNICOS/mk operating systems August 1997 This online revision supports the CF release, running on UNICOS and UNICOS/mk operating systems March 1998 This online revision supports the CF release, running on UNICOS and UNICOS/mk operating systems. 3.1 August 1998 This printing supports the CF release running on UNICOS and UNICOS/mk operating systems. 3.2 January 1999 This printing supports the CF release running on UNICOS and UNICOS/mk operating systems. 003 July 1999 This revision supports the CF release running on UNICOS and UNICOS/mk operating systems. 004 March 2000 This revision supports the CF release running on UNICOS and UNICOS/mk operating systems. S i

6 Cray Fortran Compiler Commands and Directives Reference Manual 35 January 2001 The CF release supports the Cray SV1 series and Cray T3E systems. This manual (S ) is the successor of manual The manual revision number reflects the PE release number. 36 June 2002 This manual documents the Cray Fortran Compiler release 3.6 which runs on the UNICOS and UNICOS/mk operating systems. ii S

7 Contents Preface Related Cray Fortran Compiler Publications xiii Cray Fortran Compiler Man Pages xiv Cray Fortran Compiler Messages xiv Related Fortran Publications xiv Related Publications xv Ordering Documentation xv Conventions xvi Reader Comments xvii Introduction [1] 1 Invoking the Cray Fortran Compiler [2] 5 Setting Up the Cray Fortran Compiler Programming Environment The ftn(1) Command a alloc A module_name[,module_name] b bin_obj_file c C cifopts d disable and -e enable D identifier[=value][,identifier[=value]] f source_form F g G debug_lvl i Page xiii S iii

8 Cray Fortran Compiler Commands and Directives Reference Manual Page -I incldir J dir_name l lib L dir m msg_lvl M msgs N col o out_file O opt[,opt] O O O O O aggress, -O noaggress O allfastint, -O fastint, -O nofastint (UNICOS Systems Only) O bl, -O nobl O clonen O fusion, -O nofusion (UNICOS/mk Systems Only) O ieeeconform, -O noieeeconform O inline n and -O inlinefrom=source O infinitevl, -O noinfinitevl (UNICOS Systems Only) O jump, -O nojump (UNICOS/mk Systems Only) O loopalign, -O noloopalign (UNICOS Systems Only) O modinline, -O nomodinline O msgs, -O nomsgs O negmsgs, -O nonegmsgs O nointerchange O overindex, -O nooverindex O pattern, -O nopattern O pipelinen (UNICOS/mk Systems Only) iv S

9 Contents Page -O recurrence, -O norecurrence O reshape[=array] (UNICOS/mk Systems Only) O scalar O scalar O scalar O scalar O shortcircuitn O split n (UNICOS/mk Systems Only) O streamn (Cray SV1 series Systems Only) O task0 (UNICOS Systems Only) O task1 (UNICOS Systems Only) O task2 (UNICOS Systems Only) O task3 (UNICOS Systems Only) O taskinner, -O notaskinner (UNICOS Systems Only) O threshold, -O nothreshold (UNICOS Systems Only) O unroll n (UNICOS/mk Systems Only) O vector O vector O vector O vector O vsearch, -O novsearch O zeroinc, -O nozeroinc Optimization Values p module_site Q path r list_opt R runchk s size S asm_file t num (UNICOS Systems Only) S v

10 Cray Fortran Compiler Commands and Directives Reference Manual Page -T U identifier[,identifier] v V Wa"assembler_opt" Wl"loader_opt" Wr"lister_opt" x dirlist X npes (UNICOS/mk Systems Only) Z (UNICOS/mk Systems Only) sourcefile [sourcefile...] Environment Variables AUXBUF (UNICOS Systems Only) AUXPAGE (UNICOS Systems Only) CRAY_FTN_OPTIONS and CRI_F90_OPTIONS FORMAT_TYPE_CHECKING FORTRAN_MODULE_PATH LD_OPTIONS (UNICOS/mk Systems Only) LISTIO_PRECISION LPP MP_DEDICATED (UNICOS Systems Only) MP_HOLDTIME (UNICOS Systems Only) MP_SAMPLE (UNICOS Systems Only) MP_SLVSIN (UNICOS Systems Only) MP_SLVSSZ (UNICOS Systems Only) NCPUS (UNICOS Systems Only) NLSPATH NPROC OMP_DYNAMIC (UNICOS Systems Only) vi S

11 Contents Page OMP_NESTED (UNICOS Systems Only) OMP_NUM_THREADS (UNICOS Systems Only) OMP_SCHEDULE (UNICOS Systems Only) SEGDIR (UNICOS Systems Only) TARGET TMPDIR ZERO_WIDTH_PRECISION Cray Fortran Compiler Directives [3] 83 Using Directives Directive Lines Range and Placement of Directives Interaction of Directives with the -x Command Line Option Command Line Options and Directives Vectorization and Tasking Directives Declare Lack of Side Effects: CNCALL (UNICOS systems only) Copy Arrays to Temporary Storage: COPY_ASSUMED_SHAPE Ignore Vector Dependencies: IVDEP Specify Scalar Processing: NEXTSCALAR Request Pattern Matching: PATTERN and NOPATTERN Declare an Array with No Repeated Values: PERMUTATION Designate Nested Loops: PREFERTASK (UNICOS Systems Only) Designate Loop Nest for Vectorization: PREFERVECTOR (UNICOS Systems Only) Designate Reduction Loops: RECURRENCE, NORECURRENCE Using RECURRENCE and NORECURRENCE on UNICOS Systems Using RECURRENCE and NORECURRENCE on UNICOS/mk Systems Designate Loops with Low Trip Counts: SHORTLOOP, SHORTLOOP Enable and Disable Tasking: TASK and NOTASK (UNICOS Systems Only) Unroll Loops: UNROLL and NOUNROLL Enable and Disable Vectorization: VECTOR and NOVECTOR Specify a Vectorizable Function: VFUNCTION (UNICOS Systems Only) S vii

12 Cray Fortran Compiler Commands and Directives Reference Manual Page Vectorize Search Loops: VSEARCH and NOVSEARCH (UNICOS Systems Only) Multi-Streaming Processor (MSP) Directives (Cray SV1 series Systems Only) Specify Loop to be Optimized for MSP: PREFERSTREAM (Cray SV1 series Systems Only) Enable MSP Optimization: STREAM and NOSTREAM (Cray SV1 series Systems Only) Inlining Directives Disable or Enable Cloning for a Block of Code: CLONE and NOCLONE Disable or Enable Inlining for a Block of Code: INLINE and NOINLINE Specify Inlining for a Procedure: INLINEALWAYS and INLINENEVER Create Inlinable Templates for Module Procedures: MODINLINE and NOMODINLINE Scalar Optimization Directives Align Loops on Buffer Boundaries: ALIGN (UNICOS Systems Only) Bottom Load Operands: BL and NOBL Bypass Cache References: CACHE_BYPASS (UNICOS/mk Systems Only) Control Loop Interchange: INTERCHANGE and NOINTERCHANGE Directives Determine Register Storage: NOSIDEEFFECTS (UNICOS Systems Only) Request Loop Splitting: SPLIT and NOSPLIT (UNICOS/mk Systems Only) Suppress Scalar Optimization: SUPPRESS Local Use of Compiler Features Check Array Bounds: BOUNDS and NOBOUNDS Specify Source Form: FREE and FIXED Storage Directives Allocating to SSD: AUXILIARY (UNICOS Systems Only) Restrictions Auxiliary Arrays and Memory Permit Cache Blocking: BLOCKABLE Directive Declare Cache Blocking: BLOCKINGSIZE and NOBLOCKING Directives Align on Cache Line Boundaries: CACHE_ALIGN (UNICOS/mk Systems Only) Declare Common Blocks Global to All Tasks: COMMON (UNICOS Systems Only) Request Stack Storage: STACK Declare Local Addressing: SYMMETRIC (UNICOS/mk Systems Only) viii S

13 Contents Page Declare Common Blocks Local to Each Task: TASKCOMMON (UNICOS Systems Only) Miscellaneous Directives Specify Array Dependencies: CONCURRENT (Cray SV1 series and UNICOS/mk Systems Only) 136 Flowtracing Directives: FLOW and NOFLOW (UNICOS Systems Only) Create Identification String: ID Disregard Dummy Argument Type, Kind, and Rank: IGNORE_TKR External Name Mapping Directive: NAME Reserve E Registers: USES_EREGS (UNICOS/mk Systems Only) OpenMP Fortran API Directives (UNICOS Systems Only) [4] 143 Using Directives Conditional Compilation Parallel Region Constructs (PARALLEL and END PARALLEL Directives) Work-sharing Constructs Specify Parallel Execution: DO and END DO Directives Mark Code for Specific Threads: SECTION, SECTIONS and END SECTIONS Directives Request Single thread Execution: SINGLE and END SINGLE Directives Combined Parallel Work-sharing Constructs Declare a Parallel Region: PARALLEL DO and END PARALLEL DO Directives Declare Sections within a Parallel Region: PARALLEL SECTIONS and END PARALLEL SECTIONS Directives Synchronization Constructs Request Execution by the Master Thread: MASTER and END MASTER Directives Request Execution by a Single Thread: CRITICAL and END CRITICAL Directives Synchronize All Threads in a Team: BARRIER Directive Protect a Location from Multiple Updates: ATOMIC Directive Read and Write Variables to Memory: FLUSH Directive Request Sequential Ordering: ORDERED and END ORDERED Directives Data Environment Constructs Declare Common Blocks Private to a Thread: THREADPRIVATE Directive Data Scope Attribute Clauses S ix

14 Cray Fortran Compiler Commands and Directives Reference Manual Page PRIVATE Clause SHARED Clause DEFAULT Clause FIRSTPRIVATE Clause LASTPRIVATE Clause REDUCTION Clause COPYIN Clause Data Environment Rules Directive Binding Directive Nesting Analyzing Data Dependencies for Multiprocessing Dependency Analysis Examples Rewriting Data Dependencies Work Quantum Source Preprocessing [5] 191 General Rules Directives #include Directive #define Directive #undef Directive # (Null) Directive Conditional Directives #if Directive #ifdef Directive #ifndef Directive #elif Directive #else Directive #endif Directive Predefined Macros Command Line Options x S

15 Contents Page Appendix A Autotasking Directives (UNICOS Systems Only) (Outmoded) 201 Using Directives Directive Lines Range and Placement of Directives Interaction of Directives with the -x Command Line Option Command Line Options and Directives Migrating to OpenMP Fortran API Directives Concurrent Blocks: CASE and ENDCASE Declare Lack of Side Effects: CNCALL Mark Parallel Loop: DOALL Mark Parallel Loop: DOPARALLEL and ENDDO Critical Region: GUARD and ENDGUARD Specify Maximum Number of CPUs for a Parallel Region: NUMCPUS Mark Parallel Region: PARALLEL and ENDPARALLEL Declare an Array with No Repeated Values: PERMUTATION Declare a Cross-iteration Dependency: WAIT and SEND Autoscoping Rules User-added Scope Required Examples Read-only Variables Array Indexed by Loop Index Read-then-write Variables Write-then-read Variables and Arrays Autotasking Restrictions Glossary 223 Index 233 Figures Figure 1. ftn(1) Command Example Figure 2. Optimization Values S xi

16 Cray Fortran Compiler Commands and Directives Reference Manual Page Figure 3. Accessing 32 bit Components Through an Equivalenced Array Figure 4. Accessing Sequenced Components Through an Equivalenced Array Figure 5. Derived Type Storage Tables Table 1. Compiling options Table 2. -O opt summary Table 3. Automatic inlining specifications Table 4. Description of source Table 5. Values for the TARGET Environment Variable Table 6. Directives Table 7. Initialization Values Table 8. Autotasking Directive parameter Table 9. Autotasking Directive work_distribution xii S

17 Preface This manual describes the commands and directives for using the Cray Fortran Compiler, which is invoked through the ftn(1) and f90(1) commands. The manual is organized into the following chapters: Note: Since the ftn(1) and f90(1) commands have the same functionality and options, ftn(1) will be used to refer to both commands. Chapter 1, page 1, introduces the content of this manual and provides a general description of the compiler. Chapter 2, page 5, describes the ftn(1) commands, which you use to invoke the compiler. This chapter includes information about the options you can use on the Cray Fortran Compiler command line and environment variables that affect the compiler. Chapter 3, page 83, describes the Cray Fortran Compiler directives that the compiler recognizes. Chapter 4, page 143, describes the OpenMP Fortran API directives. Chapter 5, page 191, describes the source preprocessor. Appendix A, page 201, describes the Autotasking directives, which are outmoded. Cray Inc. encourages you to write new codes and to update existing codes using the OpenMP Fortran API directives described in Chapter 4, page 143. Related Cray Fortran Compiler Publications This manual is one of a set of manuals that describes the Cray Fortran Compiler. The other manuals in the set are as follows: Intrinsic Procedures Reference Manual Fortran Language Reference Manual, Volume 1 Fortran Language Reference Manual, Volume 2 Fortran Language Reference Manual, Volume 3 S xiii

18 Cray Fortran Compiler Commands and Directives Reference Manual Cray Fortran Compiler Man Pages In addition to printed and online manuals, several online man pages describe aspects of the Cray Fortran Compiler. Man pages exist for the library routines, the intrinsic procedures, and several programming environment tools. You can print copies of online man pages by using the pipe symbol with the man(1), col(1), and lpr(1) commands. In the following example, these commands are used to print a copy of the explain(1) man page: % man explain col -b lpr Each man page includes a general description of one or more commands, routines, system calls, or other topics, and provides details of their usage (command syntax, routine parameters, system call arguments, and so on). If more than one topic appears on a page, the entry in the printed manual is alphabetized under its primary name; online, the secondary entry names are linked to these primary names. For example, egrep is a secondary entry on the page with a primary entry name of grep. To access grep online, you can type man grep. To access egrep online, you can type either man grep or man egrep. Both commands display the grep man page. Cray Fortran Compiler Messages You can obtain Cray Fortran Compiler message explanations by using the online explain(1) command. Related Fortran Publications You can consult the following commercially available reference books for more information on the history of Fortran and the Fortran language itself: Adams, J., W. Brainerd, and J. Martin. Fortran 95 Handbook : Complete ISO/ANSI Reference. MIT Press, ISBN Chapman, S. Fortran 90/95 for Scientists and Engineers. McGraw Hill Text, ISBN Chapman, S. Introduction to Fortran 90/95. McGraw Hill Text, ISBN Counihan, M. Fortran 95 : Including Fortran 90, Details of High Performance Fortran (HPF), and the Fortran Module for Variable-Length Character Strings. UCL Press, ISBN xiv S

19 Preface Gehrke, W. Fortran 95 Language Guide. Springer Verlag, ISBN International Organization for Standardization. ISO/IEC :1997, Information technology Programming languages Fortran Metcalf, M. and J. Reid. Fortran 90/95 Explained. Oxford University Press, ISBN Related Publications The following documents contain additional programming environment publications that may interest you: Segment Loader (SEGLDR) and ld Reference Manual UNICOS User Commands Reference Manual UNICOS Performance Utilities Reference Manual Scientific Library Reference Manual Application Programmer s Library Reference Manual Application Programmer s I/O Guide Optimizing Application Code on UNICOS Systems CRAY T3E Fortran Optimization Guide Ordering Documentation To order software documentation, contact the Cray Software Distribution Center in any of the following ways: orderdsk@cray.com Web: Click on the Cray Publications Order Form link. Telephone (inside U.S., Canada): (BUG CRAY), then S xv

20 Cray Fortran Compiler Commands and Directives Reference Manual Telephone (outside U.S., Canada): Contact your Cray representative, or call Fax: Mail: Software Distribution Center Cray Inc Mendota Heights Road Mendota Heights, MN USA Conventions The following conventions are used throughout this document: Convention command variable Meaning This fixed-space font denotes literal items, such as file names, pathnames, man page names, command names, and programming language elements. Italic typeface indicates an element that you will replace with a specific value. For instance, you may replace filename with the name datafile in your program. It also denotes a word or concept being defined. user input This bold, fixed-space font denotes literal items that the user enters in interactive sessions. Output is shown in nonbold, fixed-space font. [ ] Brackets enclose optional portions of a syntax representation for a command, library routine, system call, and so on.... Ellipses indicate that a preceding element can be repeated. xvi S

21 Preface Reader Comments Contact us with any comments that will help us to improve the accuracy and usability of this document. Be sure to include the title and number of the document with your comments. We value your comments and will respond to them promptly. Contact us in any of the following ways: Telephone (inside U.S., Canada): (Cray Customer Support Center) Telephone (outside U.S., Canada): Contact your Cray representative, or call (Cray Customer Support Center) Mail: Software Publications Cray Inc Mendota Heights Road Mendota Heights, MN USA S xvii

22

23 Introduction [1] This manual describes the Cray Fortran Compiler release 3.6, which supports these systems: Cray SV1 series systems using UNICOS or later. The use of the bte_move intrinsic requires UNICOS Cray T3E systems using UNICOS/mk or later. The Cray Fortran Compiler supports these standards: Selected features from the Fortran 2000 draft currently being defined by the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC). The Fortran 95 standard (ISO/IEC :1997). This standard is adopted by the American National Standards Institute (ANSI) and the International Organization for Standardization (ISO) Because the Fortran 95 standard is a superset of previous standards, the Cray Fortran Compiler compiles code written in accordance with previous Fortran standards. The Fortran 95 standard is a revision to the Fortran 90 language standard. Because of the number and complexity of the features, the standards organizations are continuing to interpret the Fortran 95 standard for Cray and for other vendors. To maintain conformance to the Fortran 95 standard, Cray may need to change the behavior of certain the Cray Fortran Compiler features in future releases based upon the outcome of the outstanding interpretations to the standard. The ftn(1) command also invokes the ftnlx(1), ftnlist(1), or ftnlint(1) command (depending on the options used), and a loader, as follows: If you are running the Cray Fortran Compiler on a UNICOS system, the ftn(1) command invokes the loader segldr(1). If you are running the Cray Fortran Compiler on a UNICOS/mk system, the ftn(1) command invokes the loader cld(1). In the most basic case, the ftn(1) command invokes the Cray Fortran Compiler, processes the input files named on the command line, and generates a binary file. The loader loads the binary file and generates an executable output file (the default output file is a.out). The ftnlist(1) and the lister portion of the ftnlx(1) command generate a program s listing file. S

24 Cray Fortran Compiler Commands and Directives Reference Manual In the following simple example, the ftn(1) command invokes the compiler. Option -r s is specified to generate a source listing. File pgm.f is the input file. You run the program by entering the output file name as a command; in this example, the default output file name, a.out, is used. Figure 1, page 2, illustrates this example. % ftn -r s pgm.f %./a.out FTN Command -r s generates a standard listing Cray Fortran Compiler pgm.f Source code pgm.t Lister pgm.lst Listing pgm.o segldr or cld (UNICOS) (UNICOS/mk) stdin Input data a.out Executable program stdout Output data a10132 Figure 1. ftn(1) Command Example You can use the options on the ftn(1) command line to modify the default actions; for example, you can disable the load step. For more information on ftn(1) command line options, see Chapter 2, page 5. 2 S

25 Introduction [1] The Cray Fortran Compiler is one of many software products that form the Cray Fortran programming environment. This environment allows you to develop, debug, and run Fortran codes on your computer system. It includes the following products: Loaders. On UNICOS systems, segldr(1) is your loader. On UNICOS/mk systems, cld(1) is your loader. The ftnlx(1), ftnlist(1), and ftnlint(1) commands generate listings and check for possible errors in Cray Fortran programs. You should use the ftnlx(1) command, unless it does not provide a feature that the ftnlint(1) or ftnlist(1) command offers. The libraries include functions optimized for use on UNICOS/mk systems. Information on the individual library routines can be found in the online man pages for each routine. In addition to online man pages, the following manuals contain printed copies of the library routine man pages and other library information: Application Programmer s Library Reference Manual Scientific Library Reference Manual The Cray Fortran Compiler intrinsic procedures are implemented within the math library (libm), within libfi, and within the compiler itself. The Intrinsic Procedures Reference Manual, contains copies of the online man pages for all the intrinsic procedures. The performance tools, which can help you analyze program performance. The performance tools include apprentice and pat(1). Information on the individual tools can be found in the online man pages for each tool. More information on the MPP Apprentice tool can be found in Introducing the MPP Apprentice Tool. Online documentation utilities. The man(1) command allows you to retrieve online man pages. Prose reference text, such as this manual, can be retrieved online through the WWW browser supported at your site. Contact your support staff for specific information on retrieving information in this manner. A debugger. TotalView includes standard debugging capabilities, such as allowing you to step through code and set breakpoints. It can be used when you invoke the Cray Fortran Compiler and direct it to produce symbol tables. The -g and -G debug options to the ftn(1) command line generate symbol tables. S

26

27 Invoking the Cray Fortran Compiler [2] This chapter describes the ftn(1) command, which invokes the Cray Fortran Compiler. This chapter also describes environment variables used to determine shell characteristics when working with the Cray Fortran Compiler. The ftn(1) man page contains information from this chapter in an abbreviated form. 2.1 Setting Up the Cray Fortran Compiler Programming Environment The installation and configuration of the Cray Fortran Compiler programming environment uses a utility called modules, which is provided and installed as part of the release package. File /opt/ctl/doc/readme was distributed in the release package. It contains information on initializing the module(1) command and initializing the environment. The default programming environment is available to you after you have entered the following command: % module load modules PrgEnv If you have questions on setting up the programming environment, contact your system support staff. 2.2 The ftn(1) Command The ftn(1) command invokes the Cray Fortran Compiler. The syntax of the command is as follows: S

28 Cray Fortran Compiler Commands and Directives Reference Manual ftn [-a alloc] [ -A module_name[,module_name ]...] [-b bin_obj_file] [-c] [-C cifopts] [ -d disable] [-D identifier[= value][,identifier[ =value]]...] [ -e enable] [-f source_form] [ -F] [-g] [-G debug_lvl ] [-i 32] [-I incldir] [-J dir_name] [ -l lib] [-L dir] [-m msg_lvl] [ -M msgs] [-N col] [-o out_file] [ -O opt[,opt]... ] [-p module_site] [-Q path] [-r list_opt] [-R runchk] [ -s size] [-S asm_file] [-t num] [ -T] [-U identifier[, identifier]...] [-v] [ -V] [-Wa"assembler_opt"] [-Wl"loader_opt"] [ -Wr"lister_opt"] [-x dirlist] [-X npes] [ -Z] [--] sourcefile [sourcefile...] Note: Some options are not available on all platforms. If you specify an option that is not supported on your platform, a message is issued and, when possible, compilation continues. Some default values shown for ftn(1) command options may have been changed by your site. See your system support staff for further details a alloc The -a alloc option allows you to specify a storage allocation mechanism. Enter one of the following for alloc: alloc Action pad[n] (UNICOS/mk systems only) Pads all local static storage and most common blocks. This option does not pad common blocks that contain data that has been storage associated with an EQUIVALENCE statement. This option adds padding following each element in a common block. The padding improves single-pe performance by reducing primary and secondary cache conflict between elements within the same common block. If n is not specified, a fixed amount of padding is added after each common block element. The size of the padding that is added depends on the size of the preceding element. If n is specified, padding is added in 8-byte words according to the value you specify. For example, specifying -a pad1 6 S

29 Invoking the Cray Fortran Compiler [2] directs the system to add one 8-byte word after each element in a common block. Specifying -a pad causes the compiler to generate common blocks that do not follow standard sequence association rules. Programs that rely on data in different elements of a common block to be a certain distance apart may behave differently when compiled with -a pad. taskcommon (UNICOS systems only) Converts all common blocks in the compilation to taskcommon blocks. Local variables named in SAVE statements are stored in taskcommon, causing each processor (task) to have a private copy of saved variables. This includes variables initialized in DATA statements or data declaration statements. For a given procedure, a COMMON compiler directive can override this command line specification. For more information on the COMMON compiler directive, see Section 3.7.5, page 133. This option is typically used when using the Message Passing Toolkit (MPT) on UNICOS systems. For more information on MPT, see the Message Passing Toolkit: PVM Programmer s Manual, and the Message Passing Toolkit: MPI Programmer s Manual. Warning: When -a pad is specified, and the compiler automatically generates padding, you must ensure that: The common blocks are declared identically throughout the program and all program files are compiled with -a pad. Arrays in common are always referenced within the range of their declared bounds. The same version of the compiler is used to compile all subroutines and modules using this feature. Failure to follow the preceding rules can cause incorrect program behavior. Typically, cld(1) detects these errors. To ensure that you receive all messages related to this condition, compile with the -Wl"-D msglevel=caution" option, which causes the compiler to generate messages that caution the use of common blocks of different sizes. S

30 Cray Fortran Compiler Commands and Directives Reference Manual A module_name[,module_name]... The -A module_name[,module_name...] option directs the compiler to behave as if a USE module_name statement were entered in your Fortran source code for each module_name. The USE statements are entered in every program unit and interface body in the source file being compiled b bin_obj_file The -b bin_obj_file option disables the load step and saves the binary object file version of your program in bin_obj_file. Only one input file is allowed when the -b bin_obj_file option is specified. If you have more than one input file, use the -c option to disable the load step and save the binary files to their default file names. If only one input file is processed and neither the -b nor the -c option is specified, the binary version of your program is not saved after the load is completed. If both the -b bin_obj_file and -c options are specified on the ftn(1) command line, the load step is disabled and the binary object file is written to the name specified as the argument to the -b bin_obj_file option. For more information on the -c option, see Section 2.2.4, page 8. By default, the binary file is saved in file.o, where file is the name of the source file and.o is the suffix used c The -c option disables the load step and saves the binary object file version of your program in file.o, where file is the name of the source file and.o is the suffix used. If there is more than one input file, a file.o is created for each input file specified. If only one input file is processed and neither the -b bin_obj_file nor the -c options are specified, the binary version of your program is not saved after the load is completed. If both the -b bin_obj_file and -c options are specified on the ftn(1) command line, the load step is disabled and the binary object file is written to the name specified as the argument to the -b bin_obj_file option. For more information on the -b bin_obj_file option, see Section 2.2.3, page 8. If both the -o out_file and the -c option are specified on the ftn(1) command line, the load step is disabled and the binary file is written to the out_file specified 8 S

31 Invoking the Cray Fortran Compiler [2] as an argument to -o. For more information on the -o out_file option, see Section , page C cifopts The -C cifopts option creates one compiler information file (CIF) for each source file. The compiler places each CIF in file.t, where file is the name of the source file and.t is the CIF suffix. The -r option overrides -C option, if both are used. By default, the ftn(1) command does not create a CIF. The -C option creates a CIF, which can be used as input to the ftnlx(1) command. The most common specification is -C a, which writes all CIF information possible d disable and -e enable The -d disable and -e enable options disable or enable compiling options. To specify more than one compiling option, enter the options without separators between them; for example, -e af. Enter one or more of the following args for disable or enable: Table 1. Compiling options args Action, if enabled Operating system 0 Initializes all undefined local stack variables to 0 (zero). If a user variable is of type character, it is initialized to NUL. The variables are initialized upon execution of each procedure. Enabling this option can help identify problems caused by using uninitialized numeric and logical variables. Also see the -e i option. A message is generated if you specify both -e 0 and -e i on the command line; the rightmost option specified overrides the other. Disabled by default. UNICOS UNICOS/mk a Aborts compilation after encountering the first error. Disabled by default. UNICOS A B Generates code necessary to use the MPP Apprentice tool. Disabled by default. Generates binary output. If disabled, inhibits all optimization and allows only syntactic and semantic checking. Enabled by default. UNICOS/mk UNICOS/mk UNICOS UNICOS/mk S

32 Cray Fortran Compiler Commands and Directives Reference Manual args Action, if enabled Operating system d Controls a column-oriented debugging feature when using fixed source form. When enabled, a D or d character in column one causes the compiler to replace the D or d with a blank and treat the entire line as a valid source line. This feature can be useful, for example, during debugging if you want to insert PRINT statements. UNICOS UNICOS/mk f i When disabled, a D or d character in column one is treated as a comment character. Disabled by default. Generates an output file during execution that is suitable for processing by perfview or flowview(1). To use perfview, you must also specify -l perf. See the perftrace(7) or flowtrace(7) man pages for more information. (Disabled) Generates a run-time error when an uninitialized local real or integer variable is used in a floating-point operation or array subscript. This option causes allocated but uninitialized local stack storage to be set to an undefined value. When the -e i option is specified, variables are reset for each invocation of a subprogram. Therefore, a SAVE statement is needed to preserve the value of a variable between invocations. This option does not apply to statically allocated uninitialized variables (data specified on a COMMON, MODULE, or SAVE statement), to dummy arguments, or to ALLOCATABLE arrays. Also see the -e 0 option. A message is generated if you specify both -e 0 and -e i on the command line; the rightmost option specified overrides the other. The loaders offer the -f option for uninitialized statically allocated variables. The -f loader option is related to this feature in that -e i and -f both preset uninitialized data to undefined values; -e i applies to stack data, and -f applies to static data. Also, see the following for more information: For UNICOS systems, see the -f option on segldr(1) For UNICOS/mk systems, see the -D preset= option on cld(1) Disabled by default. UNICOS UNICOS/mk UNICOS UNICOS/mk 10 S

33 Invoking the Cray Fortran Compiler [2] args Action, if enabled Operating system I Treats all variables as if an IMPLICIT NONE statement had been specified. Does not override any IMPLICIT statements or explicit type statements. All variables must be typed. Disabled by default. UNICOS UNICOS/mk j Executes DO loops at least once. Disabled by default. UNICOS L m n o p Allow zero-trip shortloops. This option supports the use of the!dir$ SHORTLOOP directive on shortloops that do not execute (that is, zero-trip shortloops). Disabled by default. Writes module files to modulename.mod rather than to file.o. You cannot mix modulename.mod files with file.o files. System modules work with either option. By default, files are written to the directory from which the ftn(1) command is entered. You can use the -J dir_name option to specify an alternate directory. For more information on the -J dir_name option, see Section , page 18. Disabled by default. Generates messages to note all nonstandard Fortran usage, based on the Fortran 95 standard. Disabled by default. Display to stderr the optimization options used by the compiler for this compilation. Enables double precision arithmetic. UNICOS UNICOS/mk UNICOS UNICOS/mk UNICOS UNICOS/mk UNICOS UNICOS/mk UNICOS When disabled, variables declared on a DOUBLE PRECISION statement and constants specified with the D exponent are implicitly converted to default real type. This causes arithmetic operations and intrinsics involving these variables to have a default real type rather than a double-precision real type. Similarly, variables declared on a DOUBLE COMPLEX statement and complex constants specified with the D exponent are implicitly mapped to the complex type in which each part has a default real type. Specific double precision and double complex intrinsic procedure names are mapped to their single precision equivalents. Double precision arithmetic is not supported on UNICOS/mk systems. Enabled by default. UNICOS/mk S

34 Cray Fortran Compiler Commands and Directives Reference Manual args Action, if enabled Operating system P q Q Performs source preprocessing on file.f[90], file.f[90], file.ftn, or file.ftn but does not compile. When specified, source code is included by #include directives but not by Fortran INCLUDE lines. Generates file.i, which contains the source code after the preprocessing has been performed and the effects applied to the source program. For more information on source preprocessing, see Chapter 5, page 191. Disabled by default. Aborts compilation if 100 or more errors are generated. Enabled by default. Controls whether or not the compiler accepts variable names that begin with a leading underscore (_) character. For example, when specified, the compiler accepts _ANT as a variable name. Enabling this option can cause collisions with system name space (for example, library entry point names). Disabled by default. UNICOS UNICOS/mk UNICOS UNICOS/mk UNICOS UNICOS/mk r Rounds multiplication results. Enabled by default. UNICOS R Compiles all functions and subroutines as if they contained a RECURSIVE keyword. Disabled by default. UNICOS UNICOS/mk S Generates assembly language output and saves it in file.s. When the -e S option is specified on the command line with the -S asm_file option, the -S asm_file option overrides the -e S option. Disabled by default. UNICOS UNICOS/mk 12 S

35 Invoking the Cray Fortran Compiler [2] args Action, if enabled Operating system t Determines the memory allocation method used for automatic variables. An automatic variable is a variable that is not a dummy argument but whose declaration depends on a nonconstant expression (array bounds and/or character length). Storage is allocated for automatic variables and array temporaries upon entry to a procedure. Storage is deallocated upon exit from the procedure. When disabled, automatic variables are allocated memory on the heap. When enabled, the compiler attempts to limit the amount of memory requested from the heap for automatic variables; that is, an attempt is made to allocate storage for them on the stack. Generally, this reduces system call overhead. If not enough stack memory is available, the heap is used. By default, the Cray Fortran Compiler requests 16,000 words of stack space for automatic arrays and array temporaries, with a stack increment size of 8,000 words. Initial size may be increased, and increment size may be increased or decreased through directives passed to the loader. Initial stack and increment sizes can affect performance because of the number of stack overflows that might occur. Multitasking can increase the occurrences of stack overflows and decrease optimal performance. Stack overflow occurrences can be minimized and performance increased by tuning initial stack and increment values. Enabled by default. UNICOS S