| 1 |
<html> |
| 2 |
<head> |
| 3 |
<title>cfortran.h: Interfacing C or C++ and FORTRAN</title> |
| 4 |
</head> |
| 5 |
|
| 6 |
<BODY BGCOLOR="#FFFFFF"> |
| 7 |
|
| 8 |
<h1>cfortran.h: Interfacing C or C++ and <i>FORTRAN</i></h1> |
| 9 |
|
| 10 |
<hr> |
| 11 |
|
| 12 |
<b>Author:</b><a href="http://www-zeus.desy.de/~burow">Burkhard Burow</a> <br> |
| 13 |
<b>Email:</b> [email protected] <br> |
| 14 |
<b>www:</b> <a href="http://www-zeus.desy.de/~burow/cfortran">www-zeus.desy.de/~burow/cfortran</a> <br> |
| 15 |
|
| 16 |
<hr> |
| 17 |
<p> |
| 18 |
<b>Supports:</b> |
| 19 |
<FONT COLOR="#993300"><pre> |
| 20 |
Alpha OSF, DECstation, IBM RS/6000, |
| 21 |
Silicon Graphics, Sun, HP9000, LynxOS, Convex, Absoft, |
| 22 |
f2c, g77, NAG f90, PowerStation <i>FORTRAN</i> with Visual C++, NEC SX-4, |
| 23 |
Portland Group. |
| 24 |
</pre></font> |
| 25 |
C and C++ are generally equivalent as far as <tt>cfortran.h</tt> is concerned. |
| 26 |
Unless explicitly noted otherwise, mention of C implicitly includes C++. |
| 27 |
C++ compilers tested include: |
| 28 |
<p><FONT COLOR="#993300"><pre> |
| 29 |
SunOS> CC +p +w # Clean compiles. |
| 30 |
IRIX> CC # Clean compiles. |
| 31 |
IRIX> CC -fullwarn # Still some warnings to be overcome. |
| 32 |
GNU> g++ -Wall # Compiles are clean, other than warnings for unused |
| 33 |
# cfortran.h static routines. |
| 34 |
</pre></font> |
| 35 |
|
| 36 |
<b>N.B.</b>: The best documentation on interfacing C or C++ and <i>FORTRAN</i> is in |
| 37 |
the chapter named something like 'Interfacing C and <i>FORTRAN</i>' |
| 38 |
to be found in the user's guide of almost every <i>FORTRAN</i> compiler. |
| 39 |
Understanding this information for one or more <i>FORTRAN</i> compilers |
| 40 |
greatly clarifies the aims and actions of <tt>cfortran.h</tt>. |
| 41 |
Such a chapter generally also addresses issues orthogonal to <tt>cfortran.h</tt>, |
| 42 |
for example the order of array indices, the index of the first element, |
| 43 |
as well as compiling and linking issues. |
| 44 |
|
| 45 |
|
| 46 |
<h2> Short Summary of the Syntax Required to Create the Interface</h2> |
| 47 |
|
| 48 |
e.g. Prototyping a <i>FORTRAN</i> subroutine for C: |
| 49 |
|
| 50 |
<tt>PROTOCCALLSFSUBni</tt> is optional for C, but mandatory for C++. |
| 51 |
<FONT COLOR="#993300"><pre> |
| 52 |
PROTOCCALLSFSUB2(SUB_NAME,sub_name,STRING,PINT) |
| 53 |
#define SUB_NAME(A,B) CCALLSFSUB2(SUB_NAME,sub_name,STRING,PINT, A,B) |
| 54 |
|
| 55 |
^ - - |
| 56 |
number of arguments _____| | STRING BYTE PBYTE BYTEV(..)| |
| 57 |
/ | STRINGV DOUBLE PDOUBLE DOUBLEV(..)| |
| 58 |
/ | PSTRING FLOAT PFLOAT FLOATV(..)| |
| 59 |
types of arguments ____ / | PNSTRING INT PINT INTV(..)| |
| 60 |
\ | PPSTRING LOGICAL PLOGICAL LOGICALV(..)| |
| 61 |
\ | PSTRINGV LONG PLONG LONGV(..)| |
| 62 |
\ | ZTRINGV SHORT PSHORT SHORTV(..)| |
| 63 |
| LONGLONG PLONGLONG LONGLONG(..) |
| 64 |
| PZTRINGV ROUTINE PVOID SIMPLE | |
| 65 |
- - |
| 66 |
</pre></font> |
| 67 |
|
| 68 |
e.g. Prototyping a <i>FORTRAN</i> function for C: |
| 69 |
|
| 70 |
<FONT COLOR="#993300"><pre> |
| 71 |
/* PROTOCCALLSFFUNn is mandatory for both C and C++. */ |
| 72 |
PROTOCCALLSFFUN1(INT,FUN_NAME,fun_name,STRING) |
| 73 |
#define FUN_NAME(A) CCALLSFFUN1(FUN_NAME,fun_name,STRING, A) |
| 74 |
</pre></font> |
| 75 |
e.g. calling <tt>FUN_NAME</tt> from C: |
| 76 |
<FONT COLOR="#993300"><pre> |
| 77 |
{int a; a = FUN_NAME("hello");} |
| 78 |
</pre></font> |
| 79 |
|
| 80 |
e.g. Creating a <i>FORTRAN</i>-callable wrapper for |
| 81 |
a C function returning void, with a 7 dimensional integer array argument: |
| 82 |
[Not supported from C++.] |
| 83 |
|
| 84 |
<FONT COLOR="#993300"><pre> |
| 85 |
FCALLSCSUB1(csub_name,CSUB_NAME,csub_name,INTVVVVVVV) |
| 86 |
</pre></font> |
| 87 |
|
| 88 |
e.g. Creating a <i>FORTRAN</i>-callable wrapper for other C functions: |
| 89 |
<FONT COLOR="#993300"><pre> |
| 90 |
FCALLSCFUN1(STRING,cfun_name,CFUN_NAME,cfun_name,INT) |
| 91 |
[ ^-- BYTE, DOUBLE, FLOAT, INT, LOGICAL, LONG, LONGLONG, SHORT, VOID |
| 92 |
are other types returned by functions. ] |
| 93 |
</pre></font> |
| 94 |
|
| 95 |
e.g. COMMON BLOCKs: |
| 96 |
<FONT COLOR="#993300"><pre> |
| 97 |
<b>FORTRAN:</b> |
| 98 |
|
| 99 |
common /fcb/ v,w,x |
| 100 |
character *(13) v, w(4), x(3,2) |
| 101 |
|
| 102 |
<b>C:</b> |
| 103 |
|
| 104 |
typedef struct { char v[13],w[4][13],x[2][3][13]; } FCB_DEF; |
| 105 |
#define FCB COMMON_BLOCK(FCB,fcb) |
| 106 |
COMMON_BLOCK_DEF(FCB_DEF,FCB); |
| 107 |
FCB_DEF FCB; /* Define, i.e. allocate memory, in exactly one *.c file. */ |
| 108 |
</pre></font> |
| 109 |
e.g. accessing <tt>FCB</tt> in C: |
| 110 |
<FONT COLOR="#993300"><pre> |
| 111 |
printf("%.13s",FCB.v); |
| 112 |
</pre></font> |
| 113 |
|
| 114 |
|
| 115 |
<h2> I) Introduction</h2> |
| 116 |
|
| 117 |
<tt>cfortran.h</tt> is an easy-to-use powerful bridge between C and <i>FORTRAN</i>. |
| 118 |
It provides a completely transparent, machine independent interface between |
| 119 |
C and <i>FORTRAN</i> routines (= subroutines and/or functions) and global data, |
| 120 |
i.e. structures and COMMON blocks. |
| 121 |
<p> |
| 122 |
The complete <tt>cfortran.h</tt> package consists of 4 files: the documentation in |
| 123 |
cfortran.doc, the engine <tt>cfortran.h</tt>, examples in <tt>cfortest.c</tt> and |
| 124 |
<tt>cfortex.f/or</tt>. [<tt>cfortex.for</tt> under VMS, |
| 125 |
<tt>cfortex.f</tt> on other machines.] |
| 126 |
<p> |
| 127 |
The <tt>cfortran.h</tt> package continues to be developed. |
| 128 |
The most recent version is |
| 129 |
available via WWW at |
| 130 |
<tt><a href="http://www-zeus.desy.de/~burow/cfortran">http://www-zeus.desy.de/~burow/cfortran</a></tt>. |
| 131 |
<p> |
| 132 |
The examples may be run using one of the following sets of instructions: |
| 133 |
<p> |
| 134 |
<b>N.B.</b> Unlike earlier versions, <tt>cfortran.h</tt> 3.0 and later versions |
| 135 |
automatically uses the correct <tt>ANSI ##</tt> or <tt>pre-ANSI /**/</tt> |
| 136 |
preprocessor operator as required by the C compiler. |
| 137 |
<p> |
| 138 |
<b>N.B.</b> As a general rule when trying to determine how to link C and |
| 139 |
<i>FORTRAN</i>, |
| 140 |
link a trivial <i>FORTRAN</i> program using the <i>FORTRAN</i> compilers verbose option, |
| 141 |
in order to see how the <i>FORTRAN</i> compiler drives the linker. e.g. |
| 142 |
<FONT COLOR="#993300"><pre> |
| 143 |
unix> cat f.f |
| 144 |
END |
| 145 |
unix> f77 -v f.f |
| 146 |
.. lots of info. follows ... |
| 147 |
</pre></font> |
| 148 |
<p> |
| 149 |
<b>N.B.</b> If using a C <tt>main()</tt>, i.e. <i>FORTRAN</i> <tt>PROGRAM</tt> |
| 150 |
is not entry of the executable, |
| 151 |
and if the link bombs with a complaint about |
| 152 |
a missing "<tt>MAIN</tt>" (e.g. <tt>MAIN__</tt>, <tt>MAIN_</tt>, |
| 153 |
<tt>f90_main</tt> or similar), |
| 154 |
then <i>FORTRAN</i> has hijacked the entry point to the executable |
| 155 |
and wishes to call the rest of the executable via "<tt>MAIN</tt>". |
| 156 |
This can usually be satisfied by doing e.g. '<tt>cc -Dmain=MAIN__ ...</tt>' |
| 157 |
but often kills the command line arguments in <tt>argv</tt> and <tt>argc</tt>. |
| 158 |
The <tt>f77</tt> verbose option, usually <tt>-v</tt>, may point to a solution. |
| 159 |
|
| 160 |
<FONT COLOR="#993300"><pre> |
| 161 |
RS/6000> # Users are strongly urged to use f77 -qextname and cc -Dextname |
| 162 |
RS/6000> # Use -Dextname=extname if extname is a symbol used in the C code. |
| 163 |
RS/6000> xlf -c -qextname cfortex.f |
| 164 |
RS/6000> cc -c -Dextname cfortest.c |
| 165 |
RS/6000> xlf -o cfortest cfortest.o cfortex.o && cfortest |
| 166 |
|
| 167 |
DECFortran> #Only DECstations with DECFortran for Ultrix RISC Systems. |
| 168 |
DECFortran> cc -c -DDECFortran cfortest.c |
| 169 |
DECFortran> f77 -o cfortest cfortest.o cfortex.f && cfortest |
| 170 |
|
| 171 |
IRIX xxxxxx 5.2 02282015 IP20 mips |
| 172 |
MIPS> # DECstations and Silicon Graphics using the MIPS compilers. |
| 173 |
MIPS> cc -o cfortest cfortest.c cfortex.f -lI77 -lU77 -lF77 && cfortest |
| 174 |
MIPS> # Can also let f77 drive linking, e.g. |
| 175 |
MIPS> cc -c cfortest.c |
| 176 |
MIPS> f77 -o cfortest cfortest.o cfortex.f && cfortest |
| 177 |
|
| 178 |
VMS> define lnk$library sys$library:vaxcrtl |
| 179 |
VMS> cc cfortest.c |
| 180 |
VMS> fortran cfortex.for |
| 181 |
VMS> link/exec=cfortest cfortest,cfortex |
| 182 |
VMS> run cfortest |
| 183 |
|
| 184 |
OSF1 xxxxxx V3.0 347 alpha |
| 185 |
Alpha/OSF> # Probably better to let cc drive linking, e.g. |
| 186 |
Alpha/OSF> f77 -c cfortex.f |
| 187 |
Alpha/OSF> cc -o cfortest cfortest.c cfortex.o -lUfor -lfor -lFutil -lots -lm |
| 188 |
Alpha/OSF> cfortest |
| 189 |
Alpha/OSF> # Else may need 'cc -Dmain=MAIN__' to let f77 drive linking. |
| 190 |
|
| 191 |
Sun> # Some old cc(1) need a little help. <a href="cfortran.html#SIIoSun">[See Section II o) Notes: Sun]</a> |
| 192 |
Sun> f77 -o cfortest cfortest.c cfortex.f -lc -lm && cfortest |
| 193 |
Sun> # Some older f77 may require 'cc -Dmain=MAIN_'. |
| 194 |
|
| 195 |
NEC> cc -c -Xa cfortest.c |
| 196 |
NEC> f77 -o cfortest cfortest.o cfortex.f && cfortest |
| 197 |
|
| 198 |
LynxOS> # In the following, 'CC' is either 'cc' or 'gcc -ansi'. |
| 199 |
LynxOS> # Unfortunately cc is easily overwhelmed by cfortran.h, |
| 200 |
LynxOS> # and won't compile some of the cfortest.c demos. |
| 201 |
LynxOS> f2c -R cfortex.f |
| 202 |
LynxOS> CC -Dlynx -o cfortest cfortest.c cfortex.c -lf2c && cfortest |
| 203 |
|
| 204 |
HP9000> # Tested with HP-UX 7.05 B 9000/380 and with A.08.07 A 9000/730 |
| 205 |
HP9000> # CC may be either 'c89 -Aa' or 'cc -Aa' |
| 206 |
HP9000> # Depending on the compiler version, you may need to include the |
| 207 |
HP9000> # option '-tp,/lib/cpp' or worse, you'll have to stick to the K&R C. |
| 208 |
HP9000> # <a href="cfortran.html#SIIoHP9000">[See Section II o) Notes: HP9000]</a> |
| 209 |
HP9000> # Users are strongly urged to use f77 +ppu and cc -Dextname |
| 210 |
HP9000> # Use -Dextname=extname if extname is a symbol used in the C code. |
| 211 |
HP9000> CC -Dextname -c cfortest.c |
| 212 |
HP9000> f77 +ppu cfortex.f -o cfortest cfortest.o && cfortest |
| 213 |
HP9000> # Older f77 may need |
| 214 |
HP9000> f77 -c cfortex.f |
| 215 |
HP9000> CC -o cfortest cfortest.c cfortex.o -lI77 -lF77 && cfortest |
| 216 |
|
| 217 |
HP9000> # If old-style f77 +800 compiled objects are required: |
| 218 |
HP9000> # #define hpuxFortran800 |
| 219 |
HP9000> cc -c -Aa -DhpuxFortran800 cfortest.c |
| 220 |
HP9000> f77 +800 -o cfortest cfortest.o cfortex.f |
| 221 |
|
| 222 |
f2c> # In the following, 'CC' is any C compiler. |
| 223 |
f2c> f2c cfortex.f |
| 224 |
f2c> CC -o cfortest -Df2cFortran cfortest.c cfortex.c -lf2c && cfortest |
| 225 |
|
| 226 |
Portland Group $ # Presumably other C compilers also work. |
| 227 |
Portland Group $ pgcc -DpgiFortran -c cfortest.c |
| 228 |
Portland Group $ pgf77 -o cfortest cfortex.f cfortest.o && cfortest |
| 229 |
|
| 230 |
NAGf90> # cfortex.f is distributed with <i>FORTRAN</i> 77 style comments. |
| 231 |
NAGf90> # To convert to f90 style comments do the following once to cfortex.f: |
| 232 |
NAGf90> mv cfortex.f cf_temp.f && sed 's/^C/\!/g' cf_temp.f > cfortex.f |
| 233 |
NAGf90> # In the following, 'CC' is any C compiler. |
| 234 |
NAGf90> CC -c -DNAGf90Fortran cfortest.c |
| 235 |
NAGf90> f90 -o cfortest cfortest.o cfortex.f && cfortest |
| 236 |
|
| 237 |
PC> # On a PC with PowerStation <i>FORTRAN</i> and Visual_C++ |
| 238 |
PC> cl /c cftest.c |
| 239 |
PC> fl32 cftest.obj cftex.for |
| 240 |
|
| 241 |
GNU> # GNU <i>FORTRAN</i> |
| 242 |
GNU> # <a href="cfortran.html#gcctrad">See Section VI caveat on using 'gcc -traditional'</a>. |
| 243 |
GNU> gcc -ansi -Wall -O -c -Df2cFortran cfortest.c |
| 244 |
GNU> g77 -ff2c -o cfortest cfortest.o cfortex.f && cfortest |
| 245 |
|
| 246 |
AbsoftUNIX> # Absoft <i>FORTRAN</i> for all UNIX based operating systems. |
| 247 |
AbsoftUNIX> # e.g. Linux or Next on Intel or Motorola68000. |
| 248 |
AbsoftUNIX> # Absoft f77 -k allows <i>FORTRAN</i> routines to be safely called from C. |
| 249 |
AbsoftUNIX> gcc -ansi -Wall -O -c -DAbsoftUNIXFortran cfortest.c |
| 250 |
AbsoftUNIX> f77 -k -o cfortest cfortest.o cfortex.f && cfortest |
| 251 |
|
| 252 |
AbsoftPro> # Absoft Pro <i>FORTRAN</i> for MacOS |
| 253 |
AbsoftPro> # Use #define AbsoftProFortran |
| 254 |
|
| 255 |
CLIPPER> # INTERGRAPH CLIX using CLIPPER C and <i>FORTRAN</i> compilers. |
| 256 |
CLIPPER> # N.B. - User, not cfortran.h, is responsible for |
| 257 |
CLIPPER> # f77initio() and f77uninitio() if required. |
| 258 |
CLIPPER> # - LOGICAL values are not mentioned in CLIPPER doc.s, |
| 259 |
CLIPPER> # so they may not yet be correct in cfortran.h. |
| 260 |
CLIPPER> # - K&R mode (-knr or Ac=knr) breaks FLOAT functions |
| 261 |
CLIPPER> # (see CLIPPER doc.s) and cfortran.h does not fix it up. |
| 262 |
CLIPPER> # [cfortran.h ok for old sun C which made the same mistake.] |
| 263 |
CLIPPER> acc cfortest.c -c -DCLIPPERFortran |
| 264 |
CLIPPER> af77 cfortex.f cfortest.o -o cfortest |
| 265 |
</pre></font> |
| 266 |
|
| 267 |
By changing the SELECTion <tt>ifdef</tt> of <tt>cfortest.c</tt> and recompiling one can try out |
| 268 |
a few dozen different few-line examples. |
| 269 |
|
| 270 |
<p> |
| 271 |
|
| 272 |
The benefits of using <tt>cfortran.h</tt> include: |
| 273 |
|
| 274 |
<ol> |
| 275 |
<p><li> Machine/OS/compiler independent mixing of C and <i>FORTRAN</i>. |
| 276 |
|
| 277 |
<p><li> Identical (within syntax) calls across languages, e.g. |
| 278 |
<FONT COLOR="#993300"><pre> |
| 279 |
<b>FORTRAN:</b> |
| 280 |
|
| 281 |
CALL HBOOK1(1,'pT spectrum of pi+',100,0.,5.,0.) |
| 282 |
|
| 283 |
<b>C:</b> |
| 284 |
HBOOK1(1,"pT spectrum of pi+",100,0.,5.,0.); |
| 285 |
</pre></font> |
| 286 |
<p><li> Each routine need only be set up once in its lifetime. e.g. |
| 287 |
Setting up a FORTRAN routine to be called by C. |
| 288 |
ID,...,VMX are merely the names of arguments. |
| 289 |
These tags must be unique w.r.t. each other but are otherwise arbitrary. |
| 290 |
<FONT COLOR="#993300"><pre> |
| 291 |
PROTOCCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT) |
| 292 |
#define HBOOK1(ID,CHTITLE,NX,XMI,XMA,VMX) \ |
| 293 |
CCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT, \ |
| 294 |
ID,CHTITLE,NX,XMI,XMA,VMX) |
| 295 |
</pre></font> |
| 296 |
|
| 297 |
<p><li> Source code is NOT required for the C routines exported to <i>FORTRAN</i>, nor for |
| 298 |
the <i>FORTRAN</i> routines imported to C. In fact, routines are most easily |
| 299 |
prototyped using the information in the routines' documentation. |
| 300 |
|
| 301 |
<p><li> Routines, and the code calling them, can be coded naturally in the language |
| 302 |
of choice. C routines may be coded with the natural assumption of being |
| 303 |
called only by C code. <tt>cfortran.h</tt> does all the required work for <i>FORTRAN</i> |
| 304 |
code to call C routines. Similarly it also does all the work required for C |
| 305 |
to call <i>FORTRAN</i> routines. Therefore: |
| 306 |
<ul> |
| 307 |
<li> C programmers need not embed <i>FORTRAN</i> argument passing mechanisms into |
| 308 |
their code. |
| 309 |
<li> <i>FORTRAN</i> code need not be converted into C code. i.e. The honed and |
| 310 |
time-honored <i>FORTRAN</i> routines are called by C. |
| 311 |
</ul> |
| 312 |
<p><li> <tt>cfortran.h</tt> is a single ~1700 line C include file; portable to most |
| 313 |
remaining, if not all, platforms. |
| 314 |
|
| 315 |
<p><li> <tt>STRINGS</tt> and <tt>VECTORS</tt> of |
| 316 |
<tt>STRINGS</tt> along with the usual simple arguments to |
| 317 |
routines are supported as are functions returning |
| 318 |
<tt>STRINGS</tt> or numbers. Arrays |
| 319 |
of pointers to strings and values of structures as C arguments, |
| 320 |
will soon be |
| 321 |
implemented. |
| 322 |
After learning the machinery of <tt>cfortran.h</tt>, users can expand |
| 323 |
it to create custom types of arguments. [This requires no modification to |
| 324 |
<tt>cfortran.h</tt>, all the preprocessor |
| 325 |
directives required to implement the |
| 326 |
custom types can be defined outside <tt>cfortran.h</tt>] |
| 327 |
|
| 328 |
<p><li> <tt>cfortran.h</tt> requires each routine to be exported to be explicitly set up. |
| 329 |
While is usually only be done once in a header file it would be best if |
| 330 |
applications were required to do no work at all in order to cross languages. |
| 331 |
<tt>cfortran.h</tt>'s simple syntax could be a convenient back-end for a program |
| 332 |
which would export <i>FORTRAN</i> or C routines directly from the source code. |
| 333 |
</ol> |
| 334 |
|
| 335 |
|
| 336 |
<h3>Example 1 </h3> |
| 337 |
<tt>cfortran.h</tt> has been used to make the C header file <tt>hbook.h</tt>, |
| 338 |
which then gives any C programmer, e.g. <tt>example.c</tt>, full and |
| 339 |
completely transparent access to <b>CERN</b>'s <b>HBOOK</b> library of routines. |
| 340 |
Each <b>HBOOK</b> routine required about 3 lines of simple code in |
| 341 |
<tt>hbook.h</tt>. The example also demonstrates how <i>FORTRAN</i> common blocks |
| 342 |
are defined and used. |
| 343 |
<FONT COLOR="#993300"><pre> |
| 344 |
/* hbook.h */ |
| 345 |
#include <cfortran.h> |
| 346 |
: |
| 347 |
PROTOCCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT) |
| 348 |
#define HBOOK1(ID,CHTITLE,NX,XMI,XMA,VMX) \ |
| 349 |
CCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT, \ |
| 350 |
ID,CHTITLE,NX,XMI,XMA,VMX) |
| 351 |
: |
| 352 |
/* end hbook.h */ |
| 353 |
|
| 354 |
|
| 355 |
|
| 356 |
/* example.c */ |
| 357 |
#include "hbook.h" |
| 358 |
: |
| 359 |
typedef struct { |
| 360 |
int lines; |
| 361 |
int status[SIZE]; |
| 362 |
float p[SIZE]; /* momentum */ |
| 363 |
} FAKE_DEF; |
| 364 |
#define FAKE COMMON_BLOCK(FAKE,fake) |
| 365 |
COMMON_BLOCK_DEF(FAKE_DEF,FAKE); |
| 366 |
: |
| 367 |
main () |
| 368 |
{ |
| 369 |
: |
| 370 |
HBOOK1(1,"pT spectrum of pi+",100,0.,5.,0.); |
| 371 |
/* c.f. the call in FORTRAN: |
| 372 |
CALL HBOOK1(1,'pT spectrum of pi+',100,0.,5.,0.) |
| 373 |
*/ |
| 374 |
: |
| 375 |
FAKE.p[7]=1.0; |
| 376 |
: |
| 377 |
} |
| 378 |
</pre></font> |
| 379 |
|
| 380 |
<b>N.B.</b> |
| 381 |
<ol> |
| 382 |
<li> The routine is language independent. |
| 383 |
<li> <tt>hbook.h</tt> is machine independent. |
| 384 |
<li> Applications using routines via <tt>cfortran.h</tt> are machine independent. |
| 385 |
</ol> |
| 386 |
|
| 387 |
<h3>Example 2</h3> Many VMS System calls are most easily called from <i>FORTRAN</i>, but |
| 388 |
<tt>cfortran.h</tt> now gives that ease in C. |
| 389 |
<FONT COLOR="#993300"><pre> |
| 390 |
#include <cfortran.h> |
| 391 |
|
| 392 |
PROTOCCALLSFSUB3(LIB$SPAWN,lib$spawn,STRING,STRING,STRING) |
| 393 |
#define LIB$SPAWN(command,input_file,output_file) \ |
| 394 |
CCALLSFSUB3(LIB$SPAWN,lib$spawn,STRING,STRING,STRING, \ |
| 395 |
command,input_file,output_file) |
| 396 |
|
| 397 |
main () |
| 398 |
{ |
| 399 |
LIB$SPAWN("set term/width=132","",""); |
| 400 |
} |
| 401 |
</pre></font> |
| 402 |
Obviously the <tt>cfortran.h</tt> command above could be put into a header file along |
| 403 |
with the description of the other system calls, but as this example shows, it's |
| 404 |
not much hassle to set up <tt>cfortran.h</tt> for even a single call. |
| 405 |
|
| 406 |
|
| 407 |
<h3>Example 3</h3> <tt>cfortran.h</tt> and the source cstring.c create the cstring.obj library |
| 408 |
which gives <i>FORTRAN</i> access to all the functions in C's system |
| 409 |
library described by the system's C header file <tt>string.h</tt>. |
| 410 |
<FONT COLOR="#993300"><pre> |
| 411 |
C EXAMPLE.FOR |
| 412 |
PROGRAM EXAMPLE |
| 413 |
DIMENSION I(20), J(30) |
| 414 |
: |
| 415 |
CALL MEMCPY(I,J,7) |
| 416 |
: |
| 417 |
END |
| 418 |
|
| 419 |
/* cstring.c */ |
| 420 |
#include <string.h> /* string.h prototypes memcpy() */ |
| 421 |
#include <cfortran.h> |
| 422 |
|
| 423 |
: |
| 424 |
FCALLSCSUB3(memcpy,MEMCPY,memcpy,PVOID,PVOID,INT) |
| 425 |
: |
| 426 |
</pre></font> |
| 427 |
|
| 428 |
The simplicity exhibited in the above example exists for many but not all |
| 429 |
machines. |
| 430 |
<a href="cfortran.html#IIii4">Note 4. of Section II ii)</a> details the limitations and describes tools |
| 431 |
which try to maintain the best possible interface when <i>FORTRAN</i> calls C |
| 432 |
routines. |
| 433 |
|
| 434 |
|
| 435 |
<h2>II) Using cfortran.h</h2> |
| 436 |
|
| 437 |
The user is asked to look at the source files <tt>cfortest.c</tt> and |
| 438 |
<tt>cfortex.f</tt> |
| 439 |
for clarification by example. |
| 440 |
<p> |
| 441 |
|
| 442 |
<h3>o) Notes:</h3> |
| 443 |
|
| 444 |
<ul> |
| 445 |
<p><li> Specifying the <i>FORTRAN</i> compiler |
| 446 |
<p> |
| 447 |
<tt>cfortran.h</tt> generates interfaces for the default |
| 448 |
<i>FORTRAN</i> compiler. The default can be overridden by defining with |
| 449 |
one of the following methods, |
| 450 |
<ul> |
| 451 |
<p><li> in the code, e.g.: <tt>#define NAGf90Fortran</tt> |
| 452 |
<p><li> in the compile directive, e.g.: <tt>unix> cc -DNAGf90Fortran</tt> |
| 453 |
</ul> |
| 454 |
one of the following before including <tt>cfortran.h</tt>: |
| 455 |
<FONT COLOR="#993300"><pre> |
| 456 |
NAGf90Fortran f2cFortran hpuxFortran apolloFortran sunFortran |
| 457 |
IBMR2Fortran mipsFortran DECFortran vmsFortran |
| 458 |
CONVEXFortran PowerStationFortran AbsoftUNIXFortran |
| 459 |
SXFortran pgiFortran AbsoftProFortran |
| 460 |
</pre></font> |
| 461 |
This also allows crosscompilation. |
| 462 |
<p> |
| 463 |
If wanted, <tt>NAGf90Fortran</tt>, <tt>f2cFortran</tt>, <tt>DECFortran</tt>, <tt>AbsoftUNIXFortran</tt>, |
| 464 |
<tt>AbsoftProFortran</tt> and <tt>pgiFortran</tt> must be requested by the user. |
| 465 |
|
| 466 |
<p><li><tt>/**/</tt> |
| 467 |
<p> |
| 468 |
<tt>cfortran.h</tt> (ab)uses the comment kludge <tt>/**/</tt> when the |
| 469 |
ANSI C preprocessor |
| 470 |
catenation operator <tt>##</tt> doesn't exist. |
| 471 |
In at least MIPS C, this kludge is |
| 472 |
sensitive to blanks surrounding arguments to macros. |
| 473 |
Therefore, for applications using non-ANSI C compilers, the |
| 474 |
<tt>argtype_i</tt>, |
| 475 |
<tt>routine_name</tt>, |
| 476 |
<tt>routine_type</tt> |
| 477 |
and |
| 478 |
<tt>common_block_name arguments</tt> to the |
| 479 |
<tt>PROTOCCALLSFFUNn</tt>, <tt>CCALLSFSUB/FUNn</tt>, <tt>FCALLSCSUB/FUNn</tt> and <tt>COMMON_BLOCK</tt> macros |
| 480 |
<b> must not</b> be followed by any white space characters such as |
| 481 |
blanks, tabs or newlines. |
| 482 |
|
| 483 |
<p><li> <tt>LOGICAL</tt> |
| 484 |
<p> |
| 485 |
<i>FORTRAN</i> <tt>LOGICAL</tt> values of .TRUE. and .FALSE. do not agree with the C |
| 486 |
representation of TRUE and FALSE on all machines. <tt>cfortran.h</tt> does the |
| 487 |
conversion for <tt>LOGICAL</tt> and PLOGICAL arguments and for functions returning |
| 488 |
<tt>LOGICAL</tt>. Users must convert arrays of <tt>LOGICAL</tt>s from C to <i>FORTRAN</i> with the |
| 489 |
C2FLOGICALV(array_name, elements_in_array); macro. Similarly, arrays of <tt>LOGICAL</tt> |
| 490 |
values may be converted from the <i>FORTRAN</i> into C representation by using |
| 491 |
F2CLOGICALV(array_name, elements_in_array); |
| 492 |
<p> |
| 493 |
When C passes or returns <tt>LOGICAL</tt> values to <i>FORTRAN</i>, by default <tt>cfortran.h</tt> |
| 494 |
only makes the minimal changes required to the value. [e.g. Set/Unset the |
| 495 |
single relevant bit or do nothing for <i>FORTRAN</i> compilers which use 0 as FALSE |
| 496 |
and treat all other values as TRUE.] Therefore <tt>cfortran.h</tt> will pass <tt>LOGICAL</tt>s |
| 497 |
to <i>FORTRAN</i> which do not have an identical representation to .TRUE. or .FALSE. |
| 498 |
This is fine except for abuses of <i>FORTRAN</i>/77 in the style of: |
| 499 |
<FONT COLOR="#993300"><pre> |
| 500 |
logical l |
| 501 |
if (l .eq. .TRUE.) ! (1) |
| 502 |
</pre></font> |
| 503 |
instead of the correct: |
| 504 |
<FONT COLOR="#993300"><pre> |
| 505 |
if (l .eqv. .TRUE.) ! (2) |
| 506 |
</pre></font> |
| 507 |
or: |
| 508 |
<FONT COLOR="#993300"><pre> |
| 509 |
if (l) ! (3) |
| 510 |
</pre></font> |
| 511 |
For <i>FORTRAN</i> code which treats <tt>LOGICAL</tt>s from C in the method of (1), |
| 512 |
<tt>LOGICAL_STRICT</tt> must be defined before |
| 513 |
including <tt>cfortran.h</tt>, either in the |
| 514 |
code, <tt>"#define LOGICAL_STRICT"</tt>, or compile with |
| 515 |
<tt>"cc -DLOGICAL_STRICT"</tt>. |
| 516 |
There is no reason to use <tt>LOGICAL_STRICT</tt> for <i>FORTRAN</i> |
| 517 |
code which does not do (1). |
| 518 |
At least the IBM's <tt>xlf</tt> and the Apollo's <tt>f77</tt> |
| 519 |
do not even allow code along the |
| 520 |
lines of (1). |
| 521 |
<p> |
| 522 |
DECstations' <tt>DECFortran</tt> and MIPS <i>FORTRAN</i> compilers use |
| 523 |
different internal |
| 524 |
representations for <tt>LOGICAL</tt> values. |
| 525 |
[Both compilers are usually called <tt>f77</tt>, |
| 526 |
although when both are installed on a single machine the MIPS' one is usually |
| 527 |
renamed. (e.g. <tt>f77</tt>2.1 for version 2.10.)] <tt>cc</tt> doesn't know |
| 528 |
which <i>FORTRAN</i> |
| 529 |
compiler is present, so <tt>cfortran.h</tt> assumes MIPS <tt>f77</tt>. |
| 530 |
To use <tt>cc</tt> with DECFortran |
| 531 |
define the preprocessor constant 'DECFortran'. |
| 532 |
e.g. |
| 533 |
<FONT COLOR="#993300"><pre> |
| 534 |
<b>i) </b> cc -DDECFortran -c the_code.c |
| 535 |
</pre></font> |
| 536 |
or |
| 537 |
<FONT COLOR="#993300"><pre> |
| 538 |
<b>ii)</b> #define DECFortran /* in the C code or add to <tt>cfortran.h</tt>. */ |
| 539 |
</pre></font> |
| 540 |
|
| 541 |
MIPS <tt>f77</tt> [SGI and DECstations], <tt>f2c</tt>. Therefore, |
| 542 |
for these compilers, <tt>LOGICAL_STRICT</tt> is |
| 543 |
defined by default in <tt>cfortran.h</tt>. |
| 544 |
[The Sun and HP compilers have not been |
| 545 |
tested, so they may also require <tt>LOGICAL_STRICT</tt> as the default.] |
| 546 |
|
| 547 |
<p><li> <tt>SHORT</tt> and <tt>BYTE</tt> |
| 548 |
<p> |
| 549 |
They are irrelevant for the CRAY where <i>FORTRAN</i> |
| 550 |
has no equivalent to C's <tt>short</tt>. |
| 551 |
Similarly <tt>BYTE</tt> is irrelevant for <tt>f2c</tt>. The |
| 552 |
author has tested SHORT and BYTE with a modified cfortest.c/cfortex.f on all |
| 553 |
machines supported except for the HP9000 and the Sun. |
| 554 |
<p> |
| 555 |
<tt>BYTE</tt> is a signed 8-bit quantity, i.e. values are -128 to 127, |
| 556 |
on all machines |
| 557 |
except for the SGI [at least for MIPS Computer Systems 2.0.] On the SGI it is |
| 558 |
an unsigned 8-bit quantity, i.e. values are 0 to 255, although the SGI '<i>FORTRAN</i> |
| 559 |
77 Programmers Guide' claims BYTE is signed. Perhaps MIPS 2.0 is dated, since |
| 560 |
the DECstations using MIPS 2.10 <tt>f77</tt> have a signed <tt>BYTE</tt>. |
| 561 |
<p> |
| 562 |
To minimize the difficulties of signed and unsigned |
| 563 |
<tt>BYTE</tt>, <tt>cfortran.h</tt> creates |
| 564 |
the type '<tt>INTEGER_BYTE</tt>' to agree with <i>FORTRAN</i>'s |
| 565 |
<tt>BYTE</tt>. Users may define |
| 566 |
<tt>SIGNED_BYTE</tt> or |
| 567 |
<tt>UNSIGNED_BYTE</tt>, before including <tt>cfortran.h</tt>, |
| 568 |
to specify <i>FORTRAN</i>'s |
| 569 |
<tt>BYTE</tt>. If neither is defined, <tt>cfortran.h</tt> assumes |
| 570 |
<tt>SIGNED_BYTE</tt>. |
| 571 |
|
| 572 |
<p><li> <tt>f2c / g77</tt> |
| 573 |
<p> |
| 574 |
<tt>f2c</tt> and <tt>g77</tt> by default promote <tt>REAL</tt> functions to |
| 575 |
double. As of December 9, 2005, the Debian package of cfortran supports this |
| 576 |
behavior, so the <tt>f2c -R</tt> option must <b>NOT</b> be used to turn this |
| 577 |
promotion off. |
| 578 |
|
| 579 |
<p><li> <tt>f2c</tt> |
| 580 |
<p>[Thanks to Dario Autiero for pointing out the following.] |
| 581 |
<tt>f2c</tt> has a strange feature in that either one or two underscores are appended |
| 582 |
to a <i>FORTRAN</i> name of a routine or common block, |
| 583 |
depending on whether or not the original name contains an underscore. |
| 584 |
<b><pre> |
| 585 |
S.I. Feldman et al., "A <i>FORTRAN</i> to C converter", |
| 586 |
Computing Science Technical Report No. 149. |
| 587 |
|
| 588 |
page 2, chapter 2: INTERLANGUAGE conventions |
| 589 |
........... |
| 590 |
</pre></b> |
| 591 |
To avoid conflict with the names of library routines and with names that |
| 592 |
<tt>f2c</tt> generates, |
| 593 |
<i>FORTRAN</i> names may have one or two underscores appended. |
| 594 |
<i>FORTRAN</i> names are |
| 595 |
forced to lower case (unless the -U option described in Appendix B is in |
| 596 |
effect); external names, i.e. the names of <i>FORTRAN</i> procedures |
| 597 |
and common |
| 598 |
blocks, have a single underscore appended if they do not contain any |
| 599 |
underscore and have a pair of underscores appended if they do contain |
| 600 |
underscores. Thus <i>FORTRAN</i> subroutines names <tt>ABC</tt>, |
| 601 |
<tt>A_B_C</tt> and <tt>A_B_C_</tt> result |
| 602 |
in C functions named <tt>abc</tt>_, <tt>a_b_c__</tt> and <tt>a_b_c___</tt>. |
| 603 |
<p> |
| 604 |
|
| 605 |
<tt>cfortran.h</tt> is unable to change the naming convention on a name by name basis. |
| 606 |
<i>FORTRAN</i> routine and common block names which do not contain an underscore |
| 607 |
are unaffected by this feature. |
| 608 |
Names which do contain an underscore may use the following work-around: |
| 609 |
|
| 610 |
<FONT COLOR="#993300"><pre> |
| 611 |
/* First 2 lines are a completely standard <tt>cfortran.h</tt> interface |
| 612 |
to the <i>FORTRAN</i> routine E_ASY . */ |
| 613 |
PROTOCCALLSFSUB2(E_ASY,e_asy, PINT, INT) |
| 614 |
#define E_ASY(A,B) CCALLSFSUB2(E_ASY,e_asy, PINT, INT, A, B) |
| 615 |
#ifdef f2cFortran |
| 616 |
#define e_asy_ e_asy__ |
| 617 |
#endif |
| 618 |
/* Last three lines are a work-around for the strange f2c naming feature. */ |
| 619 |
</pre></font> |
| 620 |
|
| 621 |
<p><li> <tt>gfortran</tt> |
| 622 |
<p> |
| 623 |
<tt>gfortran</tt> behaves similarly to <tt>f2c</tt> and <tt>g77</tt>, EXCEPT |
| 624 |
that it does NOT by default promote <tt>REAL</tt> functions to |
| 625 |
double. Therefore you should use <tt>-DgFortran</tt> instead of |
| 626 |
<tt>-Dg77Fortran</tt> or <tt>-Df2cFortran</tt> to let <tt>cfortran.h</tt> |
| 627 |
know about this difference. |
| 628 |
|
| 629 |
<p><li> NAG f90 |
| 630 |
<p> The <i>FORTRAN</i> 77 subset of <i>FORTRAN</i> 90 is supported. |
| 631 |
Extending <tt>cfortran.h</tt> to |
| 632 |
interface C with all of <i>FORTRAN</i> 90 has not yet been examined. |
| 633 |
<br> The NAG f90 library hijacks the <tt>main()</tt> of any program and starts the user's |
| 634 |
program with a call to: <tt>void f90_main(void)</tt>;<br> |
| 635 |
While this in itself is only a minor hassle, a major problem arises because |
| 636 |
NAG f90 provides no mechanism to access command line arguments.<br> |
| 637 |
At least version 'NAGWare f90 compiler Version 1.1(334)' appended _CB to |
| 638 |
common block names instead of the usual <tt>_</tt>. |
| 639 |
To fix, add this to <tt>cfortran.h</tt>: |
| 640 |
<FONT COLOR="#993300"><pre> |
| 641 |
#ifdef old_NAG_f90_CB_COMMON |
| 642 |
#define COMMON_BLOCK CFC_ /* for all other Fortran compilers */ |
| 643 |
#else |
| 644 |
#define COMMON_BLOCK(UN,LN) _(LN,_CB) |
| 645 |
#endif |
| 646 |
</pre></font> |
| 647 |
|
| 648 |
<p><li> RS/6000 |
| 649 |
<p> Using <tt>"xlf -qextname ..."</tt>, which appends an underscore, <tt>'_'</tt>, |
| 650 |
to all <i>FORTRAN</i> |
| 651 |
external references, requires <tt>"cc -Dextname ..."</tt> so that |
| 652 |
<tt>cfortran.h</tt> also |
| 653 |
generates these underscores. |
| 654 |
Use i<tt>-Dextname=extname</tt> if <tt>extname</tt> is a symbol used in |
| 655 |
the C code. |
| 656 |
The use of <tt>"xlf -qextname"</tt> is <b>strongly encouraged</b>, since it |
| 657 |
allows for |
| 658 |
transparent naming schemes when mixing C and <i>FORTRAN</i>. |
| 659 |
|
| 660 |
<p><li> <a name="SIIoHP9000">HP9000</a> |
| 661 |
<p> Using <tt>"f77 +ppu ..."</tt>, which appends an underscore, |
| 662 |
<tt>'_'</tt>, to all <i>FORTRAN</i> |
| 663 |
external references, requires <tt>"cc -Dextname ..."</tt> so |
| 664 |
that <tt>cfortran.h</tt> also |
| 665 |
generates these underscores. |
| 666 |
Use <tt>-Dextname=extname</tt> if extname is a symbol used in the C code. |
| 667 |
The use of <tt>"f77 +ppu"</tt> is <b>strongly encouraged</b>, since it allows |
| 668 |
for |
| 669 |
transparent naming schemes when mixing C and <i>FORTRAN</i>. |
| 670 |
<p> |
| 671 |
At least one release of the HP <tt>/lib/cpp.ansi</tt> |
| 672 |
preprocessor is broken and will |
| 673 |
go into an infinite loop when trying to process <tt>cfortran.h</tt> with the |
| 674 |
<tt>##</tt> catenation operator. The K&R version of <tt>cfortran.h</tt> must then be used and the |
| 675 |
K&R preprocessor must be specified. e.g. |
| 676 |
<FONT COLOR="#993300"><pre> |
| 677 |
HP9000> cc -Aa -tp,/lib/cpp -c source.c |
| 678 |
</pre></font> |
| 679 |
The same problem with a similar solution exists on the Apollo. |
| 680 |
An irrelevant error message <tt>'0: extraneous name /usr/include'</tt> |
| 681 |
will appear for |
| 682 |
each source file due to another HP bug, and can be safely ignored. |
| 683 |
e.g. |
| 684 |
<FONT COLOR="#993300"><pre> |
| 685 |
cc -v -c -Aa -tp,/lib/cpp cfortest.c |
| 686 |
</pre></font> |
| 687 |
|
| 688 |
will show that the driver passes |
| 689 |
<tt>'-I /usr/include'</tt> instead of <tt>'-I/usr/include'</tt> to |
| 690 |
<tt>/lib/cpp</tt> |
| 691 |
<p> |
| 692 |
On some machines the above error causes compilation to stop; one must then use |
| 693 |
K&R C, as with old HP compilers which don't support function prototyping. |
| 694 |
<tt>cfortran.h</tt> has to be informed that K&R C is to being used, e.g. |
| 695 |
<FONT COLOR="#993300"><pre> |
| 696 |
HP9000> cc -D__CF__KnR -c source.c |
| 697 |
</pre></font> |
| 698 |
|
| 699 |
<p><li> AbsoftUNIXFortran |
| 700 |
<p> |
| 701 |
By default, <tt>cfortran.h</tt> follows the default AbsoftUNIX/ProFortran |
| 702 |
and prepends <tt>_C</tt> |
| 703 |
to each common block name. To override the <tt>cfortran.h</tt> behavior |
| 704 |
<tt>#define COMMON_BLOCK(UN,LN)</tt> before including <tt>cfortran.h</tt>. |
| 705 |
[Search for <tt>COMMON_BLOCK</tt> in <tt>cfortran.h</tt> for examples.] |
| 706 |
|
| 707 |
<p><li> <a name="SIIoApollo">Apollo</a> |
| 708 |
<p> |
| 709 |
On at least one release, 'C compiler 68K Rev6.8(168)', the default C |
| 710 |
preprocessor, from cc -A xansi or cc -A ansi, enters an infinite loop when |
| 711 |
using <tt>cfortran.h</tt>. This Apollo bug can be circumvented by using: |
| 712 |
<ul> |
| 713 |
<p><li> <tt>cc -DANSI_C_preprocessor=0</tt> to force use of |
| 714 |
<tt>/**/</tt>, instead of <tt>'##'</tt>. |
| 715 |
<p><b>AND</b> |
| 716 |
<p><li> The pre-ANSI preprocessor, i.e. use <tt>cc -Yp,/usr/lib</tt> |
| 717 |
</ul> |
| 718 |
<p>The same problem with a similar solution exists on the HP. |
| 719 |
|
| 720 |
<p><li> <a name="SIIoSun">Sun</a> |
| 721 |
<p>Old versions of cc(1), say <~1986, may require help for <tt>cfortran.h</tt> |
| 722 |
applications: |
| 723 |
<ul> |
| 724 |
<p><li> <tt>#pragma</tt> may not be understood, hence <tt>cfortran.h</tt> |
| 725 |
and <tt>cfortest.c</tt> may require |
| 726 |
<FONT COLOR="#993300"><pre> |
| 727 |
sun> mv <tt>cfortran.h</tt> cftmp.h && grep -v "^#pragma" <cftmp.h >cfortran.h |
| 728 |
sun> mv cfortest.c cftmp.c && grep -v "^#pragma" <cftmp.c >cfortest.c |
| 729 |
</pre></font> |
| 730 |
<p><li> Old copies of <tt>math.h</tt> may not include the following from a newer <tt>math.h</tt>. |
| 731 |
[For an ancient <tt>math.h</tt> on a 386 or sparc, get similar from a new <tt>math.h</tt>.] |
| 732 |
</ul> |
| 733 |
<FONT COLOR="#993300"><pre> |
| 734 |
#ifdef mc68000 /* 5 lines Copyright (c) 1988 by Sun Microsystems, Inc. */ |
| 735 |
#define FLOATFUNCTIONTYPE int |
| 736 |
#define RETURNFLOAT(x) return (*(int *)(&(x))) |
| 737 |
#define ASSIGNFLOAT(x,y) *(int *)(&x) = y |
| 738 |
#endif |
| 739 |
</pre></font> |
| 740 |
|
| 741 |
<p><li> Mips compilers |
| 742 |
<p> |
| 743 |
e.g. DECstations and SGI, require applications with a C main() and calls to |
| 744 |
GETARG(3F), i.e. <i>FORTRAN</i> routines returning the command line arguments, to use |
| 745 |
two macros as shown: |
| 746 |
<FONT COLOR="#993300"><pre> |
| 747 |
: |
| 748 |
CF_DECLARE_GETARG; /* This must be external to all routines. */ |
| 749 |
: |
| 750 |
main(int argc, char *argv[]) |
| 751 |
{ |
| 752 |
: |
| 753 |
CF_SET_GETARG(argc,argv); /* This must precede any calls to GETARG(3F). */ |
| 754 |
: |
| 755 |
} |
| 756 |
</pre></font> |
| 757 |
The macros are null and benign on all other systems. Sun's <tt>GETARG(3F)</tt> |
| 758 |
also |
| 759 |
doesn't work with a generic C <tt>main()</tt> |
| 760 |
and perhaps a workaround similar to the |
| 761 |
Mips' one exists. |
| 762 |
|
| 763 |
<p><li> Alpha/OSF |
| 764 |
<p>Using the DEC <i>FORTRAN</i> and the DEC C compilers of |
| 765 |
DEC OSF/1 [RT] V1.2 (Rev. 10), |
| 766 |
<i>FORTRAN</i>, when called from C, has occasional trouble using a routine received as |
| 767 |
a dummy argument. |
| 768 |
|
| 769 |
e.g. In the following the <i>FORTRAN</i> routine 'e' will crash when it tries to use |
| 770 |
the C routine 'c' or the <i>FORTRAN</i> routine 'f'. |
| 771 |
The example works on other systems. |
| 772 |
|
| 773 |
<FONT COLOR="#993300"><pre> |
| 774 |
C FORTRAN /* C */ |
| 775 |
integer function f() #include <stdio.h> |
| 776 |
f = 2 int f_(); |
| 777 |
return int e_(int (*u)()); |
| 778 |
end |
| 779 |
int c(){ return 1;} |
| 780 |
integer function e(u) int d (int (*u)()) { return u();} |
| 781 |
integer u |
| 782 |
external u main() |
| 783 |
e=u() { /* Calls to d work. */ |
| 784 |
return printf("d (c ) returns %d.\n",d (c )); |
| 785 |
end printf("d (f_) returns %d.\n",d (f_)); |
| 786 |
/* Calls to e_ crash. */ |
| 787 |
printf("e_(c ) returns %d.\n",e_(c )); |
| 788 |
printf("e_(f_) returns %d.\n",e_(f_)); |
| 789 |
} |
| 790 |
</pre></font> |
| 791 |
|
| 792 |
Solutions to the problem are welcomed! |
| 793 |
A kludge which allows the above example to work correctly, requires an extra |
| 794 |
argument to be given when calling the dummy argument function. |
| 795 |
i.e. Replacing <tt>'e=u()'</tt> by <tt>'e=u(1)'</tt> |
| 796 |
allows the above example to work. |
| 797 |
|
| 798 |
|
| 799 |
<p><li> The <i>FORTRAN</i> routines are called using macro expansions, therefore the usual |
| 800 |
caveats for expressions in arguments apply. The expressions to the routines may |
| 801 |
be evaluated more than once, leading to lower performance and in the worst case |
| 802 |
bizarre bugs. |
| 803 |
|
| 804 |
<p><li> For those who wish to use <tt>cfortran.h</tt> in large applications. |
| 805 |
<a href="cfortran.html#IV">[See Section IV.]</a> |
| 806 |
This release is intended to make it easy to get applications up and running. |
| 807 |
This implies that applications are not as efficient as they could be: |
| 808 |
<ul> |
| 809 |
<p><li> The current mechanism is inefficient if a single header file is used to |
| 810 |
describe a large library of <i>FORTRAN</i> functions. Code for a static wrapper fn. |
| 811 |
is generated in each piece of C source code for each <i>FORTRAN</i> function |
| 812 |
specified with the <tt>CCALLSFFUNn</tt> statement, irrespective of whether or not the |
| 813 |
function is ever called. |
| 814 |
<p><li> Code for several static utility routines internal to <tt>cfortran.h</tt> is placed |
| 815 |
into any source code which <tt>#includes cfortran.h</tt>. These routines should |
| 816 |
probably be in a library. |
| 817 |
</ul> |
| 818 |
</ul> |
| 819 |
|
| 820 |
<h3>i) Calling <i>FORTRAN</i> routines from C:</h3> |
| 821 |
|
| 822 |
The <i>FORTRAN</i> routines are defined by one of the following two instructions: |
| 823 |
<p> |
| 824 |
for a SUBROUTINE: |
| 825 |
<FONT COLOR="#993300"><pre> |
| 826 |
/* PROTOCCALLSFSUBn is optional for C, but mandatory for C++. */ |
| 827 |
PROTOCCALLSFSUBn(ROUTINE_NAME,routine_name,argtype_1,...,argtype_n) |
| 828 |
#define Routine_name(argname_1,..,argname_n) \ |
| 829 |
CCALLSFSUBn(ROUTINE_NAME,routine_name,argtype_1,...,argtype_n, \ |
| 830 |
argname_1,..,argname_n) |
| 831 |
</pre></font> |
| 832 |
|
| 833 |
for a FUNCTION: |
| 834 |
<FONT COLOR="#993300"><pre> |
| 835 |
PROTOCCALLSFFUNn(routine_type,ROUTINE_NAME,routine_name,argtype_1,...,argtype_n) |
| 836 |
#define Routine_name(argname_1,..,argname_n) \ |
| 837 |
CCALLSFFUNn(ROUTINE_NAME,routine_name,argtype_1,...,argtype_n, \ |
| 838 |
argname_1,..,argname_n) |
| 839 |
</pre></font> |
| 840 |
Where: |
| 841 |
<FONT COLOR="#993300"><pre> |
| 842 |
'n' = 0->14 [SUBROUTINE's ->27] (easily expanded in <tt>cfortran.h</tt> to > 14 [27]) is |
| 843 |
the number of arguments to the routine. |
| 844 |
Routine_name = C name of the routine (IN UPPER CASE LETTERS).[see 2.below] |
| 845 |
ROUTINE_NAME = <i>FORTRAN</i> name of the routine (IN UPPER CASE LETTERS). |
| 846 |
routine_name = <i>FORTRAN</i> name of the routine (IN lower case LETTERS). |
| 847 |
routine_type = the type of argument returned by <i>FORTRAN</i> functions. |
| 848 |
= BYTE, DOUBLE, FLOAT, INT, LOGICAL, LONG, LONGLONG, SHORT, STRING, VOID. |
| 849 |
[Instead of VOID one would usually use CCALLSFSUBn. |
| 850 |
VOID forces a wrapper function to be used.] |
| 851 |
argtype_i = the type of argument passed to the <i>FORTRAN</i> routine and must be |
| 852 |
consistent in the definition and prototyping of the routine s.a. |
| 853 |
= BYTE, DOUBLE, FLOAT, INT, LOGICAL, LONG, LONGLONG, SHORT, STRING. |
| 854 |
For vectors, i.e. 1 dim. arrays use |
| 855 |
= BYTEV, DOUBLEV, FLOATV, INTV, LOGICALV, LONGV, LONGLONGV, SHORTV, |
| 856 |
STRINGV, ZTRINGV. |
| 857 |
For vectors of vectors, i.e. 2 dim. arrays use |
| 858 |
= BYTEVV, DOUBLEVV, FLOATVV, INTVV, LOGICALVV, LONGVV, LONGLONGVV, SHORTVV. |
| 859 |
For n-dim. arrays, 1<=n<=7 [7 is the maximum in <i>FORTRAN</i> 77], |
| 860 |
= BYTEV..nV's..V, DOUBLEV..V, FLOATV..V, INTV..V, LOGICALV..V, |
| 861 |
LONGV..V, SHORTV..V, LONGV..V. |
| 862 |
N.B. Array dimensions and types are checked by the C compiler. |
| 863 |
For routines changing the values of an argument, the keyword is |
| 864 |
prepended by a 'P'. |
| 865 |
= PBYTE, PDOUBLE, PFLOAT, PINT, PLOGICAL, PLONG, PSHORT, PLONGLONG |
| 866 |
PSTRING, PSTRINGV, PZTRINGV. |
| 867 |
For EXTERNAL procedures passed as arguments use |
| 868 |
= ROUTINE. |
| 869 |
For exceptional arguments which require no massaging to fit the |
| 870 |
argument passing mechanisms use |
| 871 |
= PVOID. |
| 872 |
The argument is cast and passed as (void *). |
| 873 |
Although PVOID could be used to describe all array arguments on |
| 874 |
most (all?) machines , it shouldn't be because the C compiler |
| 875 |
can no longer check the type and dimension of the array. |
| 876 |
argname_i = any valid unique C tag, but must be consistent in the definition |
| 877 |
as shown. |
| 878 |
</pre></font> |
| 879 |
|
| 880 |
Notes: |
| 881 |
<ol> |
| 882 |
<p><li> <tt>cfortran.h</tt> may be expanded to handle a more argument type. To suppport new |
| 883 |
arguments requiring complicated massaging when passed between <i>FORTRAN</i> and C, |
| 884 |
the user will have to understand <tt>cfortran.h</tt> and follow its code and mechanisms. |
| 885 |
<p> |
| 886 |
To define types requiring little or no massaging when passed between <i>FORTRAN</i> |
| 887 |
and C, the pseudo argument type <tt>SIMPLE</tt> may be used. |
| 888 |
For a user defined type called 'newtype', the definitions required are: |
| 889 |
|
| 890 |
<FONT COLOR="#993300"><pre> |
| 891 |
/* The following 7 lines are required verbatim. |
| 892 |
'newtype' is the name of the new user defined argument type. |
| 893 |
*/ |
| 894 |
#define newtype_cfV( T,A,B,F) SIMPLE_cfV(T,A,B,F) |
| 895 |
#define newtype_cfSEP(T, B) SIMPLE_cfSEP(T,B) |
| 896 |
#define newtype_cfINT(N,A,B,X,Y,Z) SIMPLE_cfINT(N,A,B,X,Y,Z) |
| 897 |
#define newtype_cfSTR(N,T,A,B,C,D,E) SIMPLE_cfSTR(N,T,A,B,C,D,E) |
| 898 |
#define newtype_cfCC( T,A,B) SIMPLE_cfCC(T,A,B) |
| 899 |
#define newtype_cfAA( T,A,B) newtype_cfB(T,A) /* Argument B not used. */ |
| 900 |
#define newtype_cfU( T,A) newtype_cfN(T,A) |
| 901 |
|
| 902 |
/* 'parameter_type(A)' is a declaration for 'A' and describes the type of the |
| 903 |
parameter expected by the <i>FORTRAN</i> function. This type will be used in the |
| 904 |
prototype for the function, if using ANSI C, and to declare the argument used |
| 905 |
by the intermediate function if calling a <i>FORTRAN</i> FUNCTION. |
| 906 |
Valid 'parameter_type(A)' include: int A |
| 907 |
void (*A)() |
| 908 |
double A[17] |
| 909 |
*/ |
| 910 |
#define newtype_cfN( T,A) parameter_type(A) /* Argument T not used. */ |
| 911 |
|
| 912 |
/* Before any argument of the new type is passed to the <i>FORTRAN</i> routine, it may |
| 913 |
be massaged as given by 'massage(A)'. |
| 914 |
*/ |
| 915 |
#define newtype_cfB( T,A) massage(A) /* Argument T not used. */ |
| 916 |
|
| 917 |
An example of a simple user defined type is given cfortex.f and cfortest.c. |
| 918 |
Two uses of SIMPLE user defined types are [don't show the 7 verbatim #defines]: |
| 919 |
|
| 920 |
/* Pass the address of a structure, using a type called PSTRUCT */ |
| 921 |
#define PSTRUCT_cfN( T,A) void *A |
| 922 |
#define PSTRUCT_cfB( T,A) (void *) &(A) |
| 923 |
|
| 924 |
/* Pass an integer by value, (not standard F77 ), using a type called INTVAL */ |
| 925 |
#define INTVAL_cfN( T,A) int A |
| 926 |
#define INTVAL_cfB( T,A) (A) |
| 927 |
</pre></font> |
| 928 |
|
| 929 |
Upgrades to <tt>cfortran.h</tt> try to be, and have been, backwards compatible. This |
| 930 |
compatibility cannot be offered to user defined types. <tt>SIMPLE</tt> user defined |
| 931 |
types are less of a risk since they require so little effort in their creation. |
| 932 |
If a user defined type is required in more than one C header file of interfaces |
| 933 |
to libraries of <i>FORTRAN</i> routines, good programming practice, and ease of code |
| 934 |
maintenance, suggests keeping any user defined type within a single file which |
| 935 |
is #included as required. To date, changes to the <tt>SIMPLE</tt> macros were introduced |
| 936 |
in versions 2.6, 3.0 and 3.2 of <tt>cfortran.h</tt>. |
| 937 |
|
| 938 |
<a name="IIi2"></a> |
| 939 |
<p><li> <tt>Routine_name</tt> is the name of the macro which the C programmer will use in |
| 940 |
order to call a <i>FORTRAN</i> routine. In theory <tt>Routine_name</tt> could be any valid and |
| 941 |
unique name, but in practice, the name of the <i>FORTRAN</i> routine in UPPER CASE |
| 942 |
works everywhere and would seem to be an obvious choice. |
| 943 |
|
| 944 |
<p><li> <tt>[BYTE|DOUBLE|FLOAT|INT|LOGICAL|LONG|SHORT|LONGLONG][V|VV|VVV|...]</tt> |
| 945 |
<p> |
| 946 |
<tt>cfortran.h</tt> encourages the exact specification of the type and dimension of |
| 947 |
array parameters because it allows the C compiler to detect errors in the |
| 948 |
arguments when calling the routine. |
| 949 |
<p> |
| 950 |
<tt>cfortran.h</tt> does not strictly require the exact specification since the argument |
| 951 |
is merely the address of the array and is passed on to the calling routine. |
| 952 |
Any array parameter could be declared as <tt>PVOID</tt>, but this circumvents |
| 953 |
C's compiletime ability to check the correctness of arguments and is therefore |
| 954 |
discouraged. |
| 955 |
<p> |
| 956 |
Passing the address of these arguments implies that <tt>PBYTEV</tt>, <tt>PFLOATV</tt>, ... , |
| 957 |
<tt>PDOUBLEVV</tt>, ... don't exist in <tt>cfortran.h</tt>, since by default the routine and the |
| 958 |
calling code share the same array, i.e. the same values at the same memory |
| 959 |
location. |
| 960 |
<p> |
| 961 |
These comments do NOT apply to arrays of <tt>(P)S/ZTRINGV</tt>. For these parameters, |
| 962 |
<tt>cfortran.h</tt> passes a massaged copy of the array to the routine. When the routine |
| 963 |
returns, <tt>S/ZTRINGV</tt> ignores the copy, while <tt>PS/ZTRINGV</tt> replaces the calling |
| 964 |
code's original array with copy, which may have been modified by the called |
| 965 |
routine. |
| 966 |
|
| 967 |
|
| 968 |
<p><li> <tt>(P)STRING(V)</tt>: |
| 969 |
<ul> |
| 970 |
<p><li><tt>STRING</tt> |
| 971 |
<p> If the argument is a fixed length character array, e.g. char ar[8];, |
| 972 |
the string is blank, ' ', padded on the right to fill out the array before |
| 973 |
being passed to the <i>FORTRAN</i> routine. The useful size of the string is the same |
| 974 |
in both languages, e.g. ar[8] is passed as character*7. If the argument is a |
| 975 |
pointer, the string cannot be blank padded, so the length is passed as |
| 976 |
strlen(argument). On return from the <i>FORTRAN</i> routine, pointer arguments are not |
| 977 |
disturbed, but arrays have the terminating '\0' replaced to its original |
| 978 |
position. i.e. The padding blanks are never visible to the C code. |
| 979 |
|
| 980 |
<p><li><tt>PSTRING</tt> |
| 981 |
<p> The argument is massaged as with STRING before being passed to the |
| 982 |
<i>FORTRAN</i> routine. On return, the argument has all trailing blanks removed, |
| 983 |
regardless of whether the argument was a pointer or an array. |
| 984 |
|
| 985 |
<p><li><tt>(P)STRINGV</tt> |
| 986 |
<p> Passes a 1- or 2-dimensional char array. e.g. <tt>char a[7],b[6][8];</tt> |
| 987 |
<tt>STRINGV</tt> may thus also pass a string constant, e.g. <tt>"hiho"</tt>. |
| 988 |
<tt>(P)STRINGV</tt> does NOT pass a pointer, e.g. <tt>char *</tt>, to either a 1- or a |
| 989 |
2-dimensional array, since it cannot determine the array dimensions. |
| 990 |
A pointer can only be passed using <tt>(P)ZTRINGV</tt>. |
| 991 |
<p>N.B. If a C routine receives a character array argument, e.g. <tt>char a[2][3]</tt>, |
| 992 |
such an argument is actually a pointer and my thus not be passed by |
| 993 |
<tt>(P)STRINGV</tt>. Instead <tt>(P)ZTRINGV</tt> must be used. |
| 994 |
|
| 995 |
<p><li><tt>STRINGV</tt> |
| 996 |
<p> The elements of the argument are copied into space malloc'd, and |
| 997 |
each element is padded with blanks. The useful size of each element is the same |
| 998 |
in both languages. Therefore <tt>char bb[6][8];</tt> is equivalent to <tt>character*7 bb(6)</tt>. |
| 999 |
On return from the routine the malloc'd space is simply released. |
| 1000 |
|
| 1001 |
<p><li><tt>PSTRINGV</tt> |
| 1002 |
<p> Since <i>FORTRAN</i> has no trailing <tt>'\0'</tt>, elements in an array of |
| 1003 |
strings are contiguous. Therefore each element of the C array is padded with |
| 1004 |
blanks and strip out C's trailing <tt>'\0'</tt>. After returning from the routine, the |
| 1005 |
trailing <tt>'\0'</tt> is reinserted and kill the trailing blanks in each element. |
| 1006 |
</ul> |
| 1007 |
|
| 1008 |
<p><b>Summary</b>: <tt>STRING(V)</tt> arguments are blank padded during the call to the <i>FORTRAN</i> |
| 1009 |
routine, but remain original in the C code. <tt>(P)STRINGV</tt> arguments are blank |
| 1010 |
padded for the <i>FORTRAN</i> call, and after returning from <i>FORTRAN</i> trailing blanks |
| 1011 |
are stripped off. |
| 1012 |
|
| 1013 |
<p><li><tt>(P)ZTRINGV</tt>: |
| 1014 |
|
| 1015 |
<ul> |
| 1016 |
<p><li> <tt>(P)ZTRINGV</tt> - is identical to <tt>(P)STRINGV</tt>, |
| 1017 |
except that the dimensions of the array of strings is explicitly specified, |
| 1018 |
which thus also allows a pointer to be passed. |
| 1019 |
<tt>(P)ZTRINGV</tt> can thus pass a 1- or 2-dimensional <tt>char</tt> array, e.g. |
| 1020 |
<tt>char b[6][8]</tt>, |
| 1021 |
or it can pass a pointer to such an array, e.g. <tt>char *p;</tt>. |
| 1022 |
<tt>ZTRINGV</tt> may thus also pass a string constant, e.g. <tt>"hiho"</tt>. |
| 1023 |
If passing a 1-dimensional array, <tt>routine_name_ELEMS_j</tt> (see below) must be 1. |
| 1024 |
[Users of <tt>(P)ZTRINGV</tt> should examine <tt>cfortest.c</tt> for examples.]: |
| 1025 |
|
| 1026 |
<p><li> <tt>(P)ZTRINGV</tt> must thus be used instead of <tt>(P)STRINGV</tt> whenever |
| 1027 |
<tt>sizeof()</tt> |
| 1028 |
can't be used to determine the dimensions of the array of string or strings. |
| 1029 |
e.g. when calling <i>FORTRAN</i> from C with a <tt>char *</tt> received by C as an argument. |
| 1030 |
|
| 1031 |
<p><li> There is no <tt>(P)ZTRING</tt> type, since <tt>(P)ZTRINGV</tt> can pass a 1-dimensional |
| 1032 |
array or a pointer to such an array, e.g. <tt>char a[7], *b;</tt> |
| 1033 |
If passing a 1-dimensional array, <tt>routine_name_ELEMS_j</tt> (see below) must be 1. |
| 1034 |
|
| 1035 |
<p><li> To specify the numbers of elements, |
| 1036 |
<tt>routine_name_ELEMS_j</tt> and <tt>routine_name_ELEMLEN_j</tt> must be defined as shown below |
| 1037 |
before interfacing the routine with <tt>CCALLSFSUBn</tt>, <tt>PROTOCCALLSFFUNn</tt>, etc. |
| 1038 |
|
| 1039 |
<FONT COLOR="#993300"><pre> |
| 1040 |
#define routine_name_ELEMS_j ZTRINGV_ARGS(k) |
| 1041 |
[..ARGS for subroutines, ..ARGF for functions.] |
| 1042 |
</pre></font> |
| 1043 |
or |
| 1044 |
|
| 1045 |
<FONT COLOR="#993300"><pre> |
| 1046 |
#define routine_name_ELEMS_j ZTRINGV_NUM(l) |
| 1047 |
</pre></font> |
| 1048 |
|
| 1049 |
Where: |
| 1050 |
<pre> |
| 1051 |
routine_name is as above. |
| 1052 |
j [1-n], is the argument being specifying. |
| 1053 |
k [1-n], the value of the k'th argument is the dynamic number |
| 1054 |
of elements for argument j. The k'th argument must be |
| 1055 |
of type BYTE, DOUBLE, FLOAT, INT, LONG, LONGLONG or SHORT. |
| 1056 |
l the number of elements for argument j. This must be an |
| 1057 |
integer constant available at compile time. |
| 1058 |
i.e. it is static. |
| 1059 |
</pre> |
| 1060 |
|
| 1061 |
<p><li> Similarly to specify the useful length, [i.e. don't count C's trailing <tt>'\0'</tt>,] |
| 1062 |
of each element: |
| 1063 |
<FONT COLOR="#993300"><pre> |
| 1064 |
#define routine_name_ELEMLEN_j ZTRINGV_ARGS(m) |
| 1065 |
[..ARGS for subroutines, ..ARGF for functions.] |
| 1066 |
</pre></font> |
| 1067 |
or |
| 1068 |
<FONT COLOR="#993300"><pre> |
| 1069 |
#define routine_name_ELEMLEN_j ZTRINGV_NUM(q) |
| 1070 |
</pre></font> |
| 1071 |
Where: |
| 1072 |
<pre> |
| 1073 |
m [1-n], as for k but this is the length of each element. |
| 1074 |
q as for l but this is the length of each element. |
| 1075 |
</pre> |
| 1076 |
</ul> |
| 1077 |
|
| 1078 |
|
| 1079 |
<p><li> <tt>ROUTINE</tt> |
| 1080 |
The argument is an <tt>EXTERNAL</tt> procedure. |
| 1081 |
|
| 1082 |
When C passes a routine to <i>FORTRAN</i>, the language of the function must be |
| 1083 |
specified as follows: [The case of <tt>some_*_function</tt> must be given as shown.] |
| 1084 |
<p> |
| 1085 |
When C passes a C routine to a <i>FORTRAN</i>: |
| 1086 |
<FONT COLOR="#993300"><pre> |
| 1087 |
FORTRAN_ROUTINE(arg1, .... , |
| 1088 |
C_FUNCTION(SOME_C_FUNCTION,some_c_function), |
| 1089 |
...., argn); |
| 1090 |
</pre></font> |
| 1091 |
and similarly when C passes a <i>FORTRAN</i> routine to <i>FORTRAN</i>: |
| 1092 |
<FONT COLOR="#993300"><pre> |
| 1093 |
FORTRAN_ROUTINE(arg1, .... , |
| 1094 |
FORTRAN_FUNCTION(SOME_FORT_FUNCTION,some_fort_function), |
| 1095 |
...., argn); |
| 1096 |
</pre></font> |
| 1097 |
If <tt>fcallsc</tt> has been redefined; the same definition of <tt>fcallsc</tt> used when creating |
| 1098 |
the wrapper for '<tt>some_c_function</tt>' must also be defined when <tt>C_FUNCTION</tt> is used. |
| 1099 |
<a href="cfortran.html#IIii5">See ii) 5. of this section</a> for when and how to redefine |
| 1100 |
<tt>fcallsc</tt>. |
| 1101 |
|
| 1102 |
<tt>ROUTINE</tt> was introduced with <tt>cfortran.h</tt> version 2.6. Earlier versions of |
| 1103 |
<tt>cfortran.h</tt> used <tt>PVOID</tt> to pass external procedures as arguments. Using |
| 1104 |
<tt>PVOID</tt> for |
| 1105 |
this purpose is no longer recommended since it won't work 'as is' for |
| 1106 |
<tt>apolloFortran</tt>, <tt>hpuxFortran800</tt>, |
| 1107 |
<tt>AbsoftUNIXFortran</tt>, <tt>AbsoftProFortran</tt>. |
| 1108 |
|
| 1109 |
<h3>ii) Calling C routines from <i>FORTRAN</i>:</h3> |
| 1110 |
|
| 1111 |
Each of the following two statements to export a C routine to <i>FORTRAN</i> create |
| 1112 |
<i>FORTRAN</i> 'wrappers', written in C, which must be compiled and linked along with |
| 1113 |
the original C routines and with the <i>FORTRAN</i> calling code. |
| 1114 |
<p> |
| 1115 |
<i>FORTRAN</i> callable 'wrappers' may also be created for C macros. i.e. in this |
| 1116 |
section, the term 'C function' may be replaced by 'C macro'. |
| 1117 |
<p> |
| 1118 |
for C functions returning void: |
| 1119 |
<FONT COLOR="#993300"><pre> |
| 1120 |
FCALLSCSUBn( Routine_name,ROUTINE_NAME,routine_name,argtype_1,...,argtype_n) |
| 1121 |
</pre></font> |
| 1122 |
|
| 1123 |
for all other C functions: |
| 1124 |
<FONT COLOR="#993300"><pre> |
| 1125 |
FCALLSCFUNn(routine_type,Routine_name,ROUTINE_NAME,routine_name,argtype_1,...,argtype_n) |
| 1126 |
</pre></font> |
| 1127 |
|
| 1128 |
Where: |
| 1129 |
'n' = 0->27 (easily expanded to > 27) stands for the number of arguments to the |
| 1130 |
routine. |
| 1131 |
<FONT COLOR="#993300"><pre> |
| 1132 |
Routine_name = the C name of the routine. [see 9. below] |
| 1133 |
ROUTINE_NAME = the <i>FORTRAN</i> name of the routine (IN UPPER CASE LETTERS). |
| 1134 |
routine_name = the <i>FORTRAN</i> name of the routine (IN lower case LETTERS). |
| 1135 |
routine_type = the type of argument returned by C functions. |
| 1136 |
= BYTE, DOUBLE, FLOAT, INT, LOGICAL, LONG, LONGLONG, SHORT, STRING, VOID. |
| 1137 |
[Instead of VOID, FCALLSCSUBn is recommended.] |
| 1138 |
argtype_i = the type of argument passed to the <i>FORTRAN</i> routine and must be |
| 1139 |
consistent in the definition and prototyping of the routine |
| 1140 |
= BYTE, DOUBLE, FLOAT, INT, LOGICAL, LONG, LONGLONG, SHORT, STRING. |
| 1141 |
For vectors, i.e. 1 dim. arrays use |
| 1142 |
= BYTEV, DOUBLEV, FLOATV, INTV, LOGICALV, LONGLONG, LONGV, SHORTV, STRINGV. |
| 1143 |
For vectors of vectors, 2 dim. arrays use |
| 1144 |
= BYTEVV, DOUBLEVV, FLOATVV, INTVV, LOGICALVV, LONGVV, LONGLONGVV, SHORTVV. |
| 1145 |
For n-dim. arrays use |
| 1146 |
= BYTEV..nV's..V, DOUBLEV..V, FLOATV..V, INTV..V, LOGICALV..V, |
| 1147 |
LONGV..V, LONGV..V, SHORTV..V. |
| 1148 |
For routines changing the values of an argument, the keyword is |
| 1149 |
prepended by a 'P'. |
| 1150 |
= PBYTE, PDOUBLE, PFLOAT, PINT, PLOGICAL, PLONG, PLONGLONG, PSHORT, |
| 1151 |
PSTRING, PNSTRING, PPSTRING, PSTRINGV. |
| 1152 |
For EXTERNAL procedures passed as arguments use |
| 1153 |
= ROUTINE. |
| 1154 |
For exceptional arguments which require no massaging to fit the |
| 1155 |
argument passing mechanisms use |
| 1156 |
= PVOID. |
| 1157 |
The argument is cast and passed as (void *). |
| 1158 |
</pre></font> |
| 1159 |
|
| 1160 |
|
| 1161 |
Notes: |
| 1162 |
<ol> |
| 1163 |
<p><li> For <i>FORTRAN</i> calling C++ routines, C++ does NOT easily allow support for: |
| 1164 |
<tt>STRINGV</tt>. |
| 1165 |
<tt>BYTEVV</tt>, <tt>DOUBLEVV</tt>, <tt>FLOATVV</tt>, <tt>INTVV</tt>, <tt>LOGICALVV</tt>, <tt>LONGVV</tt>, <tt>LONGLONGVV</tt>, <tt>SHORTVV</tt>. |
| 1166 |
<tt>BYTEV..V</tt>, <tt>DOUBLEV..V</tt>, <tt>FLOATV..V</tt>, <tt>INTV..V</tt>, <tt>LOGICALV..V</tt>, <tt>LONGV..V</tt>, <tt>LONGLONGV..V</tt>, <tt>SHORTV..V</tt>. |
| 1167 |
Though there are ways to get around this restriction, |
| 1168 |
the restriction is not serious since these types are unlikely to be used as |
| 1169 |
arguments for a C++ routine. |
| 1170 |
|
| 1171 |
<p><li> <tt>FCALLSCSUB/FUNn</tt> expect that the routine to be 'wrapped' has been properly |
| 1172 |
prototyped, or at least declared. |
| 1173 |
|
| 1174 |
|
| 1175 |
<p><li> <tt>cfortran.h</tt> may be expanded to handle a new argument type not already among |
| 1176 |
the above. |
| 1177 |
|
| 1178 |
|
| 1179 |
<a name="IIii4"></a> |
| 1180 |
<p><li> <tt>[BYTE|DOUBLE|BYTE|DOUBLE|FLOAT|INT|LOGICAL|LONG|LONGLONG|SHORT][V|VV|VVV|...]</tt> |
| 1181 |
<p> |
| 1182 |
<tt>cfortran.h</tt> encourages the exact specification of the type and dimension of |
| 1183 |
array parameters because it allows the C compiler to detect errors in the |
| 1184 |
arguments when declaring the routine using <tt>FCALLSCSUB/FUNn</tt>, assuming the |
| 1185 |
routine to be 'wrapped' has been properly prototyped. |
| 1186 |
<p> |
| 1187 |
<tt>cfortran.h</tt> does not strictly require the exact specification since the argument |
| 1188 |
is merely the address of the array and is passed on to the calling routine. |
| 1189 |
Any array parameter could be declared as <tt>PVOID</tt>, but this circumvents |
| 1190 |
C's compiletime ability to check the correctness of arguments and is therefore |
| 1191 |
discouraged. |
| 1192 |
<p> |
| 1193 |
Passing the address of these arguments implies that <tt>PBYTEV</tt>, <tt>PFLOATV</tt>, ... , |
| 1194 |
<tt>PDOUBLEVV</tt>, ... don't exist in <tt>cfortran.h</tt>, since by default the routine and the |
| 1195 |
calling code share the same array, i.e. the same values at the same memory |
| 1196 |
location. |
| 1197 |
<p> |
| 1198 |
These comments do NOT apply to arrays of <tt>(P)STRINGV</tt>. For these parameters, |
| 1199 |
<tt>cfortran.h</tt> passes a massaged copy of the array to the routine. When the routine |
| 1200 |
returns, <tt>STRINGV</tt> ignores the copy, while <tt>PSTRINGV</tt> replaces the calling |
| 1201 |
code's original array with copy, which may have been modified by the called |
| 1202 |
routine. |
| 1203 |
|
| 1204 |
|
| 1205 |
<p><li> <a name="IIii5"></a> |
| 1206 |
<tt>(P(N))STRING</tt> arguments have any trailing blanks removed before being passed |
| 1207 |
to C, the same holds true for each element in <tt>(P)STRINGV</tt>. Space is malloc'd in |
| 1208 |
all cases big enough to hold the original string (elements) as well as C's |
| 1209 |
terminating <tt>'\0'</tt>. i.e. The useful size of the string (elements) is the same in |
| 1210 |
both languages. <tt>P(N)STRING(V)</tt> => the string (elements) will be copied from the |
| 1211 |
malloc'd space back into the <i>FORTRAN</i> bytes. If one of the two escape mechanisms |
| 1212 |
mentioned below for PNSTRING has been used, the copying back to <i>FORTRAN</i> is |
| 1213 |
obviously not relevant. |
| 1214 |
|
| 1215 |
|
| 1216 |
<p><li> <tt>(PN)STRING</tt>'s, [NOT <tt>PSTRING</tt>'s nor <tt>(P)STRINGV</tt>'s,] |
| 1217 |
behavior may be overridden |
| 1218 |
in two cases. In both cases <tt>PNSTRING</tt> and <tt>STRING</tt> behave identically. |
| 1219 |
<ol> |
| 1220 |
<p><li> If a <tt>(PN)STRING</tt> argument's first 4 bytes are all the <tt>NUL</tt> character, |
| 1221 |
i.e. <tt>'\0\0\0\0'</tt> the </tt>NULL</tt> pointer is passed to the C routine. |
| 1222 |
|
| 1223 |
<p><li> the <tt>NUL</tt> character, i.e. C strings' terminating |
| 1224 |
<tt>'\0'</tt>, the address of the string |
| 1225 |
is simply passed to the C routine. i.e. The argument is treated in this case as |
| 1226 |
it would be with <tt>PPSTRING</tt>, to which we refer the reader for more detail. |
| 1227 |
</ol> |
| 1228 |
<p> |
| 1229 |
Mechanism 1. overrides 2. . Therefore, to use this mechanism to pass the <tt>NULL</tt> |
| 1230 |
string, <tt>""</tt>, to C, the first character of the string must obviously be the <tt>NUL</tt> |
| 1231 |
character, but of the first 4 characters in the string, at least one must not |
| 1232 |
be <tt>HEX-00</tt>. |
| 1233 |
|
| 1234 |
<p>Example: |
| 1235 |
<FONT COLOR="#993300"><pre> |
| 1236 |
|
| 1237 |
<b>C FORTRAN /* C */</b> |
| 1238 |
character*40 str #include <cfortran.h> |
| 1239 |
C Set up a NULL as : void cs(char *s) {if (s) printf("%s.\n",s);} |
| 1240 |
C i) 4 NUL characters. FCALLSCSUB1(cs,CS,cs,STRING) |
| 1241 |
C ii) NULL pointer. |
| 1242 |
character*4 NULL |
| 1243 |
NULL = CHAR(0)//CHAR(0)//CHAR(0)//CHAR(0) |
| 1244 |
|
| 1245 |
data str/'just some string'/ |
| 1246 |
|
| 1247 |
C Passing the NULL pointer to cs. |
| 1248 |
call cs(NULL) |
| 1249 |
C Passing a copy of 'str' to cs. |
| 1250 |
call cs(str) |
| 1251 |
C Passing address of 'str' to cs. Trailing blanks NOT killed. |
| 1252 |
str(40:) = NULL |
| 1253 |
call cs(str) |
| 1254 |
end |
| 1255 |
</pre></font> |
| 1256 |
|
| 1257 |
Strings passed from <i>FORTRAN</i> to C via <tt>(PN)STRING</tt> must not have undefined |
| 1258 |
contents, otherwise undefined behavior will result, since one of the above two |
| 1259 |
escape mechanisms may occur depending on the contents of the string. |
| 1260 |
<p> |
| 1261 |
This is not be a problem for <tt>STRING</tt> arguments, which are read-only in the C |
| 1262 |
routine and hence must have a well defined value when being passed in. |
| 1263 |
<p> |
| 1264 |
<tt>PNSTRING</tt> arguments require special care. Even if they are write-only in the C |
| 1265 |
routine, <tt>PNSTRING</tt>'s above two escape mechanisms require that the value of the |
| 1266 |
argument be well defined when being passed in from <i>FORTRAN</i> to C. Therefore, |
| 1267 |
unless one or both of <tt>PNSTRING</tt>'s escape mechanisms are required, <tt>PSTRING</tt> |
| 1268 |
should |
| 1269 |
be used instead of <tt>PNSTRING</tt>. |
| 1270 |
Prior to version 2.8, <tt>PSTRING</tt> did have the above two escape mechanisms, |
| 1271 |
but they were removed from <tt>PSTRING</tt> to allow strings with undefined contents to |
| 1272 |
be passed in. <tt>PNSTRING</tt> behaves like the old <tt>PSTRING</tt>. |
| 1273 |
[Thanks go to Paul Dubois (<tt>[email protected]</tt>) for pointing out that <tt>PSTRING</tt> |
| 1274 |
must allow for strings with undefined contents to be passed in.] |
| 1275 |
|
| 1276 |
<p>Example: |
| 1277 |
|
| 1278 |
<FONT COLOR="#993300"><pre> |
| 1279 |
<b>C FORTRAN /* C */</b> |
| 1280 |
character*10 s,sn #include <cfortran.h> |
| 1281 |
void ps(char *s) {strcpy(s,"hello");} |
| 1282 |
C Can call ps with undef. s. FCALLSCSUB1(ps,PS,ps,PSTRING) |
| 1283 |
call ps(s) FCALLSCSUB1(ps,PNS,pns,PNSTRING) |
| 1284 |
print *,s,'=s' |
| 1285 |
|
| 1286 |
C Can't call pns with undef. s. |
| 1287 |
C e.g. If first 4 bytes of s were |
| 1288 |
C "\0\0\0\0", ps would try |
| 1289 |
C to copy to NULL because |
| 1290 |
C of PNSTRING mechanism. |
| 1291 |
sn = "" |
| 1292 |
call pns(sn) |
| 1293 |
print *,sn,'=sn' |
| 1294 |
|
| 1295 |
end |
| 1296 |
</pre></font> |
| 1297 |
|
| 1298 |
|
| 1299 |
<p><li> <tt>PPSTRING</tt> |
| 1300 |
The address of the string argument is simply passed to the C routine. Therefore |
| 1301 |
the C routine and the <i>FORTRAN</i> calling code share the same string at the same |
| 1302 |
memory location. If the C routine modifies the string, the string will also be |
| 1303 |
modified for the <i>FORTRAN</i> calling code. |
| 1304 |
The user is responsible for negociating the differences in representation of a |
| 1305 |
string in <i>FORTRAN</i> and in C, i.e. the differences are not automatically resolved |
| 1306 |
as they are for <tt>(P(N)STRING(V)</tt>. |
| 1307 |
This mechanism is provided for two reasons: |
| 1308 |
<ul> |
| 1309 |
<p><li> Some C routines require the string to exist at the given memory location, |
| 1310 |
after the C routine has exited. Recall that for the usual <tt>P(N)STRING(V)</tt> |
| 1311 |
mechanism, a copy of the <i>FORTRAN</i> string is given to the C routine, and this |
| 1312 |
copy ceases to exist after returning to the <i>FORTRAN</i> calling code. |
| 1313 |
<p><li> This mechanism can save runtime CPU cycles over |
| 1314 |
(<tt>P(N)STRING(V)</tt>, since it |
| 1315 |
does not perform their malloc, copy and kill trailing blanks of the string |
| 1316 |
to be passed.<br> |
| 1317 |
Only in a small minority of cases does the potential benefit of the saved |
| 1318 |
CPU cycles outweigh the programming effort required to manually resolve |
| 1319 |
the differences in representation of a string in <i>FORTRAN</i> and in C. |
| 1320 |
</ul> |
| 1321 |
<p> |
| 1322 |
For arguments passed via <tt>PPSTRING</tt>, the argument passed |
| 1323 |
may also be an array of |
| 1324 |
strings. |
| 1325 |
|
| 1326 |
|
| 1327 |
<p><li> <tt>ROUTINE</tt> |
| 1328 |
ANSI C requires that the type of the value returned by the routine be known, |
| 1329 |
For all ROUTINE arguments passed from <i>FORTRAN</i> to C, the type of <tt>ROUTINE</tt> is |
| 1330 |
specified by defining a cast as follows: |
| 1331 |
<FONT COLOR="#993300"><pre> |
| 1332 |
#undef ROUTINE_j |
| 1333 |
#define ROUTINE_j (cast) |
| 1334 |
</pre></font> |
| 1335 |
Where: |
| 1336 |
<pre> |
| 1337 |
j [1-n], is the argument being specifying. |
| 1338 |
(cast) is a cast matching that of the argument expected by the C |
| 1339 |
function protoytpe for which a wrapper is being defined. |
| 1340 |
</pre> |
| 1341 |
e.g. To create a <i>FORTRAN</i> wrapper for <tt>qsort(3C)</tt>: |
| 1342 |
<FONT COLOR="#993300"><pre> |
| 1343 |
#undef ROUTINE_4 |
| 1344 |
#define ROUTINE_4 (int (*)(void *,void *)) |
| 1345 |
FCALLSCSUB4(qsort,FQSORT,fqsort,PVOID,INT,INT,ROUTINE) |
| 1346 |
</pre></font> |
| 1347 |
In order to maintain backward compatibility, <tt>cfortran.h</tt> defines a generic cast |
| 1348 |
for <tt>ROUTINE_1</tt>, <tt>ROUTINE_2</tt>, ..., <tt>ROUTINE_27</tt>. The user's definition |
| 1349 |
is therefore |
| 1350 |
strictly required only for DEC C, which at the moment is the only compiler |
| 1351 |
which insists on the correct cast for pointers to functions. |
| 1352 |
<p> |
| 1353 |
When using the <tt>ROUTINE</tt> argument inside some <i>FORTRAN</i> code: |
| 1354 |
|
| 1355 |
<ul> |
| 1356 |
|
| 1357 |
<p><li> it is difficult to pass a C routine as the parameter, |
| 1358 |
since in many <i>FORTRAN</i> implementations, |
| 1359 |
<i>FORTRAN</i> has no access to the normal C namespace. |
| 1360 |
e.g. For most UNIX, |
| 1361 |
<i>FORTRAN</i> implicitly only has access to C routines ending in <tt>_</tt>. |
| 1362 |
If the calling <i>FORTRAN</i> code receives the routine as a parameter |
| 1363 |
it can of course easily pass it along. |
| 1364 |
<p><li> if a <i>FORTRAN</i> routine is passed directly as the parameter, |
| 1365 |
the called C routine must call the parameter routine |
| 1366 |
using the <i>FORTRAN</i> argument passing conventions. |
| 1367 |
<p><li> if a <i>FORTRAN</i> routine is to be passed as the parameter, |
| 1368 |
but if <i>FORTRAN</i> can be made to pass a C routine as the parameter, |
| 1369 |
then it may be best to pass a C-callable wrapper for the <i>FORTRAN</i> routine. |
| 1370 |
The called C routine is thus spared all <i>FORTRAN</i> argument passing conventions. |
| 1371 |
<tt>cfortran.h</tt> can be used to create such a C-callable wrapper |
| 1372 |
to the parameter <i>FORTRAN</i> routine. |
| 1373 |
</ul> |
| 1374 |
<p> |
| 1375 |
ONLY PowerStationFortran: |
| 1376 |
<p> |
| 1377 |
This <i>FORTRAN</i> provides no easy way to pass a <i>FORTRAN</i> routine as an argument to a |
| 1378 |
C routine. The problem arises because in <i>FORTRAN</i> the stack is cleared by the |
| 1379 |
called routine, while in C/C++ it is cleared by the caller. |
| 1380 |
The C/C++ stack clearing behavior can be changed to that of <i>FORTRAN</i> by using |
| 1381 |
<tt>stdcall__</tt> in the function prototype. The <tt>stdcall__</tt> cannot be applied in this |
| 1382 |
case since the called C routine expects the ROUTINE parameter to be a C routine |
| 1383 |
and does not know that it should apply <tt>stdcall__</tt>. |
| 1384 |
In principle the <tt>cfortran.h</tt> generated <i>FORTRAN</i> callable wrapper for the called C |
| 1385 |
routine should be able to massage the <tt>ROUTINE</tt> argument such that <tt>stdcall__</tt> is |
| 1386 |
performed, but it is not yet known how this could be easily done. |
| 1387 |
|
| 1388 |
|
| 1389 |
<p><li> <i>The following instructions are not required for VAX/VMS:</i> |
| 1390 |
<p> |
| 1391 |
<tt>(P)STRINGV</tt> information [NOT required for VAX VMS]: <tt>cfortran.h</tt> cannot convert |
| 1392 |
the <i>FORTRAN</i> vector of <tt>STRINGS</tt> to the required C vector of <tt>STRINGS</tt> without |
| 1393 |
explicitly knowing the number of elements in the vector. The application must |
| 1394 |
do one of the following for each <tt>(P)STRINGV</tt> argument in a routine before that |
| 1395 |
routine's <tt>FCALLSCFUNn/SUBn</tt> is called: |
| 1396 |
|
| 1397 |
<FONT COLOR="#993300"><pre> |
| 1398 |
#define routine_name_STRV_Ai NUM_ELEMS(j) |
| 1399 |
or |
| 1400 |
#define routine_name_STRV_Ai NUM_ELEM_ARG(k) |
| 1401 |
or |
| 1402 |
#define routine_name_STRV_Ai TERM_CHARS(l,m) |
| 1403 |
</pre></font> |
| 1404 |
|
| 1405 |
where: |
| 1406 |
|
| 1407 |
<pre> |
| 1408 |
routine_name is as above. |
| 1409 |
i [i=1->n.] specifies the argument number of a STRING VECTOR. |
| 1410 |
j would specify a fixed number of elements. |
| 1411 |
k [k=1->n. k!=i] would specify an integer argument which specifies the |
| 1412 |
number of elements. |
| 1413 |
l [char] the terminating character at the beginning of an |
| 1414 |
element, indicating to <tt>cfortran.h</tt> that the preceding |
| 1415 |
elements in the vector are the valid ones. |
| 1416 |
m [m=1-...] the number of terminating characters required to appear |
| 1417 |
at the beginning of the terminating string element. |
| 1418 |
The terminating element is NOT passed on to |
| 1419 |
the C routine. |
| 1420 |
|
| 1421 |
e.g. #define ce_STRV_A1 TERM_CHARS(' ',2) |
| 1422 |
FCALLSCSUB1(ce,CE,ce,STRINGV) |
| 1423 |
</pre> |
| 1424 |
|
| 1425 |
<tt>cfortran.h</tt> will pass on all elements, in the 1st and only argument to the C |
| 1426 |
routine ce, of the <tt>STRING VECTOR</tt> until, but not including, the first string |
| 1427 |
element beginning with 2 blank, <tt>' '</tt>, characters. |
| 1428 |
|
| 1429 |
|
| 1430 |
<p><li> <i>Instructions required only for <i>FORTRAN</i> compilers which generate |
| 1431 |
routine names which are undistinguishable from c routine names:</i> |
| 1432 |
<br> |
| 1433 |
i.e. |
| 1434 |
<pre> |
| 1435 |
AbsoftUNIXFortran (AbsoftProFortran ok, since it uses Uppercase names.) |
| 1436 |
HP9000 if not using the +ppu option of <tt>f77</tt> |
| 1437 |
IBM RS/6000 if not using the -qextname option of xlf |
| 1438 |
</pre> |
| 1439 |
Call them the <tt>same_namespace</tt> compilers. |
| 1440 |
<p> |
| 1441 |
<tt>FCALLSCSUBn(...)</tt> and <tt>FCALLSCFUNn(...)</tt>, when compiled, are expanded into |
| 1442 |
'wrapper' functions, so called because they wrap around the original C |
| 1443 |
functions and interface the format of the original C functions' arguments and |
| 1444 |
return values with the format of the <i>FORTRAN</i> call. |
| 1445 |
<p> |
| 1446 |
Ideally one wants to be able to call the C routine from <i>FORTRAN</i> using the same |
| 1447 |
name as the original C name. This is not a problem for <i>FORTRAN</i> compilers which |
| 1448 |
append an underscore, <tt>'_'</tt>, to the names of routines, since the original C |
| 1449 |
routine has the name 'name', and the <i>FORTRAN</i> wrapper is called <tt>'name_'</tt>. |
| 1450 |
Similarly, if the <i>FORTRAN</i> compiler generates upper case names for routines, the |
| 1451 |
original C routine <tt>'name'</tt> can have a wrapper called <tt>'NAME'</tt>, [Assuming the C |
| 1452 |
routine name is not in upper case.] For these compilers, e.g. Mips, IBM |
| 1453 |
RS/6000 <tt>'xlf -qextname'</tt>, HP-UX </tt>'f77 +ppu'</tt>, the naming of the wrappers is done |
| 1454 |
automatically. |
| 1455 |
<p> |
| 1456 |
For <tt>same_namespace</tt> compilers things are not as simple, but <tt>cfortran.h</tt> tries to |
| 1457 |
provide tools and guidelines to minimize the costs involved in meeting their |
| 1458 |
constraints. The following two options can provide <tt>same_namespace</tt> compilers |
| 1459 |
with distinct names for the wrapper and the original C function. |
| 1460 |
<p> |
| 1461 |
These compilers are flagged by <tt>cfortran.h</tt> with the <tt>CF_SAME_NAMESPACE</tt> constant, |
| 1462 |
so that the change in the C name occurs only when required. |
| 1463 |
<p> |
| 1464 |
For the remainder of the discussion, routine names generated by <i>FORTRAN</i> |
| 1465 |
compilers are referred to in lower case, these names should be read as upper |
| 1466 |
case for the appropriate compilers. |
| 1467 |
<p> |
| 1468 |
<i>HP9000 (When <tt>f77 +ppu</tt> is not used.)</i> |
| 1469 |
<p> |
| 1470 |
<tt>f77</tt> has a <tt>-U</tt> option which forces uppercase external names to be generated. |
| 1471 |
Unfortunately, <tt>cc</tt> does not handle recursive macros. Hence, if one wished to use |
| 1472 |
<tt>-U</tt> for separate C and <i>FORTRAN</i> namespaces, one would have to adopt a different |
| 1473 |
convention of naming the macros which allow C to call <i>FORTRAN</i> subroutines. |
| 1474 |
(Functions are not a problem.) The macros are currently the uppercase of the |
| 1475 |
original <i>FORTRAN</i> name, and would have to be changed to lower case or mixed |
| 1476 |
case, or to a different name. (Lower case would of course cause conflicts on |
| 1477 |
many other machines.) Therefore, it is suggested that <tt>f77 -U</tt> not be used, and |
| 1478 |
instead that Option a) or Option b) outlined below be used. |
| 1479 |
|
| 1480 |
<p> |
| 1481 |
<i>VAX/VMS:</i> |
| 1482 |
<p> |
| 1483 |
For the name used by <i>FORTRAN</i> in calling a C routine to be the same as that of |
| 1484 |
the C routine, the source code of the C routine is required. A preprocessor |
| 1485 |
directive can then force the C compiler to generate a different name for the C |
| 1486 |
routine. e.g. |
| 1487 |
<FONT COLOR="#993300"><pre> |
| 1488 |
#if defined(vms) |
| 1489 |
#define name name_ |
| 1490 |
#endif |
| 1491 |
void name() {printf("name: was called.\n");} |
| 1492 |
FCALLSCSUB0(name,NAME,name) |
| 1493 |
</pre></font> |
| 1494 |
In the above, the C compiler generates the original routine with the name |
| 1495 |
<tt>'name_'</tt> and a wrapper called <tt>'NAME'</tt>. This assumes that the name of the routine, |
| 1496 |
as seen by the C programmer, is not in upper case. The VAX VMS linker is not |
| 1497 |
case sensitive, allowing <tt>cfortran.h</tt> to export the upper case name as the |
| 1498 |
wrapper, which then doesn't conflict with the routine name in C. Since the IBM, |
| 1499 |
HP and AbsoftUNIXFortran platforms have case sensitive linkers |
| 1500 |
this technique is not available to them. |
| 1501 |
<p> |
| 1502 |
The above technique is required even if the C name is in mixed case, see |
| 1503 |
Option a) for the other compilers, but is obviously not required when |
| 1504 |
Option b) is used. |
| 1505 |
<p> |
| 1506 |
|
| 1507 |
<b>Option a)</b> Mixed Case names for the C routines to be called by <i>FORTRAN</i>. |
| 1508 |
<p> |
| 1509 |
If the original C routines have mixed case names, there are no name space |
| 1510 |
conflicts. |
| 1511 |
<p> |
| 1512 |
Nevertheless for VAX/VMS, the technique outlined above must also be used. |
| 1513 |
|
| 1514 |
<p> |
| 1515 |
|
| 1516 |
<b>Option b)</b> Modifying the names of C routines when used by <i>FORTRAN</i>: |
| 1517 |
|
| 1518 |
The more robust naming mechanism, which guarantees portability to all machines, |
| 1519 |
'renames' C routines when called by <i>FORTRAN</i>. Indeed, one must change the names |
| 1520 |
on <tt>same_namespace</tt> compilers when <i>FORTRAN</i> calls C routines for which the source |
| 1521 |
is unavailable. [Even when the source is available, renaming may be preferable |
| 1522 |
to Option a) for large libraries of C routines.] |
| 1523 |
<p> |
| 1524 |
Obviously, if done for a single type of machine, it must be done for all |
| 1525 |
machines since the names of routines used in <i>FORTRAN</i> code cannot be easily |
| 1526 |
redefined for different machines. |
| 1527 |
<p> |
| 1528 |
The simplest way to achieve this end is to do explicitly give the modified |
| 1529 |
<i>FORTRAN</i> name in the <tt>FCALLSCSUBn(...)</tt> and <tt>FCALLSCFUNn(...)</tt> |
| 1530 |
declarations. e.g. |
| 1531 |
|
| 1532 |
<FONT COLOR="#993300"><pre> |
| 1533 |
FCALLSCSUB0(name,CFNAME,cfname) |
| 1534 |
</pre></font> |
| 1535 |
|
| 1536 |
This allows <i>FORTRAN</i> to call the C routine <tt>'name'</tt> as <tt>'cfname'</tt>. |
| 1537 |
Any name can of |
| 1538 |
course be used for a given routine when it is called from <i>FORTRAN</i>, although |
| 1539 |
this is discouraged due to the confusion it is sure to cause. e.g. Bizarre, |
| 1540 |
but valid and allowing C's <tt>'call_back'</tt> routine to be called from <i>FORTRAN</i> as |
| 1541 |
<tt>'abcd'</tt>: |
| 1542 |
<FONT COLOR="#993300"><pre> |
| 1543 |
FCALLSCSUB0(call_back,ABCD,abcd) |
| 1544 |
</pre></font> |
| 1545 |
|
| 1546 |
<tt>cfortran.h</tt> also provides preprocessor directives for a systematic 'renaming' of |
| 1547 |
the C routines when they are called from <i>FORTRAN</i>. This is done by redefining |
| 1548 |
the fcallsc macro before the <tt>FCALLSCSUB/FUN/n</tt> declarations as follows: |
| 1549 |
<FONT COLOR="#993300"><pre> |
| 1550 |
#undef fcallsc |
| 1551 |
#define fcallsc(UN,LN) preface_fcallsc(CF,cf,UN,LN) |
| 1552 |
|
| 1553 |
FCALLSCSUB0(hello,HELLO,hello) |
| 1554 |
</pre></font> |
| 1555 |
Will cause C's routine 'hello' to be known in <i>FORTRAN</i> as <tt>'cfhello'</tt>. Similarly |
| 1556 |
all subsequent <tt>FCALLSCSUB/FUN/n</tt> declarations will generate wrappers to allow |
| 1557 |
<i>FORTRAN</i> to call C with the C routine's name prefaced by <tt>'cf'</tt>. The following has |
| 1558 |
the same effect, with subsequent <tt>FCALLSCSUB/FUN/n</tt>'s appending the modifier to |
| 1559 |
the original C routines name. |
| 1560 |
<FONT COLOR="#993300"><pre> |
| 1561 |
#undef fcallsc |
| 1562 |
#define fcallsc(UN,LN) append_fcallsc(Y,y,UN,LN) |
| 1563 |
|
| 1564 |
FCALLSCSUB0(Xroutine,ROUTINE,routine) |
| 1565 |
</pre></font> |
| 1566 |
Hence, C's Xroutine is called from <i>FORTRAN</i> as: |
| 1567 |
<FONT COLOR="#993300"><pre> |
| 1568 |
CALL XROUTINEY() |
| 1569 |
</pre></font> |
| 1570 |
The original behavior of <tt>FCALLSCSUB/FUN/n</tt>, where <i>FORTRAN</i> routine names are left |
| 1571 |
identical to those of C, is returned using: |
| 1572 |
<FONT COLOR="#993300"><pre> |
| 1573 |
#undef fcallsc |
| 1574 |
#define fcallsc(UN,LN) orig_fcallsc(UN,LN) |
| 1575 |
</pre></font> |
| 1576 |
|
| 1577 |
In C, when passing a C routine, i.e. its wrapper, as an argument to a <i>FORTRAN</i> |
| 1578 |
routine, the <i>FORTRAN</i> name declared is used and the correct fcallsc must be in |
| 1579 |
effect. E.g. Passing 'name' and 'routine' of the above examples to the <i>FORTRAN</i> |
| 1580 |
routines, <tt>FT1</tt> and <tt>FT2</tt>, respectively: |
| 1581 |
<FONT COLOR="#993300"><pre> |
| 1582 |
/* This might not be needed if fcallsc is already orig_fcallsc. */ |
| 1583 |
#undef fcallsc |
| 1584 |
#define fcallsc(UN,LN) orig_fcallsc(UN,LN) |
| 1585 |
FT1(C_FUNCTION(CFNAME,cfname)); |
| 1586 |
|
| 1587 |
#undef fcallsc |
| 1588 |
#define fcallsc(UN,LN) append_fcallsc(Y,y,UN,LN) |
| 1589 |
FT1(C_FUNCTION(XROUTINE,xroutine)); |
| 1590 |
</pre></font> |
| 1591 |
If the names of C routines are modified when used by <i>FORTRAN</i>, fcallsc would |
| 1592 |
usually be defined once in a header_file.h for the application. This definition |
| 1593 |
would then be used and be valid for the entire application and fcallsc would at |
| 1594 |
no point need to be redefined. |
| 1595 |
|
| 1596 |
<p> |
| 1597 |
<b> |
| 1598 |
Once again: the definitions, instructions, declarations and difficulties |
| 1599 |
described here, note 9. OF II ii), |
| 1600 |
apply only for, |
| 1601 |
</b><pre> |
| 1602 |
VAX VMS |
| 1603 |
IBM RS/6000 WITHOUT THE -qextname OPTION FOR xlf, OR |
| 1604 |
HP-UX WITHOUT THE +ppu OPTION FOR f77 |
| 1605 |
AbsoftUNIXFortran |
| 1606 |
</pre> |
| 1607 |
<b> |
| 1608 |
and apply only when creating wrappers which enable |
| 1609 |
<i>FORTRAN</i> to call c routines. |
| 1610 |
</b> |
| 1611 |
|
| 1612 |
</ol> |
| 1613 |
|
| 1614 |
<h3>iii) Using C to manipulate <i>FORTRAN</i> COMMON BLOCKS:</h3> |
| 1615 |
|
| 1616 |
<i>FORTRAN</i> common blocks are set up with the following three constructs: |
| 1617 |
<ol> |
| 1618 |
<p><li> |
| 1619 |
<FONT COLOR="#993300"><pre> |
| 1620 |
#define Common_block_name COMMON_BLOCK(COMMON_BLOCK_NAME,common_block_name) |
| 1621 |
</pre></font> |
| 1622 |
<pre> |
| 1623 |
Common_block_name is in UPPER CASE. |
| 1624 |
COMMON_BLOCK_NAME is in UPPER CASE. |
| 1625 |
common_block_name is in lower case. |
| 1626 |
</pre> |
| 1627 |
[<tt>Common_block_name</tt> actually follows the same 'rules' as |
| 1628 |
<tt>Routine_name</tt> in |
| 1629 |
<a href="cfortran.html#IIi2">Note 2. of II i)</a>.] |
| 1630 |
This construct exists to ensure that C code accessing the common |
| 1631 |
block is machine independent. |
| 1632 |
|
| 1633 |
<p><li> |
| 1634 |
<FONT COLOR="#993300"><pre> |
| 1635 |
COMMON_BLOCK_DEF(TYPEDEF_OF_STRUCT, Common_block_name); |
| 1636 |
</pre></font> |
| 1637 |
|
| 1638 |
where |
| 1639 |
<FONT COLOR="#993300"><pre> |
| 1640 |
typedef { ... } TYPEDEF_OF_STRUCT; |
| 1641 |
</pre></font> |
| 1642 |
declares the structure which maps on to the common block. The |
| 1643 |
<tt>#define</tt> of |
| 1644 |
<tt>Common_block_name</tt> must come before the use of |
| 1645 |
<tt>COMMON_BLOCK_DEF</tt>. |
| 1646 |
|
| 1647 |
<p><li> |
| 1648 |
In exactly one of the C source files, storage should be set aside for the |
| 1649 |
common block with the definition: |
| 1650 |
|
| 1651 |
<FONT COLOR="#993300"><pre> |
| 1652 |
TYPEDEF_OF_STRUCT Common_block_name; |
| 1653 |
</pre></font> |
| 1654 |
|
| 1655 |
The above definition may have to be omitted on some machines for a common block |
| 1656 |
which is initialized by <i>FORTRAN</i> |
| 1657 |
<tt>BLOCK DATA</tt> or is declared with a smaller size |
| 1658 |
in the C routines than in the <i>FORTRAN</i> routines. |
| 1659 |
<p> |
| 1660 |
The rules for common blocks are not well defined when linking/loading a mixture |
| 1661 |
of C and <i>FORTRAN</i>, but the following information may help |
| 1662 |
resolve problems. |
| 1663 |
<p> |
| 1664 |
From the 2nd or ANSI ed. of K&R C, p.31, last paragraph: |
| 1665 |
<p><b>i)</b> |
| 1666 |
An external variable must be defined, exactly once, outside of any function; |
| 1667 |
this sets aside storage for it. |
| 1668 |
<p><b>ii)</b> |
| 1669 |
The variable must also be declared in each function that wants to access it; |
| 1670 |
... |
| 1671 |
The declaration ... may be implicit from context. |
| 1672 |
<p> |
| 1673 |
In <i>FORTRAN</i>, every routine says <tt>'common /bar/ foo'</tt>, |
| 1674 |
i.e. part ii) of the above, but there's no part i) requirement. |
| 1675 |
<tt>cc/ld</tt> on some machines don't require i) either. |
| 1676 |
Therefore, when handling <i>FORTRAN</i>, and sometimes C, |
| 1677 |
the loader/linker must automagically set aside storage for common blocks. |
| 1678 |
<p> |
| 1679 |
Some loaders, turn off the |
| 1680 |
'automagically set aside storage' capability for <i>FORTRAN</i> common blocks, |
| 1681 |
if any C object declares that common block. |
| 1682 |
Therefore, C code should define, i.e. set aside storage, |
| 1683 |
for the the common block as shown above. |
| 1684 |
|
| 1685 |
e.g. |
| 1686 |
<FONT COLOR="#993300"><pre> |
| 1687 |
<b>C Fortran</b> |
| 1688 |
common /fcb/ v,w,x |
| 1689 |
character *(13) v, w(4), x(3,2) |
| 1690 |
|
| 1691 |
<b>/* C */</b> |
| 1692 |
typedef struct { char v[13],w[4][13],x[2][3][13]; } FCB_DEF; |
| 1693 |
#define Fcb COMMON_BLOCK(FCB,fcb) |
| 1694 |
COMMON_BLOCK_DEF(FCB_DEF,Fcb); |
| 1695 |
FCB_DEF Fcb; /* Definition, which sets aside storage for Fcb, */ |
| 1696 |
/* may appear in at most one C source file. */ |
| 1697 |
</pre></font> |
| 1698 |
|
| 1699 |
C programs can place a string (or a multidimensional array of strings) into a |
| 1700 |
<i>FORTRAN</i> common block using the following call: |
| 1701 |
|
| 1702 |
<FONT COLOR="#993300"><pre> |
| 1703 |
C2FCBSTR( CSTR, FSTR,DIMENSIONS); |
| 1704 |
</pre></font> |
| 1705 |
|
| 1706 |
where: |
| 1707 |
<br> |
| 1708 |
<tt>CSTR</tt> is a pointer to the first element of C's copy of the string (array). |
| 1709 |
The C code must use a duplicate of, not the original, common block string, |
| 1710 |
because the <i>FORTRAN</i> common block does not allocate space for C strings' |
| 1711 |
terminating '\0'. |
| 1712 |
<br> |
| 1713 |
<tt>FSTR</tt> is a pointer to the first element of the string (array) in the common |
| 1714 |
block. |
| 1715 |
<br> |
| 1716 |
<tt>DIMENSIONS</tt> is the number of dimensions of string array. |
| 1717 |
e.g. |
| 1718 |
<FONT COLOR="#993300"><pre> |
| 1719 |
char a[10] has DIMENSIONS=0. |
| 1720 |
char aa[10][17] has DIMENSIONS=1. |
| 1721 |
etc... |
| 1722 |
</pre></font> |
| 1723 |
|
| 1724 |
<tt>C2FCBSTR</tt> will copy the string (array) from <tt>CSTR</tt> to <tt>FSTR</tt>, |
| 1725 |
padding with blanks, |
| 1726 |
' ', the trailing characters as required. <tt>C2FCBSTR</tt> uses <tt>DIMENSIONS</tt> |
| 1727 |
and <tt>FSTR</tt> to |
| 1728 |
determine the lengths of the individual string elements and the total number of |
| 1729 |
elements in the string array. |
| 1730 |
<p> |
| 1731 |
Note that: |
| 1732 |
<ul> |
| 1733 |
<li> the number of string elements in <tt>CSTR</tt> and <tt>FSTR</tt> are identical. |
| 1734 |
<li> for arrays of strings, the useful lengths of strings in <tt>CSTR</tt> and <tt>FSTR</tt> must be |
| 1735 |
the same. i.e. <tt>CSTR</tt> elements each have 1 extra character to accommodate the |
| 1736 |
terminating <tt>'\0'</tt>. |
| 1737 |
<li> On most non-ANSI compilers, the <tt>DIMENSION</tt> argument cannot be prepended by any |
| 1738 |
blanks. |
| 1739 |
</ul> |
| 1740 |
<p> |
| 1741 |
<tt>FCB2CSTR( FSTR, CSTR,DIMENSIONS)</tt> |
| 1742 |
|
| 1743 |
is the inverse of <tt>C2FCBSTR</tt>, and shares the same arguments and caveats. |
| 1744 |
<tt>FCB2CSTR</tt> copies each string element of <tt>FSTR</tt> to <tt>CSTR</tt>, |
| 1745 |
minus <i>FORTRAN</i> strings' |
| 1746 |
trailing blanks. |
| 1747 |
<p> |
| 1748 |
|
| 1749 |
<b><tt>cfortran.h</tt> |
| 1750 |
users are strongly urged to examine the common block examples in |
| 1751 |
<tt>cfortest.c</tt> and <tt>cfortex.f</tt></b>. |
| 1752 |
The use of strings in common blocks is |
| 1753 |
demonstrated, along with a suggested way for C to imitate <i>FORTRAN</i> |
| 1754 |
<tt>EQUIVALENCE</tt>'d |
| 1755 |
variables. |
| 1756 |
</ol> |
| 1757 |
|
| 1758 |
<p> |
| 1759 |
<center><b> |
| 1760 |
**** USERS OF CFORTRAN.H NEED READ NO FURTHER **** |
| 1761 |
</b></center> |
| 1762 |
|
| 1763 |
<h2>III) Some Musings</h2> |
| 1764 |
|
| 1765 |
<tt>cfortran.h</tt> is simple enough to be used by the most basic of |
| 1766 |
applications, i.e. |
| 1767 |
making a single C/<i>FORTRAN</i> routine available to the <i>FORTRAN</i>/C programmers. Yet |
| 1768 |
<tt>cfortran.h</tt> is powerful enough to easily make entire C/<i>FORTRAN</i> |
| 1769 |
libraries |
| 1770 |
available to <i>FORTRAN</i>/C programmers. |
| 1771 |
<p> |
| 1772 |
|
| 1773 |
<tt>cfortran.h</tt> is the ideal tool for <i>FORTRAN</i> libraries which are being |
| 1774 |
(re)written |
| 1775 |
in C, but are to (continue to) support <i>FORTRAN</i> users. It allows the routines to |
| 1776 |
be written in 'natural C', without having to consider the <i>FORTRAN</i> argument |
| 1777 |
passing mechanisms of any machine. It also allows C code accessing these |
| 1778 |
rewritten routines, to use the C entry point. Without <tt>cfortran.h</tt>, |
| 1779 |
one risks the |
| 1780 |
perverse practice of C code calling a C function using <i>FORTRAN</i> argument |
| 1781 |
passing |
| 1782 |
mechanisms! |
| 1783 |
<p> |
| 1784 |
|
| 1785 |
Perhaps the philosophy and mechanisms of <tt>cfortran.h</tt> could be used |
| 1786 |
and extended |
| 1787 |
to create other language bridges such as ADAFORTRAN, CPASCAL, COCCAM, etc. |
| 1788 |
<p> |
| 1789 |
|
| 1790 |
The code generation machinery inside <tt>cfortran.h</tt>, i.e. the global |
| 1791 |
structure is |
| 1792 |
quite good, being clean and workable as seen by its ability to meet the needs |
| 1793 |
and constraints of many different compilers. Though the individual instructions |
| 1794 |
of the A..., C..., T..., R... and K... tables deserve to be cleaned up. |
| 1795 |
|
| 1796 |
|
| 1797 |
<a name="IV"></a> |
| 1798 |
<h2>IV) Getting Serious with cfortran.h</h2> |
| 1799 |
|
| 1800 |
<tt>cfortran.h</tt> is set up to be as simple as possible for the casual user. While |
| 1801 |
this ease of use will always be present, 'hooks', i.e. preprocessor directives, |
| 1802 |
are required in <tt>cfortran.h</tt> so that some of the following 'inefficiencies' can |
| 1803 |
be eliminated if they cause difficulties: |
| 1804 |
|
| 1805 |
<ul> |
| 1806 |
<p><li> <tt>cfortran.h</tt> contains a few small routines for string manipulation. These |
| 1807 |
routines are declared static and are included and compiled in all source code |
| 1808 |
which uses <tt>cfortran.h</tt>. Hooks should be provided in <tt>cfortran.h</tt> to create an |
| 1809 |
object file of these routines, allowing <tt>cfortran.h</tt> to merely prototypes |
| 1810 |
these routines in the application source code. This is the only 'problem' which |
| 1811 |
afflicts both halves of <tt>cfortran.h</tt>. The remaining discussion refers to the C |
| 1812 |
calls <i>FORTRAN</i> half only. |
| 1813 |
|
| 1814 |
<p><li> Similar to the above routines, <tt>cfortran.h</tt> generates code for a 'wrapper' |
| 1815 |
routine for each FUNCTION exported from <i>FORTRAN</i>. Again <tt>cfortran.h</tt> needs |
| 1816 |
preprocessor directives to create a single object file of these routines, |
| 1817 |
and to merely prototype them in the applications. |
| 1818 |
|
| 1819 |
<p><li> Libraries often contain hundreds of routines. While the preprocessor makes |
| 1820 |
quick work of generating the required interface code from <tt>cfortran.h</tt> and the |
| 1821 |
application.h's, it may be convenient for very large stable libraries to have |
| 1822 |
final_application.h's which already contain the interface code, i.e. these |
| 1823 |
final_application.h's would not require <tt>cfortran.h</tt>. [The convenience can be |
| 1824 |
imagined for the VAX VMS CC compiler which has a fixed amount of memory for |
| 1825 |
preprocessor directives. Not requiring <tt>cfortran.h</tt>, with its hundreds of |
| 1826 |
directives, could help prevent this compiler from choking on its internal |
| 1827 |
limits quite so often.] |
| 1828 |
</ul> |
| 1829 |
|
| 1830 |
With a similar goal in mind, <tt>cfortran.h</tt> defines 100's of preprocessor |
| 1831 |
directives. There is always the potential that these will clash with other tags |
| 1832 |
in the users code, so final_applications.h, which don't require <tt>cfortran.h</tt>, |
| 1833 |
also provide the solution. |
| 1834 |
<p> |
| 1835 |
In the same vein, routines with more than 14 arguments can not be interfaced by |
| 1836 |
<tt>cfortran.h</tt> with compilers which limit C macros to 31 arguments. To resolve this |
| 1837 |
difficulty, final_application.h's can be created on a compiler without this |
| 1838 |
limitation. |
| 1839 |
<p> |
| 1840 |
Therefore, new machinery is required to do: |
| 1841 |
|
| 1842 |
<FONT COLOR="#993300"><pre> |
| 1843 |
application.h + <tt>cfortran.h</tt> => final_application.h |
| 1844 |
</pre></font> |
| 1845 |
|
| 1846 |
The following example may help clarify the means and ends: |
| 1847 |
<p> |
| 1848 |
If the following definition of the <tt>HBOOK1</tt> routine, |
| 1849 |
the <tt>/*commented_out_part*/</tt>, |
| 1850 |
is passed through the preprocessor [perhaps #undefing and #defining |
| 1851 |
preprocessor |
| 1852 |
constants if creating an <tt>application.h</tt> for compiler other than that of the |
| 1853 |
preprocessor being used, e.g. <tt>cpp -Umips ... </tt>] : |
| 1854 |
|
| 1855 |
<FONT COLOR="#993300"><pre> |
| 1856 |
#include <cfortran.h> |
| 1857 |
PROTOCCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT) |
| 1858 |
/*#define HBOOK1(ID,CHTITLE,NX,XMI,XMA,VMX) \*/ |
| 1859 |
CCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT, \ |
| 1860 |
ID,CHTITLE,NX,XMI,XMA,VMX) |
| 1861 |
</pre></font> |
| 1862 |
|
| 1863 |
A function prototype is produced by the <tt>PROTOCCALLSFSUB6(...)</tt>. |
| 1864 |
Interface code is produced, based on the 'variables', |
| 1865 |
<tt>ID,CHTITLE,NX,XMI,XMA,VMX</tt> which will correctly massage a |
| 1866 |
<tt>HBOOK1</tt> call. |
| 1867 |
Therefore, adding the #define line: |
| 1868 |
|
| 1869 |
<FONT COLOR="#993300"><pre> |
| 1870 |
'prototype code' |
| 1871 |
#define HBOOK1(ID,CHTITLE,NX,XMI,XMA,VMX) \ |
| 1872 |
'interface code'(ID,CHTITLE,NX,XMI,XMA,VMX) |
| 1873 |
</pre></font> |
| 1874 |
|
| 1875 |
which is placed into <tt>final_application.h</tt>. |
| 1876 |
<p> |
| 1877 |
The only known limitation of the above method does not allow the 'variable' |
| 1878 |
names to include <tt>B1,B2,...,B9,BA,BB,... </tt> |
| 1879 |
|
| 1880 |
Obviously the machinery to automatically generate |
| 1881 |
<tt>final_applications.h</tt> from |
| 1882 |
<tt>cfortran.h</tt> and |
| 1883 |
<tt>applications.h</tt> needs more than just some preprocessor |
| 1884 |
directives, but a fairly simple unix shell script should be sufficient. Any |
| 1885 |
takers? |
| 1886 |
|
| 1887 |
|
| 1888 |
|
| 1889 |
<h2>V) Machine Dependencies of cfortran.h</h2> |
| 1890 |
|
| 1891 |
Porting <tt>cfortran.h</tt> applications, e.g. the <tt>hbook.h</tt> and |
| 1892 |
<tt>cstring.c</tt> mentioned |
| 1893 |
above, to other machines is trivial since they are machine independent. |
| 1894 |
Porting |
| 1895 |
<tt>cfortran.h</tt> requires a solid knowledge of the new machines C |
| 1896 |
preprocessor, and |
| 1897 |
its <i>FORTRAN</i> argument passing mechanisms. Logically <tt>cfortran.h</tt> |
| 1898 |
exists as two |
| 1899 |
halves, a "C CALLS FORTRAN" and a "FORTRAN CALLS C" utility. In some cases it |
| 1900 |
may be perfectly reasonable to port only 'one half' of <tt>cfortran.h</tt> onto a new |
| 1901 |
system. |
| 1902 |
<p> |
| 1903 |
|
| 1904 |
The lucky programmer porting <tt>cfortran.h</tt> to a new machine, must discover the |
| 1905 |
<i>FORTRAN</i> argument passing mechanisms. A safe starting point is to assume that |
| 1906 |
variables and arrays are simply passed by reference, but nothing is guaranteed. |
| 1907 |
Strings, and n-dimensional arrays of strings are a different story. It is |
| 1908 |
doubtful that any systems do it quite like VAX VMS does it, so that a UNIX or |
| 1909 |
<tt>f2c</tt> versions may provide an easier starting point. |
| 1910 |
<p> |
| 1911 |
|
| 1912 |
<tt>cfortran.h</tt> uses and abuses the preprocessor's |
| 1913 |
<tt>##</tt> operator. Although the <tt>##</tt> |
| 1914 |
operator does not exist in many compilers, many kludges do. |
| 1915 |
<tt>cfortran.h</tt> uses |
| 1916 |
<tt>/**/</tt> with no space allowed between the slashes, <tt>'/' |
| 1917 |
</tt>, and the macros or tags |
| 1918 |
to be concatenated. e.g. |
| 1919 |
|
| 1920 |
<FONT COLOR="#993300"><pre> |
| 1921 |
#define concat(a,b) a/**/b /* works*/ |
| 1922 |
main() |
| 1923 |
{ |
| 1924 |
concat(pri,ntf)("hello"); /* e.g. */ |
| 1925 |
} |
| 1926 |
</pre></font> |
| 1927 |
|
| 1928 |
<b>N.B.</b> On some compilers without ##, /**/ may also not work. The author may be |
| 1929 |
able to offer alternate kludges. |
| 1930 |
|
| 1931 |
|
| 1932 |
|
| 1933 |
<h2>VI) Bugs in vendors C compilers and other curiosities</h2> |
| 1934 |
|
| 1935 |
<ol> |
| 1936 |
<p><li> ULTRIX xxxxxx 4.3 1 RISC |
| 1937 |
<br> |
| 1938 |
Condolences to long suffering ultrix users! |
| 1939 |
DEC supplies a working C front end for alpha/OSF, but not for ultrix. |
| 1940 |
<p> |
| 1941 |
From K&R ANSI C p. 231: |
| 1942 |
<FONT COLOR="#993300"><pre> |
| 1943 |
ultrix> cat cat.c |
| 1944 |
#define cat(x, y) x ## y |
| 1945 |
#define xcat(x,y) cat(x,y) |
| 1946 |
cat(cat(1,2),3) |
| 1947 |
xcat(xcat(1,2),3) |
| 1948 |
ultrix> cc -E cat.c |
| 1949 |
123 <---- Should be: cat(1,2)3 |
| 1950 |
123 <---- Correct. |
| 1951 |
ultrix> |
| 1952 |
</pre></font> |
| 1953 |
|
| 1954 |
The problem for <tt>cfortran.h</tt>, preventing use of -std and -std1: |
| 1955 |
|
| 1956 |
<FONT COLOR="#993300"><pre> |
| 1957 |
ultrix> cat c.c |
| 1958 |
#define cat(x, y) x ## y |
| 1959 |
#define xcat(x,y) cat(x,y) |
| 1960 |
#define AB(X) X+X |
| 1961 |
#define C(E,F,G) cat(E,F)(G) |
| 1962 |
#define X(E,F,G) xcat(E,F)(G) |
| 1963 |
C(A,B,2) |
| 1964 |
X(A,B,2) |
| 1965 |
ultrix> cc -std1 -E c.c |
| 1966 |
2+2 |
| 1967 |
AB (2) <---- ????????????? |
| 1968 |
ultrix> |
| 1969 |
ultrix> cc -std0 -E c.c |
| 1970 |
2+2 |
| 1971 |
AB(2) <---- ????????????? |
| 1972 |
ultrix> |
| 1973 |
</pre></font> |
| 1974 |
|
| 1975 |
Due to further ultrix preprocessor problems, |
| 1976 |
for all definitions of definitions with arguments, |
| 1977 |
<tt>cfortran.h</tt> >= 3.0 includes the arguments and recommends the same, |
| 1978 |
even though it is not required by ANSI C. |
| 1979 |
e.g. Users are advised to do |
| 1980 |
<FONT COLOR="#993300"><pre> |
| 1981 |
#define fcallsc(UN,LN) orig_fcallsc(UN,LN) |
| 1982 |
</pre></font> |
| 1983 |
instead of |
| 1984 |
<FONT COLOR="#993300"><pre> |
| 1985 |
#define fcallsc orig_fcallsc |
| 1986 |
</pre></font> |
| 1987 |
since ultrix fails to properly preprocess the latter example. |
| 1988 |
|
| 1989 |
|
| 1990 |
<p><li> ConvexOS convex C210 11.0 convex |
| 1991 |
<p> |
| 1992 |
In a program with a C main, output to <tt>LUN=6=*</tt> from <i>FORTRAN</i> |
| 1993 |
goes into |
| 1994 |
<tt>$pwd/fort.6</tt> instead of stdout. |
| 1995 |
Presumably, a magic incantation can be called |
| 1996 |
from the C main in order to properly initialize the <i>FORTRAN</i> I/O. |
| 1997 |
|
| 1998 |
|
| 1999 |
<p><li> SunOS 5.3 Generic_101318-69 sun4m sparc |
| 2000 |
<p> |
| 2001 |
The default data and code alignments produced by cc, gcc and <tt>f77</tt> are compatible. |
| 2002 |
If deviating from the defaults, consistent alignment options must be used |
| 2003 |
across all objects compiled by cc and <tt>f77</tt>. [Does gcc provide such options?] |
| 2004 |
|
| 2005 |
|
| 2006 |
<p><li> <tt>SunOS 5.3 Generic_101318-69 sun4m sparc</tt> with |
| 2007 |
<tt>cc: SC3.0.1 13 Jul 1994</tt> |
| 2008 |
or equivalently |
| 2009 |
<tt>ULTRIX 4.4 0 RISC</tt> using <tt>cc -oldc</tt> |
| 2010 |
are K&R C preprocessors that suffer from infinite loop macros, e.g. |
| 2011 |
|
| 2012 |
<FONT COLOR="#993300"><pre> |
| 2013 |
zedy03> cat src.c |
| 2014 |
#include <cfortran.h> |
| 2015 |
PROTOCCALLSFFUN1(INT,FREV,frev, INTV) |
| 2016 |
#define FREV(A1) CCALLSFFUN1( FREV,frev, INTV, A1) |
| 2017 |
/* To avoid the problem, deletete these ---^^^^--- spaces. */ |
| 2018 |
main() { static int a[] = {1,2}; FREV(a); return EXIT_SUCCESS; } |
| 2019 |
|
| 2020 |
zedy03> cc -c -Xs -v -DMAX_PREPRO_ARGS=31 -D__CF__KnR src.c |
| 2021 |
"src.c", line 4: FREV: actuals too long |
| 2022 |
"src.c", line 4: FREV: actuals too long |
| 2023 |
.... 3427 more lines of the same message |
| 2024 |
"src.c", line 4: FREV: actuals too long |
| 2025 |
cc : Fatal error in /usr/ccs/lib/cpp |
| 2026 |
Segmentation fault (core dumped) |
| 2027 |
</pre></font> |
| 2028 |
|
| 2029 |
|
| 2030 |
<p><li> Older sun C compilers |
| 2031 |
<p> |
| 2032 |
To link to <tt>f77</tt> objects, older sun C compilers require the <tt>math.h</tt> macros: |
| 2033 |
|
| 2034 |
<FONT COLOR="#993300"><pre> |
| 2035 |
#define RETURNFLOAT(x) { union {double _d; float _f; } _kluge; \ |
| 2036 |
_kluge._f = (x); return _kluge._d; } |
| 2037 |
#define ASSIGNFLOAT(x,y) { union {double _d; float _f; } _kluge; \ |
| 2038 |
_kluge._d = (y); x = _kluge._f; } |
| 2039 |
</pre></font> |
| 2040 |
|
| 2041 |
Unfortunately, in at least some copies of the sun |
| 2042 |
<tt>math.h</tt>, the semi-colon |
| 2043 |
for <tt>'float _f;'</tt> is left out, leading to compiler warnings. |
| 2044 |
<p> |
| 2045 |
The solution is to correct <tt>math.h</tt>, |
| 2046 |
or to change <tt>cfortran.h</tt> to <tt>#define</tt> |
| 2047 |
<tt>RETURNFLOAT(x)</tt> and <tt>ASSIGNFLOAT(x,y)</tt> instead of including |
| 2048 |
<tt>math.h</tt>. |
| 2049 |
|
| 2050 |
<a name="gcctrad"></a> |
| 2051 |
<p><li> gcc version 2.6.3 and probably all other versions as well: |
| 2052 |
<p> |
| 2053 |
Unlike all other C compilers supported by <tt>cfortran.h</tt>, |
| 2054 |
<tt>'gcc -traditional'</tt> promotes to double all functions returning float |
| 2055 |
as demonstrated by the following example. |
| 2056 |
|
| 2057 |
<FONT COLOR="#993300"><pre> |
| 2058 |
/* m.c */ |
| 2059 |
#include <stdio.h> |
| 2060 |
int main() { FLOAT_FUNCTION d(); float f; f = d(); printf("%f\n",f); return 0; } |
| 2061 |
|
| 2062 |
/* d.c */ |
| 2063 |
float d() { return -123.124; } |
| 2064 |
|
| 2065 |
burow[29] gcc -c -traditional d.c |
| 2066 |
burow[30] gcc -DFLOAT_FUNCTION=float m.c d.o && a.out |
| 2067 |
0.000000 |
| 2068 |
burow[31] gcc -DFLOAT_FUNCTION=double m.c d.o && a.out |
| 2069 |
-123.124001 |
| 2070 |
burow[32] |
| 2071 |
</pre></font> |
| 2072 |
|
| 2073 |
Thus, <tt>'gcc -traditional'</tt> is not supported by <tt>cfortran.h</tt>. |
| 2074 |
Support would require the same <tt>RETURNFLOAT</tt>, etc. macro machinery |
| 2075 |
present in old sun <tt>math.h</tt>, before sun gave up the same promotion. |
| 2076 |
|
| 2077 |
<p> |
| 2078 |
<b>Aside</b>: The Visual C++ compiler is happy with UN, but barfs on (UN), |
| 2079 |
so either (UN) causes nonstandard C/C++ or Visual C++ is broken. |
| 2080 |
</ol> |
| 2081 |
|
| 2082 |
<h2>VII) History and Acknowledgements</h2> |
| 2083 |
|
| 2084 |
<table border=1> |
| 2085 |
<tr><td> 1.0 </td><td> |
| 2086 |
<ul> |
| 2087 |
<li> Supports VAX VMS using C 3.1 and <i>FORTRAN</i> 5.4. |
| 2088 |
</ul> |
| 2089 |
</td><td>Oct. '90.</td></tr> |
| 2090 |
<tr><td> 1.0 </td><td> |
| 2091 |
<ul> |
| 2092 |
<li> Supports Silicon Graphics w. Mips Computer 2.0 <tt>f77</tt> and cc. |
| 2093 |
[Port of C calls <i>FORTRAN</i> half only.] |
| 2094 |
</ul> |
| 2095 |
</td><td>Feb. '91.</td></tr> |
| 2096 |
<tr><td> 1.1 </td><td> |
| 2097 |
<ul> |
| 2098 |
<li> Supports Mips Computer System 2.0 <tt>f77</tt> and cc. |
| 2099 |
[Runs on at least: Silicon Graphics IRIX 3.3.1 |
| 2100 |
DECstations with Ultrix V4.1] |
| 2101 |
</ul> |
| 2102 |
</td><td>Mar. '91.</td></tr> |
| 2103 |
<tr><td> 1.2 </td><td> |
| 2104 |
<ul> |
| 2105 |
<li> Internals made simpler, smaller, faster, stronger. |
| 2106 |
<li> Mips version works on IBM RS/6000, this is now called the unix version. |
| 2107 |
</ul> |
| 2108 |
</td><td>May '91.</td></tr> |
| 2109 |
<tr><td> 1.3 </td><td> |
| 2110 |
<ul> |
| 2111 |
<li> UNIX and VAX VMS versions are merged into a single <tt>cfortran.h</tt>. |
| 2112 |
<li> C can help manipulate (arrays of) strings in <i>FORTRAN</i> common blocks. |
| 2113 |
<li> Dimensions of string arrays arguments can be explicit. |
| 2114 |
</ul> |
| 2115 |
</td><td>July '91.</td></tr> |
| 2116 |
<tr><td> 2.0 </td><td> |
| 2117 |
<ul> |
| 2118 |
<li> Improved code generation machinery creates K&R or ANSI C. |
| 2119 |
<li> Supports Sun<tt>f2c</tt> with vcc on VAX Ultrix. |
| 2120 |
<li> <tt>cfortran.h</tt> macros now require routine and COMMON block names in both |
| 2121 |
upper and lower case. No changes required to applications though. |
| 2122 |
<li> PROTOCCALLSFSUBn is eliminated, with no loss to <tt>cfortran.h</tt> performance. |
| 2123 |
<li> Improved tools and guidelines for naming C routines called by <i>FORTRAN</i>. |
| 2124 |
</ul> |
| 2125 |
</td><td>Aug. '91.</td></tr> |
| 2126 |
<tr><td> 2.1 </td><td> |
| 2127 |
<ul> |
| 2128 |
<li> <tt>LOGICAL</tt> correctly supported across all machines. |
| 2129 |
<li> HP9000 fully supported. |
| 2130 |
<li> VAX Ultrix cc or gcc with <tt>f77</tt> now supported. |
| 2131 |
</ul> |
| 2132 |
</td><td>Oct. '91.</td></tr> |
| 2133 |
<tr><td> 2.2 </td><td> |
| 2134 |
<ul> |
| 2135 |
<li> SHORT, i.e. INTEGER*2, and BYTE now supported. |
| 2136 |
<li> <tt>LOGICAL_STRICT</tt> introduced. More compact and robust internal tables. |
| 2137 |
<li> typeV and typeVV for type = BYTE, DOUBLE, FLOAT, INT, <tt>LOGICAL</tt>, LONG, LONGLONG, SHORT. |
| 2138 |
<li> <i>FORTRAN</i> passing strings and NULL pointer to C routines improved. |
| 2139 |
</ul> |
| 2140 |
</td><td>Dec. '91.</td></tr> |
| 2141 |
<tr><td> 2.3 </td><td> |
| 2142 |
<ul> |
| 2143 |
<li> Extraneous arguments removed from many internal tables. |
| 2144 |
<li> Introduce pseudo argument type SIMPLE for user defined types. |
| 2145 |
<li> LynxOS using <tt>f2c</tt> supported. (Tested with LynxOS 2.0 386/AT.) |
| 2146 |
</ul> |
| 2147 |
</td><td>May '92.</td></tr> |
| 2148 |
<tr><td> 2.4 </td><td> |
| 2149 |
<ul> |
| 2150 |
<li> Separation of internal C and <i>FORTRAN</i> compilation directives. |
| 2151 |
<li> <tt>f2c</tt> and NAG f90 supported on all machines. |
| 2152 |
</ul> |
| 2153 |
</td><td>Oct. '92.</td></tr> |
| 2154 |
<tr><td> 2.5 </td><td> |
| 2155 |
<ul> |
| 2156 |
<li> Minor mod.s to source and/or doc for HP9000, <tt>f2c</tt>, and NAG f90. |
| 2157 |
</ul> |
| 2158 |
</td><td>Nov. '92.</td></tr> |
| 2159 |
<tr><td> 2.6 </td><td> |
| 2160 |
<ul> |
| 2161 |
<li> Support external procedures as arguments with type ROUTINE. |
| 2162 |
</ul> |
| 2163 |
</td><td>Dec. '92.</td></tr> |
| 2164 |
<tr><td> 2.7 </td><td> |
| 2165 |
<ul> |
| 2166 |
<li> Support Alpha VMS. Support HP9000 f77 +ppu |
| 2167 |
<li> Support arrays with up to 7 dimensions. |
| 2168 |
<li> Minor mod. of <i>FORTRAN</i> NULL to C via (P)STRING. |
| 2169 |
<li> Specify the type of ROUTINE passed from <i>FORTRAN</i> to C [ANSI C requirement.] |
| 2170 |
<li> Macros never receive a null parameter [RS/6000 requirement.] |
| 2171 |
</ul> |
| 2172 |
</td><td>Jan. '93.</td></tr> |
| 2173 |
<tr><td> 2.8 </td><td> |
| 2174 |
<ul> |
| 2175 |
<li> <tt>PSTRING</tt> for <i>FORTRAN</i> calls C no longer provides escape to pass |
| 2176 |
NULL pointer nor to pass address of original string. |
| 2177 |
PNSTRING introduced with old <tt>PSTRING</tt>'s behavior. |
| 2178 |
PPSTRING introduced to always pass original address of string. |
| 2179 |
<li> Support Alpha/OSF. |
| 2180 |
<li> Document that common blocks used in C should be declared AND defined. |
| 2181 |
</ul> |
| 2182 |
</td><td>April'93.</td></tr> |
| 2183 |
<tr><td> 3.0 </td><td> |
| 2184 |
<ul> |
| 2185 |
<li> Automagic handling of ANSI ## versus K&R /**/ preprocessor op. |
| 2186 |
<li> Less chance of name space collisions between <tt>cfortran.h</tt> and other codes. |
| 2187 |
<li> SIMPLE macros, supporting user defined types, have changed names. |
| 2188 |
</ul> |
| 2189 |
</td><td>March'95.</td></tr> |
| 2190 |
<tr><td> 3.1 </td><td> |
| 2191 |
<ul> |
| 2192 |
<li> Internal macro name _INT not used. Conflicted with IRIX 5.3. |
| 2193 |
<li> SunOS, all versions, should work out of the box. |
| 2194 |
<li> ZTRINGV_ARGS|F(k) may no longer point to a PDOUBLE or PFLOAT argument. |
| 2195 |
<li> ConvexOS 11.0 supported. |
| 2196 |
</ul> |
| 2197 |
</td><td>May '95.</td></tr> |
| 2198 |
<tr><td> 3.2 </td><td> |
| 2199 |
<ul> |
| 2200 |
<li> __hpux no longer needs to be restricted to MAX_PREPRO_ARGS=31. |
| 2201 |
<li> <tt>PSTRING</tt> bug fixed. |
| 2202 |
<li> ZTRINGV_ARGS|F(k) may not point to a PBYTE,PINT,PLONG or PSHORT argument. |
| 2203 |
<li> (P)ZTRINGV machinery improved. Should lead to fewer compiler warnings. |
| 2204 |
(P)ZTRINGV no longer limits recursion or the nesting of routines. |
| 2205 |
<li> SIMPLE macros, supporting user defined types, have changed slightly. |
| 2206 |
</ul> |
| 2207 |
</td><td>Oct. '95.</td></tr> |
| 2208 |
<tr><td> 3.3 </td><td> |
| 2209 |
<ul> |
| 2210 |
<li> Supports PowerStation <i>FORTRAN</i> with Visual C++. |
| 2211 |
<li> g77 should work using f2cFortran, though no changes made for it. |
| 2212 |
<li> (PROTO)CCALLSFFUN10 extended to (PROTO)CCALLSFFUN14. |
| 2213 |
<li> FCALLSCFUN10 and SUB10 extended to FCALLSCFUN14 and SUB14. |
| 2214 |
</ul> |
| 2215 |
</td><td>Nov. '95.</td></tr> |
| 2216 |
<tr><td> 3.4 </td><td> |
| 2217 |
<ul> |
| 2218 |
<li> C++ supported, |
| 2219 |
but it required the reintroduction of PROTOCCALLSFSUBn for users. |
| 2220 |
<li> HP-UX f77 +800 supported. |
| 2221 |
</ul> |
| 2222 |
</td><td>Dec. '95.</td></tr> |
| 2223 |
<tr><td> 3.5 </td><td> |
| 2224 |
<ul> |
| 2225 |
<li> Absoft UNIX <i>FORTRAN</i> supported. |
| 2226 |
</ul> |
| 2227 |
</td><td>Sept.'96.</td></tr> |
| 2228 |
<tr><td> 3.6 </td><td> |
| 2229 |
<ul> |
| 2230 |
<li> Minor corrections to cfortran.doc. |
| 2231 |
<li> Fixed bug for 15th argument. [Thanks to Tom Epperly at Aspen Tech.] |
| 2232 |
<li> For AbsoftUNIXFortran, obey default of prepending _C to COMMON BLOCK name. |
| 2233 |
<li> <i>FORTRAN</i> calling C with ROUTINE argument fixed and cleaned up. |
| 2234 |
</ul> |
| 2235 |
</td><td>Oct. '96.</td></tr> |
| 2236 |
<tr><td> 3.7 </td><td> |
| 2237 |
<ul> |
| 2238 |
<li> Circumvent IBM and HP "null argument" preprocessor warning. |
| 2239 |
</ul> |
| 2240 |
</td><td>Oct. '96</td></tr> |
| 2241 |
<tr><td> 3.8 </td><td> |
| 2242 |
<ul> |
| 2243 |
<li> (P)STRINGV and (P)ZTRINGV can pass a 1- or 2-dim. char array. |
| 2244 |
(P)ZTRINGV thus effectively also provides (P)ZTRING. |
| 2245 |
<li> (P)ZTRINGV accepts a (char *) pointer. |
| 2246 |
</ul> |
| 2247 |
</td><td>Feb. '97</td></tr> |
| 2248 |
<tr><td> 3.9 </td><td> |
| 2249 |
<ul> |
| 2250 |
<li> Bug fixed for *VVVVV. |
| 2251 |
<li> <tt>f2c</tt>: Work-around for strange underscore-dependent naming feature. |
| 2252 |
<li> NEC SX-4 supported. |
| 2253 |
<li> CRAY: Avoid bug of some versions of the C preprocessor. |
| 2254 |
<li> CRAY T3E: FORTRAN_REAL introduced. |
| 2255 |
</ul> |
| 2256 |
</td><td>May '97</td></tr> |
| 2257 |
<tr><td> 4.0 </td><td> |
| 2258 |
<ul> |
| 2259 |
<li> new/delete now used for C++. malloc/free still used for C. |
| 2260 |
<li> FALSE no longer is defined by <tt>cfortran.h</tt> . |
| 2261 |
<li> Absoft Pro <i>FORTRAN</i> for MacOS supported. |
| 2262 |
</ul> |
| 2263 |
</td><td>Jan. '98</td></tr> |
| 2264 |
<tr><td> 4.1 </td><td> |
| 2265 |
<ul> |
| 2266 |
<li> COMMA and COLON no longer are defined by <tt>cfortran.h</tt> . |
| 2267 |
<li> Bug fixed when 10th arg. or beyond is a string. |
| 2268 |
[Rob Lucchesi of NASA-Goddard pointed out this bug.] |
| 2269 |
<li> CCALLSFSUB/FUN extended from 14 to 27 arguments. |
| 2270 |
<li> Workaround SunOS CC 4.2 cast bug. [Thanks to Savrak SAR of <b>CERN</b>.] |
| 2271 |
</ul> |
| 2272 |
</td><td>April'98</td></tr> |
| 2273 |
<tr><td> 4.2 </td><td> |
| 2274 |
<ul> |
| 2275 |
<li> Portland Group needs -DpgiFortran . [Thank George Lai of NASA.] |
| 2276 |
</ul> |
| 2277 |
</td><td>June '98</td></tr> |
| 2278 |
<tr><td> 4.3 </td><td> |
| 2279 |
<ul> |
| 2280 |
<li> (PROTO)CCALLSFSUB extended from 20 to 27 arguments. |
| 2281 |
</ul> |
| 2282 |
</td><td>July '98</td></tr> |
| 2283 |
</table> |
| 2284 |
<p> |
| 2285 |
['Support' implies these and more recent releases of the respective |
| 2286 |
OS/compilers/linkers can be used with <tt>cfortran.h</tt>. |
| 2287 |
Earlier releases may also work.] |
| 2288 |
|
| 2289 |
<p> |
| 2290 |
<center><b>Acknowledgements</b></center> |
| 2291 |
<ul> |
| 2292 |
<li> <b>CERN</b> very generously sponsored a week in 1994 for me to work on <tt>cfortran.h</tt>. |
| 2293 |
<li> M.L.Luvisetto (Istituto Nazionale Fisica Nucleare - Centro Nazionale |
| 2294 |
Analisi Fotogrammi, Bologna, Italy) provided all the support for the port to |
| 2295 |
the CRAY. Marisa's encouragement and enthusiasm was also much appreciated. |
| 2296 |
<li> J.Bunn (<b>CERN</b>) supported the port to PowerStation <i>FORTRAN</i> with Visual C++. |
| 2297 |
<li> Paul Schenk (UC Riverside, <b>CERN</b> PPE/OPAL) in June 1993 extended <tt>cfortran.h</tt> 2.7 |
| 2298 |
to have C++ call <i>FORTRAN</i>. This was the starting point for full C++ in 3.4. |
| 2299 |
<li> Glenn P.Davis of University Corp. for Atmospheric Research (UCAR) / Unidata |
| 2300 |
supported the NEC SX-4 port and helped understand the CRAY. |
| 2301 |
<li> Tony Goelz of Absoft Corporation ported <tt>cfortran.h</tt> to Absoft. |
| 2302 |
<li> Though <tt>cfortran.h</tt> has been created in my 'copious' free time, I thank |
| 2303 |
NSERC for their generous support of my grad. student and postdoc years. |
| 2304 |
<li> Univ.Toronto, DESY, <b>CERN</b> and others have provided time on their computers. |
| 2305 |
<li> The HTML version of the <tt>cfortran.h</tt> documentation has been made by |
| 2306 |
Olivier Couet <tt>[email protected]</tt>. |
| 2307 |
</ul> |
| 2308 |
|
| 2309 |
<FONT COLOR="#993300"><pre> |
| 2310 |
THIS PACKAGE, I.E. CFORTRAN.H, THIS DOCUMENT, AND THE CFORTRAN.H EXAMPLE |
| 2311 |
PROGRAMS ARE PROPERTY OF THE AUTHOR WHO RESERVES ALL RIGHTS. THIS PACKAGE AND |
| 2312 |
THE CODE IT PRODUCES MAY BE FREELY DISTRIBUTED WITHOUT FEES, SUBJECT |
| 2313 |
(AT YOUR CHOICE) EITHER TO THE <a href = "file:///usr/share/common-licenses/LGPL">GNU LIBRARY GENERAL PUBLIC LICENSE</a> OR TO THE |
| 2314 |
FOLLOWING RESTRICTIONS: |
| 2315 |
- YOU MUST ACCOMPANY ANY COPIES OR DISTRIBUTION WITH THIS (UNALTERED) NOTICE. |
| 2316 |
- YOU MAY NOT RECEIVE MONEY FOR THE DISTRIBUTION OR FOR ITS MEDIA |
| 2317 |
(E.G. TAPE, DISK, COMPUTER, PAPER.) |
| 2318 |
- YOU MAY NOT PREVENT OTHERS FROM COPYING IT FREELY. |
| 2319 |
- YOU MAY NOT DISTRIBUTE MODIFIED VERSIONS WITHOUT CLEARLY DOCUMENTING YOUR |
| 2320 |
CHANGES AND NOTIFYING THE AUTHOR. |
| 2321 |
- YOU MAY NOT MISREPRESENTED THE ORIGIN OF THIS SOFTWARE, EITHER BY EXPLICIT |
| 2322 |
CLAIM OR BY OMISSION. |
| 2323 |
|
| 2324 |
THE INTENT OF THE ABOVE TERMS IS TO ENSURE THAT THE CFORTRAN.H PACKAGE NOT BE |
| 2325 |
USED FOR PROFIT MAKING ACTIVITIES UNLESS SOME ROYALTY ARRANGEMENT IS ENTERED |
| 2326 |
INTO WITH ITS AUTHOR. |
| 2327 |
|
| 2328 |
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER |
| 2329 |
EXPRESSED OR IMPLIED. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE |
| 2330 |
SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST |
| 2331 |
OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. THE AUTHOR IS NOT RESPONSIBLE |
| 2332 |
FOR ANY SUPPORT OR SERVICE OF THE CFORTRAN.H PACKAGE. |
| 2333 |
|
| 2334 |
Burkhard Burow |
| 2335 |
[email protected] |
| 2336 |
</pre></font> |
| 2337 |
P.S. Your comments and questions are welcomed and usually promptly answered. |
| 2338 |
<br> |
| 2339 |
VAX VMS and Ultrix, Alpha, OSF, Silicon Graphics (SGI), DECstation, Mips RISC, |
| 2340 |
Sun, CRAY, Convex, IBM RS/6000, Apollo DomainOS, HP, LynxOS, <tt>f2c</tt>, NAG, Absoft, |
| 2341 |
NEC SX-4, PowerStation and Visual C++ are registered trademarks of their |
| 2342 |
respective owners. |