summaryrefslogtreecommitdiffstats
path: root/doc/html/ddl.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/ddl.html')
-rw-r--r--doc/html/ddl.html238
1 files changed, 121 insertions, 117 deletions
diff --git a/doc/html/ddl.html b/doc/html/ddl.html
index 097f92d..fcce13e 100644
--- a/doc/html/ddl.html
+++ b/doc/html/ddl.html
@@ -1,72 +1,91 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
-
<head>
-<TITLE>DDL for HDF5</TITLE>
+ <title>DDL for HDF5</title>
</head>
<body>
+<h1>DDL in BNF for HDF5</h1>
+
+
+<h2>1. Introduction</h2>
+
+This document contains the data description language (DDL) for an HDF5 file.
+The description is in Backus-Naur Form.
-<B> DDL in BNF </B> <br>
+<h2>2. Explanation of Symbols</h2>
-<P>
-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.
+This section contains a brief explanation of the symbols used in the DDL.
<PRE>
- ::= defined as
- &lt;tname&gt; a token with the name tname
- &lt;a&gt; | &lt;b&gt; one of &lt;a&gt; or &lt;b&gt;
- &lt;a&gt;<FONT SIZE=1.7>opt</FONT> zero or one occurrence of &lt;a&gt;
- &lt;a&gt;* zero or more occurrence of &lt;a&gt;
- &lt;a&gt;+ one or more occurrence of &lt;a&gt;
- TBD To Be Decided
+ ::= defined as
+ &lt;tname&gt; a token with the name tname
+ &lt;a&gt; | &lt;b&gt; one of &lt;a&gt; or &lt;b&gt;
+ &lt;a&gt;<FONT SIZE=1.7>opt</FONT> zero or one occurrence of &lt;a&gt;
+ &lt;a&gt;* zero or more occurrence of &lt;a&gt;
+ &lt;a&gt;+ one or more occurrence of &lt;a&gt;
+ TBD To Be Decided
+</pre>
+<h2>3. The DDL</h2>
-&lt;file&gt; ::= hdf5 "&lt;file_name&gt;" { &lt;file_boot_block&gt;<FONT SIZE=1.7>opt</FONT> &lt;root_group&gt; }
+<dir>
+<pre>
+&lt;file&gt; ::= HDF5 "&lt;file_name&gt;" { &lt;file_boot_block&gt;<FONT SIZE=1.7>opt</FONT> &lt;root_group&gt; }
&lt;file_name&gt; ::= &lt;identifier&gt;
-&lt;file_boot_block&gt; ::= boot_block { &lt;boot_block_content&gt; }
+&lt;file_boot_block&gt; ::= BOOT_BLOCK { &lt;boot_block_content&gt; }
&lt;boot_block_content&gt; ::= TBD
-&lt;root_group&gt; ::= group "/" { &lt;nlink&gt;<FONT SIZE=1.7>opt</FONT> &lt;group_attribute&gt;* &lt;group_member&gt;* }
-// nlink must appear before attributes and members.
+&lt;root_group&gt; ::= GROUP "/" { &lt;unamed_datatype&gt;* &lt;group_attribute&gt;* &lt;group_member&gt;* }
+
+&lt;unamed_datatype&gt ::= DATATYPE "&lt;unamed_type_name&gt;" { &lt;compound_type_def&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;compound_type_def&gt; ::= &lt;named_scalar_type&gt; | &lt;named_array_type&gt;
-&lt;nlink&gt;<FONT SIZE=1.7>opt</FONT> ::= { nlink &lt;no_of_hardlinks&gt; }
+&lt;named_scalar_type&gt; ::= &lt;scalar_type&gt; &lt;field_name&gt; ;
-&lt;no_of_hardlinks&gt; ::= an integer larger than 1
+&lt;scalar_type&gt; ::= H5T_STD_I8BE | H5T_STD_I8LE | ...
+
+&lt;field_name&gt; ::= &lt;identifier&gt;
+
+&lt;named_array_type&gt; ::= &lt;scalar_type&gt; &lt;field_name&gt; &lt;dim_sizes&gt; ;
+
+&lt;dim_sizes&gt; ::= dimension sizes in the form of [dimsize1][dimzise2]...,
+ where dimsize1, dimsize2 are integers
&lt;group_attribute&gt; ::= &lt;attribute&gt;
-&lt;attribute&gt; ::= attribute "attr_name" { &lt;datatype&gt;
- &lt;dataspace&gt;
- &lt;data&gt;<FONT SIZE=1.7>opt</FONT> }
-// &lt;datatype&gt;, &lt;dataspace&gt; and &lt;data&gt; can be in any order
-// as long as &lt;data&gt; comes the last.
+&lt;attribute&gt; ::= ATTRIBUTE "&lt;attr_name&gt" { &lt;datatype&gt;
+ &lt;dataspace&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;datatype_name&gt;" } | // shared data type
- datatype { &lt;scalar_datatype&gt; } |
- datatype { &lt;dt_definition&gt;+ }
+&lt;datatype&gt; ::= DATATYPE { &lt;named_type&gt; } |
+ DATATYPE { "&lt;scalar_type&gt;" } |
+ DATATYPE { &lt;compound_type_def&gt;+ }
-&lt;datatype_name&gt; ::= &lt;identifier&gt;
+&lt;named_type&gt; ::= &lt;hardlink&gt;
-&lt;scalar_datatype&gt; ::= H5T_NATIVE_CHAR | H5T_NATIVE_INT | ... // data types supported by HDF5
+&lt;hardlink&gt; ::= HARDLINK { "&lt;abs_name&gt;" }
-&lt;dt_definition&gt; ::= &lt;scalar_datatype&gt; &lt;field_name&gt; ;
+&lt;abs_name&gt; ::= object absolute name
-&lt;field_name&gt; ::= &lt;identifier&gt;
-
-&lt;dataspace&gt; ::= dataspace { "&lt;dataspace_name&gt;" } |
- dataspace { array &lt;current_dims&gt; &lt;max_dims&gt; } |
- dataspace { other &lt;ds_definition&gt;+ }
+&lt;dataspace&gt; ::= DATASPACE { "&lt;dataspace_name&gt;" } |
+ DATASPACE { ARRAY &lt;current_dims&gt; &lt;max_dims&gt; } |
+ DATASPACE { OTHER &lt;ds_definition&gt;+ }
&lt;dataspace_name&gt; ::= &lt;identifier&gt;
-&lt;current_dims&gt; ::= a list of integers represented as (<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;current_dims&gt; ::= a list of integers in the form of (<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
@@ -74,44 +93,47 @@ of the some symbols used.
&lt;data&gt; ::= data {TBD}
-&lt;group_member&gt; ::= &lt;named_datatype&gt; | &lt;named_dataspace&gt; | &lt;group&gt; | &lt;dataset&gt; | &lt;softlink&gt;
+&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;datatype_name&gt;" { &lt;dt_definition&gt;+ }
+&lt;named_datatype&gt; ::= DATATYPE "&lt;type_name&gt;" { &lt;compound_type_def&gt;+ }
-&lt;named_dataspace&gt; ::= dataspace "&lt;dataspace_name&gt;" { array &lt;current_dims&gt; &lt;max_dims&gt; } |
- dataspace "&lt;dataspace_name&gt;" { other &lt;ds_definition&gt;+ }
+&lt;type_name&gt; ::= "&lt;identifier&gt;"
-&lt;group&gt; ::= group "&lt;group_name&gt;" { &lt;nlink&gt;<FONT SIZE=1.7>opt</FONT> &lt;group_attribute&gt;* &lt;group_member&gt;* }
+&lt;named_dataspace&gt; ::= DATASPACE "&lt;dataspace_name&gt;" { ARRAY &lt;current_dims&gt; &lt;max_dims&gt; } |
+ DATASPACE "&lt;dataspace_name&gt;" { OTHER &lt;ds_definition&gt;+ }
+&lt;group&gt; ::= GROUP "&lt;group_name&gt;" { &lt;hardlink&gt; } |
+ GROUP "&lt;group_name&gt;" { &lt;group_attribute&gt;* &lt;group_member&gt;* }
+
&lt;group_name&gt; ::= &lt;identifier&gt;
-&lt;dataset&gt; ::= dataset "&lt;dataset_name&gt;" { &lt;nlink&gt;<FONT SIZE=1.7>opt</FONT>
- &lt;datatype&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;data&gt;<FONT SIZE=1.7>opt</FONT> }
-// Any order is ok as long as &lt;data&gt; and &lt;dataset_attribute&gt; are
-// after &lt;datatype&gt; and &lt;dataspace&gt;.
-// nlink must appear before others.
+// 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_name&gt; ::= &lt;identifier&gt;
-&lt;storagelayout&gt; :: = storagelayout &lt;contiguous_layout&gt; |
- storagelayout &lt;chunked_layout&gt; |
- storagelayout &lt;compact_layout&gt; |
- storagelayout &lt;external_layout&gt;
+&lt;storagelayout&gt; :: = STORAGELAYOUT &lt;contiguous_layout&gt; |
+ STORAGELAYOUT &lt;chunked_layout&gt; |
+ STORAGELAYOUT &lt;compact_layout&gt; |
+ STORAGELAYOUT &lt;external_layout&gt;
-&lt;contiguous_layout&gt; ::= {contiguous} // default
+&lt;contiguous_layout&gt; ::= {CONTIGUOUS} // default
-&lt;chunked_layout&gt; ::= {chunked &lt;dims&gt; }
+&lt;chunked_layout&gt; ::= {CHUNKED &lt;dims&gt; }
&lt;dims&gt; ::= (<i>i<FONT SIZE=1.0>1</i></FONT>, <i>i<FONT SIZE=1.0>2</i></FONT>, ... ), <i>i<FONT SIZE=1.0>k</i></FONT> is an integer, <i>k</i> = 1,2,...
&lt;compact_layout&gt; ::= TBD
-&lt;external_layout&gt; ::= {external &lt;external_file&gt;+ }
+&lt;external_layout&gt; ::= {EXTERNAL &lt;external_file&gt;+ }
&lt;external_file&gt; ::= (&lt;file_name&gt; &lt;offset&gt; &lt;size&gt;)
@@ -119,86 +141,68 @@ of the some symbols used.
&lt;size&gt; ::= an integer
-&lt;compression&gt; :: = compression { TBD }
+&lt;compression&gt; :: = COMPRESSION { TBD }
&lt;dataset_attribute&gt; ::= &lt;attribute&gt;
-&lt;softlink&gt; ::= softlink "&lt;softlink_name&gt;" { linktarget "&lt;target&gt;" }
+&lt;softlink&gt; ::= SOFTLINK "&lt;softlink_name&gt;" { LINKTARGET "&lt;target&gt;" }
&lt;softlink_name&gt; ::= &lt;identifier&gt;
&lt;target&gt; ::= &lt;identifier&gt;
&lt;identifier&gt; ::= string
-// character "/" should be used with care.
-// &lt;dataset_name&gt; cannot contain "/", for example.
+// character '/' should be used with care.
</PRE>
-<HR>
-<B> An example of HDF5 File in DDL </B>
-<PRE>
+</dir>
-Consider an HDF5 file, example.h5, with the following structure:
- /
+<h2>4. An Example of an HDF5 File in DDL</h2>
- / | \
- 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;
+<dir>
+<PRE>
+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;
+ }
+}
}
+</pre>
+</dir>
+
+<hr>
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+</address>
+
+Last modified: 28 October 1998
+
+</body>
+</html>