apiny Pe LLL et. i UFR ey ae aTCopyright © 1999 Butterworth-Heinemann 4Q_ Amember ofthe Reed Elsevier group All rights reserved. Digital Press™ is an imprint of Butterworth-Heinemann. [No part ofthis publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, - recording, or otherwise, without the prior written permission of the publisher. Recognizing the importance of preserving what has been written, Butterworth- Heinemann prints its books on acid-free paper whenever possible. Butterworth-Heinemann supports the efforts of American Forests and the Global ReLeaf program in its campaign for the betterment of trees, 1000 forests, and our environment. Library of Congress Cataloging-in-Publication Data Etzel, Michael. Digital Visual Fortran programmers guide / Michael Etzel, Karen Dickinson. Pp cm. ISBN 1-55958-218-4 (alk. paper) 1. FORTRAN (Computer program language) I. Dickinson, Karen. IL Title. QA76.73.F25E89 1999 005. 13’3—DC21 98-3242 Bay x cap British Library Cataloguing-in-Publication Data ‘A.catalogue record for this book is available from the British Library. The publisher offers special discounts on bulk orders of this book. For information, please contact: Manager of Special Sales ButterworthHeinemann 225 Wildwood Avenue ‘Woburn, MA 01801-2041 Tel: 781-904-2500 Fax: 781-904-2620 For information on all Butterworth-Heinemann publications available, contact our ‘World Wide Web home page at: http: //waw.bh.com AA 909876543 76.73 Printed in the United States of America ESS £90484078-4Te) MEE airy Meecha Guide ed KAREN DICKINSOao, aayPERPUSTAKAAN UNIVERSITI PUTRA MALA DEC, DEC Fortran, DIGITAL, OpenVMS, VAX, and VAX FORTRAN trademarks of Digital Equipment Corporation. Compaq is registered in the U.S. Patent and Trademark Office. Acrobat and Adobe are registered trademarks of Adobe Systems Incorpora ActiveX, Excel, Microsoft, MS, Microsoft Press, MS-DOS, NT, PowerPo Visual Basic, Visual C++, Visual Studio, Win32, Win32s, Windows, : Windows NT are cither registered trademarks or trademarks of Micro: Corporation in the United States and/or other countries. CRAY isa registered trademark of Cray Research, Inc. IBM is a registered trademark of International Business Machines, Inc. IEEE is a registered trademark of the Institute of Electrical and Electrot Engineers, Inc. IMSL is a trademark of Visual Numerics, Inc. Incel and Pentium are trademarks of Intel Corporation. OpenGL is a registered trademark of Silicon Graphics, Inc. Sun Microsystems is a registered trademark of Sun Microsystems, Inc. Jav a trademark of Sun Microsystems, Inc. UNIX is a registered trademark in the United States and other count licensed exclusively through X/Open Company Ltd. All other trademarks and registered trademarks are the property of th respective holders.> 6 NOV 2h Conten Preface Acknowledgments > Introducting the Microsoft Visual Development Environment il Visual Development Environment Windows 12 Building an Existing Visual Fortran Project (Celsius) 13 Editing CELSIUS.FOR. Building Programs and Libraries 2.1 Overview of Building Projects 2.2 Types of Projects 23 Defining Your Project 24 Errors during the Build Process 25 Compiler Limits 2.6 Running Fortran Applications 27 Porting Projects between x86 and Alpha Platforms 28 Visual Fortran Samples 3 Using the Compiler and Linker from the Command Line 3.1 The Format of the DF Command 3.2 Examples of the DF Command Format 33 Input and Output Files 34 Environment Variables Used with the DF Command 35 Specifying Project Types with DF Command Options 3.6 Redirecting Command-Line Output to Files 3.7 Using the DF Command to Compile and Linkvill Contents 38 39 DF Indirect Command File Use Compiler and Linker Messages 4 Compiler and Linker Options 41 42 43 Compiler Options Linker Options and Related Information 60 60 63 64 144 Microsoft Fortran PowerStation Command-Line Compatibility 178 5 Debugging Fortran Programs 5.1 52 53 54 55 Preparing Your Program for Debugging Debugging the Squares Example Program Viewing Fortran Data Types in the Debugger Using the Array Viewer in the Debugger Locating Run-Time Errors in the Debugger 6 Performance: Making Programs Run Faster 61 62 63 64 65 6.6 67 68 Software Environment and Efficient Compilation Analyze Program Performance Data Alignment Considerations Use Arrays Efficiently Improve Overall /O Performance 185 185 188 199 202 205 209 210 216 222 232 237 Additional Source Code Guidelines for Run-Time Efficiency242 Optimization Levels: the /optimize Option Other Options Related to Optimization 7 Using QuickWin 71 72 73 74 75 76 77 78 Capabilities of QuickWin Comparing QuickWin with Windows-Based Applications Using Win32 with QuickWin Types of QuickWin Programs The QuickWin User Interface USE Statement Needed for QuickWin Applications Creating QuickWin Windows Using Graphics and Character-Font Routines 245 262 269 270 271 271 272 274 277 277 283Contents 79 7.10 TAN 712 7.13 714 TAS Defining Graphics Characteristics Displaying Graphics Output Working with Screen Images Enhancing QuickWin Applications Customizing QuickWin Applications QuickWin Programming Precautions Simulating Nonblocking VO 8 Creating Fortran DLLs 81 8.2 83 Coding Requirements for Sharing Procedures in DLLs Coding Requirements for Sharing Data in DLLs Building and Using Dynamic-Link Libraries 9 Creating Windows Applications 9.1 Coding Requirements for Fortran Windows Applications 9.2 The Visual Fortran Windows Module 9.3 Sample Fortran Windows Applications 9.4 Getting Help with Windows Programming 10 Portability and Design Considerations 10.1. Portability 10.2 Choosing Your Development Environment 10.3 Selecting a Program Type 10.4 Structuring Your Program 10.5 Special Design Considerations 10.6 Using the Special Features of Microsoft Windows I] Using Dialogs IL.1 Using the Resource Editor to Design a Dialog 11.2 Writing a Dialog Application 11.3. Dialog Functions 114 Dialog Controls 115. Using Dialog ControlsContents 12. Drawing Graphics Elements 12.1 Working with Graphics Modes 122 Adding Color 123 Understanding Coordinate Systems 124 Advanced Graphics Using OpenGL 13. Using Fonts from the Graphics Library 13.1 Available Typefaces 13.2 Using Fonts 133 SHOWFONT.F90 Example 14 Using National Language Support Routines 14.1 Single and Multibyte Character Sets 142 National Language Support Library Routines 15. Portability Library 15.1 Using the Portability Library 15.2. Routines for Information Retrieval 15.3 Process Control Routines 15:4 Numeric Routines 15.5 Input and Output with Portability Routines 156 Date and Time Routines 15.7 Error Handling Routines 15.8 Miscellaneous String and Sorting Routines 159 Other Compatibility Routines 16 Files, Devices, and /O Hardware 161 Devices and Files 162 VO Hardware 385 386 395, 399 410 413 414 414 416 Al9 421 421 431 432 432 434 435 436 437 439 439 440 443 443 462Contents 17. Using COM and Automation Objects 17.1 The Role of the Module Wizard 17.2 Using the Module Wizard to Generate Code 4 4 4 17.3 Calling the Routines Generated by the Module Wizard 4 17.4 Additional Information about COM and Automation Objects 477 18 Programming with Mixed Languages 4 18,1 Overview of Mixed-Language Issues 4 182 Exchanging and Accessing Data in Mixed-Language Programmi 499 183 Handling Data Types in Mixed-Language Programming 5 184 Visual Fortran/Visual C++ Mixed-Language Programs 5 185 Fortran/Visual Basic Mixed-Language Programs 5 186 — Fortran/MASM Mixed-Language Programs 5 19. Creating Multithread Applications 5 19.1 Basic Concepts of Multithreading 5 19.2 Writing a Multithread Program 5 19.3 Compiling and Linking Multithread Programs 5 19.4 Other Sources of Information 5 20 Data Representation 5 20.1 Integer Data Representations 5 20.2 Logical Data Representations 5 203 Native IEEE Floating-Point Representations 5 20.4 Character Representation 5 205 Hollerith Representation 5 21 Handling Run-Time Errors 5 2il Default Run-Time Error Processing 5 212 Methods of Handling Errors 5 213 Locating Run-Time Errors 5 214 Using Traceback Information 5 215 Run-Time Environment Variables 5 1 Cont22. The Floating-Point Environment. 22.1 22.2 223 22.4 225 Representing Numbers Contents 601 602 Loss of Precision Errors: Rounding, Special Values, Underflow, and Overflow Setting and Retrieving Floating-Point Status and Control (x86 Only) Handling Arithmetic Exceptions Intel Pentium Floating-Point Flaw (x86 Only) 23 Converting Unformatted Numeric Data 23.1 23.2 233 234 Supported Native and Nonnative Numeric Formats Limitations of Numeric Conversion Methods of Specifying the Data Format Additional Notes on Nonnative Data 24 Using the IMSL Mathematical and Statistical Libraries 24.1 242 243 Using the Libraries from Visual Fortran Library Naming Conventions Using IMSL Libraries in a Mixed-Language Environment 25 Using Visual Fortran Tools 25.1 25.2 253 25.4 25.5 25.6 25.7 25.8 259 25.10 25.11 25.12 25.13 Overview of Visual Fortran Tools Using Tools from the Command Line Setting Up the Command Console Fortran Compiler and Linker MS-DOS Editor Building Projects with NMAKE Resource Compiler Options Managing Libraries with LIB Editing Files with EDITBIN Examining Files with DUMPBIN Editing Format Descriptors with the Format Editor Profiling Code from the Command Line Fortran Tools: FSPLIT and FPR 609 Words. 613 618 622 625 625 628 629 633 635 636 638 639 643 644 647 648 650 651 651 676 680 689 696 698 700 718Contents A Hexadecimal-Binary-Octal-Decimal Conversions B_ Compatibility Information i Bl Compatibility with Microsoft Fortran PowerStation 82 Compatibility with Digital Fortran on Other Platforms 1 ConiPrefac This book is a printed version of the online Visual Fortran Programmers Gu. provided with the DIGITAL™ ‘Visual Fortran (Digital Visual Fortran or sit ply Visual Fortran) Version 6 kit. The “Visual” part of the name “Digital Visual Fortran” comes from its « of the industry-leading visual development environment from Microsof This development environment is also used by the same version of Micros Visual C++® and includes an integrated text editor, source debugger, brows and linker. Visual Fortran is derived from the highly efficient, optimizing Digical tran compiler available on Digital UNIX® and OpenVMS™ Alpha syster Visual Fortran Version 6 provides full support of the Fortran 95 (and pri standards and includes numerous Digital Fortran and Microsoft Fortran Pe erStation extensions. Intended Audience This book assumes you have a working knowledge of the Fortran langua For example, if you see Fortran 90/95 language elements in program exa ples in this book that you are not familiar with, please consult books ab the Fortran 90/95 language to gain a better understanding of such Fort language elements. If you will be creating Visual Fortran applications, you should have ac: to the Visual Fortran documentation provided with your Visual Fortran ‘As needed, you should use this book with the online and printed Visual E tran documentation, including the printed DIGITAL Fortran Language Re ence Manual and the DIGITAL Visual Fortran Getting Started.xvi Preface Organization This book describes the use of Visual Fortran Version 6.0. It contains the fol- lowing chapters and appendixes that describe: > How to build and debug efficient applications: Chapter 1: Introducing the Microsoft Visual Development Environment Chapter 2: Building Programs and Libraries ‘Chapter 3: Using the Compiler and Linker from the Command Line Chapter 4: Compiler and Linker Options Chapter 5: Debugging Fortran Programs ‘Chapter 6: Performance: Making Programs Run Faster > Special coding and related considerations for certain Visual Fortran project types: Chapter 7: Using QuickWin Chapter 8: Creating Fortran DLLs Chapter 9: Creating Windows Applications > Aspects of Fortran programming with Visual Fortran on Windows NT, ‘Windows 98, and Windows 95 systems: Chapter 10: Portability and Design Considerations Chapter 11: Using Dialogs Chapter 12: Drawing Graphics Elements Chapter 13: Using Fonts from the Graphics Library Chapter 14: Using National Language Support Routines Chapter 15: Portability Library Chapter 16: Files, Devices, and I/O Hardware Chapter 17: Using COM and Automation Objects Chapter 18: Programming with Mixed Languages Chapter 19: Creating Multithread Applications > Visual Fortran data types and run-time error handling: Chapter 20: Data Representation Chapter 21: Handling Run-Time Errors Chapter 22: The Floating-Point Environment Chapter 23: Converting Unformatted Numeric DataPreface > The IMSL™ Libraries (Professional Edition) and Visual Fortran tools: Chapter 24: Using the IMSL Mathematical and Statistical Libraries Chapter 25: Using Visual Fortran Tools > Numeric conversion tables and compatibility information: Appendix A: Hexadecimal-Binary-Octal-Decimal Conversions Appendix B: Compatibility Information Typographical Conventions This book uses the following general conventions: When you see this Here is what it means DR LINK, FL32 Uppercase (capital) leters indicate MS®-DOS@-level commands used in the command wi dow. expresion Words in italics indicate placeholders for information that you must supply. A fle-name is example of this kind of information. Italics are also used to introduce new terms. [optional ier] Items inside single square brackets are optional. In some examples, squate brackets are used show arrays. {choicel | choice2} Braces and a vertical bar indicate a choice among two or more items. You must choose one the items unless all ofthe items are also enclosed in square brackets. shal... A horizontal ellipsis (three dots) following an item indicates thae the item preceding the ll can be repeated. In code examples, a horizontal ellipsis means that not ll of the statements shown, !}Comment line This kind of type is used for program examples, program output, and error messages within WRITE (+) ‘Hello & text, An exclamation point marks the beginning of comment in sample programs. Contir & World’ tion lines are indicated by an ampersand (8) after the code atthe end of line to be contin and before the code on the following line. AUTOMATIC, Bold capital letcers indicate DIGITAL Fortran statements, functions, subroutines, and key: INTRINSIC, WRITE words. Keywords area required part of statement syntax, unless enclosed in brackets as explained above. In the sentence, “The following steps occur when a DO WHILE statemei executed,” the phrase DO WHILE is a DIGITAL Fortran keyword. Fortran, Fortran 90, and Fortran 95 Fortran refers to language information that is common to ANSI FORTRAN 77, ANSI/ISC Fortran 90, ANSI/ISO Fortran 95, and DIGITAL Fortran. Fortran 90 refets to language information that is common to ANSI/ISO Fortran 90 and D! TAL Fortran. Fortran 95 refers to language information chat is common to ANSI/ISO Forcran 95 and D TAL Fortran. 1 PrePreface xii When you see this Here is what it means integer This term refers to the INTEGER(KIND=1), INTEGER(KIND=2), INTEGER (INTE- GER(KIND=4)), and INTEGER(KIND=8) data types asa group. real “This term refer to the REAL (REAL(KIND=4)) and DOUBLE PRECISION (REAL(KIND-=8)) data types as a group, complex “This term refers to the COMPLEX (COMPLEX(KIND=4)) and DOUBLE COMPLEX (COMPLEX(KIND=8)) data types a a group. logical This term refers to the LOGICAL(KIND=1), LOGICAL(KIND=2), LOGICAL (LOGI- CAL(KIND=4)), and LOGICAL(KIND: daa types asa group. For More Information About Visual Fortran For up-to-date information about Visual Fortran, please visi tran Web site: heep://wwwdigital.com/fortran/ sc SSAcknowledgments > Acknowledgmen ‘We thank the many talented software engineers on the DIGITAL Visual F tran (DVF) team, who helped us learn about Visual Fortran and patien reviewed this large book for technical accuracy. These talented people hi make complex, difficult work seem interesting and fun (especially Sta meetings). We acknowledge the assistance of Microsoft technical write engineers, and others, especially those associated with Microsoft Visual C and Microsoft Fortran PowerStation. We extend special thanks to the folks Butterworth-Heinemann Publishers as well as William Youngs, Ron Stok Steve Lionel, and others at Compaq Computer Corporation who suppor the creation of this printed book. Mike: I thank the many software engineering giants at the Comy Nashua (NH) facility and fellow writers like Dick Buttlar, whose inforr explanations helped me understand the purpose and uses of various OS a compiler software components. [also thank my wife Kathleen and sons Tos Danny, Colin, and Kyle for making my life meaningful and sharing « ‘mutual interest in science and nature, Special thanks to my parents and wife's parents for their many years of love and support. Karen: Thanks to Digital (now Compaq) for all the experience I've gait here; it's never been boring. I want to thank my parents—my mother for indomitable spirit, and my late father for his sense of humor. Finally, I w to thank my husband Peter, and Blue and Sheba (my pets) for patiently p ting up with my long hours on this project, and looking happy when I fin come home. ot Acknowte dgIntroducing the Microso Visual Development Environmen Digital Visual Fortran (Visual Fortran) uses the same Microsoft® vis development environment as the same version of Microsoft Visual C+ ‘The visual development environment is also known as Microsoft Develo} Studio™, After you install Digital Visual Fortran (Visual Fortran) on your syste you can start the Microsoft visual development environment by performi the following steps: 1. From the Start menu, select Programs. 2, Select Visual Fortran to display the items installed by Setup. 3. Select Developer Studio. This chapter provides an introduction to the visual development envir¢ ment. It provides the following sections: > Section 1.1 Visual Development Environment Windows > Section 1.2 Building an Existing Visual Fortran Project (Celsius) > Section 1.3 Editing CELSIUS.FOR For More Information: > On creating a new project, types of project, defining your project set- tings, and building your application, see Chapter 2 Building Programs and Libraries.Visual Development Environment Windows > On debugging a source file, see Chapter 5 Debugging Fortran Pro- grams. > On developing programs from the command line, see Chapter 3 Using the Compiler and Linker from the Command Line. I.1 Visual Development Environment Windows Figure 1-1 shows a sample of the visual development environment. Se r -_ oles ear Tpomi| [nets psoren for casple Cslewiar presran Denonstrates the use of the QuickWin library. d nonthly calendar for the current nonth ‘walk -E Entesnal Dependence] P Create the project as 4 Quickllin application so -[E) CALNMOD.mod |, i are linked in rogram Calendar USE CALNMOD 'Data Module ISE DELIB _ USE DENIS INTEGER(2) fontnun, nunfonts _INTEGER(4) op type (xycoord) pos haracter*50 lang, country Visual Development Environment Windows ‘The left pane contains a FileView tab and may contain a ClassView or ResourceView tab: > FileView-shows each project and their files associated with the Work- space.~ E NOY 20K Visual Development Environment Windows > ClassView-appears only if Visual C++ is installed. ClassView is not used by Visual Fortran (used by Visual C++ for mixed-language program- ming). > ResourceView-appears if the Workspace uses Resources (such as dialogs and icons). After you open a Workspace, the FileView tab shows the files associat with that Workspace. In the FileView pane of Figure 1-1, there are two fil calendar.£90 and calnmod.£90. In Figure 1-1, calnmod.f90 defines a Fortran 90 module file (a post-cor piled binary file with an extension of .mod) that is used by calendar.9 Because calendar.£90 is dependent on the calnmod.mod file being present, is listed as under External Dependencies. In the right pane of Figure 1-1, the file calendar.£90 is shown in the defa text editor, which uses different colors to identify source comments (greet Fortran standard language elements (blue), and other language text (blac To edit a file listed on the FileView pane, double-click its file name or use t Open item in the File menu. The bottom of Figure 1-1 shows the output pane, which shows text d played from building the project. The output pane has multiple tabs. T output pane Build tab is selected after you open a Workspace and comp one or more project files or build the project. To display the output par select Output from the View menu. A floating window can be moved and has a title bar. To move a floati window, drag its title bar. A docking window is docked (attached) along an edge of the visual develo ment environment window and does not have a title bar. To allow a docking window to float (not be docked) or to allow a floati window to dock along an edge, do one of the following: > Click the appropriate window. > Select the Window menu option Docking View. To specify which visual development environment windows will docked windows and which will be floating windows: 1. In the Tools menu, select Options. 2. Click the Workspace tab. 3, In the Docking View list, click the check box for each window to be dis- played with a docking view. Unchecked boxes indicate floating windows. 1 Chapte4 Building an Existing Visual Fortran Project (Celsius) To cycle through your floating windows in the visual development envi- ronment, hold down the Ctrl key and press Tab. Visual Fortran online documentation is displayed by the Microsoft HTMLHelp Viewer. To use the HTMLHelp Viewer, do one of the following: > Click the Online Documentation item in the Visual Fortran program folder. (To display the Visual Fortran program folder, click Start, click Programs, and click Visual Fortran.) > After you start the visual development environment, in the Help menu, click Contents. > Select a word in a text window and press the F1 key: HTMLHelp Viewer appears in a separate window. This comprehensive online help system lets you to display text by using the contents, locate text either by index keyword or full-text search, print sections, and perform other functions (see Digital Visual Fortran Getting Started). Building an Existing Visual Fortran Project (Celsius) ‘The visual development environment organizes development into projects. A project consists of the source files required for your application, along with the specifications for building the project. Projects are contained in a workspace. A workspace can contain multiple projects. To open and execute the sample project workspace file, Celsius.dsw: . From the File menu, choose Open Workspace. The Open Workspace dialog box appeats, displaying the defaule projects directory (for a new installation, the folders within the My Projects folder). The Celsius project workspace is located in the . . . Common\MSDEV98\ My Projects folder). y .. In the list of files and directories within the My Projects folder, double- click the Celsius folder. The files and directories list now displays the Celsius workspace file. Select the Celsius workspace file, Celsius.dsw. Click the Open button. pe The visual development environment displays the contents of the Cel- sius project in the FileView pane. You can click the plus sign (+) next toEditing CELSIUS.FOR UNIVERSIT! FUT: the Celsius folder to see the contents of the project. In this case, there i only one file, CELSIUS.FOR. . IF needed, update dependencies by clicking Update All Dependencies in the Build menu. Select the appropriate configuration for which depen- dencies need to be updated and click OK. (For projects like CEL- STUS.FOR that have no dependencies, this step is not needed.) v For example, if your application uses Fortran modules, the source file that reference modules with a USE statement have dependencies on thi module (MOD) files they reference. To update these dependencies mean that the source files containing the module definitions (MODULE state ‘ment) need to be compiled before the source files that reference them, by either clicking Update All Dependencies or build the application twice ‘The FileView pane shows the files associated with a project, including any dependencies. 6, From the Build menu, choose Build Celsius.exe. The status of the build is displayed in the Build pane at the bottom o} the screen. 7, From the Build menu, choose Execute Celsius.exe to run the program. A console ouput window appears, displaying the output from the pro- gram. 8. Ifyou want to use the Debugger for this project, see Chapter 5 Debug- ging Fortran Programs. 9. When you are done with this project, select Close Workspace from the File menu. Visual Fortran includes a number of Samples, most of which include a project workspace file (see Section 2.8 Visual Fortran Samples). Editing CELSIUS.FOR The visual development environment text editor and the debugger allow you to edie and debug your projects. The following text assumes you have opened the Celsius Workspace (in the folder. . . Common \MSDEV98\ny Projects) and have built the Celsius project (see Section 1.2 Building an Existing Visual Fortran Project). From the Build menu select Set Active Configuration. Select the Debug configuration. 1 Chapter |