diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2003-10-07 19:56:17 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2003-10-07 19:56:17 (GMT) |
| commit | cf629d9e6c89eadd77ce98a527ac43b2fc4fcdc4 (patch) | |
| tree | 761bc97e2a3846cd08805586969c8fba5fde5db1 /doc/html/RM_H5S.html | |
| parent | 038c920c9f767d9be17cc6df0eb53a70bc71c557 (diff) | |
| download | hdf5-cf629d9e6c89eadd77ce98a527ac43b2fc4fcdc4.zip hdf5-cf629d9e6c89eadd77ce98a527ac43b2fc4fcdc4.tar.gz hdf5-cf629d9e6c89eadd77ce98a527ac43b2fc4fcdc4.tar.bz2 | |
[svn-r7567]
Purpose:
Alphabetic sort of RM function entries
Additional and modified HTML coding to accomodate HTMLdoc and
automated PDF generation
Description:
Solution:
Platforms tested:
Misc. update:
Diffstat (limited to 'doc/html/RM_H5S.html')
| -rw-r--r-- | doc/html/RM_H5S.html | 968 |
1 files changed, 494 insertions, 474 deletions
diff --git a/doc/html/RM_H5S.html b/doc/html/RM_H5S.html index 0d73fd7..7bb5286 100644 --- a/doc/html/RM_H5S.html +++ b/doc/html/RM_H5S.html @@ -25,6 +25,7 @@ HDF5/H5S API Specification <!-- #EndLibraryItem --></head> <body bgcolor="#FFFFFF"> +<!-- HEADER RIGHT " " --> <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> @@ -60,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5S: Dataspace Interface</h1> </center> @@ -159,20 +159,20 @@ elements of a dataset. </tr> </table> -<p> +<br> <strong>The FORTRAN90 Interfaces:</strong> <br> <font size=-1> <i>In general, each FORTRAN90 subroutine performs exactly the same task -as the corresponding C function. The links below go to the C function +as the corresponding C function. The links below (electronic versions only) go to the C function descriptions, which serve as general descriptions for both. A button, under <strong>Non-C API(s)</strong> at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them.</i> -</font> +</font><br> <table border=0> <tr><td valign=top> @@ -241,7 +241,73 @@ of the <cite>HDF5 User's Guide.</cite>. </table> --> +<!-- NEW PAGE --> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sclose" --> +<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. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5s_FORTRAN.html#h5sclose_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Scopy" --> +<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. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5s_FORTRAN.html#h5scopy_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> + +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Screate" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-Create">H5Screate</a> @@ -272,7 +338,8 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Screate_simple" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-CreateSimple">H5Screate_simple</a> @@ -326,30 +393,35 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sextent_copy" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentCopy">H5Sextent_copy</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code> + <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>Creates an exact copy of a dataspace. + <dd>Copies the extent 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. + <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>space_id</code> - <dd>Identifier of dataspace to copy. + <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 dataspace identifier if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5scopy_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_copy_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -357,112 +429,82 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_bounds" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectBounds">H5Sget_select_bounds</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>[ ] + <dd><em>herr_t </em><code>H5Sget_select_bounds</code>(<em>hid_t </em><code>space_id</code>, + <em>hssize_t *</em><code>start</code>, + <em>hssize_t *</em><code>end</code> ) <dt><strong>Purpose:</strong> - <dd>Selects array elements to be included in the selection for a dataspace. + <dd>Gets the bounding box containing the current selection. <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. + <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 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: - <center> - <table width=90% 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><tr><td valign=top> - <code>H5S_SELECT_APPEND</code> - </td><td valign=top> - Adds the new selection following the last element of the existing selection. - </td></tr><tr><td valign=top> - <code>H5S_SELECT_PREPEND </code> - </td><td valign=top> - Adds the new selection preceding the first element of the existing selection. - </td></tr> - </table> - </center> -<!-- When operator <code>H5S_SELECT_OR</code> - is used to combine a new selection with an existing selection, - the selection ordering is reset to C array ordering. ---> + 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>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. + <dd>IN: Identifier of dataspace to query. + <dt><em>hssize_t *</em><code>start</code> + <dd>OUT: Starting coordinates of the bounding box. + <dt><em>hssize_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 non-negative value if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_elements_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_bounds_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- +--> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_elem_npoints" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectAll">H5Sselect_all</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElemNPoints">H5Sget_select_elem_npoints</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sselect_all</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>hssize_t </em><code>H5Sget_select_elem_npoints</code>(<em>hid_t </em><code>space_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Selects the entire dataspace. + <dd>Gets the number of element points in the current selection. <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. + <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: The identifier for the dataspace in which the - selection is being made. + <dd>IN: Identifier of dataspace to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the number of element points in the current dataspace selection if successful. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_all_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_npoints_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -470,28 +512,58 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_elem_pointlist" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectNone">H5Sselect_none</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElemPointList">H5Sget_select_elem_pointlist</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sselect_none</code>(<em>hid_t</em> <code>space_id</code>) + <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>Resets the selection region to include no elements. + <dd>Gets the list of element points currently selected. <dt><strong>Description:</strong> - <dd><code>H5Sselect_none</code> resets the selection region - for the dataspace <code>space_id</code> to include no elements. + <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> + <coordinate>, followed by + <br> + the next coordinate, + <br> + 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: The identifier for the dataspace in which the - selection is being reset. + <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. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_none_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_pointlist_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -499,31 +571,59 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_hyper_blocklist" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectValid">H5Sselect_valid</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperBlockList">H5Sget_select_hyper_blocklist</a> <dt><strong>Signature:</strong> - <dd><em>htri_t</em> <code>H5Sselect_valid</code>(<em>hid_t</em> <code>space_id</code>) + <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>Verifies that the selection is within the extent of the dataspace. + <dd>Gets the list of hyperslab blocks currently selected. <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. + <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> + <"start" coordinate>, immediately followed by + <br> + <"opposite" corner coordinate>, followed by + <br> + the next "start" and "opposite" coordinates, + <br> + 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>The identifier for the dataspace being queried. + <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 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. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_valid_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_blocklist_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -531,28 +631,30 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_hyper_nblocks" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperNBlocks">H5Sget_select_hyper_nblocks</a> <dt><strong>Signature:</strong> - <dd><em>hssize_t</em> <code>H5Sget_simple_extent_npoints</code>(<em>hid_t </em><code>space_id</code>) + <dd><em>hssize_t </em><code>H5Sget_select_hyper_nblocks</code>(<em>hid_t </em><code>space_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Determines the number of elements in a dataspace. + <dd>Get number of hyperslab blocks. <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. + <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>ID of the dataspace object to query + <dd>IN: Identifier of dataspace to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of elements in the dataspace if successful; - otherwise returns 0. + <dd>Returns the number of hyperslab blocks in + the current dataspace selection if successful. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_npoints_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_nblocks_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -560,7 +662,8 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_npoints" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-SelectNpoints">H5Sget_select_npoints</a> @@ -588,27 +691,53 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_select_type" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</a> +<dt><strong>Name:</strong> <a name="Dataspace-GetSelectType">H5Sget_select_type</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_simple_extent_ndims</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>H5S_sel_type</em> <code>H5Sget_select_type</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Determines the dimensionality of a dataspace. + <dd>Determines the type of the dataspace selection. <dt><strong>Description:</strong> - <dd><code>H5Sget_simple_extent_ndims</code> determines the dimensionality (or rank) - of a dataspace. + <dd><code>H5Sget_select_type</code> retrieves the + type of selection currently defined for the dataspace + <code>space_id</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>Identifier of the dataspace + <dd>Dataspace identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of dimensions in the dataspace if successful; - otherwise returns a negative value. + <dd>Returns the dataspace selection type, a value of + the enumerated datatype <code>H5S_sel_type</code>, + if successful. + Valid return values are as follows: + <center> + <table width=90% border=0> + <tr><td valign=top> + <code>H5S_SEL_NONE</code> + </td><td valign=top> + No selection is defined. + </td></tr><tr><td valign=top> + <code>H5S_SEL_POINTS</code> + </td><td valign=top> + A sequence of points is selected. + </td></tr><tr><td valign=top> + <code>H5S_SEL_HYPERSLABS</code> + </td><td valign=top> + A hyperslab or compound hyperslab is selected. + </td></tr><tr><td valign=top> + <code>H5S_SEL_ALL</code> + </td><td valign=top> + The entire dataset is selected. + </td></tr> + </table> + </center> + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_ndims_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_type_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -616,7 +745,8 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_simple_extent_dims" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-ExtentDims">H5Sget_simple_extent_dims</a> @@ -659,32 +789,28 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_simple_extent_ndims" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentType">H5Sget_simple_extent_type</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</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>) + <dd><em>int</em> <code>H5Sget_simple_extent_ndims</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Determine the current class of a dataspace. + <dd>Determines the dimensionality 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>. + <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>Dataspace identifier. + <dd>Identifier of the dataspace </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). + <dd>Returns the number of dimensions in the dataspace if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_type_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_ndims_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -692,50 +818,63 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_simple_extent_npoints" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a> +<dt><strong>Signature:</strong> + <dd><em>hssize_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. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_npoints_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sget_simple_extent_type" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentType">H5Sget_simple_extent_type</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> - ) + <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>Sets or resets the size of an existing dataspace. + <dd>Determine the current class of a 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. + <dd><code>H5Sget_simple_extent_type</code> queries a dataspace to determine the + current class of a 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. + 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. - <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. + <dd>Returns a dataspace class name if successful; + otherwise H5S_NO_CLASS (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_simple_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_type_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -743,7 +882,8 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sis_simple" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a> @@ -773,7 +913,8 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Soffset_simple" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-OffsetSimple">H5Soffset_simple</a> @@ -813,68 +954,34 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - -<!-- NOT YET IMPLEMENTED (R1.2 -- 9908) - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sselect_all" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentClass">H5Sextent_class</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectAll">H5Sselect_all</a> <dt><strong>Signature:</strong> - <dd><em>H5S_class_t</em> <code>H5Sextent_class</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>herr_t</em> <code>H5Sselect_all</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Determine the current class of a dataspace. + <dd>Selects the entire 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>. + <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>Dataspace identifier. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_class_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> -</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. + <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. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_copy_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_all_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -882,28 +989,79 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sselect_elements" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetExtentNone">H5Sset_extent_none</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sset_extent_none</code>(<em>hid_t</em> <code>space_id</code>) + <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>Removes the extent from a dataspace. + <dd>Selects array elements to be included in the selection for 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>. + <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: + <center> + <table width=90% 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><tr><td valign=top> + <code>H5S_SELECT_APPEND</code> + </td><td valign=top> + Adds the new selection following the last element of the existing selection. + </td></tr><tr><td valign=top> + <code>H5S_SELECT_PREPEND </code> + </td><td valign=top> + Adds the new selection preceding the first element of the existing selection. + </td></tr> + </table> + </center> +<!-- When operator <code>H5S_SELECT_OR</code> + is 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>The identifier for the dataspace from which - the extent is to be removed. + <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; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_none_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_elements_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -911,7 +1069,8 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sselect_hyperslab" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Dataspace-SelectHyperslab">H5Sselect_hyperslab</a> @@ -1047,29 +1206,29 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sselect_none" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperNBlocks">H5Sget_select_hyper_nblocks</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectNone">H5Sselect_none</a> <dt><strong>Signature:</strong> - <dd><em>hssize_t </em><code>H5Sget_select_hyper_nblocks</code>(<em>hid_t </em><code>space_id</code> - ) + <dd><em>herr_t</em> <code>H5Sselect_none</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Get number of hyperslab blocks. + <dd>Resets the selection region to include no elements. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_hyper_nblocks</code> returns the - number of hyperslab blocks in the current dataspace selection. + <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: Identifier of dataspace to query. + <dd>IN: The identifier for the dataspace in which the + selection is being reset. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of hyperslab blocks in - the current dataspace selection if successful. - Otherwise returns a negative value. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_nblocks_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_none_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1077,58 +1236,32 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sselect_valid" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperBlockList">H5Sget_select_hyper_blocklist</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectValid">H5Sselect_valid</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> - ) + <dd><em>htri_t</em> <code>H5Sselect_valid</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Gets the list of hyperslab blocks currently selected. + <dd>Verifies that the selection is within the extent of the dataspace. <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> - <"start" coordinate>, immediately followed by - <br> - <"opposite" corner coordinate>, followed by - <br> - the next "start" and "opposite" coordinates, - <br> - etc. - <br> - until all of the selected blocks have been listed. - <p> - No guarantee is implied as the order in which blocks are listed. + <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>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. + <dd>The identifier for the dataspace being queried. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <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. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_blocklist_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_valid_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1136,29 +1269,29 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sset_extent_none" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectElemNPoints">H5Sget_select_elem_npoints</a> +<dt><strong>Name:</strong> <a name="Dataspace-SetExtentNone">H5Sset_extent_none</a> <dt><strong>Signature:</strong> - <dd><em>hssize_t </em><code>H5Sget_select_elem_npoints</code>(<em>hid_t </em><code>space_id</code> - ) + <dd><em>herr_t</em> <code>H5Sset_extent_none</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Gets the number of element points in the current selection. + <dd>Removes the extent from a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_elem_npoints</code> returns - the number of element points in the current dataspace selection. + <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>IN: Identifier of dataspace to query. + <dd>The identifier for the dataspace from which + the extent is to be removed. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of element points in the current dataspace selection if successful. - Otherwise returns a negative value. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_npoints_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_none_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1166,57 +1299,51 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sset_extent_simple" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectElemPointList">H5Sget_select_elem_pointlist</a> +<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</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> + <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>Gets the list of element points currently selected. + <dd>Sets or resets the size of an existing dataspace. <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. + <dd><code>H5Sset_extent_simple</code> sets or resets the size of + an existing dataspace. <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> - <coordinate>, followed by - <br> - the next coordinate, - <br> - etc. - <br> - until all of the selected element points have been listed. + <code>rank</code> is the dimensionality, or number of + dimensions, of the dataspace. <p> - The points are returned in the order they will be iterated through - when the selection is read/written from/to disk. + <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>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. + <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 non-negative value if successful; + <dd>Returns a dataspace identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_pointlist_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_simple_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1225,62 +1352,38 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> +<!-- NOT YET IMPLEMENTED (R1.2 -- 9908) <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectBounds">H5Sget_select_bounds</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentClass">H5Sextent_class</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sget_select_bounds</code>(<em>hid_t </em><code>space_id</code>, - <em>hssize_t *</em><code>start</code>, - <em>hssize_t *</em><code>end</code> - ) + <dd><em>H5S_class_t</em> <code>H5Sextent_class</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Gets the bounding box containing the current selection. + <dd>Determine the current class of a dataspace. <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. + <dd><code>H5Sextent_class</code> queries a dataspace to determine the + current class of a dataspace. <p> - Calling this function on a <code>none</code> selection will - return <code>FAIL</code>. + 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>IN: Identifier of dataspace to query. - <dt><em>hssize_t *</em><code>start</code> - <dd>OUT: Starting coordinates of the bounding box. - <dt><em>hssize_t *</em><code>end</code> - <dd>OUT: Ending coordinates of the bounding box, - i.e., the coordinates of the diagonally opposite corner. + <dd>Dataspace identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. -<!-- + <dd>Returns a dataspace class name if successful; + otherwise H5S_NO_CLASS (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_bounds_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_class_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> ---> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> - --> </dl> - - - - +--> <!--<hr> @@ -1331,90 +1434,6 @@ of the <cite>HDF5 User's Guide.</cite>. --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetSelectType">H5Sget_select_type</a> -<dt><strong>Signature:</strong> - <dd><em>H5S_sel_type</em> <code>H5Sget_select_type</code>(<em>hid_t</em> <code>space_id</code>) -<dt><strong>Purpose:</strong> - <dd>Determines the type of the dataspace selection. -<dt><strong>Description:</strong> - <dd><code>H5Sget_select_type</code> retrieves the - type of selection currently defined for the dataspace - <code>space_id</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 the dataspace selection type, a value of - the enumerated datatype <code>H5S_sel_type</code>, - if successful. - Valid return values are as follows: - <center> - <table width=90% border=0> - <tr><td valign=top> - <code>H5S_SEL_NONE</code> - </td><td valign=top> - No selection is defined. - </td></tr><tr><td valign=top> - <code>H5S_SEL_POINTS</code> - </td><td valign=top> - A sequence of points is selected. - </td></tr><tr><td valign=top> - <code>H5S_SEL_HYPERSLABS</code> - </td><td valign=top> - A hyperslab or compound hyperslab is selected. - </td></tr><tr><td valign=top> - <code>H5S_SEL_ALL</code> - </td><td valign=top> - The entire dataset is selected. - </td></tr> - </table> - </center> - Otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_type_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</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. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sclose_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - - <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> <table border=0 width=98%> @@ -1448,14 +1467,15 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> +<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> Describes HDF5 Release 1.6.0, July 2003 -</address><!-- #EndLibraryItem --> - -Last modified: 10 June 2003 +</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT"> +<!-- +document.writeln("Last modified: 3 October 2003"); +--> +</SCRIPT> </body> </html> |