[svn-r3381]

Purpose:
    Added array datatype class section.
Platforms tested:
    IE 5

1 files changed, 216 insertions, 4 deletions

diff --git a/doc/html/Datatypes.html b/doc/html/Datatypes.html
index d7ab7a2..88d8d05 100644
--- a/doc/html/Datatypes.html
+++ b/doc/html/Datatypes.html
@@ -651,6 +651,7 @@
       <code>H5Tinsert()</code>) and cannot be subsequently modified.
       This makes it imposible to define recursive data structures.
 
+
     <a name="DTypes-PredefinedAtomic">
     <h2>6. Predefined Atomic Datatypes</h2>
     </a>
@@ -2429,7 +2430,215 @@ in the HDF5 distribution.
 
 
 
-    <h2>10. Sharing Datatypes among Datasets</h2>
+<h2>10. Array Datatypes</h2>
+
+The array class of datatypes, <code>H5T_ARRAY</code>, allows the 
+construction of true, homogeneous, multi-dimensional arrays.  
+Since these are homogeneous arrays, each element of the array will be 
+of the same datatype, designated at the time the array is created.
+
+<p>
+Arrays can be nested.
+Not only is an array datatype used as an element of an HDF5 dataset,
+but the elements of an array datatype may be of any datatype, 
+including another array datatype.
+
+<p>
+Array datatypes cannot be subdivided for I/O; the entire array must 
+be transferred from one dataset to another. 
+
+<p>
+Within the limitations outlined in the next paragraph, array datatypes 
+may be <em>N</em>-dimensional and of any dimension size.  
+Unlimited dimensions, however, are not supported. 
+Functionality similar to unlimited dimension arrays is available through 
+the use of variable-length datatypes.
+
+<p>
+The maximum number of dimensions, i.e., the maximum rank, of an array
+datatype is specified by the HDF5 library constant <code>H5S_MAX_RANK</code>.
+The minimum rank is 1 (one).
+All dimension sizes must be greater than 0 (zero). 
+
+<p>
+One array dataype may only be converted to another array datatype 
+if the number of dimensions and the sizes of the dimensions are equal 
+and the datatype of the first array's elements can be converted 
+to the datatype of the second array's elements.
+
+<h3>10.1 Array Datatype APIs</h2>
+
+The functions for creating and manipulating array datadypes are 
+as follows:
+
+<dir>
+<table>
+    <tr>
+        <td><code><b>H5Tarray_create</b></code>
+        </td><td>&nbsp;&nbsp;
+        </td><td>Creates an array datatype.
+        </td></tr><tr><td colspan=3><dir>
+            <em>hid_t</em> <code>H5Tarray_create</code>(
+                       <em>hid_t</em> <code>base</code>,
+                       <em>int</em> <code>rank</code>,
+                       <em>const hsize_t</em> <code>dims[/*rank*/]</code>,
+                       <em>const int</em> <code>perm[/*rank*/]</code>
+            )
+        </dir>
+    </td></tr><tr>
+        <td><code><b>H5Tget_array_ndims</b></code>
+        </td><td>&nbsp;&nbsp;
+        </td><td>Retrieves the rank of the array datatype.
+        </td></tr><tr><td colspan=3><dir>
+            <em>int</em> <code>H5Tget_array_ndims</code>(
+                       <em>hid_t</em> <code>adtype_id</code>
+            )
+        </dir>
+    </td></tr><tr>
+        <td><code><b>H5Tget_array_dims</b></code>
+        </td><td>&nbsp;&nbsp;
+        </td><td>Retrieves the dimension sizes of the array datatype.
+        </td></tr><tr><td colspan=3><dir>
+            <em>int</em> <code>H5Tget_array_dims</code>(
+                       <em>hid_t</em> <code>adtype_id</code>,
+                       <em>hsize_t *</em><code>dims[]</code>,
+                       <em>int *</em><code>perm[]</code>
+            )
+        </dir>
+    </td></tr>
+</table>
+</dir>
+
+
+<h3>10.2 Transition Issues in Adapting Existing Software<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+(Transition to HDF5 Release 1.4 Only)</h3>
+
+The array datatype class is new with Release 1.4;  
+prior releases included an array element for compound datatypes.
+<p>
+The use of the array datatype class will not interfere with the 
+use of existing compound datatypes.  Applications may continue to 
+read and write the older field arrays, but they will no longer be 
+able to create array fields in newly-defined compound datatypes.
+<p>
+Existing array fields will be transparently mapped to array datatypes
+when they are read in.
+
+
+<h3>10.3 Code Example</h3>
+
+The following example creates an array datatype and creates and writes 
+a dataset to the HDF5 file.  The elements of the dataset have the 
+array datatype.
+
+<center>
+<table border align=center width="100%">
+  <caption align=bottom><h4>Example: Array Datatype</h4></caption>
+  <tr>
+    <td>
+      <pre>
+/*  
+ *  This example creates and writes dataset to the HDF5 file.
+ *  Elements of the datasets have an array datatype.
+ */
+ 
+#include <hdf5.h>
+
+#define FILE        "SDS_array_type.h5"
+#define DATASETNAME "IntArray" 
+#define ARRAY_DIM1     5                      /* array dimensions and rank */
+#define ARRAY_DIM2     4 
+#define ARRAY_RANK     2 
+#define SPACE_DIM     10                      /* dataset dimensions and rank */ 
+#define RANK  1 
+
+int
+main (void)
+{
+    hid_t       file, dataset;         /* file and dataset handles */
+    hid_t       datatype, dataspace;   /* handles */
+    hsize_t     sdims[] = {SPACE_DIM};              /* dataset dimensions */
+    hsize_t     adims[] = {ARRAY_DIM1, ARRAY_DIM2}; /* array dimensions */
+    hsize_t     adims_out[2]; 
+    herr_t      status;                             
+    int         data[SPACE_DIM][ARRAY_DIM1][ARRAY_DIM2];   /* data to write */
+    int         k, i, j;
+    int         array_rank_out; 
+
+    /* 
+     * Data  and output buffer initialization. 
+     */
+    for (k = 0; k < SPACE_DIM; k++) {
+      for (j = 0; j < ARRAY_DIM1; j++) {
+	for (i = 0; i < ARRAY_DIM2; i++)
+               data[k][j][i] = k;
+      }
+    }     
+    /*
+     * Create a new file using H5F_ACC_TRUNC access,
+     * default file creation properties, and default file
+     * access properties.
+     */
+    file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /*
+     * Describe the size of the array and create the data space for fixed
+     * size dataset. 
+     */
+    dataspace = H5Screate_simple(RANK, sdims, NULL); 
+
+    /* 
+     * Define array datatype for the data in the file.
+     */
+    datatype = H5Tarray_create(H5T_NATIVE_INT, ARRAY_RANK, adims, NULL);
+
+    /*
+     * Create a new dataset within the file using defined dataspace and
+     * datatype and default dataset creation properties.
+     */
+    dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace,
+			H5P_DEFAULT);
+
+    /*
+     * Write the data to the dataset using default transfer properties.
+     */
+    status = H5Dwrite(dataset, datatype, H5S_ALL, H5S_ALL,
+		      H5P_DEFAULT, data);
+
+
+    /*
+     * Close/release resources.
+     */
+    H5Sclose(dataspace);
+    H5Tclose(datatype);
+    H5Dclose(dataset);
+    /*
+     * Reopen dataset, and return information about its datatype.
+     */
+    dataset = H5Dopen(file, DATASETNAME);
+    datatype = H5Dget_type(dataset);
+    array_rank_out = H5Tget_array_ndims(datatype);
+    status = H5Tget_array_dims(datatype, adims_out, NULL); 
+    printf(" Array datatype rank is %d \n", array_rank_out);
+    printf(" Array dimensions are %d x %d \n", (int)adims_out[0],   
+                                               (int)adims_out[1]);
+
+    H5Tclose(datatype);
+    H5Dclose(dataset);
+    H5Fclose(file);
+ 
+    return 0;
+}     
+      </pre>
+    </td>
+  </tr>
+</table>
+</center>
+
+
+
+    <h2>11. Sharing Datatypes among Datasets</h2>
 
     <p>If a file has lots of datasets which have a common datatype,
       then the file could be made smaller by having all the datasets
@@ -2446,7 +2655,7 @@ in the HDF5 distribution.
     <p>
       <center>
 	<table border align=center width="100%">
-	  <caption align=bottom><h4>Example: Shared Types</h4></caption>
+	  <caption align=bottom><h4>Example: Shared Datatypes</h4></caption>
 	  <tr>
 	    <td>
 	      <p>To create two datasets that share a common datatype
@@ -2474,8 +2683,11 @@ hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT);
 	</table>
       </center>
 
+
+
+
     <a name="Datatypes-DataConversion">
-    <h2>11. Data Conversion</h2>
+    <h2>12. Data Conversion</h2>
     </a>
 
     <p>The library is capable of converting data from one type to
@@ -2881,7 +3093,7 @@ H5Tregister(H5T_PERS_SOFT, "cus2be",
 
 <!-- Created: Thu Dec  4 14:57:32 EST 1997 -->
 <!-- hhmts start -->
-Last modified:  5 February 2001
+Last modified:  9 February 2001
 <!-- hhmts end -->
 
 <br>