.TITLE SFTRAN3 Mini User's Guide
.LAYOUT 0
.LM 0 .RM 70 .NF .NJ .PS 59,70
.SEND TOC .LAYOUT 1,3
.SEND TOC .RM 70
.SEND TOC .DISPLAY NUMBER RL
.SEND TOC .CENTER ;Table of Contents
.SEND TOC .SKIP
.STYLE HEADERS 6,1,6,7,7,1
-
.SK 12
.CENTER ;SFTRAN3 Mini User's Guide
.SK 6
.CENTER ;1982 November 17
.SK 26
.CENTER ;Jet Propulsion Laboratory
.CENTER ;California Institute of Technology
.CENTER ;Pasadena, California 91109
.F .J
.PG
.HL 1 INTRODUCTION
SFTRAN3 is a preprocessor which extends Fortran with a comprehensive
set of control structures for structured programming.  It also provides
a variety of useful ancillary services, such as listing control, a
portable "Include" feature, and run-time instrumentation of code.
.SK
SFTRAN recognizes two kinds of input lines:  SFTRAN lines and anything
else.  SFTRAN control structures are translated into Fortran statements
which conform to both the Fortran 66 and Fortran 77 ANSI Standards.  The
"anything else" lines are passed through unchanged, so that source
programs which conform to either ANSI standard plus SFTRAN extensions
are translated to Fortran programs which conform to the respective
standard.  Extensions available in the target Fortran compiler are also
available to the SFTRAN user.
.HL 1 SFTRAN3 Language Reference
.HL 2 General Syntax
SFTRAN syntax is similar to Fortran:
.SK .RM -6
.LIST 0,"-"
.LE;Statements occupy positions 7 through 72.
.LE;Continuation is indicated by a character other than blank or zero
    in position 6.
.LE;Positions 73-80 can be used for identification.  (However, the
    SFTRAN processor writes its own sequence numbers in the Fortran
    output it generates.)
.LE;SFTRAN recognizes the Fortran character set.
.LE;Blanks are not significant, although they count in determining
    the maximum allowed lengths of things.
.LE;C (or * in Fortran 77 version only) in column 1 indicates comment.
.LE;SFTRAN statements may not have Fortran statement numbers.
.LE;Tabs may NOT be used for statement formatting.
.END LIST .RM
.HL 2 Control Structures
The notation used is:
.LIST
.LE;label: is a string of at most 38 characters -- alphabetic, numeric,
    special, or blank, but not colon or unbalanced parentheses.  The
    first character must be a letter, and must be in one of positions
    2 through 5.  A colon follows the label.
.LE;(procedure name) is a string of unrestricted (within reason) length 
    -- alphabetic, numeric, special, or blank, but not unbalanced 
    parentheses.  The name is surrounded with parentheses.
.LE;S or Sn is zero or more statements, either SFTRAN or Fortran (or a mix).
.LE;Pn is a logical expression.
.LE;N is an integer literal.
.LE;I is an integer variable.
.LE;Ii is an integer expression.
.LE;Ln is a logical variable.
.LE;Square brackets denote optional items.  The brackets are not part of
    the statement.
.END LIST
.HL 3 Non-looping Structures
.HL 4 CASE
.TP 11 .LITERAL
[ label: ] DO CASE (I1,N)      
           CASE 1
              S1
           CASE 2
              S2
           ...
           CASE N
              Sn
         [ CASE OTHER
              S       ]
           END CASE
.END LITERAL .SK
Evaluates expression I1, then executes the statements under the 
corresponding case.  N must be an integer literal, greater than zero.
All of cases 1 through N must be present.  If the value of I1 is outside
the range 1 through N, S is executed if present.  If I1 is out of range
and no CASE OTHER is present, the CASE structure is a NO-OP.
.HL 4 IF...THEN...ELSE
.TP 10 .LITERAL
[ label: ] IF     (P1) THEN
              S1
         [ ELSEIF (P2) THEN
              S2            ]
         [ ELSEIF (P3) THEN
              S3            ]
           ...
         [ ELSE
              S ]
           END IF
