





                      A DESCRIPTION OF RATIONAL FORTRAN (RATFOR)


            HISTORY.

            RATFOR  was   developed  by   Kernighan  and  Plauger  of  Bell
            Laboratories and Whitesmiths, Inc.,  respectively,  in  the mid
            1970's  as  a  FORTRAN  upgrade.    The  C  language  was under
            development by Kernighan and  Ritchie at  about the  same time.
            Both RATFOR and C are heavily derivative of the B language.  As
            a result, RATFOR  is  similar  to  C  in  as  many  ways  as is
            reasonably   possible.     Addison-Wesley  published  "Software
            Tools", by Kernighan and  Plauger, in  1976; this  book was the
            original  document  defining  the  RATFOR  langauge.   A users'
            group, the Software Tools Users' Group (STUG), sprang up around
            the Berkeley  UNIX community  and released a shell for non-UNIX
            operating systems.   This  shell, called  the Virtual Operating
            System  (VOS),  was  very  UNIX-like  and  was  written in STUG
            RATFOR.  A full RATFOR compiler was developed at the University
            of Arizona as the Y language. in the late 1970's.

            Better availability  of UNIX  after the mid 1980's, VOS use has
            declined, and STUG is inactive in 1989.  The better  utility of
            C for OS applications has displaced RATFOR for OS applications,
            and the Y langauge has been replaced by C at  the University of
            Arizona.   Current RATFOR  usage is primarily as an engineering
            applications language.  It is used  on mainframe  UNIX systems,
            CP/M, and  MS-DOS.   RATFOR has  been approved  as a structured
            language for military applications in a few Air Force programs.
            Workstation usage is implemented by using RATFOR source code on
            the workstation and uploading FORTRAN source code for execution
            on mainframes.

            MISOSYS  Ratfor  was  introduced  in  1986.   Included with the
            packages for the Model 4 and MS-DOS are a variety of nontrivial
            engineering  applications  and  support  for use of RATFOR as a
            workstation tool.  MS-DOS  RATFOR  includes  a  special  set of
            routines to  pass comments  to mainframes  and to provide upper
            case FORTRAN for older CDC mainframes.   2.0  was introduced as
            an upgrade to MISOSYS RATFOR in the summer of 1988.

            SUPPORT.

            Mainframes:  RATFOR has been a standard UNIX (TM) utility since
            about 1976, and is  supplied with  UNIX operating  systems from
            Bell  Laboratories  and  Mt.  Xinu.   Mt. Xinu, which vends the
            Berkeley UNIX 4.2, also  provides an  extended RATFOR,  EFL, or
            extended  FORTRAN  language.    Bell  Laboratories and Mt. Xinu
            RATFOR  is  accompanied  by  another  utility,   STRUCT,  which
            provides RATFOR source code from FORTRAN source code.

            The  original  RATFOR  for  minis  is  available  on  tape from
            Addison-Wesley of  Reading,  MA  on  9-track  tape  in  IBM 360
            format.   STUG will  provide tapes  for RATFOR and an extensive





            RATFOR library, including the  UNIX-like  VOS  shell,  a RATFOR
            version  of  YACC,  and  a  software  configuration  management
            system.

            Microcomputers:   Ports  of  UNIX  to  microcomputers, provided
            under  Bell  Laboratories  license  from other vendors, such as
            XENIX, do not  provide  RATFOR.    MISOSYS,  Inc.  provides and
            supports a  highly developed RATFOR for MS-DOS and for the TRS-
            80 Model 4.  MISOSYS RATFOR is also supported on  Compuserve on
            page LDOS.

            Public Domain:  A subset of RATFOR as defined in Software Tools
            was released into  the  public  domain  by  individuals  at the
            University   of   Wisconsin.      This   PD   RATFOR  has  seen
            implementation as the CP/M PD RATFOR and as  a C  port that has
            seen fairly  wide distribution.  This RATFOR does not implement
            the full set of keywords does not support  macros beyond simple
            text replacement.

            LANGUAGE DEFINITION.

            General:   The RATFOR language is defined informally, primarily
            by  the  UNIX  documentation   and  secondarily   by  the  STUG
            implementation.   RATFOR is usually implemented as a translator
            to FORTRAN and is  used  with  an  otherwise  unrelated FORTRAN
            compiler.    Thus,  in  addition  to  the  RATFOR keywords, all
            FORTRAN keywords are de facto additional keywords in RATFOR.

            As implemented  in  the  MISOSYS  version,  RATFOR  consists of
            twelve keywords  and fifteen intrinsic (built-in) macros.  Four
            alphanumerics are predefined and reserved by  RATFOR as special
            macros.   The pound sign character "#", the braces "{", "}" and
            the semicolon are special characters in RATFOR.   The backslash
            is  a  special  escape  character  when  used in literals.  The
            underline  character  is  used  as  a   statement  continuation
            character.

            The "#"  character marks  the end of the line and the beginning
            of a comment field on any line.  The braces  are used  to group
            statements together  for parsing program flow exactly as in the
            C language.

            RATFOR code is limited to 80 columns so  that all  text will be
            displayed on  an 80  column monitor  without wraparound or 135-
            character mode.  Blanks are significant in RATFOR  and are used
            as delimiters.   The  macros are case-sensitive.  The intrinsic
            macros are recognized only when invoked  using all  lower case,
            and the  reserved macro  alphanumerics are recognized only when
            invoked using all upper  case.    This  is  in  accordance with
            RATFOR  tradition  of  using  all  lower case in writing source
            code, except for  user-defined  macros,  which  are  written in
            upper case so that they are easily seen in listings.






            Keywords:    The  twelve  RATFOR keywords fall into two groups,
            logical  program  flow  control   or  branching,   and  looping
            commands.  The looping keywords are

               for -- identical to C "for"
               while -- identical to C "while"
               repeat -- identical to C "do"
               do --  compatible with FORTRAN "DO" without statement label.

            The statement label is optional with the use  of "do"  for ease
            in porting FORTRAN programs.

            The branching keywords of RATFOR are

               if -- identical to C "if"
               else -- used only with "if"
               switch -- similar to C "switch"
               cswitch -- identical to C "switch"
               case -- used with "switch" and "cswitch"
               default -- used with "switch" and "cswitch"
               break -- identical to C "break"
               next -- identical to C "continue"

            RATFOR has an extension to "break" and "next".  An option is to
            append an integer constant, as in "break 2".   This multi-level
            "break" and  "next" allows  an efficient  implementation of any
            flow chart without the use of  GO  TO,  something  that  is not
            possible in any other commonly used program language.

            The  operation  of  the  RATFOR  "switch"  differs  from  the C
            "switch" in an essential  characteristic:    whenever  a "case"
            condition is  met, it  alone is executed and program flow exits
            the "switch" construct.  The "break" keyword does  not interact
            with the RATFOR "switch" keyword.  Using the RATFOR "switch" is
            simpler than using the C keyword, but a degree of generality is
            lost.     MISOSYS  RATFOR   provides  the  nonstandard  keyword
            "cswitch" to provide this  generality in  RATFOR.   The keyword
            "cswitch" interacts  with the  keyword "break"  as if it were a
            loop; the multi-level "break" counts "cswitch" as one level.

            The keyword "cswitch" is  available as  a nonstandard extension
            in MISOSYS RATFOR.

            MACROS.

            General:  RATFOR macros are interpreted as a preprocessor step.
            The preprocessor is incorporated  into a  single pass  with the
            translator  in  MISOSYS  RATFOR  and  its  use and operation is
            transparent to the user.

            A RATFOR macro can appear at  any  point  in  the  source code.
            Macros  are  case  sensitive.    If  the  user  needs to use an
            intrinsic macro name for another purpose,  he can  use an upper





            case  character  in  his  source  code  or remove the intrinsic
            macro.

            RATFOR interprets each  macro  and  pushes  back  the resulting
            string to  the input  to the  preprocessor, so  that if another
            macro is invoked, it will also be invoked.  This  allows nested
            macro calls.

            Intrinsic  Macros:    The  fifteen intrinsic RATFOR macros fall
            into six categories.   They are  macro definition,  source code
            file   control,    string   manipulation,   syntax   extension,
            conditional compilation, and default  definitions.    The macro
            definition macro is

               define -- macro definition.

            The source code file control macro is

               include -- generalization of compiler "INCLUDE".

            The text manipulation macros are

               incr -- interprets string as integer, increments
               lentok -- provides length of alphanumeric string
               substr -- provides access to substrings
               ifelse -- performs conditional checks
               arith -- provides access to integer arithmetic.

            The  syntax  of  "substr"  is  "substr(str,cstart,clen)".   The
            result is a substring  of the  string "str"  beginning with the
            character  "cstart".    The  number of characters in the result
            will  be  equal  to  the  value  of  "clen"  or  the  remaining
            characters in "str", whichever is smaller.  The argument "clen"
            can be omitted and all the  remaining characters  in "str" will
            be used.   If  "cstart" is larger than the length of "str", the
            result will  be a  null string,  or a  string with  a length of
            zero.

            The  syntax  of  "ifelse" is "ifelse(cstr1,cstr2,ostr1,ostr2)".
            The two strings cstr1  and  cstr2  are  compared;  if  they are
            equal, ostr1  results, otherwise  ostr2 results.  The result is
            pushed back onto the input data stream so  that the  result can
            include a macro invocation.  A null string can be used as cstr1
            or   cstr2   by   simply   omitting   that   argument,   as  in
            "ifelse(XX,,O1,O2)".  If the string XX is not defined, or if it
            is defined as a null string, the output will be O1.

            The syntax extension macros are

               read -- provides or generalizes short form of "read"
               print -- provides or generalizes short form of "print"
               return -- allows "return(<expression>)" in functions.

            The conditional compilation macros are






               undefine -- removes macro definition
               ifdef -- includes lines of source if macro is defined
               ifnotdef -- complement of "ifdef"
               elsedef -- "else" for "ifdef" and "ifnotdef"
               enddef -- end of conditional code block.

            The default definitions are

               READLUN=* -- default I/O unit in "read"
               PRINTLUN=* -- default I/O unit in "print"
               ARB=* -- used in declaring arrays in subprograms
               YES=.true. -- actually a convenience definition
               NO=.false. -- actually a convenience definition.

            Since FORTRAN 66 is  used on  the TRS-80  Model 4,  the default
            definitions  for  that  version  of  RATFOR are 1, 3, and 1 for
            READLUN,  PRINTLUN,  and  ARB,  respectively.    And additional
            default  definition  is  CHARACTER,  which is translated to the
            "byte" declaration supported by CP/M fortran.

            Notice that most macros have one or more  arguments enclosed in
            parentheses.  Exceptions are "define" and "include", which have
            a free form format as an option, and "read" and  "print", which
            are extensions to the FORTRAN 77 syntax.

            User-Defined  Macros:    The  "define" statement can be used to
            define macros at any point in the RATFOR  source program.   The
            macro is  in effect  from that point in the source code forward
            and is not recognized prior to its definition.

            Most user-defined macros are used for  simple text replacement,
            as in

               define PI 3.1415927

            but macros  with arguments  are also allowed.  For example, the
            macro STR1  can be  used to  simplify declaration  of arrays of
            characters:

               define(STR1,[character $1,(incr(lentok($2))])

            once defined, usage such as

            STR1(nam,xxx)

            appears to the FORTRAN compiler as

                  character nam(4)

            which simplifies the use of strings of characters.  For Model 4
            usage, "character" should be in upper  case so  that the "byte"
            data type  will be used.  Macros defined in this way are useful
            for extending the syntax of the language.






            Very little checking is done in  macro interpretation, allowing
            almost unlimited  freedom in macro definition.  This means that
            recursive  macros,  or  macros  which  invoke  themselves,  are
            possible.   Errors in writing such macros can result in endless
            loops, which are manifested as an  apparent hang  in the RATFOR
            preprocessor stage.  Recursive macro loop control is done using
            the "ifelse"  macro to  decide whether  the recursion  is to be
            continued.    MISOSYS  RATFOR  provides  a  dump  of  the macro
            recursion stack in a walkback format  to aid  in debugging such
            macros.   See the  MISOSYS RATFOR manual and the book "Software
            Tools" for  detailed  instructions  in  writing  complex RATFOR
            macros.

            LITERALS.

            RATFOR literals  can be expressed using either single quotes or
            double quotes.  When a  double  quote  is  needed  in  a string
            defined using  double quotes  in the  literal, the double quote
            character is preceded by a backslash.   The  backslash will not
            be carried  through unless  it is also preceded by a backslash.
            This is important in giving MS-DOS pathnames in  literals.  For
            example, "c:\dir1\filename.ext" becomes 'c:dir1filename.ext' to
            the FORTRAN  compiler,  while  "c:\\dir1\\filename.ext" becomes
            'c:\dir1\filename.ext'.   The double backslash is not necessary
            when the  RATFOR "include"  statement is  used because literals
            are not used in implementing the source file inclusion.

            HEADER FILES.

            MISOSYS MS-DOS  RATFOR searches for a file "PROFILE.RAT" on the
            currently logged  drive and  directory.   If one  is found, the
            string  "include(PROFILE.RAT)"  is  pushed  back onto the input
            before the source file is read.

            The header file capability is supported in Model 4 RATFOR using
            the  unique  command  line  macro definition capability of that
            version    of    RATFOR.        Inclusion    of    the   string
            "PROFILE=<filespec>"  on  the  command  line  causes the string
            "include(<filespec>)" to be pushed back onto the input stream.

            The header file capability provides the capability to customize
            the RATFOR  environment for  a given user, a given application,
            or for any other pupose deemed appropriate by the user.

            The content of the  PROFILE.RAT file  are not  restricted other
            than it  must be  valid RATFOR source code.  For general usage,
            the  PROFILE.RAT  file  can  contain  one   or  more  "include"
            statements to  read in  standard RATFOR  headers.  For example,
            constants for a given set of applications, such  as Boltzmann's
            constant and  the speed  of light,  might be part of one header
            file, while a macro library providing extensions to  the RATFOR
            keyword  set  or  extensions  of the FORTRAN intrinsic function
            library  might  be  part  of  another  header  file.    Another





            possibility is that a standard set of executable subprograms be
            included in this way, as  a  substitute  for  use  of  the user
            library linking functions.

            FURTHER INFORMATION.

            Specific  questions  can  be  left for Jim Beard [71675,566] on
            page LDOS.  Documentation and other information can be obtained
            from one or more of the following as appropriate:

               MISOSYS, Inc. (MS-DOS and TRS-80 Model 4 RATFOR)
               P. O. Box 239
               Sterling, VA 22170-0239
               (703) 450-4181
               (800) MISOSYS (or, 647-6797)

               Bell Laboratories (Bell UNIX and RATFOR)
               (201) 391-2828

               Mt. Xinu (Berkeley UNIX, RATFOR, and EFL)
               (415) 644-0146

               W. Plauger (Co-inventor of RATFOR)
               C/O Whitesmiths, Inc.
               398 Main St.
               Concord, MA 01742
               (508) 369-8499

               Addison-Wesley Publishing (Publisher of "Software Tools")
               (508) 944-3700

