PU0093
                                                       CDF-194
                                                       M.W. Eaton
                                                       P. Sinervo
                                                       K. Chadwick
                                                       K. Leininger


                                EXPAND and XFORT

                            Macro expanders for CDF

                                  Release 4.31
                              Revised: 14 May 1991

                                   CONTENTS


        1       INTRODUCTION . . . . . . . . . . . . . . . . . . . . 3

        2       USAGE  . . . . . . . . . . . . . . . . . . . . . . . 5

        3       MACRO DEFINITIONS  . . . . . . . . . . . . . . . . . 7

        4       EXTENSIONS TO FORTRAN-77 SYNTAX  . . . . . . . . .  11
        4.1       Long Variable Names  . . . . . . . . . . . . . .  11
        4.2       Hexidecimal And Octal Constants  . . . . . . . .  12
        4.3       Blank Lines, Tabs And Continuation Lines . . . .  12
        4.4       Upper And Lower Case Code  . . . . . . . . . . .  13
        4.5       Exclamation Point Comments . . . . . . . . . . .  13
        4.6       Extended DO Loop Syntax  . . . . . . . . . . . .  13

        5       QUALIFIERS . . . . . . . . . . . . . . . . . . . .  15
        5.1       The ADD_COMMENTS Qualifier . . . . . . . . . . .  16
        5.2       The COMMENTS Qualifier . . . . . . . . . . . . .  16
        5.3       The CONTRACT Qualifier . . . . . . . . . . . . .  16
        5.4       The DEBUG Qualifier  . . . . . . . . . . . . . .  17
        5.5       The DEFAULT_EXTENSIONS Qualifier . . . . . . . .  17
        5.6       The EXPAND Qualifier . . . . . . . . . . . . . .  18
        5.7       The ENVIRONMENT Qualifier  . . . . . . . . . . .  18
        5.8       The FORTOPT Qualifier  . . . . . . . . . . . . .  19
        5.9       The HEADER Qualifier . . . . . . . . . . . . . .  19
        5.10      The IMPLICIT Qualifier . . . . . . . . . . . . .  20
        5.11      The INCLUDE Qualifier  . . . . . . . . . . . . .  20
        5.12      The OUTPUT Qualifier . . . . . . . . . . . . . .  20
        5.13      The OPTIONS Qualifier  . . . . . . . . . . . . .  21
        5.14      The PRETTY Qualifier . . . . . . . . . . . . . .  21
        5.15      The SPLIT Qualifier  . . . . . . . . . . . . . .  21
        5.16      The TRANSLATE Qualifier  . . . . . . . . . . . .  21
        5.17      The WARNING Qualifier  . . . . . . . . . . . . .  22

        6       IMPLEMENTATION ON NON-VAX OPERATING SYSTEMS  . . .  23

        6.1       IBM VM/CMS Implementation  . . . . . . . . . . .  23
                                                                Page 2


        6.2       UNIX Implementation  . . . . . . . . . . . . . .  25

        6.3       Small Version Implementation . . . . . . . . . .  28

        7       EXAMPLES . . . . . . . . . . . . . . . . . . . . .  29
        7.1       The Simplest Case  . . . . . . . . . . . . . . .  30
        7.2       Invoking The Fortran Compiler  . . . . . . . . .  31
        7.3       Use Of Qualifiers  . . . . . . . . . . . . . . .  31
        7.4       A Complicated Example  . . . . . . . . . . . . .  32
        7.5       How To Use The /TRANSLATE Feature  . . . . . . .  33
        7.6       Using The /NOEXPAND Qualifier  . . . . . . . . .  35
        7.7       Using $$ELSEIF And $$ELSE In Coding Your Macros   37
        7.8       Long Name Aliasing . . . . . . . . . . . . . . .  39
        7.9       Do-While And Do-Enddo  . . . . . . . . . . . . .  40
        7.10      The Use Of The $$BLOCK_DATA Macro  . . . . . . .  42

        8       ERROR MESSAGES . . . . . . . . . . . . . . . . . .  44
        8.1       Table Of Error Messages  . . . . . . . . . . . .  45

        9       RELEASE NOTES  . . . . . . . . . . . . . . . . . .  60
        9.1       Changes Since Release 4.0  . . . . . . . . . . .  60
        9.2       Changes Since Release 3.0  . . . . . . . . . . .  60
        9.3       Changes Since Release 2.0  . . . . . . . . . . .  62
        9.4       Changes Since Release 1.0  . . . . . . . . . . .  63
                                                                          Page 3


     1  INTRODUCTION

          The macro expanders EXPAND  and  XFORT  provide  a  powerful  and
     flexible approach for coding within multiple environments.  They offer
     macro expansion and debugging facilities that are transparent  to  the
     Fortran  compiler  and  destination  machine architectures.  They also
     allow programmers to use a superset of ANSI standard Fortran-77 syntax
     that  assist  in  source  coding  and that improve the readibility and
     verifiability of the source code.

          The use of the expanders does not incur overhead during execution
     time  as  the  compiled  code  reflects  only the expand-time selected
     options and no others.  EXPAND/XFORT introduces roughly  25%  overhead
     during   compilation   for  a  program  being  compiled  for  the  VAX
     environment and  approximately  200%  overhead  for  a  program  being
     compiled  for  a  non-VAX  environment,  with the increase in overhead
     arising from the need to perform the  translation  of  variable  names
     longer than six characters for the non-VAX environment.

          The expanders operate on input files that at the  simplest  level
     only  contain  ANSI  standard  or VAX Fortran-77 source code.  In this
     case, the expanders are completely passive when expanding  for  a  VAX
     environment  and  the  resultant  output  file, before compilation, is
     identical to the input file.  For non-VAX environments, the  expanders
     will  accept  a  certain  set  of  extensions  to  ANSI Fortran-77 and
     generate output code that is compatible with the targeted environment.
     The  real  power  of  the expanders lies in the ability of the user to
     embed macro definitions that allow conditional  compilation  based  on
     expand-time  qualifiers.   The macro definitions allow a programmer to
     tailor  code  in  a  completely  transparent  way  to  a  variety   of
     destination  machine architectures ("environments") for which the code
     may be targeted.

          EXPAND/XFORT are Fortran programs that are written employing many
     of  the  features  provided by the expanders.  As such, they provide a
     good example of portable software, as the same source code is used for
     the  DEC  VAX/VMS  ,IBM  VM/CMS and UNIX EXPAND/XFORT implementations.
     The XFORT expander (available only on the VAX) is an  amalgamation  of
     EXPAND  and  the  VAX Fortran compiler.  After the input file has been
     expanded, the VAX compiler is invoked on  the  expanded  source  file,
     obviating  the  need  to  manage or refer to the expanded intermediate
     source file.  This allows the  user  to  simply  replace  the  Fortran
     compilation  step  with XFORT.  In addition, the syntax of the command
     string and the EXPAND/XFORT error messages are similar to those of the
     VAX  Fortran  compiler, with which the user is probably familiar.  The
     functionality of XFORT is provided by the  COMPILE  exec  on  the  IBM
     VM/CMS operating system.

          Most users should read this introduction and section 2  on  usage
     fairly  carefully,  and  read  the rest of the paper in "browse" mode.
     The novice should also refer to section 7 for examples of  syntax  and
     usage.   As  one's  sophistication increases (or the need arises), one
     should read the rest of this manuscript in more detail.
                                                                          Page 4


          Users of EXPAND on IBM systems should read  the  section  on  the
     VM/CMS  implementation  for  details  on  how  the  VAX-oriented  file
     structure is mapped to the VM/CMS mini-disk system.

          Users of EXPAND on UNIX systems should read the  section  on  the
     UNIX Implementation.

          Modifications to this document  since  the  last  major  revision
     (indicated  by  an  increment in the arabic numeral to the left of the
     decimal point in the version  number)  appear  in  the  release  notes
     section.   Note  also  that there is a "small" version of the expander
     available with a version denoted as 4.30s.  Note that this is  exactly
     the  same  as the version 4.30 except that the array used to store the
     expander input files is a factor of 10 smaller to run on many  of  the
     experimental machines that have not been configured to run with enough
     virtual memory for the "regular" version of  the  expander.   See  the
     section entitled Small Version Implementation.
                                                                          Page 5


     2  USAGE

          As mentioned in the introduction, there are two  different  macro
     expanders,  XFORT and EXPAND, that are very similar in their function.
     EXPAND does an expansion of the macro  definitions  contained  in  the
     input  file and provides translation of non-Fortran-77 syntax when the
     targeted environment is other than VAX/VMS.

          To setup expand on the FNAL cluster issue the following command:

         $ SETUP EXPAND.version

     where version is one of the versions availabe.  For example, to  setup
     expand 4.30 issue the following command:

         $ SETUP EXPAND.V4_30

     or to setup expand 4.30s (the small version of expand 4.30) issue  the
     following command:

         $ SETUP EXPAND.V4_30S

     If you simply issue the command:

         $ SETUP EXPAND

     you will get the current version of the expander.   To  find  out  the
     current  version, you can either set default to the expand_dir area or
     type the help expand command.

          To setup expand on the FNALD cluster issue the following command:

         $ SETUP EXPAND VERSION_4_30

     or similarly:

         $ SETUP EXPAND VERSION_4_30S

     The only  difference  between  FNAL  and  FNALD  is  a  slight  syntax
     difference for the two different clusters.

          The input file type defaults to  ".CDF"  if  a  filetype  is  not
     specified.   The  output  filetype  can  be specified by the user, but
     defaults to ".VAX" for an input filetype of ".CDF" and ".INC"  for  an
     input  filetype  of ".CIN" on the VAX.  The default output filetype is
     ".IBM" for an input filetype of ".CDF" in the  IBM  implementation  of
     EXPAND.   For the MIPS environment, the default output filetype is .f.
     EXPAND  produces  its  output  file  in  the  user's  current  default
     directory,  and  one  may  then  compile  this  file using the Fortran
     compiler.  XFORT goes one step further in that it actually invokes the
     Fortran  compiler  with  default  qualifiers  "OPTIMIZE/LIST"  on  the
     expanded output file.  Fortran compiler options are discussed in  more
     detail in section 5.
                                                                          Page 6


          At the simplest level, one may use the expanders by typing either

         $ EXPAND <filestring>

     or

         $ XFORT <filestring>

     where either expander will  prompt  you  for  <filestring>  if  it  is
     omitted.   <filestring>  may  consist  of up to 10 files, separated by
     either ",", if one wishes separate output files, or "+", if one  wants
     them concatenated into a single output file.  You may mix both "," and
     "+", in  one  command.   In  addition,  <filestring>  may  have  local
     qualifiers  appended to it, while the expander name (EXPAND/XFORT) may
     have global qualifiers appended to it.  Both the qualifier syntax  and
     the  difference  between  local and global qualifiers are described in
     section 5.

          EXPAND/XFORT will modify the input source file so that the output
     source  code  conforms  to  the  syntax  of the targeted "environment"
     specified by the user.  In this sense, EXPAND  supports  an  augmented
     syntax  of  Fortran-77,  allowing  the  use  of  constructs such as DO
     WHILE...ENDDO, hexidecimal  and  octal  notation,  and  some  form  of
     IMPLICIT   NONE,  even  when  the  native  compiler  in  the  targeted
     environment does not support these.  The expanders generate Fortran-77
     compliant  code  in  place  of  the  augmented syntax.  The extensions
     supported by EXPAND are described in detail in section 4.
                                                                          Page 7


     3  MACRO DEFINITIONS

          Both expanders support the following macro definitions:

         $$IMPLICIT
         $$INCLUDE '<filespec>'
         $$BLOCK_DATA '<filespec>'
         $$IF VAX
              IBM
              ABSOFT
              CYBER
              FTN77
              FPS
              MIPS
              RS6000
              SUNOS
              ULTRIX
              UNIX
              <option>
         $$ELSE
         $$ELSEIF <option>
                  <environment>
         $$ENDIF

         $$IF <option 1>      OR <option 2>      OR ...
              <environment 1> OR <environment 2> OR ...
         $$ELSEIF <option 3>      OR <option 4>      OR ...
                  <environment 3> OR <environment 4> OR ...
         $$ELSE
         $$ENDIF

         $$DEBUG
         $$ENDDEBUG
         $$ALIAS <longname> <shortname>

     Macro definitions may occur anywhere on a line in the input file,  but
     must not be preceded by any nonblank or tab characters (usual practice
     is  to  have  the  macro  definitions  begin  in  column  1).    Macro
     definitions  may  NOT be abbreviated.  Case is irrelevant with regards
     to macro definitions.

          The macro equivalent of the VAX Fortran "IMPLICIT NONE" statement
     is   called   $$IMPLICIT.    Interpretation  for  the  VAX  and  other
     environments that support the "IMPLICIT NONE" statement is the same as
     the  VAX  "IMPLICIT NONE"  statement,  i.e.   the  macro definition is
     simply replaced by  the  equivalent  "IMPLICIT NONE"  statement.   For
     environments  that  do not support the "IMPLICIT NONE" statement (such
     as the IBM Fortran V1.4.1 compiler), the macro definition is  replaced
     by  "IMPLICIT LOGICAL (A-Z)".  The translation of the $$IMPLICIT macro
     may be disabled using the EXPAND qualifier "/NOIMPLICIT".

          The  macro  equivalent  of  the  VAX  or  IBM  Fortran  "INCLUDE"
     statement is called $$INCLUDE.  Interpretation for the VAX is the same
     as the VAX "INCLUDE" statement, i.e. the macro  definition  is  simply
     replaced  by the equivalent "INCLUDE" line.  For non-VAX environments,
                                                                          Page 8


     the processing  of  the  $$INCLUDE  macro  results  in  the  specified
     "include" file being read in, expanded and    added  to  the  expanded
     source file (this behaviour  can  be  modified  by  the  /INCLUDE  and
     /NOINCLUDE   qualifiers).    Macro  definitions,  including  $$INCLUDE
     statements, are allowed in "INCLUDE" files.

          One standard mode of include  file  management  is  to  give  all
     include  files  the  filetype of ".CIN".  These include files are then
     processed with EXPAND to produce a file with filetype ".INC"  that  is
     then  included  by  the  compiler  during  compilation.   For  non-VAX
     environments, a $$INCLUDE directive specifying a file with a  filetype
     ".INC"  is treated by actually including the corresponding ".CIN" file
     from the specified directory, and processing the ".CIN" file as it  is
     read  in.   This  dichotomy  in the management of include files arises
     from the rather different ways in which non-VAX  compiler's  implement
     the  INCLUDE  directive,  if  they  support  such an extension at all.
     Since the expanded source file is only an intermediate  file  in  most
     cases, there is little penalty for expanding all include files in-line
     for the non-VAX environments.  Note that the relationships between the
     expanded  file  extensions  and  the  extensions of the primary source
     files can be changed with the /DEFAULT_EXTENSIONS qualifier.

          The macro "$$BLOCK_DATA" is a variant of the  "$$INCLUDE"  macro,
     except  that  only  code delimited by the macros "$$IF BLOCK_DATA" and
     "$$ENDIF" in the include file will be actually included in the  source
     file.  This construct is provided for include files that define COMMON
     blocks that are  initialized  via  BLOCK  DATA.   The  necessary  DATA
     statements  may then be contained in the include file but delimited by
     the "$$IF BLOCK_DATA" and "$$ENDIF" macros.  The  block  data  program
     can  then  consist  of  a set of $$INCLUDE macros for the common block
     declarations, followed by a set of $$BLOCK_DATA macros that will bring
     in  the  DATA  statements  contained  in  the  include files.  If this
     explanation is confusing, see the  example  use  of  the  $$BLOCK_DATA
     macro given in section 7.

          A general purpose macro definition for conditionals is $$IF.  The
     expanders    recognizes    several   different   destination   machine
     architectures, called "ENVIRONMENT"s.   These  are  VAX,  IBM,  CYBER,
     ABSOFT, FPS, FTN77, MIPS, RS6000, SUNOS and ULTRIX.  The appearance of
     a $$IF <environment> line in the input file calls for the expander  to
     attempt  to  match <environment> with the environment specified by the
     user.  If a match is found, all lines following  the  $$IF  until  the
     terminating  $$ENDIF  are  included in the output file; otherwise they
     are discarded.  It is also possible to have logical  "ORing"  so  that
     more  than  one  environment  can be specified for a specific piece of
     code.   This  "ORing"  can  also  be  done  on   subsequent   $$ELSEIF
     statements.

          A generalization of the above is that $$IF may also be used  with
     an  option  <option>.   Interpretation  by  the  expander is the same,
     except that the expander searches the option list as specified by  the
     user-specified  EXPAND  qualifier "/OPTION=<option>".  $$IF statements
     may be nested up to ten levels deep.   The  macro  definition  $$ENDIF
     ends  the  previous  pending  $$IF statement.  Processing of the input
     file proceeds as before the occurrence of  the  $$IF  statement.   The
                                                                          Page 9


     logical  "ORing"  of  several possible options is also possible, as in
     the case of environments.

          The macro conditional $$ELSE offers the user more flexibility  in
     her coding environment.  Nested between a $$IF statement and a $$ENDIF
     statement, the $$ELSE statement acts  much  like  the  Fortran  "ELSE"
     statement;  namely  that if the $$IF condition was satisfied, the code
     following the $$ELSE statement is ignored, and if the  $$IF  statement
     was  not  satisfied,  the code following the $$ELSE is included in the
     output file.  An example  using  the  $$ELSE  statement  is  given  in
     section 7.7.

          The macro conditional $$ELSEIF works in much the same way as  the
     macro  conditional  $$ELSE,  except that it allows the programmer even
     more flexibility in coding her macro conditionals by offering the full
     block  structured  logic available in Fortran programming in the macro
     expander.  Again, the macro conditional $$ELSEIF works much  like  the
     Fortran  "ELSEIF"  statement.  BEWARE, though, that it works just like
     the Fortran "ELSEIF" statement in that if any of the  preceding  macro
     conditions  were  satisfied,  the  current and all subsequent $$ELSEIF
     statements will be ignored!  See the example in section 7.7  for  more
     details.

          The macro definition $$DEBUG works similarly  to  $$IF.   If  the
     expander  recognizes a $$DEBUG statement, and the /DEBUG qualifier has
     been specified, the following lines of the  input  file  are  included
     until  the  occurrence  of  a  $$ENDDEBUG  line,  otherwise  they  are
     discarded.  $$DEBUG conditionals may be nested with $$IF conditionals.
     $$ENDDEBUG terminates the previous pending $$DEBUG statement.

          The $$ALIAS macro is the recommended way  of  providing  for  the
     translation  of  long  variable  names when the code is expanded for a
     non-VAX environment.  EXPAND/XFORT provide automatic aliasing, but the
     user  has  to  be  aware  of the distinctions between local and global
     Fortran variables.  Local variables, i.e. variables that are local  to
     the program unit, may be handled without any $$ALIAS macro definitions
     whatsoever.   The  expander  simply  recognizes  the  long  name   and
     translates  the  long  name  to  an  appropriately mnemonic short name
     (ie. alias) in the  output  file.   However,  this  scheme  cannot  be
     guaranteed  to work in all cases as the alias created by EXPAND may be
     used elsewhere in  the  source  code  in  a  different  context.   The
     expander  detects such name conflicts and will issue a warning message
     if it encounters the alias in the original source file.   EXPAND  does
     not  treat this condition as an error, as there are cases where a user
     has decided (foolishly in our opinion) to use both the long and  short
     name for the same variable.

          Global long names,  e.g. subroutine  names,  must  be  explicitly
     declared  via  the  $$ALIAS macro, since it can not be guaranteed that
     the expander will pick consistent short names at expand time  in  each
     file  that  contains  the  global  variable.   Note  that  the $$ALIAS
     statement must appear in the source file before the  first  occurrence
     of  the  long name in the file.  Also note that global aliases must be
     specified  in  each  file  that  references  the  global  symbol.    A
     convenient way of doing this is by putting the $$ALIAS statements in a
                                                                         Page 10


     ".CIN" file that is included before the first non-comment statement in
     every  source file containing the global long-variable name.  Variable
     names that are part of a COMMON declaration can (and probably  should)
     be  aliased  in  the ".CIN" file that defines the common block itself.
     In this way, the aliases only have to be defined in one file.  Section
     4.1 disusses in more detail the treatment of long variable names.
                                                                         Page 11


     4  EXTENSIONS TO FORTRAN-77 SYNTAX


          EXPAND/XFORT extends the ANSI  standard  Fortran-77  language  by
     providing  the  user with several constructs that are available in the
     VAX/VMS  compiler  and  that  assist  in  coding  of  subroutines  and
     algorithms.   Some  of  these  "extensions"  have  been  chosen on the
     grounds that they simplify coding,  such  as  the  extended  DO...ENDO
     syntax.  Other extensions are necessary to provide a common syntax for
     concepts that are not part of Fortran-77 but that  are  used  heavily,
     such as hexidecimal and octal constants.



     4.1  Long Variable Names

          As mentioned in the previous section, EXPAND/XFORT will translate
     Fortran  variable  names  longer than six characters into aliases that
     are at most six characters in length.   This  creation  of  the  short
     alias  is performed either be an $$ALIAS macro (the preferred method),
     or by allowing the expander to create  an  short  name  that  has  not
     appeared  in  the  source file prior to encountering the long variable
     name.

          Since  Fortran-77  does  not  embody  the  concept  of   reserved
     "keywords",  the  expander  will recognize Fortran variables which are
     longer than six characters only if they contain either the  characters
     "_"  or  "$".   The corollary to this also holds; any variable with an
     underscore or a dollar character in it  will  be  treated  as  a  long
     variable  name even if it is six characters in length or shorter (this
     is necessary as some compilers do not allow variable names  containing
     the  underscore  or  dollar  symbol).   If the expander is required to
     create the alias name for the variable, it first uses  the  first  few
     characters of each part of the long variable name that is delimited by
     undescores  or  dollar  symbols.   If  the  concatenation   of   these
     characters  yields  a  variable  name  already  in  use,  one  of  the
     characters is arbitrarily modified until a unique short variable  name
     is  found.  For example, the variable name THIS_LONG_VARIABLE would be
     translated  to  THLOVA,  provided  THLOVA   has   not   been   already
     encountered.

          Since the alias is created  before  the  entire  source  file  is
     parsed,  the  expander  can create a name that may appear later in the
     source file.  Such obvious errors are indicated to  the  user  by  the
     expander  issuing a warning message.  This situation is not treated as
     an error as some programmers employ both long and short variable names
     in  their  code.   We  hasten  to  add  that  we  consider such coding
     practices abhorrent and strongly deprecate their use.

          There are some minor restrictions on Fortran coding  syntax  when
     using  long names.  Since EXPAND/XFORT is NOT a compiler, spaces, tabs
     or valid Fortran delimiters are required to separate Fortran  language
     elements   and   constants  from  variable  names.   For  example  the
     syntactically correct (but unreadable) Fortran-77 statements
                                                                         Page 12


         Do 10Long_Name = 1, 4
         DoLong_Name = 1, 4

     will hopelessly confuse the expander.   These  two  statements  become
     palatable   once   spaces   or   tabs  are  inserted  to  delimit  the
     alpha-numeric tokens on the line.

          Note that for the MIPS, RS6000, ULTRIX  and  SUNOS  environments,
     variable  names are NOT translated as this is not necessary with these
     compilers.



     4.2  Hexidecimal And Octal Constants

          Because of  the  lack  of  a  standard  Fortran-77  notation  for
     hexidecimal  and octal constants, EXPAND/XFORT automatically translate
     VAX format hexidecimal and octal constants into integer constants  for
     non-VAX  environments  other  than the MIPS environment which does not
     translate   these   constants.     This    strategy    ensures    that
     hexidecimal/octal   constants  occuring  in  any  context  (either  in
     executable statements, DATA statements or  PARAMETER  statements)  are
     treated  consistently  in all environments.  As an example, the source
     code

         Long_Hex_Name = '00000010'X
         Long_Oct_Name = '00000011'O

     would be translated to

         LOHENA = 16
         LOOCNA = 9

     for all non-VAX environments except the UNIX platforms.



     4.3  Blank Lines, Tabs And Continuation Lines

          Since many compilers do not allow blank  lines  in  source  code,
     EXPAND/XFORT remove all blank lines from the expanded source file when
     the code is being expanded for all non-VAX environments except the FPS
     environment where blank lines are tolerated.

          The expanders also support the VAX form of  a  continuation  line
     marked  by  a  tab  character  followed  by  a  single  numeral.  Such
     "tab-continuations" are translated into  standard  continuation  lines
     with the numeral appearing in column 6.

          For all of the non-VAX environments, EXPAND/XFORT  converts  tabs
     into  the  appropriate  number of blanks (as most non-VAX compilers do
     not recognize tabs as valid delimiters).  The logical tabs used by the
     expanders  are  set  at  column 9 and every 8th column thereafter (ie.
     columns 9, 17, 25, etc.), which correspond to the default logical  tab
     settings  on a VAX.  Tabs encountered in strings are also expanded, so
                                                                         Page 13


     that a user should not use an explicit tab  character  if  the  single
     character  is  to  be  preserved.   A viable alternative is to use the
     intrinisc function CHAR(9) for ASCII environments  (such  as  VAX  and
     ABSOFT),  and  CHAR(5)  for EBCDIC environments (such as IBM) to yield
     the tab character.

          Since a tab counts as a single character for a VAX  compiler,  an
     expanded  source  line  may  exceed 72 columns once tabs are converted
     into blanks, even though the original line may have  a  valid  length.
     In  such  cases,  EXPAND/XFORT  will break the expanded source line at
     column 72 and continue it on the following source line.  This  has  no
     effect  on  the  syntactical  content of the resulting source line but
     ensures that it will compile correctly in non-VAX environments.



     4.4  Upper And Lower Case Code

          EXPAND/XFORT  allows  the  use  of  mixed-case  source  code,  by
     translating  all  non-comment  lines  into  upper case for all non-VAX
     environments except FPS.  Quoted strings are excluded from this as are
     all  comment  lines.   Note  however  that hollerith strings (who uses
     them?) are not supported and will be changed to upper case.

          There may be a problem  if  a  user  has  lower  case  in  FORMAT
     statements  that  are  defined  be  a quoted string.  For example, the
     format specification "i4" in the source line

        Write(6, '('' k = '',i4,)') k

     will not be converted to upper case since it is imbedded in a  string,
     with  the  result  that  the  code  will  not  compile in many non-VAX
     environments.



     4.5  Exclamation Point Comments

          The VAX compiler treats anything after an exclamation point ("!")
     on  a  source  line  as a comment, allowing the user to imbed trailing
     comments.  EXPAND/XFORT will  convert  these  trailing  comments  into
     standard  Fortran-77  comment lines by placing the comment string on a
     separate comment card.



     4.6  Extended DO Loop Syntax

          The expanders allow a user to use VAX forms of  the  extended  DO
     loop syntax, by translating such structures into standard DO loops and
     control structures.  EXPAND/XFORT will translate both  DO...ENDDO  and
     DO WHILE...ENDDO control structures in the following manner:

        DO I=1, N               ==>             DO <label> I=1,N
           .                    ==>                .
                                                                         Page 14


           .                    ==>                .
           .                    ==>                .
        ENDDO                   ==>     <label> CONTINUE

     and

                                ==>     <label> CONTINUE
        DO WHILE (<log-exp>)    ==>             IF (<log-exp>) THEN
           .                    ==>                .
           .                    ==>                .
        ENDDO                   ==>               GOTO <label>
                                ==>             ENDIF

     In these two examples, <label>  is  a  statement  label  generated  by
     EXPAND/XFORT  that  is  as numerically small as possible and that does
     not clash with any other statement  labels  defined  in  the  original
     source  code  or  generated by EXPAND/XFORT.  The expression <log-exp>
     can be any valid logical expression allowed in an IF statement, and it
     may span any number of source lines.

          Note that this translation is NOT done for the  MIPS  environment
     as the compiler accepts extended do loop syntax.
                                                                         Page 15


     5  QUALIFIERS

          Both expanders understand the following qualifiers:

          /ADD_COMMENTS                         (default)
          /NOADD_COMMENTS
          /COMMENTS=ALL                         (default)
                    SOURCE
                    NONE
          /CONTRACT
          /NOCONTRACT                           (default)
          /DEBUG
          /NODEBUG                              (default)
          /DEFAULT_EXTENSIONS={(ext_in_1, ext_out_1), (ext_in_2, ext_out_2),..}
          /ENVIRONMENT=VAX                      (default on VAX)
                       CYBER
                       IBM                      (default on IBM)
                       ABSOFT
                       FTN77
                       FPS
                       MIPS                     (default on SGI)
                       RS6000                   (default on AIX/RS6000)
                       SUNOS                    (default on SUN computers)
                       ULTRIX                   (default on DEC stations)
          /HEADER
          /NOHEADER                             (default)
          /IMPLICIT                             (default)       
          /NOIMPLICIT
          /INCLUDE              (default for non-VAX environments)
          /NOINCLUDE            (default for VAX environment)
          /OUTPUT=<filespec>
                  *.<filetype>
          literal/OPTIONS=(<opt1>,<opt2>,...)
          /PRETTY
          /NOPRETTY                             (default)
          /SPLIT
          /NOSPLIT                              (default)
          /TRANSLATE
          /NOTRANSLATE                          (default)
          /WARNING                              (default)       
          /NOWARNING

     EXPAND understands the qualifiers

          /EXPAND                               (default)
          /NOEXPAND

     while in addition XFORT understands

          /FORTOPT={<fortran qualifier string>} (default = /OPTIMIZE/LIST)


          Qualifiers may be made global (i.e. applying  to  all  the  input
     files)  by  appending  the  qualifier  directly  to  the expander name
     (EXPAND/XFORT), or local (i.e. applying only to  an  individual  input
                                                                         Page 16


     file) by appending the qualifier to the input file name.  All language
     elements for qualifiers  except  <option>  may  be  abbreviated  to  a
     minimum  of three letters.  Qualifiers may have blanks separating them
     from  other  qualifiers  (e.g. /DEBUG  /ENV=VAX),  but  may  not  have
     embedded blanks (e.g. /ENV = VAX).



     5.1  The ADD_COMMENTS Qualifier

          EXPAND inserts FORTRAN comment statements into the output  source
     file  for  informational purposes.  For example, a comment is inserted
     at the beginning and end of an inserted include  file.   This  comment
     creation  may  be  suppressed  with the /NOADD_COMMENTS qualifier when
     appropriate (for example, when  expanding  source  code  that  is  not
     FORTRAN).

          The default is /ADD_COMMENTS.



     5.2  The COMMENTS Qualifier

          The qualifier /COMMENTS gives the  user  some  control  over  the
     inclusion  of  Fortran comment cards in the expanded source file.  All
     comments (including those found in INCLUDE files) will be included  in
     the  output file when /COMMENT=ALL is specified, and all comments will
     be stripped from the expanded file when  /COMMENT=NONE  is  specified.
     If  /COMMENT=SOURCE  is  specified, only the comments appearing in the
     source file will be retained (ie.  comments in INCLUDE files  will  be
     deleted).

          The benefit of /COMMENT=NONE is that it reduces the size  of  the
     expanded  source  file  and  so  reduces  the I/O overhead involved in
     running EXPAND.  A typical reduction in execution time of 30%  can  be
     realized  with the use of /COMMENTS=NONE.  The reduction in the number
     of comment lines is also advantagous when using the  ABSOFT  debugger,
     where the number of lines of source being debugged is limited.

          The difference in effect of this qualifier and the  /ADD_COMMENTS
     and  /NOADD_COMMENTS  qualifiers  is  that  it  gives  the  user  some
     selection as to which  FORTRAN  comment  statements  to  retain.   The
     /ADD_COMMENTS qualifier controls whether EXPAND inserts any additional
     FORTRAN comment statements into the expanded source file (see above).



     5.3  The CONTRACT Qualifier

          The qualifier /CONTRACT will have EXPAND/XFORT look  through  the
     soure  file  for all FORTRAN variables that are declared as PARAMETERS
     but that are not  referenced  in  the  source  code,  and  have  those
     PARAMETER  statements  (and the associated type declaration statements
     for those parameters) removed from the output source file.  The effect
     of  this  is  to reduce the size of the output source file without any
                                                                         Page 17


     change to the way the code executes.  This is  particularly  effective
     when  large  PARAMETER  include files are included in a source program
     because only  a  few  of  the  PARAMETERs  in  the  include  file  are
     referenced in the source code.

          PARAMETERs whose types are declared  in  a  multiple  declaration
     statement are not removed, eg.  in the following code fragment

        INTEGER         VAR1
        INTEGER         VAR2,   VAR3
     C
        PARAMETER       (VAR1 = 1)
        PARAMETER       (VAR2 = 2)
        PARAMETER       (VAR3 = 3)

     if the three PARAMETERs VAR1, VAR2 and VAR3 are not referenced in  the
     source  file,  only  the  declaration and PARAMETER statement for VAR1
     would be removed by /CONTRACT because VAR2 and VAR3 are declared in  a
     single  INTEGER statement.  VAR2 and VAR3 would be removed if they had
     been declared in separate INTEGER statements.

          The addition of the /CONTRACT  capability  is  motivated  by  the
     desire to reduce the size of the compiler listing files when debugging
     code in the ABSOFT environment.  It is also useful when using the  IBM
     FORTVS  debugger  as  it  reduces the size of the listing file and the
     ensuing virtual memory requirements.

          Note that if include files are not being included in  the  source
     code,  then  /CONTRACT  has  no  effect on parameters defined in these
     include files (effectively /CONTRACT is most  useful  if  all  include
     files are included in-line in the source file).

          /NOCONTRACT is the default in all environments.



     5.4  The DEBUG Qualifier

          The qualifier /DEBUG enables the inclusion of code  delimited  by
     $$DEBUG  and $$ENDDEBUG lines, while the qualifier /NODEBUG will cause
     code delimited by $$DEBUG and $$ENDDEBUG lines to be excluded.



     5.5  The DEFAULT_EXTENSIONS Qualifier

          EXPAND has a set of default input  and  output  file  extensions.
     For  include  files,  the  default input extension is ".CIN" while for
     source files, the default input  extension  is  ".CDF".   The  default
     output  file  extensions  are ".INC" and ".FOR" for include and source
     files, respectively.  These default extensions may be overridden  with
     the DEFAULT_EXTENSIONS qualifier.
                                                                         Page 18


          The parameters to this qualifier are pairs  of  extensions,  each
     surrounded  by  a  set of round brackets ("(" and ")").  Several pairs
     can be provided as long as they are  separated  by  commas,  with  the
     entire list being surrounded by a set of curly brackets ("{" and "}").
     The first extension is the input  extension  and  the  second  is  the
     output  extension  that  the  expanded source file is given (presuming
     that the /OUTPUT qualifier has not been specified).

          For example, the initial default extensions are equivalent to:

           /DEFAULT_EXT={(CDF,FOR),(CIN,INC)}

     Hence, an input file with extension .CDF  will  be  expanded  into  an
     output file with extension .FOR while input files with extensions .CIN
     will be expanded into output files with extension .INC.

          The other feature provided by this qualifier is  the  ability  to
     change  what EXPAND will use as the primary source for an include file
     that is being expanded into the output source file with the  $$INCLUDE
     macro.  The extension used in the $$INCLUDE file specification will be
     treated as  one  of  the  default  output  file  extensions,  and  the
     corresponding  input  file  extension will then be used to specify the
     input file that will be  included.   Hence  the  statement  "$$INCLUDE
     'TEST.INC'"  will  have  EXPAND  look for the file TEST.CIN and expand
     that file into the output source file.  On  the  other  hand,  if  the
     primary  source  of  the  include files have extensions of .PINC, then
     EXPAND should be provided with the qualifier

     /DEFAULT_EXTENSION={(PINC,INC)}


          Note that all default extensions must be  provided  whenever  the
     DEFAULT_EXTENSION qualifier is used as all previous default extensions
     are no longer in effect.  One way of implementing a customized set  of
     default extensions is to have the VAX symbol EXPAND defined as
     EXPAND/DEFAULT_EXTENSIONS={(in_1,out_1),(in_2,out_2),...}



     5.6  The EXPAND Qualifier

          The  qualifier  /EXPAND  enables  the  expansion  of  the   macro
     definitions in the output file, while the qualifier /NOEXPAND disables
     the expansion of  macro  definitions  (except  for  $$INCLUDE).   This
     feature  is  useful  for  expanding code for non-VAX environments, but
     leaving the macro definitions in so that the user may still select the
     compile time options she wishes (e.g. /DEBUG).



     5.7  The ENVIRONMENT Qualifier

          The   qualifier    /ENVIRONMENT=<environment>    specifies    the
     environment   the  expanded  code  is  targeted  to.   This  sets  the
     appropriate expand-time options for  the  specified  environment  (eg.
                                                                         Page 19


     translation  of  long  variable names, translation of extended DO loop
     syntax, and translation of $$IMPLICIT) and enables  the  inclusion  of
     code   delimited   by   $$IF <environment>  and  $$ENDIF.   While  the
     $$IF...$$ENDIF macro syntax is the same  for  both  <environment>  and
     <option>,  note that only one environment may be selected, while up to
     ten options may  be  selected.   The  potential  confusion  from  this
     redundancy of syntax is offset by the simplicity of use it affords.

          Because of the similarity in the FORTRAN compilers on  most  UNIX
     platforms,  EXPAND  supports  an extension of the $$IF...  syntax that
     makes the pseudo-environment "UNIX" equivalent  to  any  of  the  UNIX
     environments supported by EXPAND.  Thus the following sets of code are
     equivalent:

     $$IF UNIX                        ==> $$IF MIPS OR RS6000 OR ULTRIX OR SUNOS
     C                                ==> C
     C   Code for UNIX                ==> C  Code for UNIX
     C                                ==> C
     $$ELSEIF IBM OR VAX              ==> $$ELSEIF IBM OR VAX
     C                                ==> C
     C                                ==> C
     C  Code for IBM and VAX          ==> C  Code for IBM and VAX
     C                                ==> C
     $$ELSE                           ==> $$ELSE
     C                                ==> C
     C  Code for other platforms.     ==> C  Code for other platforms.
     C                                ==> C
     $$ENDIF                          ==> $$ENDIF

     Note that the default environment is the platform that EXPAND is currently
     executing on.  




     5.8  The FORTOPT Qualifier

          The qualifier /FORTOPT allows the user to  override  the  default
     compiler  options  used by XFORT to invoke the VAX compiler.  Note the
     braces "{" and "}"must be present around the /FORTOPT qualifier string
     (this   is   necessary  to  separate  any  compiler  and  EXPAND/XFORT
     qualifiers).  All /FORTOPT qualifiers  are  understood  to  be  global
     qualifiers,  in  that  they  will  apply to all files specified in the
     parameter list, regardless of  where  they  appear  in  the  parameter
     string.



     5.9  The HEADER Qualifier

          The qualifier /HEADER results in a  a  descriptive  header  being
     placed  in  the  output file giving the version number of the expander
     used to produce the output file.  The output file  will  also  contain
     the command line that was used to invoke the expander, and the time at
     which the expander was invoked.  This particular feature may be useful
                                                                         Page 20


     in documenting certain output files in particularly complicated coding
     environments.  The EXPAND/XFORT version number is  also  displayed  in
     the terminal output.

          The qualifier /NOHEADER disables this feature.



     5.10  The IMPLICIT Qualifier

          The qualifier /IMPLICIT enables the translation of the  $IMPLICIT
     macro   into  either  "IMPLICIT NONE"  or  "IMPLICIT  LOGICAL  (A-Z)",
     depending on the selected environment.  The former is  used  for  VAX,
     ABSOFT and IBM environments, while the latter is used for all others.

          The qualifier /NOIMPLICIT will cause the $$IMPLICIT macro  to  be
     translated  into  a  simple  comment  line  in  the  source code, thus
     allowing a user to disable the use of IMPLICIT NONE at expand-time.



     5.11  The INCLUDE Qualifier

          The qualifier /INCLUDE will direct EXPAND to expand  all  include
     files in the output source file when a $$INCLUDE macro is encountered.
     Normally  this   behaviour   is   controlled   by   the   /ENVIRONMENT
     specification,  since  on  the  VAX  the  default  is  to  convert the
     $$INCLUDE references to VAX FORTRAN INCLUDE statements while on  other
     environments the file extension in the $$INCLUDE statement is modified
     to point to the primary source for the include file and this  file  is
     explicitly   expanded   into  the  output  source  file.   In  non-VAX
     environments, the /INCLUDE qualifier is automatically in effect.

          This option is useful if one wants  to  provide  complete  source
     files  that  do  not  have  any  references to external include files.
     Because the /ENVIRONMENT qualifier implicitly sets this  switch  also,
     one  must  be  sure  to  specify the /INCLUDE or /NOINCLUDE qualifiers
     AFTER any /ENVIRONMENT  qualfiers.   Otherwise  the  setting  for  the
     specified  environment  will  be  used  and  not that specified by the
     /INCLUDE or /NOINCLUDE qualifier.



     5.12  The OUTPUT Qualifier

          The qualifier /OUTPUT=<filespec> will direct the output from  the
     expander  into  file  <filespec>.   Note that the user must have write
     access to <filespec>  for  this  qualifier  to  work.   The  qualifier
     /OUTPUT=*.<filetype>   writes   the   output   file   to  <input  file
     name>.<filetype>.  Records in the output file  are  truncated  at  132
     characters  for  the  VAX environment and at 80 characters for non-VAX
     environments.
                                                                         Page 21


     5.13  The OPTIONS Qualifier

          The qualifier /OPTIONS=(<opt1>,opt2>,...) enables code  delimited
     by  $$IF <opt1>,  $$IF <opt2>,  ... and  $$ENDIF.   Note that a single
     option need not be enclosed by parentheses.



     5.14  The PRETTY Qualifier

          The PRETTY qualifier will cause the  expander  output  to  be  be
     translated to upper case and exclamation comments to be converted into
     regular comment lines.  This qualifier cannot be used  in  conjunction
     with  the  /TRANSLATE  qualifier.   It  is  meant  to  be used for VAX
     environments, if at all.

          The  qualifier  /NOPRETTY  disables  this  feature,  and  is  the
     default.



     5.15  The SPLIT Qualifier

          The qualifier /SPLIT  will  cause  the  expander  to  generate  a
     separate  output  file for each subroutine, main program or block data
     subroutine in the source file.  The filenames of the output files will
     be  the  name  of the program section they contain, while the filetype
     would be the default one unless otherwise  specified  by  the  /OUTPUT
     qualifier.  This feature is only supported if the /TRANSLATE option is
     specified, or if the code is being expanded for a non-VAX  environment
     where the /TRANSLATE option is the default.

          The qualifier /NOSPLIT disables this feature, and is the default.



     5.16  The TRANSLATE Qualifier

          The  qualifier  /TRANSLATE  controls  the   various   translation
     features   performed   by  EXPAND/XFORT.   When  specified,  tabs  are
     converted to blanks, blank lines are removed,  non-commented  code  is
     converted  to  upper  case,  and  imbedded comments flagged by "!" are
     converted to separate comment lines.  In addition, long variable names
     are  aliased  to  short  versions,  and  any DO...ENDDO structures are
     converted to standard Fortran-77 constructions.

          This option is automatically selected when the environments  IBM,
     FTN77,  FPS, ABSOFT, or CYBER are specified.  For the FPS environment,
     only tabs and comments delimited by "!" are  translated.   Note  again
     that the MIPS environment has a combination of these variables that is
     described in more detail in the UNIX IMPLEMENTATION section.

          The  qualifier  /NOTRANSLATE  disables   this   feature.    Since
     /TRANSLATE  is  enabled  by the setting of the /ENVIRONMENT qualifier,
     the routine use of /TRANSLATE and /NOTRANSLATE is not necessary.
                                                                         Page 22


     5.17  The WARNING Qualifier

          The /WARNING  qualifier  will  allow  the  reporting  of  various
     warning  messages  to the user while the input file is being expanded.
     The only significant source of warning messages (as opposed  to  fatal
     errors)  come from the use of both long and short variable names.  The
     number of warning messages is  limited  to  10  per  file;  additional
     messages are suppressed.

          The qualifier /NOWARNING suppresses all warning messages, and its
     use is not recommended.
                                                                         Page 23


     6  IMPLEMENTATION ON NON-VAX OPERATING SYSTEMS

     6.1  IBM VM/CMS Implementation

          The expanders run as native programs on both DEC VAX/VMS and  IBM
     VM/CMS operating systems, with all features described in this document
     being available in either implementation.   However,  because  of  the
     differences  in  file  systems  and  file naming schemes, a mapping of
     VAX-style file specifications has to be made to the  VM/CMS  operating
     system to ensure true portability of source code.  EXPAND/XFORT choose
     to use VAX file specifications for consistency.  Hence, VAX  filenames
     must  be  specified  in  $$INCLUDE  and  $$BLOCK_DATA  macros, and the
     expander will map these to to the corresponding filename on VM/CMS.

          Certain  restrictions  have   to   be   imposed   on   all   file
     specifications to ensure a one-to-one mapping of source files from one
     system to another.  All VAX file  specifications  must  consist  of  a
     filename  that is at most eight characters long, a file extension that
     is up to five characters in length, and a VAX logical  directory  name
     that  can  be up to 32 characters in length and that must map uniquely
     to a three letter mnemonic character string.  These restrictions arise
     from  the  manner is which files are specified on VM/CMS.  A file on a
     VM/CMS system resides on a mini-disk that is  linked  to  each  user's
     virtual  machine  with  a  mode  letter from A to Z.  Each file on the
     mini-disk has a filename that is up to eight characters in  length  as
     well  as  a  filetype  that  may  also be up to eight characters long.
     EXPAND/XFORT maps the VAX filename (ie.  excluding the file extension)
     to  the  VM/CMS  eight character filename, with the VAX filename being
     truncated if it is longer than eight characters.  The VM/CMS  filetype
     is  created from a concatenation of a three character mnemonic for the
     VAX logical directory name and the first five characters  of  the  VAX
     extension.   Since  the  common VAX extensions are three characters in
     length, the resulting filetype is usually six characters long.

          The mapping of logical directory names to IBM mnemonics is  taken
     from  a  file  called  XLOGNAME.DAB.  The following is an excerpt from
     this file that illustrates this scheme:

               EXP       Expand$Library                          
               GEN       C$Gen                                   
               GEO       C$Geom                                  
               GMU       C$Gmu                                   
               ISA       IsaJet$Source                           
               JET       C$Jet                                   
                
     For example, the filename "Expand$Library:FILES.CIN" on  VMS  will  be
     mapped  to  the  file  "FILES EXPCIN H" on VM/CMS, where the mini-disk
     containing the file is linked at mode H.

          EXPAND is invoked on VM/CMS in essentially the same way as it  is
     invoked on VMS:

        EXPAND <input_filename> <output_filetype>  [ ( <options>
        
     The input and output files  are  now  specified  by  the  CM/VMS  file
                                                                         Page 24


     specifications  <input_filename>  and  <output_filename>.  The various
     expand qualifiers must be specified  as  a  string  following  a  left
     parenthesis.   Note  that  only one input file may be specified at any
     one time.  The equivalent of XFORT is provided by the COMPILE command,
     which  first  expands  the file and then passes the expanded output to
     the FORTVS compiler.  If compilation is successful, the output file is
     immediately  erased.   In the case of a compiler warning or error, the
     expanded output file is left and given the filetype EXPAND.
                                                                         Page 25


     6.2  UNIX Implementation

          The EXPAND/XFORT environment called MIPS is an  environment  that
     supports  not  only  the  MIPS  processors  as  implemented on Silicon
     Graphics platforms but also others that use the MIPS chip set.  EXPAND
     version 4.31 and later now also operate natively on the MIPS platforms
     as well as the other UNIX platforms that are currently  considered  by
     EXPAND to be UNIX environments (namely AIX/RS6000, SUNOS, and ULTRIX).
     Because of the differences in the UNIX operating systems compared with
     the VAX and IBM systems, various features of EXPAND have been modified
     to provide the same functionality on these different platforms.

          To setup the expander on a UNIX platform one needs  to  have  UPS
     installed.  Assuming UPS is installed, issue the following command:

         % setup expand.version

     where version is the version that you are interested in.  For example,
     if you want version 4.30 issue the following command:

         % setup expand.v4_30

     or if you want version 4.30s issue the following command:

         % setup expand.v4_30s


          If you simply setup expand without a version  you  will  get  the
     current  version.   If  you  are  interested  in  finding out what the
     current version is, you should see  the  ups  documentation  available
     from the Computing Division Library.

          Due to the conflicting use of forward slashes (/)  as  seperators
     on  the  VAX and IBM while the MIPS uses them to seperate directories,
     another methodology was developed to seperate options to the expander.
     The  use of the dash was decided since this is very similar to the way
     in which other unix commands are implemented.  All other syntax should
     be the same.  For example:

     expand -env=mips -contract test.cdf
      
     Note that as is the case for all UNIX commands, the expander  is  case
     sensitive  and  everything  should  be  in lower case!  Blank space is
     ignored and can be utilized as you would like.  However, there must be
     a  blank  after  the  word  expand  so  that  the operating system can
     recognize the command itself and  before  the  filename  so  that  the
     expander can distinguish the file from the options.  For example:

     expand -env=mips-contract-include test.cdf

     is  perfectly  legitimate.   The  options   should   have   the   same
     functionality as currently exists on the VAX and IBM platforms.
                                                                         Page 26


          There are behaviors as previously described that  are  unique  to
     the  expander.   These  are  critical  to  the proper operation of the
     expander.

          VAX logical names are translated to  environmental  variables  in
     uppercase  as  is the UNIX convention.  Any dollar signs are converted
     to underscores to avoid any shell problems.  For example:

        expand$source  -->  EXPAND_SOURCE

     This is relevant to include files.  For  include  files,  the  logical
     name,  if  found,  will  be  translated  as  above, then the resultant
     environmental variable will be explicitly expanded to a full path name
     and  the  resultant file included inline in the code during the expand
     phase (in other words, before compilation.) If you  have  defined  the
     environmental   variable   EXPAND_SOURCE   as  /usr/people/kevin,  the
     following occurs:

        $$INCLUDE expand$source:cmdin.inc

     will become

        $INCLUDE /usr/people/kevin/cmdin.inc

     which contents will then be brought inline in the code.  Note that the
     contents  of  the file /usr/people/kevin/cmdin.inc will be included in
     the file.  This is similar behavior to the other non-VAX  environments
     except  for  the  use  of  the  environmental variables.  Note that it
     should be common that some setup procedure or the system  has  defined
     the  environmental  variables  for  you;  otherwise,  you will have to
     define any environmental variables yourself if you use  logical  names
     in your include filenames.

          Long variable names are not translated, but  $$ALIAS  macros  ARE
     honored.  This means that the long names will not be translated unless
     they are explicitly requested with a $$ALIAS macro.

          Hex and octal values are not translated.

          Tab and continuation lines are converted as in all other  non-VAX
     environments.

          Expand 4.30 is case insensitive.

          Do loop structure is not modified since the MIPS  compiler  fully
     supports extended do loop syntax.

          The $$IMPLICIT macro is converted to IMPLICIT NONE.

          Long file names are supported and the include files  are  written
     on multiple comment lines if they span more than 80 characters.

          Support for relative addressing is there; however, only one level
     of indirection is supported.  In other words, you cannot expand a file
     named ../../test.cdf while you can expand a file named ./test.cdf.
                                                                         Page 27


          Blanks inside of include  filenames  are  stripped  out  although
     these  should  be  removed  if  noticed  as  this  is  NOT good coding
     practice!  Note also that include files MUST be in  lowercase  on  the
     unix  platforms as this is the algorithm used on UNIX to differentiate
     files from other devices.

          Contract directive works for simple cases;  however,  it  may  be
     case  sensitive  and will not remove certain cases due to a bug in the
     algorithm.
                                                                         Page 28


     6.3  Small Version Implementation

          There is a small version of the expander  available.   The  small
     denotes  the  array  size  used to store the expander input file as it
     processes it.  Note that the regular  version  of  the  expander  (the
     version  without  a  trailing  s)  will support input files up to 100K
     lines while the small version of the expander will support input files
     up  to approximately 10K lines.  This distinction becames necessary as
     many of the experimental systems  on  and  offsite  are  running  with
     relatively  small  virtual  memory  sizes  while  the expander grew to
     support several of the larger experiments.  The small version  of  the
     expander  is  exactly  the same as the regular version of the expander
     except for this internal array size.  All  functionality  remains  the
     same.   The  small and regular distinction is only available from 4.30
     and beyond.
                                                                         Page 29


     7  EXAMPLES

          For most  of  the  examples  listed  below,  the  following  file
     "TEST.CDF" is used.

           PROGRAM TEST
     C
     $$INCLUDE 'C$INC:GEN202.INC/LIST'
     $$INCLUDE 'C$INC:OBS203.INC/LIST'
           LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
     C
     C  Set all flags to .FALSE. initially
     C
           LVAX = .FALSE.
           LCYBER = .FALSE.
           FRED = .FALSE.
           IAN = .FALSE.
           JOHN = .FALSE.
           MARY = .FALSE.
     C
     $$IF VAX
           LVAX = .TRUE.
         $$IF FRED
           FRED = .TRUE.
         $$ENDIF
         $$IF IAN
           IAN = .TRUE.
             $$IF JOHN
           JOHN = .TRUE.
                 $$IF MARY
           MARY = .TRUE.
                 $$ENDIF
             $$ENDIF
         $$ENDIF
     $$ENDIF
     $$IF CYBER
           LCYBER = .TRUE.
     $$ENDIF
     $$DEBUG
           WRITE (6,100) LVAX,LCYBER,FRED,IAN,JOHN,MARY
     100   FORMAT (' LVAX = ',L1,/,
          +               ' LCYBER = ',L1,/,
          +               ' FRED = ',L1,/,
          +               ' IAN = ',L1,/,
          +               ' JOHN = ',L1,/,
          +               ' MARY = ',L1)
     $$ENDDEBUG
     C
           STOP
           END
                                                                         Page 30


     7.1  The Simplest Case

          The command

         $ EXPAND TEST

     takes the  file  "TEST.CDF",  given  in  section  7,  does  the  macro
     expansion, and creates a file "TEST.VAX", listed below.

           PROGRAM TEST
     C
           INCLUDE 'C$INC:GEN202.INC/LIST'
           INCLUDE 'C$INC:OBS203.INC/LIST'
           LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
     C
     C  Set all flags to .FALSE. initially
     C
           LVAX = .FALSE.
           LCYBER = .FALSE.
           FRED = .FALSE.
           IAN = .FALSE.
           JOHN = .FALSE.
           MARY = .FALSE.
     C
           LVAX = .TRUE.
     C
           STOP
           END

     This file may now be compiled.
                                                                         Page 31


     7.2  Invoking The Fortran Compiler

          The command

         $ XFORT TEST

     is completely equivalent to the commands

         $ EXPAND TEST
         $ FORTRAN/LIST/OPTIMIZE TEST




     7.3  Use Of Qualifiers

          The command

         $ XFORT/ENV=CYBER/DEBUG TEST

     takes the  file  "TEST.CDF",  given  in  section  7,  does  the  macro
     expansion  testing  for  $$DEBUG and $$IF CYBER macro definitions, and
     produces the output file "TEST.VAX", listed below.

           PROGRAM TEST
     C
           INCLUDE 'C$INC:GEN202.INC/LIST'
           INCLUDE 'C$INC:OBS203.INC/LIST'
           LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
     C
     C  Set all flags to .FALSE. initially
     C
           LVAX = .FALSE.
           LCYBER = .FALSE.
           FRED = .FALSE.
           IAN = .FALSE.
           JOHN = .FALSE.
           MARY = .FALSE.
     C
           LCYBER = .TRUE.
           WRITE (6,100) LVAX,LCYBER,FRED,IAN,JOHN,MARY
     100   FORMAT (' LVAX = ',L1,/,
          +               ' LCYBER = ',L1,/,
          +               ' FRED = ',L1,/,
          +               ' IAN = ',L1,/,
          +               ' JOHN = ',L1,/,
          +               ' MARY = ',L1)
     C
           STOP
           END

     It then compiles "TEST.VAX" using qualifiers /OPTIMIZE/LIST.
                                                                         Page 32


     7.4  A Complicated Example

          The command

         $ XFORT/OPT=(FRED,IAN)/FORT={/MACHINE/CHECK=(OVER,UNDER)-
         $_A+B/OPT=(JOHN,MARY),C

     expands file "A.CDF" with options "FRED" and  "IAN",  and  outputs  it
     into  file  "A.VAX";  expands file "B.CDF" with options "FRED", "IAN",
     "JOHN" and "MARY", and  appends  it  to  file  "A.VAX";  expands  file
     "C.CDF" with options "FRED" and "IAN", and outputs it to file "C.VAX".
     It then issues the command

         $ FORTRAN/LIST/OPTIMIZE/MACHINE/CHECK=(OVER,UNDER) A.VAX,C.VAX

     Again, note the braces surrounding the  Fortran  options  string,  and
     that  the  first  Fortran  option begins with a "/" in the XFORT call.
     Also note that the command interpreter  allows  command  lines  to  be
     continued onto the next line.
                                                                         Page 33


     7.5  How To Use The /TRANSLATE Feature

          The /TRANSLATE qualifier allows the user to convert existing code
     to a pure Fortran--77 environment.  For this example the input file is
     "TRANS.FOR", listed below.

           PROGRAM TRANS
     C
     $$INCLUDE 'C$SIM:OBS203.INC/LIST'
     C
     c  this is a lower case comment (including the first c)
     C
           A = 5.
           B = 7.
     C
     ! This is a comment line with a !
     C
           C = SQRT (A*B)      ! this comment was at the end of the following source
                         D = C/A
     C        this    comment        line    has     tabs 
     C                   HI MOM 
     100   FORMAT ('!!!!!!!!!!!!!!!!!!!!!!!!') 
           F = D/C
     C
           STOP
           END

     This file is riddled with tabs, blank lines,  etc.,  and  would  never
     compile  anywhere  other  than  on  a VAX.  However, if one issues the
     command

         $ EXPAND/TRANSLATE TRANS.FOR

     the resultant output file "TRANS.VAX" is given below

           PROGRAM TRANS
     C
     $$INCLUDE 'C$SIM:OBS203.INC/LIST'
     C
     C  this is a lower case comment (including the first c)
     C
           A = 5.
           B = 7.
     C
     C This is a comment line with a !
     C
           C = SQRT (A*B)  
     C THIS COMMENT WAS AT THE END OF THE FOLLOWING SOURCE
                     D = C/A
     C     this  comment    line  has  tabs  
     C             HI MOM 
     100   FORMAT ('!!!!!!!!!!!!!!!!!!!!!!!!') 
           F = D/C
     C
           STOP
                                                                         Page 34


           END

                                                                         Page 35


     7.6  Using The /NOEXPAND Qualifier

          The /NOEXPAND qualifier can be  useful  if  the  user  wishes  to
     target  the source code for a non-VAX environment, but still wishes to
     have the option of compile time expansion  of  the  macro  definitions
     (N.B.   this  assumes  that  there  exists  a  version of the expander
     operating on the destination machine).  For this example, we reuse the
     file "TEST.CDF", given at the beginning of this section, and issue the
     command

         $ EXPAND/NOEXPAND/ENVIRONMENT=FTN77 TEST

     The qualifier /ENVIRONMENT=FTN77 explicitly includes the  contents  of
     any  $$INCLUDE  statement  which  the  expander  encounters, while the
     qualifier /NOEXPAND leaves the  other  macro  definitions  unexpanded.
     The resultant output file "TEST.VAX" is given below.

           PROGRAM TEST
     C
           parameter (maxgen=400)
           common /gen202/ngen,pgen(4,maxgen),kgen(2,maxgen),xvgen(3)
           equivalence (wgtgen,xvgen(1))
     c
     c  this common contains the generated particle list corresponding
     c  to the record type 20 subtype 2
     c
     c  ngen=number of particles
     c  pgen are the px,py,pz and extra word for each particle
     c  kgen are the particle type and iparent pointer
     c  xvgen are the x,y,z, of the interaction vertex.
     c  wgtgen is the (relative) generation weight of the event.
     c  maxgen is the maximum number of particle allowed
     c
           PARAMETER (MAXTOB=600,MAXVOB=600)
           COMMON /OBS203/ NTOBS,NVOBS,PTOBS(4,MAXTOB),KTOBS(5,MAXTOB),
          1PVOBS(3,MAXVOB),KVOBS(4,MAXVOB),LABOBS(16)
     C
     C  THIS COMMON CONTAINS THE OBSERVABLE PARTICLES WHICH OCCURED INSIDE
     C  OUR DETECTOR, INCLUDING ALL DECAYS, INTERACTIONS, CONVERSIONS,
     C  CATASTROPHIC De/DX, ETC.; EVEN NEUTRINOS ARE INCLUDED IN THIS LIST.
     C
     C  NTOBS = NUMBER OF PARTICLES
     C  NVOBS = NUMBER OF VERTEXES
     C  PTOBS = PX,PY,PZ, AND (    ) FOR EACH PARTICLE
     C  KTOBS = TYPE, (     ), ORIGINATING VERTEX AND TERMINATION VERTEX(=0
     C          IF NOT TERMINATED), AND PARENT PARTON.
     C  PVOBS = X,Y,AND Z FOR EACH VERTEX
     C  KVOBS = PARENT PARTICLE, FIRST AND LAST DAUGHTER PARTICLES AND
     C          INTERACTION TYPE (1=CONVERSION, 2=DECAY, 3=INTERACTION)
     C
           LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
     C
     C  Set all flags to .FALSE. initially
     C
           LVAX = .FALSE.
                                                                         Page 36


           LCYBER = .FALSE.
           FRED = .FALSE.
           IAN = .FALSE.
           JOHN = .FALSE.
           MARY = .FALSE.
     C
     $$IF VAX
           LVAX = .TRUE.
     $$IF FRED
           FRED = .TRUE.
     $$ENDIF
     $$IF IAN
           IAN = .TRUE.
     $$IF JOHN
           JOHN = .TRUE.
     $$IF MARY
           MARY = .TRUE.
     $$ENDIF
     $$ENDIF
     $$ENDIF
     $$ENDIF
     $$IF CYBER
           LCYBER = .TRUE.
     $$ENDIF
     $$DEBUG
           WRITE (6,100) LVAX,LCYBER,FRED,IAN,JOHN,MARY
     100   FORMAT (' LVAX = ',L1,/,
          +               ' LCYBER = ',L1,/,
          +               ' FRED = ',L1,/,
          +               ' IAN = ',L1,/,
          +               ' JOHN = ',L1,/,
          +               ' MARY = ',L1)
     C
           STOP
           END

     Note that the qualifier /ENVIRONMENT=FTN77 is required to specifically
     include  the contents of the $$INCLUDE statements, but (unfortunately)
     does not  affect  $$IF  conditionals  which  depend  on  the  selected
     environment.   The  expander on the destination machine must make this
     selection.
                                                                         Page 37


     7.7  Using $$ELSEIF And $$ELSE In Coding Your Macros

          The following is an example using $$ELSEIF and $$ELSE in a ".CDF"
     file

           SUBROUTINE TEST
     C
     C  This subroutine is to test out the $$ELSEIF/$$ELSE macro conditionals
     C
           IMPLICIT LOGICAL (A-Z)
     C
     $$if vax
           VAX = .TRUE.
           IBM = .FALSE.
     $$if fred
           FRED = .TRUE.
           JOHN = .FALSE.
     $$elseif john
           FRED = .FALSE.
           JOHN = .TRUE.
     $$else
           NOOPT = .TRUE.
     $$endif
     $$elseif ibm
           VAX = .FALSE.
           IBM = .TRUE.
     $$if TIM
           TIM = .TRUE.
           MIKE = .FALSE.
     $$elseif MIKE
           TIM = .FALSE.
           MIKE = .TRUE.
     $$else
           NOOPT = .TRUE.
     $$endif
     $$else
           FTN77 = .TRUE.
     $$endif
     C
           RETURN
           END

     The following command

         $ EXPAND/ENVI=IBM/OPTIONS=(TIM,MIKE)/HEADER TEST

     will produce the following output file

           SUBROUTINE TEST
     C
     C          EXPAND/XFORT Version 1.4,  6 June 1984
     C  Command line:
     C          EXPAND/ENVI=IBM/OPTIONS=(TIM,MIKE)/HEADER TEST
     C  Invoked on 8-JUN-1984 15:44:34.42
     C
                                                                         Page 38


     C  This subroutine is to test out the $$ELSEIF/$$ELSE macro conditionals
     C
           IMPLICIT LOGICAL (A-Z)
     C
           VAX = .FALSE.
           IBM = .TRUE.
           TIM = .TRUE.
           MIKE = .FALSE.
     C
           RETURN
           END

     Note that even though "MIKE" was selected  as  an  option,  since  the
     preceding  conditional  with  "TIM" was satisfied, the branch with the
     Fortran statement "MIKE = .FALSE." was included in the output file, in
     direct  analogy  with  the  Fortran "ELSEIF" statement.  Note also the
     descriptive header included in the output  file  as  selected  by  the
     /HEADER  qualifier.   This  may  be  of  use in documenting particular
     output files.
                                                                         Page 39


     7.8  Long Name Aliasing

          The following example shows how long name aliasing  may  be  done
     using the macro expander.

     $$If Vax
     $$Else
     $$Include 'Display$Source:Dalias.Inc/List'
     $$EndIf
             Program Dsp_Driver
     c
     $$Implicit
     $$Include 'Display$Source:Ddvatt.Inc/List'
     c
             Call Dsp_Initialize
             Call Dsp_Display
             Call Dsp_Display
             Call Jpause (Dsp_Current_Device)
             Call Dsp_Terminate
     c
             Stop
             End

     The following command

         $ EXPAND/ENVI=IBM DSPDRI

     will produce the following output file

     C================== Include DISPLAY$SOURCE:DALIAS.CIN ==================
     C============================ End Include ==============================
            PROGRAM DSPDRI
     C
            IMPLICIT LOGICAL A-Z
     C================== Include DISPLAY$SOURCE:DDVATT.CIN ==================
            .
            .
            .
     C============================ End Include ==============================
     C
             CALL DINIT         
             CALL DISPLY     
             CALL DISPLY     
             CALL JPAUSE (DCRTDV            )
             CALL DFIN         
     C
             STOP
             END

     There are several things to note in this example.   The  local  symbol
     "Dsp_Driver"  was  translated  "on  the  fly" to the somewhat mnemonic
     "DSPDRI" by the expander with no other programmer specification.   The
     global  symbol "Dsp_Initialize" had its alias "DINIT" specified in the
     file "Dalias.Cin", which was  searched  for  alias  specifications  at
     expand  time.   The  include  files  "DALIAS" and "DDVATT" contain the
                                                                         Page 40


     global aliases needed by the file, which is why  the  headers  appear,
     indicating that the file has been referenced.



     7.9  Do-While And Do-Enddo

          An example of the manner in which  EXPAND  translates  DO...ENDDO
     structures is given in the file TESTDO below.  Note that any number of
     DO loop nesting is supported, as is the mixture of simple DO loops and
     DO WHILE loops.

        PROGRAM TESTDO
     C--
     C  This example illustrates the translation of DO...ENDDO and DO WHILE...ENDDO
     C  constructs.
     C--
     $$IMPLICIT
     C--
     C  Alias statements.
     C--
     $$ALIAS    CONTINUE_LOOPING        CONLOO
     C--
     C  Include files.
     C--
     $$INCLUDE 'C$INC:LOGUNI.INC'
     C--
     C  Local variables.
     C--
        INTEGER         I,      J,      K
        LOGICAL         CONTINUE_LOOPING
     C
        DO I=1, 10
          DO J=1, 10
            CONTINUE_LOOPING = .TRUE.
            K = I
            DO WHILE (K.LE.J .AND. CONTINUE_LOOPING)
              WRITE(LUPRT, '('' K = '')') K
              K = K + 1
              CONTINUE_LOOPING = (K.LE.J)
            ENDDO
          ENDDO
        ENDDO
     C
        STOP
        END

     The expanded output file is shown below:

     C
     C         EXPAND/XFORT Version 3.37,  8 Dec 1987
     C  Command line:
     C         EXPAND /ENV=IBM/HEADER/OUT=*.IBM TESTDO.CDF
     C  Invoked on  7-MAR-1988 05:32:59.91
     C
                                                                         Page 41


             PROGRAM TESTDO
     C--
     C  This example illustrates the translation of DO...ENDDO and DO WHILE...ENDDO
     C  constructs.
     C--
             IMPLICIT LOGICAL(A-Z)
     C--
     C  Alias statements.
     C--
     C--
     C  Include files.
     C--
     C====================== Include C$INC:LOGUNI.CIN =======================
                .
                .
                .
     C============================ End Include ==============================
     C--
     C  Local variables.
     C--
             INTEGER         I,      J,      K
             LOGICAL         CONLOO          
     C
             DO    1 I=1, 10 
               DO    2 J=1, 10 
                 CONLOO           = .TRUE.
                 K = I
        3        CONTINUE
                 IF  (K.LE.J .AND. CONLOO          )
          &     THEN
                   WRITE(LUPRT, '('' K = '')') K
                   K = K + 1
                   CONLOO           = (K.LE.J)
                 GOTO    3 
                 ENDIF
        2      CONTINUE
        1    CONTINUE
     C
             STOP
             END

                                                                         Page 42


     7.10  The Use Of The $$BLOCK_DATA Macro

          The  following  example,  taken  from  the  CDF   offline   code,
     illustrates how the $$BLOCK_DATA macro is used to construct BLOCK DATA
     programs.  The INCLUDE files contain the declarations  of  the  common
     blocks  and  parameters,  and also contain the DATA statements for the
     BLOCK  DATA  program  enclosed  in   the   $$IF   BLOCK_DATA...$$ENDIF
     construction.  The source file for the BLOCK DATA is:

        BLOCK DATA CALBD
     C
     C  This is the block data module for the calorimetry library
     C
     $$IMPLICIT
     $$INCLUDE 'C$INC:GEOMET.INC'
     $$INCLUDE 'C$INC:TOWERE.INC'
     $$INCLUDE 'C$INC:DSTOWE.INC'
     $$INCLUDE 'C$CAL:CADECM.INC'
     $$INCLUDE 'C$CAL:CADX16.INC'
     $$INCLUDE 'C$CAL:DEADCM.INC'
     $$INCLUDE 'C$CAL:CALORIMETRY.INC'
     C
        INTEGER I
     C
     $$BLOCK_DATA 'C$INC:TOWERE.INC'
     $$BLOCK_DATA 'C$INC:DSTOWE.INC'
     $$BLOCK_DATA 'C$CAL:CADECM.INC'
     $$BLOCK_DATA 'C$CAL:CADX16.INC'
     $$BLOCK_DATA 'C$CAL:DEADCM.INC'
     $$BLOCK_DATA 'C$CAL:CALORIMETRY.INC'
     C
        END

     The dummy variable I is used as an index in an implied DO loop in  one
     of the DATA statements.  The expanded file (for /ENVIRONMENT=VAX) is:

     C
     C         EXPAND/XFORT Version 3.37,  8 Dec 1987
     C  Command line:
     C         EXPAND /HEADER/OUT=*.FOR TESTBK.CDF
     C  Invoked on  7-MAR-1988 05:35:38.90
     C
        BLOCK DATA CALBD
     C
     C  This is the block data module for the calorimetry library
     C
             IMPLICIT NONE
        INCLUDE 'C$INC:GEOMET.INC'
        INCLUDE 'C$INC:TOWERE.INC'
        INCLUDE 'C$INC:DSTOWE.INC'
        INCLUDE 'C$CAL:CADECM.INC'
        INCLUDE 'C$CAL:CADX16.INC'
        INCLUDE 'C$CAL:DEADCM.INC'
        INCLUDE 'C$CAL:CALORIMETRY.INC'
     C
                                                                         Page 43


        INTEGER I
     C
     C=========== Block_Data Initialization for C$INC:TOWERE.CIN ============

     C  Max rapidity index for each detector
        DATA MRAPTE / MYCEM, MYCHA, MYWHA, MYPEM, MYPHA, MYFEM, MYFHA/
                .
                .
     C============================ End Include ==============================
     C=========== Block_Data Initialization for C$INC:DSTOWE.CIN ============
     C
     C-- block length for each tower type
        DATA TETBLK/13,16,13,18,27,10,7,9,11,6/
     C-- PHA
        DATA TEPHAE/5*0,3,3,3,7,0/
     C-- FEM
                .
                .
        <remainder deleted>
                .
     C============================ End Include ==============================
     C
        END
       
                                                                         Page 44


     8  ERROR MESSAGES

          You will undoubtedly do something  the  expander  does  not  like
     while  you  are  learning  how to use the various qualifiers and macro
     definitions.  Doing something wrong will produce  one  or  more  error
     messages,  which are documented below.  Note that error messages which
     pertain to the syntax errors in the input  file  also  appear  in  the
     output file from the expander.

          The error  messages  issued  by  the  expander  are  all  of  the
     following type:

         %EXPAND-<severity>-<mnemonic>, <text>

     where <severity> is one of the following:

     "S" indicating success.
     "I" indicating an informational message.
     "W" indicating a warning.
     "E" indicating an error.
         or
     "F" indicating a fatal error.

     and <mnemonic> is a mnemonic for the type of error (documented in  the
     folling   sections   below).    In   addition,  the  error  codes  are
     supplemented by an english language explanation of the  error  <text>,
     which  will  hopefully explain the error and how to correct it without
     referring to this section.
                                                                         Page 45


     8.1  Table Of Error Messages


     ABORT, Abort

         Explanation:

             The expander found an error condition from which it could  not
             recover, and is terminating abnormally.  This error message is
             always preceded by another error message indicating what error
             condition occurred.

         User Action:

             Remedy the error condition  which  immediately  preceded  this
             error message.

     BADALIAS, Conflicting Alias

         Explanation:

             An conflicting set of $$ALIAS macros were detected.  This  can
             only  occur  if  a  long variable name has two or more $$ALIAS
             statements that specify different short variable  names.   The
             second $$ALIAS statement is ignored.

         User Action:

             Remove the conflicting $$ALIAS statement.

     BADCOMQUL, Bad /COMMENT qualifier

         Explanation:

             An invalid token was specified with  the  /COMMENT  qualifier.
             The valid tokens are ALL, SOURCE or NONE.

         User Action:

             Correct the /COMMENT syntax when EXPAND/XFORT is invoked.

     BADFIFO, EXPAND internal buffer corrupted

         Explanation:

             EXPAND uses an internal buffer to  store  the  expanded  code.
             This message indicates that the buffer is probably full.

         User Action:

             Reduce the size of the program being expanded.  EXPAND  stores
             only  one  program  in  its  buffer at one time, so check that
             there are valid SUBROUTINE, FUNCTION, PROGRAM  or  BLOCK  DATA
             statements  delimiting each program unit.  Otherwise, complain
             to the author.
                                                                         Page 46


     BADLNGNAM, Bad long name

         Explanation:

             An invalid long variable name was encountered.

         User Action:


     BADOPFILE, Bad output file spec

         Explanation:

             The output file specification is invalid.

         User Action:

             Check the output file specified by the /OUT qualifier.

     BADDELIM, Bad delimiter

         Explanation:

             The expander has encountered either  a  missing  or  incorrect
             delimiter  in the command string during parsing.  Most likely,
             either a delimiter was omitted from the command string  or  an
             extra delimiter was present.

         User Action:

             Reissue the command with the correct delimiter  or  number  of
             delimiters.

     BADABBREV, Bad abbreviation

         Explanation:

             The user has specified a qualifier whose length is  less  than
             three letters.

         User Action:

             The user will probably want to reissue the command with either
             the correct spelling or a proper abbreviation.

     BADENDNST, Improperly nested conditional

         Explanation:

             You  have  terminated  a  $$IF  statement  with  a  $$ENDDEBUG
             statement, or vice-versa.

         User Action:

             The user should modify  the  input  file  so  that  the  macro
                                                                         Page 47


             conditionals are properly terminated.

     BADENVIRO, Bad environment

         Explanation:

             Either the syntax of the /ENVIRONMENT qualifier  was  bad,  or
             the selected environment was not supported.

         User Action:

             Either reissue  the  command  with  the  correct  spelling  or
             reexamine your proposed destination for the file.

     BADFILNAM, Bad file name

         Explanation:

             The user has specified an invalid file name  for  one  of  the
             files which the expander must use.

         User Action:

             Reissue the command with a correct file name.

     BADFILNUM, Unacceptable number of files

         Explanation:

             The user has specified too many files (currently ten) for  the
             expander to deal with.

         User Action:

             Reissue the command with fewer input files.  Alternately,  the
             user may wish to complain to the author.

     BADFILTYP, Bad file type

         Explanation:

             The file type of the input files to the expander  defaults  to
             ".CDF".   Either  the  user  is trying to expand a file of the
             improper type, or the user has a misnamed file.

         User Action:

             Examine the input file and rename it, if appropriate.

     BADFORTSTR, Bad Fortran options

         Explanation:

             The /FORTOPT qualifier was issued with  an  incorrect  syntax.
             Note  that  the syntax of the actual Fortran options string is
                                                                         Page 48


             not checked until the FORTRAN command is issued.

         User Action:

             Reissue the command with the proper syntax.

     BADLNGNAM, Bad long name

         Explanation:

             The long name which was  to  be  translated  had  a  non-ASCII
             character in it.

         User Action:

             Change the syntax of the program line.

     BADLOGNAM, Bad logical name

         Explanation:

             The expander was unable to translate a logical name.

         User Action:

             Reissue the command with the proper spelling  of  the  logical
             name, or make sure the logical name is defined.

     BADOPTSTR, Bad options string

         Explanation:

             The /OPTIONS qualifier was issued  with  an  incorrect  syntax
             (e.g. multiple options not enclosed by parentheses).

         User Action:

             Reissue the command with the proper syntax.

     BADQUAL, Bad qualifier

         Explanation:

             The expander detected either an unrecognized qualifier  or  an
             unsupported qualifier.

         User Action:

             Either  reissue  the  command  with  the  proper  spelling  or
             reexamine your intent.

     CONTRACT, Found <...> parameters in <...> lines of code.
     CONTRACT, <...> lines of code will be removed.

         Explanation:
                                                                         Page 49


             This is a summary of the actions taken by the /CONTRACT option
             when removing un-used PARAMETER and declaration statements.

         User Action:

             This is an informational message.  The number of lines removed
             should  always  be  less  than or equal to twice the number of
             parameters found.

     CREATALIS, Alias for long name created

         Explanation:

             EXPAND/XFORT is generating an alias for a long variable name.

         User Action:

             Check that the alias created by EXPAND does not conflict  with
             any  other  local  variables  (the  compiler  will  do this is
             $$IMPLICIT is used).  If the  long  variable  name  is  for  a
             global variable, explicitly alias the variable to a short name
             that will be used globally with an $$ALIAS statement.

     DUPALIAS, Duplicate long name alias

         Explanation:

             A duplicate alias was found for a particular long name.

         User Action:

             Change the alias statement so that there is no conflict.

     DOTRANSL, Error while checking for DO...ENDDO statements.

         Explanation:

             This message is caused  either  by  incorrect  syntax  in  the
             specified source lines, or by a logic error in EXPAND/XFORT.

         User Action:

             Check the source code for any invalid  syntax  or  delimiters.
             If the source code looks correct, inform the author.

     EXPANDING, Program

         Explanation:

             EXPAND/XFORT inform  the  user  of  the  program  units  being
             expanded  when  the  code  is  being translated to the non-VAX
             environment.

         User Action:
                                                                         Page 50


             None required.  This is a purely informational message.

     FIFOFULL, Source program has too many lines

         Explanation:

             The internal buffer used by EXPAND/XFORT to hold each expanded
             subroutine has been filled.

         User Action:

             Ensure that the input source file  contains  valid  Fortran-77
             programs.  EXPAND will write out each subroutine as it is read
             in and so look for  single  programs  that  may  expand  to  a
             voluminous  output  file.  To avoid this error, consider using
             the /COMMENT qualifier to reduce  the  size  of  the  expanded
             source file.  Otherwise, complain to the author.

     HEXCVTERR, Error Converting Hexidecimal Constant

         Explanation:

             EXPAND/XFORT cannot translate a hexidecimal constant.

         User Action:

             Check  that  the  specified  source  line  contains  a   valid
             hexidecimal   constant.   The  syntax  is  'xyz'X,  where  the
             characters  in  the  quoted  string  are  any  combination  of
             0123456789ABCDEF.

     ILLGLENDDO, Unmatched ENDDO statement

         Explanation:

             An ENDDO or END DO statement has been  encountered  that  does
             not  have  a  corresponding  DO  or  DO WHILE statement in the
             preceding source code.

         User Action:

             Check that all DO...ENDDO and DO WHILE...ENDDO statements  are
             correctly specified.

     ILLGLFORT, Statement contains illegal Fortran-77 Syntax

         Explanation:

             A source line has been encountered that cannot be parsed as  a
             valid  Fortran-77  statement.   THe  most likely cause of this
             error is a bad character in the file, or a program that begins
             with a continuation line.

         User Action:
                                                                         Page 51


             Check the source lines specified in the error message.

     IMPLICIT, IMPLICIT NONE not supported in this environment

         Explanation:

             A $$IMPLICIT macro has  been  encountered  but  the  targetted
             environment does not have an equivalent of IMPLICIT NONE.

         User Action:

             Specify the /NOIMPLICIT qualifier to prevent EXPAND/XFORT from
             translating the $$IMPLICIT macros.

     IGNORQUAL, Qualifier ignored

         Explanation:

             After parsing a bad qualifier string in  the  command  string,
             the expander simply ignored the qualifier.

         User Action:

             If the qualifier was misspelled, then the user  will  probably
             want  to  reissue  the  command  with  the  correctly  spelled
             qualifier.   Otherwise,  the  qualifier  specified  is  either
             unsupported or unknown.

     IMNESELSE, Improperly nested $$ELSE conditional

         Explanation:

             Either more than one $$ELSE conditional was found  in  a  $$IF
             loop, or a $$ELSE conditional was found outside a $$IF loop.

         User Action:

             Since this can only occur due to a fault  in  the  programmers
             logic, the programmer will want to correct the input file.

     INVALISYN, Invalid "<conditional> "syntax

         Explanation:

             The syntax of a $$IF or  $$ELSEIF  command  was  found  to  be
             faulty.

         User Action:

             Supply the missing arguments for the $$IF or $$ELSEIF command.

     INVINCSYN, Invalid $$INCLUDE syntax

         Explanation:
                                                                         Page 52


             The syntax of a $$INCLUDE statement was found to be faulty.

         User Action:

             Correct the syntax of the $$INCLUDE in the  input  file  using
             the syntax of the VAX "INCLUDE" statement as a model.

     INVOPFILE, Invalid OUTPUT file

         Explanation:

             An invalid output file  has  been  specified  by  the  /OUTPUT
             qualifier.

         User Action:

             Check the file specifications for the output file.

     MSSNGQUOTE, Missing quote in statement

         Explanation:

             A source line contains either a spurious quote character or  a
             quoted   string   that  does  not  have  a  terminating  quote
             character.

         User Action:

             Check the source  lines  indicated  in  the  message  for  any
             missing or spurious quotes.

     MSSNGENDDO Missing ENDDO statement

         Explanation:

             A DO loop is not terminated with an ENDDO or END DO statement.
             This  error  can  only  occur  if the targetted environment is
             non-VAX or the /TRANSL option has been selected.

         User Action:

             Check the source code for any unterminated  DO...ENDDO  or  DO
             WHILE...ENDDO loops.

     NODELIM, No valid delimiter found

         Explanation:

             No valid delimiter was  found  for  a  given  qualifier.   For
             example,  the  /ENVIRONMENT qualifier was specified without an
             "=" immediately following it.

         User Action:

             The user will presumably want to reissue the command with  the
                                                                         Page 53


             correct syntax of the qualifier.

     NOSPLIT, Program name not found

         Explanation:

             EXPAND/XFORT could not  find  a  statement  that  defines  the
             program or subroutine name, which it needs for the filename of
             the output file.  This error only can occur if  /SPLIT  is  in
             effect.

         User Action:

             Ensure that EXPAND/XFORT is being invoked  on  a  source  file
             containing only complete program sections.

     NULFILSTR, Null file string

         Explanation:

             A  file  which  the  expander  must  use  has  a   null   file
             specification.

         User Action:

             Reissue the command with a proper file specification.

     NULOPTSTR, Null option

         Explanation:

             A null option was specified in the options string.   Probably,
             an extra comma was specified.

         User Action:

             None.

     NULQUALSTR, Null qualifier string

         Explanation:

             A qualifier specified in the command  string  was  either  all
             blanks  or of zero length.  The user probably had an extra "/"
             in the command string.

         User Action:

             None, unless the expander aborts as a result.

     OCTCVTERR, Error converting Octal Constant

         Explanation:

             An error was encountered translating an octal constant.
                                                                         Page 54


         User Action:

             Verify that the octal constant is  correctly  specified  (i.e.
             of the form 'xyz'O, where the digits between the quotes are in
             the range 0-7).

     POINTERR, Pointer error

         Explanation:

             One of the internal  pointers  which  the  expander  uses  has
             either  gotten  corrupted or a bad value due to faulty program
             logic.

         User Action:

             This is a bad one and should never happen.  If it does, please
             make an exact record (i.e. to the letter) of what happened and
             report it to the author.

     READERR, Read error

         Explanation:

             The expander could  not  read  from  the  input  file  it  was
             supposed to read from.  Somehow, the input file got munged, or
             the user does not have read access to the input file.

         User Action:

             Ensure  that  you  have  read  access  to  the   input   file.
             Otherwise,  short of a catastrophic hardware error, the author
             has no idea how this could occur.

     TOMANLOOP, Too many nested loops

         Explanation:

             You have tried to nest $$IF or $$DEBUG  statements  more  than
             ten   levels   deep.    You   must  be  doing  something  very
             complicated!

         User Action:

             Change the syntax of the input file so that the loops are  not
             so  deeply  nested.   Alternately, you may want to complain to
             the author.

     TOOMANINC, Too many nested $$INCLUDE statements

         Explanation:

             The user has nested $$INCLUDE statements more than ten deep.

         User Action:
                                                                         Page 55


             Either be slightly more  clever  about  the  coding  of  one's
             options,  or  complain  to  the author if you really need that
             level of complexity.

     TOOMANYTOKENS, Number of tokens exceeds

         Explanation:

             Too many tokens have been specified on the command line.

         User Action:

             As this error is hard to achieve with  any  realistic  command
             string, check the syntax of the EXPAND/XFORT parameter list.

     TOOMANLIN, Too many lines

         Explanation:

             The number of  expanded  source  lines  exceeds  the  internal
             buffer in EXPAND/XFORT.

         User Action:

             Make sure that the program is  not  unnecessarily  voluminous.
             Also ensure that each program section is properly delimited by
             SUBROUTINE, FUNCTION, PROGRAM or  BLOCK  DATA  statements,  as
             EXPAND/XFORT  writes  out  each expanded routine separately to
             the output file.  As a last resort, one can consider  reducing
             the  number  of comment statements in the expanded output with
             the /COMMENT qualifier.

     TOOMANYWARNINGS

         Explanation:

             More than  10  warning  messages  have  been  generated.   The
             additional warning messages are suppressed.

         User Action:

             Determine the cause of the warning  messages  and  modify  the
             source  code  to  remove  them.  Alternatively, ignore them at
             your peril.

     TOOMANALI, too many long name alias definitions

         Explanation:

             EXPAND/XFORT has run out of room to store  additional  aliases
             for long variable names.

         User Action:

             Reduce the number of long variable names being referenced,  or
                                                                         Page 56


             complain to the author.

     TOOMANOPT, Too many options

         Explanation:

             The user has specified more that ten options for a given  file
             in the command string.

         User Action:

             Either be slightly more  clever  about  the  coding  of  one's
             options,  or  complain  to  the author if you really need that
             level of complexity.

     TRANSLGNM, Long name translated

         Explanation:

             EXPAND/XFORT has encountered a long variable  name  for  which
             the user has not provided an $$ALIAS macro.  EXPAND/XFORT will
             generate an alias for the variable.

         User Action:

             Check that the short name alias generated by EXPAND  does  not
             conflict  with any short name variables appearing later in the
             source code.  Note that the compiler catches almost all  cases
             of this sort if IMPLICIT NONE (or $$IMPLICIT) is used.  Global
             variable names must be explicitly aliased by the user

     TRNSLSHRT

         Explanation:

             EXPAND/XFORT has  found  the  short  name  alias  for  a  long
             variable name used explicitly in the user's source code.  This
             probably  means  that  an  alias  generated  by   EXPAND/XFORT
             conflicts with a variable defined by the user.

         User Action:

             Check the source code for the  occurence  of  the  short  name
             alias  and  verify  that it is not being used explicitly as an
             alias for a long variable name.  If so, replace it  with  it's
             long variable name equivalent.  If it is a conflict between an
             alias generated by EXPAND, add an explicit  $$ALIAS  statement
             to  force  the  long variable name to be aliased to some other
             short name that does not conflict with existing names  in  the
             program.

     UNBALBRAC, Unbalanced braces

         Explanation:
                                                                         Page 57


             XFORT  has  detected  unbalanced  braces   in   the   /FORTOPT
             qualifier.

         User Action:

             Reissue the command with balanced braces.

     UNBLCLOS, Unable to close file

         Explanation:

             The expander was unable  to  close  a  file  which  it  either
             created  or  read.   Either the file got munged somehow during
             the expansion, the file was never created, or  something  even
             more unusual happened.

         User Action:

             Make sure that the input file you are trying to expand exists,
             that  you  have write access to the output file you are trying
             to create, and that the disk isn't full.

     UNBLOPEN, Unable to open file

         Explanation:

             The expander was unable to open a file which it either created
             or  read.   Either  the  file  got  munged  somehow during the
             expansion, the file was never created, or something even  more
             unusual happened.

         User Action:

             Make sure that the input file you are trying to expand exists,
             that  you  have write access to the output file you are trying
             to create, and that the disk isn't full.

     UNBLPRET, Unable to pretty record

         Explanation:

             The expander was unable to "pretty" up a specified  record  in
             the input file according to its algorithm.

         User Action:

             Make sure that there are no non-ASCII characters in  the  file
             which  you  are trying to expand, otherwise report the problem
             to the author.

     UNBLREAD, Unable to read from input file

         Explanation:

             The expander was unable to read from an input  file  that  was
                                                                         Page 58


             necessary for the macro expansion.

         User Action:

             Make sure that the input file you are trying to expand exists,
             as  well  as  any  "INCLUDE"  files which are explicitly being
             included, and that you have read access to these files.

     UNBLTRAN, Unable to translate character

         Explanation:

             The expander found a character in a  record  which  it  simply
             could not handle while attempting to "pretty" things up.

         User Action:

             Make sure that there are no non-ASCII characters in  the  file
             which  you  are trying to expand, otherwise report the problem
             to the author.

     UNBLWRIT, Unable to write to output file

         Explanation:

             The expander was unable to write to a file which was necessary
             for  expansion.  Either the file got munged somehow during the
             expansion, the file was never created, or something even  more
             unusual happened.

         User Action:

             Make sure that the input file you are trying to expand exists,
             that  you  have write access to the output file you are trying
             to create, and that the disk isn't full.

     UNREXPLIN, Unrecognized expand line

         Explanation:

             The expander  found  a  macro  definition  which  it  did  not
             understand

         User Action:

             The user will probably want to correct the syntax of the macro
             definition.

     UNTERMIF, <number> unterminated ...

         Explanation:

             The  expander  found  <number>  macro  conditionals  were  not
             terminated by appropriate statements.
                                                                         Page 59


         User Action:

             The user should modify  the  input  file  so  that  the  macro
             conditionals   are   terminated  with  the  appropriate  macro
             definition.
                                                                         Page 60


     9  RELEASE NOTES

     9.1  Changes Since Release 4.0


     1.  

              Blanks in include files supported.

     2.  

              Ported to MIPS, RS6000, ULTRIX and SUNOS environments.

     3.  

              Added "OR" feature in $$IF...$$ELSEIF macro.

     4.  

              Added "UNIX" environments.

     5.  

              Relative file addressing supported in unix.

     6.  

              $$ALIAS supported in MIPS environment.

     7.  

              Block data crashing fixed.

     8.  

              Long include filenames supported.




     9.2  Changes Since Release 3.0


     1.  The expander processing of  include  files  has  once  again  been
         modified.  For all environments other than "VAX", the include file
         is included as in-line code.

     2.  Expand/Xfort is now available as a native application for the  IBM
         under the VM/CMS operating system.

     3.  Improved tab handling.

     4.  Hexadecimal  and  Octal  constants  are  "validated"  for  non-VAX
         environments.  This "validation" will only affect source code that
         uses Hexadecimal or Octal constants with only Bit  31  set  (which
                                                                         Page 61


         the IBM VS Fortran compiler views as an illegal integer constant).

     5.  An error in the lookup table used for long  name  aliasing,  which
         occasionally resulted in infinite loops, has been corrected.

     6.  The expander now recognizes the  VAX  Fortran  DO-WHILE-ENDDO  and
         DO-ENDDO statements, and appropriately translates them for non-VAX
         environments.

     7.  The expander  macro  "$$IMPLICIT"  offers  programmers  a  machine
         independent  implementation  of  the  VAX  Fortran "IMPLICIT NONE"
         statement.  For the environments that  have  the  "IMPLICIT  NONE"
         statement,  the  output file contains an "IMPLICIT NONE" statement
         in the place of the "$$IMPLICIT" macro, for the environments which
         do  not  recognize  the "IMPLICIT NONE" statement, then the output
         file contains the statement "IMPLICIT LOGICAL A-Z".   In  addition
         for  the  ABSOFT  environment, the output file will also contain a
         "SAVE" statement following the "IMPLICIT NONE" statement.

     8.  Large files (>6000 records) can now be handled.

     9.  Two  new  options,   "/WARNING"   and   "/NOWARNING"   have   been
         implemented.   "/NOWARNING"  suppresses  all  the warning messages
         from  Expand  concerning  the  long  variable  name   translation.
         "/WARNING" is the default.

    10.  The handling of tabs in the IBM version has been fixed.   The  old
         version  gave rather unusual error messages when tabs were used to
         delimit tokens for the IBM version.

    11.  "ABSOFT" is now a recognized environment.  "ACP_NODE" is no longer
         a  recognized environment.  The use of "/ENVIRONMENT=ACP_NODE" has
         been  replaced   by   "/ENVIRONMENT=ABSOFT".    The   construction
         "$$If  ACP_NODE  ...  $$ENDIF"  is  still  valid  but  is meant to
         differentiate between code that runs in the host  from  code  that
         runs  within  the  ACP  node  by selecting the Expand/Xfort option
         "/OPTION=ACP_NODE".   The  use   of   "$$IF  ABSOFT  ...  $$ENDIF"
         should  be  reserved  for true compiler dependent variances of the
         same code.  A case in point is  when  I*2  variables  need  to  be
         fished     out    of    an    I*4    word.     In    all    cases,
         "/ENVIRONMENT=ABSOFT/OPTION=ACP_NODE"  should  be  specified  when
         code  is  being  compiled  to  run on an ACP node.  For code being
         compiled to run on the ACP  simulator,  the  Expand/Xfort  options
         "/ENVIRONMENT=VAX/OPTION=ACP_NODE" should be specified.

         For   the   near   future,   both   "/ENVIRONMENT=ACP_NODE"    and
         "/ENVIRONMENT=ABSOFT"  will  be  supported,  but  the intent is to
         remove ACP_NODE as a valid environment as soon as the CDF  offline
         and  Level  3  code  is  converted  to  use "/ENVIRONMENT=ABSOFT".
         User's should convert  their  own  code  to  use  the  ABSOFT  and
         ACP_NODE correctly as soon as possible.

    12.  A new option "/COMMENT" can be used to control the disposition  of
         comments  in  the Expanded output file.  The user can now have all
         comments deleted from the output file ("/COMMENT=NONE"), have only
                                                                         Page 62


         comments   occuring   in   the   primary   input   file   retained
         ("/COMMENT=SOURCE"),    or    have    all    comments     retained
         ("/COMMENT=ALL").    The   default  is  "/COMMENT=ALL",  which  is
         functionally equivalent to the previous version  of  Expand/Xfort.
         This feature is intended for user's who require small source files
         (e.g.    when   using   the    ABSOFT    debugger).     Typically,
         "/COMMENT=SOURCE"  or "/COMMENT=NONE" will generate an output file
         that is about 40% of the input file size.

    13.  The option "/HEADER" will also write to the terminal  the  version
         of Expand/Xfort being executed.  Previously, this information only
         appeared in the output file.

    14.  The qualifier /CONTRACT has been  added  that  removes  extraneous
         PARAMETER  and declaration statements from the output source file.
         This provides another method by  which  the  size  of  the  output
         source file can be reduced.

    15.  The  qualifiers  /ADD_COMMENTS  and  /NO_ADD_COMMENTS  have   been
         implemented.   They control whether EXPAND inserts FORTRAN comment
         statements into the output file.

    16.  The /DEFAULT_EXTENSIONS qualifier has been added  to  provide  the
         user the ability to control all file default file extensions.

    17.  The behaviour of the /INCLUDE and /NOINCLUDE qualifiers have  been
         radically  changed.   They now control the processing of $$INCLUDE
         macros and not the conversion of INCLUDE statements  to  $$INCLUDE
         macros.

    18.  Several  minor  bugs  have  been   fixed;   hexidecimal   constant
         conversion  has  been made more robust, and the number of DO loops
         allowed in a program has been increased to 200 from 50.




     9.3  Changes Since Release 2.0


     1.  /ENVIRONMENT=FPS is now a valid environment, corresponding to  the
         FPSx64   series  machines.   Since  the  FPS  machines  support  a
         different superset of Fortran-77 than a VAX does, the "/TRANSLATE"
         qualifier,  which  is  automatically  selected in this environment
         performs  a  subset  of  modifications  specific  to   the   "FPS"
         environment.   Specifically, since the FPS Fortran compiler allows
         both blank lines and long names, the only lines which are modified
         by  the  expander  are  those  containing  <tab>s  and  those with
         comments delimited by "!".  For the "FPS" environment, "$$INCLUDE"
         statements are included inline.

     2.  "$$INCLUDE" is handled differently for "/ENVIRONMENT=IBM".  If the
         file name in the "$$INCLUDE" statement does not contain the string
         "C$", then the include file is now included inline.
                                                                         Page 63


     3.  For non-VAX environments, if the appropriate ".CIN" file does  not
         exist,  the  ".INC" file is used instead.  Also, for include files
         which reside in the area "C$INC", the same area is used to  search
         for the the ".CIN" file.

     4.  A potentially nasty bug was fixed in that  the  expander  did  not
         correctly  handle  code  which  had options where one option was a
         substring of the other.

     5.  All source lines for "/ENVIRONMENT=IBM" are now truncated at  line
         72 to avoid distribution problems over BITnet.

     6.  The default Fortran qualifiers for XFORT are now "/OPTIMIZE/LIST".

     7.  VAX format hex constants are  now  translated  into  integers  for
         non-VAX  environments,  eliminating the need for machine dependent
         code for these constants.




     9.4  Changes Since Release 1.0


     1.  The expanders recognize input file types other  than  ".CDF",  but
         default to ".CDF".

     2.  Case is irrelevant with regards to macro definitions.

     3.  The contents of a file referenced by a  "$$INCLUDE"  statement  is
         now  included  directly  into  the  output file if the destination
         machine environment is non-VAX.

     4.  "IBM" and "FTN77" are now recognized environments.   "UNKNOWN"  is
         no longer a valid environment, "FTN77" taking the place of it.

     5.  "$$ELSE" is a new macro conditional, whose function is similar  to
         the Fortran-77 "ELSE" statement.  See section 3 for more details.

     6.  The functionality of "EXPAND" has been expanded  so  that  it  may
         function  as  a  translator  of  existing  code to the CDF offline
         format, and also  to  translate  code  for  other  machines  while
         leaving some macro conditionals unexpanded.  For more details, see
         section 4.

     7.  Examples have  been  added  to  illustrate  the  features  of  the
         previous item.

     8.  "$$ELSEIF" has been added as valid macro definition.  See  section
         3 for more details.

     9.  Records in the output file are now truncated at 133 characters.
                                                                         Page 64


    10.  An obscure bug in some copies of Relase 1.3 which  did  not  allow
         multiple  file  names  to  be entered on the command line has been
         fixed.

    11.  The "$$INCLUDE" syntax now properly transforms the syntax  of  the
         "INCLUDE" statement to the IBM syntax.

    12.  "/TEST" has  been  removed  as  a  valid  qualifier,  due  to  the
         resultant confusion due to its usage in the offline system.

    13.  The output file from EXPAND now defaults  to  the  user's  current
         default directory, in lieu of a "/OUTPUT" qualifier.

    14.  An input file type of ".CIN" now produces an output file  type  of
         ".INC"  by  default.  The intent is that this now allows for macro
         definitions in "INCLUDE" files.

    15.  The "$$INCLUDE" in the input file now produces <tab> "INCLUDE"  in
         the output file if "/ENVIRONMENT=VAX" has been selected.

    16.  The qualifier "/TRANSLATE" is now allowed in "XFORT".

    17.  "$$INCLUDE" files may now have macro definitions embedded in them,
         and  as  well  may  have other "$$INCLUDE" specifications in them.
         Includes may be nested up to ten levels deep.

    18.  A bug  has  been  fixed  for  the  "/FTN77"  environment  when  it
         explicitly  includes  the  contents  of  the include file.  It now
         looks for the corresponding ".CIN" file, and expands it  with  the
         appropriate  qualifiers  of  the  parent file of which the include
         file is a part.

    19.  "ACP_NODE" is now a valid environment.

    20.  The output file type now defaults to the same as  the  input  file
         type,  when  specified, unless the input file type is ".CIN, .INC,
         .CDF, .FOR".  The respective output file types  are  ".INC,  .CIN,
         .FOR,  .CDF".   If  no  file  type  is  specified, the input still
         defaults to ".CDF", and the output to ".FOR".

    21.  Limited wildcarding of  the  output  file  is  now  allowed.   For
         example,  the  qualifier "/OUTPUT=*.FTN" will direct the output of
         the expander to the users current default directory with  filetype
         ".FTN".   The  asterisk  must be the first character in the output
         specification.  Wildcarding is allowed both in  local  and  global
         qualifiers.

    22.  "$$IF" and "$$ELSEIF" are now protected to ensure that  either  an
         option   or   a  qualifier  has  been  specified  with  the  macro
         definition.

    23.  Translation of Fortran variable names which are  longer  that  six
         characters   for   non-VAX  environments  is  now  supported.   In
         particular, local variable names need  not  have  the  short  name
         aliases  explicitly  specified.  See section 3 and section 5.9 for
                                                                         Page 65


         more details.

    24.  There is a new macro definition "$$ALIAS".  See section 3 for more
         details.

    25.  "$$INCLUDE" has  changed  slightly  for  "/ENVIRONMENT=IBM".   The
         appropriate  ".CIN"  file  will  be scanned, as well as any nested
         ".CIN" file, for any "$$ALIAS" statements which  are  required  to
         properly  translate  global variables in the source file.  Headers
         as to which file has been referenced appear in  the  output  file,
         but otherwise the "INCLUDE" file syntax in the output file remains
         as before.  This change was mandated in order to allow translation
         of long names for "/ENVIRONMENT=IBM".