




             *******************************************
             *                                         *
             *        BC-FORTRAN77 Version 1.3C        *
             *                                         *
             *             Copyright  1990            *
             *                                         *
             *              Andre Koestli              *
             *        Martin-Luther-Strasse 63         *
             *          W-7000 Stuttgart 50            *
             *       Federal Republic of Germany       *
             *                                         *
             *******************************************



1.  PREFACE
===========


About this text
---------------

The following text is a short introduction to the BC-FORTRAN77 Version C
development system, written by Andre Koestli. He holds the copyright of
this product, but does allow everybody to use it for noncommercial and
nonmilitary applications.

 Florian Nold (email address MEHA@DFRRUF1.BITNET) translated the original
german documents into english and has provided a supplementary dictionary
explaining the error and warning messages (see appendix). Many thanx to
Mr. Ken McNorton for reading and correcting this text. The original
german introduction (file lies.txt) has also been included.

If you find any mistakes in this english translation please write them to
Florian Nold. Errors and suggestions to the BC-FORTRAN77 system itself
have to be send to the author A. Koestli himself, since Florian Nold has
NO connection whatsoever with him.


Preface by the author of BC-FORTRAN77
-------------------------------------

Version 'C' of BC-FORTRAN77, consisting of the following 7 described
files, was completely developed by Andre Koestli. I, Andre Koestli,
allow the general use of Version 'C' for noncommercial applications.
All rights remain entirely by me. I do not permit the sale of Version 'C'
under any circumstances, not even in connection with other products.
This text may not be changed and it has to be included with every copy
of Version 'C'. For commercial applications Version 'P' must be used
(see below).

It is STRICTLY forbidden to use BC-FORTRAN77 Version 'C' for any military
purpose or research.

March 1990, A. Koestli


BC-FORTRAN77 version 'C' is part of an extensive development system
called version 'P' (see below). The purpose of version 'C' is to make a
FORTRAN77 compiler available for programming courses. Another advantage
is that BC-FORTRAN77 is available for Amiga, Atari ST and MS-DOS
computers.


2.  BC-FORTRAN77 version 'P'
============================


BC-FORTRAN77 version 'P' is a large development system, consisting of a
compiler, linker, editor, precompiler and a version managment system,
which are all embedded in a user friendly desktop shell. This shell only
compiles source, which has been changed since the last compiler run.
So even large programs, consisting of hundreds of subroutines, will be
processed in a few seconds. Version 'P' supports the use of a mathema-
tical coprocessor and special 68020 commands.

Version 'P' includes a comfortable debugger for interactively testing
programs. Supplementary libraries (e.g. plot output) are also included.

The price of version 'P' is 350 DM (incl. manual, 150 pages). To order
verison 'P' please write directly to A. Koestli. At the moment Version
'P' is only available for ATARI ST and Amiga, not for MS-DOS machines.


3.  BC-FORTRAN77 Version C
==========================


BC-FORTRAN77 version 'C', which is described in the rest of this text,
includes the following files:

      LIES.TXT    original german version of this text, written  by Andre
                  Koestli, the author of BC-FORTRAN77.
                  ('lies' is the german word for 'read')
      BCFMAN.TXT  this text
      BCFMAN.TEX  TeX/LaTeX version of this text
      BCF.TTP     the compiler
      BCL.TTP     the linker
      BCRTSY.B    the runtime library
      MATHLIB.B   library (incl. FORTRAN77 standard functions)

Be sure to include ALL these files without any changes when copying
BC-FORTRAN77.

Using a command-line-interpreter or a shell (e.g. gulam) would be the
best way to work with BC-FORTRAN77. If you don't have any shell, you can
start BC-FORTRAN77 from the desktop. Filenames and options can be entered
in the dialogbox, which appears after double clicking the program icons.


4.  The Installation
====================


The simplest way is to put all the files in the same directory. If you
prefer to store the binaries, sources, etc. in distinct directories, put
BCF.TTP and BCL.TTP in the directory, where the shell would search for
the bin-stuff.
BCRTSY.B and MATHLIB.B should be moved to the directory \BC of the actual
drive.


5.  The Compiler BCF.TTP
========================


To invoke the compiler enter

      BCF [-options] filename
or
      double click on the BCF.TTP-icon on the desktop and enter options
      and filename.

If the filename does not contain any point, the extension .F will be
appended. In any case the compiler will write its output to the file
filename.B.

