This chapter contains the following topics:

• Section 1.1,Compaq Fortran Programming Environment
• Section 1.2, Commands to Create and Run an Executable Program
• Section 1.3, Creating and Running a Program Using a Module and Separate Function
• Section 1.4, f90 or fort Command and Related Software Components
• Section 1.5, Program Development Stages and Tools
• Section 1.6, Compaq Fortran and Standards It Conforms To

The following aspects of Compaq Fortran are relevant to the compilation environment and should be considered before extensive coding begins:

• To install Compaq Fortran on your Compaq Tru64 UNIX Alpha system, first obtain the UNIX Software Program Library Compact Disc (CD) media. Then perform the installation as described in Compaq Fortran Installation Guide for Tru64 UNIX Systems.
• To install Compaq Fortran on your Compaq Linux Alpha system, use the Compaq Fortran CD-ROM supplied with your kit. Perform the installation using the installation letter in your kit.
• (TU*X ONLY) Once Compaq Fortran is installed on a Compaq Tru64 UNIX Alpha system, you can:
  • Use the f90 command to compile and link programs.
  • Use the online f90(1) reference page and this manual to provide information about the f90 command.
• (L*X ONLY) Once Compaq Fortran is installed on a Compaq Linux Alpha system, you can:
  • Use the fort command to compile and link programs.
  • Use the online fort(1) reference page and this manual to provide information about the fort command.
• Make sure you have adequate stack size, especially if your programs use large arrays as data. Users may be able to overcome this problem by increasing the per-process data limit, using the limit command (C shell) or ulimit command (Korn and Bourne and bash (L*X ONLY) shells) (see csh(1), ksh(1), sh(1), or bash(1)).
  Determine whether the maximum per-process data size is already allocated by checking the value of the maxdsiz parameter in the system configuration file. If necessary, increase its value. Changes to the configuration file do not take effect until the operating system kernel has been rebuilt and the system has been rebooted.
  For example, the following C shell commands check the current stacksize limit and then increase the size to a larger value (if this limit can be increased from your process):

  % limit stacksize stacksize 4096 kbytes % limit stacksize 32676 % limit stacksize stacksize 32676 kbytes

  
  You can also remove the limitation on stacksize:

  % limit stacksize unlimited

  
  Similarly, with the Korn and Bourne and bash (L*X ONLY) shells, use the ulimit command with the -s option (see ksh(1) and sh(1) and bash(1)). For example:

  $ ulimit -s 4096 $ ulimit -s 32676 $ ulimit -s 32676

  
  If you are unable to increase your limits to a value needed by your program, contact your system administrator.

