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:

Create a dataset in which to store the dataset regions (the selections).
Create selections in the dataset(s). The dataset(s) should already exist in the file.
Create references to the selections and store them in a buffer.
Write the dataset region references to the file.
Close all objects.

Reading References to Dataset Regions

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

Open and read the dataset containing references to the dataset regions. The datatype H5T_STD_REF_DSETREG must be used during the read operation.
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.
Obtain information about the selection or read selected data from the dataset.
Close all objects when they are no longer needed.

Programming Example

Description

The example below first creates a dataset in the file. Then it creates a dataset to store references to the dataset regions (selections). The first selection is a 6 x 6 hyperslab. The second selection is a point selection in the same dataset. References to both selections are created and stored in the buffer and then written to the dataset in the file.

After creating the dataset and references, the program reads the dataset containing the dataset region references. It reads data from the dereferenced dataset and displays the number of elements and raw data. Then it reads two selections, a hyperslab selection and a point selection. The program queries a number of points in the hyperslab and their coordinates and displays them. Then it queries a number of selected points and their coordinates and displays the information.

To obtain the example, download:

[

C example

h5_ref2reg.c

FORTRAN example

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

Output of C Example

Selected hyperslab: 
0 0 0 3 3 4 0 0 0 
0 0 0 3 4 4 0 0 0 
Selected points: 
1 0 0 0 0 0 0 0 6 
0 0 0 0 0 0 5 0 0

Output of FORTRAN Example

 Hyperslab selection

 3*0,  2*3,  4,  3*0
 3*0,  3,  2*4,  3*0

 Point selection

 1,  7*0,  6
 6*0,  5,  2*0

Remarks

The following code creates a dataset to store references to the dataset(s) regions (selections). Notice that the H5T_STD_REF_DSETREG datatype is used.

    dset1 = H5Dcreate (file_id, dsetnamer, H5T_STD_REF_DSETREG,
                       spacer_id, creation_prp);

FORTRAN:

    CALL h5dcreate_f (file_id, dsetnamer, H5T_STD_REF_DSETREG, &
                     spacer_id, dset1, hdferr, creation_prp)

This program uses hyperslab and point selections. We used the dataspace identifier for the calls to H5Sselect_hyperslab / h5sselect_hyperslab_f and H5Sselect_elements / h5sselect_elements_f. The identifier was obtained when the dataset was created and it describes the dataset's dataspace. We did not close it when the dataset was closed to decrease the number of function calls used in the example. In a real application program, one should open the dataset and determine its dataspace using the H5Dget_space / h5dget_space_f function.
H5Rcreate / h5rcreate_f is used to create a dataset region reference. The signature of the function 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, space_id, ref, hdferr)

        loc_id      IN: INTEGER (HID_T)
        name        IN: CHARACTER (LEN=*) 
        space_id    IN:  INTEGER (HID_T)
        ref_type   OUT: TYPE(hdset_reg_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 referenced dataset.
- In C, the ref_type argument specifies the reference type. Since we are creating references to the dataset regions, the H5R_DATASET_REGION datatype is used.
- The space_id argument is a dataspace identifier. This dataspace includes a selection in the referenced dataset.
- In C, the function H5Rcreate returns a non-negative value if successful and a negative value otherwise. In FORTRAN, the return code from the h5rcreate_f subroutine is returned in hdferr: 0 if succesful and -1 otherwise.
The dataset with the region references was read by H5Dread / h5dread_f with the H5T_STD_REF_DSETREG datatype specified.
The read reference can be used to obtain the dataset identifier, as we did with the following call:
C:
```
    dset2 = H5Rdereference (dset1, H5R_DATASET_REGION, &ref_out[0]);
```
FORTRAN:
```
    CALL h5rdereference_f (dset1, ref_out(1), dset2, hdferr)
```
or to obtain spacial information ( dataspace and selection ) with the call to H5Rget_region / h5rget_region_f:
C:
```
    dspace2 = H5Rget_region (dset1, H5R_DATASET_REGION, &ref_out[0]);
```
FORTRAN:
```
    CALL H5rget_region_f (dset1, ref_out(1), dspace2, hdferr)
```
The reference to the dataset region has information for both the dataset itself and its selection. In both calls,
- the dset1 parameter is the identifier for the dataset with the region references and
- the ref_out parameter specifies the type of reference stored. In this example a reference to the dataset region is stored.
The C function returns the dataspace identifier or a negative value if it is not successful. In FORTRAN, the dataset identifier or dataspace identifier is returned in dset2 or dspace2 and the return code for the call is returned in hdferr: 0 if successful and -1 otherwise.

File Contents

HDF5 File Created by C Example

Fig. A REF_REG.h5 in DDL


HDF5 "REF_REG.h5" {
GROUP "/" {
   DATASET "MATRIX" {
      DATATYPE { H5T_STD_I32BE }
      DATASPACE { SIMPLE ( 2, 9 ) / ( 2, 9 ) }
      DATA {
         1, 1, 2, 3, 3, 4, 5, 5, 6,
         1, 2, 2, 3, 4, 4, 5, 6, 6
      }
   }
   DATASET "REGION_REFERENCES" {
      DATATYPE { H5T_REFERENCE }
      DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
      DATA {
         DATASET 0:744 {(0,3)-(1,5)}, DATASET 0:744 {(0,0), (1,6), (0,8)}
      }
   }
}
}

HDF5 File Created by FORTRAN Example:

Fig. B FORTRAN.h5 in DDL


HDF5 "FORTRAN.h5" {
GROUP "/" {
   DATASET "MATRIX" {
      DATATYPE { H5T_STD_I32BE }
      DATASPACE { SIMPLE ( 9, 2 ) / ( 9, 2 ) }
      DATA {
         1, 1,
         1, 2,
         2, 2,
         3, 3,
         3, 4,
         4, 4,
         5, 5,
         5, 6,
         6, 6
      }
   }
   DATASET "REGION_REFERENCES" {
      DATATYPE { H5T_REFERENCE }
      DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
      DATA {
         DATASET 0:744 {(3,0)-(5,1)}, DATASET 0:744 {(0,0), (6,1), (8,0)}
      }
   }
}
}

Notice how the raw data in the dataset with the dataset regions is displayed. Each element of the raw data consists of a reference to the dataset (DATASET number1:number2) and its selected region. If the selection is a hyperslab, the corner coordinates of the hyperslab are displayed. For the point selection, the coordinates of each point are displayed.

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

hdfhelp@ncsa.uiuc.edu

References to Dataset Regions

Contents: