# Compaq Fortran
User Manual for
Tru64 UNIX and
Linux Alpha Systems

Previous | Contents | Index

# Chapter 1
Getting Started

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

# 1.1 Compaq Fortran Programming Environment

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.

# 1.2 Commands to Create and Run an Executable Program

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` .

## 1.3.2 Running the Sample Program

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.

## 1.4.1 f90 or fort Driver Program

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.

## 1.4.3 Compaq Fortran Compiler

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.

# 1.6 Compaq Fortran and Standards It Conforms To

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

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.

Note #### 1 This is the same as International Standards Organization standard ISO/IEC 1539-1:1997 (E). #### 2 This is the same as International Standards Organization standard ISO/IEC 1539:1991 (E). #### 3 See the specification at `http://www.openmp.org/specs/`. #### 4 See High Performance Fortran Language Specification, Version 1.1, Technical Report CRPC-TR-92225, Center for Research on Parallel Computation, Rice University, Houston, Texas, USA.

Previous | Next | Contents | Index