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 atomic types or small arrays of such types. 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.

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.

h5_compound.c

compound.f90

Compound.java

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 creates a new datatype of the specified class with the specified number of bytes.
```
    hid_t H5Tcreate ( H5T_class_t class, size_t size ) 
```
- The class parameter specifies the datatype to create. Currently only the H5T_COMPOUND datatype class is supported with this function.
- The size parameter specifies the number of bytes in the datatype to create.
H5Tinsert adds a member to the compound datatype specified by type_id.
```
   herr_t H5Tinsert ( hid_t type_id, const char * name, off_t offset, 
                      hid_t field_id ) 
```
- The type_id parameter is the identifier of the compound datatype to modify.
- The name parameter is the name of the field to insert. The new member name must be unique within a compound datatype.
- The offset parameter is the offset in the memory structure of the field to insert. The library defines the HOFFSET macro 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.
- The field_id parameter is the datatype identifier of the field to insert.
H5Tclose releases a datatype.
```
   herr_t H5Tclose ( hid_t type_id ) 
```
The type_id parameter is the identifier of the datatype to release.

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 ]
         }
      }
   }
}
}

The National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign

hdfhelp@ncsa.uiuc.edu
Describes HDF5 Release 1.2.2, June 2000