- - Quick Links - - HDF5 HDF4 Tools Projects Downloads Documentation Publications Contact Us

• LINKS
• Main Website
• What is HDF5?
• Online Brochure
• Downloads
• Documentation
• Software using HDF5
• HDF5 Users
• Sample HDF5 Files
• Acknowledgments
• Licenses

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

HDF5 Tutorial:   Advanced Topics
References to Regions

Contents:

• References to Dataset Regions
• Creating and Storing References to Dataset Regions
• Reading References to Dataset Regions
• Programming Example
  • Description
  • Remarks

---

References to Dataset Regions

Previously you learned about creating, reading, and writing dataset selections. Here you will learn how to store dataset selections in a file, and how to read them back using references to dataset regions.

A dataset region reference points to the dataset selection by storing the relative file address of the dataset header and the global heap offset of the referenced selection. The selection referenced is located by retrieving the coordinates of the areas in the selection from the global heap. This internal mechanism of storing and retrieving dataset selections is transparent to the user. A reference to a dataset selection (a region) is constant for the life of the dataset.

Creating and Storing References to Dataset Regions

The following steps are involved in creating and storing references to dataset regions:

1. Create a dataset in which to store the dataset regions (the selections).

2. Create selections in the dataset(s). The dataset(s) should already exist in the file.

3. Create references to the selections and store them in a buffer.

4. Write the dataset region references to the file.

5. Close all objects.

Reading References to Dataset Regions

The following steps are involved in reading references to dataset regions and referenced dataset regions (selections).

1. Open and read the dataset containing references to the dataset regions. The datatype H5T_STD_REF_DSETREG must be used during the read operation.

2. Use H5Rdereference / h5rdeference_f to obtain the dataset identifier from the read dataset region reference. OR Use H5Rget_region / h5rget_region_f to obtain the dataspace identifier for the dataset containing the selection from the read dataset region reference.

3. Obtain information about the selection or read selected data from the dataset.

4. Close all objects when they are no longer needed.

Programming Example

Description

The examples below create a dataset in a file, and write references to regions in the dataset to a dataset of region references. (The regions in the dataset are selected using H5Sselect_hyperslab / h5sselect_hyperslab_f and H5Sselect_elements / h5sselect_elements_f.)

Then it reopens the file, dereferences the references and outputs the referenced regions to the screen.

Examples:

[ C example ] - h5ex_t_regref.c  
[ FORTRAN example ] - refregexample.f90

Remarks

• A dataset region reference dataset can be created by calling H5Dcreate / h5dcreate_f with a a datatype of H5T_STD_REF_DSETREG.

• The dataspace selections are stored as references in the dataset of region references, using the H5Rcreate / h5rcreate_f call, and passing in hdset_ref_ref_t for the reference type.

• The dataset with the region references is read by calling H5Dread / h5dread_f with a datatype of H5T_STD_REF_DSETREG.

• The H5Rdereference / h5rdereference_f opens the dataset, using its reference, and returns the dataset identifier. H5R_DATASET_REGION is passed in as the reference type.

• The H5Rget_region / h5rget_region_f call obtains the spacial information ( dataspace and selection ) for the region reference.

---

- - Last modified: 21 December 2016