• Make sure you have an adequate process file descriptor limit, especially if your programs use a large number of module files.
  During compilation, your application may attempt to use more module files than your descriptor limit allows. In this case, the Compaq Fortran compiler will close a previously opened module file before it opens another to stay within your descriptor limit. This results in slower compilation time. Increasing the descriptor limit may improve compilation time in such cases.
  Users can view and usually increase the per-process limit on the number of open files by using the limit command (C shell) or ulimit command (Korn and Bourne and bash (L*X ONLY) shell). (See csh(1), ksh(1), sh(1), or bash(1).)
  Determine whether the maximum per-process limit is already allocated by checking the value of the appropriate descriptor parameter in the system configuration file. If necessary, increase its value. Changes to the configuration file do not take effect until the operating system kernel has been rebuilt and the system has been rebooted.
  For example, the following C shell commands check the current limits and then increase the size to a larger value for cases where this limit can be increased from your process:

  % limit descriptor descriptors 100 files % limit descriptor 4096 % limit descriptor descriptors 4096 files

  
  With the Korn, Bourne, and bash (L*X ONLY) shells, you can use the ulimit command with the -n option (see ksh(1), sh(1), and bash(1). For example:

  $ ulimit -n 2048 $ ulimit -n 4096 $ ulimit -n 4096

• Compaq Fortran supports the use of the environment variable TMPDIR to specify a working directory (instead of /tmp ) to contain temporary files created during compilation. Several other environment variables can similarly be used during program execution (see Appendix B).
  If you need to set environment variables frequently, consider setting these in your .login file or appropriate shell initialization file ( .cshrc or .profile ).
• Your source files can be in free or fixed form. The f90 and fort commands recognize certain file suffixes as files containing fixed form or files containing free form. You can also specify an option on the command line to specify the source form. Recognized file suffixes are described in Section 2.1.1.
  A special type of fixed source form is tab form (a Compaq extension). For details about the source forms, see the Compaq Fortran Language Reference Manual.
• Each source file to be compiled must contain at least one program unit (main program, external subroutine, external function, module, block data). Consider the following aspects of program development:
  • Modularity and efficiency
    For a large application, using a set of relatively small source files promotes incremental application development.
    When compiling multiple source files into a single object file with a single f90 (or fort ) command, certain interprocedure optimizations will occur to minimize run-time execution time (unless you specify a lower level of optimization).
  • Code re-use
    Modules, external subprograms, and included files allow re-use of common code. Code used in multiple places in a program should be placed in a module, external subprogram (function or subroutine), or included file.
    When using modules and external subprograms, there is one copy of the code for a program. When using INCLUDE statements, the code in the specified source file is repeated once for each INCLUDE statement.
    In most cases, using modules or external subprograms makes programs easier to maintain and minimizes program size.

For More Information:

• On modules, see Section 2.1.3.
• On the types of subprograms and using an explicit interface to a subprogram, see Chapter 11.
• On performance considerations, including compiling source programs for optimal run-time performance, see Chapter 5.

Example 1-1 shows a short Fortran 95/90 main program using free form source.

Example 1-1 Sample Main Program

! File hello.f90 PROGRAM HELLO_TEST print *, 'hello world' print *, ' ' END PROGRAM HELLO_TEST

To create and revise your source files, use a text editor, such as vi or emacs . On Linux systems, the peco editor is available. For instance, to use vi to edit the file hello.f90 , type:

% vi hello.f90

The following command compiles the program named hello.f90 and automatically uses ld to link the main program into an executable program file named a.out :

% f90 hello.f90

The f90 command (or on Linux systems, the fort command) automatically passes a standard default list of Compaq Fortran Run-Time Libraries to the ld linker. In this example, because all external routines used by this program reside in these standard libraries, additional libraries or object files are not specified on the f90 (or fort ) command line.

If your path definition includes the directory containing a.out , you can run the program by simply typing its name:

% a.out

If the executable image is in your current directory, specify:

% ./a.out

If the executable image is not in a directory in your path definition and it is not in your current directory, then specify its full path. For example:

% /usr/disk5/mcdonald/a.out

1.3 Creating and Running a Program Using a Module and Separate Function

Example 1-2 shows a sample Fortran 95/90 main program using free source form that uses a module and an external subprogram.

The function CALC_AVERAGE is contained in a separately created file and depends on the module ARRAY_CALCULATOR for its interface block.

Example 1-2 Sample Main Program that Uses a Module and Separate Function

! File: main.f90 ! This program calculates the average of five numbers PROGRAM MAIN USE ARRAY_CALCULATOR (1) REAL, DIMENSION(5) :: A = 0 REAL :: AVERAGE PRINT *, 'Type five numbers: ' READ (*,'(F10.3)') A AVERAGE = CALC_AVERAGE(A) (2) PRINT *, 'Average of the five numbers is: ', AVERAGE END PROGRAM MAIN

1. The USE statement accesses the module ARRAY_CALCULATOR. This module contains the function declaration for CALC_AVERAGE (use association).
2. The 5-element array is passed to the function CALC_AVERAGE, which returns the value to the variable AVERAGE for printing.

Example 1-3 shows the module referenced by the main program. This example program shows more Fortran 95/90 features, including an interface block and an assumed-shape array.

Example 1-3 Sample Module

! File: array_calc.f90. ! Module containing various calculations on arrays. MODULE ARRAY_CALCULATOR INTERFACE FUNCTION CALC_AVERAGE(D) REAL :: CALC_AVERAGE REAL, INTENT(IN) :: D(:) END FUNCTION CALC_AVERAGE END INTERFACE ! Other subprogram interfaces... END MODULE ARRAY_CALCULATOR

Example 1-4 shows the function declaration CALC_AVERAGE referenced by the main program.

Example 1-4 Sample Separate Function Declaration

! File: calc_aver.f90. ! External function returning average of array. FUNCTION CALC_AVERAGE(D) REAL :: CALC_AVERAGE REAL, INTENT(IN) :: D(:) CALC_AVERAGE = SUM(D) / UBOUND(D, DIM = 1) END FUNCTION CALC_AVERAGE

1.3.1 Commands to Create the Executable Program

During the early stages of program development, the sample program files in Example 1-2, Example 1-3, and Example 1-4 might be compiled separately and then linked together, using the following commands:

% f90 -c array_calc.f90 % f90 -c calc_aver.f90 % f90 -c main.f90 % f90 -o calc main.o array_calc.o calc_aver.o

In this sequence of f90 (or fort ) commands:

• The -c option (used in the first three commands) prevents linking and retains the .o files.
• The first command creates the files array_calculator.mod and array_calc.o (the name in the MODULE statement in Example 1-3 determines the name of module file array_calculator.mod ). Module files are written into the current working directory.
• The second command creates the file calc_aver.o .
• The third command creates the file main.o and uses the module file array_calculator.mod .
• The last command links all object files into the executable program named calc . To link files, use the f90 command instead of the ld command.

To allow more optimizations to occur (such as the inline expansion of called subprograms), the entire set of three source files can be compiled and linked together with a single f90 command:

% f90 -o calc array_calc.f90 calc_aver.f90 main.f90

The order in which the file names are specified is significant. This f90 command:

• Compiles the file array_calc.f90 , which contains the module definition, and creates its object file and the file array_calculator.mod .
• Compiles the file calc_aver.f90 , which contains the external function CALC_AVERAGE.
• Compiles the file main.f90 (main program). The USE statement references the module file array_calculator.mod .
• Uses ld to link the main program and all object files into an executable program file named calc .

If your path definition includes the directory containing calc , you can run the program by simply typing its name:

% calc

When running the sample program, the PRINT and READ statements in the main program result in the following dialogue between user and program:

Type five numbers: 55.5 4.5 3.9 9.0 5.6 Average of the five numbers is: 15.70000

1.3.3 Debugging the Sample Program

To debug a program with the Compaq Ladebug Debugger, compile the source files with the -g and -ladebug options to request additional symbol table information for source line debugging in the object and executable program files. The following f90 command also uses the -o option to name the executable program file calc_debug :

% f90 -g -ladebug -o calc_debug array_calc.f90 calc_aver.f90 main.f90

The Ladebug debugger has a character-cell interface ( ladebug command) and a windowing interface.

For instance, to use the character-cell interface to debug an executable program named calc_debug on a system running Compaq Tru64 UNIX, type the following command:

% ladebug calc_debug

The Compaq Tru64 UNIX operating system provides the Ladebug debugger and the dbx debugger, both of which can be used to debug Compaq Fortran programs. On Linux Alpha systems, the Compaq Fortran CD-ROM includes the Ladebug debugger.

For more information about Ladebug, see the following Web site:

http://www.compaq.com/products/software/ladebug/

For more information on running the program within the debugger, see Chapter 4, Using the Ladebug Debugger.

1.4 f90 or fort Command and Related Software Components

Compaq Fortran provides the standard features of a compiler and linker. Compaq Fortran also supports the use of preprocessors and other compilers.

Compiling and linking are usually done by a single f90 or fort command. The f90 or fort command allows you to use:

• A preprocessor, if needed, such as cpp or fpp .
• The Compaq Fortran compiler.
• The C compiler by means of the cc command. (On Linux systems, the cc command is a symbolic link to ccc or gcc .)
• The ld linker.

The f90 or fort command invokes a driver program that is the actual user interface to the Compaq Fortran compiler. It accepts a list of command-line options and file names, and causes one or more programs (preprocessor, compiler, assembler, or linker, executed in a sequential manner) to process each file.

After the Compaq Fortran compiler processes the appropriate files to create one or more object files, the driver program passes a list of files, certain options, and other information to the cc (or, on Linux systems, the ccc ) compiler.

The cc compiler processes relevant non-Fortran files and information (including running the cpp preprocessor) and passes certain information (such as .o object files) to the ld linker. The cc compiler applies cpp to files that it recognizes, such as any file with a .c suffic. If cpp is used, it is executed once for each file.

If any program does not return a normal status, further processing is discontinued and the f90 command displays a message identifying the program (and its returned status, in hexadecimal) before terminating its own execution.

See Figure 2-1, Driver Programs and Software Components.

1.4.2 cpp, fpp, and Other Preprocessors

When you use a preprocessor for Compaq Fortran source files, the output files the preprocessor creates are used as input source files by the Compaq Fortran compiler. Preprocessors include:

• The C preprocessor cpp , which is provided with the C compiler on Tru64 UNIX and Linux operating systems. To run cpp before Fortran 90 source files are compiled, specify the -cpp option on the f90 or fort command line. With fixed form source files, you can alternatively name a file using a file suffix of .F to run cpp . With free form source files, you can use a file suffix of .F90 to run cpp .
• The Fortran preprocessor fpp , which is provided with Compaq Fortran on Tru64 UNIX and Linux operating systems. To run fpp before Fortran 90 source files are compiled, specify the -fpp option on the f90 or fort command line. With fixed form source files, you can alternatively name a file using a file suffix of .F to run fpp . With free form source files, you can use a file suffix of .F90 to run fpp .
• Preprocessors provided with optional products, such as the Compaq KAP Fortran/OpenMP performance preprocessor (see Section 5.1.1). Such preprocessors usually need to be run to create the appropriate source file (or files) before you enter the f90 command line.

The Compaq Fortran compiler provides the following primary functions:

• Verifying the correctness of Compaq Fortran source statements and displaying any warnings or error messages.
• Generating machine-level object language instructions from the source statements.
  If the -omp option was specified on Tru64 UNIX systems, the compiler generates code enabled for parallel execution, based on OpenMP language constructs in the input source files.
  If the -hpf option was specified on Tru64 UNIX systems, the compiler generates code enabled for parallel execution, based on HPF language constructs in the input source files.
• Grouping the instructions to generate an object file that can be processed by the linker.

The object file created by the compiler contains information used by the linker, including the following:

• The object file name.
  This is taken from the name specified in the first PROGRAM, SUBROUTINE, FUNCTION, MODULE, or BLOCK DATA statement in the source program. If a program unit does not have any of these statements, the source file name is used, appended with $MAIN (or $DATA for block data subprograms).
• A list of global symbols declared in the object file.
  The linker uses this information when it binds two or more program units together and must resolve references to the same names in the program units. Such global symbols include entry points and common block names.
• A symbol table (if specifically requested by the -g , -g2 , or -g3 options on the f90 command line).
  A symbol table lists the names of all external and internal variables within an object file, with definitions of their locations. The table is of primary use in program debugging.

The file name of the Compaq Fortran compiler is decfort90 , which may appear in certain messages.

1.4.4 Other Compilers

You can compile and link multilanguage programs using a single f90 command.

The f90 command recognizes C or Assembler program files by their file suffix characters and passes them to the cc driver and compiler for compilation. Before compilation, cc applies the cpp preprocessor to files that it recognizes, such as any file with a .c suffix, and passes appropriate files to other compilers or the assembler.

Certain options passed to cc are passed by cc to the ld linker.

1.4.5 Linker (ld)

When you enter an f90 command, the ld linker is invoked automatically unless a compilation error occurs or you specify the -c option on the command line. The linker produces an executable program image with a default name of a.out .

The ld linker provides such primary functions as:

• Adding information for virtual memory allocation in the executable program
• Resolving symbol references among object files
• Assigning values to relocatable global symbols
• Performing relocation

For more information, see ld(1) and your operating system's programmer's guide.

1.5 Program Development Stages and Tools

This manual primarily addresses the program development activities associated with implementation and testing phases. For information about topics usually considered during application design, specification, and maintenance, see your operating system documentation, appropriate reference pages, or appropriate commercially published documentation.

Table 1-1 lists and describes some of the software tools you can use when implementing and testing a program.

Table 1-1 Main Tools for Program Development and Testing

Task or Activity	Tool and Description
Manage source files	Use rcs or sccs to manage source files. For more information, see the Compaq Tru64 UNIX Using Programming Support Tools or the appropriate reference page.
Create and modify source files	Use a text editor, such as vi or emacs . For more information, see your operating system documentation.
Analyze source code	Use searching commands such as grep and diff . For more information, see the Compaq Tru64 UNIX Using Programming Support Tools and the appropriate reference page.
Build program (compile and link)	You can use the f90 command to create small programs, perhaps using shell scripts, or use the make command to build your application in an automated fashion using a makefile. For more information on f90 , see Chapter 2. For more information on make , see the make(1) reference page and the Compaq Tru64 UNIX Using Programming Support Tools.
Debug and Test program	Use Ladebug (or dbx) to debug your program or run it for general testing. For more information on debugging, see Chapter 4.
Analyze performance	To perform profiling of code, use the prof and pixie (TU*X ONLY) programs. The f90 command option needed to use prof is -p (same as -p1 ). To perform call graph profiling, use the gprof tool. The f90 command option needed to use gprof is -pg . Related profiling tools (TU*X ONLY) include the use of feedback files and -cord . For more information on profiling Fortran 90 code, see Chapter 5.
Install program (TU*X ONLY)	Use setld and related commands such as tar . For more information, see the Compaq Tru64 UNIX Using Programming Support Tools.

To view information about an object file or an object library, use the following shell commands:

• The file command shows the type of a file (such as which programming language, whether it is an object library, ASCII file, and so forth).
• The strings command (TU*X ONLY) shows whether the object ( .o ) file was compiled by Compaq Fortran 77 or Compaq Fortran and, if it was, the version number used.
• The nm command shows symbol table information, including the identification field of each object file.
• The size command shows the size of the code and data sections.

For more information on these commands, see the appropriate reference page or the operating system's programmer's guide.

To perform other program development functions at various stages of program development:

• Use the ar command to:
  • Create an archive object library.
  • Maintain the object modules in the library.
  • List the object modules in the library.
  • Perform other functions.
  
  Use ranlib to add a table of contents to the object library for linking purposes. For more information, see ar(1) or the Compaq Tru64 UNIX Programmer's Guide.
• Use f90 or ld , not the ar command, to create shared libraries on Tru64 UNIX systems. For more information, see Section 2.6 and the Compaq Tru64 UNIX Programmer's Guide.
• Use fort or ld , not the ar command, to create shared libraries on Linux systems. For more information, see Section 2.6.
• Use the strip command to remove symbolic and other debugging information to minimize image size. For more information, see strip(1).
• Use the fsplit command to split a multiple routine Fortran file into multiple, individual files. For more information, see fsplit(1).

For More Information:

• On the Compaq Tru64 UNIX programming environment, see the Compaq Tru64 UNIX Programmer's Guide and the Compaq Tru64 UNIX Using Programming Support Tools.

Compaq Fortran conforms to American National Standard Fortran 95 (ANSI X3J3/96-007) ¹ and American National Standard Fortran 90 (ANSI X3.198-1992) ², and includes support for the OpenMP Fortran 1.1 Application Program Interface ³ and the High Performance Fortran Language Specification ⁴.

The ANSI committee X3J3 is currently answering questions of interpretation of Fortran 95 and Fortran 90 language features. Any answers given by the ANSI committee that are related to features implemented in Compaq Fortran may result in changes in future releases of the Compaq Fortran compiler, even if the changes produce incompatibilities with earlier releases of Compaq Fortran.

Compaq Fortran also includes support for programs that conform to the previous Fortran standards (ANSI X3.9-1978 and ANSI X3.0-1966), the International Standards Organization standard ISO 1539-1980 (E), the Federal Information Processing Institute standard FIPS 69-1, and the Military Standard 1753 Language Specification.

Compaq Fortran provides a number of extensions to the Fortran 95/90 standards. Compaq Fortran extensions to the Fortran 95/90 standards are generally provided for compatibility with Compaq Fortran extensions to the ANSI FORTRAN-77 standard and to support the High Performance Fortran (HPF) Language Specification.

When creating new programs that need to be standard-conforming for portability reasons, you should avoid or minimize the use of extensions to the Fortran 95/90 standards. Extensions to the Fortran 95/90 standards are identified visually in the Compaq Fortran Language Reference Manual, which defines the Compaq Fortran language.