[ HDF5 Tutorial Top ] [ Next ] [ Prev ]

HDF5 Table (H5TB)


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:

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 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. For example: 

  H5TBmake_table ("Table Title", file_id, "Table1", NFIELDS, NRECORDS, dst_size, 
         field_names, dst_offset, field_type, chunk_size, fill_data, compress, p_data);

This call creates a dataset named "Table1". The dst_size parameter contains the size in bytes of the structure associated with the table. This value is obtained with sizeof. In this example:

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:

   H5TBread_table (file_id, "Table1", dst_size, dst_offset, dst_sizes, dst_buf);

The destination buffer, dst_buf, that was previously packed by H5TBmake_table, is unpacked by the H5LTrepack.

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. For example: 

   H5TBappend_records (file_id, "Table1", 1, dst_size, dst_offset, &particle[0]);

To read the records just appended from disk use the function H5TBread_records:

   H5TBread_records (file_id, "Table1", NRECORDS, NRECORDS+1, dst_size, 
            dst_offset, particle_out);

Programming Example

The following C program provide 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. In this example, the first and second records are overwritten:

   H5TBwrite_records (file_id, "Table1", 0, 2, dst_size, dst_offset, particle);

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, dst_size, 
                         dst_offset, 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, dst_size, 
                         dst_offset, 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. For example, this call will read back the entire table:

   H5TBread_fields_name (file_id, "Table1", 
              "Name,Latitude,Longitude,Pressure,Temperature",
              dst_size, dst_offset, 0, NRECORDS-1, p_data_out);

Note that since the start and end records to read from are zero based index values, the last element to read from is equal to the number of records minus one. To read a subset of all the fields, use:

   H5TBread_fields_name (file_id, "Table2", "Latitude,Longitude",0, NRECORDS-1, 
               dst_size, field_offset_pos, position_out);

Note that for the offsets of the fields of the array are initialized as:

size_t field_offset_pos[2] = { HOFFSET( Position, lati ),
                               HOFFSET( Position, longi )};

 

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. The following example will overwrite the field Pressure, writing 3 records starting at record 2: 

   H5TBwrite_fields_index (file_id, "Table1", nfields, field_index_pre, 
                      2, 3, dst_size, dst_offset, pressure_in);

Note that this function, as compared to H5TBread_fields_name, has one extra parameter, nfields, that specifies the number of fields to write. This value is also the dimension of the array pressure_in. To read individual fields by index use the function H5TBread_fields_index. For example:

   H5TBread_fields_index (file_id, "Table1", nfields,
          field_index_pre, 2, 3, dst_size, dst_offset, pressure_out);

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). For example:

   H5TBget_table_info ( file_id, "Table1", &nfields_out, &nrecords_out );

The H5TBget_field_info retrieves the names, the sizes, the offsets of the fields, as well as the size of the compound datatype. For example:

   H5TBget_field_info (file_id, "Table1", names_out, sizes_out, 
                  offset_out, size_out);

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. The H5TBdelete_record function is simple to use. A start position and the number of records to delete are all that needs to be specified. For example:

   H5TBdelete_record (file_id, "Table1", 3, 2);

This call deletes 2 records from "Table1", 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. For example: 

   H5TBinsert_record (file_id, "Table1", 3, 2, dst_size, dst_offset, data);

This function call inserts 2 records from "Table1", starting at position 3. The records that are after the inserted ones are pushed down.

Programming Example

The following C program provide 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. For example:

   H5TBadd_records_from (file_id, "Table1", start1, nrecords, "Table2", start2);

This call 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. 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. The following call combines "Table1" and "Table2" into a new table called "Table3":

   H5TBcombine_tables (file_id1, "Table1", file_id2, "Table2", "Table3");

The tables can be located in different files, identified by file_id1 and file_id2 (identifiers obtained from H5Fcreate). 

Programming Example

The following C program provides an example. 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. The following example inserts a field called "New Field" into the table named "Table1":

   H5TBinsert_field (file_id, "Table1", "New Field", field_type, 
                      position, fill_data, data); 

Programming Example

The following C program provides an example. 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. The following example deletes a field, "New Field", from the table, "Table1":

   H5TBdelete_field (file_id, "Table1", "New Field");

Programming Example

The following C program provides an example. 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.

[ HDF5 Tutorial Top ] [ Next ] [ Prev ]

The HDF Group
Last Modified:   February 20, 2007