SUN/209.11

Starlink Project
Starlink User Note 209.11

P.M. Allan
A.J. Chipperfield
R.F. Warren-Smith
P.W. Draper
D.S. Berry

12 May 2011

CNF and F77
Mixed Language Programming – FORTRAN and C

Version 4.3

Programmer’s Manual


Abstract

The CNF package comprises two sets of software which ease the task of writing portable programs in a mixture of FORTRAN and C. F77 is a set of C macros for handling the FORTRAN/C subroutine linkage in a portable way, and CNF is a set of functions to handle the difference between FORTRAN and C character strings, logical values and pointers to dynamically allocated memory.

Contents

1 How to read this document
2 Cookbook
 2.1 Calling C from FORTRAN
 2.2 Calling FORTRAN from C
 2.3 Building the Program
3 Representation of Data
 3.1 Numeric Types
 3.2 Characters
 3.3 Logical Types
 3.4 Pointer Types
 3.5 Arrays
 3.6 Same Language – Different Compiler
4 Communication Between Routines
 4.1 Arguments
 4.2 Function Values
 4.3 Global Data
5 More on Calling C from FORTRAN
 5.1 General Description
 5.2 Declaration of a Function
 5.3 Declaration of Arguments
 5.4 Arguments – and Pointers to Them
 5.5 Type Specifiers
 5.6 Logical Values
 5.7 External Names
 5.8 Common Blocks
6 Converting Between FORTRAN and C Strings
 6.1 The CNF Functions
 6.2 Handling Byte Strings (HDS Locators)
 6.3 Using Dynamic FORTRAN Character Strings
7 Pointers
 7.1 Pointer Registration and Conversion
 7.2 Allocating Exportable Dynamic Memory
 7.3 Accessing Dynamic Memory from C and FORTRAN
 7.4 Registering Your Own Pointers
8 More on Calling FORTRAN from C
 8.1 Thread Safety
9 More on Arrays
 9.1 CHARACTER and LOGICAL Arrays
 9.2 Arrays of pointer to char
 9.3 POINTER Arrays
10 The IMPORT and EXPORT Macros
11 Subroutines and Functions as Arguments
12 Other Approaches to Mixed Language Programming
13 Compiling and Linking
A Implementation Specific Details
 A.1 Sun
  A.1.1 General
  A.1.2 Data Types
  A.1.3 External Names
  A.1.4 Arguments
  A.1.5 Function Values
  A.1.6 Global Data
 A.2 DEC Unix
  A.2.1 General
  A.2.2 LOGICAL Values
  A.2.3 POINTERS on Alphas
 A.3 VAX/VMS
  A.3.1 General
  A.3.2 Data Types
  A.3.3 Arguments
  A.3.4 Function Values
  A.3.5 Global Data
 A.4 Other Operating Systems
B Rationale for Mixed Language Programming
C Alphabetical List of F77 Macros
D Classified List of F77 Macros
 D.1 Declaration of a C Function
 D.2 Arguments of a C Function
 D.3 Generate Pointers to Arguments
 D.4 Data Type Macros
 D.5 Logical Value Macros
 D.6 External Name Macro
 D.7 Common Block Macros
 D.8 Declaring Variables for Passing to a FORTRAN Routine
 D.9 Importing and Exporting Arguments
 D.10 Passing Arguments to a FORTRAN Routine
 D.11 Thread Safety
E Full Description of F77 Macros
 E.1 Generic Descriptions
 E.2 Specific Descriptions
