427ff7da28
Bug Fix/Code Cleanup/Doc Cleanup/Optimization/Branch Sync :-)
Description:
Generally speaking, this is the "signed->unsigned" change to selections.
However, in the process of merging code back, things got stickier and stickier
until I ended up doing a big "sync the two branches up" operation. So... I
brought back all the "infrastructure" fixes from the development branch to the
release branch (which I think were actually making some improvement in
performance) as well as fixed several bugs which had been fixed in one branch,
but not the other.
I've also tagged the repository before making this checkin with the label
"before_signed_unsigned_changes".
Platforms tested:
FreeBSD 4.10 (sleipnir) w/parallel & fphdf5
FreeBSD 4.10 (sleipnir) w/threadsafe
FreeBSD 4.10 (sleipnir) w/backward compatibility
Solaris 2.7 (arabica) w/"purify options"
Solaris 2.8 (sol) w/FORTRAN & C++
AIX 5.x (copper) w/parallel & FORTRAN
IRIX64 6.5 (modi4) w/FORTRAN
Linux 2.4 (heping) w/FORTRAN & C++
Misc. update:
310 lines
9.5 KiB
HTML
310 lines
9.5 KiB
HTML
<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>
|
|
|
|
|
|
|