Examples:

      BCF -D TEST.F     compile the file TEST.F to TEST.B using the
                        debug-option
      BCF TEST SUB      compile the file TEST.F to TEST.B and SUB.F to
                        SUB.B
      BCF TEST.X        compile the file TEST.X to TEST.B


Compiler Options
----------------

      -D    Debug, equivalent to -BVL.
      -B    deBugcode, uses -H implicit, generate code to check
            arraybounds and substrings.
      -H    parcHeck, generate code to check parameter lists and stack
            overflow.
      -V    Varlist, generate list of variables used by the debugger
      -L    Lineslist, generate list of linenumbers for the debugger
      -U    Uppercase, convert lowercase characters to uppercase
            (except character constants and FORMAT statements).
            If this option is not specified the compiler will treat
            xy, xY, Xy, XY as 4 different variables !
      -F    Freeinput, allows Free-Form-Input-Format (not standard !)
      -P    Protocol, print compiler listing.
      -W    Wait for RETURN key when compiler has finished.


Language-Extensions and Restrictions
------------------------------------

BC-FORTRAN77 supports the fully FORTRAN77 standard defined by ANSI/ISO.
This standard is often ignored by some special features. I do not
recommend the use of these extensions, because they do not comply with
the ANSI standard and are therefore not precisely defined.

The most important specialities are:

      INTEGER*1         8 bit INTEGER
      INTEGER*2         16 bit INTEGER
      INTEGER*4         same as INTEGER
      LOGICAL*1         8 bit LOGICAL
      LOGICAL*2         8 bit LOGICAL
      LOGICAL*4         same as LOGICAL
      IMPLICIT NONE     turn off all implicit typedefs
      COMMON /adr/      absolute addressed COMMON, adr may be a constant
                        or a simple variable
      EQUIVALENCE()     between CHARACTER and other types and mixing in
                        COMMON blocks

      recursive subroutine calls
      max. length of names: 8 chars. (standard 6 chars.)


The most important restrictions are:

      32kB  code per subroutine
      32kB  SAVE/DATA per subroutine or BLOCK DATA
      700   subroutines per file
      500   different COMMON blocks per file

There are also some restrictions, which would cause a compile-time-error,
if subroutines are unreasonable large. In most cases the 32kB limit would
be exceeded anyway.


6.  The Linker BCL.TTP
======================


To invoke the linker just type

      BCL [-options] filename ..

or click the BCL.TTP icon on the desktop and enter options and filenames.

If the filename doesn't contain any point, the extension .B will be
appended. The executable program will be stored using the name of the
first file and the extension .PRG. If the source contains any mathemati-
cal standard function calls the file MATHLIB.B must be specified too.
The runtime system BCRTSY.B will be linked automatically.

Example:

      BCL -S16 TEST SUB MATHLIB
or
      BCL -S16 TEST.B SUB.B MATHLIB.B

will link the files TEST.B and SUB.B. The name of the resulting execu-
table will be TEST.PRG (stacksize 16kB).


Linker Options
--------------

      -Sn   Stacksize of the resulting executable is set to n kB.
            If this option is not specified, a very large stack will be
            assumed. The stack is used to store all local variables/
            arrays of nested subroutine calls.
      -O    Optimize: remove unused functions in order to reduce code
            size
      -P    Protocol: generate listing of COMMON blocks and program
            modules
      -W    Wait for RETURN key when finished


Restrictions
------------

The most important restriction is the RAM size: the generated program
file (without COMMON blocks and stack) may be as large as the largest
remaining free memory block after loading the linker. On the other hand
it's also possible to generate a program with very large COMMON blocks
or stack, that runs out of memory while loading or executing.

The max. number of subroutines is restricted to 3000, the max. number of
COMMON blocks is 1500.


The Runtime System BCRTSY.B
---------------------------

The runtime system BCRTSY.B contains stuff needed by every BC-FORTRAN77
program. Therefore it will be linked automatically by BCL.TTP.

