[ HDF5 Tutorial Top ]

# References to Objects

## Contents:

- References to Objects
- Creating and Storing References to Objects
- Reading References and Accessing Objects Using References
- Programming Example
  - Description
  - Remarks
  - File 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.

[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

###### Last Modified: June 22, 2001