   README file for Ftnchek Version 2.7

Author: Robert Moniot
	Fordham University
	New York, NY  10023  USA
	Telephone: (212) 636-6311
	Bitnet:    MONIOT@FORDMULC
	Internet:  moniot@mary.fordham.edu

Date:	August 1993

Ftnchek is written in a portable style of C.  You must have a C
compiler for the machine on which you wish to build it.

If the file you received is in the form of a "shell archive" or "shar"
file, and you received it by electronic mail, you should first
concatenate all parts in order (if it was sent in pieces), removing
any mail headers.  If you received it by ftp, this step should not be
necessary.  Next, if you have a UNIX system, simply feed it as input
to the program "sh" to unpack it automatically.  If you do not have a
UNIX system, you will have to use your text editor to clip out each
file manually.  You will observe that each line of every file has been
prefixed with the letter X.  You should use your editor to remove all
initial X's.  It is also possible that tabs may have been converted to
blanks during transport over the network.  This should not matter for
any files except the makefiles, where you should change any indented
lines so that the indentation is replaced by a single tab.

If the file you received is a Unix compressed tar file, you should
first unzip it using the Unix "uncompress" command, and then give it
as input to "tar" to unpack the files.  For example, assuming the file
has been placed in the desired directory, and is named ftnchek.tar.Z, you
would give the two Unix commands
	uncompress ftnchek.tar.Z
	tar -xf ftnchek.tar

After accomplishing this step, you should find that you have received
the following set of source files:

       exprtype.c       ftnchek.h        pgsymtab.c       symtab.c
       forlex.c         intrins.h        plsymtab.c       symtab.h
       fortran.c        iokeywds.h       project.c        tokdefs.h
       ftnchek.c        keywords.h

These are all necessary for compiling Ftnchek on any system.  You
should also have received the following auxiliary files:

       average.f        makefile         makefile.unix    newcome.c
       average.out      makefile.bc      newarge.c        newcomh.c
       build.com        makefile.mpw     newargh.c        shell_mung.c
       fortran.y

The file average.f contains the example program used in the
documentation, and average.out is the result of running Ftnchek on it.
VAX/VMS users should rename "AVERAGE.F" to "AVERAGE.FOR".  The file
build.com contains the commands for creating the executable and help
library for VMS.  The file named makefile is the same as
makefile.unix.  The other makefiles are specialized for Borland C (IBM
PC), Macintosh Programmer's Workbench, and Unix or Unix-like systems.
The file fortran.y contains the grammar from which the parser
fortran.c was created.  (The file fortran.c has been trimmed to
shorten it for transmission over electronic networks.)  It is not
needed to compile Ftnchek.  The file shell_mung.c is needed only for
the VMS version of Ftnchek.  It is from the GNU project.  The files
newarge.c, newargh.c, newcome.c, and newcomh.c are used for the
Borland C version.

Documentation is in the files:

        ftnchek.doc     ftnchek.hlp      ftnchek.man      ftnchek.ps

The first is a flat text file.  Ftnchek.hlp is for making a help
library for VMS systems.  Ftnchek.man and ftnchek.ps are provided for
the convenience of those with access to nroff/troff or PostScript,
respectively.

Once Ftnchek is working, you can test it by giving the command:

        $ ftnchek -list -sym average

Then compare the output against the file "average.out".

To install Ftnchek, follow the instructions below for your operating
system.


(1) Unix and Unix-like systems

   Give the command:

        $ make

Note: System-specific compilation options are provided for some
systems.  Users installing Ftnchek on one of these systems should
say

	$ make system

where system is one of the following words:

       IBM-RS6000       SOLARIS2.x       SUNOS4.1         ULTRIX-MIPS
       GENERIC          STARDENT         SUNOS5.x         UNIX
       SGI              SUNOS4.0

Also, see below for options that allow compiling with bigger
table sizes or accepting/rejecting certain syntax extensions.


(2) VAX/VMS

   Give the command

        $ @BUILD

   After the program has been compiled, you must turn it into a
   so-called "DCL foreign command" so that it can be invoked by
   giving its name on a command line, instead of using the RUN
   command.  Do this with the command

        $ FTNCHEK :== $disk:[directory]FTNCHEK

   where you substitute the disk and directory names where the file
   FTNCHEK.EXE resides.  This command must be executed once per
   login.  It is suggested you put this command into your LOGIN.COM
   file.

   The BUILD procedure also creates a VMS help library named
   FTNCHEK.HLB.  To access it from the VMS HELP command, you must
   give the command

        $ DEFINE HLP$LIBRARY disk:[directory]FTNCHEK.HLB"

   Again, this command must be executed once per login to have effect.


(3) MS-DOS with Turbo C

   Rename the file "makefile.bc" to "makefile" and then give the
   command:

        C> MAKE


(4) Macintosh Programmer's Workshop (MPW)

   Rename the file "makefile.mpw" to "makefile".  Edit the file,
   changing character '+' to CHAR(182), option-d on the Macintosh
   keyboard; and the character '/' to CHAR(196), option-f.  Then
   use the "make" command to create Ftnchek.

(5) Other systems

   It should suffice simply to compile all the ".c" files (omitting
   shell_mung.c and new*.c) and link them, .  The only differences among
   the versions for different operating systems have to do with the use of
   "/" vs. "-" as an option prefix, the default filename extension
   ".FOR" vs. ".f", and the selection of some system-specific language
   extensions.  Selection among these options is done by defining a
   macro name for each system.  The VAX/VMS compiler pre-defines the
   macro name "VMS", while the Turbo C compiler pre-defines
   "__TURBOC__".  The macro names "UNIX" and "MSDOS" are not
   pre-defined and must be defined on the compiler command line or by
   editing ftnchek.h if they are desired.

   See the section below for more details about using macro names to
   control the system-dependent choices available in compiling
   Ftnchek.


Ftnchek has a number of fixed internal parameters that affect its
operation, such as the symbol table sizes and support for various
extensions and particular operating systems.  The following is a
description of the most important of these parameters.  They are
implemented as C language macro names.  If you wish to change a
parameter defined by one of these macros, it is necessary to recompile
Ftnchek with the macro definition changed to the desired value.

Briefly, the effect of the macro names specifying the system is as
follows: If VMS or __TURBOC__ or MSDOS is defined, then both "/" and
"-" are allowed as option prefixes.  Otherwise only "-" is allowed.
If VMS or __TURBOC__ or MSDOS is defined, then ".FOR" will be the
default extension for source files, otherwise ".f" is used.  If VMS is
defined, then the VMS extensions controlled by VMS_INCLUDE,
VMS_INTRINSICS, VMS_IO, and VMS_TAB will be supported.  If UNIX is
defined, then the Unix nonstandard intrinsic functions will be
supported and preprocessor directives will be tolerated.  More
detailed control over these options is possible by defining other
macro names described below.

This can usually be done without editing any of the source files, by
specifying the macro definition on the C compiler command line.  Under
Unix, this is done with the -D option.  For example, to define the
macro BpW that sets the default word size to be eight bytes, the
compiler would be invoked with the additional option -DBpW=8.  Under
VMS, the corresponding option would be /DEFINE=("BpW=8").  For other
systems, consult your C compiler manual.

Unless otherwise noted, the following macro names need not have any
particular value.  They only need to be defined in order to have
effect.  For more details on these parameters, look at ftnchek.h.


  Macro                 Meaning                           Remarks
UNIX                  Compile Ftnchek for Unix-like    Default for most
                       operating system                 choices
VMS                   Compile Ftnchek for VAX/VMS      Automatically defined
                       operating system                 by VAX C compiler
MSDOS                 Compile Ftnchek for MS-DOS       Automatic if compiler
                       operating system                 is Turbo C

