[svn-r2986] Purpose:

    Corrections & updates
Description:
    Updated and corrected DDL description & examples to include all the
    current features for the v1.4 release.  Lots of changes...
Platforms tested:
    Netscape 4.76

1 files changed, 123 insertions, 122 deletions

diff --git a/doc/html/ddl.html b/doc/html/ddl.html
index 797a30b..f0b5dd7 100644
--- a/doc/html/ddl.html
+++ b/doc/html/ddl.html
@@ -85,38 +85,36 @@ This section contains a brief explanation of the symbols used in the DDL.
 
 <super_block_content> ::= TBD
 
-&lt;root_group&gt; ::= GROUP "/" { &lt;unamed_datatype&gt;* &lt;object_id&gt;<FONT SIZE=1.7>opt</FONT> &lt;group_attribute&gt;* &lt;group_member&gt;* }  
+&lt;root_group&gt; ::= GROUP "/" { &lt;unamed_datatype&gt;* &lt;object_id&gt;<FONT SIZE=1.7>opt</FONT>
+            &lt;group_attribute&gt;* &lt;group_member&gt;* }  
 
-&lt;unamed_datatype&gt; ::= DATATYPE &lt;unamed_type_name&gt; { &lt;compound_type&gt; }
+&lt;datatype&gt; ::= &lt;atomic_type&gt | &lt;compound_type&gt | &lt;variable_length_type&gt |
+            &lt;array_type&gt
 
-&lt;unamed_type_name&gt; ::= the assigned name for unamed type is in the form of 
-                      #oid1:oid2, where oid1 and oid2 are the object ids of the type
-
-&lt;variable_length_type&gt; ::= H5T_VLEN of &lt;atomic_type&gt;
-
-&lt;compound_type&gt; ::= &lt;member_type_def&gt;+ 
-
-&lt;member_type_def&gt; ::= &lt;scalar_type_def&gt; | &lt;array_type_def&gt;
+&lt;unamed_datatype&gt; ::= DATATYPE &lt;unamed_type_name&gt; { &lt;datatype&gt; }
 
-&lt;scalar_type_def&gt; ::= &lt;atomic_type&gt; &lt;field_name&gt; ;
+&lt;unamed_type_name&gt; ::= the assigned name for unamed type is in the form of 
+           #oid1:oid2, where oid1 and oid2 are the object ids of the type
 
-&lt;atomic_type&gt; ::= &lt;integer&gt; | &lt;float&gt; | &lt;time&gt; | &lt;string&gt; | &lt;bitfield&gt; | &lt;opaque&gt; |
-                 &lt;reference&gt; | &lt;enum&gt;
+&lt;atomic_type&gt; ::= &lt;integer&gt; | &lt;float&gt; | &lt;time&gt; | &lt;string&gt; | &lt;bitfield&gt; |
+               &lt;opaque&gt; | &lt;reference&gt; | &lt;enum&gt;
 
-&lt;integer&gt; ::=  H5T_STD_I8BE | H5T_STD_I8LE | H5T_STD_I16BE | H5T_STD_I16LE | H5T_STD_I32BE |
-               H5T_STD_I32LE | H5T_STD_I64BE | H5T_STD_I64LE |  H5T_STD_U8BE |
-               H5T_STD_U8LE | H5T_STD_U16BE | H5T_STD_U16LE | H5T_STD_U32BE |
-               H5T_STD_U32LE | H5T_STD_U64BE | H5T_STD_U64LE | H5T_NATIVE_CHAR |
-               H5T_NATIVE_UCHAR | H5T_NATIVE_SHORT | H5T_NATIVE_USHORT | 
-               H5T_NATIVE_INT | H5T_NATIVE_UINT | H5T_NATIVE_LONG | H5T_NATIVE_ULONG |
-               H5T_NATIVE_LLONG | H5T_NATIVE_ULLONG
+&lt;integer&gt; ::=  H5T_STD_I8BE | H5T_STD_I8LE | H5T_STD_I16BE |
+           H5T_STD_I16LE | H5T_STD_I32BE | H5T_STD_I32LE | H5T_STD_I64BE |
+           H5T_STD_I64LE | H5T_STD_U8BE | H5T_STD_U8LE | H5T_STD_U16BE |
+           H5T_STD_U16LE | H5T_STD_U32BE | H5T_STD_U32LE | H5T_STD_U64BE |
+           H5T_STD_U64LE | H5T_NATIVE_CHAR | H5T_NATIVE_UCHAR |
+           H5T_NATIVE_SHORT | H5T_NATIVE_USHORT | H5T_NATIVE_INT |
+           H5T_NATIVE_UINT | H5T_NATIVE_LONG | H5T_NATIVE_ULONG |
+           H5T_NATIVE_LLONG | H5T_NATIVE_ULLONG
 
