summaryrefslogtreecommitdiffstats
path: root/doc/html/Dataspaces.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/Dataspaces.html')
-rw-r--r--doc/html/Dataspaces.html568
1 files changed, 568 insertions, 0 deletions
diff --git a/doc/html/Dataspaces.html b/doc/html/Dataspaces.html
new file mode 100644
index 0000000..d2579b6
--- /dev/null
+++ b/doc/html/Dataspaces.html
@@ -0,0 +1,568 @@
+<HTML>
+<HEAD>
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+ <TITLE>The Data Space Interface (H5S)</TITLE>
+</HEAD>
+<BODY>
+
+<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 an 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), (2,1),
+(3,1), (1,2), (2,2), etc. With "FORTRAN" ordering, example 1's selected points
+would be iterated through in this order: (1,1), (1,2), (1,3), (1,4), (1,5),
+(2,1), (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, H5S_SIMPLE, or H5S_NONE, although
+others are planned to be added later. The H5S_NONE dataspace can only hold a
+selection, not an extent.
+</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>
+
+<DT>
+<TT>H5S_class_t H5Sget_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, or H5S_NONE on success or
+FAIL 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_NONE.
+</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 H5Sextent_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 H5Sextent_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 H5Sextent_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,
+only the H5S_SELECT_SET operator is supported, which replaces the existing
+selection with the parameters from this call. Overlapping blocks are not
+supported with the H5S_SELECT_SET operator.
+<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
+&lt;dataspace rank&gt; by &lt;<I>num_elements</I>&gt; 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. Currently,
+only the H5S_SELECT_SET operator is supported, which replaces the existing
+selection with the parameters from this call. 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>hbool_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 H5Sselect_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>
+<ADDRESS>
+<A HREF="mailto:matzke@llnl.gov">Robb Matzke</A></ADDRESS>
+
+<ADDRESS>
+<A HREF="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</A></ADDRESS>
+
+<BR><!-- Created: Thu Dec 4 14:57:32 EST 1997 --><!-- hhmts start -->Last
+modified: Thu May 28 15:12:04 EST 1998&nbsp;<!-- hhmts end -->
+</BODY>
+</HTML>