Please see The HDF Group's new Support Portal for the latest information.
The HDF5 Table interface condenses the steps needed to create tables in HDF5. The datatype of the dataset that gets created is of type H5T_COMPOUND. The members of the table can have different datatypes.
Following are the topics covered in this tutorial:
- The Table Programming Model
- Making and Reading a Table
- Appending and Reading Records
- Overwriting Records
- Writing and Reading Fields by Name
- Writing and Reading Fields by Index
- Querying Functions
- Deleting Records
- Inserting Records
- Adding Records from One Table to Another
- Combining Tables
- Inserting a New Field into a Table
- Deleting a Field from a Table
If using the HDF5 interface to create tables, it requires numerous steps, but does allow for more complex structures. Refer to the Compound Datatypes tutorial topic, for creating compound datatypes with the HDF5 interface.
The Table Programming Model
In the Table programming model you must first obtain an identifier of the group or file where you want to use the Table functions and then call the appropriate function. For example:
/* Create a new HDF5 file using default properties. */
file_id = H5Fcreate ("my_table.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
/* Call some TB function */
H5TBsome_function (file_id, ...extra parameters);
/* Close the file. */
status = H5Fclose (file_id);
Alignment of Structure Fields
In the following examples a structure called Particle is used
to represent a hypothetical particle. This particle has a name, a
position (specified by latitude and longitude), pressure and temperature. The
structure is defined as:
typedef struct Particle
{
char name[16];
int lati;
int longi;
float pressure;
double temperature;
} Particle;
The sizes in bytes associated with the several types in the Particle structure are as follow, for a total size of
36 bytes.
name |
lati |
longi |
pressure |
temperature |
| 16 | 4 | 4 | 4 | 8 |
The byte-offset of fields within structures is compiler dependent though. In memory this layout can be different. Here is an example of the memory layout for the Intel86 architecture running the Microsoft Visual Studio compiler.
name |
lati |
longi |
pressure |
padding |
temperature |
| 16 | 4 | 4 | 4 | 4 | 8 |
The size of this structure in memory is 40 bytes. Four bytes of padding are inserted to make "pressure" (being a 4-byte value) start on a 4-byte boundary in memory. This (putting an n-byte item at an n-byte boundary) is called "natural alignment". It is done because most CPUs can access data faster if it is naturally aligned. Some compilers have means to force a specific structure alignment, but this is highly compiler-specific and therefore cannot be used in a portable program.
Making and Reading a Table
To create and write a table the function H5TBmake_table is used.
The following comments pertain to the ex_table_01.c programming example.
The dst_size parameter contains the size in bytes of the structure associated with
the table. This value is obtained with sizeof:
size_t dst_size = sizeof( Particle );
The parameter dst_offset is an array containing the offsets of the fields.
These values are obtained with the HOFFSET macro, which retrieves
the offset of a member from the beginning of its parent structure.
size_t dst_offset[NFIELDS] = { HOFFSET( Particle, name ),
HOFFSET( Particle, lati ),
HOFFSET( Particle, longi ),
HOFFSET( Particle, pressure ),
HOFFSET( Particle, temperature )};
The parameter field_type is an array containing the type of
each field. These values are initialized as:
string_type = H5Tcopy( H5T_C_S1 ); H5Tset_size( string_type, 16 ); field_type[0] = string_type; field_type[1] = H5T_NATIVE_INT; field_type[2] = H5T_NATIVE_INT; field_type[3] = H5T_NATIVE_FLOAT; field_type[4] = H5T_NATIVE_DOUBLE;
To read back the table the function H5TBread_table is used.
The destination buffer, dst_buf, that was previously packed
by H5TBmake_table,
is unpacked.
Programming Example
The following example demonstrates how to create and write a table with the function H5TBmake_table. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Appending and Reading Records
To append records to a table the H5TBappend_records function is used. This function adds records to the end of the table. The dataset is extended to hold the new records.
To read the records just appended from disk use the function H5TBread_records.
Programming Example
The following C program provides an example of how to append records to a table. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Overwriting Records
To overwrite records in a table use the H5TBwrite_records function. This function overwrites one or several records by specifying a start record and the number of records to write.
Programming Example
The following C program provides an example of how to overwrite records in a table. The table is initially filled with a set of fill values. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Writing and Reading Fields by Name
Individual fields can be written, either by specifying the names or indices. To overwrite fields in a table by name use the
H5TBwrite_fields_name
function. This function overwrites one or several fields by specifying their
names and a start record and the number of records to write. In the
following example,
the field Pressure is overwritten, writing three records starting at record 2:
H5TBwrite_fields_name (file_id, "Table1", "Pressure", 2, 3, sizeof( float ),
0, field_sizes_pre, pressure_in);
To overwrite the latitude and longitude fields, again writing 3 records starting at record 2, use:
H5TBwrite_fields_name (file_id, "Table1", "Latitude,Longitude", 2, 3,
sizeof( Position ), field_offset_pos, field_sizes_pos, position_in);
The data buffer of this call is of type Particle, defined
as:
typedef struct Position
{
int lati;
int longi;
} Position;
To read individual fields from disk use the function H5TBread_fields_name.
Programming Example
The following C program provides an example of how to overwrite fields in a table, by specifying the field names.
Writing and Reading Fields by Index
Individual fields can also be written by specifying their indices. To overwrite fields in a table by index the H5TBwrite_fields_index function is used. This function overwrites one or several fields by specifying their indices, a start record and the number of records to write.
Note that H5TBwrite_fields_index, as compared to
H5TBread_fields_name,
has one extra parameter, nfields, that specifies the number of
fields to write.
To read individual fields by index use the function
H5TBread_fields_index.
Programming Example
The following C program provides an example of how to overwrite fields in a table, by specifying the field indices.
Querying Functions
Information about a table can be retrieved using two functions, H5TBget_table_info and H5TBget_field_info. The H5TBget_table_info retrieves the table dimensions (the number of records and the number of fields).
The H5TBget_field_info retrieves the names, the sizes, the offsets of the fields, as well as the size of the compound datatype.
Programming Example
The following C program provides an example of how to retrieve information from a table. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Deleting Records
Several contiguous records can be deleted from a table using the H5TBdelete_record function. This function is simple to use. A start position and the number of records to delete are all that needs to be specified. For example:
status=H5TBdelete_record ( file_id, TABLE_NAME, 3, 3 );
The above call deletes 3 records from a table, starting at position 3. Note that this position is a zero index based position. The records that are after the deleted ones are pulled up.
Programming Example
The following C program provides an example of how to use this function. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Inserting Records
It is possible to insert records in any position of a table. To insert records in a table the H5TBinsert_record function is used. This function is similar to the H5TBdelete_record function, but has an extra parameter for the data being written.
Programming Example
The following C program provides an example of how to insert records in a table. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Adding Records from One Table to Another
The H5TBadd_records_from function is used to add records from one table to another.
The following example reads nrecords records from "table1", starting at
position start1, and inserts those records into "table2", starting at
position start2.
Programming Example
The following C program provides an example of adding records from one table to another. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Combining Tables
Two tables can be combined into a third, using the function
H5TBcombine_tables.
To use this function only the names of the tables are necessary.
In the following example, two tables,
"table1" and "table2" are
combined into a new table called "table3":
The tables can be located in different files, identified by the file identifiers obtained from opening or creating the file.
Programming Example
The following C program provides an example of combining tables. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Inserting a New Field into a Table
A new field can be inserted into a table, using the function H5TBinsert_field. To use this function, the field name, its type, the position where to insert the field and the data to insert in the table must be supplied.
Programming Example
The following C program provides an example of inserting a new field into a table. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
Deleting a Field from a Table
The function H5TBdelete_field is used to delete a field from a table. To use this function only the field name is supplied.
Programming Example
The following C program provides an example of deleting a field from a table. The corresponding HDF5 file that is generated is also referenced here. You can use an HDF5 file browser to access this file by clicking on the link below.
- - Last modified: 21 December 2016