fpt Reference: File Handling

fpt and WinFPT Reference Manual - Command-line Commands

| SimCon Home | Ref Manual Home |

File Handling

fpt_project_setup

The utility fpt_project_setup uses the commands described on this page to set up an initial fpt project. Large Fortran projects may have complex directory structures, multiple programs, and duplicate include files and sub-programs. Users may need to modify the fsp scripts which it creates to handle special cases.

fpt_project_setup has been implemented under Linux (including Linux for the Raspberry Pi) and MacOS in fpt version 4.318 and later. The utility is not yet available under Windows.

Reading Files

Format of an fpt Command

An fpt command, written in an operating system terminal window, is of the form:

$ fpt arg1, arg2, arg3 ...

Where the arguments may be:

Fortran file names
Specification (fsp) files, with the filename extension .fsp
fpt commands, written as quoted strings and introduced by the character %, or for Windows, by the character /

Specification (fsp) files contain lists of Fortran files, fpt commands and further specification files written one to a line.

fpt commands may also contain Fortran file names.

INCLUDE Statements

INCLUDE statements in the Fortran code contain Fortran file names. The names are usually written as quoted strings, for example:

INCLUDE 'include_file.inc'

#include "include_file_name.h"

(Note that fpt supports CPP syntax).

Finding and Opening Files

fpt must find and open the named files. In all cases the file names are handled in exactly the same way.

File name extensions

If the file name extension is specified that will always be the extension which fpt will use unless the extension is edited by the editing commands described below.

If no file name extension is specified fpt will first attempt to open the file with no extension. If this fails, fpt will add the file name extension specified by the commands:

Primary files are those which contain programs, modules, sub-modules, top-level subroutines and functions or block data. They are submitted directly to the Fortran compiler. Include files are those referenced in INCLUDE or #include statements. The command INPUT FILE NAME EXTENSION specifies the same extension for both primary and include files.

For example, the program:

! ***************************************************************** ! defext.for 6-Jan-26 John Collins ! ***************************************************************** PROGRAM defext INCLUDE 'standard.for' INCLUDE 'non_standard.odd' INCLUDE 'no_ext' INCLUDE 'default_ext' WRITE (*,*) in_standard WRITE (*,*) in_non_standard WRITE (*,*) in_no_ext WRITE (*,*) in_default_ext END PROGRAM defext ! **************************************

with the INCLUDE files:

! standard.for CHARACTER(*),PARAMETER :: in_standard = "From standard.for" ! End of standard.for

! non_standard.odd CHARACTER(*),PARAMETER :: in_non_standard = 1 "From non_standard.odd" ! End of non_standard.odd

! no_ext Note there is no file name extension CHARACTER(*),PARAMETER :: in_no_ext = "From no_ext.for" ! End of no_ext

! default_ext.for CHARACTER(*),PARAMETER :: in_default_ext = 1 "From default_ext.for" ! End of default_ext.for

is processed by the fsp file:

! defext.fsp 6-Jan-26 John Collins % input directory: "../original_source" % input file name extension: ".for" ! Could also use % include input file name extension: ".for" % output directory ../fpt_output % primary output file name extension: ".f90" % include output file name extension: ".i90" FPTMAIN:free_format.fsp % overwrite changed files ! Note no extension defext ! End of defext.fsp

fpt finds and opens the files as described above. In the example we have written the code in fixed format (though it is converted to free format in the fpt output). This has been done because users are most likely to need to handle file name formats in migration, and because the defaulting of the file name extension is most commonly found under VMS.

The project, named defext, will be found in the examples directory in the fpt distribution.

Directories (Folders)

If the file name specification contains the directory, which may be an absolute rooted directory or a relative directory, this is the directory where the file will be sought, except:

that the file name may be edited by the editing commands described below;
the directories specified in INCLUDE statements may be ignored This is specified by the command: IGNORE DIRECTORIES IN INCLUDE STATEMENTS. This command is useful in migration where the syntax of file specifications may differ from that of the current processor.

If no directory is specified, or the directory has been ignored, The directory or directories where the file will be sought are specified by the commands:

These commands are position-sensitive in the fsp files or the command line. They apply to the file specifications which follow them. An example, part of the fsp file for WRF, is shown below:

% primary input search path: - "../modified_source/WRFV3/external/io_grib2/g2lib/utest" - "../UCAR_clean_build/WRFV3/external/io_grib2/g2lib/utest" % include input search path: - "../modified_source/WRFV3/inc" - "../UCAR_clean_build/WRFV3/inc" !!! test_g2lib.F ! Separate program not in main build % primary input search path: - "../modified_source/WRFV3/external/io_grib_share" - "../UCAR_clean_build/WRFV3/external/io_grib_share" % include input search path: - "../modified_source/WRFV3/inc" - "../UCAR_clean_build/WRFV3/inc" % primary input file name extension: ".F" io_grib_share.F % primary input search path: - "../modified_source/WRFV3/external/io_int" - "../UCAR_clean_build/WRFV3/external/io_int" % include input search path: - "../modified_source/WRFV3/inc" - "../UCAR_clean_build/WRFV3/inc" % add to include search path: "../UCAR_clean_build/WRFV3/external/ioapi_share" % add to include search path: "../UCAR_clean_build/WRFV3/external/io_grib_share" % primary input file name extension: ".F90" !!! diffwrf.F ! Separate program io_int.F90

