mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Convert HL table spec file to doxygen (#5149)
This commit is contained in:
Allen Byrne
@@ -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>
|
||||
<caption><b>Table 1. Attributes of an Image Dataset</b></caption>
|
||||
<tr>
|
||||
<th><b>Attribute Name</b></th>
|
||||
<th><b>Required</b><br /><b>Optional</b></th>
|
||||
<th><b>Type</b></th>
|
||||
<th><b>String Size</b></th>
|
||||
<th><b>Value</b></th>
|
||||
<th><b>Description</b></th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>CLASS</td>
|
||||
<td>Required</td>
|
||||
<td>String</td>
|
||||
<td>5</td>
|
||||
<td>"TABLE"</td>
|
||||
<td>This attribute is type #H5T_C_S1, with size 5. For all Tables, the value of this attribute is
|
||||
<b>TABLE</b>. This attribute identifies this data set as intended to be interpreted as Table that
|
||||
conforms to the specifications on this page.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>VERSION</td>
|
||||
<td>Required</td>
|
||||
<td>String</td>
|
||||
<td>3</td>
|
||||
<td>"0.2"</td>
|
||||
<td>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".</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TITLE</td>
|
||||
<td>Optional</td>
|
||||
<td>String</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>The <b>TITLE</b> is an optional String that is to be used as the informative title of the whole table.
|
||||
The <b>TITLE</b> is set with the parameter table_title of the function #H5TBmake_table.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FIELD_(n)_NAME</td>
|
||||
<td>Required</td>
|
||||
<td>String</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>The <b>FIELD_(n)_NAME</b> 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 <b>FIELD_</b> is concatenated with the zero based field (n)
|
||||
index together with the name of the field.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FIELD_(n)_FILL</td>
|
||||
<td>Optional</td>
|
||||
<td>String</td>
|
||||
<td> </td>
|
||||
<td> </td>
|
||||
<td>The <b>FIELD_(n)_FILL</b> is an optional String that is the fill value for column n of the table.
|
||||
For each of the fields the word <b>FIELD_</b> 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.</td>
|
||||
</tr>
|
||||
</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
|
||||
|
||||
*/
|
||||
|
||||
@@ -1,193 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>HDF5 Table Specification</title>
|
||||
</head>
|
||||
|
||||
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.
|
||||
|
||||
<h2>
|
||||
1. Overview</h2>
|
||||
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.
|
||||
<p>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.
|
||||
<h2>
|
||||
2. Table Attributes</h2>
|
||||
The attributes for the Table are strings. They are written with the <a href="RM_H5LT.html#H5LTset_attribute_string"><code>H5LTset_attribute_string</code></a>
|
||||
Lite API function. "Required" attributes must always be used. "Optional" attributes
|
||||
must be used when required.
|
||||
<br>
|
||||
<h4>
|
||||
Attributes</h4>
|
||||
|
||||
<dl>
|
||||
<dt>
|
||||
Attribute name="<b>CLASS</b>" (Required)</dt>
|
||||
|
||||
<dd>
|
||||
This attribute is type H5T_C_S1, with size 5.</dd>
|
||||
|
||||
<dd>
|
||||
For all Tables, the value of this attribute is "TABLE".</dd>
|
||||
|
||||
<dd>
|
||||
This attribute identifies this data set as intended to be interpreted as Table that conforms to the specifications on this page.</dd>
|
||||
</dl>
|
||||
|
||||
<dl>
|
||||
Attribute name="<b>VERSION</b>" (Required)
|
||||
|
||||
<dd>
|
||||
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".</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
<dl>
|
||||
<dt>
|
||||
Attribute name="<b>TITLE</b>" (Optional)</dt>
|
||||
|
||||
<dd>
|
||||
The <b>TITLE</b> is an optional String that is to be used as the
|
||||
informative title of the whole table.
|
||||
The <b>TITLE</b> is set with the parameter <code> table_title</code> of the function
|
||||
<a href="RM_H5TB.html#H5TBmake_table"> <code> H5TBmake_table</code></a>. </dd>
|
||||
</dl>
|
||||
|
||||
<dl>
|
||||
<dt>
|
||||
Attribute name="<b>FIELD_(n)_NAME</b>" (Required)</dt>
|
||||
|
||||
<dd>
|
||||
The <b>FIELD_(n)_NAME</b> is an optional String that is to be used as the
|
||||
informative title of column <b>n</b> 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.</dd>
|
||||
|
||||
</dl>
|
||||
<dl>
|
||||
<dt>
|
||||
Attribute name="<b>FIELD_(n)_FILL</b>" (Optional)</dt>
|
||||
|
||||
<dd>
|
||||
The <b>FIELD_(n)_FILL</b> is an optional String that is the fill value for
|
||||
column <b>n</b> 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.</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
<dl>
|
||||
|
||||
<br>
|
||||
<center><table BORDER=2 BGCOLOR="#FFFFFF" >
|
||||
<caption><b>Table 1. Attributes of an Image Dataset</b></caption>
|
||||
|
||||
<tr>
|
||||
<td><b>Attribute Name</b></td>
|
||||
|
||||
<td><b>(R = Required</b>
|
||||
<br><b>O= Optional)</b></td>
|
||||
|
||||
<td><b>Type</b></td>
|
||||
|
||||
<td><b>String Size</b></td>
|
||||
|
||||
<td><b>Value</b></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>CLASS</td>
|
||||
|
||||
<td>R</td>
|
||||
|
||||
<td>String</td>
|
||||
|
||||
<td>5</td>
|
||||
|
||||
<td>"TABLE"</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>VERSION</td>
|
||||
|
||||
<td>R</td>
|
||||
|
||||
<td>String</td>
|
||||
|
||||
<td>3</td>
|
||||
|
||||
<td>"0.2"</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>TITLE</td>
|
||||
|
||||
<td>O</td>
|
||||
|
||||
<td>String</td>
|
||||
|
||||
<td> </td>
|
||||
|
||||
<td>
|
||||
|
||||
<tr>
|
||||
<td>FIELD_(n)_NAME</td>
|
||||
|
||||
<td>R</td>
|
||||
|
||||
<td>String</td>
|
||||
|
||||
<td> </td>
|
||||
|
||||
<td>
|
||||
|
||||
|
||||
<tr>
|
||||
<td>FIELD_(n)_FILL</td>
|
||||
|
||||
<td>O*</td>
|
||||
|
||||
<td>String</td>
|
||||
|
||||
<td> </td>
|
||||
|
||||
<td>
|
||||
|
||||
</table>
|
||||
</center>
|
||||
|
||||
</dl>
|
||||
<p>
|
||||
<center>
|
||||
|
||||
</center>
|
||||
<i>* </i>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.<p>The following
|
||||
section of code shows the calls necessary to the creation of a table.
|
||||
|
||||
<p><code>/* Create a new HDF5 file using default properties. */<br>
|
||||
file_id = H5Fcreate( "my_table.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT );</code> </p>
|
||||
|
||||
<p><code>/* Call the make table function */<br>
|
||||
</code> <code>H5TBmake_table( "Table Title", file_id, "Table1", NFIELDS, NRECORDS, dst_size, <br>
|
||||
field_names, dst_offset, field_type, <br>
|
||||
chunk_size, fill_data, compress, p_data ) </code> </p>
|
||||
|
||||
<p><code> /* Close the file. */<br>
|
||||
status = H5Fclose( file_id );</code> </p>
|
||||
|
||||
</body>
|
||||
Reference in New Issue
Block a user