Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.




How to Use CDFs in C

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 C Application programming Interface (API), and the API provides the essential framework on which graphical and data analysis packages can be created. The CDF home page contains examples, documentation, FAQs, and tools - https://cdf.gsfc.nasa.gov/. The CDF User Guide and CDF C Reference Manual are available at: /html/cdf_docs.html.

2.Installation

Users should know where on their system cdf.h has been installed. may be either an absolute or relative file name. They may also need to specify the location of system include files. For Microsoft Visual C++ this is usually accomplished by setting MS-DOS environment variables, e.g., execute VCVARS32.BAT for VC++. The /c option specifies that only an object module is to be produced. The object module will be named .obj. The C library can be found in /usr/local/cdf38_1/lib directory.

3.CDF applications

Both the Standard and Internal interfaces for C applications are built into the CDF library. The Standard interface, provding a user-friendly, specific function, e.g., read/write a variable data, is actually built on a series of the Internal interface calls. Either or both interfaces can be used in an application.

Each application includes the following line at/near the top of each source file that calls the CDF functions: #include “cdf.h”

For C applications, all items are referenced starting at zero (0). These include variable, attribute, and attribute entry numbers, record numbers, dimensions, and dimension indices. Note that both rVariables and zVariables are numbered starting at zero (0).

4.Files

Each source file that calls the CDF library or references CDF parameters must include cdf.h, the CDF’s main include file. On OpenVMS systems a logical name, CDF$INC, that specifies the location of cdf.h is defined in the definitions file, DEFINITIONS.COM, provided with the CDF distribution. This is a script to define various environment variables.

On UNIX systems (including Mac OS X) an environment variable, $CDF_INC, that serves the same purpose is defined in the definitions file, “definitions.[C|B|K]” in the CDF distribution. This is a script to define various environment variables.

On Windows systems, a bat file, setenv.bat, is distributed in the pre-compiled CDF distribution package. This bat file, once executed, will set up various environment variables. The cdf.h should be in %CDF_INC% (or %CDF_BASE%\include) folder.

This section assumes that you are using the appropriate definitions file on those systems. The location of cdf.h is specified as described in the appropriate sections for those systems. The CDF file’s offset and size since V 3 use the 64-bit data type, while the earlier versions, V 2, use 32-bit.

5.Compiling the source code

When the source file is compiled, the path name of the disk/directory containing cdf.h must be specified. Use the defined environment variable: CDFINC, $CDF_INC or %CDF_INC%, depending on the systems used. If the environment variable is not defined, use the actual full path name for the directory that contains cdf.h.

The text file below shows how to compile/link/execute a CDF application, cdf_app.c.

    Linux

- Compile and link with static library (libcdf.a)

  gcc -o cdf_app -I $CDF_INC -O2 cdf_app.c $CDF_LIB/libcdf.a -lc -lm

- Execute with static library

  cdf_app

- Compile and link with dynamic library (libcdf.so)

  gcc -o cdf_app -I $CDF_INC -O2 cdf_app.c $CDF_LIB/libcdf.so -lc -lm

- Execute with dynamic library

  setenv LD_LIBRARY_PATH $CDF_LIB:.... [for csh/tcsh shell]
  export LD_LIBRARY_PATH=$CDF_LIB;.... [for other shells]
  cdf_app

Mac OS X

Compile and link with static library (libcdf.a)

clang -o cdf_app -I CDF_INC -O2 cdf_app.c CDF_LIB/libcdf.a -lc -lm

- Execute with static library

  cdf_app

- Compile and link with dynamic library (libcdf.dylib)

  clang -o cdf_app -I CDF_INC -O2 cdf_app.c CDF_LIB/libcdf.dylib -lc -lm

- Execute with dynamic library

  setenv DYLD_LIBRARY_PATH CDF_LIB:.... [for csh/tcsh shell]
  export DYLD_LIBRARY_PATH=CDF_LIB;.... [for other shells]
  cdf_app

Windows

- compile

  cl /O2 /c /I %CDF_INC% cdf_app.c

- Link with static library (libcdf.lib)

  link /out:cdf_app.exe cdf_app.obj %CDF_LIB%\libcdf.lib

- Execute with static library

  cdf_app

- Link with dynamic library (the import library: dllcdf.lib)

  link /out:cdf_app.exe cdf_app.obj %CDF_BIN%\dllcdf.lib

- Execute with dynamic library (the dynamic library: dllcdf.dll)

  PATH = %PATH%;%CDF_BIN%
  cdf_app

6.Making the executables

Applications, after compiling, must be linked with the CDF library to make them executables. On OpenVMS systems, a logical name, CDF$LIB, which specifies the location of the CDF library, is defined in the definitions file, DEFINITIONS.COM, provided with the CDF distribution.

On UNIX systems (including Mac OS X) an environment variable, $CDF_LIB, which serves the same purpose, is defined in the definitions file: “definitions.[C|B|K].” The same for the type of shell being used: C for the C-shell (csh and tcsh), K for the Korn (ksh), BASH, and POSIX shells, and B for the Bourne shell (sh) and zsh.

On Windows systems, %CDF_LIB% (or %CDF_BASE%\lib) and PATH are the directories for the CDF libraries. The setenv.bat, once executed, will set up CDF_LIB environment variables.

Two CDF libraries are distributed: the static library and the dynamic (shareable) library. Executables can be linked with either one. CDF libraries normally have the name: “libcdf” with an extension.

For the static library, all non-Windows systems have the same extension: “.a.” For Windows, it has a “.lib” extension.

For the dynamic library, the extension can be “.so” for Linux, “.sl” for HPUX, “.dylib” for Mac OS, or “.dll” for Windows. [CDF has this “dllcdf.dll” for its Windows dynamic library.]

A statically linked executable can execute as is. The dynamically linked application needs to provide the directory where the dynamic library can be located when it is executing. On Unix/Linux systems, the environment variable “LD_LIBRARY_PATH” needs to set to the directory where the CDF dynamic library is. On Windows, the directory that contains the dynamic library needs to add to the system PATH environment variable. The script or bat file mentioned earlier can just do that.

7.Examples

An example of a create CDF C file:

/* CDFsetFileBackwardFlag(BACKWARDFILEon); */
status = CDFlib (CREATE_, CDF_, "TEST", 0L, dimSizes, &id, NULL_); 

if (status < CDF_OK) {
  if (status == CDF_EXISTS) {
    status = CDFlib (OPEN_, CDF_, "TEST", &id, NULL_);
    if (status < CDF_OK) QuitCDF ("1.0", status);

    status = CDFlib (DELETE_, CDF_, NULL_);
    if (status < CDF_OK) QuitCDF ("1.1", status);

    status = CDFlib (CREATE_, CDF_, "TEST", 0L, dimSizes, &id, NULL_);
    if (status < CDF_OK) QuitCDF ("1.2", status);
  }
  else
    QuitCDF ("1.3", status);
}

An example of a read CDF C file:

status = CDFlib (GET_, CDF_FORMAT_, &formatOut,
               CDF_ENCODING_, &encoding_out,
               CDF_MAJORITY_, &majority_out,
         NULL_);
if (status < CDF_OK) QuitCDF ("4.0", status);

if (formatOut != SINGLE_FILE) QuitCDF ("4.1", status);
if (encoding_out != actual_encoding) QuitCDF ("4.2", status);
if (majority_out != majority) QuitCDF ("4.3", status);