1 EXPAND
   The macro expanders EXPAND and XFORT are designed to provide the
user a powerful and flexible approach towards coding within the CDF 
environment, particularly with regards to multiple machine architectures.
In addition, they offer macro expansion and debugging facilities which are
transparent to the FORTRAN compiler and destination machine architectures.

   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. Note that the input file type defaults to .CDF. Otherwise, the
expander uses the specified in put file type specification. EXPAND
produces a .FOR file in the user's current default directory, which one
may then compile using the FORTRAN compiler. If the input file type is
.CIN, .FOR, or .INC, then the output file defaults to respectively
.INC, .CDF, and .CIN.  This is to allow macro definitions within
INCLUDE statements.  XFORT goes one step further in that it actually
invokes the VAX FORTRAN compiler with default qualifiers /DEBUG/LIST. 

   The EXPAND and XFORT commands are defined as foreign DCL commands:

	$ EXPAND :== $FERMI$EXE:EXPAND
	$ XFORT :== $FERMI$EXE:XFORT

2 Filestrings
   <filestring> may consist of up to 10 files, separated by either 
a comma, if one wishes separate output files, or a plus sign, if 
one wants them concatenated into a single output file.  You may mix 
both delimiters in one command.  In addition, <filestring> may have 
local qualifiers appended to it, while the expander name may have 
global qualifiers appended to it.  Both the qualifier syntax and 
the difference between local and global qualifiers is described 
in under the section Qualifiers.

2 Macro_definitions
   Both expanders understand the following macro definitions:

      $$INCLUDE <filespec>
      $$IF VAX
      $$IF CYBER
      $$IF IBM
      $$IF FTN77
      $$IF FPS
      $$IF <option>
      $$ELSE
      $$ELSEIF <option>
      $$ENDIF
      $$DEBUG
      $$ENDDEBUG
      $$ALIAS <long name> <short name>

Macro definitions may occur anywhere on a line in the input file,
but must not be preceded by any nonblank characters.  Macro definitions 
may not be abbreviated.  Case is irrelevant for macro definitions.

3 $$INCLUDE
   The macro equivalent of the VAX FORTRAN INCLUDE statement is called
$$INCLUDE.  Interpretation for the VAX is the same as the VAX INCLUDE
statement.  For /ENV=IBM, the syntax of the INCLUDE statement is changed
to the IBM INCLUDE syntax. For other machine environments, the contents
of the relevant .CIN file are expanded and simply included in the
expanded source file.  Macro definitions, including $$INCLUDE
statements, are allowed in $$INCLUDE files.  $$INCLUDE files may be
nested up to ten levels deep.  On the VAX, this macro definition is
simply replaced by the equivalent INCLUDE line.  Note that this is the
only macro definition which must be used in the CDF offline coding
environment. 

3 $$IF
   A general purpose macro definition for conditionals is $$IF. The
expander recognizes several different destination machine
architectures, called ENVIRONMENTs.  These are VAX, CYBER, IBM, FPS,
ACP_NODE, and FTN77.  The appearance of a $$IF <environment> line in
the input file calls for the expander to attempt to match that
environment with the selected environment of the calling sequence.  If
a match is found, those lines until the terminating $$ENDIF are
included in the output file, otherwise they are discarded. 

   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 calling sequence for <option>.  Note that there must be
exactly one space between $$IF and either <environment> or <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.

3 $$ELSE
   The macro conditional $$ELSE offers the user more flexibility in
his/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.

3 $$ELSEIF
   The macro conditional $$ELSEIF works in much the same way as
the macro conditional $$ELSE, except that it allows the
programmer much more fleibility in coding his/her macro
conditional 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
in that if any of the preceding macro conditions were satisfied,
the current and all subsequent $$ELSEIF statements will be
ignored!  See the examples for more details. 

3 $$ENDIF
   The macro definition $$ENDIF terminates a pending $$IF statement.
For more information, see $$IF

3 $$DEBUG
   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.

3 $$ENDDEBUG
   The macro definition $$ENDDEBUG terminates a previous pending
$$DEBUG statement.  For more information, see $$DEBUG.

3 $$ALIAS
   There are two different ways of accommodating Fortran
