mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
3c6be60da7
Purpose: Feature Add Description: Added support for dumping Group Comments. This involved a modification of the DDL as well. Solution: Steal code from h5ls and put it in the h5dump. The ddl.html file was updated as normal. And a test was created... Platforms tested: Dangermouse, Modi4, Kelgia
563 lines
18 KiB
HTML
563 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>DDL for HDF5</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
|
|
<br>
|
|
<a href="Files.html">Files</a>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Datatypes</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<br>
|
|
<a href="References.html">References</a>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<br>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="MountingFiles.html">Mounting Files</a>
|
|
<br>
|
|
<a href="Performance.html">Performance</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
DDL
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<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.
|
|
|
|
<h2>2. Explanation of Symbols</h2>
|
|
|
|
This section contains a brief explanation of the symbols used in the DDL.
|
|
|
|
<PRE>
|
|
::= defined as
|
|
<tname> a token with the name tname
|
|
<a> | <b> one of <a> or <b>
|
|
<a><FONT SIZE=1.7>opt</FONT> zero or one occurrence of <a>
|
|
<a>* zero or more occurrence of <a>
|
|
<a>+ one or more occurrence of <a>
|
|
[0-9] an element in the range between 0 and 9
|
|
`[' the token within the quotes (used for special characters)
|
|
TBD To Be Decided
|
|
</pre>
|
|
|
|
<h2>3. The DDL</h2>
|
|
|
|
<dir>
|
|
<pre>
|
|
<file> ::= HDF5 <file_name> { <file_super_block><FONT SIZE=1.7>opt</FONT> <root_group> }
|
|
|
|
<file_name> ::= <identifier>
|
|
|
|
<file_super_block> ::= BOOT_BLOCK { <super_block_content> }
|
|
|
|
<super_block_content> ::= TBD
|
|
|
|
<root_group> ::= GROUP "/" {
|
|
<unamed_datatype>*
|
|
<object_id><FONT SIZE=1.7>opt</FONT>
|
|
<group_comment><FONT SIZE=1.7>opt</FONT>
|
|
<group_attribute>*
|
|
<group_member>*
|
|
}
|
|
|
|
<datatype> ::= <atomic_type> | <compound_type> | <variable_length_type> | <array_type>
|
|
|
|
<unamed_datatype> ::= DATATYPE <unamed_type_name> { <datatype> }
|
|
|
|
<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
|
|
|
|
<atomic_type> ::= <integer> | <float> | <time> | <string> |
|
|
<bitfield> | <opaque> | <reference> | <enum>
|
|
|
|
<integer> ::= 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
|
|
|
|
<float> ::= H5T_IEEE_F32BE | H5T_IEEE_F32LE |
|
|
H5T_IEEE_F64BE | H5T_IEEE_F64LE |
|
|
H5T_NATIVE_FLOAT | H5T_NATIVE_DOUBLE |
|
|
H5T_NATIVE_LDOUBLE
|
|
|
|
<time> ::= TBD
|
|
|
|
<string> ::= H5T_STRING { STRSIZE <strsize> ;
|
|
STRPAD <strpad> ;
|
|
CSET <cset> ;
|
|
CTYPE <ctype> ; }
|
|
|
|
<strsize> ::= <int_value>
|
|
|
|
<strpad> ::= H5T_STR_NULLTERM | H5T_STR_NULLPAD | H5T_STR_SPACEPAD
|
|
|
|
<cset> ::= H5T_CSET_ASCII
|
|
|
|
<ctype> ::= H5T_C_S1 | H5T_FORTRAN_S1
|
|
|
|
<bitfield> ::= TBD
|
|
|
|
<opaque> ::= H5T_OPAQUE { <identifier> }
|
|
|
|
<reference> ::= H5T_REFERENCE { <ref_type> }
|
|
|
|
<ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG
|
|
|
|
<compound_type> ::= H5T_COMPOUND { <member_type_def>+ }
|
|
|
|
<member_type_def> ::= <datatype> <field_name> ;
|
|
|
|
<field_name> ::= <identifier>
|
|
|
|
<variable_length_type> ::= H5T_VLEN { <datatype> }
|
|
|
|
<array_type> ::= H5T_ARRAY { <dim_sizes> <datatype> }
|
|
|
|
<dim_sizes> ::= `['<dimsize>`]' | `['<dimsize>`]'<dim_sizes>
|
|
|
|
<dimsize> ::= <int_value>
|
|
|
|
<attribute> ::= ATTRIBUTE <attr_name> { <dataset_type>
|
|
<dataset_space>
|
|
<data><FONT SIZE=1.7>opt</FONT> }
|
|
|
|
<attr_name> ::= <identifier>
|
|
|
|
<dataset_type> ::= DATATYPE <path_name> | <datatype>
|
|
|
|
<enum> ::= H5T_ENUM { <enum_base_type> <enum_def>+ }
|
|
|
|
<enum_base_type> ::= <integer>
|
|
// Currently enums can only hold integer type data, but they may be expanded
|
|
// in the future to hold any datatype
|
|
|
|
<enum_def> ::= <enum_symbol> <enum_val>;
|
|
|
|
<enum_symbol> ::= <identifier>
|
|
|
|
<enum_val> ::= <int_value>
|
|
|
|
<path_name> ::= <path_part>+
|
|
|
|
<path_part> ::= /<identifier>
|
|
|
|
<dataspace> ::= <scalar_space> | <simple_space> | <complex_space>
|
|
|
|
<scalar_space> ::= SCALAR
|
|
|
|
<simple_space> ::= SIMPLE { <current_dims> / <max_dims> }
|
|
|
|
<complex_space> ::= COMPLEX { <complex_space_definition> }
|
|
|
|
<dataset_space> ::= DATASPACE <path_name> | <dataspace>
|
|
|
|
<current_dims> ::= <dims>
|
|
|
|
<max_dims> ::= `(' <max_dim_list> `)'
|
|
|
|
<max_dim_list> ::= <max_dim> | <max_dim>, <max_dim_list>
|
|
|
|
<max_dim> ::= <int_value> | H5S_UNLIMITED
|
|
|
|
<complex_space_definition> ::= TBD
|
|
|
|
<data> ::= DATA { <scalar_space_data> | <simple_space_data> | <complex_space_data> } | <subset>
|
|
|
|
<scalar_space_data> ::= <any_element>
|
|
|
|
<any_element> ::= <atomic_element> | <compound_element> |
|
|
<variable_length_element> | <array_element>
|
|
|
|
<any_data_seq> ::= <any_element> | <any_element>, <any_data_seq>
|
|
|
|
<atomic_element> :: = <integer_data> | <float_data> | <time_data> |
|
|
<string_data> | <bitfield_data> | <opaque_data> |
|
|
<enum_data> | <reference_data>
|
|
|
|
<subset> ::= SUBSET { <start>;
|
|
<stride>;
|
|
<count>;
|
|
<block>;
|
|
DATA { <simple_space_data> }
|
|
}
|
|
|
|
<start> ::= START (<coor_list>)
|
|
|
|
<stride> ::= STRIDE (<pos_list>)
|
|
|
|
<count> ::= COUNT (<coor_list>)
|
|
|
|
<block> ::= BLOCK (<coor_list>)
|
|
|
|
<coor_list> ::= <int_value>, <coor_list> | <int_value>
|
|
|
|
<integer_data> ::= <int_value>
|
|
|
|
<float_data> ::= a floating point number
|
|
|
|
<time_data> ::= TBD
|
|
|
|
<string_data> ::= a string
|
|
// A string is enclosed in double quotes.
|
|
// If a string is displayed on more than one line, string concatenate
|
|
// operator '//'is used.
|
|
|
|
<bitfield_data> ::= TBD
|
|
|
|
<opaque_data> ::= TBD
|
|
|
|
<enum_data> ::= <enum_symbol>
|
|
|
|
<reference_data> ::= <object_ref_data> | <data_region_data> | NULL
|
|
|
|
<object_ref_data> ::= <object_type> <object_num>
|
|
|
|
<object_type> ::= DATASET | GROUP | DATATYPE
|
|
|
|
<object_id> ::= OBJECTID { <object_num> }
|
|
|
|
<object_num> ::= <int_value>:<int_value> | <int_value>
|
|
|
|
<data_region_data> ::= H5T_STD_REF_DSETREG <object_num> { <data_region_data_list> }
|
|
|
|
<data_region_data_list> ::= <data_region_data_info>, <data_region_data_list> | <data_region_data_info>
|
|
|
|
<data_region_data_info> ::= <region_info> | <point_info>
|
|
|
|
<region_info> ::= (<region_vals>)
|
|
|
|
<region_vals> ::= <lower_bound>:<upper_bound>, <region_vals> | <lower_bound>:<upper_bound>
|
|
|
|
<lower_bound> ::= <int_value>
|
|
|
|
<upper_bound> ::= <int_value>
|
|
|
|
<point_info> ::= (<point_vals>)
|
|
|
|
<point_vals> ::= <int_value> | <int_value>, <point_vals>
|
|
|
|
<compound_element> ::= { <any_data_seq> }
|
|
|
|
<atomic_simple_data> :: = <atomic_element>, <atomic_simple_data> | <atomic_element>
|
|
|
|
<simple_space_data> :: = <any_data_seq>
|
|
|
|
<variable_length_element> ::= ( <any_data_seq> )
|
|
|
|
<array_element> ::= `[' <any_data_seq> `]'
|
|
|
|
<complex_space_data> ::= TBD
|
|
|
|
<named_datatype> ::= DATATYPE <type_name> { <datatype> }
|
|
|
|
<type_name> ::= <identifier>
|
|
|
|
<named_dataspace> ::= TBD
|
|
|
|
<hardlink> ::= HARDLINK <path_name>
|
|
|
|
<group> ::= GROUP <group_name> { <hardlink> | <group_info> }
|
|
|
|
<group_comment> ::= COMMENT <string_data>
|
|
|
|
<group_name> ::= <identifier>
|
|
|
|
<group_info> ::= <object_id><FONT SIZE=1.7>opt</FONT> <group_comment><FONT SIZE=1.7>opt</FONT> <group_attribute>* <group_member>*
|
|
|
|
<group_attribute> ::= <attribute>
|
|
|
|
<group_member> ::= <named_datatype> | <named_dataspace> | <group> |
|
|
<dataset> | <softlink>
|
|
|
|
<dataset> ::= DATASET <dataset_name> { <hardlink> | <dataset_info> }
|
|
|
|
<dataset_info> ::= <dataset_type> <dataset_space> <storagelayout><FONT SIZE=1.7>opt</FONT>
|
|
<compression><FONT SIZE=1.7>opt</FONT> <dataset_attribute>* <object_id><FONT SIZE=1.7>opt</FONT>
|
|
<data><FONT SIZE=1.7>opt</FONT>
|
|
// Tokens above can be in any order as long as <data> is
|
|
// after <dataset_type> and <dataset_space>.
|
|
|
|
<dataset_name> ::= <identifier>
|
|
|
|
<storagelayout> :: = STORAGELAYOUT <contiguous_layout> |
|
|
STORAGELAYOUT <chunked_layout> |
|
|
STORAGELAYOUT <compact_layout> |
|
|
STORAGELAYOUT <external_layout>
|
|
|
|
<contiguous_layout> ::= {CONTIGUOUS} // default
|
|
|
|
<chunked_layout> ::= {CHUNKED <dims> }
|
|
|
|
<dims> ::= (<dims_values>)
|
|
|
|
<dims_values> ::= <int_value> | <int_value>, <dims_values>
|
|
|
|
<compact_layout> ::= TBD
|
|
|
|
<external_layout> ::= {EXTERNAL <external_file>+ }
|
|
|
|
<external_file> ::= (<file_name> <offset> <size>)
|
|
|
|
<offset> ::= <int_value>
|
|
|
|
<size> ::= <int_value>
|
|
|
|
<compression> :: = COMPRESSION { TBD }
|
|
|
|
<dataset_attribute> ::= <attribute>
|
|
|
|
<softlink> ::= SOFTLINK <softlink_name> { LINKTARGET <target> }
|
|
|
|
<softlink_name> ::= <identifier>
|
|
|
|
<target> ::= <identifier>
|
|
|
|
<identifier> ::= a string
|
|
// character '/' should be used with care.
|
|
|
|
<pos_list> ::= <pos_int>, <pos_list> | <pos_int>
|
|
|
|
<int_value> ::= 0 | <pos_int>
|
|
|
|
<pos_int> ::= [1-9][0-9]*
|
|
|
|
</PRE>
|
|
</DIR>
|
|
|
|
|
|
<H2>4. An Example of an HDF5 File in DDL</H2>
|
|
|
|
<DIR>
|
|
<PRE>
|
|
HDF5 "example.h5" {
|
|
GROUP "/" {
|
|
ATTRIBUTE "attr1" {
|
|
DATATYPE H5T_STRING {
|
|
STRSIZE 17;
|
|
STRPAD H5T_STR_NULLTERM;
|
|
CSET H5T_CSET_ASCII;
|
|
CTYPE H5T_C_S1;
|
|
}
|
|
DATASPACE SCALAR
|
|
DATA {
|
|
"string attribute"
|
|
}
|
|
}
|
|
DATASET "dset1" {
|
|
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,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
|
|
0, 1, 2, 3, 4, 5, 6, 7, 8, 9
|
|
}
|
|
}
|
|
DATASET "dset2" {
|
|
DATATYPE H5T_COMPOUND {
|
|
H5T_STD_I32BE "a";
|
|
H5T_IEEE_F32BE "b";
|
|
H5T_IEEE_F64BE "c";
|
|
}
|
|
DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
|
|
DATA {
|
|
{
|
|
1,
|
|
0.1,
|
|
0.01
|
|
},
|
|
{
|
|
2,
|
|
0.2,
|
|
0.02
|
|
},
|
|
{
|
|
3,
|
|
0.3,
|
|
0.03
|
|
},
|
|
{
|
|
4,
|
|
0.4,
|
|
0.04
|
|
},
|
|
{
|
|
5,
|
|
0.5,
|
|
0.05
|
|
}
|
|
}
|
|
}
|
|
GROUP "group1" {
|
|
COMMENT "This is a comment for group1";
|
|
DATASET "dset3" {
|
|
DATATYPE "/type1"
|
|
DATASPACE SIMPLE { ( 5 ) / ( 5 ) }
|
|
DATA {
|
|
{
|
|
[ 0, 1, 2, 3 ],
|
|
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
|
|
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
|
|
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
|
|
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
|
|
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
|
|
},
|
|
{
|
|
[ 0, 1, 2, 3 ],
|
|
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
|
|
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
|
|
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
|
|
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
|
|
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
|
|
},
|
|
{
|
|
[ 0, 1, 2, 3 ],
|
|
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
|
|
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
|
|
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
|
|
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
|
|
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
|
|
},
|
|
{
|
|
[ 0, 1, 2, 3 ],
|
|
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
|
|
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
|
|
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
|
|
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
|
|
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
|
|
},
|
|
{
|
|
[ 0, 1, 2, 3 ],
|
|
[ 0.1, 0.1, 0.1, 0.1, 0.1, 0.1,
|
|
0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
|
|
0.3, 0.3, 0.3, 0.3, 0.3, 0.3,
|
|
0.4, 0.4, 0.4, 0.4, 0.4, 0.4,
|
|
0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
DATASET "dset3" {
|
|
DATATYPE H5T_VLEN { H5T_STD_I32LE }
|
|
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
|
|
DATA {
|
|
(0), (10, 11), (20, 21, 22), (30, 31, 32, 33)
|
|
}
|
|
}
|
|
GROUP "group2" {
|
|
HARDLINK "/group1"
|
|
}
|
|
SOFTLINK "slink1" {
|
|
LINKTARGET "somevalue"
|
|
}
|
|
DATATYPE "type1" H5T_COMPOUND {
|
|
H5T_ARRAY { [4] H5T_STD_I32BE } "a";
|
|
H5T_ARRAY { [5][6] H5T_IEEE_F32BE } "b";
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
</dir>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
|
|
<br>
|
|
<a href="Files.html">Files</a>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Datatypes</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<br>
|
|
<a href="References.html">References</a>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<br>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="MountingFiles.html">Mounting Files</a>
|
|
<br>
|
|
<a href="Performance.html">Performance</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
DDL
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
Last modified: 17 November 2000
|
|
|
|
<br>
|
|
Describes HDF5 Release 1.5, Unreleased Development Branch
|
|
|
|
|
|
</body>
|
|
</html>
|