Next: , Previous: Classic Data Structures, Up: Data


3.3 NetCDF-4 User Defined Data Types

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, NF_NETCDF4, or NF90_NETCDF4), but without the classic model flag (NC_CLASSIC_MODEL, NF_CLASSIC_MODEL, or NF90_CLASSIC_MODEL.)

Once types are defined, use their ID like any other type ID when defining variables or attributes. Each API has functions to read and write variables and attributes of any type. Use these functions to read and write variables and attributes of user defined type. In C use 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.

3.3.1 Compound 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 the nc_put_var[1asm] calls to write multi-dimensional arrays of these structs, and nc_get_var[1asm] calls to read them. (For example, the nc_put_varm function will write mapped arrays of these structs.)

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.

3.3.2 VLEN 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.

3.3.3 Opaque 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.

3.3.4 Enum 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.

3.3.5 Groups

Although not a type of data, groups can help organize data within a dataset. Like a directory structure on a Unix file-system, the grouping feature allows users to organize variables and dimensions into distinct, named, hierarchical areas, called groups. For more information on groups types, see Groups in The NetCDF C Interface Guide.