




                     Ratfiv Version 2.1


     Ratfiv is a structured Fortran  preprocessor  providing
SWITCH,  IF  - ELSE, WHILE, FOR, DO, REPEAT - UNTIL, STRING,
and BREAK and NEXT constructs.  Also supported  are  INCLUDE
files,   DEFINE  for  symbolic  constants  and  macros  with
arguments, conditional compilation, formats in read,  write,
encode, and decode statements, use of >, <, etc.  instead of
.GT.,  .LT.,  etc,  and  the  RETURN  VALUE   construct   in
functions.

     Ratfiv  was  developed   from   the   Ratfor   compiler
distributed   by   Lawrence   Berkley  Labs;   versions  are
available for  VAX  VMS  and  RSX/IAS  systems.   The  major
enhancements in Ratfiv are:

      1. Ability to specify a format statement inside  READ,
         WRITE, ENCODE, and DECODE statements;

      2. Consistent line continuation  using  the  underline
         character;

      3. Production of properly indented upper case  Fortran
         code with comments passed through;

      4. Optional output of Fortran 77 code  with  the  /F77
         switch (however this switch produces valid code for
         VAX Fortran 77 only);

      5. Addition of a /SYMBOLS switch to the  command  line
         to optionally read the SYMBOLS file;

      6. Output of quoted strings  or  optionally  hollerith
         strings  (quoted  string output allows Ratfiv to be
         used with DEC Fortran OPEN statements, the  Fortran
         77 CHARACTER data type, etc.);

      7. Evaluated and unevaluated arguments in macros;

      8. Correct line number reporting;

      9. Exit with error status if an  error  occurs  during
         compilation;

     10. Use of character constants in case labels;

     11. Numerous bug fixes;

     12. Comprehensive documentation;

     13. Ratfiv keywords need not appear at the beginning of
         a source line in order to be recognized.


                                                      Page 2



     This version of Ratfiv may  be  used  if  you  want  to
compile  the  Ratfiv source to the other programs written in
Ratfiv on this tape.  

     Version 2 of Ratfiv has a few enhancements, bug  fixes,
and changes since Version 1.  The enhancements are:

      1. The documentation has  been  revised,  particularly
         the section on defining macros;

      2. Hollerith  strings  may  be  optionally   outputted
         instead of quoted strings;

      3. The initialization and increment parts of FOR loops
         may have more than one statement in them;

      4. Macro definitions may have commas in them;

      5. Arguments to the _len and _include macros may  have
         commas in them;

      6. The special macro arguments $& and %& are  replaced
         by ALL the arguments passed to the macro;

      7. Octal  constants  may   be   inserted   in   STRING
         variables;

      8. The number of special  escaped  characters  in  the
         STRING  statement  has  been  increased  and  these
         characters  may  also  be  used   with   the   CASE
         statement;

      9. Quoted strings are consistent in  that  double  and
         single  quoted  strings  may  both  have  double or
         single quotes in them, even in the STRING and  CASE
         statements;

     10. Macros may be defined  which  emulate  the  _ifdef,
         _ifndef, _enddef, and _elsedef macros (see the file
         RATFOR.SYM for an example of this);

     11. Some unused  CONTINUE  statements  in  the  Fortran
         output have been eliminated.



A few changes were made  that  could  cause  incompatibility
with Version 1.  I am sorry for these changes, but they were
necessary for my peace of mind.  I expect this version to be
pretty stable.  The changes are:

      1. The dot (.) character is not allowed in macro names
         anymore.   This  change  was  made because it could


                                                      Page 3



         cause problems when a macro name appeared next to a
         valid dot character, as in "if (status.eq.EOF)".

      2. The BREAK statement may not be used to break from a
         SWITCH statement anymore.  This change was made for
         compatibility with Ratfor preprocessors and to make
         BREAK consistent with the NEXT statement.  It was a
         bad idea in the first place  to  have  BREAK  break
         from a SWITCH statement.

      3. Brackets ([]) have no special meaning within  macro
         definitions anymore.  The use of brackets in macros
         was too obscure to justify them.  In any case there
         was little need for them.

      4. The   NEWLINE   character    was    changed    from
         carriage-return to line feed for compatibility with
         Ratfor preprocessors.