CHARACTER – Declare a CHARACTER argument
CHARACTER_ARG – Pass a CHARACTER argument to a FORTRAN routine
CHARACTER_ARRAY – Declare a CHARACTER array argument
CHARACTER_ARRAY_ARG – Pass a CHARACTER array argument to a FORTRAN routine
CHARACTER_RETURN_ARG – Pass argument(s) that will be the return value of a FORTRAN CHARACTER FUNCTION
CHARACTER_RETURN_VALUE – Declare argument(s) that will be the return value of a FORTRAN CHARACTER FUNCTION
DECLARE_CHARACTER – Declare a CHARACTER variable
DECLARE_CHARACTER_ARRAY – Declare a CHARACTER array
DECLARE_CHARACTER_DYN – Declare a CHARACTER variable
F77_BLANK_COMMON – Refer to blank common
F77_BYTE_TYPE – Define the type BYTE
F77_CALL – Call a FORTRAN routine from C
F77_CHARACTER_ARG_TYPE – Define the type of a FORTRAN CHARACTER argument
F77_CHARACTER_ARRAY_ARG_TYPE – Define the type of a FORTRAN CHARACTER array argument
F77_CHARACTER_TYPE – Define the type CHARACTER
F77_CREATE_CHARACTER – Create a FORTRAN CHARACTER variable
F77_CREATE_CHARACTER_ARRAY – Create a FORTRAN CHARACTER array
F77_CREATE_CHARACTER_ARRAY_M – Create a FORTRAN CHARACTER array (n-D)
F77_CREATE_LOGICAL_ARRAY_M – Create a FORTRAN LOGICAL array (n-D)
F77_DOUBLE_TYPE – Define the type DOUBLE PRECISION
F77_EXPORT_CHARACTER – Export a C variable to a FORTRAN variable.
F77_EXPORT_CHARACTER_ARRAY – Export a CHARACTER array from C to FORTRAN
F77_EXPORT_CHARACTER_ARRAY_P – Export an array of pointers to char from C to a FORTRAN CHARACTER array.
F77_EXTERNAL_NAME – The external name of a function
F77_FALSE – The logical value FALSE
F77_IMPORT_CHARACTER – Import a FORTRAN variable to a C variable.
F77_IMPORT_CHARACTER_ARRAY – Import a CHARACTER array from FORTRAN to C.
F77_IMPORT_CHARACTER_ARRAY_P – Import a FORTRAN CHARACTER array to a C array of pointers to char.
F77_INTEGER_TYPE – Define the type INTEGER
F77_ISFALSE – Is this the FORTRAN logical value false?
F77_LOCK – Prevents code from being run simultaneously in two separate threads
F77_ISTRUE – Is this the FORTRAN logical value true?
F77_LOGICAL_TYPE – Define the type LOGICAL
F77_NAMED_COMMON – Refer to a named common block
F77_POINTER_TYPE – Define the type POINTER
F77_REAL_TYPE – Define the type REAL
F77_SUBROUTINE – Declare a SUBROUTINE
F77_TRUE – The logical value TRUE
F77_UBYTE_TYPE – Define the type UBYTE
F77_UWORD_TYPE – Define the type UWORD
F77_WORD_TYPE – Define the type WORD
GENPTR_CHARACTER – Generate a pointer to a CHARACTER argument
GENPTR_CHARACTER_ARRAY – Generate a pointer to a CHARACTER array argument
GENPTR_SUBROUTINE – Generate a pointer to a SUBROUTINE argument.
SUBROUTINE – Declare a SUBROUTINE argument.
SUBROUTINE_ARG – Pass a SUBROUTINE argument to a FORTRAN routine.
TRAIL – Declare hidden trailing arguments
TRAIL_ARG – Pass the length of a CHARACTER argument to a FORTRAN routine

F Classified List of CNF Functions
 F.1 Import a FORTRAN String to C
 F.2 Export a C String to FORTRAN
 F.3 String Lengths
 F.4 Miscellaneous String Handling
 F.5 LOGICAL Array Handling
 F.6 Memory and Pointer Handling
G CNF C Routine Descriptions
cnfCalloc – Allocate space that may be accessed from C and FORTRAN
cnfCopyf – Copy one FORTRAN string to another FORTRAN string
cnfCptr – Convert a FORTRAN pointer to a C pointer
cnfCreat – Create a temporary C string and return a pointer to it
cnfCref – Create a temporary FORTRAN CHARACTER string and return a pointer to it.
cnfCrefa – Create a temporary FORTRAN CHARACTER array and return a pointer to it.
cnfCreib – Create a temporary C string and import a FORTRAN string into it including trailing blanks
cnfCreim – Create a temporary C string and import a FORTRAN string into it discarding trailing blanks
cnfCrela – Create a temporary FORTRAN LOGICAL array and return a pointer to it.
cnfExpch – Export a C array of char to a FORTRAN string.
cnfExpla – Export a C int array to a FORTRAN LOGICAL array
cnfExpn – Export a C string to a FORTRAN string, copying a given maximum number of characters
cnfExprt – Export a C string to a FORTRAN string
cnfExprta – Export a C string array to a FORTRAN CHARACTER array
cnfExprtap – Export a C array of pointers to char, to a FORTRAN CHARACTER array
cnfFptr – Convert a C pointer to a FORTRAN pointer
cnfFree – Free allocated space
cnfFreef – Free a FORTRAN string
cnfImpb – Import a FORTRAN string into a C string, retaining trailing blanks
cnfImpbn – Import no more than max characters from a FORTRAN string into a C string, retaining trailing blanks
cnfImpch – Import a FORTRAN string into a C array of char.
cnfImpla – Import a FORTRAN LOGICAL array into a C int array
cnfImpn – Import no more than max characters from a FORTRAN string into a C string
cnfImprt – Import a FORTRAN string into a C string
cnfImprta – Import a FORTRAN CHARACTER array into a C string array.
cnfImprtap – Import a FORTRAN CHARACTER array into a C array of pointers to char.
cnfLenc – Find the length of a C string
cnfLenf – Find the length of a FORTRAN string
cnfMalloc – Allocate space that may be accessed from C and FORTRAN
cnfRegp – Register a pointer for use from both C and FORTRAN
cnfUregp – Unregister a pointer previously registered using cnfRegp

H CNF FORTRAN Function Description
CNF_PVAL – Expand a FORTRAN pointer to its full value
CNF_CVAL – Convert a Fortran INTEGER into the same type as used in the TRAIL macro.

I References

References

[1]   American National Standard – Programming Language – FORTRAN (ANSI X3.9-1978, ISO 1539-1980(E)). Publ, American National Standards Institute.

[2]   American National Standard for Information Systems – Programming Language – C (ANSI X3.159-1989). Publ, American National Standards Institute.

[3]   Banahan, M.F., 1988. The C Book: featuring the draft ANSI C standard. Publ, Addison-Wesley.