HP OpenVMS Systems Documentation

HP Fortran for OpenVMS
User Manual

HP 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 an HP Fortran source file that contains module declarations, HP 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.31).

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.

HP 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), enter 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.2).

For More Information:

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

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 HP 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:

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.43).

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

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.

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

• You can request that the HP 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 HP 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).

HP Fortran provides certain include library modules in the text library FORSYSDEF.TLB. Users can create a text library and populate it with include library modules (see Section 2.4). Within a library, text library modules are identified by a library module name (no file type).

To include a text library module, the INCLUDE statement specifies the name of the library module within parentheses, as follows:

You can specify the library name before the library module name in the INCLUDE statement. For example:

INCLUDE 'MYLIB(PROJINC)'

Use one of the following methods to access a source library module in a text library:

• Specify only the name of the library module in an INCLUDE statement in your HP Fortran source program. You use FORTRAN command qualifiers and logical names to control the directory search for the library.
• Specify the name of both the library and library module in an INCLUDE statement in your HP Fortran source program.
• When the INCLUDE statement does not specify the library name, you can define a default library by using the logical name FORT$LIBRARY.
• When the INCLUDE statement does not specify the library name, you can specify the name of the library using the /LIBRARY qualifier on the FORTRAN command line that you use to compile the source program.

When the library is named in the INCLUDE statement, the FORTRAN command searches various directories for the named library, similar to the search for an include file.

HP Fortran allows you to use multiple methods to specify which directories are searched for named text libraries:

• You can request that the HP Fortran compiler search either in the current process default directory or in the directory where the source file resides that references the text library. To do this, specify the /ASSUME=NOSOURCE_INCLUDE (process default directory) or /ASSUME=SOURCE_INCLUDE qualifier (source file directory).
• 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 compile 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.

The HP 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).

You can specify /LIST or /NOLIST after the library module name. For example:

INCLUDE 'PROJLIB(MYINC)/LIST'

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.43).

For More Information:

• On the /ASSUME=[NO]SOURCE_INCLUDE qualifier, see Section 2.3.7.
• On the /INCLUDE qualifier, see Section 2.3.25.
• On creating and using text libraries, see Section 2.4.

When the INCLUDE statement does not specify the library, you can specify additional text libraries to be searched on the FORTRAN command line or by defining a logical name. The order in which the compiler searches for a library file follows:

• Specify the library name on the FORTRAN command line, appended with the /LIBRARY positional qualifier. The /LIBRARY qualifier identifies a file specification as a text library.
  Concatenate the name of the text library to the name of the source file and append the /LIBRARY qualifier to the text library name (use the plus sign (+)) separator. For example:

  $ FORTRAN APPLIC+DATAB/LIBRARY

  
  Whenever an INCLUDE statement occurs in APPLIC.FOR, the compiler searches the library DATAB.TLB for the source text module identified in the INCLUDE statement and incorporates it into the compilation.
  When more than one library is specified on a FORTRAN command line, the HP Fortran compiler searches the libraries each time it processes an INCLUDE statement that specifies a text module name. The compiler searches the libraries in the order specified on the command line. For example:

  $ FORTRAN APPLIC+DATAB/LIBRARY+NAMES/LIBRARY+GLOBALSYMS/LIBRARY

  
  When the HP Fortran compiler processes an INCLUDE statement in the source file APPLIC.FOR, it searches the libraries DATAB.TLB, NAMES.TLB, and GLOBALSYMS.TLB, in that order, for source text modules identified in the INCLUDE statement.
  When the FORTRAN command requests multiple compilations, a library must be specified for each compilation in which it is needed. For example:

  $ FORTRAN METRIC+DATAB/LIBRARY, APPLIC+DATAB/LIBRARY

  
  In this example, HP Fortran compiles METRIC.FOR and APPLIC.FOR separately and uses the library DATAB.TLB for each compilation.
  If the text library is not in the current process default directory, specify the device and/or directory. For example:

  $ FORTRAN PROJ_MAIN+$DISK2:[PROJ.LIBS]COMMON_LIB/LIBRARY

  
  Instead of specifying the device and directory name, you can use the /ASSUME=SOURCE_INCLUDE and /INCLUDE qualifiers and FORT$INCLUDE logical name to control the directory search.
