This Chapter presents HL-HDF's building blocks so that the user will have a knowledge of the proper terminology prior to working hands-on with the library.

To make the most of the functionality in HL-HDF, users should have a working knowledge of the C programming language.

This documentation is designed to be complimentary to the official HDF5 documentation and users should refer to the official set for more detail on HDF5's internal mechanisms.

The Hierarchy

The "H" in HDF stands for "Heirarchical" and this describes how HDF files are structured. An HDF file can be likened to a file system. At the root of the file system is a period (".") or a slash ("/") and the file may consist of an arbitrary number of levels of data, like subdirectories in a file system. For example, if a NOAA satellite image containing several spectral bands of data are stored in this manner, one way of doing so could look like this:

.
/NOAA 14/
/NOAA 14/info
/NOAA 14/info/xsize
/NOAA 14/info/ysize
/NOAA 14/Channel 1/
/NOAA 14/Channel 2/
/NOAA 14/Channel 3/

where info is an object containing header information. The same strategy could be used to store several polar scans of weather radar data, for example. Alternatively, a numerical weather prediction model state could be represented in part using GRIB descriptors like this:

.
/Level 0/
/Level 0/Type 105/
/Level 0/Type 105/Parameter 11/
/Level 0/Type 102/
/Level 31/
/Level 31/Type 109/
/Level 31/Type 109/Parameter 11/

Or, why not a point from a weather station containing wind speed and direction values:

.
/WMO 02064/
/WMO 02064/dd/
/WMO 02064/ff/
/WMO 02036/

HL-HDF Building Blocks

HL-HDF provides a number of building blocks which are defined in detail in the header file hlhdf_types.h.

Datatype

A Datatype is a data representation consisting of atomic data types such as a string, byte, integer, floating point value of a given word size, or in the form of a C struct containing combinations of atomic types. A Datatype is used to describe the characteristics of one's data, and a number of Datatypes may collectively constitute a header. Every Datatype is given a name which is stored in a string; this string is used to represent the Datatype in the HDF file.

Attribute

An Attribute contains a string used to identify it, an array with up to four dimensions, and a number of Datatypes describing that Attribute. An Attribute is an appropriate object for storing point values, for example, and storing time series of them is enabled in the Attribute object.

Reference

A Reference is basically a pointer to another object. A Reference can only be pointed to a Datatype, a Dataset or a Group. Using the Reference might be needed when generating HDF5 images, since a reference to a palette has to be inserted in the Dataset object.

Dataset

A Dataset is a higher level object and contains a string used to identify it, an optional array with between one and four dimensions, an array of Datatypes, and an array of Attributes. A Dataset is an appropriate object for storing profile (transect) or image data, and it can be used to store time series of a given variable.

Group

A Group is the highest level object and consists of a string used to identify it and an arbitrary combination of any of the Datatype, Attribute, Dataset, and Group building blocks. The root of any HDF5 file (denoted with "." or "/") is always a Group.

Node

A Node is a term used in the HL-HDF code to refer to any of the above mentioned building blocks in an HDF5 file. In other words, any given object in the heirarchy is a Node.

Scalar

A Scalar is an individual value.

Atomic

In HDF5 the predefined datatypes (for example 'int', 'short', ...) are referred to as Atomic, as opposed to the Compound datatypes which are a combination of Atomic datatypes.

C Header Definitions

The previous section presented the principles of HL-HDF building blocks. This section presents their actual names and their definitions, along with some fundamentals from HDF5 itself.

hid_t

This variable comes from HDF5 and is a type for managing references to nodes. Each node reference is represented as an integer and hid_t keeps track of them.

herr_t

This variable comes from HDF5 and is a type for handling error codes.

hsize_t

This variable comes from HDF5 and represents a native multiple-precision integer.

HL-HDF defined types.

Most of the types defined in HL-HDF can be found in hlhdf_types.h.