UNIX_CPP              Tolerate Unix preprocessor       Default if UNIX defined
                       lines starting with #
NO_UNIX_CPP           Do not tolerate them             For UNIX w/o UNIX_CPP

VMS_IO                Add support for VMS-Fortran      Implied by VMS unless
                       I/O keywords                     NO_VMS_IO defined
NO_VMS_IO             Do not support VMS-Fortran       For VMS but not VMS_IO
                       I/O keywords
VMS_INCLUDE           Add support for VMS-style        Implied by VMS unless
                       INCLUDE statement features        NO_VMS_INCLUDE defined
                       (default extension, /NOLIST)
NO_VMS_INCLUDE        Do not support VMS-style         For VMS but not
                       INCLUDE statement features       VMS_INCLUDE
VMS_TAB               Accept VMS-style tab-formatted
                       source lines.
NO_VMS_TAB            Do not accept tab-formatting.    For VMS but not VMS_TAB

OPTION_PREFIX_SLASH   Allow options to start with      Implied by VMS and by
                       either - or /.                   MSDOS

DEF_SRC_EXTENSION     Default extension expected       Defaults:
                       for input source files	        VMS, MSDOS: ".for"
                                                        All others: ".f"
DEF_LIST_EXTENSION    Default extension for output     Default: ".lis"
                       list-files
DEF_PROJ_EXTENSION    Default extension for input      Default: ".prj"
                       and output project files
STDIN_PROJ_FILENAME   Output project-file name used    Default: "ftnchek.prj"
                       when input source is stdin


STRICT_SYNTAX         Disallow underscores or dollar   Each option can be
                      signs in variable names, inline   restored by a
                      comments (with ! character)       macro in next group
                      INCLUDE or DO .. ENDDO statements.
                      variable field widths in FORMAT,
                      and hex, octal and binary constants

The following seven macros are all defined by default unless
STRICT_SYNTAX is defined.  If STRICT_SYNTAX is defined, then any of
the individual options can be selected by defining the corresponding
individual macro.

ALLOW_DOLLARSIGNS     Allow dollar signs in variable
                      names
ALLOW_UNDERSCORES     Allow underscores in variable
                      names
INLINE_COMMENT_CHAR   Allow Inline comments starting   Must be defined
                       with '!'                          as '!'
ALLOW_INCLUDE         Support INCLUDE statement
                      names
ALLOW_DO_ENDO         Support DO ... ENDDO statements
                      names
ALLOW_VARIABLE_FORMAT Accept <integer_expr> in format
                      for repeat or field width
TYPELESS_CONSTANTS    Accept Z'19AF' and similar hex
                       octal and binary constants

The nonstandard double complex intrinsic functions are always
supported since they are needed by the double complex datatype.  Other
groups of nonstandard functions can be selected by the following group
of macros.

STANDARD_INTRINSICS   Do not support extended set
                       of intrinsic functions
NONSTD_INTRINSICS     Support commonly available       Default behavior
                       intrinsic functions
UNIX_INTRINSICS       Support Unix-specific            Default if UNIX defined
                       intrinsic functions
NO_UNIX_INTRINSICS    Do not support Unix-specific
                       intrinsic functions
VMS_INTRINSICS        Support VMS-specific             Default if VMS defined
                       intrinsic functions
NO_VMS_INTRINSICS     Do not support VMS-specific
                       intrinsic functions

RAND_NO_ARG           RAND/IRAND function has no       Default behavior:
                       argument                         allows both 0 argument
RAND_ONE_ARG          RAND/IRAND function has one       and 1 argument forms
                       argument

ENV_PREFIX            Prefix for environment           Default "FTNCHEK_"
                       variables that set options

MAXLINE               Maximum input line length.       Default 132
                        Ignores past this.
