From 0cf4d3a79c5847af9db5fc496d7e14b3f94415a2 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Thu, 29 Oct 1998 20:09:28 -0500 Subject: [PATCH] [svn-r835] New DDL for Release 1.0. --- doc/html/ddl.html | 250 +++++++++++++++++++++++----------------------- 1 file changed, 127 insertions(+), 123 deletions(-) diff --git a/doc/html/ddl.html b/doc/html/ddl.html index 097f92d580..fcce13e4d4 100644 --- a/doc/html/ddl.html +++ b/doc/html/ddl.html @@ -1,72 +1,91 @@ + - -DDL for HDF5 + DDL for HDF5 +

DDL in BNF for HDF5

- DDL in BNF
-

-The following describes the data description language for HDF5 file. -The description is in Backus-Naur Form. A quick explanation -of the some symbols used. +

1. Introduction

+ +This document contains the data description language (DDL) for an HDF5 file. +The description is in Backus-Naur Form. + +

2. Explanation of Symbols

+ +This section contains a brief explanation of the symbols used in the DDL. 
-	::=               defined as
-	<tname>           a token with the name tname
-	<a> | <b>         one of <a> or <b>
-	<a>opt             zero or one occurrence of <a>
-	<a>*              zero or more occurrence of <a>
-	<a>+              one or more occurrence of <a>
-        TBD               To Be Decided
+    ::=                      defined as
+    <tname>                  a token with the name tname
+    <a> | <b>                one of <a> or <b>
+    <a>opt                    zero or one occurrence of <a>
+    <a>*                     zero or more occurrence of <a>
+    <a>+                     one or more occurrence of <a>
+    TBD                      To Be Decided
+
+

3. The DDL

-<file> ::= hdf5 "<file_name>" { <file_boot_block>opt <root_group> } + +
+<file> ::= HDF5 "<file_name>" { <file_boot_block>opt <root_group> }
 
 <file_name> ::= <identifier>
 
-<file_boot_block> ::= boot_block { <boot_block_content> }
+<file_boot_block> ::= BOOT_BLOCK { <boot_block_content> }
 
 <boot_block_content> ::= TBD
 
-<root_group> ::= group "/" { <nlink>opt <group_attribute>* <group_member>* }  
-// nlink must appear before attributes and members.
+<root_group> ::= GROUP "/" { <unamed_datatype>* <group_attribute>* <group_member>* }  
 
-<nlink>opt ::= { nlink <no_of_hardlinks> }
+<unamed_datatype> ::= DATATYPE "<unamed_type_name>" { <compound_type_def>+ }
 
-<no_of_hardlinks> ::= an integer larger than 1
+<unamed_type_name> ::= the assigned name for unamed type is in the form of 
+                      #oid1:oid2, where oid1 and oid2 are the object ids of the type
 
-<group_attribute> ::= <attribute> 
+<compound_type_def> ::=  <named_scalar_type> | <named_array_type>
 
-<attribute> ::= attribute "attr_name" { <datatype>    
-                                        <dataspace>   
-                                        <data>opt  } 
-// <datatype>, <dataspace> and <data> can be in any order 
-// as long as <data> comes the last.
+<named_scalar_type> ::= <scalar_type> <field_name> ;
 
-<attr_name> ::=  <identifier>
-
-<datatype> ::= datatype { "<datatype_name>" } |          // shared data type
-               datatype { <scalar_datatype> }  |         
-               datatype { <dt_definition>+ }        
-
-<datatype_name> ::= <identifier>
-
-<scalar_datatype> ::= H5T_NATIVE_CHAR | H5T_NATIVE_INT | ...     // data types supported by HDF5
-
-<dt_definition> ::= <scalar_datatype> <field_name> ;
+<scalar_type> ::= H5T_STD_I8BE | H5T_STD_I8LE | ...
 
 <field_name> ::= <identifier>
 
