next up previous contents
Next: Checking the integrity of Up: Creating a new interface Previous: General procedure for Fortran   Contents


Interfacing packages written in C: cuter.h

We comment in this section the possibility of interfacing packages originally written in C with CUTEr. As of yet, the LOQO interface is the only one written in C, but it is hoped that given the growing interest in C/C++ optimization packages, this number is meant to increase.

The new subdirectory include of $CUTER/common hosts the C header file cuter.h containing various declarations related to the coexistence of object files originating from Fortran and C source files, and simplifying calling sequences to the CUTEr tools from C. All the definition in this header file may be accessed by specifying

#include{cuter.h}

at the top of your C driver.

We now briefly describe the header file cuter.h and the apparent prototypes of the CUTEr tools, as seen from the C language.

Partly inspired by f2c.h, cuter.h defines the types

typedef long int integer;
typedef float    real;
typedef double   doublereal;
typedef long int logical;

meant to imitate the corresponding Fortran data types. Users may then define variables of type doublereal when having in mind a corresponding Fortran 77 variable or argument of type double precision, or a Fortran 90 variable or argument of type real whose kind is that of 1.0D+0.

It also defines the two macros

#define FALSE_ (0)
#define TRUE_  (1)

simulating the two possible values for Fortran variables of type logical. Note the trailing underscores.

In CUTEr, positive or negative infinite values are achieved by any number larger in modulus than $10^{20}$, hence the definition

#define CUTE_INF 1e20

in cuter.h.

For convenience, and to account for the differences between the plethora of Fortran and C compilers out there, common apparent prototypes for the CUTEr tools have been defined in cuter.h. These apparent prototypes follow the general pattern

TOOLNAME( arg1, arg2, $\ldots$, argn )

where the tool name TOOLNAME must be specified in uppercase letters. Caution should be exercised when specifying the arguments of a routine, given the fact that to interface Fortran and C, all the arguments appearing in the argument list should be pointers. In practice, this has the consequence that integer variables appearing in an argument list in the driver should be declared as

integer *variable_name;

instead of

integer variable_name;

As is always the case in C, the exception to this is arrays, since they are always treated as pointers. Thus, for instance, a reference to the CUTEr tool CSH with the help of cuter.h appears as

CSH( &n, &m, x, &m, v, &nnzh, &lh, h, irnh, icnh );

with the declarations

integer *n, *m, *nnzh, *lh, *irnh, *icnh;
doublereal *x, *v, *h;

Note that in these declarations, irnh, icnh, x, v and h are arrays, while the other variables simulate Fortran integer variables. This is the reason why the addresses of the latter variables appear explicitly in the calling sequence to CSH, while the arrays appear as if they were the ``real'' Fortran arguments.

The calling sequences of most tools are exactly as in Fortran--they can be seen by typing

prompt% man toolname

at the command prompt. The prototypes say that the CUTEr tools all return a void ouput.

One notable difference between Fortran and C is the way external files are handled. C uses streams while Fortran requires that a unit number be associated to each open file. To account for this difference, and as the unit number is required by several CUTEr tools, the two functions FORTRAN_OPEN and FORTRAN_CLOSE have been defined, with apparent prototypes

void FORTRAN_OPEN( integer *funit, char *fname, integer *ierr );
void FORTRAN_CLOSE( integer *funit, integer *ierr );

funit being the unit number associated to the file, and ierr being the error code returned by these functions, a value of zero indicating a successful operation. These two functions may be called to open and close the OUTSDIF.d file generated by the SIF decoder.


next up previous contents
Next: Checking the integrity of Up: Creating a new interface Previous: General procedure for Fortran   Contents
Dominique Orban 2005-03-24