- - Quick Links - - HDF5 HDF4 Tools Projects Downloads Documentation Publications Contact Us

• LINKS
• Main Website
• What is HDF5?
• Online Brochure
• Downloads
• Documentation
• Software using HDF5
• HDF5 Users
• Sample HDF5 Files
• Acknowledgments
• Licenses

This web site is no longer maintained (but will remain online).
Please see The HDF Group's new Support Portal for the latest information.

HDF5 Tutorial:   Advanced Topics
Compound Datatypes

Contents:

• Creating Compound Datatypes
• High Level APIs
• Programming Example
  • Description
  • Remarks

---

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 one 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 dataset with a compound datatype, write data to it, and then read data back.

[ C Example ] - h5ex_t_cmpd.c
[ Fortran 90 Example ] - compound.f90

Remarks

• H5Tcreate / h5tcreate_f creates a new datatype of the specified class with the specified number of bytes. To create a compound datatype, H5T_COMPOUND is specified for the class.

• 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.

---

- - Last modified: 21 December 2016