-<dataspace> ::= dataspace { "<dataspace_name>" } |
-                dataspace { array <current_dims> <max_dims> } | 
-                dataspace { other <ds_definition>+ } 
+<named_array_type> ::= <scalar_type> <field_name> <dim_sizes> ;
+
+<dim_sizes> ::= dimension sizes in the form of [dimsize1][dimzise2]..., 
+                where dimsize1, dimsize2 are integers
+
+<group_attribute> ::= <attribute> 
+
+<attribute> ::= ATTRIBUTE "<attr_name>" { <datatype>    
+                                          <dataspace>   
+                                          <data>opt  } 
+// <datatype> and <dataspace> must appear before <data>.
+
+<attr_name> ::=  <identifier>
+
+<datatype> ::= DATATYPE { <named_type> } |        
+               DATATYPE { "<scalar_type>" }  |         
+               DATATYPE { <compound_type_def>+ }
+
+<named_type> ::= <hardlink>
+
+<hardlink> ::= HARDLINK { "<abs_name>" }  
+
+<abs_name> ::= object absolute name
+
+<dataspace> ::= DATASPACE { "<dataspace_name>" } |
+                DATASPACE { ARRAY <current_dims> <max_dims> } | 
+                DATASPACE { OTHER <ds_definition>+ } 
 
 <dataspace_name> ::= <identifier>
 
-<current_dims> ::= a list of integers represented as (i1, i2, ... ) where ik is an integer, k = 1,2,...
+<current_dims> ::= a list of integers in the form of (i1, i2, ... ),
+                   where ik is an integer, k = 1,2,...
 
 <max_dims> ::= (i1, i2, ... ) where ik is an integer or H5S_UNLIMITED
 
@@ -74,44 +93,47 @@ of the some symbols used.
 
 <data> ::= data {TBD}
 
-<group_member> ::= <named_datatype> | <named_dataspace> | <group> | <dataset> | <softlink>
+<group_member> ::= <named_datatype> | <named_dataspace> | <group> | <dataset> | 
+                   <softlink>
 
-<named_datatype> ::= datatype "<datatype_name>" { <dt_definition>+ }
+<named_datatype> ::= DATATYPE "<type_name>" { <compound_type_def>+ }
 
-<named_dataspace> ::= dataspace "<dataspace_name>" { array <current_dims> <max_dims> } |
-                      dataspace "<dataspace_name>" { other <ds_definition>+ }
+<type_name> ::= "<identifier>"
 
-<group> ::= group "<group_name>" { <nlink>opt <group_attribute>* <group_member>* }  
+<named_dataspace> ::= DATASPACE "<dataspace_name>" { ARRAY <current_dims> <max_dims> } |
+                      DATASPACE "<dataspace_name>" { OTHER <ds_definition>+ }
 
+<group> ::= GROUP "<group_name>" { <hardlink> } |
+            GROUP "<group_name>" { <group_attribute>* <group_member>* } 
+            
 <group_name> ::= <identifier>
 