BCRTSY.B consists of:

      arithmetic routines
            32 bit INTEGER multiplication/divison
            REAL arithmetics
            DOUBLE PRECISION arithmetics: in order to increase perfor-
            mance a special internal floating point number representation
            is used. These subroutines are much more tuned to speed than
            to accuracy.
            REAL: 6 decimal digits, 32 bit, 1 bit sign, 23 bit mantissa,
            8 bit exponent
            DOUBLE PRECISION: 13 decimal digits, 64 bit, 1 bit sign,
            47 bit mantissa, 16 bit exponent
            Math. coprocessor is not supported by Version 'C'.

      CHARACTER routines
      I/O routines
      Debugger: a tiny debugger is included too. After every error
                message the debugger waits for your reaction.
                The debugger may also be activated by pressign the
                ALT-key, to stop a running program. The following command
                keys are supported:
                  S     print the subroutine call Stack and the line
                        number (if the compiler option -L has been
                        specified)
                  V     print the Variables and their contents of the
                        actual subroutine (only if the compiler option
                        -V has been specified)
                  Z     terminate program
                space   continue, in the case that no runtime error has
                        occured. If you press the ALT-key simultaneously,
                        only the next program step will be executed
                        (e.g. next label, subroutine, ELSE, ENDIF, DO, )


The Standard Library MATHLIB.B
------------------------------

MATHLIB.B contains all the mathematical functions described by the ANSI
standard. If the linker issues an error message like 'External nicht
gefunden: f_SQRT' (german text for 'external not found') you have to
specify MATHLIB.B when running the linker BCL.TTP.


Starting your Program
---------------------

Every executable program produced by BCL can be started like any other
program from the desktop or a shell.


7.  Error Messgages
===================


The error messages produced by the compiler, the linker and the runtime
system should be self explainatory and are supplemented with the
following short list of messages. A complete list of errors (26 pages of
the version P manual) would exceed this short description.

IO-Errors
---------

Input-Output-Errors. If you specify the IOSTAT parameter, you get the
error number (see below) for the operation attempted in the IOSTAT data
item.

   number   description

     -1     end of file (EOF) reached
     -2     EOF reached while processing a record
      1     filenumber already used (OPEN)
      2     too many files (OPEN), max. 32 files
      3     filename too long (OPEN), max. 31 characters
      5     filenumber (unit) not opened. Only the units 5 and 6 are
            preconnected and can be used without issuing an OPEN
            statement
      6     formatted / unformatted I/O contradiction
      7     REC-parameter specified for a sequential access file
      8     BACKSPACE, REWIND, ENDFILE not allowed for this file
            (e.g. AUX: or PRN:)
     10     internal I/O only formatted
     20     integer overflow processing an input
     21     data error occured while processing list-directed input,
            e.g. missing quote-character for strings
     22     unexpected EOF
     23     record too long
     24     read error processing UNFORMATTED SEQUENTIAL input
     30     format code and I/O-listelement do not fit together
            INTEGER needs I-format code
            REAL, DOUBLE PRECISION (COMPLEX) need one (two) F-, G-, E-
            or D-format code(s)
            LOGICAL need L-format code
            CHARACTER need A-format code
     31     format code L: T or F expected (input)
     32     format code I: unexpected character found (input), only
            blanks, signs and numerals are allowed
     33     format code E, F, or D: unexpected character (input), only
            blanks, signs, numerals, decimal-point, E, e, D or d are
            allowed.
     34     format code contains too many (
     35     format code contains too many )
     36     forbidden position for numeral series in format code
     37     unknown format code
     38     missing . in F, E, G or D format code
     39     4Htext or 'text' in READ format code
            FORTRAN66 allows to read a text for the format code, not
            allowed in FORTRAN77
     40     exponent to high for given format code
     42     format code too long, max. length of internal record buffer
            80 char.
     43     internal I/O, record too long
     44     TL, record too long. If the recordlength exceeds the length
            of the internal record buffer, left tabbing will not work
     45     field length 0 (zero) in I, L, F, E, G or D format code


TOS Errors
----------

in general: 1000 + n --> TOS-Error -n

   number   description

    1002    drive not ready
    1004    CRC error (cyclic redundancy code)
    1010    write error
    1011    read error
    1013    disk is write protected
    1014    media change detected
    1016    bad sector
    1017    put disk into drive
    1033    file not found
    1034    path not found
    1035    too many files
    1036    access not possible (write protected ?)
    1039    out of memory (RAM)
    1040    wrong memoryblock address
    1046    wrong drive character (e.g. K)
    1066    wrong format of program file


8.  Problems
============


If you find any bug in BC-FORTRAN77 (compiler, linker or libraries)
please inform the author Author A. Koestli.
As you will appreciate, the author can't offer any update service or
advise support by phone for this product, in contrast to the commercial
version 'P'.


                        **********************
                        *                    *
                        *      APPENDIX      *
                        *                    *
                        *  Small dictionary  *
                        *                    *
                        **********************

            German                              English

