Please see The HDF Group's new Support Portal for the latest information.
Contents:
- References to Objects
- Creating and Storing References to Objects
- Reading References and Accessing Objects Using References
- Programming Example
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