% macropackage = lplain % Introduction to BC-FORTRAN 1.3C % written by Florian Nold (email address MEHA@DFRRUF1.BITNET) % % Version 1.0, 3.3.1991 % \documentstyle[titlepage]{article} \textheight 23.0cm \textwidth 15.5cm \footheight 5.0cm \headheight 0.0cm \headsep 0.1cm \evensidemargin -0.2cm \oddsidemargin -0.2cm \title{BC--FORTRAN77 Version 1.3C} \date{Copyright $\copyright$ 1990} \author{Andre Koestli\\ Martin--Luther--Strasse 63\\ W-7000 Stuttgart 50\\ Federal Republic of Germany} \begin{document} \maketitle \tableofcontents \section{Preface} \subsection*{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 {\tt 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 {\tt lies.txt}) has also been included. If you find any mistakes in this english {\it 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 {\bf NO} connection whatsoever with him. \subsection*{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 {\bf strictly} forbidden to use BC--FORTRAN77 Version ''C'' for any military purpose or research. \noindent March 1990, A. Koestli \bigskip 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. \section{BC--FORTRAN77 version ''P''} {\em 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 mathematical 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. \section{BC--FORTRAN77 Version C} BC--FORTRAN77 version ''C'', which is described in the rest of this text, includes the following files: \begin{tabbing} \quad\= BCFMAN.TEX \= \kill \> {\tt LIES.TXT} \> original german version of this text, written by Andre Koestli, the author of \\ \> \> BC--FORTRAN77. (''lies'' is the german word for ''read'')\\ \> {\tt BCFMAN.TEX}\> this text\\ \> {\tt BCFMAN.TXT}\> ASCII version of this text\\ \> {\tt BCF.TTP} \> the compiler\\ \> {\tt BCL.TTP} \> the linker\\ \> {\tt BCRTSY.B } \> the runtime library\\ \> {\tt MATHLIB.B } \> library (incl. FORTRAN77 standard functions)\\ \end{tabbing} Be sure to include {\bf all} these files without any changes when copying BC-FORT\-RAN77. Using a command-line-interpreter or a shell (e.g. {\tt 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. \section{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 {\tt BCF.TTP} and {\tt BCL.TTP} in the directory, where the shell would search for the bin-stuff. {\tt BCRTSY.B} and {\tt MATHLIB.B} should be moved to the directory {\tt $\backslash$BC} of the actual drive. \section{The Compiler {\tt BCF.TTP}} To invoke the compiler enter \begin{enumerate} \item {\tt BCF [{\it -options}]} {\it filename}\\ or \item double click on the {\tt BCF.TTP}--icon on the desktop and enter options and filename. \end{enumerate} If the {\it filename} does not contain any point, the extension {\tt .F} will be appended. In any case the compiler will write its output to the file {\it filename}{\tt .B}. \noindent Examples:\\ \begin{itemize} \item {\tt BCF -D TEST.F} compile the file {\tt TEST.F} to {\tt TEST.B} using the debug--option \item {\tt BCF TEST SUB} compile the file {\tt TEST.F} to {\tt TEST.B} and {\tt SUB.F} to {\tt SUB.B} \item {\tt BCF TEST.X} compile the file {\tt TEST.X} to {\tt TEST.B} \end{itemize} \subsection*{Compiler Options} \begin{tabular}{l l} {\tt -D} & {\bf D}ebug, equivalent to {\tt -BVL}.\\ {\tt -B} & de{\bf B}ugcode, uses {\tt -H} implicit, generate code to check arraybounds and substrings.\\ {\tt -H} & parc{\bf H}eck, generate code to check parameter lists and stack overflow.\\ {\tt -V} & {\bf V}arlist, generate list of variables used by the debugger.\\ {\tt -L} & {\bf L}ineslist, generate list of linenumbers for the debugger.\\ {\tt -U} & {\bf U}ppercase, convert lowercase characters to uppercase (except character constants\\ & and FORMAT statements). If this option is not specified the compiler will treat\\ & {\tt xy, xY, Xy, XY} as 4 different variables !\\ {\tt -F} & {\bf F}reeinput, allows Free-Form-Input-Format (not standard !)\\ {\tt -P} & {\bf P}rotocol, print compiler listing.\\ {\tt -W} & {\bf W}ait for RETURN key when compiler has finished.\\ \end{tabular} \subsection*{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. \noindent The most important specialities are: \begin{tabbing} \quad \= IMPLICIT NONEABC \= \kill \> 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 /\%{\it adr}/ \> absolute addressed COMMON, {\it 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.)\\ \end{tabbing} The most important restrictions are: \begin{tabbing} \quad \=32kB \= \kill \> 32kB \> code per subroutine\\ \> 32kB \> SAVE/DATA per subroutine or BLOCK DATA\\ \> 700 \> subroutines per file\\ \> 500 \> different COMMON blocks per file\\ \end{tabbing} 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. \section{The Linker {\tt BCL.TTP}} To invoke the linker just type \begin{itemize} \item[] {\tt BCL} [{\it -options}] {\it filename $\ldots$} \end{itemize} or click the {\tt BCL.TTP} icon on the desktop and enter options and filenames. If the filename doesn't contain any point, the extension {\tt .B} will be appended. The executable program will be stored using the name of the first file and the extension {\tt .PRG}. If the source contains any mathematical standard function calls the file {\tt MATHLIB.B} must be specified too. The runtime system {\tt BCRTSY.B} will be linked automatically. \newline Example: \begin{itemize} \item[] {\tt BCL -S16 TEST SUB MATHLIB}\\ or \item[] {\tt BCL -S16 TEST.B SUB.B MATHLIB.B} \end{itemize} will link the files {\tt TEST.B} and {\tt SUB.B}. The name of the resulting executable will be {\tt TEST.PRG} (stacksize 16kB). \subsection*{Linker Options} \begin{tabular}{l l} {\tt -S{\it n}} & {\bf S}tacksize of the resulting executable is set to {\it 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.\\ {\tt -O} & {\bf O}ptimize: remove unused functions in order to reduce code size\\ {\tt -P} & {\bf P}rotocol: generate listing of COMMON blocks and program modules\\ {\tt -W} & {\bf W}ait for RETURN key when finished \end{tabular} \subsection*{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. \subsection*{The Runtime System {\tt BCRTSY.B}} The runtime system {\tt BCRTSY.B} contains stuff needed by every BC-FORTRAN77 program. Therefore it will be linked automatically by {\tt BCL.TTP}. \newline {\tt BCRTSY.B} consists of: \begin{itemize} \item arithmetic routines \begin{itemize} \item 32 bit INTEGER multiplication/divison \item REAL arithmetics \item DOUBLE PRECISION arithmetics: in order to increase performance 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''. \end{itemize} \item CHARACTER routines \item I/O routines \item 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 {\tt ALT}-key, to stop a running program. The following command keys are supported: \begin{itemize} \item[{\tt S}] print the subroutine call {\bf S}tack and the line number (if the compiler option {\tt -L} has been specified) \item[{\tt V}] print the {\bf V}ariables and their contents of the actual subroutine (only if the compiler option {\tt -V} has been specified) \item[{\tt Z}] terminate program \item[{\it space}] continue, in the case that no runtime error has occured. If you press the {\tt ALT}-key simultaneously, only the next program step will be executed (e.g. next label, subroutine, ELSE, ENDIF, DO, etc.) \end{itemize} \end{itemize} \subsection*{The Standard Library {\tt MATHLIB.B}} {\tt MATHLIB.B} contains all the mathematical functions described by the ANSI standard. If the linker issues an error message like ''External nicht gefunden: f\underline{ }SQRT'' (german text for ''external not found'') you have to specify {\tt MATHLIB.B} when running the linker {\tt BCL.TTP}. \subsection*{Starting your Program} Every executable program produced by {\tt BCL} can be started like any other program from the desktop or a shell. \section{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. \subsection*{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. \begin{tabbing} error-number \quad description \\ error\= number\quad \= \kill \> -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 \> {\tt 4Htext} or ''{\tt 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\\ \end{tabbing} \subsection*{TOS Errors} in general: $ 1000 + n \leadsto \mbox{TOS-Error } -n$ \begin{tabbing} error-number \quad description \\ error\= number\quad \= \kill \> 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. {\tt K}) \\ \> 1066 \> wrong format of program file\\ \end{tabbing} \section{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''. \newpage \appendix \section*{Small dictionary} \begin{tabular}{l|l} German & English \\ \hline\\ 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 $\ldots$ & error opening file $\ldots$\\ Fehler beim Laden & load error\\ Fehler beim Lesen & read error \\ haupt & main\\ hier nicht erlaubt & not allowed here\\ \end{tabular} \newpage \begin{tabular}{l|l} German & English \\ \hline\\ 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\\ \end{tabular} \newpage \begin{tabular}{l|l} German & English \\ \hline\\ 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\\ \end{tabular} \end{document}