367 lines
11 KiB
HTML
367 lines
11 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - References to Dataset Regions
|
|
</TITLE>
|
|
</HEAD>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<!-- BEGIN MAIN BODY -->
|
|
|
|
|
|
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
|
|
<H1><BIG><BIG><BIG><FONT COLOR="#c101cd"> References to Dataset Regions</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI> <A HREF="#def">References to Dataset Regions</A>
|
|
<LI> <A HREF="#def1">Creating and Storing References to Dataset Regions</A>
|
|
<LI> <A HREF="#def2">Reading References to Dataset Regions</A>
|
|
<LI> Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description</A>
|
|
<LI> <A HREF="#rem">Remarks</A>
|
|
<LI> <A HREF="#fc">File Contents</A>
|
|
</UL>
|
|
</UL>
|
|
<HR>
|
|
<A NAME="def">
|
|
<H2>References to Dataset Regions</H2>
|
|
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.
|
|
<P>
|
|
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.
|
|
<A NAME="def1">
|
|
<H2>Creating and Storing References to Dataset Regions</H2>
|
|
The following steps are involved in creating and storing references to
|
|
dataset regions:
|
|
<OL>
|
|
|
|
<LI> Create a dataset in which to store the dataset regions (the selections).
|
|
<P>
|
|
<LI> Create selections in the dataset(s).
|
|
The dataset(s) should already exist in the file.
|
|
<P>
|
|
<LI> Create references to the selections and store them in a buffer.
|
|
<P>
|
|
<LI> Write the dataset region references to the file.
|
|
<P>
|
|
<LI> Close all objects.
|
|
</OL>
|
|
|
|
<A NAME="def2">
|
|
<H2>Reading References to Dataset Regions</H2>
|
|
|
|
The following steps are involved in reading references to dataset
|
|
regions and referenced dataset regions (selections).
|
|
<OL>
|
|
<LI> Open and read the dataset containing references to the dataset regions.
|
|
The datatype <CODE>H5T_STD_REF_DSETREG</CODE> must be used during
|
|
the read operation.
|
|
<P>
|
|
<LI>Use <CODE>H5Rdereference</CODE> / <CODE>h5rdeference_f</CODE> to
|
|
obtain the dataset identifier from the read
|
|
dataset region reference.
|
|
<dir><dir><dir>
|
|
<B><font size=-1>OR</font></B>
|
|
</dir></dir></dir>
|
|
Use <CODE>H5Rget_region</CODE> / <CODE>h5rget_region_f</CODE> to obtain
|
|
the dataspace identifier for the dataset
|
|
containing the selection from the read dataset region reference.
|
|
<P>
|
|
<LI> Obtain information about the selection or read selected data from
|
|
the dataset.
|
|
<P>
|
|
<LI> Close all objects when they are no longer needed.
|
|
</OL>
|
|
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
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.
|
|
<P>
|
|
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.<BR>
|
|
<P>
|
|
To obtain the example, download:
|
|
<UL>
|
|
[<A HREF="examples/h5_ref2reg.c">C example</A> ]
|
|
- <code>h5_ref2reg.c</code><BR>
|
|
[<A HREF="examples/refregexample.f90">FORTRAN example</A> ]
|
|
- <code>refregexample.f90</code>
|
|
</UL>
|
|
<B>NOTE:</B> To download a tar file of the examples, including a Makefile,
|
|
please go to the <A HREF="references.html">References</A> page.
|
|
<P>
|
|
|
|
Following is the output from the examples:
|
|
<P>
|
|
<I><U>Output of C Example</U></I>
|
|
<PRE>
|
|
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
|
|
</PRE>
|
|
<I><U>Output of FORTRAN Example</U></I>
|
|
<PRE>
|
|
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
|
|
</PRE>
|
|
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI> The following code creates a dataset to store references to the
|
|
dataset(s) regions (selections). Notice that the
|
|
<CODE>H5T_STD_REF_DSETREG</CODE> datatype is used.
|
|
<P>
|
|
<I><B>C:</I></B>
|
|
<pre>
|
|
dset1 = H5Dcreate (file_id, dsetnamer, H5T_STD_REF_DSETREG,
|
|
spacer_id, creation_prp);
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN:</B></I>
|
|
<pre>
|
|
CALL h5dcreate_f (file_id, dsetnamer, H5T_STD_REF_DSETREG, &
|
|
spacer_id, dset1, hdferr, creation_prp)
|
|
</pre>
|
|
<P>
|
|
|
|
<LI> This program uses hyperslab and point selections. We used the dataspace
|
|
identifier for the calls to <CODE>H5Sselect_hyperslab</CODE> /
|
|
<CODE>h5sselect_hyperslab_f</CODE> and
|
|
<CODE>H5Sselect_elements</CODE> / <CODE>h5sselect_elements_f</CODE>.
|
|
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 <CODE>H5Dget_space</CODE> /
|
|
<CODE>h5dget_space_f</CODE> function.
|
|
<P>
|
|
<LI> <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> is used to create a
|
|
dataset region reference. The signature of the function is as follows:
|
|
<P>
|
|
<I><B>C</B></I>:
|
|
<pre>
|
|
herr_t H5Rcreate (void *ref, hid_t loc_id, const char *name,
|
|
H5R_type_t ref_type, hid_t space_id)
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN</B></I>:
|
|
<pre>
|
|
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
|
|
</pre>
|
|
<P>
|
|
<UL>
|
|
<LI> The <em>ref</em> argument specifies the buffer in which
|
|
to store the reference.
|
|
<P>
|
|
<LI> The <I>loc_id</I> and <I>name</I> arguments specify the
|
|
referenced dataset.
|
|
<P>
|
|
<LI> In C, the <I>ref_type</I> argument specifies the reference type.
|
|
Since we are creating references to the dataset regions,
|
|
the <CODE>H5R_DATASET_REGION</CODE> datatype is used.
|
|
<P>
|
|
<LI> The <I>space_id</I> argument is a dataspace identifier.
|
|
This dataspace includes a selection in the referenced dataset.
|
|
<P>
|
|
<LI> In C, the function <CODE>H5Rcreate</CODE> returns a non-negative
|
|
value if successful and a negative value otherwise. In FORTRAN, the
|
|
return code from the <CODE>h5rcreate_f</CODE> subroutine is
|
|
returned in <I>hdferr</I>: 0 if succesful and -1 otherwise.
|
|
</UL>
|
|
<P>
|
|
<LI> The dataset with the region references was read by
|
|
<CODE>H5Dread</CODE> / <CODE>h5dread_f</CODE> with
|
|
the <CODE>H5T_STD_REF_DSETREG</CODE> datatype specified.
|
|
<P>
|
|
<LI> The read reference can be used to obtain the dataset identifier, as we
|
|
did with the following call:
|
|
<P>
|
|
<I><B>C:</B></I>
|
|
<pre>
|
|
dset2 = H5Rdereference (dset1, H5R_DATASET_REGION, &ref_out[0]);
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN:</B></I>
|
|
<pre>
|
|
CALL h5rdereference_f (dset1, ref_out(1), dset2, hdferr)
|
|
</pre>
|
|
<P>
|
|
or to obtain spacial information ( dataspace and selection ) with the call
|
|
to <CODE>H5Rget_region</CODE> / <CODE>h5rget_region_f</CODE>:
|
|
<P>
|
|
<I><B>C:</B></I>
|
|
<pre>
|
|
dspace2 = H5Rget_region (dset1, H5R_DATASET_REGION, &ref_out[0]);
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN:</B></I>
|
|
<pre>
|
|
CALL H5rget_region_f (dset1, ref_out(1), dspace2, hdferr)
|
|
</pre>
|
|
<P>
|
|
The reference to the dataset region has information for both the dataset
|
|
itself and its selection. In both calls,
|
|
<UL>
|
|
<LI> the <em>dset1</em> parameter is the identifier for the dataset
|
|
with the region references and
|
|
<P>
|
|
<LI> the <em>ref_out</em> parameter specifies the type of reference
|
|
stored. In this example a reference to the dataset region is stored.
|
|
</UL>
|
|
<P>
|
|
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 <I>dset2</I> or <I>dspace2</I>
|
|
and the return code for the call is returned in <I>hdferr</I>:
|
|
0 if successful and -1 otherwise.
|
|
<P>
|
|
</UL>
|
|
|
|
|
|
</UL>
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
<P>
|
|
<I><U>HDF5 File Created by C Example</U></I>
|
|
<P>
|
|
<B>Fig. A</B> <I><code>REF_REG.h5</code> in DDL</I>
|
|
<PRE>
|
|
|
|
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)}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
</PRE>
|
|
<I><U>HDF5 File Created by FORTRAN Example</U></I>:
|
|
<P>
|
|
<B>Fig. B</B> <I><code>FORTRAN.h5</code> in DDL</I>
|
|
<PRE>
|
|
|
|
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)}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
|
|
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.
|
|
<!--
|
|
Since only two selections were stored, the third and fourth elements of the
|
|
dataset are set to NULL. This was done by the buffer
|
|
inizialization in the program.
|
|
-->
|
|
|
|
|
|
<!-- BEGIN FOOTER INFO -->
|
|
|
|
<P><hr noshade size=1>
|
|
<font face="arial,helvetica" size="-1">
|
|
<a href="http://www.ncsa.uiuc.edu/"><img border=0
|
|
src="footer-ncsalogo.gif"
|
|
width=78 height=27 alt="NCSA"><br>
|
|
The National Center for Supercomputing Applications</A><br>
|
|
<a href="http://www.uiuc.edu/">University of Illinois
|
|
at Urbana-Champaign</a><br>
|
|
<br>
|
|
<!-- <A HREF="helpdesk.mail.html"> -->
|
|
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
|
|
hdfhelp@ncsa.uiuc.edu</A>
|
|
<br>
|
|
<BR> <H6>Last Modified: June 22, 2001</H6><BR>
|
|
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
|
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
|
|
</FONT>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|