netCDF  4.2.1.1
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
User Defined Types

Compound Types

In netCDF-4 files it's possible to create a data type which corresponds to a C struct. These are known as “compound” types (following HDF5 nomenclature).

That is, a netCDF compound type is a data structure which contains an arbitrary collection of other data types, including other compound types.

To define a new compound type, use nc_def_compound(). Then call nc_insert_compound() for each type within the compound type.

Read and write arrays of compound data with the nc_get_vara() and nc_put_vara() functions. These functions were actually part of the netCDF-2 API, brought out of semi-retirement to handle user-defined types in netCDF-4.

Opaque Types

Store blobs of bits in opaque types. Create an opaque type with nc_def_opaque. Read and write them with nc_get_vara()/nc_put_vara().

Variable Length Arrays (VLEN)

Create a VLEN type to store variable length arrays of a known base type. Use nc_def_vlen() to define a VLEN type, read and write them with nc_get_vara()/nc_put_vara().

NetCDF supported six data types through version 3.6.0 (char, byte, short, int, float, and double).

Starting with version 4.0, many new data types are supported (unsigned int types, strings, compound types, variable length arrays, enums, opaque).

In addition to the new atomic types the user may define types.

Types are defined in define mode, and must be fully defined before they are used. New types may be added to a file by re-entering define mode.

Once defined the type may be used to create a variable or attribute.

Types may be nested in complex ways. For example, a compound type containing an array of VLEN types, each containing variable length arrays of some other compound type, etc. Users are cautioned to keep types simple. Reading data of complex types can be challenging for Fortran users.

Types may be defined in any group in the data file, but they are always available globally in the file.

Types cannot have attributes (but variables of the type may have attributes).

Only files created with the netCDF-4/HDF5 mode flag (NC_NETCDF4) but without the classic model flag (NC_CLASSIC_MODEL) may use user-defined types or the new atomic data types.

Once types are defined, use their ID like any other type ID when defining variables or attributes. Use functions nc_put_att()/nc_get_att() and the nc_put_var()/nc_get_var(), nc_put_var1()/nc_get_var1(), nc_put_vara()/nc_get_vara(), or nc_put_vars()/nc_get_vars() functons to access attribute and variable data of user defined type.

Types

Compound types allow the user to combine atomic and user-defined types into C-like structs. Since users defined types may be used within a compound type, they can contain nested compound types.

Users define a compound type, and (in their C code) a corresponding C struct. They can then use nc_put_vara() and related functions to write multi-dimensional arrays of these structs, and nc_get_vara() calls to read them.

While structs, in general, are not portable from platform to platform, the HDF5 layer (when installed) performs the magic required to figure out your platform's idiosyncrasies, and adjust to them. The end result is that HDF5 compound types (and therefore, netCDF-4 compound types), are portable.

For more information on creating and using compound types, see Compound Types in The NetCDF C Interface Guide.

Types

Variable length arrays can be used to create a ragged array of data, in which one of the dimensions varies in size from point to point.

An example of VLEN use would the to store a 1-D array of dropsonde data, in which the data at each drop point is of variable length.

There is no special restriction on the dimensionality of VLEN variables. It's possible to have 2D, 3D, 4D, etc. data, in which each point contains a VLEN.

A VLEN has a base type (that is, the type that it is a VLEN of). This may be one of the atomic types (forming, for example, a variable length array of NC_INT), or it can be another user defined type, like a compound type.

With VLEN data, special memory allocation and deallocation procedures must be followed, or memory leaks may occur.

Compression is permitted but may not be effective for VLEN data, because the compression is applied to structures containing lengths and pointers to the data, rather than the actual data.

For more information on creating and using variable length arrays, see Variable Length Arrays in The NetCDF C Interface Guide.

Types

Opaque types allow the user to store arrays of data blobs of a fixed size.

For more information on creating and using opaque types, see Opaque Type in The NetCDF C Interface Guide.

Types

Enum types allow the user to specify an enumeration.

For more information on creating and using enum types, see Enum Type in The NetCDF C Interface Guide.


Generated on Wed Aug 22 2012 14:39:40 for netCDF. NetCDF is a Unidata library.