HDF5 Tutorial: Advanced Topics
Compound Datatypes

Creating Compound Datatypes

A compound datatype is similar to a struct in C or a common block in FORTRAN. It is a collection of one or more datatypes and can include compound datatypes. To create and use a compound datatype you need to be familiar with various properties of the compound datatype:

It is of class compound.
It has a fixed total size, in bytes.
It consists of zero or more members (defined in any order) with unique names and occupying non-overlapping regions within the datum.
Each member has its own datatype.
Each member is referenced by an index number between zero and N-1, where N is the number of members in the compound datatype.
Each member has a name which is unique among its siblings in a compound datatype.
Each member has a fixed byte offset, which locates the first byte (smallest byte address) of that member in the compound datatype.
Each member can be a small array of up to four dimensions.

Properties of members of a compound datatype are defined when the member is added to the compound datatype and cannot be subsequently modified.

Compound datatypes must be built out of other datatypes. First, one creates an empty compound datatype and specifies its total size. Then members are added to the compound datatype in any order.

High Level APIs

The High Level HDF5 Table APIs (H5TB) include functions to easily create tables in HDF5, using a compound datatype. Please be sure to review them, in addition to this tutorial.

Programming Example

Description

This example shows how to create a compound datatype, write an array to the file which uses the compound datatype, and read back subsets of the members.

C Example

h5_compound.c

Fortran 90 Example

compound.f90

The program outputs the following:


Field c : 
1.0000 0.5000 0.3333 0.2500 0.2000 0.1667 0.1429 0.1250 0.1111 0.1000 

Field a : 
0 1 2 3 4 5 6 7 8 9 

Field b : 
0.0000 1.0000 4.0000 9.0000 16.0000 25.0000 36.0000 49.0000 64.0000 81.0000 

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Remarks

H5Tcreate / h5tcreate_f creates a new datatype of the specified class with the specified number of bytes.
H5Tinsert / h5tinsert_f adds a member to the compound datatype specified by the datatype identifier.

The library defines the HOFFSET macro that can be used to compute the offset of a member within a struct:
```
  HOFFSET ( s, m ) 
```
This macro computes the offset of member m within a struct variable s.
H5Tclose / h5tclose_f releases a datatype.

File Contents

HDF5 "SDScompound.h5" {
GROUP "/" {
   DATASET "ArrayOfStructures" {
      DATATYPE {
         H5T_STD_I32BE "a_name";
         H5T_IEEE_F32BE "b_name";
         H5T_IEEE_F64BE "c_name";
      }
      DATASPACE { SIMPLE ( 10 ) / ( 10 ) }
      DATA {
         {
            [ 0 ],
            [ 0 ],
            [ 1 ]
         },
         {
            [ 1 ],
            [ 1 ],
            [ 0.5 ]
         },
         {
            [ 2 ],
            [ 4 ],
            [ 0.333333 ]
         },
         {
            [ 3 ],
            [ 9 ],
            [ 0.25 ]
         },
         {
            [ 4 ],
            [ 16 ],
            [ 0.2 ]
         },
         {
            [ 5 ],
            [ 25 ],
            [ 0.166667 ]
         },
         {
            [ 6 ],
            [ 36 ],
            [ 0.142857 ]
         },
         {
            [ 7 ],
            [ 49 ],
            [ 0.125 ]
         },
         {
            [ 8 ],
            [ 64 ],
            [ 0.111111 ]
         },
         {
            [ 9 ],
            [ 81 ],
            [ 0.1 ]
         }
      }
   }
}
}

- - Last modified:September 23rd 2009

HDF5 Tutorial: Advanced TopicsCompound Datatypes