Fish 'n' More 2/fishmore-publicdomainlibraryvol.ii1991xetec.iso/disks/disk470.lzh/BCF/fortran.doc

Text File | 1991-03-10 | 15KB | 440 lines

/* This translation of 'lies.txt' was done by Markus Buchhorn                */
/* ([e-mail]) in the interests of spreading PD/similar software.*/
/* I accept no responsibility whatsoever for errors in the translation of the*/
/* document. If you don't trust me, get someone else to translate it for you.*/
/* A point of clarification: I have used the term 'subroutine' liberally in  */
/* the translation. More correct translation would be 'sub-program', yet I   */
/* think subroutine is usually intended.                                     */
/*                                                                           */
/* I apologise for the disjointedness of some of the sentences, but sometimes*/
/* I just translated the sentence as it stood, or had to make up words that  */
/* approximated the intent of the sentence/caption.    Markus Buchhorn 4Feb91*/


    -------------------------------------------------
    |             BC-FORTRAN77 Vers.1.3C            |
    |  Copyright: Andre Köstli                      |
    |     1990    Martin-Luther-Str.63              |
    |             D7000 Stuttgart 50                |
    |-----------------------------------------------|
    | The Version "C" of  BC-FORTRAN77, consisting  |
    | of the (later described) 5 Parts,             |
    | was totally programmed by myself.  I          |
    | allow free usage-rights to  Vers.C for        |
    | noncommercial applications, all rights though |
    | remain with me, in particular, the sale of    |
    | Vers.C, even in the accompaniment of other    |
    | Products, is not permitted. Every copy        |
    | of this distribution must contain this        |
    | textfile (uneditted) [NB-German version -MB]  |
    | For commercial aplications there exists       |
    | Vers.P of this programme, which has a         |
    | licensing requirement.                        |
    | The use of these programmes for military      |
    | purposes, and related research, is forbidden !|
    | March 1990                          A.Köstli  |
    -------------------------------------------------


BC-FORTRAN77 Version C is a part of an extensive
development system, Version P (see below). Vers.C
is intended to provide, in a simple way, a compiler for
programming courses. To meet this intent, this software
runs almost identically on AMIGAs, ATARI STs and
MS-DOS computers.


BC-FORTRAN77 Vers.P
-------------------

BC-FORTRAN77 Vers.P is an extensive development system,
that combines, besides a compiler and linker, also an editor,
precompiler and version-management-system under a single
User-interface. The system is designed so that in the
development-cycle only the modified subroutines need
to be recompiled; even with programmes with several hundred
subroutines, each development-cycle (edit, compile, link and run)
takes only a few seconds. Mathematical coprocessors are supported
in Version P, as well as 68020-processor specific commands.

Version P contains a user-friendly debugger with source-code
interface, to enable interactive testing, as well as several
libraries which (among other things) allow the use of the
Amiga libraries: Exec, Dos, Graphics and Intuition.

Together with a 150 page manual, BC-FORTRAN77 Vers.P
costs DM 350.- and can be ordered from the above address.
(Please indicate AMIGA or ATARI ST. The MS-DOS version of Version P.
does not exists at this time.)



BC-FORTRAN77 Vers.C
-------------------

BC-FORTRAN77 Vers.C, to which the rest of this text pertains,
consists of the following files:

    LIES.TXT    This Text (German version -MB)
    BCF         Compiler
    BCL         Linker
    BCRTSY      Runtimesystem
    MATHLIB.B   Library with standard functions

If you make a copy, all of these files must be included unchanged.

To run BC-FORTRAN77 on the AMIGA you need 1MB RAM, and it
will run from the CLI or the shell.



Installation.
-------------

The easiest way to use this is attained if you work
only from one directory, in which all of the parts of
BC-FORTRAN77 are.

Should you want to use several directories, one can
install it with the following CLI commands:

    COPY BC? C:
    COPY BCRTSY S:
    COPY MATHLIB.B S:


Compiler
--------

The Compiler is executed with

    BCF [-Option...] Datafile...

If <Datafile> contains no period '.' then a .F extension is assumed.
The compiled version of the program is written to Datafile.B

Example:

    BCF -D TEST.F

compiles TEST.F with the debug-option into TEST.B

    BCF TEST SUB

compiles TEST.F to TEST.B and SUB.F to SUB.B

    BCF TEST.X.Y

