.AUTOPARAGRAPH
.NHY
\\
.CENTER
^RATFIV ^VERSION 2.1
.SKIP 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 _._G_T_., _._L_T_., 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:
.LIST
.LE;^ABILITY TO SPECIFY A FORMAT STATEMENT INSIDE
^^READ, WRITE, ENCODE,\\ AND ^^DECODE\\ STATEMENTS;
.LE;^CONSISTENT LINE CONTINUATION USING THE UNDERLINE CHARACTER;
.LE;^PRODUCTION OF PROPERLY INDENTED UPPER CASE ^FORTRAN CODE WITH
COMMENTS PASSED THROUGH;
.LE;^OPTIONAL OUTPUT OF ^FORTRAN 77 CODE WITH THE /^F77 SWITCH
(however this switch produces valid code for ^V^A^X ^Fortran 77 only);
.LE;^ADDITION OF A ^^/SYMBOLS\\ SWITCH TO THE COMMAND LINE
TO OPTIONALLY READ THE ^^SYMBOLS\\ FILE;
.LE;^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.);
.LE;^EVALUATED AND UNEVALUATED ARGUMENTS IN MACROS;
.LE;^CORRECT LINE NUMBER REPORTING;
.LE;^EXIT WITH ERROR STATUS IF AN ERROR OCCURS DURING COMPILATION;
.LE;^USE OF CHARACTER CONSTANTS IN CASE LABELS;
.LE;^NUMEROUS BUG FIXES;
.LE;^COMPREHENSIVE DOCUMENTATION;
.LE;^RATFIV KEYWORDS NEED NOT APPEAR AT THE BEGINNING OF
A SOURCE LINE IN ORDER TO BE RECOGNIZED.
.END LIST
 ^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:
.list
.le;The documentation has been revised, particularly the section
on defining macros;
.le;Hollerith strings may be optionally outputted instead of
quoted strings;
.le;The initialization and increment parts of FOR loops may
have more than one statement in them;
.le;Macro definitions may have commas in them;
.le;Arguments to the __len and __include macros may have commas in them;
.le;The special macro arguments _$_& and _%_& are replaced by ALL
the arguments passed to the macro;
.le;Octal constants may be inserted in STRING variables;
.le;The number of special escaped characters in the STRING statement
has been increased and these characters may also be used with
the CASE statement;
.le;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;
.le;Macros may be defined which emulate the __ifdef, __ifndef,
__enddef, and __elsedef macros
(see the file RATFOR.SYM for an example of this);
.le;Some unused CONTINUE statements in the Fortran output have been
eliminated.
.end list
.skip 2
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:
.list
.le;The dot (.) character is not allowed in macro names anymore.
This change was made because it could cause problems when a macro name
appeared next to a valid dot character, as in "if (status.eq.EOF)".
.le;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.
.le;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.
.le;The NEWLINE character was changed from carriage-return to line feed
for compatibility with Ratfor preprocessors.
.end list
.skip 2
Some of the bug fixes are (there weren't too many bugs):
.list
.le;include statements insert their input into the input stream
correctly when they appear in a macro;
.le;Error line number reporting is REALLY correct this time;
.le;Literal Fortran code is allowed in macros.
.end list
.skip 2
 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.
.skip 2
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.
.skip 2
 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.
\\
.skip 4
^TO BUILD ^RATFIV, DO
.SKIP 1
^^@BUILD\\
.SKIP 1
^DOCUMENTATION IS IN THE FILE ^^RATFIV.DOC\\.
.SKIP 1
^^
 Before building Ratfiv on IAS systems, change the first line in RATFIV.TKB
from
.skip 1
.indent +5
RATFIV/FP=
.skip 1
to
.skip 1
.indent +5
RATFIV/FP/RW=
.skip 1
This builds Ratfiv without any read-only sections.
 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.
\\
.SKIP 2
 ^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:
.LIST
.LE;^DELETE THE ^^MAXBUF\\=512 OPTION.
.LE;^CHANGE ^^ACTFIL=8\\ TO ^^ACTFIL\\=7
.LE;^CHANGE ^^UNITS=10\\ TO ^^UNITS=9\\
.END LIST
^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.
.SKIP 2
^SEND COMMENTS, PROBLEMS, ETC. TO:
.SKIP 1
.LM +7
.NOFILL
^WILLIAM ^P. ^WOOD, ^JR.
^INSTITUTE ^FOR ^CANCER ^RESEARCH
7701 ^BURHOLME ^AVE.
^PHILADELPHIA, ^P^A. 19111
(215) 728 2760
