philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
42f49894fc51dbcbd8ec47b3464901ed84a26f03
hdf5/doc/html/RM_H5S.html
Frank Baker 42f49894fc [svn-r1875] 
HDF5 Reference Manual
	Backs out FORTRAN API info. (It was checked into wrong tree.)
	Retains minor edits and formatting fixes that were made while
	   inserting FORTRAN.
1999-12-14 09:45:34 -05:00

1007 lines
38 KiB
HTML
Raw Blame History

<html>
<head><title>
HDF5/H5S API Specification
</title></head>
<body bgcolor="#FFFFFF">
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
<a href="H5.user.html">HDF5 User Guide</a>&nbsp;<br>
<a href="index.html">Other HDF5 documents and links</a>&nbsp;<br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;&nbsp;
<br>
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5I.html">H5I</a>&nbsp;&nbsp;
<br>
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<a href="RM_H5R.html">H5R</a>&nbsp;&nbsp;
<a href="RM_H5RA.html">H5RA</a>&nbsp;&nbsp;
H5S&nbsp;&nbsp;
<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<a href="Tools.html">Tools</a>&nbsp;&nbsp;
</td></tr>
</table>
</center>
<hr>
<center>
<h1>H5S: Dataspace Interface</h1>
</center>
<h2>Dataspace Object API Functions</h2>
These functions create and manipulate the dataspace in which to store the
elements of a dataset.
<table border=0>
<tr><td valign=top>
<li><a href="#Dataspace-Create">H5Screate</a>
<li><a href="#Dataspace-Copy">H5Scopy</a>
<li><a href="#Dataspace-Close">H5Sclose</a>
<li><a href="#Dataspace-CreateSimple">H5Screate_simple</a>
<li><a href="#Dataspace-IsSimple">H5Sis_simple</a>
<li><a href="#Dataspace-OffsetSimple">H5Soffset_simple</a>
<li><a href="#Dataspace-ExtentDims">H5Sget_simple_extent_dims</a>
<li><a href="#Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</a>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<li><a href="#Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a>
<li><a href="#Dataspace-ExtentType">H5Sget_simple_extent_type</a>
<!-- NOT YET IMPLEMENTED (R1.2 -- 9908)
<li><a href="#Dataspace-ExtentClass">H5Sextent_class</a>
-->
<li><a href="#Dataspace-ExtentCopy">H5Sextent_copy</a>
<li><a href="#Dataspace-SetExtentSimple">H5Sset_extent_simple</a>
<li><a href="#Dataspace-SetExtentNone">H5Sset_extent_none</a>
<li><a href="#Dataspace-SelectNpoints">H5Sget_select_npoints</a>
<li><a href="#Dataspace-SelectHyperNBlocks">H5Sget_select_hyper_nblocks</a>
<li><a href="#Dataspace-SelectHyperBlockList">H5Sget_select_hyper_blocklist</a>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<li><a href="#Dataspace-SelectElemNPoints">H5Sget_select_elem_npoints</a>
<li><a href="#Dataspace-SelectElemPointList">H5Sget_select_elem_pointlist</a>
<li><a href="#Dataspace-SelectBounds">H5Sget_select_bounds</a>
<li><a href="#Dataspace-SelectElements">H5Sselect_elements</a>
<li><a href="#Dataspace-SelectAll">H5Sselect_all</a>
<li><a href="#Dataspace-SelectNone">H5Sselect_none</a>
<li><a href="#Dataspace-SelectValid">H5Sselect_valid</a>
<li><a href="#Dataspace-SelectHyperslab">H5Sselect_hyperslab</a>
</td></tr>
</table>
<p>
The following H5S functions are included in the HDF5 specification,
but have not yet been implemented. They are described in the
<a href="Dataspaces.html">The Dataspace Interface (H5S)</a> section
of the <cite>HDF5 User's Guide.</cite>.
<table border=0>
<tr><td valign=top>
<ul>
<li>H5Scommit
<li>H5Sis_subspace
<li>H5Slock
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
<li>H5Sopen
<li>H5Sselect_op
<li>H5Sselect_order
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
<li>H5Ssubspace
<li>H5Ssubspace_name
<li>H5Ssubspace_location
</ul>
</td></tr>
</table>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-Create">H5Screate</a>
<dt><strong>Signature:</strong>
<dd><em>hid_t</em> <code>H5Screate</code>(<em>H5S_class_t</em> <code>type</code>)
<dt><strong>Purpose:</strong>
<dd>Creates a new dataspace of a specified type.
<dt><strong>Description:</strong>
<dd><code>H5Screate</code> creates a new dataspace of a particular
<code>type</code>.
The types currently supported are <code>H5S_SCALAR</code> and
<code>H5S_SIMPLE</code>;
others are planned to be added later.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>H5S_class_t</em> <code>type</code>
<dd>The type of dataspace to be created.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a dataspace identifier if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-CreateSimple">H5Screate_simple</a>
<dt><strong>Signature:</strong>
<dd><em>hid_t</em> <code>H5Screate_simple</code>(<em>int</em> <code>rank</code>,
<em>const hsize_t *</em> <code>dims</code>,
<em>const hsize_t *</em> <code>maxdims</code>
)
<dt><strong>Purpose:</strong>
<dd>Creates a new simple data space and opens it for access.
<dt><strong>Description:</strong>
<dd><code>H5Screate_simple</code> creates a new simple data space
and opens it for access. The <code>rank</code> is the number of
dimensions used in the dataspace.
The <code>dims</code> argument is the size
of the simple dataset and the <code>maxdims</code> argument is
the upper limit on the size of the dataset. <code>maxdims</code>
may be the null pointer in which case the upper limit is the
same as <code>dims</code>. If an element of <code>maxdims</code>
is zero then the corresponding dimension is unlimited, otherwise
no element of <code>maxdims</code> should be smaller than the
corresponding element of <code>dims</code>. The dataspace
identifier returned from this function should be released with
<code>H5Sclose</code> or resource leaks will occur.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>int</em> <code>rank</code>
<dd>Number of dimensions of dataspace.
<dt><em>const hsize_t *</em> <code>dims</code>
<dd>An array of the size of each dimension.
<dt><em>const hsize_t *</em> <code>maxdims</code>
<dd>An array of the maximum size of each dimension.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a dataspace identifier if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a>
<dt><strong>Signature:</strong>
<dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code>
)
<dt><strong>Purpose:</strong>
<dd>Creates an exact copy of a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Scopy</code> creates a new dataspace which is an exact
copy of the dataspace identified by <code>space_id</code>.
The dataspace identifier returned from this function should be
released with <code>H5Sclose</code> or resource leaks will occur.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Identifier of dataspace to copy.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a dataspace identifier if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sselect_elements</code>(<em>hid_t </em><code>space_id</code>,
<em>H5S_seloper_t</em> <code>op</code>,
<em>const size_t</em> <code>num_elements</code>,
<em>const hssize_t *</em><code>coord</code>[ ]
)
<dt><strong>Purpose:</strong>
<dd>Selects array elements to be included in the selection for a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sselect_elements</code> selects array elements to be
included in the selection for the <code>space_id</code>
dataspace. The number of elements selected must be set with
the <code>num_elements</code>. The <code>coord</code> array
is a two-dimensional array of size <em>dataspace rank</em>
by <code>num_elements</code> (ie. a list of coordinates in
the array). The order of the element coordinates in the
<code>coord</code> array also specifies the order in which
the array elements are iterated through when I/O is performed.
Duplicate coordinate locations are not checked for.
<P>
The selection operator <code>op</code> determines how the
new selection is to be combined with the previously existing
selection for the dataspace.
The following operators are supported:
<dir>
<table width=80% border=0>
<tr><td valign=top>
<code>H5S_SELECT_SET</code>
</td><td valign=top>
Replaces the existing selection with the parameters from this call.
Overlapping blocks are not supported with this operator.
</td></tr><tr><td valign=top>
<code>H5S_SELECT_OR</code>
</td><td valign=top>
Adds the new selection to the existing selection.
</td></tr>
</table>
</dir>
When operators other than <code>H5S_SELECT_SET</code>
are used to combine a new selection with an existing selection,
the selection ordering is reset to 'C' array ordering.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Identifier of the dataspace.
<dt><em>H5S_seloper_t</em> <code>op</code>
<dd>operator specifying how the new selection is to be
combined with the existing selection for the dataspace.
<dt><em>const size_t</em> <code>num_elements</code>
<dd>Number of elements to be selected.
<dt><em>const hssize_t *</em><code>coord</code>[ ]
<dd>A 2-dimensional array specifying the coordinates of the
elements being selected.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectAll">H5Sselect_all</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sselect_all</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Selects the entire dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sselect_all</code> selects the entire extent
of the dataspace <code>space_id</code>.
<p>
More specifically, <code>H5Sselect_all</code> selects
the special <tt>5S_SELECT_ALL</tt> region for the dataspace
<code>space_id</code>. <tt>H5S_SELECT_ALL</tt> selects the
entire dataspace for any dataspace it is applied to.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: The identifier for the dataspace in which the
selection is being made.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectNone">H5Sselect_none</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sselect_none</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Resets the selection region to include no elements.
<dt><strong>Description:</strong>
<dd><code>H5Sselect_none</code> resets the selection region
for the dataspace <code>space_id</code> to include no elements.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: The identifier for the dataspace in which the
selection is being reset.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectValid">H5Sselect_valid</a>
<dt><strong>Signature:</strong>
<dd><em>htri_t</em> <code>H5Sselect_valid</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Verifies that the selection is within the extent of the dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sselect_valid</code> verifies that the selection
for the dataspace <code>space_id</code> is within the extent
of the dataspace if the current offset for the dataspace is used.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>The identifier for the dataspace in which the
selection is being reset.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a positive value, for <code>TRUE</code>,
if the selection is contained within the extent
or <code>0</code> (zero), for <code>FALSE</code>, if it is not.
Returns a negative value on error conditions
such as the selection or extent not being defined.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a>
<dt><strong>Signature:</strong>
<dd><em>hsize_t</em> <code>H5Sget_simple_extent_npoints</code>(<em>hid_t </em><code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Determines the number of elements in a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sget_simple_extent_npoints</code> determines the number of elements
in a dataspace. For example, a simple 3-dimensional dataspace
with dimensions 2, 3, and 4 would have 24 elements.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>ID of the dataspace object to query
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the number of elements in the dataspace if successful;
otherwise returns 0.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectNpoints">H5Sget_select_npoints</a>
<dt><strong>Signature:</strong>
<dd><em>hssize_t</em> <code>H5Sget_select_npoints</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Determines the number of elements in a dataspace selection.
<dt><strong>Description:</strong>
<dd><code>H5Sget_select_npoints</code> determines the number of elements
in the current selection of a dataspace.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Dataspace identifier.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the number of elements in the selection if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</a>
<dt><strong>Signature:</strong>
<dd><em>int</em> <code>H5Sget_simple_extent_ndims</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Determines the dimensionality of a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sget_simple_extent_ndims</code> determines the dimensionality (or rank)
of a dataspace.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Identifier of the dataspace
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the number of dimensions in the dataspace if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-ExtentDims">H5Sget_simple_extent_dims</a>
<dt><strong>Signature:</strong>
<dd><em>int</em> <code>H5Sget_simple_extent_dims</code>(<em>hid_t</em> <code>space_id</code>,
<em>hsize_t *</em><code>dims</code>,
<em>hsize_t *</em><code>maxdims</code>
)
<dt><strong>Purpose:</strong>
<dd>Retrieves dataspace dimension size and maximum size.
<dt><strong>Description:</strong>
<dd><code>H5Sget_simple_extent_dims</code> returns the size and maximum sizes
of each dimension of a dataspace through the <code>dims</code>
and <code>maxdims</code> parameters.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Identifier of the dataspace object to query
<dt><em>hsize_t *</em><code>dims</code>
<dd>OUT: Pointer to array to store the size of each dimension.
<dt><em>hsize_t *</em><code>maxdims</code>
<dd>OUT: Pointer to array to store the maximum size of each dimension.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the number of dimensions in the dataspace if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-ExtentType">H5Sget_simple_extent_type</a>
<dt><strong>Signature:</strong>
<dd><em>H5S_class_t</em> <code>H5Sget_simple_extent_type</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Determine the current class of a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sget_simple_extent_type</code> queries a dataspace to determine the
current class of a dataspace.
<p>
The function returns a class name, one of the following:
<code>H5S_SCALAR</code>,
<code>H5S_SIMPLE</code>, or
<code>H5S_NONE</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Dataspace identifier.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a dataspace class name if successful;
otherwise H5S_NO_CLASS (-1).
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sset_extent_simple</code>(<em>hid_t</em> <code>space_id</code>,
<em>int</em> <code>rank</code>,
<em>const hsize_t *</em><code>current_size</code>,
<em>const hsize_t *</em><code>maximum_size</code>
)
<dt><strong>Purpose:</strong>
<dd>Sets or resets the size of an existing dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sset_extent_simple</code> sets or resets the size of
an existing dataspace.
<p>
<code>rank</code> is the dimensionality, or number of
dimensions, of the dataspace.
<p>
<code>current_size</code> is an array of size <code>rank</code>
which contains the new size of each dimension in the dataspace.
<code>maximum_size</code> is an array of size <code>rank</code>
which contains the maximum size of each dimension in the
dataspace.
<p>
Any previous extent is removed from the dataspace, the dataspace
type is set to <code>H5S_SIMPLE</code>, and the extent is set as
specified.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Dataspace identifier.
<dt><em>int</em> <code>rank</code>
<dd>Rank, or dimensionality, of the dataspace.
<dt><em>const hsize_t *</em><code>current_size</code>
<dd>Array containing current size of dataspace.
<dt><em>const hsize_t *</em><code>maximum_size</code>
<dd>Array containing maximum size of dataspace.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a dataspace identifier if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a>
<dt><strong>Signature:</strong>
<dd><em>htri_t </em><code>H5Sis_simple</code>(<em>hid_t </em><code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Determines whether a dataspace is a simple dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sis_simple</code> determines whether a dataspace is
a simple dataspace. [Currently, all dataspace objects are simple
dataspaces, complex dataspace support will be added in the future]
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Identifier of the dataspace to query
</dl>
<dt><strong>Returns:</strong>
<dd>When successful, returns a positive value, for <code>TRUE</code>,
or <code>0</code> (zero), for <code>FALSE</code>.
Otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-OffsetSimple">H5Soffset_simple</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Soffset_simple</code>(<em>hid_t</em> <code>space_id</code>,
<em>const hssize_t *</em><code>offset</code>
)
<dt><strong>Purpose:</strong>
<dd>Sets the offset of a simple dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Soffset_simple</code> sets the offset of a
simple dataspace <code>space_id</code>. The <code>offset</code>
array must be the same number of elements as the number of
dimensions for the dataspace. If the <code>offset</code>
array is set to <TT>NULL</TT>, the offset for the dataspace
is reset to 0.
<p>
This function allows the same shaped selection to be moved
to different locations within a dataspace without requiring it
to be redefined.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: The identifier for the dataspace object to reset.
<dt><em>const hssize_t *</em><code>offset</code>
<dd>IN: The offset at which to position the selection.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<!-- NOT YET IMPLEMENTED (R1.2 -- 9908)
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-ExtentClass">H5Sextent_class</a>
<dt><strong>Signature:</strong>
<dd><em>H5S_class_t</em> <code>H5Sextent_class</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Determine the current class of a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sextent_class</code> queries a dataspace to determine the
current class of a dataspace.
<p>
The function returns a class name, one of the following:
<code>H5S_SCALAR</code>,
<code>H5S_SIMPLE</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Dataspace identifier.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a dataspace class name if successful;
otherwise H5S_NO_CLASS (-1).
</dl>
-->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-ExtentCopy">H5Sextent_copy</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sextent_copy</code>(<em>hid_t</em> <code>dest_space_id</code>,
<em>hid_t</em> <code>source_space_id</code>
)
<dt><strong>Purpose:</strong>
<dd>Copies the extent of a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sextent_copy</code> copies the extent from
<code>source_space_id</code> to <code>dest_space_id</code>.
This action may change the type of the dataspace.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>dest_space_id</code>
<dd>IN: The identifier for the dataspace to which
the extent is copied.
<dt><em>hid_t</em> <code>source_space_id</code>
<dd>IN: The identifier for the dataspace from which
the extent is copied.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SetExtentNone">H5Sset_extent_none</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sset_extent_none</code>(<em>hid_t</em> <code>space_id</code>)
<dt><strong>Purpose:</strong>
<dd>Removes the extent from a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sset_extent_none</code> removes the extent from
a dataspace and sets the type to <tt>H5S_NO_CLASS</tt>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>The identifier for the dataspace from which
the extent is to be removed.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperslab">H5Sselect_hyperslab</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Sselect_hyperslab</code>(<em>hid_t</em> <code>space_id</code>,
<em>H5S_seloper_t</em><code>op</code>,
<em>const hssize_t *</em><code>start</code>,
<em>const hsize_t *</em><code>stride</code>
<em>const hsize_t *</em><code>count</code>,
<em>const hsize_t *</em><code>block</code>
)
<dt><strong>Purpose:</strong>
<dd>Selects a hyperslab region to add to the current selected region.
<dt><strong>Description:</strong>
<dd><code>H5Sselect_hyperslab</code> selects a hyperslab region
to add to the current selected region for the dataspace
specified by <code>space_id</code>.
<p>
The <code>start</code>, <code>stride</code>, <code>count</code>,
and <code>block</code> arrays must be the same size as the rank
of the dataspace.
<p>
The selection operator <code>op</code> determines how the new
selection is to be combined with the already existing selection
for the dataspace.
<p>
The following operators are supported:
<dir>
<table width=80% border=0>
<tr><td valign=top>
<code>H5S_SELECT_SET</code>
</td><td valign=top>
Replaces the existing selection with the parameters from this call.
Overlapping blocks are not supported with this operator.
</td></tr><tr><td valign=top>
<code>H5S_SELECT_OR</code>
</td><td valign=top>
Adds the new selection to the existing selection.
</td></tr>
</table>
</dir>
<P>
The <code>start</code> array determines the starting coordinates
of the hyperslab
to select.
<p>
The <code>stride</code> array chooses array locations
from the dataspace
with each value in the <code>stride</code> array determining how
many elements to move
in each dimension. Setting a value in the <code>stride</code>
array to 1 moves to
each element in that dimension of the dataspace; setting a value of 2 in a
location in the <code>stride</code> array moves to every other
element in that
dimension of the dataspace. In other words, the <code>stride</code>
determines the
number of elements to move from the <code>start</code> location
in each dimension.
Stride values of 0 are not allowed. If the <code>stride</code>
parameter is <code>NULL</code>,
a contiguous hyperslab is selected (as if each value in the
<code>stride</code> array
was set to all 1's).
<p>
The <code>count</code> array determines how many blocks to
select from the dataspace, in each dimension.
<p>
The <code>block</code> array determines
the size of the element block selected from the dataspace.
If the <code>block</code>
parameter is set to <code>NULL</code>, the block size defaults
to a single element
in each dimension (as if the <code>block</code> array was set to all 1's).
<P>
For example, in a 2-dimensional dataspace, setting
<code>start</code> to [1,1],
<code>stride</code> to [4,4], <code>count</code> to [3,7], and
<code>block</code> to [2,2] selects
21 2x2 blocks of array elements starting with location (1,1) and selecting
blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.
<P>
Regions selected with this function call default to C order iteration when
I/O is performed.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Identifier of dataspace selection to modify
<dt><em>H5S_seloper_t</em> <code>op</code>
<dd>IN: Operation to perform on current selection.
<dt><em>const hssize_t *</em><code>start</code>
<dd>IN: Offset of start of hyperslab
<dt><em>const hsize_t *</em><code>count</code>
<dd>IN: Number of blocks included in hyperslab.
<dt><em>const hsize_t *</em><code>stride</code>
<dd>IN: Hyperslab stride.
<dt><em>const hsize_t *</em><code>block</code>
<dd>IN: Size of block in hyperslab.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperNBlocks">H5Sget_select_hyper_nblocks</a>
<dt><strong>Signature:</strong>
<dd><em>hssize_t </em><code>H5Sget_select_hyper_nblocks</code>(<em>hid_t </em><code>space_id</code>
)
<dt><strong>Purpose:</strong>
<dd>Get number of hyperslab blocks.
<dt><strong>Description:</strong>
<dd><code>H5Sget_select_hyper_nblocks</code> returns the
number of hyperslab blocks in the current dataspace selection.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Identifier of dataspace to query.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the number of hyperslab blocks in
the current dataspace selection if successful.
Otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperBlockList">H5Sget_select_hyper_blocklist</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t </em><code>H5Sget_select_hyper_blocklist</code>(<em>hid_t </em><code>space_id</code>,
<em>hsize_t </em><code>startblock</code>,
<em>hsize_t </em><code>numblocks</code>,
<em>hsize_t *</em><code>buf</code>
)
<dt><strong>Purpose:</strong>
<dd>Gets the list of hyperslab blocks currently selected.
<dt><strong>Description:</strong>
<dd><code>H5Sget_select_hyper_blocklist</code> returns a list of
the hyperslab blocks currently selected. Starting with the
<code>startblock</code>-th block in the list of blocks,
<code>numblocks</code> blocks are put into the user's buffer.
If the user's buffer fills up before <code>numblocks</code>
blocks are inserted, the buffer will contain only as many
blocks as fit.
<p>
The block coordinates have the same dimensionality (rank)
as the dataspace they are located within. The list of blocks
is formatted as follows:
<br>&nbsp;&nbsp;&nbsp;&nbsp;
&lt;"start" coordinate&gt;, immediately followed by
<br>&nbsp;&nbsp;&nbsp;&nbsp;
&lt;"opposite" corner coordinate&gt;, followed by
<br>&nbsp;&nbsp;&nbsp;&nbsp;
the next "start" and "opposite" coordinates,
<br>&nbsp;&nbsp;&nbsp;&nbsp;
etc.
<br>
until all of the selected blocks have been listed.
<p>
No guarantee is implied as the order in which blocks are listed.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Dataspace identifier of selection to query.
<dt><em>hsize_t </em><code>startblock</code>
<dd>IN: Hyperslab block to start with.
<dt><em>hsize_t </em><code>numblocks</code>
<dd>IN: Number of hyperslab blocks to get.
<dt><em>hsize_t *</em><code>buf</code>
<dd>OUT: List of hyperslab blocks selected.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectElemNPoints">H5Sget_select_elem_npoints</a>
<dt><strong>Signature:</strong>
<dd><em>hssize_t </em><code>H5Sget_select_elem_npoints</code>(<em>hid_t </em><code>space_id</code>
)
<dt><strong>Purpose:</strong>
<dd>Gets the number of element points in the current selection.
<dt><strong>Description:</strong>
<dd><code>H5Sget_select_elem_npoints</code> returns
the number of element points in the current dataspace selection.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Identifier of dataspace to query.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the number of element points in the current dataspace selection if successful.
Otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectElemPointList">H5Sget_select_elem_pointlist</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t </em><code>H5Sget_select_elem_pointlist</code>(<em>hid_t </em><code>space_id</code>
<em>hsize_t </em><code>startpoint</code>,
<em>hsize_t </em><code>numpoints</code>,
<em>hsize_t *</em><code>buf</code>
)
<dt><strong>Purpose:</strong>
<dd>Gets the list of element points currently selected.
<dt><strong>Description:</strong>
<dd><code>H5Sget_select_elem_pointlist</code> returns the list of
element points in the current dataspace selection. Starting with
the <code>startpoint</code>-th point in the list of points,
<code>numpoints</code> points are put into the user's buffer.
If the user's buffer fills up before <code>numpoints</code>
points are inserted, the buffer will contain only as many
points as fit.
<p>
The element point coordinates have the same dimensionality (rank)
as the dataspace they are located within. The list of element points
is formatted as follows:
<br>&nbsp;&nbsp;&nbsp;&nbsp;
&lt;coordinate&gt;, followed by
<br>&nbsp;&nbsp;&nbsp;&nbsp;
the next coordinate,
<br>&nbsp;&nbsp;&nbsp;&nbsp;
etc.
<br>
until all of the selected element points have been listed.
<p>
The points are returned in the order they will be iterated through
when the selection is read/written from/to disk.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Dataspace identifier of selection to query.
<dt><em>hsize_t </em><code>startpoint</code>
<dd>IN: Element point to start with.
<dt><em>hsize_t </em><code>numpoints</code>
<dd>IN: Number of element points to get.
<dt><em>hsize_t *</em><code>buf</code>
<dd>OUT: List of element points selected.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-SelectBounds">H5Sget_select_bounds</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t </em><code>H5Sget_select_bounds</code>(<em>hid_t </em><code>space_id</code>
<em>hsize_t *</em><code>start</code>,
<em>hsize_t *</em><code>end</code>
)
<dt><strong>Purpose:</strong>
<dd>Gets the bounding box containing the current selection.
<dt><strong>Description:</strong>
<dd><code>H5Sget_select_bounds</code> retrieves the coordinates of
the bounding box containing the current selection and places
them into user-supplied buffers.
<p>
The <code>start</code> and <code>end</code> buffers must be large
enough to hold the dataspace rank number of coordinates.
<p>
The bounding box exactly contains the selection.
I.e., if a 2-dimensional element selection is currently
defined as containing the points (4,5), (6,8), and (10,7),
then the bounding box will be (4, 5), (10, 8).
<p>
The bounding box calculation includes the current offset of the
selection within the dataspace extent.
<p>
Calling this function on a <code>none</code> selection will
return <code>FAIL</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>IN: Identifier of dataspace to query.
<dt><em>hsize_t *</em><code>start</code>
<dd>OUT: Starting coordinates of the bounding box.
<dt><em>hsize_t *</em><code>end</code>
<dd>OUT: Ending coordinates of the bounding box,
i.e., the coordinates of the diagonally opposite corner.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code>
)
<dt><strong>Purpose:</strong>
<dd>Releases and terminates access to a dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Sclose</code> releases a dataspace.
Further access through the dataspace identifier is illegal.
Failure to release a dataspace with this call will
result in resource leaks.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>space_id</code>
<dd>Identifier of dataspace to release.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a>&nbsp;<br>
<a href="H5.user.html">HDF5 User Guide</a>&nbsp;<br>
<a href="index.html">Other HDF5 documents and links</a>&nbsp;<br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;&nbsp;
<br>
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5I.html">H5I</a>&nbsp;&nbsp;
<br>
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<a href="RM_H5R.html">H5R</a>&nbsp;&nbsp;
<a href="RM_H5RA.html">H5RA</a>&nbsp;&nbsp;
H5S&nbsp;&nbsp;
<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<a href="Tools.html">Tools</a>&nbsp;&nbsp;
</td></tr>
</table>
</center>
<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
<br>
Last modified: 30 October 1998
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink