next up previous 211
Next: EXTREME cribsheet: Converting for extreme data sets in 99 easy steps
Up: ssn73
Previous: Changes to makefile/mk

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:

Inserts CNF_PVAL calls where required in Fortran source code
Converts INTEGER to INTEGER*8 in Fortran source code
Converts int to INT_BIG in C source code
Makes the necessary edits to a package mk file
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:
<       INTEGER STATUS             ! Global status
>       INTEGER * 8 STATUS         ! Global status
<       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

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

next up previous 211
Next: EXTREME cribsheet: Converting for extreme data sets in 99 easy steps
Up: ssn73
Previous: Changes to makefile/mk

Starlink System Note 73
Mark Taylor
13 August 2001

Copyright © 2001 Council for the Central Laboratory of the Research Councils