Debian Codegraph @

README.html

raw
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&gt; CC +p +w # Clean compiles.
30 IRIX&gt; CC # Clean compiles.
31 IRIX&gt; CC -fullwarn # Still some warnings to be overcome.
32 GNU&gt; 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&gt; cat f.f
144 END
145 unix&gt; 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&gt; # Users are strongly urged to use f77 -qextname and cc -Dextname
162 RS/6000&gt; # Use -Dextname=extname if extname is a symbol used in the C code.
163 RS/6000&gt; xlf -c -qextname cfortex.f
164 RS/6000&gt; cc -c -Dextname cfortest.c
165 RS/6000&gt; xlf -o cfortest cfortest.o cfortex.o &amp;&amp; cfortest
166
167 DECFortran&gt; #Only DECstations with DECFortran for Ultrix RISC Systems.
168 DECFortran&gt; cc -c -DDECFortran cfortest.c
169 DECFortran&gt; f77 -o cfortest cfortest.o cfortex.f &amp;&amp; cfortest
170
171 IRIX xxxxxx 5.2 02282015 IP20 mips
172 MIPS&gt; # DECstations and Silicon Graphics using the MIPS compilers.
173 MIPS&gt; cc -o cfortest cfortest.c cfortex.f -lI77 -lU77 -lF77 &amp;&amp; cfortest
174 MIPS&gt; # Can also let f77 drive linking, e.g.
175 MIPS&gt; cc -c cfortest.c
176 MIPS&gt; f77 -o cfortest cfortest.o cfortex.f &amp;&amp; cfortest
177
178 VMS&gt; define lnk$library sys$library:vaxcrtl
179 VMS&gt; cc cfortest.c
180 VMS&gt; fortran cfortex.for
181 VMS&gt; link/exec=cfortest cfortest,cfortex
182 VMS&gt; run cfortest
183
184 OSF1 xxxxxx V3.0 347 alpha
185 Alpha/OSF&gt; # Probably better to let cc drive linking, e.g.
186 Alpha/OSF&gt; f77 -c cfortex.f
187 Alpha/OSF&gt; cc -o cfortest cfortest.c cfortex.o -lUfor -lfor -lFutil -lots -lm
188 Alpha/OSF&gt; cfortest
189 Alpha/OSF&gt; # Else may need 'cc -Dmain=MAIN__' to let f77 drive linking.
190
191 Sun&gt; # Some old cc(1) need a little help. <a href="cfortran.html#SIIoSun">[See Section II o) Notes: Sun]</a>
192 Sun&gt; f77 -o cfortest cfortest.c cfortex.f -lc -lm &amp;&amp; cfortest
193 Sun&gt; # Some older f77 may require 'cc -Dmain=MAIN_'.
194
195 NEC&gt; cc -c -Xa cfortest.c
196 NEC&gt; f77 -o cfortest cfortest.o cfortex.f &amp;&amp; cfortest
197
198 LynxOS&gt; # In the following, 'CC' is either 'cc' or 'gcc -ansi'.
199 LynxOS&gt; # Unfortunately cc is easily overwhelmed by cfortran.h,
200 LynxOS&gt; # and won't compile some of the cfortest.c demos.
201 LynxOS&gt; f2c -R cfortex.f
202 LynxOS&gt; CC -Dlynx -o cfortest cfortest.c cfortex.c -lf2c &amp;&amp; cfortest
203
204 HP9000&gt; # Tested with HP-UX 7.05 B 9000/380 and with A.08.07 A 9000/730
205 HP9000&gt; # CC may be either 'c89 -Aa' or 'cc -Aa'
206 HP9000&gt; # Depending on the compiler version, you may need to include the
207 HP9000&gt; # option '-tp,/lib/cpp' or worse, you'll have to stick to the K&amp;R C.
208 HP9000&gt; # <a href="cfortran.html#SIIoHP9000">[See Section II o) Notes: HP9000]</a>
209 HP9000&gt; # Users are strongly urged to use f77 +ppu and cc -Dextname
210 HP9000&gt; # Use -Dextname=extname if extname is a symbol used in the C code.
211 HP9000&gt; CC -Dextname -c cfortest.c
212 HP9000&gt; f77 +ppu cfortex.f -o cfortest cfortest.o &amp;&amp; cfortest
213 HP9000&gt; # Older f77 may need
214 HP9000&gt; f77 -c cfortex.f
215 HP9000&gt; CC -o cfortest cfortest.c cfortex.o -lI77 -lF77 &amp;&amp; cfortest
216
217 HP9000&gt; # If old-style f77 +800 compiled objects are required:
218 HP9000&gt; # #define hpuxFortran800
219 HP9000&gt; cc -c -Aa -DhpuxFortran800 cfortest.c
220 HP9000&gt; f77 +800 -o cfortest cfortest.o cfortex.f
221
222 f2c&gt; # In the following, 'CC' is any C compiler.
223 f2c&gt; f2c cfortex.f
224 f2c&gt; CC -o cfortest -Df2cFortran cfortest.c cfortex.c -lf2c &amp;&amp; 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 &amp;&amp; cfortest
229
230 NAGf90&gt; # cfortex.f is distributed with <i>FORTRAN</i> 77 style comments.
231 NAGf90&gt; # To convert to f90 style comments do the following once to cfortex.f:
232 NAGf90&gt; mv cfortex.f cf_temp.f &amp;&amp; sed 's/^C/\!/g' cf_temp.f &gt; cfortex.f
233 NAGf90&gt; # In the following, 'CC' is any C compiler.
234 NAGf90&gt; CC -c -DNAGf90Fortran cfortest.c
235 NAGf90&gt; f90 -o cfortest cfortest.o cfortex.f &amp;&amp; cfortest
236
237 PC&gt; # On a PC with PowerStation <i>FORTRAN</i> and Visual_C++
238 PC&gt; cl /c cftest.c
239 PC&gt; fl32 cftest.obj cftex.for
240
241 GNU&gt; # GNU <i>FORTRAN</i>
242 GNU&gt; # <a href="cfortran.html#gcctrad">See Section VI caveat on using 'gcc -traditional'</a>.
243 GNU&gt; gcc -ansi -Wall -O -c -Df2cFortran cfortest.c
244 GNU&gt; g77 -ff2c -o cfortest cfortest.o cfortex.f &amp;&amp; cfortest
245
246 AbsoftUNIX&gt; # Absoft <i>FORTRAN</i> for all UNIX based operating systems.
247 AbsoftUNIX&gt; # e.g. Linux or Next on Intel or Motorola68000.
248 AbsoftUNIX&gt; # Absoft f77 -k allows <i>FORTRAN</i> routines to be safely called from C.
249 AbsoftUNIX&gt; gcc -ansi -Wall -O -c -DAbsoftUNIXFortran cfortest.c
250 AbsoftUNIX&gt; f77 -k -o cfortest cfortest.o cfortex.f &amp;&amp; cfortest
251
252 AbsoftPro&gt; # Absoft Pro <i>FORTRAN</i> for MacOS
253 AbsoftPro&gt; # Use #define AbsoftProFortran
254
255 CLIPPER&gt; # INTERGRAPH CLIX using CLIPPER C and <i>FORTRAN</i> compilers.
256 CLIPPER&gt; # N.B. - User, not cfortran.h, is responsible for
257 CLIPPER&gt; # f77initio() and f77uninitio() if required.
258 CLIPPER&gt; # - LOGICAL values are not mentioned in CLIPPER doc.s,
259 CLIPPER&gt; # so they may not yet be correct in cfortran.h.
260 CLIPPER&gt; # - K&amp;R mode (-knr or Ac=knr) breaks FLOAT functions
261 CLIPPER&gt; # (see CLIPPER doc.s) and cfortran.h does not fix it up.
262 CLIPPER&gt; # [cfortran.h ok for old sun C which made the same mistake.]
263 CLIPPER&gt; acc cfortest.c -c -DCLIPPERFortran
264 CLIPPER&gt; 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 &lt;cfortran.h&gt;
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 &lt;cfortran.h&gt;
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 &lt;string.h&gt; /* string.h prototypes memcpy() */
421 #include &lt;cfortran.h&gt;
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&gt; 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&amp;R version of <tt>cfortran.h</tt> must then be used and the
675 K&amp;R preprocessor must be specified. e.g.
676 <FONT COLOR="#993300"><pre>
677 HP9000&gt; 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&amp;R C, as with old HP compilers which don't support function prototyping.
694 <tt>cfortran.h</tt> has to be informed that K&amp;R C is to being used, e.g.
695 <FONT COLOR="#993300"><pre>
696 HP9000&gt; 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 &lt;~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&gt; mv <tt>cfortran.h</tt> cftmp.h &amp;&amp; grep -v "^#pragma" <cftmp.h >cfortran.h
728 sun&gt; mv cfortest.c cftmp.c &amp;&amp; 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 *)(&amp;(x)))
737 #define ASSIGNFLOAT(x,y) *(int *)(&amp;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 &lt;stdio.h&gt;
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-&gt;14 [SUBROUTINE's -&gt;27] (easily expanded in <tt>cfortran.h</tt> to &gt; 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&lt;=n&lt;=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 *) &amp;(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-&gt;27 (easily expanded to &gt; 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> =&gt; 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 &lt;cfortran.h&gt;
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 &lt;cfortran.h&gt;
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-&gt;n.] specifies the argument number of a STRING VECTOR.
1410 j would specify a fixed number of elements.
1411 k [k=1-&gt;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&amp;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> =&gt; 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 &lt;cfortran.h&gt;
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&amp;R ANSI C p. 231:
1942 <FONT COLOR="#993300"><pre>
1943 ultrix&gt; 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&gt; cc -E cat.c
1949 123 &lt;---- Should be: cat(1,2)3
1950 123 &lt;---- Correct.
1951 ultrix&gt;
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&gt; 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&gt; cc -std1 -E c.c
1966 2+2
1967 AB (2) &lt;---- ?????????????
1968 ultrix&gt;
1969 ultrix&gt; cc -std0 -E c.c
1970 2+2
1971 AB(2) &lt;---- ?????????????
1972 ultrix&gt;
1973 </pre></font>
1974
1975 Due to further ultrix preprocessor problems,
1976 for all definitions of definitions with arguments,
1977 <tt>cfortran.h</tt> &gt;= 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&amp;R C preprocessors that suffer from infinite loop macros, e.g.
2011
2012 <FONT COLOR="#993300"><pre>
2013 zedy03&gt; cat src.c
2014 #include &lt;cfortran.h&gt;
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&gt; 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 &lt;stdio.h&gt;
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 &amp;&amp; a.out
2067 0.000000
2068 burow[31] gcc -DFLOAT_FUNCTION=double m.c d.o &amp;&amp; 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&amp;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&amp;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.