From c5f5f1f5343a4ccf061b685ff493110c4f9d73f2 Mon Sep 17 00:00:00 2001
From: Frank Baker <fbaker@hdfgroup.org>
Date: Wed, 2 Apr 2003 14:08:38 -0500
Subject: [svn-r6566] Purpose:     New feature -- Fill value and storage space
 allocation changes Description:     Added H5Dget_space_status     Modified
 H5Dcreate and H5Dread to discuss     Also, copy and readability edits in
 H5Dcreate, H5Dread, and H5Dwrite Platforms tested:     IE 6, Safari

---
 doc/html/RM_H5D.html | 171 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 129 insertions(+), 42 deletions(-)

diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html
index e51d439..37b869c 100644
--- a/doc/html/RM_H5D.html
+++ b/doc/html/RM_H5D.html
@@ -61,10 +61,11 @@ and set and retrieve their constant or persistent properties.
     <li><a href="#Dataset-Open">H5Dopen</a>
     <li><a href="#Dataset-Close">H5Dclose</a>
     <li><a href="#Dataset-GetSpace">H5Dget_space</a>
-    <li><a href="#Dataset-GetType">H5Dget_type</a>
+    <li><a href="#Dataset-GetSpaceStatus">H5Dget_space_status</a>
 </ul>
 </td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
 <ul>
+    <li><a href="#Dataset-GetType">H5Dget_type</a>
     <li><a href="#Dataset-GetCreatePlist">H5Dget_create_plist</a>
     <li><a href="#Dataset-GetStorageSize">H5Dget_storage_size</a>
     <li><a href="#Dataset-VLGetBuf">H5Dvlen_get_buf_size</a>
@@ -159,10 +160,19 @@ facilitate moving easily between them.</i>
         <code>create_plist_id</code> is a <code>H5P_DATASET_CREATE</code>
         property list created with <code>H5Pcreate</code> and
         initialized with the various functions described above.
+	<p>
+	<code>H5Dcreate</code> returns an error if the dataset's datatype 
+	includes a variable-length (VL) datatype and the fill value 
+	is undefined, i.e., set to <code>NULL</code> in the 
+	dataset creation property list. 
+	Such a VL datatype may be directly included,  
+	indirectly included as part of a compound or array datatype, or 
+	indirectly included as part of a nested compound or array datatype.
+	<p>
         <code>H5Dcreate</code> returns a dataset identifier for success
-        or negative for failure. The identifier should eventually be
-        closed by calling <code>H5Dclose</code> to release resources
-        it uses.
+        or a negative value for failure. 
+	The dataset identifier should eventually be closed by 
+        calling <code>H5Dclose</code> to release resources it uses.
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>loc_id</code>
@@ -259,6 +269,60 @@ facilitate moving easily between them.</i>
 
 <hr>
 <dl>
+<dt><strong>Name:</strong> <a name="Dataset-GetSpaceStatus">H5Dget_space_status</a>
+<dt><strong>Signature:</strong>
+    <dd><em>hid_t</em> <code>H5Dget_space_status</code>(<em>hid_t </em><code>dset_id</code>,
+                        <em>H5D_space_status_t *</em><code>status</code>)
+<dt><strong>Purpose:</strong>
+    <dd>Determines whether space has been allocated for a dataset.
+<dt><strong>Description:</strong>
+    <dd><code>H5Dget_space_status</code> determines whether space has been 
+        allocated for the dataset <code>dset_id</code>.
+	<p>
+        Space allocation status is returned in <code>status</code>,
+        which will have one of the following values:
+        <center>
+	<table border="0">
+          <tr valign="top"><td rowspan="3">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+            H5D_SPACE_STATUS_NOT_ALLOCATED
+	    </td><td>
+            Space has not been allocated for this dataset.
+          </td></tr><tr valign="top"><td>
+            H5D_SPACE_STATUS_ALLOCATED
+	    </td><td>
+            Space has been allocated for this dataset.
+          </td></tr><tr valign="top"><td>
+            H5D_SPACE_STATUS_PART_ALLOCATED&nbsp;&nbsp;
+	    </td><td>
+            Space has been partially allocated for this dataset.  
+	    (Used only for datasets with chunked storage.)
+          </td></tr>
+        </table>
+	</center>
+<dt><strong>Parameters:</strong>
+    <dl>
+        <dt><em>hid_t</em> <code>dset_id</code>
+            <dd>IN: Identifier of the dataset to query.
+        <dt><em>H5D_space_status_t *</em><code>status</code>
+            <dd>OUT: Space allocatioin status.
+    </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/h5d_FORTRAN.html#h5dget_space_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="Dataset-GetType">H5Dget_type</a>
 <dt><strong>Signature:</strong>
     <dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code>
@@ -468,13 +532,11 @@ 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 an application buffer <code>buf</code>,
-        converting from 
-        file datatype and dataspace to memory datatype and dataspace.
+    <dd>Reads raw data from a dataset into a buffer.
 <dt><strong>Description:</strong>
     <dd><code>H5Dread</code> reads a (partial) dataset, specified by its
         identifier <code>dataset_id</code>, from the 
-        file info an application memory buffer <code>buf</code>.
+        file into 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 
@@ -496,29 +558,34 @@ facilitate moving easily between them.</i>
         the selection defined with <code>file_space_id</code> is used for the
         selection within that dataspace.
         <p>
+	If raw data storage space has not been allocated for the dataset 
+	and a fill value has been defined, the returned buffer <code>buf</code> 
+	is filled with the fill value. 
+        <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
+        dataspace identifiers 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>
+        <table border=0>
         <tr>
         <th>
-        <code>mem_space_id</code>
+        <code>mem_space_id&nbsp;&nbsp;</code>
         </th>
         <th>
