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

[

C example

h5_ref2obj.c

FORTRAN example

refobjexample.f90

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

The following code creates a dataset in which to store the references.
C:
```
    dset2_id = H5Dcreate (file_id, dsetname, H5T_STD_REF_OBJ, 
                         space_id, H5P_DEFAULT);
```
FORTRAN:
```
    CALL h5dcreate_f (file_id, dsetname, H5T_STD_REF_OBJ, & 
                      space_id, dset2_id, hdferr)
```
Notice that the H5T_SDT_REF_OBJ datatype is used to specify that references to objects will be stored. The datatype H5T_STD_REF_DSETREG is used to store the dataset region references and will be discussed later in this tutorial.
The next few calls to H5Rcreate / h5rcreate_f create references to the objects. The signature of H5Rcreate / h5rcreate_f is as follows:
C:
```
    herr_t H5Rcreate (void* ref, hid_t loc_id, const char *name, 
                      H5R_type_t ref_type, hid_t space_id)    
```
FORTRAN:
```
    h5rcreate_f (loc_id, name, ref, hdferr)

           loc_id     IN: INTEGER (HID_T) 
           name       IN: CHARACTER(LEN=*)
           ref       OUT: TYPE (hobj_ref_t_f)
           hdferr    OUT: INTEGER
```
- The ref argument specifies the buffer in which to store the reference.
- The loc_id and name arguments specify the name of the referenced object.
- In C, the ref_type argument specifies the type of the reference. Our example uses references to objects, H5R_OBJECT. References to dataset regions, H5R_DATASET_REGION, will be discussed later in this tutorial.
- In C, the space_id argument specifies the dataspace identifier. When references to the objects are created, this argument should be set to -1.
- In FORTRAN, the return value from the h5rcreate_f call is in hdferr: 0 if successful, -1 otherwise. In C, H5Rcreate returns a non-negative value if successful and a negative value otherwise.
H5Dwrite / h5dwrite_f writes a dataset containing the references. Notice that 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 was used to read references to memory.
H5Rdereference / h5rdereference_f obtains the object's identifier. The signature is as follows:
C:
```
    hid_t H5Rdereference (hid_t dset_id, H5R_type_t ref_type, 
                          void *ref)
```
FORTRAN:
```
    h5rdereference_f (dset_id, ref, obj_id, hdferr)

            dset_id    IN:   INTEGER (HID_T)
            ref        IN:   TYPE (hobj_ref_t_f)
            obj_id    OUT:   INTEGER (HID_T)
            hdferr    OUT:   INTEGER
```
- The dset_id argument is the identifier of the dataset containing the references.
- In C, the ref_type argument specifies the reference type.
- The ref argument is a buffer containing the reference to be dereferenced.
- The C function returns the identifier of the object that the reference points to or a negative value if it is unsuccessful. In FORTRAN, the object identifier is returned in obj_id and the return code is returned in hdferr.
  In our simplified situation, we know what type of object was stored in the dataset. When the type of the object is unknown, H5Rget_object_type should be used to identify the type of object the reference points to.

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.

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

hdfhelp@ncsa.uiuc.edu

References to Objects

Contents: