HDF5_module

Classes binding casacore to the HDF5 C API. More...

Modules
	HDF5_module_internal_classes
	Internal HDF5_module classes and functions.

Classes
class	casacore::HDF5DataSet
	A class representing an HDF5 data set. More...
class	casacore::HDF5Error
	Base error class for HDF5 wrapper classes. More...
class	casacore::HDF5File
	A class representing an HDF5 file. More...
class	casacore::HDF5Group
	A class representing an HDF5 group. More...
class	casacore::HDF5Object
	An abstract base class representing an HDF5 object. More...
class	casacore::HDF5Record
	A class to write/read a record into HDF5. More...

Detailed Description

Classes binding casacore to the HDF5 C API.

See below for an overview of the classes in this module.

Prerequisite

• HDF5 (see http://www.hdfgroup.uiuc.edu/HDF5/doc_dev_snapshot)

Etymology

'HDF5' is version 5 of the Hierarchical Data Format.

Synopsis

This module's main purpose is to provide limited, but convenient access to the HDF5 C API. The classes offer the following services:

• The burden of allocating and releasing the HDF5 resources (the so-called hid-s) is handled in an automatic and exception-safe way.
• The overwhelming and rather hard to use HDF5 C API is hidden.
• The standard casacore data types (scalars and arrays) are supported. Because HDF5 does not support empty strings, they are transparantly replaced by the value 'empty'. Also HDF5 does not support empty arrays, thus they are stored in a special way using a special compound value.
• A Record is stored as a group. Its values (scalars and arrays) are stored as attributes, while nested records are stored as nested groups.
• Bool values are stored as chars.
• Complex values are stored as compounds of two real values.
• Large arrays can be stored in HDF5 DataSets with an optional tile size (chunk size in HDF5 terminology). The array axes are reversed (fully transparantly) because HDF5 uses C-order, while casacore Arrays use Fortran-order.
• Automatic printing of HDF5 messages is disabled. All errors are thrown as exceptions (AipsError or derived from it).

The following interface classes are available:

• HDF5File opens or creates an HDF5 file and closes it automatically. Furthermore it has a function to test if a file is in HDF5 format.
• HDF5DataType defines the HDF5 memory and file data type. It supports the basic data types, complex, string, arrays and compounds.
• HDF5Record reads or writes a Record as a group in an HDF5 object.
• HDF5DataSet opens or creates a possible tiled data set in an HDF5 object. The array can be read or written in parts. It can be created of any HDF5DataType.
• HDF5Group opens, creates, or removes a group in an HDF5 object.

Note that HDF5Object forms the base class of HDF5File, HDF5Group, and HDF5DataSet. Most interfaces use HDF5Object, thus are applicable to all these object types.
An HDF5Object has a conversion operator to hid_t, thus can be used directly in any HDF5 function.

Because of HDF5 resource management the objects (e.g. HDF5File) cannot be copied. However, they can be used in shared pointers (like casacore's CountedPtr or std::shared_ptr).
Internally the classes use HDF5HidMeta.h which does the resource management for HDF5 meta data like attributes, property lists, etc..

Note: All HDF5 classes and all their functions are compiled, but it depends on the setting of HAVE_HDF5 how; If not set, all these functions are merely stubs and the class constructors throw an exception when used; The function HDF5Object::hasHDF5Support() tells if HDF5 is used; See the casacore build instructions at github;com/casacore/casacore for more information;

Example

See the various test programs.

Motivation

HDF5 offers a C++ interface. However, this interface is still quite complex and is too much C-oriented. Furthermore there was the need to support the casacore data types, in particular complex. The reversal of array axes was also needed.

To Do

• Set the optimal data set chunk cache size from a given access pattern. The current problem is that setting the cache size requires that the file is closed first. For the time being a fixed cache size of 16 MB is used instead of the default 1 MB.