hdf images hdf images

HDF5 Tutorial: 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 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: 02 July 2013