Example 1-2 shows a sample Compaq Fortran main program using free-form source 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 (*,'(BN,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 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 three files might be compiled separately and then linked together, using the following commands:

$ FORTRAN ARRAY_CALC.F90 $ FORTRAN CALC_AVER.F90 $ FORTRAN MAIN.F90 $ LINK/EXECUTABLE=CALC.EXE MAIN, ARRAY_CALC, CALC_AVER

In this sequence of FORTRAN commands:

• Each of the FORTRAN commands creates one object file (OBJ file type).
• The first FORTRAN command creates the object file ARRAY_CALC.OBJ and the module file ARRAY_CALCULATOR.F90$MOD. The name in the MODULE statement (ARRAY_CALCULATOR) in Example 1-3 determines the file name of the module file. The FORTRAN command creates module files in the process default device and directory with a F90$MOD file type.
• The second FORTRAN command creates the file CALC_AVER.OBJ (Example 1-4).
• The third FORTRAN command creates the file MAIN.OBJ (Example 1-2) and uses the module file ARRAY_CALCULATOR.F90$MOD.
• The LINK command links all object files (OBJ file type) into the executable program named CALC.EXE.

To allow more optimizations to occur (such as the inline expansion of called subprograms), compile the entire set of three source files together using a single FORTRAN command:

$ FORTRAN/OBJECT=CALC.OBJ ARRAY_CALC.F90 + CALC_AVER.F90 + MAIN.F90

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

• Compiles the file ARRAY_CALC.F90, which contains the module definition (shown in Example 1-3), and creates its object file and the file ARRAY_CALCULATOR.F90$MOD in the process default device and directory.
• Compiles the file CALC_AVER.F90, which contains the external function CALC_AVERAGE (shown in Example 1-4).
• Compiles the file MAIN.F90 (shown in Example 1-2). The USE statement references the module file ARRAY_CALCULATOR.F90$MOD.
• Creates a single object file named CALC.OBJ.

When you omit the file type on the FORTRAN command line, the FORTRAN command searches for a file with the F90 file type before a file with the FOR or F file type, so you can type the previous command (without file types) as follows:

$ FORTRAN/OBJECT=CALC.OBJ ARRAY_CALC + CALC_AVER + MAIN

Use a LINK command to link the single object file into an executable program:

$ LINK CALC

When you omit the file type on the LINK command line, the Linker searches for a file with a file type of OBJ. Unless you will specify a library on the LINK command line, you can omit the OBJ file type.

1.3.2 Running the Sample Program

If the current default directory contains the file named CALC you can run the program by typing the RUN command followed by its name:

$ RUN CALC

When you omit the file type on the RUN command line, the image activator searches for a file with a file type of EXE (you can omit the EXE file type).

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 using the OpenVMS Debugger, compile and link with the /DEBUG qualifier to request additional symbol table information for source line debugging in the object and executable program files. The following FORTRAN command names the object file CALC_DEBUG.OBJ. The LINK command then creates the program file CALC_DEBUG.EXE with full debugging information:

$ FORTRAN/DEBUG/OBJECT=CALC_DEBUG.OBJ/NOOPTIMIZE ARRAY_CALC + CALC_AVER + MAIN $ LINK/DEBUG CALC_DEBUG

The OpenVMS debugger has a character-cell interface and a windowing interface (available with the DECwindows Motif product). To debug an executable program named CALC_DEBUG.EXE, type the following command:

$ RUN CALC_DEBUG

For more information on running the program within the debugger and the windowing interface, see Chapter 4.

1.4 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 or appropriate commercially published documentation.

Compaq Fortran provides the standard features of a compiler and the OpenVMS operating system provides a linker.

Use a LINK command to link the object file into an executable program.

Table 1-1 lists and describes some of the software tools you can use when developing (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 the Compaq Code Management System (CMS).
Create and modify source files	Use a text editor, such as the EDIT command to use the EVE editor. You can also use the optional Language-Sensitive Editor (LSE). For more information using OpenVMS text editors, see the OpenVMS User's Manual.
Analyze source code	Use DCL commands such as SEARCH and DIFFERENCES.
Build program (compile and link)	You can use the FORTRAN and LINK commands to create small programs, perhaps using command procedures, or use the Compaq Module Management System (MMS) to build your application in an automated fashion. For more information on the FORTRAN and LINK commands, see Chapter 2 and Chapter 3 respectively.
Debug and Test program	Use the OpenVMS Debugger to debug your program or run it for general testing. For more information on the OpenVMS Debugger, see Chapter 4 in this manual.
Analyze performance	To perform program timings and profiling of code, use the LIB$ xxxx_TIMER routines, a command procedure, or the Performance Coverage Analyzer (PCA). For more information on timing and profiling Compaq Fortran code, see Chapter 5.

To perform other program development functions at various stages of program development, use the following DCL commands:

• Use the LIBRARIAN command to create an object or text library, add or delete library modules in a library, list the library modules in a library, and perform other functions. For more information, type HELP LIBRARIAN or see the OpenVMS Librarian Utility Manual.
• Use the LINK/NODEBUG command to remove symbolic and other debugging information to minimize image size. For more information, see Chapter 3.
• The LINK/MAP command creates a link map, which shows information about the program sections, symbols, image section, and other information.
• The ANALYZE/OBJECT command shows whether the object file was compiled by Compaq Fortran 77 or Compaq Fortran as well as the version number used. It also shows other information and does a partial error analysis.
• The ANALYZE/IMAGE command checks information about an executable program file. It also shows the date it was linked and the version of the operating system used to link it.

For More Information:

• On the OpenVMS programming environment, see the Preface of this manual.
• On DCL commands, use DCL HELP or see the OpenVMS DCL Dictionary.

This chapter describes how to use the FORTRAN command to compile your source programs into object files. The following topics are discussed:

• The functions of the compiler ( Section 2.1)
• FORTRAN command syntax, use, and examples ( Section 2.2)
• FORTRAN command qualifiers ( Section 2.3)
• Creating and maintaining text libraries ( Section 2.4)
• Compiler diagnostic messages and error conditions ( Section 2.5)
• Compiler output listing format ( Section 2.6)

The primary functions of the Compaq Fortran compiler are as follows:

• To verify the Compaq Fortran source statements and to issue messages if the source statements contain any errors
• To generate machine language instructions from the source statements of the Compaq Fortran program
• To group these instructions into an object module for the Compaq OpenVMS Linker

When the compiler creates an object file, it provides the linker with the following information:

• The program unit name. The program unit name is the name specified in the PROGRAM, MODULE, SUBROUTINE, FUNCTION, or BLOCK DATA statement in the source program. If a program unit does not contain any of these statements, the source file name is used with $MAIN (or $DATA, for block data subprograms) appended.
• A list of all entry points and common block names that are declared in the program unit. 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.
• Traceback information, used by the system default condition handler when an error occurs that is not handled by the program itself. The traceback information permits the default handler to display a list of the active program units in the order of activation, which aids program debugging.
• A symbol table, if specifically requested (/DEBUG qualifier). A symbol table lists the names of all external and internal variables within a object module, with definitions of their locations. The table is of primary use in program debugging.

For More Information:

On the OpenVMS Linker, see Chapter 3.

2.2 The FORTRAN Command

The FORTRAN command initiates compilation of a source program.

The command has the following form:

FORTRAN [/qualifiers] file-spec-list[/qualifiers]

/qualifiers

Indicates either special actions to be performed by the compiler or special properties of input or output files.

file-spec-list

Specifies the source files containing the program units to be compiled. You can specify more than one source file:

• If source file specifications are separated by commas (,), the programs are compiled separately.
• If source file specifications are separated by plus signs (+), the files are concatenated and compiled as one program.

When compiling source files with the default optimization (or additional optimizations), concatenating source files allows full interprocedure optimizations to occur.

In interactive mode, you can also enter the file specification on a separate line by typing the command FORTRAN, followed by a carriage return. The system responds with the following prompt:

_File:

Type the file specification immediately after the prompt and then press Return.

2.2.1 Specifying Input Files and Source Form

If you omit the file type on the FORTRAN command line, the compiler searches first for a file with a file type of F90. If a file with a file type of F90 is not found, it then searches for file with a file type of FOR and then F.

For example, the following FORTRAN command line shows how file type searching occurs:

$ FORTRAN PROJ_ABC

This FORTRAN command searches for the following files:

1. It searches first for PROJ_ABC.F90.
2. If PROJ_ABC.F90 does not exist, it then searches for PROJ_ABC.FOR.
3. If PROJ_ABC.F90 and PROJ_ABC.FOR do not exist, it then searches for PROJ_ABC.F.

Indicate the Fortran 90 source form used in your source files by using certain file types or a command-line qualifier:

• For files using fixed form, use a file type of FOR or F.
• For files using free form, use a file type of F90.
• You can also specify the /SOURCE_FORM qualifier on the FORTRAN command line to specify the source form (FIXED or FREE) for:
  • All files on that command line (when used as a command qualifier)
  • Individual source files in a comma-separated list of files (when used as a positional qualifier)

For example, if you specify a file as PROJ_BL1.F90 on an FORTRAN command line (and omit the /SOURCE_FORM=FIXED qualifier), the FORTRAN command assumes the file PROJ_BL1.F90 contains free-form source code.

2.2.2 Specifying Multiple Input Files

When you specify a list of input files on the FORTRAN command line, you can use abbreviated file specifications for those files that share common device names, directory names, or file names.

The system applies temporary file specification defaults to those files with incomplete specifications. The defaults applied to an incomplete file specification are based on the previous device name, directory name, or file name encountered in the list.

The following FORTRAN command line shows how temporary defaults are applied to a list of file specifications:

$ FORTRAN USR1:[ADAMS]T1,T2,[JACKSON]SUMMARY,USR3:[FINAL]

The preceding FORTRAN command compiles the following files:

USR1:[ADAMS]T1.F90 (or .FOR or .F) USR1:[ADAMS]T2.F90 (or .FOR or .F) USR1:[JACKSON]SUMMARY.F90 (or .FOR or .F) USR3:[FINAL]SUMMARY.F90 (or .FOR or .F)

To override a temporary default with your current default directory, specify the directory as a null value. For example:

$ FORTRAN [OMEGA]T1, []T2

The empty brackets indicate that the compiler is to use your current default directory to locate T2.

FORTRAN qualifiers typically apply to the entire FORTRAN command line. One exception is the /LIBRARY qualifier, which specifies that the file specification it follows is a text library (positional qualifier). The /LIBRARY qualifier is discussed in Section 2.3.24.

You can specify multiple files on the FORTRAN command line. You can separate the multiple source file specifications with:

• Plus signs (+)
  All files separated by plus signs are concatenated and compiled as one program into a single object file.
  A positional qualifier after one of the file specifications applies to all files concatenated by plus signs (+). One exception is the /LIBRARY qualifier (used only as a positional qualifier).
  Concatenating source files allows full interprocedure optimizations to occur across the multiple source files (unless you specify certain command qualifiers, such as /NOOPTIMIZE and /SEPARATE_COMPILATION).
• Commas (,)
  When separated by commas, the files are compiled separately into multiple object files.
  A positional qualifier applies only to the file specification it immediately follows.
  Separate compilation by using comma-separated files (or by using multiple FORTRAN commands) prevents certain interprocedure optimizations.

If you use multiple FORTRAN commands to compile multiple Compaq Fortran source files that are linked together into the same program, you must be consistent when specifying any qualifiers that effect run-time results. For instance, suppose you do the following:

1. Specify /FLOAT=IEEE_FLOAT on one command line
2. Specify /FLOAT=G_FLOAT on another command line
3. Link the resulting object files together into a program

When you run the program, the values returned for floating-point numbers in a COMMON block will be unpredictable. For qualifiers related only to compilation (such as /LIST and /SHOW), this restriction does not apply.

2.2.3 Creating and Using Module Files

Compaq Fortran creates module files for each module declaration and automatically searches for a module file referenced by a USE statement (introduced in Fortran 90). A module file contains the equivalent of the module source declaration in a post-compiled, binary form.

2.2.3.1 Creating Module Files

When you compile a Compaq Fortran source file that contains module declarations, Compaq Fortran creates a separate file for each module declaration in the current process default device and directory. The name declared in a MODULE statement becomes the base prefix of the file name and is followed by the F90$MOD file type.

For example, consider a file that contains the following statement:

MODULE MOD1

The compiler creates a post-compiled module file MOD1.F90$MOD in the current directory. An object file is also created for the module.

Compiling a source file that contains multiple module declarations will create multiple module files, but only a single object file. If you need a separate object file for each module, place only one module declaration in each file.

If a source file does not contain the main program and you need to create module files only, specify the /NOOBJECT qualifier to prevent object file creation.

To specify a directory other than the current directory for the module file(s) to be placed, use the /MODULE qualifier (see Section 2.3.28).

Note that an object file is not needed if there are only INTERFACE or constant (PARAMETER) declarations; however, it is needed for all other types of declarations including variables.

2.2.3.2 Using Module Files

Once you create a module file, you can copy module files into an appropriate shared or private directory. You reference a module file by specifying the module name in a USE statement (use association). For example:

USE MOD1

By default, the compiler searches for a module file named MOD1.F90$MOD in the current directory.

When selecting a directory location for a set of module files, consider how your application gets built, including:

• Whether the module files need to be available privately, such as for testing purposes (not shared).
• Whether you want the module files to be available to other users on your project or available system-wide (shared).
• Whether test builds and final production builds will use the same or a different directory for module files.

Compaq Fortran allows you to use multiple methods to specify which directories are searched for module files:

• You can specify one or more additional directories for the compiler to search by using the /INCLUDE=directory qualifier.
• You can specify one or more additional directories for the compiler to search by defining the logical name FORT$INCLUDE. To search multiple additional directories with FORT$INCLUDE, define it as a search list. Like other logical names, FORT$INCLUDE can be for a system-wide location (such as a group or system logical name) or a private or project location (such as a process, job, or group logical name).
• You can prevent the compiler from searching in the directory specified by the FORT$INCLUDE logical name by using the /NOINCLUDE qualifier.

To locate modules referenced by USE statements, the compiler searches directories in the following order:

1. The current process device and directory
2. Each directory specified by the /INCLUDE qualifier
3. The directory specified by the logical name FORT$INCLUDE (unless /NOINCLUDE was specified).

You cannot specify a module (.F90$MOD) file directly on the FORTRAN command line.

Suppose you need to compile a main program PROJ_M.F90 that contains one or more USE statements. To request that the compiler look for module files in the additional directories DISKA:[PROJ_MODULE.F90] and then DISKB:[COMMON.FORT] (after looking in the current directory), type the following command line:

$ FORTRAN PROJ_M.F90 /INCLUDE=(DISKA:[PROJ_MODULE.F90],DISKB:[COMMON.FORT])

If you specify multiple directories with the /INCLUDE qualifier, the order of the directories in the /INCLUDE qualifier determines the directory search order.

Module nesting depth is unlimited. If you will use many modules in a program, check the process and system file limits (see Section 1.1).

For More Information:

• On the FORTRAN /INCLUDE qualifier, see Section 2.3.22.
• On an example program that uses a module, see Section 1.3.

You can create include files with a text editor. The include files can be placed in a text library. If needed, you can copy include files or include text library to a shared or private directory.

When selecting a directory location for a set of include files or text libraries, consider how your application is to be built, including:

• Whether the include files or text library needs to be available privately, such as for testing purposes (not shared).
• Whether you want the files to be available to other users on your project or available system-wide (shared).
• Whether test builds and final production builds will use the same or a different directory.
• Instead of placing include files in a directory, consider placing them in a text library. The text library can contain multiple include files in a single library file and is maintained by using the OpenVMS LIBRARY command.

Include files have a file type like other Compaq Fortran source files (F90, FOR, or F). Use an INCLUDE statement to request that the specified file containing source lines be included in place of the INCLUDE statement.

To include a file, the INCLUDE statement has the following form:

INCLUDE 'name' INCLUDE 'name.typ'

You can specify /LIST or /NOLIST after the file name. You can also specify the /SHOW=INCLUDE or /SHOW=NOINCLUDE qualifier to control whether source lines from included files or library modules appear in the listing file (see Section 2.3.40).

You can also include a file with a directory (and optionally the device name) specified with the following form:

INCLUDE '[directory]name' INCLUDE '[directory]name.typ'

If a directory is specified, only the specified directory is searched. The remainder of this section addresses an INCLUDE statement where the directory has not been specified.

Compaq Fortran allows you to use multiple methods to specify which directories are searched for include files:

• You can request that the Compaq Fortran compiler search either in the current process default directory or in the directory where the source file resides that references the include file. To do this, specify the /ASSUME=NOSOURCE_INCLUDE (process default directory) or /ASSUME=SOURCE_INCLUDE qualifier (source file directory). The default is /ASSUME=NOSOURCE_INCLUDE.
• You can specify one or more additional directories for the compiler to search by using the /INCLUDE=directory qualifier.
• You can specify one or more additional directories for the compiler to search by defining the logical name FORT$INCLUDE. To search multiple additional directories with FORT$INCLUDE, define it as a search list. Like other logical names, FORT$INCLUDE can be for:
  • A system-wide location (such as a group or system logical name)
  • A private or project location (such as a process, job, or group logical name)
• You can prevent the compiler from searching in the directory specified by the FORT$INCLUDE logical name by using the /NOINCLUDE qualifier.

To locate include files specified in INCLUDE statements (without a device or directory name), the Compaq Fortran compiler searches directories in the following order:

1. The current process default directory or the directory that the source file resides in (depending on whether /ASSUME=SOURCE_INCLUDE was specified)
2. Each directory specified by the /INCLUDE qualifier
3. The directory specified by the logical name FORT$INCLUDE (unless /NOINCLUDE was specified).