CDI

Contents

1  Introduction

CDI is an Interface to access Climate and forecast model Data. The interface is independent from a specific data format and has a C and Fortran API. CDI was developed for a fast and machine independent access to GRIB and NetCDF datasets with the same interface. The local MPI-MET data formats SERVICE, EXTRA and IEG are also supported.

1.1  Building from sources

This section describes how to build the CDI library from the sources on a UNIX system. CDI is using the GNU configure and build system to compile the source code. The only requirement is a working ANSI C99 compiler.

First go to the download page (http://code.zmaw.de/projects/cdi/files) to get the latest distribution, if you do not already have it.

To take full advantage of CDI’s features the following additional libraries should be installed:

• Unidata NetCDF library (http://www.unidata.ucar.edu/packages/netcdf) version 3 or higher. This is needed to read/write NetCDF files with CDI.
• The ECMWF GRIB_API (http://www.ecmwf.int/products/data/software/grib_api.html) version 1.9.5 or higher. This library is needed to encode/decode GRIB2 records with CDI.

1.1.1  Compilation

Compilation is now done by performing the following steps:

1. Unpack the archive, if you haven’t already done that:
       gunzip cdi-$VERSION.tar.gz    # uncompress the archive  
       tar xf cdi-$VERSION.tar       # unpack it  
       cd cdi-$VERSION

2. Run the configure script:
       ./configure

   Or optionally with NetCDF support:

       ./configure --with-netcdf=<NetCDF root directory>

   For an overview of other configuration options use

       ./configure --help

3. Compile the program by running make:
       make

The software should compile without problems and the CDI library (libcdi.a) should be available in the src directory of the distribution.

1.1.2  Installation

After the compilation of the source code do a make install, possibly as root if the destination permissions require that.

The library is installed into the directory <prefix>/lib. The C and Fortran include files are installed into the directory <prefix>/include. <prefix> defaults to /usr/local but can be changed with the --prefix option of the configure script.

2  File Formats

2.1  GRIB

GRIB [GRIB] (GRIdded Binary) is a standard format designed by the World Meteorological Organization (WMO) to support the efficient transmission and storage of gridded meteorological data.

A GRIB record consists of a series of header sections, followed by a bitstream of packed data representing one horizontal grid of data values. The header sections are intended to fully describe the data included in the bitstream, specifying information such as the parameter, units, and precision of the data, the grid system and level type on which the data is provided, and the date and time for which the data are valid.

Non-numeric descriptors are enumerated in tables, such that a 1-byte code in a header section refers to a unique description. The WMO provides a standard set of enumerated parameter names and level types, but the standard also allows for the definition of locally used parameters and geometries. Any activity that generates and distributes GRIB records must also make their locally defined GRIB tables available to users.

CDI does not support the full GRIB standard. The following data representation and level types are implemented:

2.1.1  GRIB edition 1

GRIB1 is implemented in CDI as an internal library and enabled per default. The internal GRIB1 library is called CGRIBEX. This is lightweight version of the ECMWF GRIBEX library. CGRIBEX is written in ANSI C with a portable Fortran interface. The configure option --disable-cgribex will disable the encoding/decoding of GRIB1 records with CGRIBEX.

2.1.2  GRIB edition 2

GRIB2 is available in CDI via the ECMWF GRIB_API [GRIBAPI]. GRIB_API is an external library and not part of CDI. To use GRIB2 with CDI the GRIB_API library must be installed before the configuration of the CDI library. Use the configure option --with-grib_api to enable GRIB2 support.

The GRIB_API library is also used to encode/decode GRIB1 records if the support for the CGRIBEX library is disabled. This feature is not tested regulary and the status is experimental!

2.2  NetCDF

NetCDF [NetCDF] (Network Common Data Form) is an interface for array-oriented data access and a library that provides an implementation of the interface. The NetCDF library also defines a machine-independent format for representing scientific data. Together, the interface, library, and format support the creation, access, and sharing of scientific data.

CDI only supports the classic data model of NetCDF and arrays up to 4 dimensions. These dimensions should only be used by the horizontal and vertical grid and the time. The NetCDF attributes should follow the GDT, COARDS or CF Conventions.

NetCDF is an external library and not part of CDI. To use NetCDF with CDI the NetCDF library must be installed before the configuration of the CDI library. Use the configure option --with-netcdf to enable NetCDF support (see Build).

2.3  SERVICE

SERVICE is the binary exchange format of the atmospheric general circulation model ECHAM [ECHAM]. It has a header section with 8 integer values followed by the data section. The header and the data section have the standard Fortran blocking for binary data records. A SERVICE record can have an accuracy of 4 or 8 bytes and the byteorder can be little or big endian. In CDI the accuracy of the header and data section must be the same. The following Fortran code example can be used to read a SERVICE record with an accuracy of 4 bytes:

The constants mlon and mlat must be greater or equal than nlon and nlat. The meaning of the variables are:

  

SERVICE is implemented in CDI as an internal library and enabled per default. The configure option --disable-service will disable the support for the SERVICE format.

2.4  EXTRA

EXTRA is the standard binary output format of the ocean model MPIOM [MPIOM]. It has a header section with 4 integer values followed by the data section. The header and the data section have the standard Fortran blocking for binary data records. An EXTRA record can have an accuracy of 4 or 8 bytes and the byteorder can be little or big endian. In CDI the accuracy of the header and data section must be the same. The following Fortran code example can be used to read an EXTRA record with an accuracy of 4 bytes:

The constant msize must be greater or equal than nsize. The meaning of the variables are:

  

EXTRA is implemented in CDI as an internal library and enabled per default. The configure option --disable-extra will disable the support for the EXTRA format.

2.5  IEG

IEG is the standard binary output format of the regional model REMO [REMO]. It is simple an unpacked GRIB edition 1 format. The product and grid description sections are coded with 4 byte integer values and the data section can have 4 or 8 byte IEEE floating point values. The header and the data section have the standard Fortran blocking for binary data records. The IEG format has a fixed size of 100 for the vertical coordinate table. That means it is not possible to store more than 50 model levels with this format. CDI supports only data on Gaussian and LonLat grids for the IEG format.

IEG is implemented in CDI as an internal library and enabled per default. The configure option --disable-ieg will disable the support for the IEG format.

3  Use of the CDI Library

This chapter provides templates of common sequences of CDI calls needed for common uses. For clarity only the names of routines are used. Declarations and error checking were omitted. Statements that are typically invoked multiple times were indented and ... is used to represent arbitrary sequences of other statements. Full parameter lists are described in later chapters.

Complete examples for write, read and copy a dataset with CDI can be found in Appendix B.

3.1  Creating a dataset

Here is a typical sequence of CDI calls used to create a new dataset:

3.2  Reading a dataset

Here is a typical sequence of CDI calls used to read a dataset:

3.3  Compiling and Linking with the CDI library

Details of how to compile and link a program that uses the CDI C or FORTRAN interfaces differ, depending on the operating system, the available compilers, and where the CDI library and include files are installed. Here are examples of how to compile and link a program that uses the CDI library on a Unix platform, so that you can adjust these examples to fit your installation. Every C file that references CDI functions or constants must contain an appropriate include statement before the first such reference:

Unless the cdi.h file is installed in a standard directory where C compiler always looks, you must use the -I option when invoking the compiler, to specify a directory where cdi.h is installed, for example:

Alternatively, you could specify an absolute path name in the include statement, but then your program would not compile on another platform where CDI is installed in a different location.

Unless the CDI library is installed in a standard directory where the linker always looks, you must use the -L and -l options to links an object file that uses the CDI library. For example:

Alternatively, you could specify an absolute path name for the library:

If the CDI library is using other external libraries, you must add this libraries in the same way. For example with the NetCDF library:

4  CDI modules

4.1  Dataset functions

This module contains functions to read and write the data. To create a new dataset the output format must be specified with one of the following predefined file format types:

  

FILETYPE_GRB2 is only available if the CDI library was compiled with GRIB_API support and all NetCDF file types are only available if the CDI library was compiled with NetCDF support!

To set the byte order of a binary dataset with the file format type FILETYPE_SRV, FILETYPE_EXT or FILETYPE_IEG use one of the following predefined constants in the call to streamDefByteorder:

  

4.1.1  Create a new dataset: streamOpenWrite

The function streamOpenWrite creates a new datset.

Usage

 

Result

Upon successful completion streamOpenWrite returns an identifier to the open stream. Otherwise, a negative number with the error status is returned.

Errors

 

Example

Here is an example using streamOpenWrite to create a new NetCDF file named foo.nc for writing:

4.1.2  Open a dataset for reading: streamOpenRead

The function streamOpenRead opens an existing dataset for reading.

Usage

 

Result

Upon successful completion streamOpenRead returns an identifier to the open stream. Otherwise, a negative number with the error status is returned.

Errors

 

Example

Here is an example using streamOpenRead to open an existing NetCDF file named foo.nc for reading:

4.1.3  Close an open dataset: streamClose

The function streamClose closes an open dataset.

Usage

 

4.1.4  Get the filetype: streamInqFiletype

The function streamInqFiletype returns the filetype of a stream.

Usage

 

Result

streamInqFiletype returns the type of the file format, one of the set of predefined CDI file format types. The valid CDI file format types are FILETYPE_GRB, FILETYPE_GRB2, FILETYPE_NC, FILETYPE_NC2, FILETYPE_NC4, FILETYPE_NC4C, FILETYPE_SRV, FILETYPE_EXT and FILETYPE_IEG.

4.1.5  Define the byte order: streamDefByteorder

The function streamDefByteorder defines the byte order of a binary dataset with the file format type FILETYPE_SRV, FILETYPE_EXT or FILETYPE_IEG.

Usage

 

4.1.6  Get the byte order: streamInqByteorder

The function streamInqByteorder returns the byte order of a binary dataset with the file format type FILETYPE_SRV, FILETYPE_EXT or FILETYPE_IEG.

Usage

 

Result

streamInqByteorder returns the type of the byte order. The valid CDI byte order types are CDI_BIGENDIAN and CDI_LITTLEENDIAN

4.1.7  Define the variable list: streamDefVlist

The function streamDefVlist defines the variable list of a stream.

To safeguard against errors by modifying the wrong vlist object, this function makes the passed vlist object immutable. All further vlist changes have to use the vlist object returned by streamInqVlist().

Usage

 

4.1.8  Get the variable list: streamInqVlist

The function streamInqVlist returns the variable list of a stream.

Usage

 

Result

streamInqVlist returns an identifier to the variable list.

4.1.9  Define time step: streamDefTimestep

The function streamDefTimestep defines the time step of a stream.

Usage

 

Result

streamDefTimestep returns the number of records of the time step.

4.1.10  Get time step: streamInqTimestep

The function streamInqTimestep returns the time step of a stream.

Usage

 

Result

streamInqTimestep returns the number of records of the time step.

4.1.11  Write a variable: streamWriteVar

The function streamWriteVar writes the values of one time step of a variable to an open dataset. The values are converted to the external data type of the variable, if necessary.

Usage

 

4.1.12  Write a variable: streamWriteVarF

The function streamWriteVarF writes the values of one time step of a variable to an open dataset. The values are converted to the external data type of the variable, if necessary.

Usage

 

4.1.13  Write a horizontal slice of a variable: streamWriteVarSlice

The function streamWriteVarSlice writes the values of a horizontal slice of a variable to an open dataset. The values are converted to the external data type of the variable, if necessary.

Usage

 

4.1.14  Write a horizontal slice of a variable: streamWriteVarSliceF

The function streamWriteVarSliceF writes the values of a horizontal slice of a variable to an open dataset. The values are converted to the external data type of the variable, if necessary.

Usage

 

4.1.15  Read a variable: streamReadVar

The function streamReadVar reads all the values of one time step of a variable from an open dataset.

Usage

 

4.1.16  Read a variable: streamReadVarF

The function streamReadVar reads all the values of one time step of a variable from an open dataset.

Usage

 

4.1.17  Read a horizontal slice of a variable: streamReadVarSlice

The function streamReadVarSlice reads all the values of a horizontal slice of a variable from an open dataset.

Usage

 

4.1.18  Read a horizontal slice of a variable: streamReadVarSliceF

The function streamReadVarSliceF reads all the values of a horizontal slice of a variable from an open dataset.

Usage

 

4.2  Variable list functions

This module contains functions to handle a list of variables. A variable list is a collection of all variables of a dataset.

4.2.1  Create a variable list: vlistCreate

Usage

Example

Here is an example using vlistCreate to create a variable list and add a variable with vlistDefVar.

4.2.2  Destroy a variable list: vlistDestroy

Usage

 

4.2.3  Copy a variable list: vlistCopy

The function vlistCopy copies all entries from vlistID1 to vlistID2.

Usage

 

4.2.4  Duplicate a variable list: vlistDuplicate

The function vlistDuplicate duplicates the variable list from vlistID1.

Usage

 

Result

vlistDuplicate returns an identifier to the duplicated variable list.

4.2.5  Concatenate two variable lists: vlistCat

Concatenate the variable list vlistID1 at the end of vlistID2.

Usage

 

4.2.6  Copy some entries of a variable list: vlistCopyFlag

The function vlistCopyFlag copies all entries with a flag from vlistID1 to vlistID2.

Usage

 

4.2.7  Number of variables in a variable list: vlistNvars

The function vlistNvars returns the number of variables in the variable list vlistID.

Usage

 

Result

vlistNvars returns the number of variables in a variable list.

4.2.8  Number of grids in a variable list: vlistNgrids

The function vlistNgrids returns the number of grids in the variable list vlistID.

Usage

 

Result

vlistNgrids returns the number of grids in a variable list.

4.2.9  Number of zaxis in a variable list: vlistNzaxis

The function vlistNzaxis returns the number of zaxis in the variable list vlistID.

Usage

 

Result

vlistNzaxis returns the number of zaxis in a variable list.

4.2.10  Define the time axis: vlistDefTaxis

The function vlistDefTaxis defines the time axis of a variable list.

Usage

 

4.2.11  Get the time axis: vlistInqTaxis

The function vlistInqTaxis returns the time axis of a variable list.

Usage

 

Result

vlistInqTaxis returns an identifier to the time axis.

4.3  Variable functions

This module contains functions to add new variables to a variable list and to get information about variables from a variable list. To add new variables to a variables list one of the following time types must be specified:

  

The default data type is 16 bit for GRIB and 32 bit for all other file format types. To change the data type use one of the following predefined constants:

  

4.3.1  Define a Variable: vlistDefVar

The function vlistDefVar adds a new variable to vlistID.

Usage

 

Result

vlistDefVar returns an identifier to the new variable.

Example

Here is an example using vlistCreate to create a variable list and add a variable with vlistDefVar.

4.3.2  Get the Grid ID of a Variable: vlistInqVarGrid

The function vlistInqVarGrid returns the grid ID of a Variable.

Usage

 

Result

vlistInqVarGrid returns the grid ID of the Variable.

4.3.3  Get the Zaxis ID of a Variable: vlistInqVarZaxis

The function vlistInqVarZaxis returns the zaxis ID of a variable.

Usage

 

Result

vlistInqVarZaxis returns the zaxis ID of the variable.

4.3.4  Define the code number of a Variable: vlistDefVarCode

The function vlistDefVarCode defines the code number of a variable.

Usage

 

4.3.5  Get the Code number of a Variable: vlistInqVarCode

The function vlistInqVarCode returns the code number of a variable.

Usage

 

Result

vlistInqVarCode returns the code number of the variable.

4.3.6  Define the name of a Variable: vlistDefVarName

The function vlistDefVarName defines the name of a variable.

Usage

 

4.3.7  Get the name of a Variable: vlistInqVarName

The function vlistInqVarName returns the name of a variable.

Usage

 

Result

vlistInqVarName returns the name of the variable to the parameter name if available, otherwise the result is an empty string.

4.3.8  Define the long name of a Variable: vlistDefVarLongname

The function vlistDefVarLongname defines the long name of a variable.

Usage

 

4.3.9  Get the longname of a Variable: vlistInqVarLongname

The function vlistInqVarLongname returns the longname of a variable if available, otherwise the result is an empty string.

Usage

 

Result

vlistInqVaeLongname returns the longname of the variable to the parameter longname.

4.3.10  Define the standard name of a Variable: vlistDefVarStdname

The function vlistDefVarStdname defines the standard name of a variable.

Usage

 

4.3.11  Get the standard name of a Variable: vlistInqVarStdname

The function vlistInqVarStdname returns the standard name of a variable if available, otherwise the result is an empty string.

Usage

 

Result

vlistInqVarStdname returns the standard name of the variable to the parameter stdname.

4.3.12  Define the units of a Variable: vlistDefVarUnits

The function vlistDefVarUnits defines the units of a variable.

Usage

 

4.3.13  Get the units of a Variable: vlistInqVarUnits

The function vlistInqVarUnits returns the units of a variable if available, otherwise the result is an empty string.

Usage

 

Result

vlistInqVarUnits returns the units of the variable to the parameter units.

4.3.14  Define the data type of a Variable: vlistDefVarDatatype

The function vlistDefVarDatatype defines the data type of a variable.

Usage

 

4.3.15  Get the data type of a Variable: vlistInqVarDatatype

The function vlistInqVarDatatype returns the data type of a variable.

Usage

 

Result

vlistInqVarDatatype returns an identifier to the data type of the variable. The valid CDI data types are DATATYPE_PACK8, DATATYPE_PACK16, DATATYPE_PACK24, DATATYPE_FLT32, DATATYPE_FLT64, DATATYPE_INT8, DATATYPE_INT16 and DATATYPE_INT32.

4.3.16  Define the missing value of a Variable: vlistDefVarMissval

The function vlistDefVarMissval defines the missing value of a variable.

Usage

 

4.3.17  Get the missing value of a Variable: vlistInqVarMissval

The function vlistInqVarMissval returns the missing value of a variable.

Usage

 

Result

vlistInqVarMissval returns the missing value of the variable.

4.4  Attributes

Attributes may be associated with each variable to specify non CDI standard properties. CDI standard properties as code, name, units, and missing value are directly associated with each variable by the corresponding CDI function (e.g. vlistDefVarName). An attribute has a variable to which it is assigned, a name, a type, a length, and a sequence of one or more values. The attributes have to be defined after the variable is created and before the variable list is associated with a stream. Attributes are only used for NetCDF datasets.

It is also possible to have attributes that are not associated with any variable. These are called global attributes and are identified by using CDI_GLOBAL as a variable pseudo-ID. Global attributes are usually related to the dataset as a whole.

CDI supports integer, floating point and text attributes. The data types are defined by the following predefined constants:

  

4.4.1  Get number of variable attributes: vlistInqNatts

The function vlistInqNatts gets the number of variable attributes assigned to this variable.

Usage

 

4.4.2  Get information about an attribute: vlistInqAtt

The function vlistInqAtt gets information about an attribute.

Usage

 

4.4.3  Define an integer attribute: vlistDefAttInt

The function vlistDefAttInt defines an integer attribute.

Usage

 

4.4.4  Get the value(s) of an integer attribute: vlistInqAttInt

The function vlistInqAttInt gets the values(s) of an integer attribute.

Usage

 

4.4.5  Define a floating point attribute: vlistDefAttFlt

The function vlistDefAttFlt defines a floating point attribute.

Usage

 

4.4.6  Get the value(s) of a floating point attribute: vlistInqAttFlt

The function vlistInqAttFlt gets the values(s) of a floating point attribute.

Usage

 

4.4.7  Define a text attribute: vlistDefAttTxt

The function vlistDefAttTxt defines a text attribute.

Usage

 

4.4.8  Get the value(s) of a text attribute: vlistInqAttTxt

The function vlistInqAttTxt gets the values(s) of a text attribute.

Usage

 

4.5  Grid functions

This module contains functions to define a new horizontal Grid and to get information from an existing Grid. A Grid object is necessary to define a variable. The following different Grid types are available:

  

4.5.1  Create a horizontal Grid: gridCreate

The function gridCreate creates a horizontal Grid.

Usage

 

Result

gridCreate returns an identifier to the Grid.

Example

Here is an example using gridCreate to create a regular lon/lat Grid:

4.5.2  Destroy a horizontal Grid: gridDestroy

Usage

 

4.5.3  Duplicate a horizontal Grid: gridDuplicate

The function gridDuplicate duplicates a horizontal Grid.

Usage

 

Result

gridDuplicate returns an identifier to the duplicated Grid.

4.5.4  Get the type of a Grid: gridInqType

The function gridInqType returns the type of a Grid.

Usage

 

Result

gridInqType returns the type of the grid, one of the set of predefined CDI grid types. The valid CDI grid types are GRID_GENERIC, GRID_GAUSSIAN, GRID_LONLAT, GRID_LCC, GRID_SPECTRAL, GRID_GME, GRID_CURVILINEAR and GRID_UNSTRUCTURED.

4.5.5  Get the size of a Grid: gridInqSize

The function gridInqSize returns the size of a Grid.

Usage

 

Result

gridInqSize returns the number of grid points of a Grid.

4.5.6  Define the number of values of a X-axis: gridDefXsize

The function gridDefXsize defines the number of values of a X-axis.

Usage

 

4.5.7  Get the number of values of a X-axis: gridInqXsize

The function gridInqXsize returns the number of values of a X-axis.

Usage

 

Result

gridInqXsize returns the number of values of a X-axis.

4.5.8  Define the number of values of a Y-axis: gridDefYsize

The function gridDefYsize defines the number of values of a Y-axis.

Usage

 

4.5.9  Get the number of values of a Y-axis: gridInqYsize

The function gridInqYsize returns the number of values of a Y-axis.

Usage

 

Result

gridInqYsize returns the number of values of a Y-axis.

4.5.10  Define the number of parallels between a pole and the equator: gridDefNP

The function gridDefNP defines the number of parallels between a pole and the equator of a Gaussian grid.

Usage

 

4.5.11  Get the number of parallels between a pole and the equator: gridInqNP

The function gridInqNP returns the number of parallels between a pole and the equator of a Gaussian grid.

Usage

 

Result

gridInqNP returns the number of parallels between a pole and the equator.

4.5.12  Define the values of a X-axis: gridDefXvals

The function gridDefXvals defines all values of the X-axis.

Usage

 

4.5.13  Get all values of a X-axis: gridInqXvals

The function gridInqXvals returns all values of the X-axis.

Usage

 

Result

Upon successful completion gridInqXvals returns the number of values and the values are stored in xvals. Otherwise, 0 is returned and xvals is empty.

4.5.14  Define the values of a Y-axis: gridDefYvals

The function gridDefYvals defines all values of the Y-axis.

Usage

 

4.5.15  Get all values of a Y-axis: gridInqYvals

The function gridInqYvals returns all values of the Y-axis.

Usage

 

Result

Upon successful completion gridInqYvals returns the number of values and the values are stored in yvals. Otherwise, 0 is returned and yvals is empty.

4.5.16  Define the bounds of a X-axis: gridDefXbounds

The function gridDefXbounds defines all bounds of the X-axis.

Usage

 

4.5.17  Get the bounds of a X-axis: gridInqXbounds

The function gridInqXbounds returns the bounds of the X-axis.

Usage

 

Result

Upon successful completion gridInqXbounds returns the number of bounds and the bounds are stored in xbounds. Otherwise, 0 is returned and xbounds is empty.

4.5.18  Define the bounds of a Y-axis: gridDefYbounds

The function gridDefYbounds defines all bounds of the Y-axis.

Usage

 

4.5.19  Get the bounds of a Y-axis: gridInqYbounds

The function gridInqYbounds returns the bounds of the Y-axis.

Usage

 

Result

Upon successful completion gridInqYbounds returns the number of bounds and the bounds are stored in ybounds. Otherwise, 0 is returned and ybounds is empty.

4.5.20  Define the name of a X-axis: gridDefXname

The function gridDefXname defines the name of a X-axis.

Usage

 

4.5.21  Get the name of a X-axis: gridInqXname

The function gridInqXname returns the name of a X-axis.

Usage

 

Result

gridInqXname returns the name of the X-axis to the parameter name.

4.5.22  Define the longname of a X-axis: gridDefXlongname

The function gridDefXlongname defines the longname of a X-axis.

Usage

 

4.5.23  Get the longname of a X-axis: gridInqXlongname

The function gridInqXlongname returns the longname of a X-axis.

Usage

 

Result

gridInqXlongname returns the longname of the X-axis to the parameter longname.

4.5.24  Define the units of a X-axis: gridDefXunits

The function gridDefXunits defines the units of a X-axis.

Usage

 

4.5.25  Get the units of a X-axis: gridInqXunits

The function gridInqXunits returns the units of a X-axis.

Usage

 

Result

gridInqXunits returns the units of the X-axis to the parameter units.

4.5.26  Define the name of a Y-axis: gridDefYname

The function gridDefYname defines the name of a Y-axis.

Usage

 

4.5.27  Get the name of a Y-axis: gridInqYname

The function gridInqYname returns the name of a Y-axis.

Usage

 

Result

gridInqYname returns the name of the Y-axis to the parameter name.

4.5.28  Define the longname of a Y-axis: gridDefYlongname

The function gridDefYlongname defines the longname of a Y-axis.

Usage

 

4.5.29  Get the longname of a Y-axis: gridInqYlongname

The function gridInqYlongname returns the longname of a Y-axis.

Usage

 

Result

gridInqYlongname returns the longname of the Y-axis to the parameter longname.

4.5.30  Define the units of a Y-axis: gridDefYunits

The function gridDefYunits defines the units of a Y-axis.

Usage

 

4.5.31  Get the units of a Y-axis: gridInqYunits

The function gridInqYunits returns the units of a Y-axis.

Usage

 

Result

gridInqYunits returns the units of the Y-axis to the parameter units.

4.5.32  Define the reference number for an unstructured grid: gridDefNumber

The function gridDefNumber defines the reference number for an unstructured grid.

Usage

 

4.5.33  Get the reference number to an unstructured grid: gridInqNumber

The function gridInqNumber returns the reference number to an unstructured grid.

Usage

 

Result

gridInqNumber returns the reference number to an unstructured grid.

4.5.34  Define the position of grid in the reference file: gridDefPosition

The function gridDefPosition defines the position of grid in the reference file.

Usage

 

4.5.35  Get the position of grid in the reference file: gridInqPosition

The function gridInqPosition returns the position of grid in the reference file.

Usage

 

Result

gridInqPosition returns the position of grid in the reference file.

4.5.36  Define the reference URI for an unstructured grid: gridDefReference

The function gridDefReference defines the reference URI for an unstructured grid.

Usage

 

4.5.37  Get the reference URI to an unstructured grid: gridInqReference

The function gridInqReference returns the reference URI to an unstructured grid.

Usage

 

Result

gridInqReference returns the reference URI to an unstructured grid.

4.5.38  Define the UUID for an unstructured grid: gridDefUUID

The function gridDefUUID defines the UUID for an unstructured grid.

Usage

 

4.5.39  Get the UUID to an unstructured grid: gridInqUUID

The function gridInqUUID returns the UUID to an unstructured grid.

Usage

 

Result

gridInqUUID returns the UUID to an unstructured grid to the parameter uuid.

4.6  Z-axis functions

This section contains functions to define a new vertical Z-axis and to get information from an existing Z-axis. A Z-axis object is necessary to define a variable. The following different Z-axis types are available:

  

4.6.1  Create a vertical Z-axis: zaxisCreate

The function zaxisCreate creates a vertical Z-axis.

Usage

 

Result

zaxisCreate returns an identifier to the Z-axis.

Example

Here is an example using zaxisCreate to create a pressure level Z-axis:

4.6.2  Destroy a vertical Z-axis: zaxisDestroy

Usage

 

4.6.3  Get the type of a Z-axis: zaxisInqType

The function zaxisInqType returns the type of a Z-axis.

Usage

 

Result

zaxisInqType returns the type of the Z-axis, one of the set of predefined CDI Z-axis types. The valid CDI Z-axis types are ZAXIS_GENERIC, ZAXIS_SURFACE, ZAXIS_HYBRID, ZAXIS_SIGMA, ZAXIS_PRESSURE, ZAXIS_HEIGHT, ZAXIS_ISENTROPIC, ZAXIS_ALTITUDE, ZAXIS_MEANSEA, ZAXIS_TOA, ZAXIS_SEA_BOTTOM, ZAXIS_ATMOSPHERE, ZAXIS_CLOUD_BASE, ZAXIS_CLOUD_TOP, ZAXIS_ISOTHERM_ZERO, ZAXIS_SNOW, ZAXIS_LAKE_BOTTOM, ZAXIS_SEDIMENT_BOTTOM, ZAXIS_SEDIMENT_BOTTOM_TA, ZAXIS_SEDIMENT_BOTTOM_TW, ZAXIS_MIX_LAYER, ZAXIS_DEPTH_BELOW_SEA and ZAXIS_DEPTH_BELOW_LAND.

4.6.4  Get the size of a Z-axis: zaxisInqSize

The function zaxisInqSize returns the size of a Z-axis.

Usage

 

Result

zaxisInqSize returns the number of levels of a Z-axis.

4.6.5  Define the levels of a Z-axis: zaxisDefLevels

The function zaxisDefLevels defines the levels of a Z-axis.

Usage

 

4.6.6  Get all levels of a Z-axis: zaxisInqLevels

The function zaxisInqLevels returns all levels of a Z-axis.

Usage

 

Result

zaxisInqLevels saves all levels to the parameter levels.

4.6.7  Get one level of a Z-axis: zaxisInqLevel

The function zaxisInqLevel returns one level of a Z-axis.

Usage

 

Result

zaxisInqLevel returns the level of a Z-axis.

4.6.8  Define the name of a Z-axis: zaxisDefName

The function zaxisDefName defines the name of a Z-axis.

Usage

 

4.6.9  Get the name of a Z-axis: zaxisInqName

The function zaxisInqName returns the name of a Z-axis.

Usage

 

Result

zaxisInqName returns the name of the Z-axis to the parameter name.

4.6.10  Define the longname of a Z-axis: zaxisDefLongname

The function zaxisDefLongname defines the longname of a Z-axis.

Usage

 

4.6.11  Get the longname of a Z-axis: zaxisInqLongname

The function zaxisInqLongname returns the longname of a Z-axis.

Usage

 

Result

zaxisInqLongname returns the longname of the Z-axis to the parameter longname.

4.6.12  Define the units of a Z-axis: zaxisDefUnits

The function zaxisDefUnits defines the units of a Z-axis.

Usage

 

4.6.13  Get the units of a Z-axis: zaxisInqUnits

The function zaxisInqUnits returns the units of a Z-axis.

Usage

 

Result

zaxisInqUnits returns the units of the Z-axis to the parameter units.

4.7  T-axis functions

This section contains functions to define a new Time axis and to get information from an existing T-axis. A T-axis object is necessary to define the time axis of a dataset and must be assiged to a variable list using vlistDefTaxis. The following different Time axis types are available:

  

An absolute time axis has the current time to each time step. It can be used without knowledge of the calendar.

A relative time is the time relative to a fixed reference time. The current time results from the reference time and the elapsed interval. The result depends on the used calendar. CDI supports the following calendar types:

  

4.7.1  Create a Time axis: taxisCreate

The function taxisCreate creates a Time axis.

Usage

 

Result

taxisCreate returns an identifier to the Time axis.

Example

Here is an example using taxisCreate to create a relative T-axis with a standard calendar.

4.7.2  Destroy a Time axis: taxisDestroy

Usage

 

4.7.3  Define the reference date: taxisDefRdate

The function taxisDefRdate defines the reference date of a Time axis.

Usage

 

4.7.4  Get the reference date: taxisInqRdate

The function taxisInqRdate returns the reference date of a Time axis.

Usage

 

Result

taxisInqRdate returns the reference date.

4.7.5  Define the reference time: taxisDefRtime

The function taxisDefRtime defines the reference time of a Time axis.

Usage

 

4.7.6  Get the reference time: taxisInqRtime

The function taxisInqRtime returns the reference time of a Time axis.

Usage

 

Result

taxisInqRtime returns the reference time.

4.7.7  Define the verification date: taxisDefVdate

The function taxisDefVdate defines the verification date of a Time axis.

Usage

 

4.7.8  Get the verification date: taxisInqVdate

The function taxisInqVdate returns the verification date of a Time axis.

Usage

 

Result

taxisInqVdate returns the verification date.

4.7.9  Define the verification time: taxisDefVtime

The function taxisDefVtime defines the verification time of a Time axis.

Usage

 

4.7.10  Get the verification time: taxisInqVtime

The function taxisInqVtime returns the verification time of a Time axis.

Usage

 

Result

taxisInqVtime returns the verification time.

4.7.11  Define the calendar: taxisDefCalendar

The function taxisDefCalendar defines the calendar of a Time axis.

Usage

 

4.7.12  Get the calendar: taxisInqCalendar

The function taxisInqCalendar returns the calendar of a Time axis.

Usage

 

Result

taxisInqCalendar returns the type of the calendar, one of the set of predefined CDI calendar types. The valid CDI calendar types are CALENDAR_STANDARD, CALENDAR_PROLEPTIC, CALENDAR_360DAYS, CALENDAR_365DAYS and CALENDAR_366DAYS.

Bibliography

A.  Quick Reference

This appendix provide a brief listing of the C language bindings of the CDI library routines:

gridCreate

Create a horizontal Grid (4.5.1)

gridDefNP

Define the number of parallels between a pole and the equator (4.5.10)

gridDefNumber

Define the reference number for an unstructured grid (4.5.32)

gridDefPosition

Define the position of grid in the reference file (4.5.34)

gridDefReference

Define the reference URI for an unstructured grid (4.5.36)

gridDefUUID

Define the UUID for an unstructured grid (4.5.38)

gridDefXbounds

Define the bounds of a X-axis (4.5.16)

gridDefXlongname

Define the longname of a X-axis (4.5.22)

gridDefXname

Define the name of a X-axis (4.5.20)

gridDefXsize

Define the number of values of a X-axis (4.5.6)

gridDefXunits

Define the units of a X-axis (4.5.24)

gridDefXvals

Define the values of a X-axis (4.5.12)

gridDefYbounds

Define the bounds of a Y-axis (4.5.18)

gridDefYlongname

Define the longname of a Y-axis (4.5.28)

gridDefYname

Define the name of a Y-axis (4.5.26)

gridDefYsize

Define the number of values of a Y-axis (4.5.8)

gridDefYunits

Define the units of a Y-axis (4.5.30)

gridDefYvals

Define the values of a Y-axis (4.5.14)

gridDestroy

Destroy a horizontal Grid (4.5.2)

gridDuplicate

Duplicate a horizontal Grid (4.5.3)

gridInqNP

Get the number of parallels between a pole and the equator (4.5.11)

gridInqNumber

Get the reference number to an unstructured grid (4.5.33)

gridInqPosition

Get the position of grid in the reference file (4.5.35)

gridInqReference

Get the reference URI to an unstructured grid (4.5.37)

gridInqSize

Get the size of a Grid (4.5.5)

gridInqType

Get the type of a Grid (4.5.4)

gridInqUUID

Get the UUID to an unstructured grid (4.5.39)

gridInqXbounds

Get the bounds of a X-axis (4.5.17)

gridInqXlongname

Get the longname of a X-axis (4.5.23)

gridInqXname

Get the name of a X-axis (4.5.21)

gridInqXsize

Get the number of values of a X-axis (4.5.7)

gridInqXunits

Get the units of a X-axis (4.5.25)

gridInqXvals

Get all values of a X-axis (4.5.13)

gridInqYbounds

Get the bounds of a Y-axis (4.5.19)

gridInqYlongname

Get the longname of a Y-axis (4.5.29)

gridInqYname

Get the name of a Y-axis (4.5.27)

gridInqYsize

Get the number of values of a Y-axis (4.5.9)

gridInqYunits

Get the units of a Y-axis (4.5.31)

gridInqYvals

Get all values of a Y-axis (4.5.15)

streamClose

Close an open dataset (4.1.3)

streamDefByteorder

Define the byte order (4.1.5)

streamDefRecord

Define the next record (??)

streamDefTimestep

Define time step (4.1.9)

streamDefVlist

Define the variable list (4.1.7)

streamInqByteorder

Get the byte order (4.1.6)

streamInqFiletype

Get the filetype (4.1.4)

streamInqTimestep

Get time step (4.1.10)

streamInqVlist

Get the variable list (4.1.8)

streamOpenRead

Open a dataset for reading (4.1.2)

streamOpenWrite

Create a new dataset (4.1.1)

streamReadVar

Read a variable (4.1.15)

streamReadVarF

Read a variable (4.1.16)

streamReadVarSlice

Read a horizontal slice of a variable (4.1.17)

streamReadVarSliceF

Read a horizontal slice of a variable (4.1.18)

streamWriteVar

Write a variable (4.1.11)

streamWriteVarF

Write a variable (4.1.12)

streamWriteVarSlice

Write a horizontal slice of a variable (4.1.13)

streamWriteVarSliceF

Write a horizontal slice of a variable (4.1.14)

taxisCreate

Create a Time axis (4.7.1)

taxisDefCalendar

Define the calendar (4.7.11)

taxisDefRdate

Define the reference date (4.7.3)

taxisDefRtime

Define the reference time (4.7.5)

taxisDefVdate

Define the verification date (4.7.7)

taxisDefVtime

Define the verification time (4.7.9)

taxisDestroy

Destroy a Time axis (4.7.2)

taxisInqCalendar

Get the calendar (4.7.12)

taxisInqRdate

Get the reference date (4.7.4)

taxisInqRtime

Get the reference time (4.7.6)

taxisInqVdate

Get the verification date (4.7.8)

taxisInqVtime

Get the verification time (4.7.10)

vlistCat

Concatenate two variable lists (4.2.5)

vlistCopy

Copy a variable list (4.2.3)

vlistCopyFlag

Copy some entries of a variable list (4.2.6)

vlistCreate

Create a variable list (4.2.1)

vlistDefAttFlt

Define a floating point attribute (4.4.5)

vlistDefAttInt

Define an integer attribute (4.4.3)

vlistDefAttTxt

Define a text attribute (4.4.7)

vlistDefTaxis

Define the time axis (4.2.10)

vlistDefVar

Define a Variable (4.3.1)

vlistDefVarCode

Define the code number of a Variable (4.3.4)

vlistDefVarDatatype

Define the data type of a Variable (4.3.14)

vlistDefVarLongname

Define the long name of a Variable (4.3.8)

vlistDefVarMissval

Define the missing value of a Variable (4.3.16)

vlistDefVarName

Define the name of a Variable (4.3.6)

vlistDefVarStdname

Define the standard name of a Variable (4.3.10)

vlistDefVarUnits

Define the units of a Variable (4.3.12)

vlistDestroy

Destroy a variable list (4.2.2)

vlistDuplicate

Duplicate a variable list (4.2.4)

vlistInqAtt

Get information about an attribute (4.4.2)

vlistInqAttFlt

Get the value(s) of a floating point attribute (4.4.6)

vlistInqAttInt

Get the value(s) of an integer attribute (4.4.4)

vlistInqAttTxt

Get the value(s) of a text attribute (4.4.8)

vlistInqNatts

Get number of variable attributes (4.4.1)

vlistInqTaxis

Get the time axis (4.2.11)

vlistInqVarCode

Get the Code number of a Variable (4.3.5)

vlistInqVarDatatype

Get the data type of a Variable (4.3.15)

vlistInqVarGrid

Get the Grid ID of a Variable (4.3.2)

vlistInqVarLongname

Get the longname of a Variable (4.3.9)

vlistInqVarMissval

Get the missing value of a Variable (4.3.17)

vlistInqVarName

Get the name of a Variable (4.3.7)

vlistInqVarStdname

Get the standard name of a Variable (4.3.11)

vlistInqVarUnits

Get the units of a Variable (4.3.13)

vlistInqVarZaxis

Get the Zaxis ID of a Variable (4.3.3)

vlistNgrids

Number of grids in a variable list (4.2.8)

vlistNvars

Number of variables in a variable list (4.2.7)

vlistNzaxis

Number of zaxis in a variable list (4.2.9)

zaxisCreate

Create a vertical Z-axis (4.6.1)

zaxisDefLevels

Define the levels of a Z-axis (4.6.5)

zaxisDefLongname

Define the longname of a Z-axis (4.6.10)

zaxisDefName

Define the name of a Z-axis (4.6.8)

zaxisDefUnits

Define the units of a Z-axis (4.6.12)

zaxisDestroy

Destroy a vertical Z-axis (4.6.2)

zaxisInqLevel

Get one level of a Z-axis (4.6.7)

zaxisInqLevels

Get all levels of a Z-axis (4.6.6)

zaxisInqLongname

Get the longname of a Z-axis (4.6.11)

zaxisInqName

Get the name of a Z-axis (4.6.9)

zaxisInqSize

Get the size of a Z-axis (4.6.4)

zaxisInqType

Get the type of a Z-axis (4.6.3)

zaxisInqUnits

Get the units of a Z-axis (4.6.13)

B.  Examples

This appendix contains complete examples to write, read and copy a dataset with the CDI library.

B.1  Write a dataset

Here is an example using CDI to write a NetCDF dataset with 2 variables on 3 time steps. The first variable is a 2D field on surface level and the second variable is a 3D field on 5 pressure levels. Both variables are on the same lon/lat grid.

B.1.1  Result

This is the ncdump -h output of the resulting NetCDF file example.nc.

B.2  Read a dataset

This example reads the NetCDF file example.nc from Appendix B.1.

B.3  Copy a dataset

This example reads the NetCDF file example.nc from Appendix B.1 and writes the result to a GRIB dataset by simple setting the output file type to FILETYPE_GRB.

C.  Environment Variables

The following table describes the environment variables that affect CDI.