diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox index 77bb0a8f407..de9c23d80aa 100644 --- a/doxygen/dox/Specifications.dox +++ b/doxygen/dox/Specifications.dox @@ -54,7 +54,101 @@ */ /** \page TBL HDF5 Table Specification Version 1.0 +The HDF5 specification defines the standard objects and storage for the standard HDF5 +objects. (For information about the HDF5 library, model and specification, see the HDF +documentation.) This document is an additional specification do define a standard profile +for how to store tables in HDF5. Table data in HDF5 is stored as HDF5 datasets with standard +attributes to define the properties of the tables. + +\section sec_tab_spec_intro Introduction +A generic table is a sequence of records, each record has a name and a type. Table data +is stored as an HDF5 one dimensional compound dataset. A table is defined as a collection +of records whose values are stored in fixed-length fields. All records have the same structure +and all values in each field have the same data type. + +The dataset for a table is distinguished from other datasets by giving it an attribute +"CLASS=TABLE". Optional attributes allow the storage of a title for the Table and for +each column, and a fill value for each column. + +\section sec_tab_spec_attr Table Attributes +The attributes for the Table are strings. They are written with the #H5LTset_attribute_string +Lite API function. "Required" attributes must always be used. "Optional" attributes must be +used when required. +
| Attribute Name | +Required Optional |
+Type | +String Size | +Value | +Description | +
|---|---|---|---|---|---|
| CLASS | +Required | +String | +5 | +"TABLE" | +This attribute is type #H5T_C_S1, with size 5. For all Tables, the value of this attribute is +TABLE. This attribute identifies this data set as intended to be interpreted as Table that +conforms to the specifications on this page. | +
| VERSION | +Required | +String | +3 | +"0.2" | +This attribute is of type #H5T_C_S1, with size corresponding to the length of the version string. +This attribute identifies the version number of this specification to which it conforms. The current +version number is "0.2". | +
| TITLE | +Optional | +String | ++ | + | The TITLE is an optional String that is to be used as the informative title of the whole table. +The TITLE is set with the parameter table_title of the function #H5TBmake_table. | +
| FIELD_(n)_NAME | +Required | +String | ++ | + | The FIELD_(n)_NAME is an optional String that is to be used as the informative title of column n +of the table. For each of the fields the word FIELD_ is concatenated with the zero based field (n) +index together with the name of the field. | +
| FIELD_(n)_FILL | +Optional | +String | ++ | + | The FIELD_(n)_FILL is an optional String that is the fill value for column n of the table. +For each of the fields the word FIELD_ is concatenated with the zero based field (n) index +together with the fill value, if present. This value is written only when a fill value is defined +for the table. | +
The dataset for a table is distinguished from other datasets by giving -it an attribute "CLASS=TABLE". -Optional attributes allow the storage of a title for the Table and for -each column, and a fill value for each column. -
H5LTset_attribute_string
-Lite API function. "Required" attributes must always be used. "Optional" attributes
-must be used when required.
- table_title of the function
- H5TBmake_table. | Attribute Name | - -(R = Required
- O= Optional) |
-
-Type | - -String Size | - -Value | -
| CLASS | - -R | - -String | - -5 | - -"TABLE" | -
| VERSION | - -R | - -String | - -3 | - -"0.2" | -
| TITLE | - -O | - -String | - -- - | - - |
| FIELD_(n)_NAME | - -R | - -String | - -- - | - - - |
| FIELD_(n)_FILL | - -O* | - -String | - -- - | - - |
-
The following -section of code shows the calls necessary to the creation of a table. - -
/* Create a new HDF5 file using default properties. */
- file_id = H5Fcreate( "my_table.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT );
/* Call the make table function */
-H5TBmake_table( "Table Title", file_id, "Table1", NFIELDS, NRECORDS, dst_size,
- field_names, dst_offset, field_type,
- chunk_size, fill_data, compress, p_data )
/* Close the file. */
- status = H5Fclose( file_id );