FORTRAN stores CHARACTER
strings as fixed-length strings filled with trailing blanks, whereas C stores
them as a variable-length strings each terminated by the null character. Although C strings are of
variable length, there must of course be enough space reserved to store the maximum length that the
string ever reaches plus one more character for the trailing null.
To aid the programmer in converting between the two forms of character strings, a number of C functions are provided in the CNF library. These handle all aspects of converting between the two types of string and provide options such as creating temporary strings, including the trailing blanks in the C version of a string and only copying a maximum number of characters. The process of converting from FORTRAN to C strings is known as “importing” and from C to FORTRAN as “exporting”.
None of the functions are very complicated and some of them are just a tidier way of achieving what could be done with a few lines of C in the calling program. Consequently in a time critical application it may be appropriate to include the source of a CNF function in your code, rather than incur the overheads of a making a function call.
Full descriptions of the CNF functions are provided in Appendix G.
Here is an example of how to use them. This is the same as an example from the machine specific section of this document. The use of the F77 macros and the CNF functions have made the C code easier to write and completely portable to all Starlink systems.
Sometimes FORTRAN CHARACTER
variables are used to contain strings of bytes rather than normal,
printable character strings – a particular case of this is HDS locators (see SUN/92). In this
case, special characters, such as NULL, cease to have their normal meaning and this could
confuse the standard CNF import and export functions. For this reason, functions cnfImpch
and cnfExpch
are provided. These functions just import and export a given number of
characters.
The DECLARE_CHARACTER
macro used in an earlier example (2) assumes that the length of the required
FORTRAN character string is a constant, known at compile time. This is not always the case – for
example, the character argument to be passed to the FORTRAN subroutine may be derived from an
argument of the calling C function as in the case of a C wrap-around for a FORTRAN subroutine.
To cater for this situation, macros are provided which will allocate and free space for the
FORTRAN character string at run time. They make use of the CNF functions cnfCref
and
cnfFreef
.
The following example illustrates their use for both input and output of strings from a FORTRAN subroutine which takes a given string, modifies it and returns the result.
C main program
which is a C wrapper for the FORTRAN subroutine:
DECLARE_CHARACTER_DYN
is used in place of DECLARE_CHARACTER
. It declares pointers rather than
allocating space for the FORTRAN character strings to be passed to the FORTRAN subroutine. A
variable to hold the string length is also declared.
The F77_CREATE_CHARACTER
expands to executable statements which allocate space and set the
pointers and string length. The F77_FREE_CHARACTER
macro expands to executable statements which
free the previously allocated space.