-&lt;float&gt; ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE | H5T_IEEE_F64BE |  H5T_IEEE_F64LE |
-            H5T_NATIVE_FLOAT |  H5T_NATIVE_DOUBLE | H5T_NATIVE_LDOUBLE
+&lt;float&gt; ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE | H5T_IEEE_F64BE |
+            H5T_IEEE_F64LE | H5T_NATIVE_FLOAT |  H5T_NATIVE_DOUBLE |
+            H5T_NATIVE_LDOUBLE
 
 &lt;time&gt; ::= TBD
 
-&lt;string&gt; ::= { STRSIZE &lt;strsize&gt; ;
+&lt;string&gt; ::= H5T_STRING { STRSIZE &lt;strsize&gt; ;
                STRPAD &lt;strpad&gt; ;
                CSET &lt;cset&gt; ;
                CTYPE &lt;ctype&gt; ; }  
@@ -131,32 +129,38 @@ This section contains a brief explanation of the symbols used in the DDL.
 
 &lt;bitfield&gt; ::= TBD
 
-&lt;opaque&gt; ::= { H5T_OPAQUE; OPAQUE_TAG &lt;identifier&gt;; }
+&lt;opaque&gt; ::= H5T_OPAQUE { &lt;identifier&gt; }
+
+&lt;reference&gt; ::= H5T_REFERENCE { &lt;ref_type&gt; }
+
+&lt;ref_type&gt; ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG
+
+&lt;compound_type&gt; ::= H5T_COMPOUND { &lt;member_type_def&gt;+ }
 
-&lt;reference&gt; ::= H5T_REFERENCE
+&lt;member_type_def&gt; ::= &lt;datatype&gt; &lt;field_name&gt; ;
 
 &lt;field_name&gt; ::= &lt;identifier&gt;
 
-&lt;array_type_def&gt; ::= &lt;atomic_type&gt; &lt;field_name&gt; &lt;dim_sizes&gt; ;
+&lt;variable_length_type&gt; ::= H5T_VLEN { &lt;datatype&gt }
 
-&lt;dim_sizes&gt; ::= [dimsize1][dimsize2]..., where dimsize1, dimsize2 are integers
+&lt;array_type&gt; ::= H5T_ARRAY { &lt;dim_sizes&gt; &lt;datatype&gt; }
 
-&lt;group_attribute&gt; ::= &lt;attribute&gt; 
+&lt;dim_sizes&gt; ::= [dimsize1][dimsize2]...
+// where dimsize1, dimsize2 are integers
 
-&lt;attribute&gt; ::= ATTRIBUTE &lt;attr_name&gt; { &lt;datatype&gt;    
-                                        &lt;dataspace&gt;
-                                        &lt;object_id&gt;<FONT SIZE=1.7>opt</FONT>
+&lt;attribute&gt; ::= ATTRIBUTE &lt;attr_name&gt; { &lt;dataset_type&gt;    
+                                        &lt;dataset_space&gt;
                                         &lt;data&gt;<FONT SIZE=1.7>opt</FONT>  } 
-// &lt;datatype&gt; and &lt;dataspace&gt; must appear before &lt;data&gt;.
 
 &lt;attr_name&gt; ::= &lt;identifier&gt;
 
-&lt;datatype&gt; ::= DATATYPE { &lt;atomic_type&gt; }  |         
-               DATATYPE { &lt;compound_type&gt; } |
-               DATATYPE { &lt;variable_length_type&gt; } |
-               DATATYPE { &lt;named_type&gt; } 
+&lt;dataset_type&gt; ::= DATATYPE &lt;path_name&gt; | &lt;datatype&gt;
+
+&lt;enum&gt; ::= H5T_ENUM { &lt;enum_base_type&gt; &lt;enum_def&gt;+  }
 
-&lt;enum&gt; ::= H5T_ENUM { &lt;integer&gt;; &lt;enum_def&gt;+  }
+&lt;enum_base_type&gt; ::= &lt;integer&gt;
+// Currently enums can only hold integer type data, but they may be expanded
+// in the future to hold any datatype
 
 &lt;enum_def&gt; ::= &lt;enum_symbol&gt; &lt;enum_val&gt;;
 
@@ -164,32 +168,39 @@ This section contains a brief explanation of the symbols used in the DDL.
 
 &lt;enum_val&gt; ::= an integer;
 
-&lt;named_type&gt; ::= &lt;path_name&gt;
+&lt;path_name&gt; ::= &lt;path_part&gt;+
+
+&lt;path_part&gt; ::= /&lt;identifier&gt;
+
+&lt;dataspace&gt; ::= &lt;scalar_space&gt | &lt;simple_space&gt | &lt;complex_space&gt
 
-&lt;path_name&gt; ::= &lt;identifier&gt;
+&lt;scalar_space&gt; ::= SCALAR
 
-&lt;dataspace&gt; ::= DATASPACE { SCALAR } |
-                DATASPACE { SIMPLE &lt;current_dims&gt; / &lt;max_dims&gt; } | 
-                DATASPACE { COMPLEX &lt;ds_definition&gt;+ } |
-                DATASPACE { &lt;dataspace_name&gt; }
+&lt;simple_space&gt; ::= SIMPLE { &lt;current_dims&gt; / &lt;max_dims&gt; }
+
+&lt;complex_space&gt; ::= COMPLEX { &lt;complex_space_definition&gt; }
+
+&lt;dataset_space&gt; ::= DATASPACE &lt;path_name&gt; | &lt;dataspace&gt;
 
 &lt;current_dims&gt; ::= (<i>i<FONT SIZE=1.0>1</i></FONT>, <i>i<FONT SIZE=1.0>2</i></FONT>, ... ), where <i>i<FONT SIZE=1.0>k</i></FONT> is an integer, <i>k</i> = 1,2,...
 
 &lt;max_dims&gt; ::= (<i>i<FONT SIZE=1.0>1</i></FONT>, <i>i<FONT SIZE=1.0>2</i></FONT>, ... ) where <i>i<FONT SIZE=1.0>k</i></FONT> is an integer or H5S_UNLIMITED
 
-&lt;ds_definition&gt; ::= TBD
-
-&lt;dataspace_name&gt; ::= &lt;identifier&gt;
+&lt;complex_space_definition&gt; ::= TBD
 
-&lt;data&gt; ::= DATA { &lt;scalar_space_data&gt; |
-                  &lt;simple_space_data&gt; |
-                  &lt;complex_space_data&gt; |
-                  &lt;variable_length_space_data&gt; }
+&lt;data&gt; ::= DATA { &lt;scalar_space_data&gt; | &lt;simple_space_data&gt; |
+              &lt;complex_space_data&gt; }
                   
-&lt;scalar_space_data&gt; ::= &lt;atomic_scalar_data&gt; | &lt;compound_scalar_data&gt;
+&lt;scalar_space_data&gt; ::= &lt;any_element&gt;
 
-&lt;atomic_scalar_data&gt; :: = &lt;integer_data&gt; | &lt;float_data&gt; | &lt;time_data&gt; | &lt;string_data&gt; | 
-                          &lt;bitfield_data&gt; | &lt;opaque_data&gt; | &lt;enum_data&gt; | &lt;reference_data&gt;
+&lt;any_element&gt; ::= &lt;atomic_element&gt; | &lt;compound_element&gt; | 
+        &lt;variable_length_element&gt; | &lt;array_element&gt;
+
+&lt;any_data_seq&gt; ::= &lt;any_element&gt; | &lt;any_element&gt;, &lt;any_data_seq&gt;
+
+&lt;atomic_element&gt; :: = &lt;integer_data&gt; | &lt;float_data&gt; | &lt;time_data&gt; |
+                &lt;string_data&gt; | &lt;bitfield_data&gt; | &lt;opaque_data&gt; |
+                &lt;enum_data&gt; | &lt;reference_data&gt;
 
 &lt;integer_data&gt; ::= an integer
 
@@ -199,14 +210,14 @@ This section contains a brief explanation of the symbols used in the DDL.
 
 &lt;string_data&gt; ::= a string
 // A string is enclosed in double quotes. 
-// If a string is displayed on more than one line, string concatenate operator '//'is used.
+// If a string is displayed on more than one line, string concatenate
+// operator '//'is used.
 
 &lt;bitfield_data&gt; ::= TBD
 
 &lt;opaque_data&gt; ::= TBD
 
 &lt;enum_data&gt; ::= &lt;enum_symbol&gt;
-//maybe will be &lt;enum_symbol&gt; in the future
 
 &lt;reference_data&gt; ::= &lt;object_ref_data&gt; | &lt;data_region_data&gt; | NULL
 
@@ -218,12 +229,13 @@ This section contains a brief explanation of the symbols used in the DDL.
 
 &lt;object_num&gt; ::= an integer:an integer | an integer
 
-&lt;data_region_data&gt; ::= H5T_STD_REF_DSETREG &lt;object_num&gt; {&lt;data_region_data_info&gt;, 
-                     &lt;data_region_data_info&gt;, ...}
+&lt;data_region_data&gt; ::= H5T_STD_REF_DSETREG &lt;object_num&gt;
+        { &lt;data_region_data_info&gt;, &lt;data_region_data_info&gt;, ...}
 
 &lt;data_region_data_info&gt; ::= &lt;region_info&gt; | &lt;point_info&gt;
 
-&lt;region_info&gt; ::= (&lt;lower_bound&gt;:&lt;upper_bound&gt;, &lt;lower_bound&gt;:&lt;upper_bound&gt;, ...)
+&lt;region_info&gt; ::= (&lt;lower_bound&gt;:&lt;upper_bound&gt;,
+        &lt;lower_bound&gt;:&lt;upper_bound&gt;, ...)
 
 &lt;lower_bound&gt; ::= an integer
 
@@ -231,50 +243,45 @@ This section contains a brief explanation of the symbols used in the DDL.
 
 &lt;point_info&gt; ::= (an integer, an integer, ...)
 
-&lt;compound_scalar_data&gt; ::= { [ &lt;member_data&gt; ], [ &lt;member_data&gt; ], ... }
-
-&lt;member_data&gt; ::= &lt;atomic_scalar_data&gt; | &lt;atomic_simple_data&gt; 
-
-&lt;atomic_simple_data&gt; :: = &lt;atomic_element&gt;, &lt;atomic_simple_data&gt; | &lt;atomic_element&gt;
+&lt;compound_element&gt; ::= { &lt;any_data_seq&gt; }
 
-&lt;atomic_element&gt; ::= &lt;atomic_scalar_data&gt;
+&lt;atomic_simple_data&gt; :: = &lt;atomic_element&gt;, &lt;atomic_simple_data&gt; |
+        &lt;atomic_element&gt;
 
-&lt;simple_space_data&gt; :: = &lt;atomic_simple_data&gt; | &lt;compound_simple_data&gt;
+&lt;simple_space_data&gt; :: = &lt;any_data_seq&gt;
 
-&lt;variable_length_space_data&gt; ::= &lt;atomic_simple_data&gt;
+&lt;variable_length_element&gt; ::= ( &lt;any_data_seq&gt; )
 
-&lt;compound_simple_data&gt; ::= &lt;compoud_element&gt;, &lt;compound_element&gt;, ...
-
-&lt;compound_element&gt; ::= &lt;compound_scalar_data&gt;
+&lt;array_element&gt; ::= [ &lt;any_data_seq&gt; ]
 
 &lt;complex_space_data&gt; ::= TBD
 
-&lt;group_member&gt; ::= &lt;named_datatype&gt; | &lt;named_dataspace&gt; | &lt;group&gt; | &lt;dataset&gt; | 
-                   &lt;softlink&gt;
-
-&lt;named_datatype&gt; ::= DATATYPE &lt;type_name&gt; { &lt;compound_type&gt; }
+&lt;named_datatype&gt; ::= DATATYPE &lt;type_name&gt; { &lt;datatype&gt; }
 
 &lt;type_name&gt; ::= &lt;identifier&gt;
 
 &lt;named_dataspace&gt; ::= TBD
 
-&lt;group&gt; ::= GROUP &lt;group_name&gt; { &lt;hardlink&gt; } |
-            GROUP &lt;object_id&gt;<FONT SIZE=1.7>opt</FONT> &lt;group_name&gt; { &lt;group_attribute&gt;* &lt;group_member&gt;* } 
+&lt;hardlink&gt; ::= HARDLINK &lt;path_name&gt; 
+
+&lt;group&gt; ::= GROUP &lt;group_name&gt; { &lt;hardlink&gt; | &lt;group_info&gt; }
             
 &lt;group_name&gt; ::= &lt;identifier&gt;
 
-&lt;hardlink&gt; ::= HARDLINK &lt;path_name&gt; 
+&lt;group_info&gt; ::= &lt;group_attribute&gt;* &lt;group_member&gt;* 
+            
+&lt;group_attribute&gt; ::= &lt;attribute&gt; 
+
+&lt;group_member&gt; ::= &lt;named_datatype&gt; | &lt;named_dataspace&gt; | &lt;group&gt; |
+        &lt;dataset&gt; | &lt;softlink&gt;
 
-&lt;dataset&gt; ::= DATASET &lt;dataset_name&gt; { &lt;hardlink&gt; } |
-              DATASET &lt;dataset_name&gt; { &lt;datatype&gt;  
-                                       &lt;dataspace&gt; 
-                                       &lt;storagelayout&gt;<FONT SIZE=1.7>opt</FONT>
-                                       &lt;compression&gt;<FONT SIZE=1.7>opt</FONT>
-                                       &lt;dataset_attribute&gt;*
-                                       &lt;object_id&gt;<FONT SIZE=1.7>opt</FONT>
-                                       &lt;data&gt;<FONT SIZE=1.7>opt</FONT>  } 
-// Tokens within {} can be in any order  as long as &lt;data&gt; and &lt;dataset_attribute&gt;
-// are after &lt;datatype&gt; and &lt;dataspace&gt;.
+&lt;dataset&gt; ::= DATASET &lt;dataset_name&gt; { &lt;hardlink&gt; | &lt;dataset_info&gt; }
+
+&lt;dataset_info&gt; ::= &lt;dataset_type&gt;  &lt;dataset_space&gt; &lt;storagelayout&gt;<FONT SIZE=1.7>opt</FONT>
+               &lt;compression&gt;<FONT SIZE=1.7>opt</FONT> &lt;dataset_attribute&gt;* &lt;object_id&gt;<FONT SIZE=1.7>opt</FONT>
+               &lt;data&gt;<FONT SIZE=1.7>opt</FONT>
+// Tokens above can be in any order as long as &lt;data&gt; is 
+// after &lt;dataset_type&gt; and &lt;dataset_space&gt;.
 
 &lt;dataset_name&gt; ::= &lt;identifier&gt;
 
@@ -323,21 +330,20 @@ This section contains a brief explanation of the symbols used in the DDL.
 HDF5 "example.h5" {
 GROUP "/" {
    ATTRIBUTE "attr1" {
-      DATATYPE {
-         { STRSIZE 17;
+      DATATYPE H5T_STRING { 
+           STRSIZE 17;
            STRPAD H5T_STR_NULLTERM;
            CSET H5T_CSET_ASCII;
            CTYPE H5T_C_S1;
          }
-      }
-      DATASPACE { SCALAR }
+      DATASPACE SCALAR 
       DATA {
          "string attribute"
       }
    }
    DATASET "dset1" {
-      DATATYPE { H5T_STD_I32BE }
-      DATASPACE { SIMPLE ( 10, 10 ) / ( 10, 10 ) }
+      DATATYPE H5T_STD_I32BE
+      DATASPACE SIMPLE { ( 10, 10 ) / ( 10, 10 ) }
       DATA {
          0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
          0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
@@ -352,46 +358,44 @@ GROUP "/" {
       }
    }
    DATASET "dset2" {
-      DATATYPE {
+      DATATYPE H5T_COMPOUND {
          H5T_STD_I32BE "a";
          H5T_IEEE_F32BE "b";
          H5T_IEEE_F64BE "c";
       }
-      DATASPACE { SIMPLE ( 5 ) / ( 5 ) }
+      DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
       DATA {
          {
-            [ 1 ],
-            [ 0.1 ],
-            [ 0.01 ]
+            1,
+            0.1,
+            0.01
          },
          {
-            [ 2 ],
-            [ 0.2 ],
-            [ 0.02 ]
+            2,
+            0.2,
+            0.02
          },
          {
-            [ 3 ],
-            [ 0.3 ],
-            [ 0.03 ]
+            3,
+            0.3,
+            0.03
          },
          {
-            [ 4 ],
-            [ 0.4 ],
-            [ 0.04 ]
+            4,
+            0.4,
+            0.04
          },
          {
-            [ 5 ],
-            [ 0.5 ],
-            [ 0.05 ]
+            5,
+            0.5,
+            0.05
          }
       }
    }
    GROUP "group1" {
       DATASET "dset3" {
-         DATATYPE {
-            "/type1"
-         }
-         DATASPACE { SIMPLE ( 5 ) / ( 5 ) }
+         DATATYPE "/type1"
+         DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
          DATA {
             {
                [ 0, 1, 2, 3 ],
@@ -437,13 +441,10 @@ GROUP "/" {
       }
    }
    DATASET "dset3" {
-      DATATYPE { H5T_VLEN of H5T_STD_I32LE } 
-      DATASPACE { SIMPLE ( 4 ) / ( 4 ) } 
+      DATATYPE H5T_VLEN { H5T_STD_I32LE } 
+      DATASPACE SIMPLE { ( 4 ) / ( 4 ) } 
       DATA {
-         0
-         10, 11
-         20, 21, 22
-         30, 31, 32, 33
+         (0), (10, 11), (20, 21, 22), (30, 31, 32, 33)
       } 
    }
    GROUP "group2" {
@@ -452,9 +453,9 @@ GROUP "/" {
    SOFTLINK "slink1" {
       LINKTARGET "somevalue"
    }
-   DATATYPE "type1" {
-      H5T_STD_I32BE "a"[4];
-      H5T_IEEE_F32BE "b"[5][6];
+   DATATYPE "type1" H5T_COMPOUND {
+      H5T_ARRAY { [4] H5T_STD_I32BE } "a";
+      H5T_ARRAY { [5][6] H5T_IEEE_F32BE } "b";
    }
 }
 }