<HTML><HEAD>
<TITLE>HDF5 Tutorial - Hyperslab Selections
</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">Hyperslab Selections</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<H2>Contents:</H2>
<UL>
<LI><A HREF="#def">Selecting a Portion of a Dataspace</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>Selecting a Portion of a Dataspace</H2>
Hyperslabs are portions of datasets. A hyperslab selection can be a
logically contiguous collection of points in a dataspace, or it
can be a regular pattern of points or blocks in a dataspace.
You can select a hyperslab to write to or read from with the function
<CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE>.
<P>
<H2> Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
This example creates a 5 x 6 integer array in a file called <code>sds.h5</code>
(<code>sdsf.h5</code> in FORTRAN). It
selects a 3 x 4 hyperslab from the dataset as follows (Dimension 0 is
offset by 1 and Dimension 1 is offset by 2):
<P>
<B>5 x 6 array:</B>
<TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=172>
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="17%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
</TR>
<TR><TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
<TD WIDTH="17%" VALIGN="TOP"> </TD>
</TR>
</TABLE>
<P>
Then it reads the hyperslab from this file into a 2-dimensional plane
(size 7 x 7) of a 3-dimensional array (size 7 x 7 x 3), as
follows (with Dimension 0 offset by 3):
<P>
<TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=201>
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP">
<FONT SIZE=2><P> X</FONT></TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
<TR><TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
<TD WIDTH="14%" VALIGN="TOP"> </TD>
</TR>
</TABLE>
<P>
To obtain the example, download:
<UL>
[ <A HREF="examples/h5_hyperslab.c">C example</A> ]
- <code>h5_hyperslab.c</code><BR>
[ <A HREF="examples/hyperslab.f90">FORTRAN example</A> ]
- <code>hyperslab.f90</code><BR>
[ <A HREF="examples/java/HyperSlab.java">Java example</A> ]
- <code>HyperSlab.java</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>
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI><CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE>
selects a hyperslab region to
add to the current selected region for a specified dataspace.
<P>
<I><B>C</B></I>:
<pre>
herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t operator,
const hsize_t *start, const hsize_t *stride,
const hsize_t *count, const hsize_t *block )
</pre>
<P>
<I><B>FORTRAN</B></I>:
<pre>
h5sselect_hyperslab_f (space_id, operator, start, count, &
hdferr, stride, block)
space_id IN: INTEGER(HID_T)
operator IN: INTEGER
start IN: INTEGER(HSIZE_T), DIMENSION(*)
count IN: INTEGER(HSIZE_T), DIMENSION(*)
hdferr OUT: INTEGER
stride IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL
block IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL
</pre>
<P>
<UL>
<LI>The parameter <I>space_id</I> is the dataspace identifier for the
specified dataspace.
<P>
<LI>The parameter <I>operator</I> can be set to one of the following:
<dir><DL>
<dt><CODE>H5S_SELECT_SET</CODE> (<CODE>H5S_SELECT_SET_F</CODE> in FORTRAN)
<dd>Replace the existing selection with the parameters from this call.
Overlapping blocks are not supported with this operator.
<dt><CODE>H5S_SELECT_OR</CODE> (<CODE>H5S_SELECT_OR_F</CODE> in FORTRAN)
<dd>Add the new selection to the existing selection.
</DL></dir>
<P>
<LI>The <I>start</I> array determines the starting coordinates of the
hyperslab to select.
<P>
<LI>The <I>stride</I> array indicates which elements along a dimension are to
be selected.
<P>
<LI>The <I>count</I> array determines how many positions to select from the
dataspace in each dimension.
<P>
<LI>The <I>block</I> array determines the size of the element block selected
by the dataspace.
<P>
<LI>In C, a non-negative value is returned if successful, and a negative
value otherwise. In FORTRAN, the return value is returned in <I>hdferr</I>:
0 if successful and -1 otherwise.
</UL>
<P>
The <I>start</I>, <I>stride</I>, <I>count</I>, and <I>block</I> arrays must
be the same size as the rank of the dataspace.
<P>
<LI>The examples introduce the following call:
<dir><dl>
<dt><code>H5Dget_space / h5dget_space_f:</code>
<dd>Returns an identifier for a copy of the dataspace of a dataset.<P>
</dl></dir>
<LI>The C example also introduces the following calls:
<dir><dl>
<dt><code>H5Sget_simple_extent_dims:</code>
<dd>Returns the size and maximum size of each dimension of a dataspace.
<dt><code>H5Sget_simple_extent_ndims:</code>
<dd>Determines the dimensionality (or rank) of a dataspace.
</dl></dir>
<P>
The FORTRAN example does not use these calls, though they
are available as <CODE>h5sget_simple_extent_dims_f</CODE> and
<CODE>h5sget_simple_extent_ndims_f</CODE>.
</UL>
</UL>
</UL>
</PRE>
<P>
<!--
<A NAME="fc">
<H3><U>File Contents</U></H3>
-->
<!-- 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>