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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Attributes of an Image Dataset
Attribute NameRequired
Optional
TypeString SizeValueDescription
CLASSRequiredString5"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.
VERSIONRequiredString3"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".
TITLEOptionalString  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)_NAMERequiredString  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)_FILLOptionalString  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 following section of code shows the calls necessary to the creation of a table. +\code +// 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); +\endcode + +For more information see the @ref H5TB reference manual page and the @ref H5TB_UG, which includes examples. -\htmlinclude TableSpec.html */ diff --git a/doxygen/examples/TableSpec.html b/doxygen/examples/TableSpec.html deleted file mode 100644 index 474176e14d5..00000000000 --- a/doxygen/examples/TableSpec.html +++ /dev/null @@ -1,193 +0,0 @@ - - - HDF5 Table Specification - - -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. - -

-1. Overview

-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. -

-2.  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. -
  -

-Attributes

- -
-
-Attribute name="CLASS" (Required)
- -
-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.
-
- -
-Attribute name="VERSION" (Required) - -
-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".
- -
- -
-
-Attribute name="TITLE" (Optional)
- -
-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. 
-
- -
-
-Attribute name="FIELD_(n)_NAME" (Required)
- -
-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.
- -
-
-
-Attribute name="FIELD_(n)_FILL" (Optional)
- -
-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.
- -
- -
- -
  -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Table 1. Attributes of an Image Dataset
Attribute Name(R = Required -
O= Optional)
TypeString SizeValue
CLASSRString5"TABLE"
VERSIONRString3"0.2"
TITLEOString  - -
FIELD_(n)_NAMERString  -  - -
FIELD_(n)_FILLO*String  -  -
-
- -
-

-

-  -
-* The attribute FIELD_(n)_FILL is written to the table if a fill value is -specified on the creation of the Table. Otherwise, it is not.

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 );

- -