H5TB: HDF5 Table

HDF5 Table API Reference

The HDF5 Table API defines a standard storage for HDF5 datasets that are intended to be interpreted as tables. 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 following functions are part of the HDF5 Table API.

Programming Hints:

To use any of these functions or subroutines, you must first include the relevant include file (C) or module (Fortran) in your application.

The following line includes the HDF5 Table package, H5TB, in C applications:

    #include "hdf5_hl.h"

The following line includes the H5TB module in Fortran applications:

    use h5tb

The C Interfaces:

The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task as the corresponding C function. There are four types supported: integer, real, double precision and character array. The <TYPE> notation below is one of these four types.  In FORTRAN, only the functions that read and write data by fields are  available. The h5tbmake_table_f function only creates the table, it does not write data to it.

Name: H5TBmake_table

Signature:

herr_t H5TBmake_table( const char *table_title, hid_t loc_id, const char *dset_name, hsize_t nfields, const hsize_t nrecords, size_t type_size, const char *field_names [ ], const size_t *field_offset, const hid_t *field_types, hsize_t chunk_size, void *fill_data, int compress, const void *data )

Purpose:

Creates and writes a table.

Description:

H5TBmake_table creates and writes a dataset named table_name attached to the object specified by the identifier loc_id.

Parameters:

const char *table_title	IN: The title of the table.
hid_t loc_id	IN: Identifier of the file or group to create the table within.
const char *table_name	IN: The name of the dataset to create.
hsize_t nfields	IN: The number of fields.
const hsize_t nrecords	IN: The number of records.
hsize_t type_size	IN: The size in bytes of the structure associated with the table. This value is obtained with sizeof.
const char *field_names[]	IN: An array containing the names of the fields.
const size_t *field_offset	IN: An array containing the offsets of the fields.
const hid_t *field_types	IN: An array containing the type of the fields.
hsize_t chunk_size	IN: The chunk size.
void *fill_data	IN: Fill values data.
int compress	IN: Flag that turns compression on or off.
const void *data	IN: Buffer with data to be written to the table.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbmake_table_f

Note: h5tbmake_table_f only creates the table, it does not write data to it.

subroutine h5tbmake_table_f(table_title, loc_id, dset_name, nfields, &
                            nrecords, type_size, field_names, field_offset, &
                            field_types, chunk_size, compress, errcode) 
  implicit none
  character(LEN=*), intent(IN) :: table_title     ! name of the table
  integer(HID_T), intent(IN) :: loc_id            ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name       ! name of the dataset 
  integer(HSIZE_T), intent(IN) :: nfields         ! fields 
  integer(HSIZE_T), intent(IN) :: nrecords        ! records
  integer(SIZE_T), intent(IN) :: type_size        ! type size
  character(LEN=*), dimension(nfields), intent(IN) :: field_names
                                                  ! field names
  integer(SIZE_T), dimension(nfields), intent(IN) :: field_offset
                                                  ! field offset
  integer(HID_T), dimension(nfields), intent(IN) :: field_types
                                                  ! field types
  integer(HSIZE_T), intent(IN) :: chunk_size      ! chunk size
  integer, intent(IN) :: compress                 ! compress
  integer :: errcode                              ! error code
end subroutine h5tbmake_table_f
      

Name: H5TBappend_records

Signature:

herr_t H5TBappend_records ( hid_t loc_id, const char *dset_name, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *field_sizes, const void *data )

Purpose:

Adds records to the end of the table.

Description:

H5TBappend_records adds records to the end of the table named dset_name attached to the object specified by the identifier loc_id. The dataset is extended to hold the new records.

Parameters:

hid_t loc_id

IN: Identifier of the file or group where the table is located.

const char *dset_name

IN: The name of the dataset to overwrite.

hsize_t nrecords

IN: The number of records to append.

size_t type_size

IN: The size of the structure type, as calculated by sizeof().

const size_t *field_offset

IN: An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro.

const size_t *field_sizes

IN: An array containing the sizes of the fields.

const void *data

IN: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBwrite_records

Signature:

herr_t H5TBwrite_records ( hid_t loc_id, const char *table_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *field_sizes, const void *data>)

