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

HOME > HDF5 > TUTOR

HDF5 Tutorial: Advanced Topics
References to Objects

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:

Create the objects or open them if they already exist in the file.
Create a dataset to store references to the objects.
Create and store references to the objects in a buffer.
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:

Open the dataset with the references and read them. The H5T_STD_REF_OBJ datatype must be used to describe the memory datatype.
Use the read reference to obtain the identifier of the object the reference points to.
Open the dereferenced object and perform the desired operations.
Close all objects when the task is complete.

Programming Example

Description

The examples below create objects (group, dataset, ...), create references to those objects (in an object reference dataset), and then close the objects and object reference dataset. Then they re-open the object references dataset, and re-open the objects by dereferencing the references in the object reference dataset.

C example

h5ex_t_objref.c

FORTRAN example

refobjexample.f90

Remarks

An Object Reference dataset can be created by calling H5Dcreate / h5dcreate_f with an object reference datatype (H5T_STD_REF_OBJ) for the datatype identifier parameter.
The H5Rcreate / h5rcreate_f call creates the reference.
When calling H5Dwrite / h5dwrite_f to write to the dataset of references, the H5T_SDT_REF_OBJ datatype is used to describe the dataset's memory datatype.
H5Dread / h5dread_f reads the dataset containing the references to the objects. The H5T_STD_REF_OBJ memory datatype is used to read the references to memory.
The H5Rdereference / h5rdereference_f call opens the object and returns the object's identifier.

- - Last modified: 21 December 2016

HDF5 Tutorial: Advanced Topics References to Objects

Contents: