An object reference points to an entire object in the current HDF5 file by storing the relative file address (OID) of the object header for the object pointed to. The relative file address of an object header is constant for the life of the object. An object reference is of a fixed size in the file.
A dataset region reference points to a region of a dataset in the current HDF5 file by storing the OID of the dataset and the global heap offset of the region referenced. The region referenced is located by retrieving the coordinates of the areas in the region from the global heap. A dataset region reference is of a variable size in the file.
An internal dataset region reference points to a region of the current dataset by storing the coordinates of the region. An internal dataset region reference is of a fixed size in the file.
| Reference Type | Value | Description |
|---|---|---|
H5R_BADTYPE |
-1 |
Invalid reference type |
H5R_OBJECT |
0 |
Object reference |
H5R_DATASET_REGION |
1 |
Dataset region reference |
H5R_INTERNAL |
2 |
Internal reference |
H5Rcreate(href_t *reference,
hid_t loc_id,
const char *name,
H5R_type_t type,
hid_t space_id)
H5Rcreate creates an object which is a
particular type of reference (specified with the
type parameter) to some file object and/or
location specified with the space_id parameter.
For dataset region references, the selection specified
in the dataspace is the portion of the dataset which
will be referred to.
Currently only object references which point to entire datasets can be created.
H5Rdereference(hid_t dset,
H5R_type_t rtype,
href_t *ref)
H5Rdereference opens the object referenced
and returns an identifier for that object.
The parameter ref specifies a reference of
type rtype that is stored in the dataset
dset.
H5Rget_region(hid_t dataset,
H5R_type_t type,
href_t *reference)
H5Rget_region creates a copy of dataspace of
the dataset that is pointed to and defines a selection in
the copy which is the location (or region) pointed to.
The parameter ref specifies a reference of
type rtype that is stored in the dataset
dset.
This function is not yet implemented.
H5Iget_type(hid_t id)
id. Valid return values appear
in the following list:
H5I_BADID |
Invalid ID |
H5I_FILE |
File objects |
H5I_GROUP |
Group objects |
H5I_DATATYPE |
Data type objects |
H5I_DATASPACE |
Dataspace objects |
H5I_DATASET |
Dataset objects |
H5I_ATTR |
Attribute objects |
This function was inspired by the need of users to figure
out which type of object closing function
(H5Dclose, H5Gclose, etc.)
to call after a call to H5Ddereference,
but it is also of general use.
{
hid_t file1;
hid_t dataset1;
hid_t datatype, dataspace;
char buf[128];
href_t link;
href_t data[10][10];
int rank;
size_t dimsf[2];
int i, j;
/* Open the file */
file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
/* Describe the size of the array and create the data space */
rank=2;
dimsf[0] = 10;
dimsf[1] = 10;
dataspace = H5Screate_simple(rank, dimsf, NULL);
/* Define datatype */
datatype = H5Tcopy(H5T_STD_REF_OBJ);
/* Create a dataset */
dataset1=H5Dcreate(file1,"Dataset One",datatype,dataspace,H5P_DEFAULT);
/* Construct array of OIDs for other datasets in the file */
/* somewhat hokey and artificial, but demonstrates the point */
for(i=0; i<10; i++)
for(j=0; j<10; i++)
{
sprintf(buf,"/Group/Linked Set %d-%d",i,j);
if(H5Rcreate(&link,file1,buf,H5R_REF_OBJ,-1)>0)
data[i][j]=link;
} /* end for */
/* Write the data to the dataset using default transfer properties. */
H5Dwrite(dataset, H5T_POINTER_OBJECT, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
/* Close everything */
H5Sclose(dataspace);
H5Tclose(datatype);
H5Dclose(dataset1);
H5Fclose(file1);
}
Object Reference Reading Example
{
hid_t file1;
hid_t dataset1, tmp_dset;
href_t data[10][10];
int i, j;
/* Open the file */
file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
/* Open the dataset */
dataset1=H5Dopen(file1,"Dataset One",H5P_DEFAULT);
/*
* Read the data to the dataset using default transfer properties.
* (we are assuming the dataset is the same and not querying the
* dimensions, etc.)
*/
H5Dread(dataset, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
/* Analyze array of OIDs of linked datasets in the file */
/* somewhat hokey and artificial, but demonstrates the point */
for(i=0; i<10; i++)
for(j=0; j<10; i++)
{
if((tmp_dset=H5Rdereference(dataset, H5T_STD_REF_OBJ, data[i][j]))>0)
{
} /* end if */
H5Dclose(tmp_dset);
} /* end for */
/* Close everything */
H5Dclose(dataset1);
H5Fclose(file1);
}
Dataset Region Reference Writing Example
{
hid_t file1;
hid_t dataset1, dataset2;
hid_t datatype, dataspace1, dataspace2;
char buf[128];
href_t link;
href_t data[10][10]; /* HDF5 reference type */
int rank;
size_t dimsf[2];
hssize_t start[3],count[3];
int i, j;
/* Open the file */
file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
/* Describe the size of the array and create the data space */
rank=2;
dimsf[0] = 10;
dimsf[1] = 10;
dataspace1 = H5Screate_simple(rank, dimsf, NULL);
/* Define Dataset Region Reference datatype */
datatype = H5Tcopy(H5T_STD_REF_DATAREG);
/* Create a dataset */
dataset1=H5Dcreate(file1,"Dataset One",datatype,dataspace1,H5P_DEFAULT);
/* Construct array of OIDs for other datasets in the file */
/* (somewhat artificial, but demonstrates the point) */
for(i=0; i<10; i++)
for(j=0; j<10; i++)
{
sprintf(buf,"/Group/Linked Set %d-%d",i,j);
/* Get the dataspace for the object to point to */
dataset2=H5Dopen(file1,buf,H5P_DEFAULT);
dataspace2=H5Dget_space(dataspace2);
/* Select the region to point to */
/* (could be different region for each pointer) */
start[0]=5; start[1]=4; start[2]=3;
count[0]=2; count[1]=4; count[2]=1;
H5Sselect_hyperslab(dataspace2,H5S_SELECT_SET,start,NULL,count,NULL);
if(H5Rcreate(&link,file1,buf,H5R_REF_DATAREG,dataspace2)>0)
/* Store the reference */
data[i][j]=link;
H5Sclose(dataspace2);
H5Dclose(dataspace2);
} /* end for */
/* Write the data to the dataset using default transfer properties. */
H5Dwrite(dataset, H5T_STD_REF_DATAREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
/* Close everything */
H5Sclose(dataspace);
H5Tclose(datatype);
H5Dclose(dataset1);
H5Fclose(file1);
}
Dataset Region Reference Reading Example
{
hid_t file1;
hid_t dataset1, tmp_dset;
hid_t dataspace;
href_t data[10][10]; /* HDF5 reference type */
int i, j;
/* Open the file */
file1=H5Fopen("example.h5", H5F_ACC_RDWR, H5P_DEFAULT);
/* Open the dataset */
dataset1=H5Dopen(file1,"Dataset One",H5P_DEFAULT);
/*
* Read the data to the dataset using default transfer properties.
* (we are assuming the dataset is the same and not querying the
* dimensions, etc.)
*/
H5Dread(dataset, H5T_STD_REF_DATAREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, data);
/* Analyze array of OIDs of linked datasets in the file */
/* (somewhat artificial, but demonstrates the point) */
for(i=0; i<10; i++)
for(j=0; j<10; i++)
{
if((tmp_dset=H5Rdereference(dataset, H5D_STD_REF_DATAREG,data[i][j]))>0)
{
/* Get the dataspace with the pointed to region selected */
dataspace=H5Rget_space(data[i][j]);
H5Sclose(dataspace);
} /* end if */
H5Dclose(tmp_dset);
} /* end for */
/* Close everything */
H5Dclose(dataset1);
H5Fclose(file1);
}
Reference types are atomic types and may be included as fields in compound
data types.
There are (at least) three levels of reference strength:
Weak - We allow the user to store any type of reference in an array
of references. (u.e., the array of references in the example above
could be a mix of Object, Dataset Region and Internal references)
Medium - We force the user to stick with a particular type of
reference within a dataset, but the datasets pointed to (with
Object and Dataset Region references) may be of any data type
or dataspace.
Strong - We force the user to stick with a particular type of
reference and Object and Dataset Region references must point to
datasets with the same data type.
Extra Strong - We force the user to stick with a particular type of
reference and Object and Dataset Region references must point to
datasets with the same data type _and_ dataspace.
The library is currently implemented with "medium" strength references.
H5R_MAXTYPE |
3 |
Highest type in group (invalid as true type) |
href_t object in memory is a struct containing
a pointer type and union of information required for each
pointer type.
Information in this structure is not designed for users to view.
Non-C APIs may have to mangle this structure in some way, in order
to provide users with access to references in a language-appropriate
way.