variables which are longer that six characters.  Local
variables, i.e. variables which are local to that program unit,
are handled without any macro definitions whatsoever.  The
expander simply recognizes the long name and translates the
long name to an appropriately mnemonic short name in the output
file.  Global long names, e.g. subroutine names, must be
explicitly declared via the $$ALIAS statement, since it can not
be guaranteed that the expander will pick consistent short names
at expand time in each file which 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's actual
code.  Note that global aliases must be set up in each file
which references the global symbol.  A very convenient way of
doing this is by putting the $$ALIAS statements in a .CIN file
which is included before the first non-comment statement in the
file. Variable names which occur in Common blocks may be
similarly aliased in the .CIN file. In both cases, it is only
necessary to keep one copy of the global aliases. 

   There are some minor restrictions on Fortran coding syntax
when using long names.  Since this is NOT a compiler, spaces,
TABs or valid Fortran delimeters are required to separate
Fortran language elements and constants from variable names. 
For example the syntactically correct (but abhorrent) Fortran
statement 

      Do 10Long_Name = 1, 4 

will hopelessly confuse the expander. This is due to the fact
that there are no reserved words in the Fortran language, i.e.,
the statement 

      REAL REAL 

is a perfectly valid Fortran statement. 

   Finally, note that the expander can only understand Fortran
variables which are longer that six characters if they contain
either "_" or "$".  The expander will NOT handle things like
ENDDO statements and DO WHILE statements.  Subsequent versions
of the expander with FLECS-like capabilities might be considered
in the future. 

2 Qualifiers
    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).  Local /FORTOPT
qualifiers are understood but not supported.  They are interpreted as
global qualifiers.

/[NO]DEBUG
   The qualifier /DEBUG enables code delimited by $$DEBUG and
$$ENDDEBUG lines, while the qualifier /NODEBUG disables code
delimited by $$DEBUG and $$ENDDEBUG lines.  The default is /NODEBUG.
Both EXPAND and XFORT understand /[NO]DEBUG.

/OUTPUT=filespec
  The qualifier /OUTPUT=<filespec> writes the output from the expander
into file <filespec>.  The qualifier /OUTPUT=*.<filetype> writes the
output from the expander into the file <input file name>.<filetype>.
Note that that you must of course have write access to <filespec> for
this qualifier to work.  Records are truncated at 133 characters in the
output file.  Both EXPAND and XFORT understand the /OUTPUT qualifier.
The default is /OUTPUT=*.FOR.

/OPTIONS
   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.  Both EXPAND and
XFORT understand the /OPTIONS qualifier.

/ENVIRONMENT=name
   The qualifier /ENVIRONMENT=<environment> enables code delimited by 
$$IF <environment> and $$ENDIF.  While the 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 resultant
confusion from this redundancy of syntax is offset by the simplicity
of use.  Both EXPAND and XFORT accept the /ENVIRONMENT qualifier.
The default is /ENVIRONMENT=VAX, the other acceptable environments
are IBM, FTN77, ACP_NODE, CYBER and FPS.

/[NO]HEADER
   The qualifier /HEADER produces a descriptive header both to
SYS$OUTPUT and to the output file giving the version number of
the expander which was used to produce the output file. In
addition, the output file also has the command line which was
used to invoke the expander, and the time at which the expander
was invoked. This particular feature may be useful in documenting
certain output files in particularly complicated coding environments. 
Both EXPAND and XFORT accept the /HEADER qualifier, the default
setting is /NOHEADER.

/[NO]EXPAND
   The qualifier /EXPAND enables the expansion of the macro definitions
in the output file.  Only the EXPAND program uses the /EXPAND qualifier.
The default action is /EXPAND.

   The qualifier /NOEXPAND disables the expansion of the 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 (s)he wishes (e.g. /DEBUG).

/[NO]INCLUDE
   The qualifier /INCLUDE takes all Fortran INCLUDE statements in the
input file and translates them to $$INCLUDE statements, in preparation
for creation of an expander input file from existing source.  Only the
EXPAND program accepts the /INCLUDE qualifier.  The default setting
is /NOINCLUDE.

/[NO]TRANSLATE
   The qualifier /TRANSLATE takes an input file and removes TAB's, 
blank lines, comments flagged by "!", and translates all non-commented 
lines to upper case.  This is intended to translate existing code for 
a pure FORTRAN-77 environment.  Note that the environments IBM, CYBER 
and FTN77 in fact invoke the /TRANSLATE qualifier (the FPS environment
enables a partial translation since long names and blank lines are
accepted by the FPS Fortran compiler).  Both EXPAND and XFORT accept
the /TRANSLATE qualifier; the default setting is /NOTRANSLATE.