Purpose:

Overwrites records.

Description:

H5TBwrite_records overwrites records starting at the zero index position start of the table named table_name attached to the object specified by the identifier loc_id.

Parameters:

hid_t loc_id

IN: Identifier of the file or group where the table is located.

const char *table_name

IN: The name of the dataset to overwrite.

hsize_t start

IN: The zero index record to start writing. 

hsize_t nrecords

IN: The number of records to write.

size_t type_size

IN: The size of the structure type, as calculated by sizeof().

const size_t *field_offset

IN: An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro.

const size_t *field_sizes

IN: An array containing the sizes of the fields.

const void *data

IN: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBwrite_fields_name

Signature:

herr_t H5TBwrite_fields_name ( hid_t loc_id, const char *table_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *field_sizes, const void *data )

Purpose:

Overwrites fields.

Description:

H5TBwrite_fields_name overwrites one or several fields contained in the buffer field_names from a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group where the table is located.

const char *table_name

IN: The name of the dataset to overwrite.

const char * field_names

IN: The names of the fields to write.

hsize_t start

IN: The zero based index record to start writing. 

hsize_t nrecords

IN: The number of records to write.

size_t type_size

IN: The size of the structure type, as calculated by sizeof().

const size_t *field_offset

IN: An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro.

const size_t *field_sizes

IN: An array containing the sizes of the fields.

void *data

IN: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbwrite_field_name_f

subroutine h5tbwrite_field_name_f(loc_id, dset_name, field_name, start, &
                                  nrecords, type_size, buf, errcode) 

  implicit none
  integer(HID_T), intent(IN) :: loc_id           ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name      ! name of the dataset 
  character(LEN=*), intent(IN) :: field_name     ! name of the field
  integer(HSIZE_T), intent(IN) :: start          ! start record 
  integer(HSIZE_T), intent(IN) :: nrecords       ! records
  integer(SIZE_T), intent(IN) :: type_size       ! type size
  <TYPE>, intent(IN), dimension(*) :: buf        ! data buffer 
  integer :: errcode                             ! error code

end subroutine h5tbwrite_field_name_f
      

Name: H5TBwrite_fields_index

Signature:

herr_t H5TBwrite_fields_index ( hid_t loc_id, const char *table_name, int nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t* field_sizes, const void *data )

Purpose:

Overwrites fields.

Description:

H5TBwrite_fields_index overwrites one or several fields contained in the buffer field_index from a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group where the table is located.

const char *table_name

IN: The name of the dataset to overwrite.

int nfields

IN: The number of fields to overwrite. This parameter is also the size of the field_index array.

const int *field_index

IN: The indexes of the fields to write.

hsize_t start

IN: The zero based index record to start writing. 

hsize_t nrecords

IN: The number of records to write.

size_t type_size

IN: The size of the structure type, as calculated by sizeof().

const size_t *field_offset

IN: An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro.

const size_t *field_sizes

IN: An array containing the sizes of the fields.

void *data

IN: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbwrite_field_index_f

subroutine h5tbwrite_field_index_f(loc_id, dset_name, field_index, start, &
                                   nrecords, type_size, buf, errcode)
  implicit none
  integer(HID_T), intent(IN) :: loc_id           ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name      ! name of the dataset 
  integer, intent(IN) :: field_index             ! index
  integer(HSIZE_T), intent(IN) :: start          ! start record 
  integer(HSIZE_T), intent(IN) :: nrecords       ! records
  integer(SIZE_T), intent(IN) :: type_size       ! type size
  <TYPE>, intent(IN), dimension(*) :: buf        ! data buffer 
  integer :: errcode                             ! error code
end subroutine h5tbwrite_field_index_f
      

Name: H5TBread_table

Signature:

herr_t H5TBread_table( hid_t loc_id, const char *table_name, size_t dst_size,  const size_t *dst_offset, const size_t *dst_sizes, void *dst_buf )

Purpose:

Reads a table.

Description:

H5TBread_table reads a table named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group to read the table within.

const char *table_name

IN: The name of the dataset to read.

size_t dst_size

