Overview of tools for making the modifications

This section explains how to use the utilities distributed with this package to modify source code for use in 64-bit environments. The details of their operation are given in A.

To start up the EXTREME package, type

% extreme
 
   EXTREME commands are now available -- Version 0.1-0

(if the extreme alias is not set up, try source /star/bin/extreme/extreme.csh). This makes the tools provided by this package available.

One tool is provided for each of the source code conversion tasks described in the previous section:

inscnf:

Inserts CNF_PVAL calls where required in Fortran source code

frepint:

Converts INTEGER to INTEGER*8 in Fortran source code

crepint:

Converts int to INT_BIG in C source code

extmk:

Makes the necessary edits to a package mk file

extmakefile:

Makes some of the necessary edits to a package makefile

Each of these is a normal Unix filter command with usage like cat, so may be given zero, one or two arguments to specify its input and output. Where no change needs to be made, the input is written with no changes to the output. This means that the diff command can be used to see what changes the filters make, by doing something like:

% frepint file.f | diff file.f -

which might give a result like:

94c94
<       INTEGER STATUS             ! Global status
---
>       INTEGER * 8 STATUS         ! Global status
97,98c97,98
<       INTEGER I                  ! Loop variable
<       INTEGER INDF               ! NDF identifier
---
>       INTEGER * 8 I              ! Loop variable
>       INTEGER * 8 INDF           ! NDF identifier

Each of the filters, as well as making changes, draws attention to constructs which might need further attention by writing a message to standard error. In some cases, it will also insert a comment in the modified file where the questionable construct occurs. Such comment lines contain the name of the filter followed by a colon and explanatory text, so given the file watcher.c:

   int watcher( int mins ) {
      printf( "Only %i minutes till coffee break\n", mins );
   }

crepint will do the following:

% crepint watcher.c >fixed/watcher.c
crepint: Format string has %[cdiouxX*] (comment inserted)

and the resulting file fixed/watcher.c will look like this:

INT_BIG watcher( INT_BIG mins ) {
/* crepint: Format string has %[cdiouxX*]                                */
   printf( "Only %i minutes till coffee break\n", mins );
}

which can then be fixed by hand as described in section 3.3.

If the filter thinks it has lost track of the source code in a dangerous way, i.e. that it might be making changes which are likely to invalidate the code, it may exit with an error status, and print a message to standard error to that effect.

Each of the filters has a go at retaining the aesthetic qualities of the code; an attempt is made to respect case usage and spacing conventions in Fortran, padding whitespace is shuffled to keep things at the same column as before if possible, and so on. If replacement text is longer than the original then Fortran lines are broken in hopefully reasonable places, but no line breaks in existing lines are introduced in C.

In general, these filters try to be as helpful as possible, and to make any changes which can reasonably be done automatically. On the whole, they work quite well, but they are not infallible and ought to be used with human supervision. Details of the exact capabilities and behaviour of each of them is given in the command descriptions in Appendix A.

In addition, for each of the source code modifying filters inscnf, frepint and crepint, a driver script is provided. For converting large numbers of files, this is likely to be the most convenient way to proceed. Each driver script runs the filter on a given set of files, summarises any warnings, and writes any files have been changed in a new directory. Any files which did not need alteration are not rewritten. It also performs some crude safety checks that the modified source files seem to have been changed in the right way (for instance, that no changes have been made except for the ones which should have been made, and that changes to Fortran code do not result in lines longer than 72 characters). These checks do not do such careful parsing of the source code as the conversion filters themselves, so they can throw up false positives or false negatives, but they give an extra level of confidence.

The driver script for inscnf is called do-inscnf and is invoked with the files to be converted as command line arguments. For each of its command line arguments it runs inscnf and

• It writes a line to a log file ./inscnf.log saying how many lines were changed. This file does not contain anything requiring attention which is not printed to standard output.
• If and only if some changes were made, it writes the modified copy of the file, under the same name, into a directory called ./inscnf.changed.
• If the filter or the driver script thinks there might be something which needs human attention, it writes a suitable message to standard output. These warning messages can be understood in conjunction with the documentation of the filter, or of the corresponding discussion in section 3.
• It reports a brief summary to standard output of its activities, indicating how many files have changed, and whether any files have gained new dependencies on include files.

Finally it writes a short summary of the run. An excerpt of its output might look like this:

% do-inscnf *.f *.gen
astimp.f:              2 x Last arg %VAL in FTS1_GKEYD
import.f:                  Integer %VAL arg in CCD1_IMFIT?
import.f:                  Last arg %VAL in CCD1_IMFIT
  ...
71 new dependencies on include file 'CNF_PAR'.
71/483 modified files written in ./inscnf.changed.
Logfile is ./inscnf.log.

The other driver scripts, do-crepint and do-frepint, differ in the exact warnings they give, but otherwise work the same way as do-inscnf.

The driver script may occasionally throw out a comment like this:

ndf1_pshdt.f:              Possible error in modifications?

which indicates that there seems to be a difference between the output of the filter and the input plus the expected changes. The checking is done by a quick-and-dirty Perl script called cmp-inscnf (and similarly for the other filters), and if you see this warning you can run this script yourself to get an idea what the problem may have been. The above warning was emitted by do-frepint; investigate as follows:

% cmp-frepint ndf1_pshdt.f
 *** Edit error near line 69?:
 CALL NDF1_SPLDT( STR, 1, LEN( STR ), ' ', -10, F, L, NFIELD, STATUS )
 CALL NDF1_SPLDT( STR, 1, LEN( STR ), ' ', - 10, F, L, NFIELD, STATUS )

from which it is clear that the culprit is some harmlessly inserted whitespace. Note that in order to make these comparisons, the cmp-* scripts deal in a cavalier fashion with formatting, so the source lines may not look very much like the original copies and the line number reporting may not be accurate, but the message should be sufficient to locate the problem. Such ``Possible error in modifications?'' warnings ought to be infrequent, and may often not be indicative of a real problem, but it is as well to investigate them.

Detailed descriptions of the behaviour of the filter programs is given in appendix A