[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.

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>