Editing Input File Names

The file names input to fpt may be edited. The editing commands are applied after ignoring directories in INCLUDE statements if this is specified, and before the files are sought. They are executed in the order in which they are written. The editing commands are:

The editing commands are cumulative. A string inserted by one command may be modified by a subsequent command. However, they are not recursive. Thus, for example, if "/projects" is replaced by "/projects/hwrf" fpt will not find "/projects" again and go on adding "/hwrf" until it runs out of memory.

Text library references are an issue in migration from VMS. The library specification is removed leaving the file name target.

The ASSIGN and DEFINE commands emulate VMS logical names. The name defined must end in a : character.

A small section of an fsp script, which was part of a VMS to Linux migration, is shown below:

%EDIT INPUT FILE NAMES : LOWER CASE %EDIT INPUT FILE NAMES : REMOVE WHITE SPACE %EDIT INPUT FILENAMES : REPLACE '(' BY '' %EDIT INPUT FILENAMES : REPLACE ')/list' BY '.inc' %EDIT INPUT FILENAMES : REPLACE ')' BY '.inc'

Writing Files

Non-Fortran Output Files

The list file, which contains reports and diagnostics, is written to the current working directory. It has the base name of the first fsp or Fortran file specified on the command line and the file name extension fpl.

The coverage sequence decriptor file, generated by the command INSERT COVERAGE is written to the current working directory.

The include file fpt_n_subprograms.h generated by the command: MONITOR ENTRIES AND EXITS is written to the main fpt output directory.

Makefiles, generated by the command MAKE MAKEFILE are written to the main fpt output directory.

Fortran Output Files

The Fortran files output by fpt usually correspond one-to-one with the Fortran input files. There are exceptions:

Fortran files marked in an fsp file as system library files are never output.
Fortran files marked as library files are output only if they are needed to build the program or programs in the project.
Files which, after processing, contain no code as a result of the commands such as DELETE UNUSED SUB-PROGRAMS and CHANGE COMMONS TO MODULES are not output.
Include files inserted in-line after the command INSERT INCLUDE FILES INLINE are not output.
New Fortran files are created by the commands such as: CHANGE COMMON TO MODULE, MOVE COMMON BLOCK TO A SINGLE INCLUDE FILE etc. The handling of these files is described below.

Fortran File Name Extensions

The file name extensions of the Fortran files written by fpt are controlled by the commands:

In addition they may be edited by the command EDIT OUTPUT FILE NAMES.

The command OUTPUT FILE NAME EXTENSION will write the same extension for primary and include files. This is not recommended. Sooner or later an include file will be submitted to a Fortran compiler. There will be no PROGRAM statement, so it will be a default program, and no END statement. The result will be compiler-specific.

The command KEEP FILE NAME EXTENSIONS preserves the original extensions. This is the command set up by the utility fpt_project_setup. Please take care that the output directories differ from the input directories. By default fpt will not overwrite files and instead changes the output file name, but there is a danger of overwriting.

If no extension is specified primary files are written with the extension fpt and include files with the extension fpi. This is safe, in that nothing is likely to be overwritten by accident, but some compilers will not accept files with these extensions. It may be useful to keep these extensions while setting up a complex directory structure. If anything goes wrong it is easy to find and delete any files which land in the wrong place.

Fortran Output Directories

The directories to which Fortran output files are written are controlled by the commands:

Output directories may also be edited as described below.

The command KEEP OUTPUT DIRECTORIES allows the used to keep the entire directory structure of a project. Common practice is to use this command but to edit the base directory for the output files. For example:

% ouput directory: ../fpt_output % keep directories % edit output file names: replace "original_source" by "fpt_output" % edit output file names: replace "modified_source" by "fpt_output"

Note the OUTPUT DIRECTORY command in this example. If fpt creates a new Fortran file there is no original directory from which the KEEP OUTPUT DIRECTORIES command can operate. This command provides a default. When first setting up this command structure it is a good idea to leave the output file name extensions as ,fpt and .fpi in the first pass so that nothing is overwritten by accident.

If no output directory is specified the output files are written to the current working directory.

Editing Output File Names

Output file names may be edited by the commands:

In all cases, if the file names are referenced in the Fortran code, for example in INCLUDE statements, the references in the code are also changed.

Overwriting Output Files

By default fpt will not overwrite existing files. This may be changed by the commands:

If files are not to be overwritten and a name conflict arises between an fpt output file and an existing file the fpt output file is renamed by appending an integer number to the file base name.

The command OVERWRITE CHANGED FILES is useful when a program is built with a makefile. Unchanged files are not overwritten and therefore do not need to be recompiled.