anfang                              beginning
COMMON aus BLOCKDATA verlaengert    COMMON extended with BLOCK DATA
COMMON in mehreren BLOCKDATA        COMMON in several BLOCK DATA
Character Konstante erwartet        expected character constant
Dataliste laenger Wertliste         datalist longer than valuelist
Dataliste zu lang                   datalist too long
Deklaration hier nicht erlaubt      declaration not allowed at this point
Dimension fehlt fuer                missing dimension for
Doppelt                             twice
drucke                              print
ELSE ohne IF oder nach DO oder ELSE ELSE without IF or after DO or ELSE
ENDIF ohne IF oder nach DO          ENDIF without IF or after DO
Erst Initialisieren mit             first initialize with
erwartet / erwartet nach            expected / expected after
Exponent zu gross                   exponent too large
External Widerspruch                contradiction in external
External/Common nicht gefunden      external/COMMON not found
falsch                              wrong, invalid
Falsche Version                     wrong version
Falscher Name in Function           wrong name in function
Falscher Name in Subroutine         wrong name in subroutine
Falscher Operator                   wrong operator
Falscher Parameter                  wrong parameter
Falscher Typ                        wrong typ
Falsches Symbol in Dataliste        wrong symbol in datalist
Falsches Symbol in Index            wrong symbol in index
Falsches Wertelement                wrong value
Falsches Zeichen                    wrong character
Fehler                              error
Fehler (Nr.) Nach [] in Zeile       error (nr.) after [] in line
Fehler beim Eroeffnen von ...       error opening file ...
Fehler beim Laden                   load error
Fehler beim Lesen                   read error
haupt                               main
hier nicht erlaubt                  not allowed here
Illegale Konversion                 illegal conversion
illegale linke Seite                illegal left side
Index ausserhalb                    index beyond
Index inkorrekt                     index wrong
Indexanzahl                         index quantity
Indexliste                          indexlist
Integer Konstantenausdruck erwartet integer constant expression expected
Integerkonstante erwartet           interger constant expected
Integerueberlauf                    integer overflow
ist                                 is
ja                                  yes

Kein Code                           no code
Kein Input                          no input
Kein Objfile                        no object file
Keine Reloc.Info                    no relocation info
Konstanten                          constants
Label doppelt                       label used twice
Label erwartet                      label expected
Label fehlt                         label missing
Laengenfehler in Objfile            length error in objfile
Laengenwiderspruch COMMON           length mismatch of COMMON blocks
Lesefehler                          read error
Liste                               list
mehrfach benutzt                    used twice
Modul doppelt                       module found twice
Module geloescht                    module deleted
Name zu lang                        name too long
neu                                 new
Nicht definiertes Label             label undefined
nicht gefunden                      not found
Nicht genuegend RAM frei            not enough RAM
Nicht genuegend Speicher            not enough memory
Nicht implementiert                 not implemented
Nicht lokal                         not local
Nummer zu gross                     number too large
Nur Variable/Array                  only variable/array
oder                                or
offener string                      string not closed
Parameteranzahl                     number of paramters
Parameterliste                      parameter list
Parameterliste fehlt                parameter missing
Parametername erwartet              parameter expected
Parametertyp                        parameter type
Schreibfehler                       write error
Speicher                            memory
Sprung > 32kB                       branch > 32kB
Statement Nr. erwartet              statement nr. expected
Statement nicht erkannt             statement not recognized
Statement zu lang                   statement too long
String zu lang                      string too long
Substring ausserhalb                substring beyond limit
Tabellenueberlauf                   table overflow
Typen nicht kompatibel              types not compatible
Typunkompatibilitaet                type incompatibility
Typwiderspruch Dataliste/Wertliste  type mismatch datalist/valuelist
Ueberlauf Codetabelle               codetable overflow
Ueberlauf Objektspeicher            object-memory overflow (?)
Unbekannte Option                   unknown option
Ungerade Adresse                    odd memory address
Variable Dimensionierung            varible dimensions
Variable erforderlich nach          varible needed after
warte                               wait
Weiter                              continue
Wertliste laenger Dataliste         valuelist longer than datalist
Widerspruch Common/External         Common/External mismatch
Widerspruch fuer                    mismatch in
Wiederholungsfaktor -+ Zahl         repetition factor -+ number
wort                                word
zahl                                number
Zahl oder String erwartet           number or string expected
Zu viele                            too many
Zu viele Comdecks                   too many Comdecks
Zu viele Levels                     too many levels