compiles TEST.X.Y to TEST.B (Careful!).


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

    -D      Debug, combines -BVL

    -B      deBugcode, implies -H and produces
                as well code for the Debug-call,
                to check array-bounds and
                substrings.

    -H      parcHeck, code to check  parameter-
                lists and Stackoverflow is generated.

    -V      Varlist: Variablelist for the Debugger.

    -L      Lineslist: Line-number-list for the Debugger.

    -U      Uppercase: convert lower- to uppercase
                (except in character-constants and
                Formats). If this option is omitted then
                xy, XY, Xy and xY are four different
                variables!

    -F      Freeinput: Sourcecode is not in FORTRAN
                format. non-standard!

    -P      Protocol: Printout of compiled lines.


Language-coverage
------------------

BC-FORTRAN77 compiles the complete set of the ANSI/ISO standard
The standard is however 'damaged' by several unusual [local -MB] features
(which are most commonly described as 'extensions').
I strongly recommend that local dialectic constructs are
not used, as they are not standardised and are thus not
defined exactly.

The most important variations [non-standard features -MB]:

    INTEGER*1       8 bit INTEGER
    INTEGER*2      16 bit INTEGER
    INTEGER*4      same as INTEGER
    LOGICAL*1       8 bit LOGICAL
    LOGICAL*2      16 bit LOGICAL
    LOGICAL*4      same as LOGICAL
    IMPLICIT NONE  turn off implicit typing of variables
    COMMON /%adr/  Absolute Common, adr is a constant
                        or similar variable.
    EQUIVALENCE()  between Character and other types
                   as well as mixing in common-blocks.
    Recursive subroutine-calling.
    Names with max. 8 characters (Standard: 6).


The most important limitations are:

    32kB Code per subroutine
    32kB SAVE/DATA per subroutine or datablock
    700  subroutines per <datafile> [i.e. main program -MB]
    500  different common-blocks per main-program.

As well, there are a set of limitations that lead to error-messages,
due to unreasonably large subroutines, however in most cases the
above 32kB code-size limit would have been exceeded by that stage.


Linker
------

The Linker is executed by:

    BCL [-Options...] Datafile...

If <datafile> has no period '.', then a .B extension is assumed.
The programme data is then put in the file with name <datafile>, with no
.B extension. If standard mathematical functions are used then the file
MATHLIB.B has to be included in the link. The Runtimesystem BCRTSY is
automatically loaded.

example:

    BCL -S16 TEST SUB MATHLIB

or

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

will link the files TEST.B und SUB.B and will put the executable result in
TEST, which will use a stacksize of 16kB.


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

    -Sn     Stacksize of the resulting Programme
                will be set to n kB . If this option is omitted,
                then a very large stack will be assumed.
                All local-variables and subroutine-variable-storage
                will be placed on the stack.

    -O      Optimized Linking: subroutines which are never called
                are omitted.

    -P      Protocol: List of Commonblocks and
                Programme-modules.


Limitations
--------------

The most important limitation is due to RAM: availability:
The executable to be generated (without common-blocks and stack)
can only be as large as the largest free memory-chunk after the
loading of BCL. Otherwise, if one has a large common-block or stack,
one can generate an executable that can't be run in the available RAM.

The number of subroutines is limited to 3000, the number of common-blocks
is limited to 1500.


Runtimesystem
--------------

The runtimesystem BCRTSY contains routines that are needed by FORTRAN77
programmes, and is always automatically linked in with every programme.

BCRTSY contains:

    Arithmetic-routines:
        32 bit INTEGER Multiplication/Division
        REAL Arithmetic
        DOUBLE PRECISION Arithmetic
        A personal Floating-point-format is used, which is
        more oriented towards speed than precision.
        REAL: 6 Decimal-places, 32 bit
         1 bit sign, 23 bit Mantissa, 8 bit Exp.
        DOUBLE PRECISION: 13 Decimal-places, 6 bit
         1 bit sign, 47 bit Mantissa, 16 bit Exp.
        A mathematics coprocessor is not
        supported in Vers.C.

    CHARACTER Routines

    I/O Routines

    Debugger:
        A simple Debugger to aid the search for errors.
        When a programme, that had been compiled with -D or -B,
        is executed, a debug-window is opened. After a run-time error
        a message is printed there and it then waits for input.
        The Debugger can also be activated with input in this window,
        to interrupt the program execution. The following keys are
        recognised as commands by the debugger:

            S   Printout of the Subroutine-Call Stack
                With line-numbers, if the -L Option was used
                in the compilation.

            V   (printout of) Variables of the current subroutine
                with current contents, if the -V Option was used
                in the compilation.

            Z   Stop the program (quit).

            Spacebar  Continue execution, if no run-time
                      error ocurred.

            U   Continue execution until change of subroutine

            L   continue with continual display of Subroutine+Line number.

            P   continue, with display at every 200 steps.

            T   Continue one step (to the next label,
                subroutine, ELSE, ENDIF oder DO).


