c: RESEARCH J INC. CRAY® COMPUTER SYSTEMS eFT77 REFERENCE MANUAL S,R-0018 r<-w ~ Gopyright© 1986, 1988 by Gray Research, Inc. This manual or parts thereof may not be reproduced in any form unless permitted by contract or by written permission of Gray Research, Inc. RECORD OF REVISION RESEARCH. INC. PUBLICATION NUMBER SR-0018 Eadchhtime this manu~1 is r~vised and reprinted. all changes issued against the previous version are incorporated into the new version an t e new verSion IS assigned an alphabetic level. ~very page chan~ed by a reprint. with revisio~ has the revision level in the lower right hand corner. Changes to part of a page are noted y ~ changl!. bar In the margin directly o~poslte the c~a~ge. A change bar in the margin opposite the page number indicates that the entire page IS new. If the manual IS rewritten. the revIsion level changes but the manual does not contain change bars. Reql:'est.s for copies of C~ay Research. Inc. publications should be directed to the Distribution Center and comments about these publications should be directed to: CRAY RESEARCH. INC. 1345 Northland Drive Mendota Heights. Minnesota 55120 Revision Description April 1986 - Original printing. A September 1986 - Changes are the SUPPRESS directive and the TARGET command. Sections on input/output have been reorganized, with a new introduction in section 7. Other editorial changes have been made. Trademarks are now documented in the record of revision. The previous version is obsolete. B February 1988 - This reprint with revision adds the INCLUDE statement, Loopmark feature, BL and NOBL directives, ALLOC directive, INTEGER directive, I/INDEF option, -v option (UNICOS only), EDN keyword (COS only), and P and w options (CRAY-2 systems only). Section 8, I/O formatting, is reorganized. Descriptions of compiling and the use of operating system features and utilities have been expanded. An appendix on dynamic memory management has been added. The UNICOS operating system is derived from the AT&T UNIX System V operating system. UNICOS is also based, in part, on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. \ CRAY, CRAY-1, SSD, and UNICOS are registered trademarks and CFT, CFT77, CFT2, COS, CRAY-2, CRAY X-MP, CRAY Y-MP, CSIM, HSX, lOS, SEGLDR, and SUPERLINK are trademarks of Cray Research, Inc. ii SR-0018 B PREFACE This is a reference manual for the Cray Fortran compiler CFT77, which operates on all Cray computers and operating systems. The manual includes a complete description of Fortran, CFT77 features, and instructions for using the compiler. An effort has been made to make this manual serve both as a Fortran text and as an introduction to the use of Cray computers, to reduce the need for consulting other manuals and books. This is accomplished as follows: • The use of the Cray operating systems UNICOS and COS is shown for typical programming needs. • Reference material includes coding issues and examples. • Tutorials are included for the benefit of programmers who are not expert in Fortran, such as an introduction to lID in 7.1. • The use of Cray programming tools is introduced: debuggers (DEBUG, 1.1.3 and 1.2.4); program flow tracing (Flowtrace, 1.4.4.1); analysis of program structure and cross references (FTREF, 4.6.1); analysis of program performance (prof and Spy, 10.1.3); and machine performance monitoring (Perf trace, 10.1.4). Change bars appear on some text to indicate the most significant changes from the previous edition of this manual (SR-0018 A). These do not necessarily indicate changes in the CFT77 compiler; many change bars appear on new discussions of existing usage issues. A change bar on the page footer indicates that most of that page has been changed. Of the numerous books about Fortran, the following can be recommended: Merchant, Michael J. Fortran 77: Language and Style. Belmont, CA: Wadsworth, 1981. Introductory text with emphasis on programming style. Ellis, T.M.R. ~ Structured ~pproach to Fortran 77 Programming. Reading, MA: Addison-Wesley, 1981. Introductory text that explains the ANSI standard in detail. Press, William H., et. ale Numerical Recipes: The ~rt of Scientific Programming and Numerical Recipes: Example Book (Fortran). Explains the selection of algorithms for many mathematical purposes. Metcalf, Michael. Fortran Optimization. New York: Academic Press, 1985. Discusses various approaches to improving execution speed. I SR-0018 B iii Two ref~rence cards are available for CFT77: SQ-0138 UNICOS CFT77 Reference Card SQ-0137 COS CFT77 Reference Card The following publications describe the UNICOS operating system: SG-20S2 UNICOS Overview for Users SG-2010 UNICOS Primer SG-20S0 UNICOS Text Editors Primer SQ-20S4 UNICOS vi Reference Card SR-2040 UNICOS Performance Utilities Reference Manual SR-2011 UNICOS User Commands Reference Manual SR-2013 CRAY-2 UNICOS Libraries, Macros and Opdefs Reference Manual SR-Ol12 UNICOS Symbolic Debugging Package Reference Manual The following publications describe Cray software that is not specific to an operating system: SR-Ol13 Programmer's Library Reference Manual SR-0066 Segment Loader (SEGLDR) Reference Manual The following publications describe the COS operating system: SR-0146 COS Performance Utilities Reference Manual SR-OOll COS Reference Manual SR-0012 Macros and Opdefs Reference Manual I iv SR-0018 B CONTENTS PREFACE • • . • • • • • • • . • • • • • • • • • • • • • • • • • •• iii 1. THE CFT77 COMPILER • • • • • • 1-1 1.1 USING CFT77 UNDER UNICOS • • 1-2 1.1.1 Compiling and running a program ••••• 1-2 1.1.2 Issues for successful use of CFT77 1-3 1.1.3 Preparing for debugging under UNICOS • 1-4 1.1.4 The cft77 command under UNICOS •••••• 1-5 1.1.5 Compiler options under UNICOS •••• 1-10 1.2 USING CFT77 UNDER COS • • • • • • • • • • • • 1-13 1.2.1 Preparing your program as a COS job 1-13 1.2.2 Running your job under COS: operations and datasets . • • • • • • 1-14 1.2.3 Using datasets that are specific to your job 1-14 1.2.4 Preparing for debugging under COS 1-16 1.2.5 Issues for successful use of CFT77 • • 1-16 1.2.6 The CFT17 control statement under COS 1-11 1.2.1 Compiler options under COS •••••• 1-23 1.3 CROSS-COMPILING USING THE -C OR CPU= KEYWORD • 1-25 1.4 COMPILER DIRECTIVES • • • • • • . • • • • • • 1-27 1.4.1 Vectorization directives •••••• 1-28 1.4.1.1 Suppressing vectorization (VECTOR and NOVECTOR) 1-28 1.4.1.2 Ignore dependencies (IVDEP) 1-28 1.4.1.3 Vectorizable functions (VFUNCTION) • • 1-29 1.4.1.4 Loops with low trip counts (SHORTLOOP) 1-30 1.4.1.5 Register storage across subprograms (NO SIDE EFFECTS) ••••••• 1-30 1.4.2 Scalar optimization directives • • • • • • • • • 1-31 1.4.2.1 Momentary suppression (SUPPRESS) ••• 1-31 1.4.2.2 Bottom loading of operands (BL/NOBL) • 1-32 1.4.3 Output listing directives •• • • • • • • • • • 1-32 1.4.3.1 Inserting a page break (EJECT) •• 1-33 1.4.3.2 Listing of source program (LIST and NOLIST) •••• 1-33 1.4.3.3 Listing of generated code (CODE and NOCODE) •••• 1-33 SR-0018 B v 1.4 COMPILER DIRECTIVES (continued) 1.4.4 Localized control of command options ••• 1-33 1.4.4.1 Flowtrace (FLOW and NOFLOW) 1-33 1.4.4.2 Array bounds checking (BOUNDS and NOBOUNDS) 1-34 1.4.4.3 Storage allocation (ALLOC) • 1-35 1.4.4.4 Integer length (INTEGER) •• 1-35 1.4.5 Dynamic common block directive (DYNAMIC) • 1-36 1.5 INCLUDE STATEMENT - INSERTING EXTERNAL SOURCE FILES 1-36 1.6 LISTABLE OUTPUT • • • • • • • 1-37 1.7 CROSS-REFERENCE LISTINGS . • • • • • • • • • • • 1-38 1.7.1 Symbol Cross-reference Table ••••••• 1-38 1.7.1.1 Name, address, and type fields 1-39 1.7.1.2 Usage field •••• 1-39 1.7.1.3 Storage field •••••••. 1-39 1.7.1.4 Source program references 1-40 1.7.2 Parameter Table • • • • 1-41 1.7.3 Label Cross-reference Table • • • • 1-41 2. LANGUAGE ELEMENTS AND STRUCTURE 2-1 2.1 ELEMENTS OF THE FORTRAN LANGUAGE • • 2-1 2.1.1 Character set 2-1 2.1.2 Syntactic items • . • • 2-2 2.1.3 Lines . 2-2 2.1.3.1 Initial and terminal lines. 2-3 2.1.3.2 Continuation lines. 2-3 2.1.3.3 Comment lines and embedded comments 2-3 2.1.3.4 Compiler directive lines. 2-4 2.1.4 Statements • • • • • . • • • • • • • 2-4 2.1.4.1 Kinds of statements 2-4 2.1.4.2 Order of statements and lines 2-5 2.1.5 Symbolic names. • • ••••. 2-7 2.2 THE EXECUTABLE PROGRAM • • • • • • • . • • • . • • 2-8 2.2.1 Procedures: subroutines and functions 2-8 2.2.2 Summary of program structure •••• 2-9 2.2.3 Communicating data within programs •.••• 2-11 2.3 PROGRAM UNITS • • • • • • • • • • 2-11 2.3.1 PROGRAM statement •••• 2-12 2.4 FUNCTIONS • • • • • 2-13 2.4.1 Function reference • . • • • • 2-13 2.4.1.1 Data type of a function: reference versus value • • • • • •••• 2-14 2.4.1.2 Execution of functions • • • • • 2-15 2.4.1.3 Order of evaluation • • • • 2-16 2.4.2 Statement functions . • . • . • . 2-16 2.4.2.1 Statement function definition statement 2-17 2.4.3 Intrinsic functions • • • • • • • • • • • 2-19 2.4.3.1 Referencing intrinsic functions 2-20 2.4.3.2 Restrictions . • • • • • • • • • • 2-20 vi SR-0018 B 2. LANGUAGE ELEMENTS AND STRUCTURE (continued) 2.5 SUBPROGRAMS 2-21 2.5.1 External functions· · · · · and· · function· · · · ·subprograms · · · · · · 2-22 2.5.1.1 Restrictions on external functions 2-22 2.5.1.2 Function subprograms 2-22 2.5.1.3 FUNCTION statement · · · · 2-24 2.5.2 Subroutines and subroutine subprograms· · · · · · · · · · 2-25 2.5.2.1 Requirements 2-26 2.5.2.2 CALL statement· ·(subroutine · · · · · reference)· 2-26 2.5.2.3 SUBROUTINE statement 2-28 2.5.3 Altering the transfer of control· between· · · · · · program units 2-28 2.5.3.1 ENTRY ·statement · · · · · · · · · 2-29 2.5.3.2 RETURN statement 2-30 2.6 ARGUMENTS · · · · · · · · · 2-32 2.6.1 Association of arguments · · · · · · · 2-32 2.6.2 Actual arguments for external procedures · · 2-33 2.6.3 Dummy arguments · · · · · · · 2-34 2.6.4 Dummy procedures · · · · · · · 2-35 2.6.4.1 EXTERNAL statement · 2-36 2.6.4.2 INTRINSIC statement · · · · 2-36 3.