MAXSTR                Longest string constant stored   Default 200
MAXIDSIZE             Longest identifier allowed       Default 31
MAX_INCLUDE_DEPTH     Max nesting depth of include     Default 16
                       files

ENV_INCLUDE_VAR       Name of environment variable     Default "INCLUDE"
                       specifying include directory

DEFAULT_INCLUDE_DIR   Name of default include          Defaults:
                       directory                        UNIX: "/usr/include"
                                                        VMS: "SYS$LIBRARY:"
                                                        MSDOS: "\\include"


The following macros specify various internal table sizes.  If neither
SMALL_MACHINE nor LARGE_MACHINE is defined, intermediate table sizes
will be used.  In any case, individual table sizes can be chosen by
defining the corresponding macro name.  The defaults for the three
size choices (small, default, large) are listed in the Remarks column.

SMALL_MACHINE         Table sizes appropriate for a
                       PC without much memory
LARGE_MACHINE         Table sizes appropriate for a
                       mainframe or workstation

                                                      small default large
HASHSZ                Identifier hash table (elements)  798  2002  20930
STRSPACESZ            Identifier string space (bytes)  2000  4000  40000
LOCSYMTABSZ           Local symbol table (entries)      200   600   6000
GLOBSYMTABSZ          Global symbol table (entries)     200   400   4000
TOKENSPACESZ          Token list space (tokens). Used   200  1000  10000
                       to store subroutine arguments
                       and other temporary lists.


BpW                   Default bytes per word.          Default=4

WRAP_COLUMN           Default value for -wrap          Default=79
                      setting.


For the truly adventurous:

Ftnchek has three different memory-management schemes to choose from.
In the default case, the identifier string space, local and global
symbol tables, hashtable, and space for scratch tokens (used to hold
common block declarations and subprogram argument lists during local
processing) are allocated as fixed-size arrays at compile time.  Other
items, including permanent common block variable lists and subprogram
argument lists, miscellaneous string space (e.g. for character
constants), and other odds and ends, are dynamically allocated using
malloc and calloc.  This scheme is well suited to machines with large
address spaces and virtual memory.  The sizes of the fixed tables can
be chosen in three standard sets: default, SMALL_MACHINE, and
LARGE_MACHINE.  The latter is preferred for any virtual-memory machine
since memory does not become "really" allocated until needed.

The second memory-management scheme is selected by the compile-time
option DYNAMIC_TABLES.  In this case, the fixed-size arrays are
replaced by pointers, and the space they point to is allocated at the
start of program execution.  Everything else is the same.  This
version runs somewhat slower than the first scheme on machines I have
tested.  I have not proceeded to take advantage of the possibility of
letting the table sizes be selected at run time by means of
command-line settings.  To do so would require moving the allocation
step performed by init_tables() to just before the start of
processing, analogously to init_typesizes().  It would also need a set
of command-line options to be installed for specifying all the
different table sizes

The third scheme was invented to work around a problem with
malloc/calloc in Borland C on the IBM PC.  It is selected by the
compile-time option T_ALLOC.  (It is automatically selected for
Turbo C.)  Under the huge memory model, calloc is supposed
to make use of all memory from the top of the program stack to the end
of RAM.  I find that it fails after allocating about 55K worth.  The
biggest demand for calloc space comes from the permanent common and
argument lists.  In this scheme the needed space is supplied from
fixed-size tables, one each for argument list headers, argument list
elements, common block list headers, and common block list elements.
Each table is in a separately compiled module so that each can occupy
up to 64K bytes.  Therefore, it is necessary to link the additional
four routines newarge.c, newargh.c, newcome.c, newcomh.c with the
other object modules.  (The makefile does all this.)  There is an
additional option, CALLOC_FALLBACK, that causes calloc to be used if
these tables become exhausted.  This option is not the default because
the program usually hangs when calloc fails.  It should only be used
if you have to process a very large program that will not fit
otherwise.

You should not define DYNAMIC_TABLES at the same time as T_ALLOC.
