[svn-r16763] Description:

    Added "Note:" documenting that raw dataset caching is not supported 
        with MPIO and MPI POSIX drivers in read/write mode, as discussed
        in Bugzilla entry 1344.
        -- Closes documentation aspect of Bugzilla entry 1344.
    Minor edits, added "Last modified" tag, and updated HTML.
Tested:  Firefox

3 files changed, 115 insertions, 62 deletions

diff --git a/doc/html/H5P/H5Pset_cache.htm b/doc/html/H5P/H5Pset_cache.htm
index 327fef4..d14d66d 100644
--- a/doc/html/H5P/H5Pset_cache.htm
+++ b/doc/html/H5P/H5Pset_cache.htm
@@ -2,16 +2,25 @@
 <!-- HEADER RIGHT "H5Pset_cache" -->
 <hr>
 <dl>
+  <dt><div align=right><font color=999999 size=-1><i>
+      Last modified: 15 April 2009
+      </i></font></div>
+
   <dt><strong>Name:</strong> <a name="Property-SetCache">H5Pset_cache</a>
   <dt><strong>Signature:</strong>
-    <dd><em>herr_t</em> <code>H5Pset_cache</code>(<em>hid_t</em> <code>plist_id</code>,
+    <dd><em>herr_t</em> <code>H5Pset_cache</code>(
+        <em>hid_t</em> <code>plist_id</code>,
         <em>int</em> <code>mdc_nelmts</code>,
         <em>size_t</em> <code>rdcc_nelmts</code>,
         <em>size_t</em> <code>rdcc_nbytes</code>,
         <em>double</em> <code>rdcc_w0</code>
     )
+ 
+  <p>
   <dt><strong>Purpose:</strong>
     <dd>Sets the meta data cache and raw data chunk cache parameters.  
+ 
+  <p>
   <dt><strong>Description:</strong>
     <dd><code>H5Pset_cache</code> sets 
         the number of elements (objects) in the meta data cache and 
@@ -34,30 +43,53 @@
         chunks are treated no differently than other chunks (the
         preemption is strictly LRU) while a value of one means fully
         read chunks are always preempted before other chunks. 
+ 
+  <p>
+  <dt><strong>Note:</strong>
+    <dd>Raw dataset chunk caching is not currently supported when using the 
+        MPI I/O and MPI POSIX file drivers in read/write mode; see
+        <a href="#Property-SetFaplMpio"><code>H5Pset_fapl_mpio</code></a> and
+        <a href="#Property-SetFaplMpiPosix"><code>H5Pset_fapl_mpiposix</code></a>,
+        respectively.  
+        When using one of these file drivers, all calls to <code>H5Dread</code> 
+        and <code>H5Dwrite</code> will access the disk directly, 
+        and <code>H5Pset_cache</code> will have no effect on performance.
+        <p>
+        Raw dataset chunk caching is supported when these drivers are 
+        used in read-only mode.
+ 
+  <p>
   <dt><strong>Parameters:</strong>
-    <ul><table>
+    <dd><table>
         <tr>
-		    <td valign="top"><em>hid_t</em> <code>plist_id</code></td>
-            <td valign="top">IN: Identifier of the file access property list.</td></tr>
+            <td valign="top"><em>hid_t</em> <code>plist_id</code></td>
+            <td valign="top">IN: Identifier of the file access property 
+                list.</td></tr>
         <tr>
-		    <td valign="top"><em>int</em> <code>mdc_nelmts</code></td>
+            <td valign="top"><em>int</em> <code>mdc_nelmts</code></td>
             <td valign="top">IN: Number of elements (objects) in the meta data cache.</td></tr>
         <tr>
-		    <td valign="top"><em>size_t</em> <code>rdcc_nelmts</code></td>
-            <td valign="top">IN: Number of elements (objects) in the raw data chunk cache.</td></tr>
+            <td valign="top"><em>size_t</em> <code>rdcc_nelmts</code></td>
+            <td valign="top">IN: Number of elements (objects) in the raw data 
+                chunk cache.</td></tr>
         <tr>
-		    <td valign="top"><em>size_t</em>&nbsp;<code>rdcc_nbytes&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
-            <td valign="top">IN: Total size of the raw data chunk cache, in bytes.</td></tr>
+            <td valign="top"><em>size_t</em>&nbsp;<code>rdcc_nbytes&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
+            <td valign="top">IN: Total size of the raw data chunk cache, 
+                in bytes.</td></tr>
         <tr>
-		    <td valign="top"><em>double</em> <code>rdcc_w0</code></td>
+            <td valign="top"><em>double</em> <code>rdcc_w0</code></td>
             <td valign="top">IN: Preemption policy.</td></tr>
-    </table></ul>
+        </table>
+ 
+  <p>
   <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful;
         otherwise returns a negative value.
+ 
+  <p>
   <dt><strong>Fortran90 Interface:</strong> h5pset_cache_f
     <dd>
-	<pre>
+        <pre>
 SUBROUTINE h5pset_cache_f(prp_id, mdc_nelmts,rdcc_nelmts, rdcc_nbytes, rdcc_w0, hdferr)
   IMPLICIT NONE
   INTEGER(HID_T), INTENT(IN) :: prp_id        ! Property list identifier
@@ -71,36 +103,24 @@ SUBROUTINE h5pset_cache_f(prp_id, mdc_nelmts,rdcc_nelmts, rdcc_nbytes, rdcc_w0,
   INTEGER, INTENT(OUT) :: hdferr              ! Error code
                                               ! 0 on success and -1 on failure
 END SUBROUTINE h5pset_cache_f
-	</pre>		
-		
-		<!--<dt><strong>Non-C API(s):</strong>
-    	<dd>
-        
-        <img src="Graphics/Java.gif"> 
-        <img src="Graphics/C++.gif">
-        -->
+        </pre> 
+
   <dt><strong>History:</strong>
     <ul><table width="90%">
         <tr>
-		  <td valign="top" align="left" width="10%">
-		    <strong>Release</strong>&nbsp;&nbsp;&nbsp;&nbsp;</td>
+          <td valign="top" align="left" width="10%">
+            <strong>Release</strong>&nbsp;&nbsp;&nbsp;&nbsp;</td>
           <td valign="top" align="left">
-		    <strong>C</strong></td>
-		  <td valign="top">&nbsp;&nbsp;&nbsp;&nbsp;</td>
-		  <td valign="top"><strong>Fortran90</strong></td></tr>
+            <strong>Change</strong></td></tr>
         <tr>
-		  <td valign="top">1.6.1</td>
-		  <td valign="top">&nbsp;</td>
-		  <td valign="top">&nbsp;</td>
-          <td valign="top"><code>rdcc_nbytes</code>&nbsp;parameter&nbsp;type&nbsp;changed&nbsp;
-		    to <code>INTEGER(SIZE_T)</code>.</td></tr>
+          <td valign="top">1.6.1</td>
+          <td valign="top">Fortran <code>rdcc_nbytes</code> parameter type 
+            changed to <code>INTEGER(SIZE_T)</code>.</td></tr>
         <tr>
-		  <td valign="top">1.6.0</td>
-		  <td valign="top">The <code>rdcc_nbytes</code>
-                    and <code>rdcc_nelmts</code> parameters changed 
-		    from type <em>int</em> to <em>size_t</em>.</td>
-		  <td valign="top">&nbsp;</td>
-          <td valign="top">&nbsp;</td></tr>
+          <td valign="top">1.6.0</td>
+          <td valign="top">In C, the <code>rdcc_nbytes</code> 
+            and <code>rdcc_nelmts</code> parameters changed from type 
+            <em>int</em> to <em>size_t</em>.</td></tr>
     </table></ul>
 </dl>
 
diff --git a/doc/html/H5P/H5Pset_fapl_mpio.htm b/doc/html/H5P/H5Pset_fapl_mpio.htm
index 4aaff02..03b7e84 100644
--- a/doc/html/H5P/H5Pset_fapl_mpio.htm
+++ b/doc/html/H5P/H5Pset_fapl_mpio.htm
@@ -2,6 +2,10 @@
 <!-- HEADER RIGHT "H5Pset_fapl_mpio" -->
 <hr>
 <dl>
+  <dt><div align=right><font color=999999 size=-1><i>
+      Last modified: 15 April 2009
+      </i></font></div>
+
   <dt><strong>Name:</strong> <a name="Property-SetFaplMpio">H5Pset_fapl_mpio</a>
   <dt><strong>Signature:</strong>
     <dd><em>herr_t</em> <code>H5Pset_fapl_mpio</code>(
@@ -9,9 +13,11 @@
                      <em>MPI_Comm</em> <code>comm</code>,
                      <em>MPI_Info</em> <code>info</code>
     )
+
   <p>
   <dt><strong>Purpose:</strong>
     <dd>Stores MPI IO communicator information to the file access property list.
+
   <p>
   <dt><strong>Description:</strong>
     <dd><code>H5Pset_fapl_mpio</code> stores the user-supplied 
@@ -37,9 +43,22 @@
         <p>
         If the file access property list already contains previously-set 
         comm and Info values, those values will be replaced. 
+ 
+  <p>
+  <dt><strong>Note:</strong>
+    <dd>Raw dataset chunk caching is not currently supported when using 
+        this file driver in read/write mode.  
+        All calls to <code>H5Dread</code> and <code>H5Dwrite</code> 
+        will access the disk directly, and 
+        <code>H5Pset_cache</code> and <code>H5Pset_chunk_cache</code> 
+        will have no effect on performance.
+        <p>
+        Raw dataset chunk caching is supported when this driver is 
+        used in read-only mode.
+ 
   <p>
   <dt><strong>Parameters:</strong>
-    <ul><table>
+    <dd><table>
         <tr>
             <td valign="top"><em>hid_t</em> <code>fapl_id</code></td>
             <td valign="top">IN: File access property list identifier</td></tr>
@@ -49,11 +68,13 @@
         <tr>
             <td valign="top"><em>MPI_Info</em> <code>info</code></td>
             <td valign="top">IN: MPI-2 info object</td></tr>
-    </table></ul>
+        </table>
+
   <p>
   <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful.
         Otherwise returns a negative value.
+
   <p>
   <dt><strong>Fortran90 Interface:</strong> h5pset_fapl_mpio_f
     <dd>
@@ -91,7 +112,7 @@ END SUBROUTINE h5pset_fapl_mpio_f
         <tr>
           <td valign="top">1.4.0</td>
           <td valign="top">
-    	    C function introduced in this release.</td></tr>
+            C function introduced in this release.</td></tr>
     </table></ul>
 </dl>
 
diff --git a/doc/html/H5P/H5Pset_fapl_mpiposix.htm b/doc/html/H5P/H5Pset_fapl_mpiposix.htm
index 759c1b4..94f6262 100644
--- a/doc/html/H5P/H5Pset_fapl_mpiposix.htm
+++ b/doc/html/H5P/H5Pset_fapl_mpiposix.htm
@@ -2,6 +2,10 @@
 <!-- HEADER RIGHT "H5Pset_fapl_mpiposix" -->
 <hr>
 <dl>
+  <dt><div align=right><font color=999999 size=-1><i>
+      Last modified: 15 April 2009
+      </i></font></div>
+ 
   <dt><strong>Name:</strong> <a name="Property-SetFaplMpiPosix">H5Pset_fapl_mpiposix</a>
   <dt><strong>Signature:</strong>
     <dd><em>herr_t</em> <code>H5Pset_fapl_mpiposix</code>(
@@ -9,8 +13,12 @@
                      <em>MPI_Comm</em> <code>comm</code>,
                      <em>hbool_t</em> <code>use_gpfs_hints</code>
     )
+ 
+  <p>
   <dt><strong>Purpose:</strong>
     <dd>Stores MPI IO communicator information to a file access property list.
+ 
+  <p>
   <dt><strong>Description:</strong>
     <dd><code>H5Pset_fapl_mpiposix</code> stores the user-supplied 
         MPI IO parameter <code>comm</code>, for communicator, 
@@ -42,8 +50,22 @@
         and may improve file access for some applications; 
         the user of a GPFS system is encouraged to experiment 
         by running an application with and without this parameter set.
+ 
+  <p>
+  <dt><strong>Note:</strong>
+    <dd>Raw dataset chunk caching is not currently supported when using 
+        this file driver in read/write mode.  
+        All calls to <code>H5Dread</code> and <code>H5Dwrite</code> 
+        will access the disk directly, and 
+        <code>H5Pset_cache</code> and <code>H5Pset_chunk_cache</code> 
+        will have no effect on performance.
+        <p>
+        Raw dataset chunk caching is supported when this driver is 
+        used in read-only mode.
+ 
+  <p>
   <dt><strong>Parameters:</strong>
-    <ul><table>
+    <dd><table>
         <tr>
             <td valign="top"><em>hid_t</em> <code>fapl_id</code></td>
             <td valign="top">IN: File access property list identifier.</td></tr>
@@ -51,15 +73,19 @@
             <td valign="top"><em>MPI_Comm</em>&nbsp;<code>comm</code></td>
             <td valign="top">IN: MPI-2 communicator.</td></tr>
         <tr>
-            <td valign="top"><em>hbool_t</em> <code>use_gpfs_hints&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
+            <td valign="top"><em>hbool_t</em>&nbsp;<code>use_gpfs_hints&nbsp;&nbsp;&nbsp;&nbsp;</code></td>
             <td valign="top">IN: Use of GPFS hints.</td></tr>
-    </table></ul>
+        </table>
+ 
+  <p>
   <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful.
         Otherwise returns a negative value.
+ 
+  <p>
   <dt><strong>Fortran90 Interface:</strong> h5pset_fapl_mpiposix_f
     <dd>
-	<pre>
+        <pre>
 SUBROUTINE h5pset_fapl_mpiposix_f(prp_id, comm, use_gpfs, hdferr)
   IMPLICIT NONE
   INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
@@ -69,28 +95,18 @@ SUBROUTINE h5pset_fapl_mpiposix_f(prp_id, comm, use_gpfs, hdferr)
   LOGICAL, INTENT(IN) :: use_gpfs
   INTEGER, INTENT(OUT) :: hdferr        ! Error code
 END SUBROUTINE h5pset_fapl_mpiposix_f
-	</pre>		
-		
-		<!--<dt><strong>Non-C API(s):</strong>
-    	<dd>
-        
-        <img src="Graphics/Java.gif"> 
-        <img src="Graphics/C++.gif">
-        -->
+        </pre>
+
+  <p>
   <dt><strong>History:</strong>
     <ul><table width="90%">
         <tr>
           <td valign="top" align="left" width="10%">
             <strong>Release</strong>&nbsp;&nbsp;&nbsp;&nbsp;</td>
           <td valign="top" align="left">
-            <strong>C</strong></td>
-          <td valign="top">&nbsp;&nbsp;&nbsp;&nbsp;</td>
-          <td valign="top" align="left">
-            <strong>Fortran90</strong></td></tr>
+            <strong>Change</strong></td>
         <tr>
           <td valign="top">1.6.1</td>
-          <td valign="top">&nbsp;</td>
-          <td valign="top">&nbsp;</td>
           <td valign="top">
             Fortran subroutine introduced in this release.
           </td></tr>
@@ -98,16 +114,12 @@ END SUBROUTINE h5pset_fapl_mpiposix_f
           <td valign="top">1.6.0</td>
           <td valign="top">
             <code>use_gpfs_hints</code> parameter added.</td>
-          <td valign="top">&nbsp;</td>
-          <td valign="top">&nbsp;</td>
         </tr>
         <tr>
           <td valign="top">1.6.0</td>
           <td valign="top">
-            Function introduced in this release.
+            C function introduced in this release.
         	</td>
-          <td valign="top">&nbsp;</td>
-          <td valign="top">&nbsp;</td>
         </tr>
     </table></ul>
 </dl>