[svn-r8590] Purpose:

    Code optimization & bug fix

Description:
    When dimension information is being stored in the storage layout message
on disk, it is stored as 32-bit quantities, possibly truncating the dimension
information, if a dimension is greater than 32-bits in size.

Solution:
    Fix the storage layout message problem by revising file format to not store
dimension information, since it is already available in the dataspace.

    Also revise the storage layout data structures to be more compartmentalized
for the information for contiguous, chunked and compact storage.

Platforms tested:
    FreeBSD 4.9 (sleipnir) w/parallel
    Solaris 2.7 (arabica)
    h5committest

1 files changed, 233 insertions, 17 deletions

diff --git a/doc/html/H5.format.html b/doc/html/H5.format.html
index 1868138..ae1ff23 100644
--- a/doc/html/H5.format.html
+++ b/doc/html/H5.format.html
@@ -130,8 +130,7 @@ TABLE.list TD { border:none; }
 	      <li><a href="#AttributeMessage">Name: Attribute</a>                                           <!-- 0x000c -->
 	      <li><a href="#CommentMessage">Name: Object Comment</a>                                              <!-- 0x000d -->
 	      <li><a href="#OldModifiedMessage">Name: Object Modification Date and Time (Old)</a>           <!-- 0x000e -->
-<!--	      <li><a href="#SharedMessage">Name: Shared Object Message</a> -->                              <!-- 0x000f -->
-	      <li><a href="#ReservedMessage_000F">Name: Reserved - not assigned yet</a>                     <!-- 0x000f -->
+              <li><a href="#SharedMessage">Name: Shared Object Message</a>                                  <!-- 0x000f -->
 	      <li><a href="#ContinuationMessage">Name: Object Header Continuation</a>                       <!-- 0x0010 -->
 	      <li><a href="#SymbolTableMessage">Name: Group Message</a>                                     <!-- 0x0011 -->
 	      <li><a href="#ModifiedMessage">Name: Object Modification Date and Time</a>                    <!-- 0x0012 -->
@@ -4729,14 +4728,17 @@ TABLE.list TD { border:none; }
 	addresses.
 
       <li>The array can be stored in one contiguous block, as part of
-        this object header message.
+        this object header message (this is called "compact" storage below).
     </ol>
+    
+    <P>Version 3 of this message re-structured the format into specific
+        properties that are required for each layout class.
 
     <p>
     <center>
       <table border cellpadding=4 width="80%">
 	<caption align=top>
-	  <B>Data Layout Message</B>
+	  <B>Data Layout Message, Versions 1 and 2</B>
 	</caption>
 
 	<tr align=center>
@@ -4850,6 +4852,233 @@ TABLE.list TD { border:none; }
       </table>
     </center>
 
