Important API changes since version 0.99.11

Overview

Several changes has been made to the H5hut C and Fortran API:

Versions newer than 0.99.13 provide an improved API to open H5hut files. Existing code must be adapted accordingly.
A more complete set of functions to query datasets and attributes has been implemented.
Starting with version 0.99.11 the C-API is implemented with inline functions. This does not require changes in the source code but for linking - the library libh5hutC has been removed.
The compiler wrapper h5hutcc is obsolete and not available any more.
The Fortran API has been reviewed and partially rewritten.
More and better examples has been added some old examples removed.

Changes in API

The API function to open a H5hut file are more general and more flexible making it simpler to add new features. Like in HDF5 you can define properties of a file and pass this properties to the open call. Adapting old code is easy and straight forward.

Open H5hut file

Old implementation

h5_file_t*
H5OpenFile (
	const char* filename,
	h5_int32_t flags,
	MPI_Comm comm
	);

The return type was a pointer to a structure. With the argument flags the access mode of the file and the virtual file driver was selected. In the parallel version comm was used to pass the MPI communicator. In the serial version this argument was ignored.

New implementation

h5_file_t
H5OpenFile (
	const char* const filename,
	const h5_int64_t flags,
        const h5_prop_t props
	);

Return type

The function returns a value of type h5_file_t. This is not a pointer any more.

Argument flags

The type has been changed to h5_int64_t. The virtual file driver cannot be selected via this argument any more. The argument is used to select the file access mode only.

Argument props

By adding properties to the property list passed with the argument props you can

define whether independent or collective I/O should be used.
the virtual file driver can be selected.
the alignment in the HDF5 file can be set.
a throttling factor can be defined.

Property list are explained in more details in the next section.

This argument can also be set to H5_PROP_DEFAULT to use reasonable default values. In the parallel version collective I/O is the default and as MPI communicator MPI_COMM_WORLD will be used.

Example

Open the file example.h5 in the current directory for reading and writing. The code is the same in a serial and parallel version.

h5_file_t h5file = H5OpenFile ("example.h5", H5_O_RDWR, H5_PROP_DEFAULT);

Property lists

In old H5hut version several open function were implemented, for example different versions for opening a file for serial or parallel I/O. Now one function covers all cases. With property list we adopt a feature known from HDF5.

Creating a property list

If you want/have to set special properties to a file, you have to create a file property list first.

h5_prop_t
H5CreateFileProp (
        void
        );

Closing a property list

After using a file property list, you have to close it.

H5CloseProp (
        h5_prop_t prop
        );

Properties

In the following section we give a short overview over the properties you can set for a H5hut file. For more details please read the H5hut API documentation.

Collective I/O

Set property for collective I/O and pass MPI communicator to the H5hut library.

Note: Collective I/O is the default.

h5_err_t
H5SetPropFileMPIOCollective (
        h5_prop_t prop,
	MPI_Comm* comm
        );

Independent I/O

Set property for independent I/O and pass MPI communicator to the H5hut library.

h5_err_t
H5SetPropFileMPIOIndependent (
        h5_prop_t prop,
        MPI_Comm* comm
        );

Posix I/O

Set property for MPI Posix I/O and pass MPI communicator to the H5hut library.

Note: This property is only available if you compile H5hut with HDF5 1.8.12 or older.

h5_err_t
H5SetPropFileMPIOPosix (
        h5_prop_t prop,
        MPI_Comm* comm
        );

Use HDF5 Core Driver

h5_err_t
H5SetPropFileCoreVFD (
        h5_prop_t prop,
	const h5_int64_t increment
        );

Alignment of objects in HDF5

H5SetPropFileAlign (
        h5_prop_t prop,
        const h5_int64_t align
        );

Throttle I/O

h5_err_t
H5SetPropFileThrottle (
        h5_prop_t prop,list
        const h5_int64_t throttle
        )

Compiling and Linking

Compile and link a program written in C

For serial compilation set $CC to something like cc, gcc, icc. For parallel compilation use mpicc.

With H5hut ⇐ 1.99.10

$CC -I/opt/H5hut/1.99/include -c H5test.c
$CC -L/opt/H5hut/1.99/lib -L/opt/hdf5/1.8.19/lib H5test.o -o H5test -lH5hutC -lH5hut -lhdf5 -lz

Now (without -lH5hutC):

$CC -I/opt/H5hut/2.0/include -c H5test.c
$CC -L/opt/H5hut/2.0/lib -L/opt/hdf5/1.8.19/lib H5test.o -o H5test -lH5hut -lhdf5 -lz

Compile and link a program written in Fortran

No changes are required with the new version to link a Fortran program.

For serial compilation set $FC to something like f90. For parallel compilation use mpif90.

$FC -I/opt/H5hut/2.0/include -c H5test.f90
$FC -o H5test H5test.o  -L/opt/hdf5/1.8.19/lib -L/opt/H5hut/2.0/lib  -lH5hutF -lH5hut -lhdf5 -lz

API Changes