f2c - FORTRAN to C translator - OS/2 2.0 version
================================================

1. Introduction
===============

This package contains f2c, a FORTRAN to C translator available from 
netlib@research.att.com, compiled for OS/2 v 2.0 using the GNU compiler.
Support libraries for both GNU ports currently obtainable ('gcc/2' and 
'emx0.8e') are provided.

Using f2c, a FORTRAN77 program can be translated to C and can then be compiled
using gcc from one of the above GNU compilers. Tests indicate that this 
procedure works well, even with some large and messy FORTRAN programs (3500
lines of spaghetti code). An improvement in execution time of up to a factor
of two can be expected, relative to the same program compiled with a 16-bit 
compiler such as MS Fortran 5.x.

The package contains, in addition to this file, the following files:

f2c.exe         -- FORTRAN to C translator
f2c.1           -- UN*X man page for f2c
f2c.ps          -- PostScript note on implementation of f2c
f2c.h           -- C header file needed for C compilation
fprint.exe      -- print filter for carriage control expansion
fprint.c        -- source code for above
notice          -- copyright stuff
disclaim        -- disclaimer
readme          -- this file 
emx\libf2c.a      )
emx\libf2c.lib    )-- libraries for use with 'emx0.8e' compiler
gcc\libf2c.lib    )
gcc\libc.lib      )-- libraries for use with 'gcc/2' compiler

The directory gcc contains a replacement C library for the 'gcc/2' compiler
(libc.lib), which incorporates the assembler-based math functions from
the emx0.8d distribution, rather than the C-based math functions from the
gcc/2 distribution. This leads to a large enhancement in performance.

Libraries are provided for both a.out and OMF formats of emx0.8e.

2. Installation
===============

After unpacking the archive in any convenient subdirectory, the various 
bits and pieces can be installed as follows:

f2c.exe     -- place somewhere in PATH.
f2c.h       -- place in directory with other C header files.
emx\*.*     -- place in directory with other emx library files (e.g.\emx\lib)
gcc\*.*     -- place in directory with other gcc/2 library files (e.g.\gnu\lib)
               (it might be a good idea to keep your old libc.lin in case...)

The documentation can be placed anywhere you find convenient.

3. Use
======

f2c is restricted to translating one fortran file at a time (owing to
a lack of 'fork()' under OS/2**). A file <name>.f is translated to a file 
<name>.c.

The C file(s) are then compiled using gcc, and linked with the library
libf2c. In addition, the library libos2 must be linked when using the 
'emx' compiler. For compilation of the C files, the file f2c.h 
should be accessible to the compiler.

Example
-------
Compile a FORTRAN program consisting of two files proga.f and progb.f:

At command line...                      Comments...    

f2c proga.f                             produces proga.c
f2c progb.f                             produces progb.c

                                        For 'gcc/2' compiler ...

gcc -c -O2 proga.c progb.c              produces proga.obj, progb.obj
link386 proga+progb,,,libf2c;           produces proga.exe
                                        (or)
link386 proga+progb,prog,proglst,libf2c;
                                        produces prog.exe, proglst.lst
                                        (linker map)

                                        For 'emx' compiler ...
gcc -o prog.exe -O2 proga.c progb.c -lif2c -los2
                                        produces prog.exe

---
link386 as used above will produce a default exe file that can be run in both
windowed or full screen OS/2 cmd sessions. If this as what you require,
the L4071 warning can be ignored. For other cases, you will need to construct
a .def file; consult the link386 documentation (16-bit link docs might also
help you).

A simple print filter is supplied which will expand FORTRAN carriage
control output for output written, for instance, to disk.
It reads from standard input and write to standard output,
and should be used with i/o redirection.
Useage:
fprint <input >output

** Yes, emx0.8e has a fork(). f2c has been compiled using gcc/2 for the 
benefit of those who do not want/have the emx DLLs. 


4. Notes
========

4.1)  The port of f2c was complicated by differing behaviour of the two C
libraries (gcc/2 and emx). No doubt, there are things in libf2c 
that still don't work under one or the other compiler (or both). 
If you suspect a problem with the libraries, please let me know at the 
address below. If you suspect a problem with f2c itself, report it
as suggested in the f2c docs.
 
4.2)  A few things have been added to the library to make it behave a little
more like other PC fortran libraries:

4.2.1 A blank filename in an 'open' statement (i.e. OPEN(UNIT=6, FILE=' ',....)
will cause the next name on the command line to be used as the filename.
(f2c also has other ways of accessing the command line, see f2c.ps)

4.2.2 Time and date subroutines have been added:

subroutine gettim( ihour, imin, isec, i100 )
integer *2 ihour, imin, isec, i100

Returns current time, in ihour, imin and isec. (i100 is set to zero).

subroutine getdat( iyear, imonth, iday )
integer*2 iyear, imonth, iday

Returns current date.

4.2.3 Output to the screen has some carriage control characters expanded;
a '+' cannot be efficiently handled without a major rewrite of the 
output routines and is ignored.

4.3)  Note that f2c is a translator and probably won't let you get away
with a few things that your favourite FORTRAN compiler will permit. 
For instance, the MS 5.0 compiler will allow you to branch to a block
of code that is physically outside a DO loop, but logically contained
within it (I don't think this is allowed in the FORTRAN77 standard).
f2c cannot analyse the code flow and will generate incorrect code,
but will issue a warning.


5 Comments, complaints, etc to:
===============================
Roger Fearick
Dept. of Physics,
University of Cape Town.
fearick@physci.uct.ac.za