• After the compiler has searched all libraries specified on the command line, it searches the default user library (if any) specified by the logical name FORT$LIBRARY. When you want to define one of your private text libraries as a default library for the HP Fortran compiler to search, consider using the FORT$LIBRARY logical name.
  For example, define a default library using the logical name FORT$LIBRARY before compilation, as in the following example of the DCL command DEFINE:

  $ DEFINE FORT$LIBRARY $DISK2:[LIB]DATAB $ FORTRAN PROJ_MAIN

  
  While this assignment is in effect, the compiler automatically searches the library $DISK2:[LIB]DATAB.TLB for any include library modules that it cannot locate in libraries explicitly specified, if any, on the FORTRAN command line.
  You can define the logical name FORT$LIBRARY in any logical name table defined in the logical name table search list LMN$FILE_DEV. For example:

  $ DEFINE /GROUP FORT$LIBRARY $DISK2:[PROJ.LIBS]APPLIB.TLB $ FORTRAN PROJ_MAIN

  
  If the name is defined in more than one table, the HP Fortran compiler uses the equivalence for the first match it finds in the normal order of search---first the process table, then intermediate tables (job, group, and so on), and finally the system table. If the same logical name is defined in both the process and system logical name tables, the process logical name table assignment overrides the system logical name table assignment.
  If FORT$LIBRARY is defined as a search list, the compiler opens the first text library specified in the list. If the include library module is not found in that text library, the search is terminated and an error message is issued.
  The logical name FORT$LIBRARY is recognized by both Compaq Fortran 77 and HP Fortran.
• When the HP Fortran compiler cannot find the include library modules in libraries specified on the FORTRAN command line or in the default library defined by FORT$LIBRARY, it then searches the standard text library supplied by HP Fortran. This library resides in SYS$LIBRARY with a file name of FORSYSDEF.TLB and simplifies calling OpenVMS system services.
  SYS$LIBRARY identifies the device and directory containing system libraries and is normally defined by the system manager. FORSYSDEF.TLB is a library of include library modules supplied by HP Fortran. It contains local symbol definitions and structures required for use with system services and return status values from system services.
  For more information on the contents of FORSYSDEF, see Appendix E.

You can specify /LIST or /NOLIST after the library module name. For example:

INCLUDE '(MYINC)/NOLIST'

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.43).

For More Information:

• On the /ASSUME=[NO]SOURCE_INCLUDE qualifier, see Section 2.3.7.
• On the /INCLUDE qualifier, see Section 2.3.25.
• On creating and using text libraries, see Section 2.4.

The output produced by the compiler includes the object and listing files. You can control the production of these files by using the appropriate qualifiers on the FORTRAN command line.

The production of listing files depends on whether you are operating in interactive mode or batch mode:

• In interactive mode, the compiler does not generate listing files by default; you must use the /LIST qualifier to generate the listing file.
• In batch mode, the compiler generates a listing file by default. To suppress it, you must use the /NOLIST qualifier.

For command procedures that compile the application in either batch or interactive mode, consider explicitly specifying /NOLIST (or /LIST).

The compiler generates an object file by default. During the early stages of program development, you may find it helpful to use the /SYNTAX_ONLY or /NOOBJECT qualifiers to prevent the creation of object files until your source program compiles without errors. If you omit /NOOBJECT, the compiler generates object files as follows:

• If you specify one source file, one object file is generated.
• If you specify multiple source files separated by commas, each source file is compiled separately, and an object file is generated for each source file.
• If you specify multiple source files separated by plus signs, the source files are concatenated and compiled, and one object file is generated.

You can use both commas and plus signs in the same command line to produce different combinations of concatenated and separate object files (see the examples of the FORTRAN command at the end of this section).

To name an object file, use the /OBJECT qualifier in the form /OBJECT=file-spec. Otherwise, the object file has the file name of its corresponding source file and a file type of OBJ. By default, the object file produced from concatenated source files has the name of the first source file. All other file specification fields (node, device, directory, and version) assume the default values.

When creating object files that will be placed in an object library, consider using the /SEPARATE_COMPILATION qualifier, which places individual compilation units in a source file as separate components in the object file. This minimizes the size of the routines included by the linker as it creates the executable image. However, to allow more interprocedure optimizations, use the default /NOSEPARATE_COMPILATION.

For More Information:

• On creating and naming object files, see Section 2.2.6.1 and Section 2.3.33.
• On the /SEPARATE_COMPILATION qualifier, see Section 2.3.41.
• On using object libraries, see Chapter 3.

The following examples show the use of the FORTRAN command.

2.2.6.1 Naming the Object File

The following FORTRAN command compiles the HP Fortran free-form source file (CIRCLE.F90) into an object file:

$ FORTRAN /OBJECT=[BUILD]SQUARE /NOLIST [Return]
_File: CIRCLE

The source file CIRCLE.F90 is compiled, producing an object file named SQUARE.OBJ in the [BUILD] directory, but no listing file.