CFORTRAN 2.1 : Interfacing C and FORTRAN 0 Abstract ---------- This is a draft of the article which will accompany the introduction of CFORTRAN into the CERN PROGRAM LIBRARY, Release 204. cfortran.h with its accompanying documentation and examples are currently available by anonymous ftp at: zebra.desy.de [131.169.2.244] 1 Introduction -------------- CFORTRAN provides tools to help create an easy-to-use and machine independent interface between C and FORTRAN routines and global data. FORTRAN routines and global data can now be used as easily from C as they can from FORTRAN. Similarly FORTRAN programmers can now use C routines and global data just as easily as FORTRAN routines and data. In short, even without a deep understanding of the 'foreign' language, programmers can trivially call routines and use data from the 'foreign' language. The interface which gives programmers the above freedoms is easily created. The source code for the 'foreign' routines and data is not required; a description of the global data and of the routines' arguments and return values is sufficient. The interface can be created with little or no knowledge of any machine/OS/compiler/linker subtleties. The description of the routines and data is passed as arguments to C preprocessor directives, defined in cfortran.h, which generate the code needed for the interface. Note that there are no special preprocessors or other programs involved in creating the interface. The complete CFORTRAN package consists of 4 files: the documentation in cfortran.doc, the engine in cfortran.h, examples in cfortest.c and cfortex.for. The single cfortran.h file currently supports the following machines/OS: VAX VMS or Ultrix, DECstation, Silicon Graphics, IBM RS/6000, Sun, CRAY, Apollo and HP9000. 2 The Interface --------------- CFORTRAN's main aim is to provide the 'best' possible interface between the two languages. 'Best' implies that it is complete and easy, perhaps even trivially easy. Global data is fairly easily interfaced across C and FORTRAN. cfortran.h provides machinery to help make the interface machine independant, but the largest part of the interface, mapping C structures onto FORTRAN COMMON blocks, is left open. CFORTRAN can only, in cfortex.for and cfortest.c, give examples of how this mapping may be done. CFORTRAN also provides routines for C to insert/extract strings to/from FORTRAN COMMON blocks. CFORTRAN's emphasis is on the interface for routines, where it is quite complete; providing for the most common types of numeric and character arguments and return values. New types are easily added and can even be defined outside of cfortran.h. C's interface to FORTRAN routines has been designed to mimic the original FORTRAN call. This places C programmers on equal footing with FORTRAN programmers when calling FORTRAN routines. e.g. C programmers can follow and easily try out the examples of the original documentation written for FORTRAN programmers. The following example, calling HBOOK1, should demonstrate how closely CFORTRAN imitates the original FORTRAN call. HBOOK1(1,"pT spectrum of pi+",100,0.,5.,0.); /* C */ CALL HBOOK1(1,'pT spectrum of pi+',100,0.,5.,0.) ! FORTRAN The FORTRAN interface to C routines provides the machinery to convert the limited number of FORTRAN argument types into the large variety given by C. This implies that no C routines are 'out of reach' for FORTRAN, and even exotic arguments such the value of a structure can be passed via a CFORTRAN interface. 3 Creating the Interface ------------------------ The interface described in the brief outline above hopefully meets most requirements. Equally important is the fact that the interface is easily created. This ease is demonstrated by the C interface to CERN's HBOOK library of routines, contained entirely in the C header file hbook.h. The following excerpt shows how the interface to HBOOK1 is defined. /* hbook.h */ #include "cfortran.h" : #define HBOOK1(ID,CHTITLE,NX,XMI,XMA,VMX) \ CCALLSFSUB6(HBOOK1,hbook1,INT,STRING,INT,FLOAT,FLOAT,FLOAT, \ ID,CHTITLE,NX,XMI,XMA,VMX) : /* end hbook.h */ To use the interface to HBOOK, C programmers merely #include "hbook.h" at the top of their source code. Please note that hbook.h was created following only the [admittedly excellent] HBOOK documentation, without even a single peek at any HBOOK source code. Creating an interface for FORTRAN to C routines is similar. For example, to access C's memcpy routine, the following file would be compiled, and linked with the FORTRAN code and the library containing memcpy. /* string.c */ #include /* string.h prototypes memcpy() */ #include "cfortran.h" FCALLSCSUB3(memcpy,MEMCPY,memcpy,PVOID,PVOID,INT) and a FORTRAN call would look like: CALL MEMCPY(I,J,7) In reality, we would probably also want to also set up in string.c the other routines described by string.h. Note that when we compile string.c, FCALLSCSUB3(...), is expanded into a 'wrapper' function, so called because it is wrapped around the original C function and interfaces the format of the original C functions arguments and return value with the format of the FORTRAN call. 4 Getting Started ----------------- cfortran.doc provides fairly extensive documentation for CFORTRAN, and perhaps more importantly it lists the few simple commands needed to run the examples in cfortest.c and cfortex.for on the variety of machine supported. Although the examples are slightly more complicated than really necessary, they are nonetheless probably the best place to start understanding what CFORTRAN does. Users of interfaces created with CFORTRAN, e.g. hbook.h, can perhaps get by with the information in this note, but a casual knowledge of the information in cfortran.doc is probably desirable. Those wishing to create interfaces using CFORTRAN will have to become familiar with most of the information in cfortran.doc, especially the description of the set of types available for routines' arguments and return values. cfortran.doc also presents many of the constraints that have to be met in order to create an interface that is portable across the variety of machines supported by cfortran.h. Understanding cfortran.h is required only by those who wish to support a new type of argument or return value or by those who wish to port cfortran.h to another machine. B.Burow/University of Toronto burow@vxdesy.cern.ch