summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>2001-10-08 15:40:56 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>2001-10-08 15:40:56 (GMT)
commita237041a909d877fe4d3205d52944f146a9c2cb8 (patch)
treeee13371299207c4e96cf2346a4b682ae246f8ea1
parent841fe928ac257cd4e5bc21307487b31d11b4e173 (diff)
downloadhdf5-a237041a909d877fe4d3205d52944f146a9c2cb8.zip
hdf5-a237041a909d877fe4d3205d52944f146a9c2cb8.tar.gz
hdf5-a237041a909d877fe4d3205d52944f146a9c2cb8.tar.bz2
[svn-r4531] Purpose:
Update docs Description: H5Dread and H5Dwrite description contained some inaccurate information about how H5S_ALL works as a parameter for the memory and file dataspaces. Solution: Updated information to reflect current library behavior for H5S_ALL.
-rw-r--r--doc/html/RM_H5D.html233
1 files changed, 206 insertions, 27 deletions
diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html
index 720629c..615bff7 100644
--- a/doc/html/RM_H5D.html
+++ b/doc/html/RM_H5D.html
@@ -463,13 +463,13 @@ facilitate moving easily between them.</i>
<em>void *</em> <code>buf</code>
)
<dt><strong>Purpose:</strong>
- <dd>Reads raw data from the specified dataset into <code>buf</code>,
- converting from file datatype and dataspace to
- memory datatype and dataspace.
+ <dd>Reads raw data from the specified dataset into an application buffer <code>buf</code>,
+ converting from
+ file datatype and dataspace to memory datatype and dataspace.
<dt><strong>Description:</strong>
<dd><code>H5Dread</code> reads a (partial) dataset, specified by its
- identifier <code>dataset_id</code>, from the file into the
- application memory buffer <code>buf</code>.
+ identifier <code>dataset_id</code>, from the
+ file info an application memory buffer <code>buf</code>.
Data transfer properties are defined by the argument
<code>xfer_plist_id</code>.
The memory datatype of the (partial) dataset is identified by
@@ -477,21 +477,110 @@ facilitate moving easily between them.</i>
The part of the dataset to read is defined by
<code>mem_space_id</code> and <code>file_space_id</code>.
<p>
- <code>file_space_id</code> can be the constant <code>H5S_ALL</code>,
- which indicates that the entire file data space is to be referenced.
+ <code>file_space_id</code> is used to specify only the selection within
+ the file dataset's dataspace. Any dataspace specified in <code>file_space_id</code>
+ is ignored by the library and the dataset's dataspace is always used.
+ <code>file_space_id</code> can be the constant <code>H5S_ALL</code>.
+ which indicates that the entire file dataspace, as defined by the
+ current dimensions of the dataset, is to be selected.
+ <p>
+ <code>mem_space_id</code> is used to specify both the memory dataspace
+ and the selection within that dataspace.
+ <code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
+ in which case the file dataspace is used for the memory dataspace and
+ the selection defined with <code>file_space_id</code> is used for the
+ selection within that dataspace.
<p>
- <code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
- in which case the memory data space is the same as the file data space
- defined when the dataset was created.
+ The behavior of the library for the various combinations of valid
+ dataspace IDs and H5S_ALL for the <code>mem_space_id</code> and the
+ <code>file_space_id</code> parameters is described below:
+
+ <br><br>
+ <table border=1>
+ <tr>
+ <th>
+ <code>mem_space_id</code>
+ </th>
+ <th>
+ <code>file_space_id</code>
+ </th>
+ <th>
+ Behavior
+ </th>
+ </tr>
+ <tr>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ <code>mem_space_id</code> specifies the memory dataspace and the
+ selection within it.
+ <code>file_space_id</code> specifies the selection within the file
+ dataset's dataspace.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ The file dataset's dataspace is used for the memory dataspace and the
+ selection specified with <code>file_space_id</code> specifies the
+ selection within it.
+ <code>file_space_id</code> specifies the selection within the file
+ dataset's dataspace.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ <code>mem_space_id</code> specifies the memory dataspace and the
+ selection within it.
+ The selection within the file dataset's dataspace is set to the "all"
+ selection.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ The file dataset's dataspace is used for the memory dataspace and the
+ selection within the memory dataspace is set to the "all" selection.
+ The selection within the file dataset's dataspace is set to the "all"
+ selection.
+ </td>
+ </tr>
+
+ </table>
+
<p>
- The number of elements in the memory data space must match
- the number of elements in the file data space.
+ Setting an "all" selection indicates that the entire dataspace, as
+ defined by the current dimensions of a dataspace, will be selected.
+ The number of elements selected in the memory dataspace must match the
+ number of elements selected in the file dataspace.
<p>
- <code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>,
- in which case the default data transfer properties are used.
-
+ <code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>.
+ in which case the default data transfer properties are used.
<p>
- Datatype conversion takes place at the time of a read or write
+ Datatype conversion takes place at the time of the read
and is automatic. See the
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
section of <cite>The Data Type Interface (H5T)</cite> in the
@@ -511,7 +600,7 @@ facilitate moving easily between them.</i>
<dt><em>hid_t</em> <code>xfer_plist_id</code>
<dd>Identifier of a transfer property list for this I/O operation.
<dt><em>void *</em> <code>buf</code>
- <dd>Buffer to store data read from the file.
+ <dd>Buffer to receive data read from file.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
@@ -526,6 +615,7 @@ facilitate moving easily between them.</i>
</dl>
+
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataset-Write">H5Dwrite</a>
@@ -552,23 +642,113 @@ facilitate moving easily between them.</i>
The part of the dataset to write is defined by
<code>mem_space_id</code> and <code>file_space_id</code>.
<p>
+ <code>file_space_id</code> is used to specify only the selection within
+ the file dataset's dataspace. Any dataspace specified in <code>file_space_id</code>
+ is ignored by the library and the dataset's dataspace is always used.
<code>file_space_id</code> can be the constant <code>H5S_ALL</code>.
- which indicates that the entire file data space is to be referenced.
+ which indicates that the entire file dataspace, as defined by the
+ current dimensions of the dataset, is to be selected.
<p>
+ <code>mem_space_id</code> is used to specify both the memory dataspace
+ and the selection within that dataspace.
<code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
- in which case the memory data space is the same as the file data space
- defined when the dataset was created.
+ in which case the file dataspace is used for the memory dataspace and
+ the selection defined with <code>file_space_id</code> is used for the
+ selection within that dataspace.
+ <p>
+ The behavior of the library for the various combinations of valid
+ dataspace IDs and H5S_ALL for the <code>mem_space_id</code> and the
+ <code>file_space_id</code> parameters is described below:
+
+ <br><br>
+ <table border=1>
+ <tr>
+ <th>
+ <code>mem_space_id</code>
+ </th>
+ <th>
+ <code>file_space_id</code>
+ </th>
+ <th>
+ Behavior
+ </th>
+ </tr>
+ <tr>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ <code>mem_space_id</code> specifies the memory dataspace and the
+ selection within it.
+ <code>file_space_id</code> specifies the selection within the file
+ dataset's dataspace.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ The file dataset's dataspace is used for the memory dataspace and the
+ selection specified with <code>file_space_id</code> specifies the
+ selection within it.
+ <code>file_space_id</code> specifies the selection within the file
+ dataset's dataspace.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ valid dataspace ID
+ </td>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ <code>mem_space_id</code> specifies the memory dataspace and the
+ selection within it.
+ The selection within the file dataset's dataspace is set to the "all"
+ selection.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ H5S_ALL
+ </td>
+ <td>
+ The file dataset's dataspace is used for the memory dataspace and the
+ selection within the memory dataspace is set to the "all" selection.
+ The selection within the file dataset's dataspace is set to the "all"
+ selection.
+ </td>
+ </tr>
+
+ </table>
+
<p>
- The number of elements in the memory data space must match
- the number of elements in the file data space.
+ Setting an "all" selection indicates that the entire dataspace, as
+ defined by the current dimensions of a dataspace, will be selected.
+ The number of elements selected in the memory dataspace must match the
+ number of elements selected in the file dataspace.
<p>
<code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>.
in which case the default data transfer properties are used.
<p>
- Writing to an external dataset will fail if the HDF5 file is
- not open for writing.
+ Writing to an dataset will fail if the HDF5 file was
+ not opened with write access permissions.
<p>
- Datatype conversion takes place at the time of a read or write
+ Datatype conversion takes place at the time of the write
and is automatic. See the
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
section of <cite>The Data Type Interface (H5T)</cite> in the
@@ -578,7 +758,7 @@ facilitate moving easily between them.</i>
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>dataset_id</code>
- <dd>Identifier of the dataset read from.
+ <dd>Identifier of the dataset to write to.
<dt><em>hid_t</em> <code>mem_type_id</code>
<dd>Identifier of the memory datatype.
<dt><em>hid_t</em> <code>mem_space_id</code>
@@ -602,7 +782,6 @@ facilitate moving easily between them.</i>
-->
</dl>
-
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a>