     FCSYS(I-UBC)                   02/05/81                  Page  1



     NAME
             FCSYS - FC implementation guide

     INTRODUCTION
             This document is designed to aid implementation  of  the
             UBC Fortran 77 compiler. This is the fourth distribution
             that  has  been  made of the compiler and is included in
             the first UBC distribution tape. This is version version
             of the compiler.

     DISTRIBUTION CONDITIONS
             it is assumed, as a condition of distribution:

        1    we assume no liability for this program.

        2    no further distribution is allowed. Any other users must
             either obtain their own release or wait for  the  formal
             release of the compiler.

        3    any  two  installations  having  obtained  copies of the
             compiler from UBC may exchange distributions freely.

        4    the purpose of the distribution is to aid  in  debugging
             and  developement  of  the  compiler  and to allow other
             installations  access  to  the  compiler.  While  it  is
             generally  as  bug free as possible; it is expected that
             bugs  may  exist  and  that  these  (as  well   as   any
             improvements) will be reported.

        5    for  bug  reports  to  be  useful the minimal program to
             exhibit the bug should be produced. It is of little  use
             having   a   1000  line  program  that  "doesn't  work",
             requiring numerous input files and producing volumes  of
             output.

     ADDRESS
             other  installations  interested  in the compiler should
             contact:

             W. E. Webb
             Institute of Animal Resource Ecology
             2204 Main Mall
             University of British Columbia
             Vancouver, B. C.
             Canada V6T 1W5



             The phone number is 604-228-6527.

     RESTORING THE FILES FROM THE TAPE
             if there is enough disk space  available,  just  restore
             the entire distribution:

             tar x0f /dev/rmt0
     FCSYS(I-UBC)                   02/05/81                  Page  2




             If there is insufficient space (the above requires about
             12,325  blocks),  then  just  the  files  sufficient  to
             implement Fortran 77 many be restored by first restoring
             the file "f77.restore" and using it to restore the files
             required.

     SIMPLE MINDED INSTALLATION OF F77



             To install the compiler over top of Bell's fc use:

             install.fc


             To install it by itself, (as f77), use:

             install.f77


             Note that the install  files  take  two  arguments,  the
             first  of  which  may  be  either  "", "34" or "fpt". ""
             causes the standard I/D separated version  to  be  used,
             "34"  causes  a  non I/D space compiler to be installed,
             "fpt"  causes  the  floating  point  simulator   to   be
             installed.


             The  second  argument  controls  whether the standard V6
             "ar" format,  or  whether  the  PWB  (or  UNIX  library)
             version  of  "ar" is used. The second argument should be
             specfied only if the OLD V6 format is to be used.


             You will probably want to inspect the install  files  as
             they   move   files   into   the   directories   "/lib",
             "/usr/fort", and "/bin".

     PWB DEPENDENCIES
             the only part of the compiler that is dependent upon PWB
             (other than for the format of AR-I libraries) is the FDB
             (Fortran DeBugger) routine.  There  are  three  possible
             ways around this dependency:

        1    use  the  -P  switch  on  the  FDB  command.  (-U is the
             opposite for UNIX V6).

        2    change the value of the variable "sysfudge" using CDB to
             768 for PWB (default is 512  for  UNIX),  or  re-compile
             after changing the source in "fdb/run.c".

     FCSYS(I-UBC)                   02/05/81                  Page  3



        3    create  the  file "/etc/pwb" which FDB will check to see
             if its on a PWB system. This is by far the easiest,  but
             requires access to the /etc directory.

     RELEVENT FILES
             the  following  files  are  required (under some name or
             other) for the proper operation of the compiler:

       bin/fc
             is the Fortran Compiler command if it is to  be  invoked
             as  "fc".  It invokes the compiler and (if required) the
             linkeditor. This name should  only  be  used  if  Bell's
             "Fortran" compiler is not being used.

       bin/f77
             is the Fortran Compiler if it is to be invoked as "f77".
             It  invokes  the  actual  compiler and (if required) the
             linkeditor.

       usr/fort/fc
             is the actual compiler.

       usr/fort/ferr
             is the routine used by the run  time  to  print  out  an
             interpretation of a runtime error.

       usr/fort/errmsgs
             is  the file referenced by FERR to get the error message
             texts. It contains both runtime diagnostics  and  fuller
             explanations  for compiler diagnostics. It may be freely
             edited as  FERR  scans  the  file  to  find  the  proper
             diagnostic.

       usr/fort/fc.msgs-version
             contains  the  actual compiler error messages. It may be
             freely edited as long as no new lines are added  or  any
             old  lines  deleted  as  the  compiler  finds  the error
             message by looking for the n'th line for  error  message
             "n".  The  suffix  "version"  is  the  compiler internal
             version number. It is present so that  messages  may  be
             added and deleted between versions.

       bin/asa
             is  the  ASA  output  filter.  It  converts ASA carriage
             control (1 ==  page  skip,  0=double  space  etc.)  into
             standard  ASCII controls (FF, NL, CR, etc.) i(lib/libf.a
             is the runtime library if the compiler is  installed  as
             "fc".  It  contains  the routines that must be linked to
             the object  module  produced  by  the  compiler  if  the
             compiler is installed as "fc".

       lib/frt0.o
             is  the  Fortran  runtime header file if the compiler is
             installed as "fc". It invokes the main  program  if  the
             compiler is installed as "fc".
     FCSYS(I-UBC)                   02/05/81                  Page  4



       lib/mfrt0.o
             is  the  profile  runtime header file if the compiler is
             installed as "fc".

       lib/libf77.a
             is the runtime library if the compiler is  installed  as
             "f77".

       lib/frt77.o
             is  the runtime header file if the compiler is installed
             as "f77".

       lib/mfrt77.o
             is the profile runtime header file if  the  compiler  is
             installed as "f77".

     GENERATING THE COMPILER
             while the object files on the tape should be sufficient,
             all  files  needed to generate the compiler should be on
             the tape (I hope). See the file "fc/READ_ME" for details
             on generating the compiler.

     C COMPILER
             the FC compiler uses a large number of  "#define"'s  and
             has  a large symbol table. It will probably be necessary
             to change the C preprocessor to allow for  more  defined
             symbols.


             In  addition,  the large number of symbols will probably
             mean that the C compiler itself will have  to  have  its
             hash table size increased.

     LD - THE LINKEDITOR
             because  the  of  the  large number of global symbols it
             will probably be necessary to increase the size  of  the
             linkeditor's symbol table.


             I  have  included a version of LD that has the following
             features:

        1    the symbol table is large enough to handle the  compiler
             itself.

        2    it  will  accept  either  the original UNIX version 6 AR
             format, or the PWB (or UNIX library) version.

        3    it accepts the "-z"  option  that  includes  the  entire
             contents  of  a  library.  This  is  useful when a large
             program  is  stored  in  a  file   and   contains   many
             subroutines,   as   the  object  generated  will  be  an
             archieve.

     FCSYS(I-UBC)                   02/05/81                  Page  5



     NON PDP 11/45 AND 11/70
             the compiler is generated with separated I and D spaces.
             This only works on some  PDP  11's  that  run  UNIX.  If
             shared  I  and D spaces are not available then much less
             space is available for the symbol  table.  Such  systems
             should specify "34" on the "install" command so that the
             correct version is installed.

     FLOATING POINT
             the  compiler makes use of floating point arithmetic and
             will require the floating point simulator for  PDP  11's
             that don't have the floating point instruction set. This
             could  cause  problems  due  to  the  extra memory space
             required for the simulator. Such systems should  specify
             "fpt"  on  the  "install"  command  so  that the correct
             version is installed.


             It should be essentially trivial to modify  the  runtime
             to allow use of the floating point simulator.


             Note:  for  these  reasons  somebody  should  modify the
             system to incorporate the simulator into the  kernal  so
             that  programs  don't  have  to be modified as much when
             moved from system to system.

     STICKY COMPILER
             because the compiler is quite large, and since it is  at
             least  shareable  it  is  often  important  to  make the
             "/usr/fort/fc"  file  sticky.  This  will  substantially
             reduce  the  start-up time after the first "fc" command.
             The only thing is to be very  careful  in  removing  the
             compiler  if  it  has been made sticky as this is a good
             way of losing i-nodes.


             Note that if very large programs are to be  compiled  on
             non  I/D  space  machines  a  little  more memory may be
             obtained by  not  making  the  compiler  sharable.  This
                          ___
             allows  the  full  32K  address space to be used and can
             gain several K words. On systems with fast disks  it  is
             not  as  essential  to  make  the  compiler sticky. On a
             system with RK05 disks you can change the response  time
             to  the  "fc"  command from 13 to 3 seconds by making it
             sticky.

     FILES REFERENCED BY THE COMPILER
             the compiler references a couple of files:

       usr/fort/fcmsgs-version
             contains the compiler's error diagnostics. The  compiler
             will  run  without  this  file  but  it  is very hard to
             determine the causes of errors without it.
     FCSYS(I-UBC)                   02/05/81                  Page  6



       etc/pagesize
             contains the default printer page size in lines (logical
             length in the first word, physical in  the  second).  If
             this  file  does  not  exist  the  compiler  will use 60
             lines/page as the page length for listings.

     FILES REFERENCED BY THE RUNTIME


       usr/fort/ferr
             the runtime references the this file which  it  uses  to
             print  out  the text explanation for a runtime error. If
             this file is missing then the error explanation will not
             be printed.

       usr/fort/errmsgs
             is referenced by "ferr" when  it  is  requested  by  the
             runtime  error  routine  to print out the reason for the
             error.

     FILES PASSED TO LD BY FC


       lib/frt0.o
             contains the runtime header file.

       lib/mfrt0.o
             contains the profile runtime header file.

       lib/libf.a
             is the fortran library.

       lib/libc.a
             for the C library in case any C routines are called.

       lib/liba.a
             for the basic library (sqrt etc.).

     FILES PASSED TO LD BY F77


       lib/mfrt77.o
             contains the profile runtime header file.

       lib/mfrt77.o
             contains the profile runtime header file.

       lib/libf.a
             is the fortran library.

       lib/libc.a
             for the C library in case any C routines are called.

       lib/liba.a
             for the basic library (sqrt etc.).
     FCSYS(I-UBC)                   02/05/81                  Page  7



     CODE GENERATION
             the compiler generates unix standard a.out files, except
             when it generates libraries of a.out files. The linkedit
             may, if desired, produce shareable  load  modules.  Note
             that  the  object files produced by the compiler use the
             full a.out format: text,  data,  and  bss  sections  are
             produced from fortran programs. Note that since threaded
             code is used that while it is possible to make shareable
             load  modules  it  is not possible to generate separable
             load modules without changing the compiler.

     TIME ZONE DEPENDENCIES
             the compiler prints out what it thinks are the time  and
             date  for listings. This will obviously be incorrect for
             installations not on the west coast. The easiest fix  is
             to  use  "db"  (or "cdb" if you have an improved one) to
             patch the "timezone" variable in "ctime"  to  your  time
             zone value.

     TAPE FORMAT
             the  Fortran  77  subset of the distribution consists of
             the following directores:

       fc    contains source and object for the compiler itself.

       run   contains run-time routines (mostly arithmetic).

       io    contains the  io  routines  (modifications  of  unix  fc
             routines).

       fns   contains some of the standard functions (sin, sqrt etc).

       usr/fort
             contains  the  compiler  itself,  the error messages for
             runtime and the error message printing routine (ferr).

       bin   contains some objects.

       libs  contains  fortran  callable  versions  of  unix   system
             routines.

       lib   contains  some  fortran libraries and the fortran header
             file. (it also contains most of  the  libraries  on  our
             system in case something was inadvertently left out).

       fcdoc contains  documention  source  for Fortran. It is in FMT
             format. To get a copy of this document  one  could  use:
             "fmt uhead fcsys". The user's guide is: in "fc?".

       doc   contains   documentation   for   other   parts   of  the
             distribution.

     FCSYS(I-UBC)                   02/05/81                  Page  8



     THINGS TO LOOK OUT FOR
             while some parts of the compiler and runtime  have  been
             used  quite  a  bit  there  are others not so completely
             checked out:

        1    the --t (two word integer) mode has not been used much.

        2    the complex and double precision routines  haven't  been
             used much.

        3    the  basic functions haven't been checked out fully, but
             the common ones (sin, cos, exp, sqrt etc. Seem ok).

     FDB ROUTINE
             I have included on this distribution a copy of  the  FDB
             (Fortran  DeBug)  program. The documentation is with the
             other documentation.

     DOCUMENTATION
             the  directories   "fcdoc"   and   "doc"   contain   the
             documentation files. All the source is in FMT format, so
             to  print out a copy FMT must be used. I have put copies
             that can be copied to a printer in the directory  "prt".
             In general, to produce a new copy of the document use:

              fmt uhead name
             or
              fmt uhead name?
             depending  upon  the individual document. To print out a
             copy of all of the documents the shell-file "fc.fmt" may
             be used. The shell-file "prt.gen" generates the files in
             the directory "prt".


             The files "fcint?" contain such documentation as  exists
             about  the  internal  workings  of  the compiler and the
             runtime.

     KNOWN BUGS AND PROBLEMS


        1    the compiler does not conform to the Fortran 77 standard
             in the way that it passes character expressions, as only
             the address is passed, and not the address  and  length.
             This  means  that  you  cannot  declare  a  parameter as
             "character *(*) x" and then use "length(x)" to  get  the
             length.  This  is  done  to  be compatible with existing
             compilers that allow quoted strings in parameter lists.

        2    similarly hollerith constants are  treated  exactly  the
             same  as  quoted  constants.  I will probably intoduce a
             compiler option that will allow the compiler  to  follow
             the standard exactly.

     FCSYS(I-UBC)                   02/05/81                  Page  9



        3    the  runtime routines do not support the OPEN statement,
             and the INQUIRE  statement,  though  the  compiler  will
             generate the proper code for them.