-<dataset> ::= dataset "<dataset_name>" { <nlink>opt
-                                         <datatype>  
+<dataset> ::= DATASET "<dataset_name>" { <hardlink> } |
+              DATASET "<dataset_name>" { <datatype>  
                                          <dataspace> 
                                          <storagelayout>opt
                                          <compression>opt
                                          <dataset_attribute>*
                                          <data>opt  } 
-// Any order is ok as long as <data> and <dataset_attribute> are 
-// after <datatype> and <dataspace>.
-// nlink must appear before others.
+// Tokens within {} can be in any order  as long as <data> and <dataset_attribute>
+// are after <datatype> and <dataspace>.
 
 <dataset_name> ::= <identifier>
 
-<storagelayout> :: = storagelayout <contiguous_layout>  |  
-                     storagelayout <chunked_layout>  | 
-                     storagelayout <compact_layout>  | 
-                     storagelayout <external_layout> 
+<storagelayout> :: = STORAGELAYOUT <contiguous_layout>  |  
+                     STORAGELAYOUT <chunked_layout>  | 
+                     STORAGELAYOUT <compact_layout>  | 
+                     STORAGELAYOUT <external_layout> 
 
-<contiguous_layout> ::= {contiguous}    // default
+<contiguous_layout> ::= {CONTIGUOUS}    // default
 
-<chunked_layout> ::=  {chunked <dims> }
+<chunked_layout> ::=  {CHUNKED <dims> }
 
 <dims> ::= (i1, i2, ... ), ik is an integer, k = 1,2,... 
 
 <compact_layout> ::= TBD           
 
-<external_layout> ::= {external <external_file>+ }
+<external_layout> ::= {EXTERNAL <external_file>+ }
 
 <external_file> ::= (<file_name> <offset> <size>) 
 
@@ -119,86 +141,68 @@ of the some symbols used.
 
 <size> ::= an integer
 
-<compression> :: = compression { TBD }  
+<compression> :: = COMPRESSION { TBD }  
 
 <dataset_attribute> ::= <attribute> 
 
-<softlink> ::= softlink "<softlink_name>" { linktarget "<target>" }
+<softlink> ::= SOFTLINK "<softlink_name>" { LINKTARGET "<target>" }
 
 <softlink_name> ::= <identifier>
 
 <target> ::= <identifier>
 
 <identifier> ::= string   
-// character "/" should be used with care. 
-// <dataset_name> cannot contain "/", for example.
+// character '/' should be used with care.
-
- An example of HDF5 File in DDL + + + +

4. An Example of an HDF5 File in DDL

+ + 
-
-Consider an HDF5 file, example.h5, with the following structure:
-
-                             /
-
-                     /       |       \
-                 group1     group3  dataset3
-                 /   \       |       
-           group2  dataset2 softlink
-             /
-      dataset1 
-              
-
-
-hdf5 "example" { 
-
-group "/" {
-
-   datatype "shared_datatype" {                    // named data type
-            H5T_NATIVE_CHAR c[20];
-            H5T_NATIVE_INT i; 
+HDF5 "example.h5" {
+GROUP "/" {
+   DATASET "dset1" {
+      DATATYPE {
+         H5T_STD_I32BE int_name;
+         H5T_IEEE_F32BE float_name;
+         H5T_IEEE_F64BE double_name;
+      }
+      DATASPACE { ARRAY ( 5 ) ( 5 ) }
+      DATA {{0,0,1}, {1,1,0.5}, {2,4,0.333333}, {3,9,0.25}, {4,16,0.2}}
    }
- 
-   attribute "group_attribute" {                   //attribute
-             datatype {H5T_NATIVE_CHAR}
-             dataspace {array (20) (20)}
-             data { "group attribute" }
-   } 
-
-   group "group1" {
-
-         group "group2" {
-
-               dataset "dataset1" {
-                        dataspace {array (4) (4)}
-                        datatype {"shared_datatype"}
-                        attribute "dataset1_attr" {
-                                   datatype {H5T_NATIVE_CHAR}
-                                   dataspace {array (10) (10)}
-                        }
-               }
-         }
-
-         dataset "dataset2" {
-               datatype {H5T_NATIVE_INT}
-               dataspace {array (2,5) (H5S_UNLIMITED, 5)}
-               data {0,0,0,0,0,0,0,0,0,0}
+   GROUP "group1" {
+      DATASET "dset2" {
+         DATATYPE {
+            HARDLINK { "/type1" }
          }
+         DATASPACE { ARRAY ( 5 ) ( 5 ) }
+         DATA {{0,0}, {1,1.1}, {2,2.2}, {3,3.3}, {4,4.4}}
+      }
    }
-   
-   group "group3" {
-         softlink "slink" {
-                  linktarget "/sometarget" 
-         }
+   GROUP "group2" {
+      HARDLINK { "/group1" }
    }
-      
-   
-   dataset "dataset3" {
-           datatype {H5T_NATIVE_FLOAT}
-           dataspace {array (100,100) (100,100)} 
+   SOFTLINK "slink1" {
+      LINKTARGET "somevalue"
+   }
+   DATATYPE "type1" {
+      H5T_STD_I32BE int_name;
+      H5T_IEEE_F32BE float_name;
    }
- 
-} 
-
 }
+}
+
+ + +
+
+HDF Help Desk +
+ +Last modified: 28 October 1998 + + +