mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
fd05f98e9e
Purpose:
Marking files for "Release 1.4, February 2001."
Description:
Across doc files
Updating "Describes HDF5 Release..." entry to "Describes
HDF5 Release 1.4, February 2001."
Copyright.html: Added 2001 to years copyrighted.
index.html: Changed header to Release 1.4 (from 1.4 Beta)
Platforms tested:
IE 5
689 lines
27 KiB
HTML
689 lines
27 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<TITLE>Dataspace Interface (H5S)</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="RM_H5Front.html">HDF5 Reference Manual</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="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
|
|
<br>
|
|
<a href="Files.html">Files</a>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Datatypes</a>
|
|
Dataspaces
|
|
<a href="Groups.html">Groups</a>
|
|
<br>
|
|
<a href="References.html">References</a>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<br>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="MountingFiles.html">Mounting Files</a>
|
|
<br>
|
|
<a href="Performance.html">Performance</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<H1>
|
|
The Dataspace Interface (H5S)</H1>
|
|
|
|
<H2>
|
|
1. Introduction</H2>
|
|
The dataspace interface (H5S) provides a mechanism to describe the positions
|
|
of the elements of a dataset and is designed in such a way as to allow
|
|
new features to be easily added without disrupting applications that use
|
|
the dataspace interface. A dataset (defined with the dataset interface) is
|
|
composed of a collection of raw data points of homogeneous type, defined in the
|
|
datatype (H5T) interface, organized according to the dataspace with this
|
|
interface.
|
|
|
|
<P>A dataspace describes the locations that dataset elements are located at.
|
|
A dataspace is either a regular N-dimensional array of data points,
|
|
called a <I>simple</I> dataspace, or a more general collection of data
|
|
points organized in another manner, called a <I>complex</I> dataspace.
|
|
A <I>scalar</I> dataspace is a special case of the <I>simple</I> data
|
|
space and is defined to be a 0-dimensional single data point in size. Currently
|
|
only <I>scalar</I> and <I>simple</I> dataspaces are supported with this version
|
|
of the H5S interface.
|
|
<I>Complex</I> dataspaces will be defined and implemented in a future
|
|
version. <I>Complex</I> dataspaces are intended to be used for such structures
|
|
which are awkward to express in <I>simple</I> dataspaces, such as irregularly
|
|
gridded data or adaptive mesh refinement data. This interface provides
|
|
functions to set and query properties of a dataspace.
|
|
|
|
<P>Operations on a dataspace include defining or extending the extent of
|
|
the dataspace, selecting portions of the dataspace for I/O and storing the
|
|
dataspaces in the file. The extent of a dataspace is the range of coordinates
|
|
over which dataset elements are defined and stored. Dataspace selections are
|
|
subsets of the extent (up to the entire extent) which are selected for some
|
|
operation.
|
|
|
|
<P>For example, a 2-dimensional dataspace with an extent of 10 by 10 may have
|
|
the following very simple selection:
|
|
<br><br><center>
|
|
<table border cellpadding=4>
|
|
<tr align=center>
|
|
<th > </th> <th >0</th> <th >1</th> <th >2</th> <th >3</th> <th >4</th> <th >5</th> <th >6</th> <th >7</th> <th >8</th> <th >9</th>
|
|
<tr align=center>
|
|
<th>0</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>1</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>2</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>3</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>4</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>5</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>6</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>7</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>8</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>9</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
</table>
|
|
<br><strong>Example 1: Contiguous rectangular selection</strong>
|
|
</center>
|
|
|
|
|
|
<br>Or, a more complex selection may be defined:
|
|
<br><br><center>
|
|
<table border cellpadding=4>
|
|
<tr align=center>
|
|
<th > </th> <th >0</th> <th >1</th> <th >2</th> <th >3</th> <th >4</th> <th >5</th> <th >6</th> <th >7</th> <th >8</th> <th >9</th>
|
|
<tr align=center>
|
|
<th>0</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>1</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>2</th>
|
|
<td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>3</th>
|
|
<td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>4</th>
|
|
<td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>5</th>
|
|
<td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>6</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>7</th>
|
|
<td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>8</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>9</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
</table>
|
|
<br><strong>Example 2: Non-contiguous selection</strong>
|
|
</center>
|
|
|
|
<P>Selections within dataspaces have an offset within the extent which is used
|
|
to locate the selection within the extent of the dataspace. Selection offsets
|
|
default to 0 in each dimension, but may be changed to move the selection within
|
|
a dataspace. In example 2 above, if the offset was changed to 1,1, the selection
|
|
would look like this:
|
|
<br><br><center>
|
|
<table border cellpadding=4>
|
|
<tr align=center>
|
|
<th > </th> <th >0</th> <th >1</th> <th >2</th> <th >3</th> <th >4</th> <th >5</th> <th >6</th> <th >7</th> <th >8</th> <th >9</th>
|
|
<tr align=center>
|
|
<th>0</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>1</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>2</th>
|
|
<td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>3</th>
|
|
<td>-</td><td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>4</th>
|
|
<td>-</td><td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>5</th>
|
|
<td>-</td><td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>6</th>
|
|
<td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>7</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>8</th>
|
|
<td>-</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td>
|
|
<tr align=center>
|
|
<th>9</th>
|
|
<td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td>
|
|
</table>
|
|
<br><strong>Example 3: Non-contiguous selection with 1,1 offset</strong>
|
|
</center>
|
|
|
|
<P>Selections also have a linearization ordering of the points selected
|
|
(defaulting to "C" order, ie. last dimension changing fastest). The
|
|
linearization order may be specified for each point or it may be chosen by
|
|
the axis of the dataspace. For example, with the default "C" ordering,
|
|
example 1's selected points are iterated through in this order: (1,1), (1,2),
|
|
(1,3), (2,1), (2,2), etc. With "FORTRAN" ordering, example 1's selected points
|
|
would be iterated through in this order: (1,1), (2,1), (3,1), (4,1), (5,1),
|
|
(1,2), (2,2), etc.
|
|
|
|
<P>A dataspace may be stored in the file as a permanent object, to allow many
|
|
datasets to use a commonly defined dataspace. Dataspaces with extendable
|
|
extents (ie. unlimited dimensions) are not able to be stored as permanent
|
|
dataspaces.
|
|
|
|
<P>Dataspaces may be created using an existing permanent dataspace as a
|
|
container to locate the new dataspace within. These dataspaces are complete
|
|
dataspaces and may be used to define datasets. A dataspaces with a "parent"
|
|
can be queried to determine the parent dataspace and the location within the
|
|
parent. These dataspaces must currently be the same number of dimensions as
|
|
the parent dataspace.
|
|
|
|
<H2> 2. General Dataspace Operations</H2>
|
|
The functions defined in this section operate on dataspaces as a whole.
|
|
New dataspaces can be created from scratch or copied from existing data
|
|
spaces. When a dataspace is no longer needed its resources should be released
|
|
by calling <TT>H5Sclose()</TT>.
|
|
<DL>
|
|
|
|
<DT>
|
|
<TT>hid_t H5Screate(H5S_class_t <I>type</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function creates a new dataspace of a particular <I>type</I>. The
|
|
types currently supported are H5S_SCALAR and H5S_SIMPLE;
|
|
others are planned to be added later.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>hid_t H5Sopen(hid_t <I>location</I>, const char *<I>name</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function opens a permanent dataspace for use in an application.
|
|
The <I>location</I> argument is a file or group ID and <I>name</I> is
|
|
an absolute or relative path to the permanent dataspace. The dataspace ID which
|
|
is returned is a handle to a permanent dataspace which can't be modified.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>hid_t H5Scopy (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function creates a new dataspace which is an exact copy of the
|
|
dataspace <I>space</I>.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>hid_t H5Ssubspace (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function uses the currently defined selection and offset in <I>space</I>
|
|
to create a dataspace which is located within <I>space</I>. The <I>space</I>
|
|
dataspace must be a sharable dataspace located in the file, not a dataspace for
|
|
a dataset. The relationship of the new dataspace within the existing dataspace
|
|
is preserved when the new dataspace is used to create datasets. Currently,
|
|
only subspaces which are equivalent to simple dataspaces (ie. rectangular
|
|
contiguous areas) are allowed. A subspace is not "simplified" or reduced in
|
|
the number of dimensions used if the selection is "flat" in one dimension, they
|
|
always have the same number of dimensions as their parent dataspace.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Scommit (hid_t <I>location</I>, const char *<I>name</I>, hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
The dataspaces specified with <I>space</I> is stored in the file specified
|
|
by <I>location</I>. <I>Location</I> may be either a file or group handle
|
|
and <I>name</I> is an absolute or relative path to the location to store the
|
|
dataspace. After this call, the dataspace is permanent and can't be modified.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sclose (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Releases resources associated with a dataspace. Subsequent use of the
|
|
dataspace identifier after this call is undefined.
|
|
</DD>
|
|
|
|
<!-- NOT YET IMPLEMENTED (R1.2 -- 9908)
|
|
|
|
<DT>
|
|
<TT>H5S_class_t H5Sextent_class (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Query a dataspace to determine the current class of a dataspace. The value
|
|
which is returned is one of: H5S_SCALAR, H5S_SIMPLE on success or
|
|
H5S_NO_CLASS on failure.
|
|
</DD>
|
|
|
|
-->
|
|
|
|
</DL>
|
|
|
|
|
|
<H2> 3. Dataspace Extent Operations</H2>
|
|
These functions operate on the extent portion of a dataspace.
|
|
|
|
<DL>
|
|
<DT>
|
|
<TT>herr_t H5Sset_extent_simple (hid_t <I>space</I>, int <I>rank</I>, const hsize_t
|
|
*<I>current_size</I>, const hsize_t *<I>maximum_size</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Sets or resets the size of an existing dataspace, where <I>rank</I> is
|
|
the dimensionality, or number of dimensions, of the dataspace.
|
|
<I>current_size</I> is an array of size <I>rank</I> which contains the new size
|
|
of each dimension in the dataspace. <I>maximum_size</I> is an array of size
|
|
<I>rank</I> which contains the maximum size of each dimension in the dataspace.
|
|
Any previous extent is removed from the dataspace, the dataspace type is set to
|
|
H5S_SIMPLE and the extent is set as specified.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sset_extent_none (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Removes the extent from a dataspace and sets the type to H5S_NO_CLASS.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sextent_copy (hid_t <I>dest_space</I>,
|
|
hid_t <I>source_space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Copies the extent from <I>source_space</I> to <I>dest_space</I>, which may
|
|
change the type of the dataspace. Returns non-negative on success, negative on
|
|
failure.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>hsize_t H5Sget_simple_extent_npoints (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function 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.
|
|
Returns the number of elements in the dataspace, negative on failure.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>int H5Sget_simple_extent_ndims (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function determines the dimensionality (or rank) of a dataspace.
|
|
Returns the number of dimensions in the dataspace, negative on failure.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sget_simple_extent_dims (hid_t <I>space</I>, hsize_t *<I>dims</I>,
|
|
hsize_t *<I>max</I>)</TT></DT>
|
|
|
|
<DD>
|
|
The function retrieves the size of the extent of the dataspace <I>space</I> by
|
|
placing the size of each dimension in the array <I>dims</I>. Also retrieves
|
|
the size of the maximum extent of the dataspace, placing the results in
|
|
<I>max</I>.
|
|
Returns non-negative on success, negative on failure.
|
|
</DD>
|
|
|
|
</DL>
|
|
|
|
<H2> 4. Dataspace Selection Operations</H2>
|
|
Selections are maintained separately from extents in dataspaces and operations
|
|
on the selection of a dataspace do not affect the extent of the dataspace.
|
|
Selections are independent of extent type and the boundaries of selections are
|
|
reconciled with the extent at the time of the data transfer. Selection offsets
|
|
apply a selection to a location within an extent, allowing the same selection
|
|
to be moved within the extent without requiring a new selection to be specified.
|
|
Offsets default to 0 when the dataspace is created. Offsets are applied when
|
|
an I/O transfer is performed (and checked during calls to H5Sselect_valid).
|
|
Selections have an iteration order for the points selected, which can be any
|
|
permutation of the dimensions involved (defaulting to 'C' array order) or a
|
|
specific order for the selected points, for selections composed of single array
|
|
elements with H5Sselect_elements. Selections can also be copied or combined
|
|
together in various ways with H5Sselect_op. Further methods of selecting
|
|
portions of a dataspace may be added in the future.
|
|
|
|
<DL>
|
|
<DT>
|
|
<TT>herr_t H5Sselect_hyperslab (hid_t <I>space</I>, h5s_selopt_t <I>op</I>,
|
|
const hssize_t * <I>start</I>, const hsize_t * <I>stride</I>,
|
|
const hsize_t * <I>count</I>, const hsize_t * <I>block</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function selects a hyperslab region to add to the current selected region
|
|
for the <I>space</I> dataspace. 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.
|
|
The selection operator <I>op</I> determines how the new selection is to be
|
|
combined with the already existing selection for the dataspace.
|
|
Currently, 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 <I>start</I> array determines the starting coordinates of the hyperslab
|
|
to select. The <I>stride</I> array chooses array locations from the dataspace
|
|
with each value in the <I>stride</I> array determining how many elements to move
|
|
in each dimension. Setting a value in the <I>stride</I> array to 1 moves to
|
|
each element in that dimension of the dataspace, setting a value of 2 in a
|
|
location in the <I>stride</I> array moves to every other element in that
|
|
dimension of the dataspace. In other words, the <I>stride</I> determines the
|
|
number of elements to move from the <I>start</I> location in each dimension.
|
|
Stride values of 0 are not allowed. If the <I>stride</I> parameter is <TT>NULL</TT>,
|
|
a contiguous hyperslab is selected (as if each value in the <I>stride</I> array
|
|
was set to all 1's). The <I>count</I> array determines how many blocks to
|
|
select from the dataspace, in each dimension. The <I>block</I> array determines
|
|
the size of the element block selected from the dataspace. If the <I>block</I>
|
|
parameter is set to <TT>NULL</TT>, the block size defaults to a single element
|
|
in each dimension (as if the <I>block</I> array was set to all 1's).
|
|
<P>For example, in a 2-dimensional dataspace, setting <I>start</I> to [1,1],
|
|
<I>stride</I> to [4,4], <I>count</I> to [3,7] and <I>block</I> 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.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sselect_elements (hid_t <I>space</I>, h5s_selopt_t <I>op</I>,
|
|
const size_t <I>num_elements</I>, const hssize_t *<I>coord</I>[])</TT></DT>
|
|
|
|
<DD>
|
|
This function selects array elements to be included in the selection for the
|
|
<I>space</I> dataspace. The number of elements selected must be set with the
|
|
<I>num_elements</I>. The <I>coord</I> array is a two-dimensional array of size
|
|
<dataspace rank> by <<I>num_elements</I>> in size (ie. a list of
|
|
coordinates in the array). The order of the element coordinates in the
|
|
<I>coord</I> array also specifies the order that the array elements are
|
|
iterated through when I/O is performed. Duplicate coordinate locations are not
|
|
checked for.
|
|
|
|
<P>The selection operator <I>op</I> determines how the new selection is to be
|
|
combined with the already 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
|
|
H5S_SELECT_SET are used to combine a new selection with an existing selection,
|
|
the selection ordering is reset to 'C' array ordering.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sselect_all (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function selects the special H5S_SELECT_ALL region for the <I>space</I>
|
|
dataspace. H5S_SELECT_ALL selects the entire dataspace for any dataspace is is
|
|
applied to.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sselect_none (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function resets the selection region for the <I>space</I>
|
|
dataspace not to include any elements.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sselect_op (hid_t <I>space1</I>, h5s_selopt_t <I>op</I>,
|
|
hid_t <I>space2</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Uses <I>space2</I> to perform an operation on <I>space1</I>. The valid
|
|
operations for <I>op</I> are:
|
|
<DL>
|
|
<DT>H5S_SELECT_COPY
|
|
<DD>Copies the selection from <I>space2</I> into <I>space1</I>, removing any
|
|
previously defined selection for <I>space1</I>. The selection order
|
|
and offset are also copied to <I>space1</I>
|
|
<DT>H5S_SELECT_UNION
|
|
<DD>Performs a set union of the selection of the dataspace <I>space2</I>
|
|
with the selection from the dataspace <I>space1</I>, with the result
|
|
being stored in <I>space1</I>. The selection order for <I>space1</I> is
|
|
reset to 'C' order.
|
|
<DT>H5S_SELECT_INTERSECT
|
|
<DD>Performs an set intersection of the selection from <I>space2</I> with
|
|
<I>space1</I>, with the result being stored in <I>space1</I>. The
|
|
selection order for <I>space1</I> is reset to 'C' order.
|
|
<DT>H5S_SELECT_DIFFERENCE
|
|
<DD>Performs a set difference of the selection from <I>space2</I> with
|
|
<I>space1</I>, with the result being stored in <I>space1</I>. The
|
|
selection order for <I>space1</I> is reset to 'C' order.
|
|
</DL>
|
|
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Sselect_order (hid_t <I>space</I>,
|
|
hsize_t <I>perm_vector</I>[])</TT></DT>
|
|
|
|
<DD>
|
|
This function selects the order to iterate through the dimensions of a dataspace
|
|
when performing I/O on a selection. If a specific order has already been
|
|
selected for the selection with H5Sselect_elements, this function will remove
|
|
it and use a dimension oriented ordering on the selected elements. The elements
|
|
of the <I>perm_vector</I> array must be unique and between 0 and the rank of the
|
|
dataspace, minus 1. The order of the elements in <I>perm_vector</I> specify
|
|
the order to iterate through the selection for each dimension of the dataspace.
|
|
To iterate through a 3-dimensional dataspace selection in 'C' order, specify
|
|
the elements of the <I>perm_vector</I> as [0, 1, 2], for FORTRAN order they
|
|
would be [2, 1, 0]. Other orderings, such as [1, 2, 0] are also possible, but
|
|
may execute slower.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>htri_t H5Sselect_valid (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function verifies that the selection for a dataspace is within the extent
|
|
of the dataspace, if the currently set offset for the dataspace is used.
|
|
Returns TRUE if the selection is contained within the extent, FALSE if it
|
|
is not contained within the extent and FAIL on error conditions (such as if
|
|
the selection or extent is not defined).
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>hsize_t H5Sget_select_npoints (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function determines the number of elements in the current selection
|
|
of a dataspace.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Soffset_simple (hid_t <I>space</I>, const hssize_t *
|
|
<I>offset</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Sets the offset of a simple dataspace <I>space</I>. The <I>offset</I> array
|
|
must be the same number of elements as the number of dimensions for the
|
|
dataspace. If the <I>offset</I> array is set to <TT>NULL</TT>, the offset
|
|
for the dataspace is reset to 0.
|
|
</DD>
|
|
|
|
</DL>
|
|
|
|
<H2> 5. Misc. Dataspace Operations</H2>
|
|
|
|
<DL>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Slock (hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
Locks the dataspace so that it cannot be modified or closed. When the library
|
|
exits, the dataspace will be unlocked and closed.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>hid_t H5Screate_simple(int <I>rank</I>, const hsize_t *<I>current_size</I>,
|
|
const hsize_t *<I>maximum_size</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function is a "convenience" wrapper to create a simple dataspace
|
|
and set it's extent in one call. It is equivalent to calling H5Screate
|
|
and H5Sset_extent_simple() in two steps.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>int H5Sis_subspace(hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function returns positive if <I>space</I> is located within another
|
|
dataspace, zero if it is not, and negative on a failure.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>char *H5Ssubspace_name(hid_t <I>space</I>)</TT></DT>
|
|
|
|
<DD>
|
|
This function returns the name of the named dataspace that <I>space</I>
|
|
is located within. If <I>space</I> is not located within another dataspace,
|
|
or an error occurs, NULL is returned. The application is responsible for
|
|
freeing the string returned.
|
|
</DD>
|
|
|
|
<DT>
|
|
<TT>herr_t H5Ssubspace_location(hid_t <I>space</I>, hsize_t *<I>loc</I>)</TT></DT>
|
|
|
|
<DD>
|
|
If <I>space</I> is located within another dataspace, this function puts
|
|
the location of the origin of <I>space</I> in the <I>loc</I> array. The <I>loc</I>
|
|
array must be at least as large as the number of dimensions of <I>space</I>.
|
|
If <I>space</I> is not located within another dataspace
|
|
or an error occurs, a negative value is returned, otherwise a non-negative value
|
|
is returned.
|
|
</DD>
|
|
|
|
</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="RM_H5Front.html">HDF5 Reference Manual</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="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
|
|
<br>
|
|
<a href="Files.html">Files</a>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Datatypes</a>
|
|
Dataspaces
|
|
<a href="Groups.html">Groups</a>
|
|
<br>
|
|
<a href="References.html">References</a>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<br>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="MountingFiles.html">Mounting Files</a>
|
|
<br>
|
|
<a href="Performance.html">Performance</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
<!-- Created: Thu Dec 4 14:57:32 EST 1997 -->
|
|
<!-- hhmts start -->
|
|
Last modified: 13 December 1999
|
|
<!-- hhmts end -->
|
|
|
|
<br>
|
|
Describes HDF5 Release 1.4, February 2001
|
|
|
|
|
|
</BODY>
|
|
</HTML>
|