+    <p>
+    <center>
+      <table border cellpadding=4 width="80%">
+	<caption align=top>
+	  <B>Data Layout Message, Version 3</B>
+	</caption>
+
+	<tr align=center>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	</tr>
+
+	<tr align=center>
+	  <td>Version</td>
+	  <td>Layout Class</td>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=4>Properties</td>
+	</tr>
+
+      </table>
+    </center>
+
+    <p>
+    <center>
+      <table align=center width="80%">
+	<tr align=left>
+          <th width="30%"><U><font size=+1>Field Name</font></U></th>
+          <th><U><font size=+1>Description</font></U></th>
+	</tr>
+
+	<tr valign=top>
+	  <td>Version</td>
+	  <td>A version number for the layout message. This value can be
+            either 1, 2 or 3.</td>
+	</tr>
+
+	<tr valign=top>
+	  <td>Layout Class</td>
+	  <td>The layout class specifies how the other fields of the
+	    layout message are to be interpreted.  A value of one
+	    indicates contiguous storage, a value of two
+	    indicates chunked storage,
+	    while a value of three
+	    indicates compact storage.</td>
+	</tr>
+
+	<tr valign=top>
+	  <td>Properties</td>
+	  <td>This variable-sized field encodes information specific to each
+            layout class and is described below.  If there is no property
+            information specified for a layout class, the size of this field
+            is zero bytes.</td>
+	</tr>
+
+      </table>
+    </center>
+
+    <P>Class-specific information for contiguous layout (Class 0):
+
+    <p>
+    <center>
+      <table border cellpadding=4 width="80%">
+	<caption align=top>
+	  <B>Property Descriptions</B>
+	</caption>
+
+	<tr align=center>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=4><br>Address<br><br></td>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=4><br>Size<br><br></td>
+	</tr>
+      </table>
+    </center>
+
+    <p>
+    <center>
+      <table align=center width="80%">
+	<tr align=left>
+          <th width="30%"><U><font size=+1>Field Name</font></U></th>
+          <th><U><font size=+1>Description</font></U></th>
+	</tr>
+
+	<tr valign=top>
+	  <td>Address</td>
+	  <td>This is the address of the first byte of raw data storage.
+            The address may have the "undefined address" value, to indicate
+            that storage has not yet been allocated for this array.</td>
+	</tr>
+
+	<tr valign=top>
+	  <td>Size</td>
+	  <td>This field contains the size allocated to store the raw data.</td>
+      </table>
+    </center>
+
+    <P>Class-specific information for chunked layout (Class 1):
+
+    <p>
+    <center>
+      <table border cellpadding=4 width="80%">
+	<caption align=top>
+	  <B>Property Descriptions</B>
+	</caption>
+
+	<tr align=center>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	</tr>
+
+	<tr align=center>
+	  <td>Dimensionality</td>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=4><br>Address<br><br></td>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=4>Dimension 0 (4-bytes)</td>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=4>Dimension 1 (4-bytes)</td>
+	</tr>
+	
+	<tr align=center>
+	  <td colspan=4>...</td>
+	</tr>
+      </table>
+    </center>
+
+    <p>
+    <center>
+      <table align=center width="80%">
+	<tr align=left>
+          <th width="30%"><U><font size=+1>Field Name</font></U></th>
+          <th><U><font size=+1>Description</font></U></th>
+	</tr>
+
+	<tr valign=top>
+	  <td>Dimensionality</td>
+	  <td>A chunk has a fixed dimensionality.  This field
+	    specifies the number of dimension size fields later in the
+	    message.</td>
+	</tr>
+
+	<tr valign=top>
+	  <td>Address</td>
+	  <td>This is the address
+	    of the B-tree that is used to look up the addresses of the
+	    chunks.
+            The address
+            may have the "undefined address" value, to indicate that
+            storage has not yet been allocated for this array.</td>
+	</tr>
+
+	<tr valign=top>
+	  <td>Dimensions</td>
+	  <td>The dimension sizes define the size of a single chunk.</td>
+	</tr>
+      </table>
+    </center>
+
+    <P>Class-specific information for compact layout (Class 2):
+
+    <p>
+    <center>
+      <table border cellpadding=4 width="80%">
+	<caption align=top>
+	  <B>Property Descriptions</B>
+	</caption>
+
+	<tr align=center>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	  <th width="25%">byte</th>
+	</tr>
+
+	<tr align=center>
+	  <td colspan=2>Size</td>
+	</tr>
+	
+	<tr align=center>
+	  <td colspan=4>Raw Data</td>
+	</tr>
+	
+	<tr align=center>
+	  <td colspan=4>...</td>
+	</tr>
+      </table>
+    </center>
+
+    <p>
+    <center>
+      <table align=center width="80%">
+	<tr align=left>
+          <th width="30%"><U><font size=+1>Field Name</font></U></th>
+          <th><U><font size=+1>Description</font></U></th>
+	</tr>
+
+	<tr valign=top>
+	  <td>Size</td>
+	  <td>This field contains the size of the raw data for the dataset array.</td>
+
+	<tr valign=top>
+	  <td>Raw Data</td>
+	  <td>This field contains the raw data for the dataset array.</td>
+	</tr>
+      </table>
+    </center>
+
 
     <hr>
     <h4><a name="ReservedMessage_0009">Name: Reserved - Not Assigned Yet</a></h4>
@@ -5348,7 +5577,6 @@ TABLE.list TD { border:none; }
       </table>
     </center>
     
-<!--
     <hr>
     <h4><a name="SharedMessage">Name: Shared Object Message</a></h4>
     <b>Header Message Type:</b> 0x000F<br>
@@ -5444,20 +5672,8 @@ TABLE.list TD { border:none; }
 	</tr>
       </table>
     </center>
--->
 
 
-    <hr>
-    <h4><a name="ReservedMessage_000F">Name: Reserved - Not Assigned Yet</a></h4>
-    <b>Header Message Type:</b> 0x000F<BR>
-    <b>Length:</b> N/A<BR>
-    <b>Status:</b> N/A<BR>
-    <b>Format of Data:</b> N/A<BR>
-
-    <p><b>Purpose and Description:</b> This message type was skipped during
-      the initial specification of the file format and may be used in a
-      future expansion to the format.
-
 <hr>
 <h4><a name="ContinuationMessage">Name: Object Header Continuation</a></h4>
 <b>Header Message Type:</b> 0x0010<BR>