mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-01-24 15:25:00 +08:00
82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
783 lines
29 KiB
HTML
783 lines
29 KiB
HTML
<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> <br>
|
|
<a href="H5.user.html">HDF5 User Guide</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <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>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<br>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5RA.html">H5RA</a>
|
|
H5S
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
</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>
|
|
<ul>
|
|
<li><a href="#Dataspace-Create">H5Screate</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-Copy">H5Scopy</a>
|
|
<li><a href="#Dataspace-ExtentClass">H5Sextent_class</a>
|
|
<li><a href="#Dataspace-ExtentCopy">H5Sextent_copy</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<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-ExtentDims">H5Sget_simple_extent_dims</a>
|
|
<li><a href="#Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</a>
|
|
<li><a href="#Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a>
|
|
<li><a href="#Dataspace-ExtentType">H5Sget_simple_extent_type</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<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>
|
|
<li><a href="#Dataspace-Close">H5Sclose</a>
|
|
</ul>
|
|
</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
|
|
<li>H5Sopen
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li>H5Sselect_name
|
|
<li>H5Sselect_op
|
|
<li>H5Sselect_order
|
|
</ul>
|
|
</td><td> </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>,
|
|
<code>H5S_SIMPLE</code>, and <code>H5S_NONE</code>;
|
|
others are planned to be added later. The <code>H5S_NONE</code>
|
|
dataspace can only hold a selection, not an extent.
|
|
<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>dh5s_selopt_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. Currently, only the
|
|
<code>H5S_SELECT_SET</code> operator is supported, which
|
|
replaces the existing selection with the parameters from
|
|
this call. 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>dh5s_selopt_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>hbool_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 <tt>TRUE</tt> if the selection is contained within
|
|
the extent and <tt>FALSE</tt> if it is not.
|
|
Returns 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.
|
|
<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>hbool_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>Returns TRUE or FALSE if Successful;
|
|
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>
|
|
|
|
|
|
<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 from which
|
|
the extent is copied.
|
|
<dt><em>hid_t</em> <code>source_space_id</code>
|
|
<dd>IN: The identifier for the dataspace to 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_NONE</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_selopt_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>
|
|
Currently, only the <code>H5S_SELECT_SET</code> operator is
|
|
supported; it replaces the existing selection with the
|
|
parameters from this call. Overlapping blocks are not
|
|
supported with the <code>H5S_SELECT_SET</code> operator.
|
|
<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-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> <br>
|
|
<a href="H5.user.html">HDF5 User Guide</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <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>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<br>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5RA.html">H5RA</a>
|
|
H5S
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
</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>
|