-        <code>file_space_id</code>
+        <code>file_space_id&nbsp;&nbsp;</code>
         </th>
         <th>
         Behavior
         </th>
         </tr>
-        <tr>
+	
+        <tr valign="top">
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
         <code>mem_space_id</code> specifies the memory dataspace and the
@@ -528,12 +595,12 @@ facilitate moving easily between them.</i>
         </td>
         </tr>
 
-        <tr>
+        <tr valign="top">
         <td>
         H5S_ALL
         </td>
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
         The file dataset's dataspace is used for the memory dataspace and the
@@ -544,9 +611,9 @@ facilitate moving easily between them.</i>
         </td>
         </tr>
 
-        <tr>
+        <tr valign="top">
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
         H5S_ALL
@@ -559,7 +626,7 @@ facilitate moving easily between them.</i>
         </td>
         </tr>
 
-        <tr>
+        <tr valign="top">
         <td>
         H5S_ALL
         </td>
@@ -585,8 +652,9 @@ facilitate moving easily between them.</i>
         <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 the read
-        and is automatic.  See the
+	Data is automatically converted from the file datatype 
+        and dataspace to the memory datatype and dataspace
+	at the time of the write.  See the
         <a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a> 
         section of <cite>The Data Type Interface (H5T)</cite> in the 
         <cite>HDF5 User's Guide</cite> for a discussion of 
@@ -634,9 +702,7 @@ facilitate moving easily between them.</i>
         <em>const void *</em> <code>buf</code>
     )
 <dt><strong>Purpose:</strong>
-    <dd>Writes raw data from an application buffer <code>buf</code> to 
-        the specified dataset, converting from 
-        memory datatype and dataspace to file datatype and dataspace.
+    <dd>Writes raw data from a buffer to a dataset.
 <dt><strong>Description:</strong>
     <dd><code>H5Dwrite</code> writes a (partial) dataset, specified by its
         identifier <code>dataset_id</code>, from the 
@@ -667,24 +733,25 @@ facilitate moving easily between them.</i>
         <code>file_space_id</code> parameters is described below:
 
         <br><br>
-        <table border=1>
+        <table border=0>
         <tr>
         <th>
-        <code>mem_space_id</code>
+        <code>mem_space_id&nbsp;&nbsp;</code>
         </th>
         <th>
-        <code>file_space_id</code>
+        <code>file_space_id&nbsp;&nbsp;</code>
         </th>
         <th>
         Behavior
         </th>
         </tr>
-        <tr>
+	
+        <tr valign="top">
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
         <code>mem_space_id</code> specifies the memory dataspace and the
@@ -694,12 +761,12 @@ facilitate moving easily between them.</i>
         </td>
         </tr>
 
-        <tr>
+        <tr valign="top">
         <td>
         H5S_ALL
         </td>
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
         The file dataset's dataspace is used for the memory dataspace and the
@@ -710,9 +777,9 @@ facilitate moving easily between them.</i>
         </td>
         </tr>
 
-        <tr>
+        <tr valign="top">
         <td>
-        valid dataspace ID
+        valid dataspace identifier
         </td>
         <td>
         H5S_ALL
@@ -725,7 +792,7 @@ facilitate moving easily between them.</i>
         </td>
         </tr>
 
-        <tr>
+        <tr valign="top">
         <td>
         H5S_ALL
         </td>
@@ -754,8 +821,9 @@ facilitate moving easily between them.</i>
         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 the write
-        and is automatic.  See the
+        Data is automatically converted from the memory datatype 
+        and dataspace to the file datatype and dataspace
+	at the time of the write.  See the
         <a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a> 
         section of <cite>The Data Type Interface (H5T)</cite> in the 
         <cite>HDF5 User's Guide</cite> for a discussion of 
@@ -926,16 +994,35 @@ facilitate moving easily between them.</i>
 <dt><strong>Purpose:</strong>
     <dd>Fills dataspace elements with a fill value in a memory buffer.
 <dt><strong>Description:</strong>
-    <dd><code>H5Dfill</code> explicitly fills a dataspace selection 
-        in memory with the fill value specified in <code>fill</code>.
-        <p>
+    <dd><code>H5Dfill</code> explicitly fills 
+        the dataspace selection in memory, <code>space_id</code>, 
+        with the fill value specified in <code>fill</code>.
         If <code>fill</code> is <code>NULL</code>, 
         a fill value of <code>0</code> (zero) is used.
         <p>
+	<code>fill_type_id</code> specifies the datatype 
+	of the fill value.<br>
+	<code>buf</code> specifies the buffer in which 
+	the dataspace elements will be written.<br>
+	<code>buf_type_id</code> specifies the datatype of 
+	those data elements.
+	<p>
         Note that if the fill value datatype differs 
         from the memory buffer datatype, the fill value 
         will be converted to the memory buffer datatype 
         before filling the selection.
+<dt><strong>Note:</strong>
+    <dd>Applications sometimes write data only to portions of 
+	an allcoated dataset.  It is often useful in such cases 
+	to fill the unused space with a known 
+	<span class="termEmphasis">fill value</span>.  
+	See <a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a>
+	for further discussion.  
+	Related functions include
+	<a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a>,
+	<a href="RM_H5P.html#Property-GetFillValue">H5Pget_fill_value</a>,
+	and
+	<a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>.
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>const void *</em><code>fill</code>
@@ -1005,7 +1092,7 @@ And in this document, the
 Describes HDF5 Release 1.5, Unreleased Development Branch
 </address><!-- #EndLibraryItem -->
  
-Last modified: 19 April 2002
+Last modified: 28 March 2003
  
 </body>
 </html>
-- 
cgit v0.12