IN: The size of the structure type, as calculated by sizeof().

const size_t *dst_offset

IN: An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro.

const size_t  *dst_sizes

IN: An array containing the sizes of the fields. These sizes can be calculated with the sizeof() macro.

void *dst_buf

OUT: Buffer with data. 

 

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBread_records

Signature:

herr_t H5TBread_records ( hid_t loc_id, const char *table_name, hsize_t start, hsize_t nrecords, size_t type_size,  const size_t *field_offset, const size_t *dst_sizes,  void *data )

Purpose:

Reads records.

Description:

H5TBread_records reads some records identified from a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group to read the table within.

const char *table_name

IN: The name of the dataset to read.

hsize_t  start

IN: The start record to read from.

hsize_t nrecords

IN: The number of records to read.

size_t type_size

IN: The size of the structure type, as calculated by sizeof().

const size_t *field_offset

IN: An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro.

const size_t *dst_sizes

IN: An array containing the size in bytes of the fields.

void *data

OUT: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBread_fields_name

Signature:

herr_t H5TBread_fields_name ( hid_t loc_id, const char *table_name, const char * field_names, hsize_t start, hsize_t nrecords, size_t type_size,  const size_t *field_offset, const size_t *dst_sizes, void *data)

Purpose:

Reads one or several fields. The fields are identified by name.

Description:

H5TBread_fields_name reads the fields identified by  field_names from a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group to read the table within.

const char *table_name

IN: The name of the dataset to read.

const char * field_names

IN: An array containing the names of the fields to read.

hsize_t  start

IN: The start record to read from.

hsize_t nrecords

IN: The number of records to read.

hsize_t type_size

IN: The size in bytes of the structure associated with the table. This value is obtained with sizeof.

const size_t *field_offset

IN: An array containing the offsets of the fields.

const size_t *dst_sizes

IN: An array containing the size in bytes of the fields.

void *data

OUT: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbread_field_name_f

subroutine h5tbread_field_name_f(loc_id, dset_name, field_name, start, &
                                 nrecords, type_size, buf, errcode) 
  implicit none
  integer(HID_T), intent(IN) :: loc_id           ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name      ! name of the dataset 
  character(LEN=*), intent(IN) :: field_name     ! name of the field
  integer(HSIZE_T), intent(IN) :: start          ! start record 
  integer(HSIZE_T), intent(IN) :: nrecords       ! records
  integer(SIZE_T), intent(IN) :: type_size       ! type size
  <TYPE>, intent(IN), dimension(*) :: buf        ! data buffer 
  integer :: errcode                             ! error code
end subroutine h5tbread_field_name_f
      

Name: H5TBread_fields_index

Signature:

herr_t H5TBread_fields_index ( hid_t loc_id, const char *table_name, int nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size,  const size_t *field_offset, const size_t *dst_sizes, void *data)

Purpose:

Reads one or several fields. The fields are identified by index.

Description:

H5TBread_fields_index reads the fields identified by  field_index from a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group to read the table within.

const char *table_name

IN: The name of the dataset to read.

int nfields

IN: The number of fields to overwrite. This parameter is also the size of the field_index array.

const int * field_index

IN: The indexes of the fields to write.

hsize_t  start

IN: The start record to read from.

hsize_t nrecords

IN: The number of records to read.

hsize_t type_size

IN: The size in bytes of the structure associated with the table. This value is obtained with sizeof.

const size_t *field_offset

IN: An array containing the offsets of the fields.

const size_t *dst_sizes

IN: An array containing the size in bytes of the fields.

void *data

OUT: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbread_field_index_f

subroutine h5tbread_field_index_f(loc_id, dset_name, field_index, start, & 
                                  nrecords, type_size, buf, errcode) 
  implicit none
  integer(HID_T), intent(IN) :: loc_id           ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name      ! name of the dataset 
  integer, intent(IN) :: field_index             ! index
  integer(HSIZE_T), intent(IN) :: start          ! start record 
  integer(HSIZE_T), intent(IN) :: nrecords       ! records
  integer(SIZE_T), intent(IN) :: type_size       ! type size
  <TYPE>, intent(IN), dimension(*) :: buf        ! data buffer 
  integer :: errcode                             ! error code