/FORTOPT={<qualifiers>} (default = /DEBUG/LIST)
   This qualifier is only accepted by the XFORT program to pass
qualifiers to the VAX FORTRAN compiler.  Note that the braces {} must
be present around the /FORTOPT qualifier string (this is obvious once
one realizes that the string may have an embedded "/", etc.).
Qualifiers may be either global (i.e. applying to all the files to be
expanded) by appending the qualifier directly to the expander name,
or local (i.e. applying only to a particular file) by appending the
qualifier directly to the filename.  The defaults used by XFORT are
"/FORTOPT={/DEBUG/LIST}".

2 Examples
   For the examples listed below, the following file TEST.CDF
is used.

            PROGRAM TEST
C
C  This is quick little test program to illustrate the usage of the 
C  macro expanders
C
C  Mark W. Eaton  10/83
C
INCLUDE 'CINC:GEN202.INC/LIST'
INCLUDE 'CINC:OBS203.INC/LIST'
            LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
C
C------------------------------------------------------
C
C  Set all flags to .FALSE. initially
C
            LVAX = .FALSE.
            LCYBER = .FALSE.
            FRED = .FALSE.
            IAN = .FALSE.
            JOHN = .FALSE.
            MARY = .FALSE.
$$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
            STOP
            END

3 The_simplest_case 
   The command

      $ EXPAND TEST

takes the file TEST.CDF, given above, does the macro expansion, 
and creates a file TEST.FOR, listed below.

            PROGRAM TEST
C
C  This is quick little test program to illustrate the usage of the 
C  macro expanders
C
C  Mark W. Eaton  10/83
C
            INCLUDE 'CINC:GEN202.INC/LIST'
            INCLUDE 'CINC:OBS203.INC/LIST'
            LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
C
C------------------------------------------------------
C
C  Set all flags to .FALSE. initially
C
            LVAX = .FALSE.
            LCYBER = .FALSE.
            FRED = .FALSE.
            IAN = .FALSE.
            JOHN = .FALSE.
            MARY = .FALSE.
            LVAX = .TRUE.
            STOP
            END

This file may now be compiled.

3 Compiling_also 
   The command

      $ XFORT TEST

is completely equivalent to the commands

      $ EXPAND TEST

and

      $ FORTRAN/LIST/DEBUG TEST

3 Using_qualifiers 
   The command

      $ XFORT/ENV=CYBER/DEBUG TEST

takes the file TEST.CDF, given above, does the macro expansion testing 
for $$DEBUG and $$IF CYBER macro definitions, and produces the output file
TEST.FOR, listed below.

            PROGRAM TEST
C
C  This is quick little test program to illustrate the usage of the 
C  macro expanders
C
C  Mark W. Eaton  10/83
C
            INCLUDE 'CINC:GEN202.INC/LIST'
            INCLUDE 'CINC:OBS203.INC/LIST'
            LOGICAL LVAX,LCYBER,FRED,IAN,JOHN,MARY
C
C------------------------------------------------------
C
C  Set all flags to .FALSE. initially
C
            LVAX = .FALSE.
            LCYBER = .FALSE.
            FRED = .FALSE.
            IAN = .FALSE.
            JOHN = .FALSE.
            MARY = .FALSE.
            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)
            STOP
            END

It then compiles TEST.FOR using qualifiers DEBUG/LIST.

3 A_bigger_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.FOR; expands file B.CDF with options FRED, IAN, JOHN and MARY, 
and appends it to file A.FOR; expands file C.CDF with options 
FRED and IAN, and outputs it to file C.FOR.  It then issues the command

      $ FORTRAN/LIST/DEBUG/MACHINE/CHECK=(OVER,UNDER) A.FOR,C.FOR

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 commands do allow command lines to be continued 
onto the next line.

3 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
C  This program is to test out the translation features of the 
C  macro expanders.
C
C  Mark W. Eaton  1/84
$$INCLUDE 'C$SIM:OBS203.INC/LIST'
C               include 'c$sim:obs203.inc/list'
C
C------------------------------------------------------------------------------
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 = SQRT (A*B)	! this comment was at the end of the previous source
      				D = C/A
