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:
266 lines
7.2 KiB
HTML
266 lines
7.2 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Selecting Individual Points and Copying a Dataspace
|
|
</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">Selecting Individual Points and Copying
|
|
a Dataspace</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI> <A HREF="#def">Description</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>Description</h2>
|
|
You can select independent points to read from or write to in a
|
|
dataspace by use of the <CODE>H5Sselect_elements</CODE> /
|
|
<CODE>h5sselect_elements_f</CODE> function.
|
|
<P>
|
|
The <CODE>H5Scopy</CODE> / <CODE>h5scopy_f</CODE> function allows
|
|
you to make an exact copy of a dataspace.
|
|
This can reduce the number of function calls needed when
|
|
selecting a dataspace.
|
|
<P>
|
|
<H2> Programming Example</H2>
|
|
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
This example shows how to use <CODE>H5Sselect_elements</CODE> /
|
|
<CODE>h5sselect_elements_f</CODE>
|
|
to select individual points in a dataset and how to use
|
|
<CODE>H5Scopy</CODE> / <CODE>h5scopy_f</CODE>
|
|
to make a copy of a dataspace.
|
|
<UL>
|
|
[ <A HREF="examples/h5_copy.c">C example</A> ]
|
|
- <code>h5_copy.c</code><BR>
|
|
[ <A HREF="examples/selectele.f90">FORTRAN example</A> ]
|
|
- <code>selectele.f90</code><BR>
|
|
[ <A HREF="examples/java/Copy.java">Java example</A> ]
|
|
- <code>Copy.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.
|
|
|
|
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI><CODE>H5Sselect_elements</CODE> / <CODE>h5sselect_elements_f</CODE>
|
|
selects array elements to be
|
|
included in the selection for a dataspace:
|
|
<P>
|
|
<I><B>C</B></I>:
|
|
<pre>
|
|
herr_t H5Sselect_elements (hid_t space_id, H5S_seloper_t operator,
|
|
size_t num_elements,
|
|
const hsize_t **coord )
|
|
</pre>
|
|
<P>
|
|
<I><B>FORTRAN</B></I>:
|
|
<pre>
|
|
h5sselect_elements_f (space_id, operator, num_elements, coord, hdferr)
|
|
|
|
space_id IN: INTEGER(HID_T)
|
|
operator IN: INTEGER
|
|
num_elements IN: INTEGER
|
|
coord IN: INTEGER(HSIZE_T), DIMENSION(*,*)
|
|
hdferr OUT: INTEGER
|
|
</pre>
|
|
<P>
|
|
<UL>
|
|
<LI>The <I>space_id</I> parameter is the dataspace identifier.
|
|
<P>
|
|
<LI>The <I>operator</I> parameter can be set to one of the following values:
|
|
<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>coord</I> array is a two-dimensional array of size
|
|
<code><em>NUMP</em> x <em>RANK</em></code> in C
|
|
(<code><em>RANK</em> x <em>NUMP</em></code> in FORTRAN)
|
|
where <code><em>NUMP</em></code> is the number of selected points
|
|
and <code><em>RANK</em></code> is the rank of the dataset.
|
|
Note that these coordinates are 0-based in C and 1-based in FORTRAN.
|
|
<p>
|
|
Consider the non-zero elements of the following array:
|
|
<pre>
|
|
0 59 0 53
|
|
0 0 0 0
|
|
0 0 1 0 </pre>
|
|
In C, the <em>coord</em> array selecting these points would be as follows:
|
|
<pre>
|
|
0 1
|
|
0 3
|
|
2 2 </pre>
|
|
While in FORTRAN, the <em>coord</em> array would be as follows:
|
|
<pre>
|
|
1 1 3
|
|
2 4 3 </pre>
|
|
<P>
|
|
<LI>In C, this function returns a non-negative value if successful and
|
|
a negative value otherwise. In FORTRAN, the value returned in <I>hdferr</I>
|
|
indicates whether it was successful (0) or not (-1).
|
|
</UL>
|
|
<P>
|
|
<LI><CODE>H5Scopy</CODE> / <CODE>h5scopy_f</CODE> creates an exact copy of a dataspace:
|
|
<P>
|
|
<I><B>C</B></I>:
|
|
|
|
<PRE>
|
|
hid_t H5Scopy (hid_t space_id)
|
|
</PRE>
|
|
<I><B>FORTRAN</B></I>:
|
|
<PRE>
|
|
h5scopy_f (space_id, new_space_id, hdferr)
|
|
|
|
space_id IN: INTEGER(HID_T)
|
|
new_space_id OUT: INTEGER(HID_T)
|
|
hdferr OUT: INTEGER
|
|
</PRE>
|
|
<P>
|
|
<UL>
|
|
<LI>The <I>space_id</I> parameter is the dataspace identifier to copy.
|
|
<P>
|
|
<LI>In C, the identifier to the dataspace's copy is returned if the
|
|
function is successful and a negative value is returned if not. In
|
|
FORTRAN, the new dataspace identifier is returned in <I>new_space_id</I>
|
|
and the return value is returned in <I>hdferr</I> ( 0 if successful and
|
|
-1 if not).
|
|
</UL>
|
|
</UL>
|
|
</UL>
|
|
<P>
|
|
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
|
|
Following is the DDL for <I>copy1.h5</I> and <I>copy2.h5</I>, as viewed with
|
|
the following commands:<br>
|
|
|
|
<code>h5dump copy1.h5</code> <br>
|
|
|
|
<code>h5dump copy2.h5</code>
|
|
|
|
<P>
|
|
<HR>
|
|
<B><I><U>C</U></B></I>:<P>
|
|
<B>Fig. S.1a</B> <I><code>copy1.h5</code> in DDL</I>
|
|
<PRE>
|
|
HDF5 "copy1.h5" {
|
|
GROUP "/" {
|
|
DATASET "Copy1" {
|
|
DATATYPE { H5T_STD_I32BE }
|
|
DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
|
|
DATA {
|
|
0, 59, 0, 53,
|
|
0, 0, 0, 0,
|
|
0, 0, 0, 0
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
<B>Fig. S.1b</B> <I><code>copy2.h5</code> in DDL</I>
|
|
<PRE>
|
|
HDF5 "copy2.h5" {
|
|
GROUP "/" {
|
|
DATASET "Copy2" {
|
|
DATATYPE { H5T_STD_I32BE }
|
|
DATASPACE { SIMPLE ( 3, 4 ) / ( 3, 4 ) }
|
|
DATA {
|
|
1, 59, 1, 53,
|
|
1, 1, 1, 1,
|
|
1, 1, 1, 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
<HR>
|
|
<I><B><U>FORTRAN</U></B></I>:<P>
|
|
<B>Fig. S.2a</B> <I><code>copy1.h5</code> in DDL</I>
|
|
<PRE>
|
|
HDF5 "copy1.h5" {
|
|
GROUP "/" {
|
|
DATASET "Copy1" {
|
|
DATATYPE { H5T_STD_I32BE }
|
|
DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) }
|
|
DATA {
|
|
0, 0, 0,
|
|
53, 0, 0,
|
|
0, 0, 0,
|
|
59, 0, 0
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
<B>Fig. S.2b</B> <I><code>copy2.h5</code> in DDL</I>
|
|
<PRE>
|
|
HDF5 "copy2.h5" {
|
|
GROUP "/" {
|
|
DATASET "Copy2" {
|
|
DATATYPE { H5T_STD_I32BE }
|
|
DATASPACE { SIMPLE ( 4, 3 ) / ( 4, 3 ) }
|
|
DATA {
|
|
1, 1, 1,
|
|
53, 1, 1,
|
|
1, 1, 1,
|
|
59, 1, 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
|
|
|
|
<!-- 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>
|
|
|
|
|
|
|