end subroutine h5tbread_field_index_f
      

Name: H5TBget_table_info

Signature:

herr_t H5TBget_table_info ( hid_t loc_id, const char *table_name, hsize_t *nfields, hsize_t *nrecords )

Purpose:

Gets the table dimensions.

Description:

H5TBget_dimensions retrieves the table dimensions from a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group to read the table within.

const char *table_name

IN: The name of the dataset to read.

hsize_t *nfields

OUT: The number of fields.

hsize_t *nrecords

OUT: The number of records.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbget_table_info_f

subroutine h5tbget_table_info_f(loc_id, dset_name, nfields, nrecords, errcode) 

  implicit none
  integer(HID_T), intent(IN) :: loc_id        ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name   ! name of the dataset 
  integer(HSIZE_T), intent(INOUT):: nfields   ! nfields 
  integer(HSIZE_T), intent(INOUT):: nrecords  ! nrecords 
  integer :: errcode                          ! error code
end subroutine h5tbget_table_info_f
      

Name: H5TBget_field_info

Signature:

herr_t H5TBget_field_info ( hid_t loc_id, const char *table_name, char *field_names[], size_t *field_sizes, size_t *field_offsets, size_t *type_size  )

Purpose:

Gets information about a table.

Description:

H5TBget_field_info gets information about a dataset named table_name attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group to read the table within.

const char *table_name

IN: The name of the dataset to read.

char *field_names[]

OUT: An array containing the names of the fields.

size_t *field_sizes

OUT: An array containing the size of the fields.

size_t *field_offsets

OUT: An array containing the offsets of the fields.

size_t *type_size

OUT: The size of the HDF5 datatype associated with the table.
More specifically, the size in bytes of the HDF5 compound datatype used to define a row, or record, in the table.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbget_field_info_f

subroutine h5tbget_field_info_f(loc_id, dset_name, nfields, field_names, & 
                                field_sizes, field_offsets, type_size, & 
                                errcode, maxlen_out)
  implicit none
  integer(HID_T), intent(IN) :: loc_id         ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name    ! name of the dataset 
  integer(HSIZE_T), intent(IN):: nfields       ! nfields 
  character(LEN=*), dimension(nfields), intent(INOUT) :: field_names    
                                               ! field names
  integer(SIZE_T), dimension(nfields), intent(INOUT) :: field_sizes    
                                               ! field sizes
  integer(SIZE_T), dimension(nfields), intent(INOUT) :: field_offsets  
                                               ! field offsets
  integer(SIZE_T), intent(INOUT):: type_size   ! type size 
  integer :: errcode                           ! error code
  integer, optional :: maxlen_out              ! returns maximum character 
                                               ! length of field_names
end subroutine h5tbget_field_info_f
      

Name: H5TBdelete_record

Signature:

herr_t H5TBdelete_record ( hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords )

Purpose:

Delete records.

Description:

H5TBdelete_record deletes records from middle of table ("pulling up" all the records after it)

Parameters:

hid_t loc_id

IN: Identifier of the file or group in which the table is located.

const char *dset_name

IN: The name of the dataset.

hsize_t  start

IN: The start record to delete from.

hsize_t nrecords

IN: The number of records to delete.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBinsert_record

Signature:

herr_t H5TBinsert_record (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size,  const size_t *field_offset, void *data  )

Purpose:

Insert records.

Description:

H5TBinsert_record inserts records into the middle of the table ("pushing down" all the records after it)

Parameters:

hid_t loc_id

IN: Identifier of the file or group in which the table is located.

const char *dset_name

IN: The name of the dataset.

hsize_t  start

IN: The position to insert.

hsize_t nrecords

IN: The number of records to insert.

void *data

IN: Buffer with data.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBadd_records_from

Signature:

herr_t H5TBadd_records_from ( hid_t loc_id, const char *dset_name1, hsize_t start1, hsize_t nrecords, const char *dset_name2, hsize_t start2 )

Purpose:

Add records from first table to second table.

Description:

H5TBadd_records_from adds records from a dataset named dset_name1 to a dataset named dset_name2. Both tables are attached to the object specified by the identifier loc_id. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group in which the table is located.

const char *dset_name1

IN: The name of the dataset to read the records.

hsize_t  start1

IN: The position to read the records from the first table

hsize_t nrecords

IN: The number of records to read from the first table.

const char *dset_name2

IN: The name of the dataset to write the records.

hsize_t  start2

IN: The position to write the records on the second table

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBcombine_tables

Signature:

herr_t H5TBcombine_tables ( hid_t loc_id1, const char *dset_name1, hid_t loc_id2, const char *dset_name2,  const char *dset_name3 )

Purpose:

Combines records from two tables into a third.

Description:

H5TBcombine_tables combines records from two datasets named dset_name1 and dset_name2, to a new table named dset_name3. These tables can be located on different files, identified by loc_id1 and loc_id2 (identifiers obtained with H5Fcreate). They can also be located on the same file. In this case one uses the same identifier for both parameters  loc_id1 and loc_id2. If two files are used, the third table is written on the first file.

Parameters:

hid_t loc_id1

IN: Identifier of the file or group in which the first table is located.

const char *dset_name1

IN: The name of the first table to combine.

hid_t loc_id2

IN: Identifier of the file or group in which the second table is located.

const char *dset_name2

IN: The name of the second table to combine.

const char *dset_name3

IN: The name of the new table.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5TBinsert_field

Signature:

herr_t H5TBinsert_field ( hid_t loc_id, const char *dset_name, const char *field_name,  hid_t field_type, hsize_t position, const void *fill_data, const void *data )

Purpose:

Insert a new field into a table.

Description:

H5TBinsert_field inserts a new field named field_name into the table dset_name. Note: this function requires the table to be re-created and rewritten in its entirety, and this can result in some unused space in the file, and can also take a great deal of time if the table is large. 

 

Parameters:

hid_t loc_id

IN: Identifier of the file or group in which the table is located.

const char *dset_name

IN: The name of the table.

const char *field_name

IN: The name of the field to insert.

hid_t field_type

IN: The data type of the field.

hize_t position

IN: The zero based index position where to insert the field.

void *fill_data

IN: Fill value data for the field. This parameter can be NULL.

const void *data

IN: Buffer with data.

 Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbinsert_field_f

subroutine h5tbinsert_field_f(loc_id, dset_name, field_name, field_type, &
                              field_index, buf, errcode )
  implicit none
  integer(HID_T), intent(IN) :: loc_id           ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name      ! name of the dataset 
  character(LEN=*), intent(IN) :: field_name     ! name of the field
  integer(HID_T), intent(IN)   :: field_type     ! field type
  integer, intent(IN) :: field_index             ! field_index
  <TYPE>, intent(IN), dimension(*) :: buf        ! data buffer 
  integer :: errcode                             ! error code
end subroutine h5tbinsert_field_f
      

Name: H5TBdelete_field

Signature:

herr_t H5TBdelete_field ( hid_t loc_id, const char *dset_name, const char *field_name )

Purpose:

Deletes a field from a table.

Description:

H5TBdelete_field deletes a  field named field_name from the table dset_name. Note: this function requires the table to be re-created and rewritten in its entirety, and this can result in some unused space in the file, and can also take a great deal of time if the table is large.

Parameters:

hid_t loc_id

IN: Identifier of the file or group in which the table is located.

const char *dset_name

IN: The name of the table.

const char *field_name

IN: The name of the field to delete.

 Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Fortran90 Interface: h5tbdelete_field_f

subroutine h5tbdelete_field_f(loc_id, dset_name, field_name, errcode)
  implicit none
  integer(HID_T), intent(IN) :: loc_id        ! file or group identifier 
  character(LEN=*), intent(IN) :: dset_name   ! name of the dataset 
  character(LEN=*), intent(IN) :: field_name  ! name of the field
  integer :: errcode                          ! error code
end subroutine h5tbdelete_field_f
      

The HDF Group Help Desk: Describes HDF5 Release 1.8.18, November 2016.

Copyright by The HDF Group and the Board of Trustees of the University of Illinois