[ HDF5 Tutorial Top ] [ Advanced Topics Top ] [ Next ] [ Prev ]

References to Objects


Contents:


References to Objects

In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name. This access method was discussed in previous sections. There is another way to access stored objects - by reference.

An object reference is based on the relative file address of the object header in the file and is constant for the life of the object. Once a reference to an object is created and stored in a dataset in the file, it can be used to dereference the object it points to. References are handy for creating a file index or for grouping related objects by storing references to them in one dataset.

Creating and Storing References to Objects

The following steps are involved in creating and storing file references to objects:
  1. Create the objects or open them if they already exist in the file.

  2. Create a dataset to store references to the objects.

  3. Create and store references to the objects in a buffer.

  4. Write the buffer containing the references to the dataset.

Reading References and Accessing Objects Using References

The following steps are involved in reading references to objects and accessing objects using references:
  1. Open the dataset with the references and read them. The H5T_STD_REF_OBJ datatype must be used to describe the memory datatype.

  2. Use the read reference to obtain the identifier of the object the reference points to.

  3. Open the dereferenced object and perform the desired operations.

  4. Close all objects when the task is complete.

Programming Example

Description

The example below first creates a group in the file. It then creates two datasets and a named datatype in that group. References to these four objects are stored in a dataset in the root group.

After that, it opens and reads the reference dataset from the file created previously, then dereferences the references.

NOTE: To download a tar file of the examples, including a Makefile, please go to the References page.

Following is the output from the examples:

  Data has been successfully written to the dataset 
  Stored datatype is of a FLOAT class

Remarks

File Contents

HDF5 File Created by C Example

Fig. A   REF_OBJ.h5 in DDL

HDF5 "REF_OBJ.h5" {
GROUP "/" {
   GROUP "GROUP1" {
      GROUP "GROUP2" {
      }
   }
   DATASET "INTEGERS" {
      DATATYPE { H5T_STD_I32BE }
      DATASPACE { SIMPLE ( 5 ) / ( 5 ) }
      DATA {
         1, 2, 3, 4, 5
      }
   }
   DATATYPE "MYTYPE" {
   }
   DATASET "OBJECT_REFERENCES" {
      DATATYPE { H5T_REFERENCE }
      DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
      DATA {
         GROUP 0:1320, GROUP 0:2272, DATASET 0:2648, DATATYPE 0:3244
      }
   }
}
}


HDF5 File Created by FORTRAN Example:

Fig. B   FORTRAN.h5 in DDL

HDF5 "FORTRAN.h5" {
GROUP "/" {
   GROUP "GROUP1" {
      GROUP "GROUP2" {
      }
   }
   DATASET "INTEGERS" {
      DATATYPE { H5T_STD_I32BE }
      DATASPACE { SIMPLE ( 5 ) / ( 5 ) }
      DATA {
         1, 2, 3, 4, 5
      }
   }
   DATATYPE "MyType" {
   }
   DATASET "OBJECT_REFERENCES" {
      DATATYPE { H5T_REFERENCE }
      DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
      DATA {
         GROUP 0:1344, GROUP 0:2320, DATASET 0:2696, DATATYPE 0:3292
      }
   }
}
}

Notice how the data in the reference dataset is described. The two numbers separated by a colon represent a unique identifier of the object. These numbers are constant for the life of the object.


NCSA
The National Center for Supercomputing Applications

University of Illinois at Urbana-Champaign

hdfhelp@ncsa.uiuc.edu

Last Modified: November 21, 2001