HDF5_module [casa core modules (libcasa_casa)]

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

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

---

Detailed Description

Classes binding casa 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 casa data types (scalars and arrays) are fully supported. Because HDF5 does not support empty strings, they are transparantly replaced by the value '__empty__'. Unfortunately HDF5 does not support empty arrays, thus they cannot be stored.
• 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 casa Arrays use Fortran-order.
• Automatic printing of HDF5 messages is disabled. All errors are thrown as exceptions (AipsError or derived from it).

The following 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.
• 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. Currently the only data types supported are Bool, Int, Float, Double, Complex, and DComplex.
• 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 casa's CountedPtr or boost's 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 casacore;googlecode;com 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 casa data types, in particular reversal of array axes was needed.

To Do

• Make it possible to store empty arrays (e.g. as a compound of a scalar (defining its type) and a vector (defining its shape).
• Set the optimal data set chunk cache size from a given access pattern. The current problem is that you can only set the cache size at the HDF5 file level, not at the data set level. Furthermore, 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.