Library
----------

MATHLIB.B contains the full mathematical functions
as described in the standard mentioned above.
If you get an error-message similar to:

    External nicht gefunden: f_SQRT          [External not found: -MB]

during the linking, then MATHLIB.H must be explicitly included in
the call to BCL.


Programme execution
--------------------

A programme generated by BCL can be executed like any other
from the CLI. As each programme has its own stacksize (-S option
in BCL), the CLI command STACK is not needed.
If the programme needs input from the keyboard
( READ(*,... ) ) one mustn't forget to reactivate the window
if the debug-window was also opened.


Error messages
---------------

The error-messages from the Compiler, linker and
runtimesystem should be, with the following exception,
self-explanatory. The complete listing (26 pages in
the Vers.P manual) would exceed the framework of
this description.

 [Of course, this could be a problem for the non-German speakers, as I'm
  not sure whether the error messages are numeric, German, English....
  I suggest posting error messages to the net, there are enough German
  speakers out there. Failing that, send me a mail message -MB]

   IO-Error: Nummer     [I/O-error: number]
        input/output-error; can be caught by putting
        the IOSTAT= parameter in the IO statement. The
        number is the same value as is then returned
        into the IOSTAT variable.

[Note that 'Format-element' is usually described as 'Format-descriptor' -MB]

    Number

    -1   Datafile-end.
    -2   Datafile-end in the middle of a record.
    1    Datafile-number already used (OPEN).
    2    Too many datafiles (OPEN). Max. 32 Datafiles.
    3    Datafilename too long (OPEN).Max. 31 characters.
    5    Datafile-number not opened. Only units
           5 and 6 can be used without being OPENed.
    6    Formatted/unformatted conflict.
    7    REC-Parameter for Datafile with ACCESS='SEQUENTIAL'
    8    BACKSPACE, REWIND, ENDFILE for this Datafile are
         not possible (AUX: und PRN:).
    10   Internal I/O only formatted.
    20   INTEGER overflow during input.
    21   Dataerror during list-driven input,
         e.g. missing apostrophe on a character-string.
    22   Unexpected datafile-end.
    23   Record too long.
    24   Readerror with UNFORMATTED SEQUENTIAL.
    30   Format-element and I/O-List-element don't match
           INTEGER requires the  I-Format-element,
           REAL, DOUBLE PRECISION (COMPLEX) one (two)
             F-, G-, E- or D-Format-elements,
           LOGICAL an L-Format-element,
           CHARACTER an A-Format-element.
    31   Format-element L: T or F expected (input)
    32   Format-element I: unexpected character (input)
           space,sign and numbers permitted.
    33   Format-element E, F or D: unexpected
           character (input).
           space, sign, numbers,
           decimalpoint, E, e, D or d (for exponent)
           permitted.
    34   Too many ( in Format.
    35   Too many ) in Format.
    36   numeric-sequence not in permitted place in format description.
    37   Format-element not recognised.
    38   . missing in F, E, G or D Format-element.
    39   4Htext or 'text' in Format for READ.
           In FORTRAN66 one could include text in a Format
           in this way; no longer permitted
           in FORTRAN77.
    40   Exponent too large for indicated format.
    42   Format-element too long. Max. Length of the internal
           Recordbuffer (80 characters).
    43   Internal I/O, Record too long.
    44   TL, Record too long. If a Record is longer than
           the internal Recordbuffer, one can no
           longer tabulate to the left.
    45   Fieldlength of 0 with I,L,F,E,G,D Format-element.

    1000+n  Amiga-Dos Error n
            See Amiga-Dos Handbook, Appendix A.

    1202 Datafile in use.
    1203 Datafile exists already.
    1204 Directory not found.  [I think.. -MB]
    1205 Datafile not found.
    1206 Invalid Window-Parameter
    1209 Function is not possible on this device.
    1210 Invalid Datafilename.
    1212 Confusion Datafilename/Directoryname.
    1213 Disk not validated.
    1214 Disk write-protected.
    1218 No Disk present.
    1221 Disk full.
    1222 Datafile delete-protected.
    1223 Datafile write-protected.
    1224 Datafile read-protected.
    1225 Not an Amiga-Dos Disk.
    1226 No disk present.
    1232 No space for entry.


Problems
--------

If someone believes that the compiler, linker or library
contains an error, please let me know in writing.
Please understand that for this product (as opposed to
Version P.) there is no updateservice nor telephone
assistence possible.