C	this	comment		line	has	tabs 
C                   HI MOM 
 100  FORMAT ('!!!!!!!!!!!!!!!!!!!!!!!!') 
      F = D/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.FOR is given below

      PROGRAM TRANS
C
C  This program is to test out the translation features of the 
C  macro expanders.
C
C  Mark W. Eaton  1/84
$$INCLUDE 'C$SIM:OBS203.INC/LIST'
C               include 'c$sim:obs203.inc/list'
C
C------------------------------------------------------------------------------
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 = SQRT (A*B)  
C THIS COMMENT WAS AT THE END OF THE PREVIOUS SOURCE
              D = C/A
C     this  comment    line  has  tabs  
C                   HI MOM 
 100  FORMAT ('!!!!!!!!!!!!!!!!!!!!!!!!') 
      F = D/C
      STOP
      END

3 Using_NOEXPAND
   The /NOEXPAND qualifier can be useful it 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
ther exists a version of the expander operating on the destination machine).
for this example, we reuse the file TEST.CDF, given at the previous level
of this help file, 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 /NOEXPAND 
leaves the other macro definitions unexpanded.  The resultant output 
file TEST.FOR is given below.

      PROGRAM TEST
C
C  This is quick little test program to illustrate the usage of the 
C  macro expanders
C
C  Mark W. Eaton  10/83
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),
     1	PVOBS(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-------------------------------------------------------------------------
C
C  Set all flags to .FALSE. initially
C
      LVAX = .FALSE.
      LCYBER = .FALSE.
      FRED = .FALSE.
      IAN = .FALSE.
      JOHN = .FALSE.
      MARY = .FALSE.
$$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
      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.

3 Using_$$ELSE
   The following example illustrates the usage of the $$ELSE macro
conditional.  Note that it is fully integrated within the logic of the
expander, i.e. it may be implemented in a nested $$IF block at any level.
The following file ELSE.CDF is used in this example.

      SUBROUTINE TEST
C
C  This subroutine is to test out the $$ELSE macro conditional
C
$$if VAX
$$INCLUDE 'M$CMS:FILES.INC/LIST'
$$ENDIF
C
C----------------------------------------------------------------------
C
$$if vax
      VAX = .TRUE.
$$if fred
      FRED = .TRUE.
$$else
      FRED = .FALSE.
$$endif
$$else
      VAX = .FALSE.
$$if ibm
      IBM = .TRUE.
$$if john
      JOHN = .TRUE.
$$else
      JOHN = .FALSE.
$$endif
$$endif
$$endif
      RETURN
      END

The command,
      
      $ EXPAND/ENVI=IBM/OPTIONS=(FRED,JOHN) ELSE

will yield the output file ELSE.FOR, given below

      SUBROUTINE TEST
C
C  This subroutine is to test out the $$ELSE macro conditional
C
C
C------------------------------------------------------------------
C
      VAX = .FALSE.
      IBM = .TRUE.
      JOHN = .TRUE.
      RETURN
      END

Note that all the  acro conditionals which were nested after the $$IF
VAX statement were ignored.

3 Using_$$ELSEIF
   The following is an example using $$ELSEIF in a .CDF file

      SUBROUTINE TEST
C
C  This subroutine is to test out the $$ELSE macro conditional
C
      IMPLICIT LOGICAL (A-Z)
C
C------------------------------------------------------------------------
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
      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
C
C  This subroutine is to test out the $$ELSE macro conditional
C
      IMPLICIT LOGICAL (A-Z)
C
C------------------------------------------------------------------------
C
      VAX = .FALSE.
      IBM = .TRUE.
      TIM = .TRUE.
      MIKE = .FALSE.
      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. 

3 LongName_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
c================================================================ 
        Program Dsp_Driver
c================================================================
c
c  Description:
c  ============
c  Main program for display program tests
c
c  Language
c  ========
c  VAX Expand (Fortran)
c
c  Author:
c  =======
c  Mark W. Eaton
c  Harvard University - CDF
c  42 Oxford St.
c  Cambridge, MA 02138
c
c  Phone: (617) 495-2909
c  FTS:         830-2909
c  High Energy Physics DECnet:  HUHEPL::EATON
c  BITNET:  (HARVHEP)EATON
c
c  Revision History:
c  =================
c  April 9, 1985 - Original creation
c  April 24, 1985 - Implement termination routines, etc.
c  June 4, 1985 - Put in second call to event display
c
c================================================================
c
$$If Vax
        Implicit None
$$EndIf
$$Include 'Display$Source:Ddvatt.Inc/List'
c
c  Executable Code:
c  ================
c
        Call Dsp_Initialize
        Call Dsp_Display
        Call Dsp_Display
        Call Jpause (Dsp_Current_Device)
        Call Dsp_Terminate
        Stop
        End

The following command

      $ EXPAND/ENVI=IBM DSPDRI

will produce the following output file

C================== Include DISPLAY$SOURCE:DALIAS.CIN ============
C============================ End Include ========================
C=================================================================
       PROGRAM DSPDRI    
C=================================================================
C
C  Description:
C  ============
C  Main program for display program tests
C
C  Language
C  ========
C  VAX Expand (Fortran)
C
C  Author:
C  =======
C  Mark W. Eaton
C  Harvard University - CDF
C  42 Oxford St.
C  Cambridge, MA 02138
C
C  Phone: (617) 495-2909
C  FTS:         830-2909
C  High Energy Physics DECnet:  HUHEPL::EATON
C  BITNET:  (HARVHEP)EATON
C
C  Revision History:
C  =================
C  April 9, 1985 - Original creation
C  April 24, 1985 - Implement termination routines, etc.
C  June 4, 1985 - Put in second call to event display
C
C=================================================================
C
       INCLUDE (DDVATT)
C================== Include DISPLAY$SOURCE:DDVATT.CIN =============
C============================ End Include =========================
C
C  Executable Code:
C  ================
C
       CALL DINIT         
        CALL DISPLY     
        CALL DISPLY     
        CALL JPAUSE (DCRTDV            )
        CALL DFIN         
        STOP
        END

Note several things 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 symobl 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 global aliases needed by the file, which is
why the headers appear, indicating that the file has been
referenced. 

2 Error_messages

   You will doubtlessly 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-<errorcode>-<error>

where <errorcode> is either "W", indicating a warning, or "F", 
indicating a fatal error. <error> is a mnemonic for the type of error, 
documented below.  In addition, the error codes are supplemented
by an english language explanation of the error, which will hopefully
explain the error and how to correct it without referring to this section.

3 ABORT
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.

3 BADDELIM
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.

3 BADABBREV
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.

3 BADENDNST
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 conditionals are properly terminated.

3 BADENVRIO
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.

3 BADFILNAM
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.

3 BADFILNUM
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.

3 BADFILTYP
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.

3 BADFORSTR
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 not checked until the FORTRAN command is issued.

      User Action: Reissue the command with the proper syntax.

3 BADLOGNAM
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.

3 BADOPTSTR
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.

3 BADQUAL
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.

3 IGNORQUAL
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.

3 IMNESELSE
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.

3 INVINCSYN
INVINCSYN, Invalid $$INCLUDE syntax

      Explanation: 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.

3 NODELIM
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 correct syntax of the qualifier.

3 NULFILSTR
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.

3 NULOPTSTR
NULOPTSTR, Null option

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

      User Action: None.

3 NULQUALSTR
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.

3 POINTERR
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.

3 READERR
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.

3 TOMANLOOP
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.

3 TOOMANINC
TOOMANINC, Too many nested $$INCLUDE statements

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

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

3 TOOMANOPT
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 of 
      complexity.

3 UNBALBRAC
UNBALBRAC, Unbalanced braces

      Explanation: XFORT has detected unbalanced braces in the 
      /FORTOPT qualifier.

      User Action: Reissue the command with balanced braces.

3 UNBLCLOS
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.

3 UNBLOPEN
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.

3 UNBLPRET
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 charcters in
      the file which you are trying to expand, otherwise report the
      problem to the author.

3 UNBLREAD
UNBLREAD, Unable to read from input file

      Explanation: The expander was unable to read from an input file 
      that was 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.

3 UNBLTRAN
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 charcters in
      the file which you are trying to expand, otherwise report the
      problem to the author.

3 UNBLWRIT
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.

3 UNREXPLIN
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.

3 UNTERMIF
UNTERMIF, <number> unterminated ...

      Explanation:  The expander found <number> macro conditionals 
      were not terminated by appropriate statements.

      User Action: The user should modify the input file so that the
      macro conditionals are terminated with the appropriate macro 
      definition.
