How to use CDFs in Fortran

1.Introduction

Common Data Format (CDF) is a conceptual data abstraction for storing, manipulating, and accessing multidimensional datasets. CDF is referred to as a data abstraction because the actual physical format in which datasets are stored is not discussed. Instead, the form of the datasets and the means (interface) by which they may be manipulated are described. The CDF library comes with the Fortran Application programming Interface (API), and the API provides the essential framework on which graphical and data analysis packages can be created.

2.Files

The cdf.inc include file declares the FUNCTIONs available in the CDF library (CDF_var_num, CDF_lib, etc.). Some Fortran compilers will display warning messages about unused variables if these functions are not used in a routine (because they will be assumed to be variables not function declarations). Most of these Fortran compilers have a command line option (e.g., -nounused) that will suppress the warning messages.

Most computer systems have Fortran and C compilers that allow a Fortran application to call a C function without being concerned that different programming languages are involved. The CDF library takes advantage of the mechanisms provided by these compilers so that the Fortran application can appear to be calling another Fortran subroutine/function (in actuality the CDF library written in C). Additional information can be found in the CDF Fortran Reference Manual: https://spdf.gsfc.nasa.gov/pub/software/cdf/doc/cdf381/cdf381frm.pdf

3.Applications

Fortran programming interface for CDF applications include constants and types defined for use by all CDF application programs written in Fortran. These constants and types are defined in cdf.inc. The file cdf.inc should be INCLUDEed in all application source files referencing CDF routines/parameters. Most computer systems have Fortran and C compilers that allow a Fortran application to call a C function without being concerned that different programming languages are involved. The CDF library takes advantage of the mechanisms provided by these compilers so that a Fortran application can appear to be calling another Fortran subroutine/function (in actuality the CDF library written in C). The Fortran application must place an ASCII NUL character after the last character of a CDF, variable, or attribute name. An example of this follows:

CHARACTER ATTR_NAME*9 ! Attribute name . . ATTR_NAME(1:8) = ‘VALIDMIN’ ! Actual attribute name ATTR_NAME(9:9) = CHAR(0) ! ASCII NUL character

4.Compiling the source code

On UNIX systems the compile and link may be combined into one step where app.f is the name of the source file(s) being compiled/linked. (The .f extension is required.) Example: % gfortran -c app.f -fsecond-underscore -I ${CDF_INC}

${CDF_INC} points to the directory that contains CDF.INC.

gfortran is the most popular and newer compiler on Linux-based systems. The older f77 compiler can also be used.

On Windows, a few of GNU-based compilers, e.g., gcc, g95, can be used as the FORTRAN compiler under Cygwin or something similar. For Microsoft or Intel specific FORTRAN compiler, refer to the compiler’s documentation for its compiling options.

Even though the application is written in Fortran and compiled with a Fortran compiler, compatible C runtime system libraries (as supplied with Microsoft Visual C++) will be necessary to successfully link the application. This is because the CDF library is written in C and calls C run-time system functions. The cdf.inc include files declares the FUNCTIONs available in the CDF library (CDF var num, CDF lib, etc.). Most of these Fortran compilers have a command line option (e.g., -nounused) that will suppress these warning messages. If a suitable command line option is not available (and the messages are too annoying to ignore), the function declarations could be removed from cdf.inc but be sure to declare each CDF function that a routine uses.

5.Making the executables

An example of the command to link the application with the CDF library (libcdf.a, the static library) on UNIX flavored systems would be as follows:

% gfortran -o app <object-file(s)>.o ${CDF_LIB}/libcdf.a

The name of the executable created will be “app”, as specified as “-o” qualifier. Some UNIX systems may also require that -lc (the C run-time library), -lm (the math library). To link with the dynamic linked library, as libcdf.so for Linux and libcdf.dylib for Mac OS X, use the specific library at the end of the command line. This may depend on the particular release of the operating system being used. Note that ${CDF_LIB} specifies the defined environment variable CDF_LIB that points to the directory that contains the CDF library. For an application that is linked with the dynamic library, the environment variable, LD_LIBRARY_PATH on Linux-based systems needs to be prointed to the directory that contain the libcdf.so. For Mac OS X, similarly, the ebnvironment variable, DYLD_LIBRARY_PATH needs to point to the directory that has libcdf.dylib.

An example of the command used to link an application to the CDF library (LIBCDF.LIB) on Windows systems using Digital Visual Fortran and Microsoft Visual C++ would be as follows:

LINK libcdf.lib /out:<name.exe> /nodefaultlib:libcd

where is the application’s object module(s) (the .obj extension is necessary); <name.exe> is the name of the executable file to be created and is the file name of the directory containing LIBCDF.LIB, the CDF’s static library. Users will need to know where on their CDF’s LIBCDF.LIB has been installed. may be either an absolute or relative file name.

To link with the CDF dynamic library, DLLCDF.dll and DLLCDF.lib, use the following command:

LINK dllcdf.lib /out:<name.exe> /nodefaultlib:libcd

Please note that DLLCDF.dll and DLLCDF.lib could be placed in two different folders, which is the case if the binary CDF package is installed. DLLCDF.dll likely resides in bin directory and dllcdf.lib in lib directory.