.END LITERAL .SK
Identical to the Fortran 77 version, except for the label.
.HL 4 DO BLOCK
.TP 3 .LITERAL
[ label: ] DO BLOCK
              S
           END BLOCK
.END LITERAL .SK
Execute S.  This has no special function, except to provide
a block label for an EXIT statement.
.HL 4 PROCEDURE
.TP 3 .LITERAL
[ label: ] PROCEDURE (procedure name)
              S
           END PROC[EDURE]
.END LITERAL .SK
Execute S, then return to the statement following the DO (procedure 
name) that activated it.  (See DO (procedure name).)
.HL 3 Looping Structures
.HL 4 DO FOR
.TP 3 .LITERAL
[ label: ] DO FOR I = N1, N2 [, N3 ]
              S
           END FOR
.END LITERAL .SK
Same as the Fortran 77 DO nn I = N1, N2 [, N3 ] -- zero trips through
if N2#.LT.#N1, unless N3#.LT.#0.
.HL 4 DO FOREVER
.TP 3 .LITERAL
[ label: ] DO FOREVER
              S
           END FOREVER
.END LITERAL .SK
Loops until some S causes an exit.
.HL 4 DO UNTIL
.TP 3 .LITERAL
[ label: ] DO UNTIL (P1)
              S
           END UNTIL
.END LITERAL .SK
Execute S.  If P1 is .TRUE., then exit, otherwise repeat.
.HL 4 DO WHILE
.TP 3 .LITERAL
[ label: ] DO WHILE (P1)
              S
            END WHILE
.END LITERAL .SK
If P1 is .TRUE., then execute S and repeat.
.HL 3 Special Statements
Each of the special statements may stand alone on a line, or may be
the object of a Fortran logical IF.  They may NOT have a label or
a Fortran statement number. 
.HL 4 DO (procedure name)
Execute S in the procedure (procedure name), then continue with the
statement following the DO (procedure name).
.HL 4 EXIT
Syntax is EXIT [ s-type ] [ (label) ], where s-type is one of:  CASE,
IF, BLOCK, PROC[EDURE], WHILE, UNTIL, FOR, FOREVER.  Go to the statement
immediately following the corresponding END#s-type statement.  If
(label) is specified, exit the structure beginning with label:.  If
EXIT is specified alone, exit the innermost containing structure.
.HL 4 CYCLE
Syntax is CYCLE [ s-type ] [ (label) ], where s-type is one of:  WHILE,
UNTIL, FOR, FOREVER.  Go to the loop test of the indicated loop
(effectively, to the corresponding END s-type statement).  If
(label) is specified, cycle the structure beginning with label:.  If
CYCLE is specified alone, cycle the innermost containing structure.
.HL 4 READ and WRITE
Syntax is:
.SK .LITERAL
        READ  (..., L1=END, L2=ERR) ...
        WRITE (..., L2=ERR)         ...
.END LITERAL .SK
Sets corresponding logical variables to .TRUE. if the END= or ERR=
exit is taken from the READ or WRITE (requires the target Fortran
compiler to support END= and ERR= options).
.HL 4 END PROGRAM
Syntax is END [PROGRAM].  Generates a Fortran END statement.
.HL 2 Preprocessor Directives
Preprocessor directives must begin in position 1.  There must be no
embedded blanks, except optionally around parentheses and between
words of the ANALYZE directives.
.HL 3 Listing Control
.HL 4 INDENT
Syntax is INDENT [ (N) ].  Specifies the number of positions to indent
each nested structure.  Default is INDENT 3.  NOINDENT turns it off.
INDENT with no argument turns it back on, without changing N.
.HL 4 LINEUP
Print columns of colons showing how the structures line up.  Default
is LINEUP.  NOLINEUP turns it off.  LINEUP turns it back on.
.HL 4 Comment Lines
Comment text beginning with the first non-blank at or after position 2
is indented to line up with the current structure indentation level.
Therefore, comments should normally begin in postition 7 in the input.
Indenting of comments can be suppressed by putting a "$" in position 2.
The "$" can be changed to another character by the use of the
.SK .I6
STET (char)
.SK
directive, where char is the desired character.
.HL 4 Inline Comments
Comments can be placed on the same line as an SFTRAN statement (but not
on an "anything else" statement), by beginning them with the "@"
character.  The character used can be changed by the use of the
.SK .I6
INLINE (char)
.SK
directive.  Example:
.SK .TP 3 .LITERAL
      IF (SWITCH) THEN  @ See if the foobizam switch is on
         ...
      END IF            @ End of foobizam switch test