Some of the bug fixes are (there weren't too many bugs):

      1. include statements  insert  their  input  into  the
         input stream correctly when they appear in a macro;

      2. Error line number reporting is REALLY correct  this
         time;

      3. Literal Fortran code is allowed in macros.




     The file "RATFOR.SYM" contains some  macro  definitions
which,  if  placed  at  the  front  of  the  Software  Tools
"SYMBOLS." file, make Ratfiv  largely  compatible  with  the
latest  (Spring 1981 VAX sig tape) version of Software Tools
Ratfor available from Joe Sventek.  I have compiled about 15
thousand  lines  of  his code with Ratfiv;  the only problem
was that some variables named "string" ("string" is a Ratfiv
keyword)  had  to  be  renamed.   Software Tools Ratfor code
should be compiled with Ratfiv's "/SYMBOLS" switch, and with
Ratfiv's  "/HOLLERITH"  switch for compatibility on the VAX.
This is the only place where  the  "/HOLLERITH"  switch  has
been  needed  so far.  Note that shortening of long names is
not available in Ratfiv;  I have not  checked  whether  long
names are used in the RSX/IAS version of the Software Tools.
Also, the "$(" and "$)" brackets for use with macros are not
available  in Ratfiv;  there seems to be little use for them
in Ratfiv.




                                                      Page 4



Version 2.1 notes:

     A help file is included for the  VAX  VMS  distribution
(RATFIV.HLP);  place it in your system help file.

     A slight modification has been made to  the  processing
of  character strings in the "string" and "case" statements.
When expanding strings with the escaped characters  "@e"  or
"@n"  in  them,  Ratfiv  now  attempts  to use the currently
defined meanings of EOS and NEWLINE,  respectively,  whereas
in  Version  2.0  it used the values which were defined when
the compiler was built (these values are 0  and  10  on  DEC
systems).   If  EOS  and/or  NEWLINE  is  not  defined  when
processing a string or case label, then the  default  values
of 0 and 10 are used, as before.

     Similarly, when "EOS" and/or  "character"  is  defined,
Ratfiv  uses these values for the terminating character of a
string and the string data type, respectively, otherwise  it
uses the default values (0 and BYTE), as before.

     These changes are documented in the section on  strings
in RATFIV.DOC.



     I expect that Ratfiv will be fairly stable from now on,
although  it's  possible  I  will  add  enhancements.   I am
interested in hearing about and fixing bugs, however.  




To build Ratfiv, do

@BUILD

Documentation is in the file RATFIV.DOC.


     Before building Ratfiv on IAS systems, change the first
line in RATFIV.TKB from

     RATFIV/FP=

to

     RATFIV/FP/RW=

This builds Ratfiv without any read-only sections.


                                                      Page 5



     The "@BUILD" file builds Ratfiv and also  Macro,  which
is  just  the  macro  preprocessor portion of Ratfiv.  Input
passes through the macro  processor  unchanged  except  that
macros  are  expanded.  There is no documentation for Macro,
however the form of the command line is  like  Ratfiv's  and
the   macros  are  the  same,  except  that  "define"  isn't
available;   use  "_macro"  instead.   Also,  the  dot   (.)
character is legal in macro names.

     There is a system-wide file called "SYMBOLS." which can
be  read by specifying "/SYMBOLS" on the Ratfiv command line
(see the section,  "USING  RATFIV"  in  "RATFIV.DOC").   The
default location of this file may be changed by changing the
define for "USER$BIN" in the "SYMBOLS." file and  rebuilding
the  compiler  from  scratch.   Most  people won't need this
file, however, so you can just leave  it  on  the  directory
where  Ratfiv  is  located,  since  Ratfiv  first checks the
default directory for the "SYMBOLS." file before looking for
the system-wide file.  



     If you are using the FOR compiler instead of F4P  on  a
PDP11,  be  sure to compile the Fortran sources with the -SN
switch.  Ignore the errors in IO.FTN;  they are  in  modules
which  aren't  used by Ratfiv.  You will also have to change
the RATFIV.TKB file as follows:

      1. Delete the MAXBUF=512 option.

      2. Change ACTFIL=8 to ACTFIL=7

      3. Change UNITS=10 to UNITS=9

These changes reduce the number  of  file  inclusion  levels
allowed  by  Ratfiv  by one, but the task would be too large
otherwise.  If the task is still too large, you  can  reduce
ACTFIL  to  6 and UNITS to 8, but don't reduce them any more
as then you will not be able to include any files.

     After reducing the number  of  file  inclusion  levels,
then  after  successfully  building Ratfiv you should change
the define for NFILES in the file "MACSYM." to  reflect  the
changes  (i.e  subtract  1  or  2  from the defined value of
NFILES), and then rebuild the compiler from scratch.


Send comments, problems, etc.  to:

       William P. Wood, Jr.
       Institute For Cancer Research
       7701 Burholme Ave.
       Philadelphia, PA. 19111


                                                      Page 6



       (215) 728 2760



