NAME

Fcc - Fortran-calls-C

SYNOPSIS

    Fcc [-c] [-h] interface.fcc >interface.c

DESCRIPTION

Given an Fcc interface language file interface.fcc, produces on the standard output a C language file which will create glue routines so that Fortran can call C.

A glue routine is a routine that is called by the Fortran compiler and in turn calls the C routine desired. The glue routine mediates the different naming and argument passing conventions of the two languages, allowing portable source code to be maintained.

OPTIONS

-h
causes a file Fcc.h to be created which is appropriate for the current machine. This file contains correct definitions for using in the C language routines to indicate the types of arguments and return values. It will also define the cpu name for use in ifdefs and defines BYTES_PER_WORD appropriately.

-c
causes the file Fcc.c to be created, which is the file containing the runtime support routines needed by the glue routines created by Fcc. These routines are included in the Basis runtime library so this option is not needed ordinarily.

-cconfig
Full path of file with C compiler configuration information. Typically this file is generated by configcompiler.

-configdir
Path to directory with the configuration files 'compiler-c' and 'compiler-f' The -cconfig and -fconfig options can be used to override the default file names by providing the full paths.

-fconfig
Full path of file with Fortran compiler configuration information Typically this file is generated by configcompiler.

-o
Name of the output file. Default is standard out.

The option -CPU (where CPU is one of SUN4, HP700, YMP, C90, RS6000, CRAY2, SGI, SOL, AXP, CS2, VP2000, or IRIX64) causes Fcc to process its input for the target CPU specified. This primarily affects how the names by which FORTRAN knows the C routines are mangled on a particular CPU.

INTERNAL OPTIONS

Additional options can be specified within the file.

-prototypes
A prototype for each routine called will be written. This is the default.

-noprototypes
No prototypes will be written.

-include quoted string
An include statement will be added for the named string. If the quoted string starts with '<' the quotes will not be written to the output. This option together with -noprototypes allows the user to make sure the routine specifications in the fcc file match the prototypes in the user's header files.

INTERFACE LANGUAGE

An interface file contains a series of descriptions of C routines which are to be called from Fortran. Each of these descriptions has the form:

[return_type] Name(argument_list) [alias ActualCName]

where the square brackets denote optional items.

Name is the name of the C-language routine. It must be a mixed-case name if the alias clause is not given. The Fortran call should be to a routine called name, where name is the lower- or upper-case version of Name. The C routine called will be Name, or ActualCName if an alias clause is present.

argument_list is a (possibly empty) list of type designators separated by commas. This list should be the same length as the argument list of the C routine.

return_type, if present, is a single type designator, or the word 'subroutine'.

A type designator is one of the following: integer, logical, real, real(Size4), real(Size8), real(Size16), Address, void, character, or string. This type designator is preceded by an ampersand in the argument list if the corresponding argument is to be passed by address. The two cases where this is needed are: (a) the argument is an array, or (b) the argument represents an output argument.

The type 'string' is handled in a special way:

(1) If an argument type is 'string', the C routine receives a C string that is a null-terminated copy of the actual argument with trailing blanks deleted.

(2) If an argument type is '&string', the C routine receives a blank, null- terminated string of the same length as the Fortran character variable used as an actual argument. On return from the C routine, the actual argument is filled with whatever resides in the string the C-routine received, less the final null, and is then blank padded if necessary to its full length.

(3) If an argument type is '+string', it is just like '&string' with the addition of passing the string length down after all other arguments.

(4) If an argument type is '*string', only the address is passed down.

The type 'character' is also handled in a special way:

Because some Fortrans limit the size of a string, it is sometimes necessary to use a long array of character*1 to hold all the characters. to pass such an array to C, use 'character' or '&character' as its type; the next argument after a 'character' or '&character' argument must be an integer argument telling how many characters of the character argument are to be used. The C wrapper routines then use the array of character*1 the same as a string of that length, as described above.

If an argument type is '+character', then the address of the string is passed. The string length is passed-by-value as an int following any other arguments. This follows the convention of most fortran compilers. For Cray, the address and length are extracted from the fortran character descriptor then passed explicitly.

Additional string types are:

(1) 'char' pass down string address. same as '*character'.

(2) 'char_num' pass down string address, trimmed length.

(3) 'char_len' pass down string address, actual length. same as '+character'.

(4) 'char_num_len'. pass down string address, trimmed length, actual length.

'void' is always treated as a pointer. It is useful when an address needs to be passed thru the wrapper without being derefereced yet still be a 'void *'. The &Address type can work but results in a 'void **' being declared which may cause compiler warnings if the prototype is not generated but is comming from a users supplied include file.

The type 'real' is an abbreviation for real(Size8), unless the -r4 option has been used, in which case it is an abbreviation for real(Size4). You are encouraged to spell out the desired kind qualifier and not rely on this option. (Which is why we don't mention it in the option section, we were hoping you wouldn't notice.)

ROUTINES

The -c options creates the Fcc.c file which has routines that are used by the wrapper code but may be useful to users as well.

(1) FccCopy(char *a, int la, char *s)

Copy NULL terminated s to buffer pointed to by a which is la long. If s is shorter than la, then a will be blank filled.

(2) FccLenTrim(char *s, int ls)

Return the length of s, which is ls long, with trailing blanks removed.

(3) FccAssign(char *a, int la, char *s, int ls)

Performs the equivalent of a string assignment in fortran. Copies as much of s into a. Blank fill a if necessary.

(4) FccBlank(char *s, int ls)

Fill s with blanks. Implemented as a macro.

RESTRICTIONS

A string argument cannot be used for both input and output.