Migration

Commands for Software Migration

Software migration is the conversion of an existing code from one compiler, operating system or environment to another. Often the code is moved from a legacy system, such as a Gould-SEL (Encore) or VMS machine to modern equipment, and the objective may be to convert the code to standard-conforming Fortran 95 or later. However, migration is not necessarily a one-way process. There may be a requirement that the code continues to run on the legacy machine, and it may be necessary to move test codes back to the legacy system for regression testing. The changes required for migration are therefore implemented as a suite of separate commands, and users should select those appropriate for their migration projects. The available commands are described here.

Coverage Analysis

INSERT COVERAGE	Test coverage shows: the proportion of a code which is actually exercised by a program test suite; the areas of the code which are not exercised; in the analysis made by fpt, separately, the proportions of the code which only handles exceptions, and the proportions of the main code paths which are exercised.
EXCEPTION	Optionally, this command is written in the code to mark exception handlers. It is assumbed that code sections reached from, for example, ERR= handlers in I/O statements are exception handlers.
MAXIMUM COVERAGE COUNT	Sets a maximum value for the 4-byte coverage counters to prevent the risk of overflow.

Run-time Trace and Compiler Validation

INSERT RUN-TIME TRACE

Statements are added to the code to trace program execution and to capture every scalar numeric value (LOGICAL, INTEGER, REAL or COMPLEX) to a trace file as it is computed. This may be used to investigate error conditions, and to validate the performance of the code under different compilers. The trace file may be used to eliminate numerical drift, and therefore to expose coding errors and compiler bugs (see "The Removal of Numerical Drift from Scientific Models", Collins J, Farrimond B, Flower D, Anderson M and Gill D. 2013, arXiv:1304.3260 [cs.SE]).

RESOLVE AMBIGUOUS FLOW

Fortran statements which contain two or more function evaluations may be ambiguous. The order of evaluation of the functions is not defined by the Fortran standard, and different compilers make different choices of order. This may lead to inconsistent results, and causes spurious error reports from the run-time trace facility. This command modifies the code so that the order of evaluation is uniquely defined.

Record-replay - Capturing and replaying I/O transactions and selected sub-program interfaces

INSERT RECORD REPLAY	Statements are added to the code to capture all terminal and file input, and to capture the values returned from selected sub-programs. The data are captured to file, and the program may be re-run, replaying the captured data instead of executing the I/O statements and calling the sub-programs. The different I/O units and sub-programs may be selected independently for replay. This technique has been used to set up reproducible test runs and to validate the performance of different versions of software libraries.
RECORD/REPLAY INTERFACE	Specifies that the named subroutine or function is to be handled as a record/replay interface. The values returned by the routine are captured to file, and the values from file file may be read into the program instead of the values computed when the file is replayed.
DEFAULT LENGTH OF RECORD REPLAY STRINGS	Specifies the length of character strings to be recorded by the record/replay mechanism in situations where the length cannot be inferred from context.
NUMBER RECORD REPLAY CALLS FROM ...	Every record/replay statement inserted into the code has a unique number which is used to check that the program flow has not changed between the recording and replay runs. This command optionally specifies a starting value for the unique numbers for each file. It prevents all of the record/replay numbers from changing when small changes are made to the code. Otherwise, when the record/replay numbers change, the entire program has to be rebuilt.

Adding a Run-time Command-line Interpreter to a Program

BUILD ACCESS DATABASE	This command creates a database, written as Fortran DATA statements, which describes the data types, attributes and COMMON block addresses of every object in a COMMON block in the program. The database supports a facility to inspect or change any variable or array element in the program at run-time. The program may be halted to make the change, or the change may be introduced through a shared memory interface as the code is run. This command has been used to set up an intractive control environment for several flight simulators and for a real-time radar control system. It can effectively emulate the run-time access to COMMON blocks provided by the Gould-SEL (Encore) MPX systems.
BUILD NAMELIST FOR COMMON BLOCKS	A NAMELIST is created which contains every variable in a COMMON block in the entire program. This may be used to create an alternative mechanism to inspect and change variables in COMMON at run-time.
BUILD NAMELIST AS ...	Specifies whether the NAMELIST built by the BUILD NAMELIST FOR COMMON BLOCKS command is to be built as a single statement or as a sequence of separate statements, one for each variable.
BUILD NAMELIST TO CHECK/IGNORE DEFAULT SIZES	Specifies whether separate variables are to be identified in building a NAMELIST when two or more variables have the same names and attributes, but one has a defined data kind or size and another inherits the kind or size from the system defaults.
COMMON BLOCK NAMELIST NAME	Specifies the name of the NAMELIST.

Optimisation and Restructuring for Special Architectures

EXPAND INLINE	User-written subroutines and functions are expanded in-line. All routines may be expanded in-line, or specific routines or calls may be selected.
INLINE	Is written in the code to mark calls or sub-programs which are to be expanded.
UNWIND ALL / MARKED LOOPS	Specifies that all DO loops, or selected DO loops are to be unwound. Loops are unwound only if the range and stride are constants.
UNWIND	Is written in the code to mark loops to be unwound.
UNWIND INNER / OUTER LOOPS FIRST	Specifies the order of loop unwinding.
SCALARISE / SCALARIZE	All array references with constant bounds are replaced by references to scalar variables. This command was implemented to support a special parallel computer architecture. It is used in combination with in-line expansion and loop unrolling.

Re-organising COMMON Blocks

MOVE COMMON BLOCKS TO A SINGLE INCLUDE FILE MOVE COMMON BLOCKS TO SEPARATE INCLUDE FILES	COMMON statements, and all declarations of the variables in them, are moved to INCLUDE files. A separate INCLUDE file may also be created for Fortran PARAMETER statements.
BUILD DATA DICTIONARY	All local variables are moved to a COMMON block, and all COMMON blocks are moved to a single INCLUDE file. This file then contains a complete specification of the static memory used by the program.

Making a Makefile

MAKE MAKEFILE MKMF

A Makefile is generated to build the program. The Makefile contains all of the Fortran MODULE and INCLUDE file dependencies. Provision is made for separate compilation rules to be applied to different files. The Makefile is compatible with gnu make.

Obfuscation

HIDE NAMES

Comments are removed from the code and variable names are replaced by meaningless strings. Intrinsic function names are left in place, and optionally, the names of global objects so that the code may be compiled against external libraries.

Restructuring and Renaming - Systematic Code Changes

Restructuring and Renaming

Many commands are available to make systematic changes to code. Declarations may be modified, for example, to declare all variables and to enforce IMPLICIT NONE, to change the way that data kinds and sizes are declared, and to substitute declaration keywords. There are commands to re-structure IF statements and CASE statements and to change the handling of statement labels. The commands are listed here. If you are unable to find the change which you require, please also check the commands for software migration.