.END LITERAL
.HL 3 INCLUDE
Syntax is:
.SK .I6
INCLUDE[,L] (include name)
.SK
The optional ,L causes the included text to be printed in the source
listing.  The text to be included must be bracketed with the statements:
.SK .TP 3 .LITERAL
      INCLUDE (include name)
         text
      END INCLUDE
.END LITERAL .SK
The (include name) follows the rules for (procedure name).  The above
text must reside in Fortran Unit 20.  Many include modules may reside
in the same Fortran-readable file.  Processing is speeded up if they
appear in the include file in the same order as they appear in 
program(s) which use them.
.HL 3 ANALYZE
The ANALYZE directives cause a program to be instrumented for collection
of run-time statistics.  The use of this feature is rather complicated,
and is not described here.  Refer to the SFTRAN3 
Programmer's Reference Manual for details.
.HL 1 Installation and Use
.HL 2 I/O Unit Numbers
The following Fortran I/O unit numbers are used by the SFTRAN3 
processor:
.SK .LITERAL
     5  Input   -- SFTRAN3 source code
    12  Output  -- Indented listing and error messages
    13  Scratch -- Unformatted scratch file
    14  Output  -- Generated Fortran source code to be sent to compiler
    15  Output  -- Error messages
    16  Output  -- Map of statement numbers -- used only with ANALYZE
    20  Input   -- File of INCLUDE modules -- used only with INCLUDE
.END LITERAL .SK
These units must be connected to appropriate files before executing the
SFTRAN3 processor.
.HL 2 Run-time Requirements
If the ANALYZE directives are used, file 16 and subroutine ZZZZC1, 
written during pre-processing, are needed at run time by the resulting
executable program.
.HL 1 Installation Under VMS
.HL 2 Contents of Distribution
The distribution for VMS contains the following:
.SK .RM -6 .LIST
.LE;The executable program SF3.EXE
.LE;A set of command procedures SF*.COM
.LE;A set of symbol assignments SFSYMB.COM
.LE;A HELP library module SFTRAN.HLP
.LE;This document, in RUNOFF format (SFTRAN.RNO).
.END LIST .RM
.HL 2 Installation Procedure
.SK .RM -6 .LIST
.LE;Copy the executable program SF3.EXE to a permanent location.
    The SYS$SYSTEM: directory is recommended.
.LE;Copy the set of command procedures SF*.COM to a permanent
    location.  The SYS$SYSTEM: directory is recommended.  If SF3.EXE
    is not in SYS$SYSTEM, edit these to point to it.
.LE;Copy the set of symbol assignments SFSYMB.COM to a permanent
    location.  The SYS$SYSTEM: directory is recommended.  If the
    SF*.COM files are not in SYS$SYSTEM, edit these to point to them.
.LE;Edit the system-wide LOGIN.COM to invoke SFSYMB.COM, or tell users
    to invoke it in their individual LOGIN.COM.
.LE;Install the HELP library module SFTRAN.HLP in 
    SYS$HELP:[SYSHLP]HELPLIB.HLB .  First edit it if necessary to
    conform to the way you have installed the other files.
.LE;Run this document, (SFTRAN.RNO) through RUNOFF (DSR), and distribute
    copies as needed.
.END LIST .RM
.HL 1 Reference
.NOPERIOD
C. L. Lawson, "SFTRAN3 Programmer's Reference Manual", JPL Document No.
1846-98, Revision A, April 15, 1981, Jet Propulsion Laboratory, 
California Institute of Technology, Pasadena, CA.