H5TB: HDF5 Table

HDF5 Table API Reference

The HDF5 Table API defines a standard storage for HDF5 datasets that are indented 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. 

The C Interfaces:

The FORTRAN90 Interfaces: (ONLY available in HDF5-1.7 snapshots)
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: The h5tbmake_table_f function 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 each member 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 each member 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 each member 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 each member 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 *field_offset, const size_t *field_sizes, void *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 *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. These sizes can be calculated with the sizeof() macro.

void *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 *field_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 *field_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 *field_sizes, void *data)

Purpose:

Reads one or several fields. The fields are identified by its 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 *field_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 *field_sizes, void *data)

Purpose:

Reads one or several fields. The fields are identified by its 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 *field_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 type 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) 

 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

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, const size_t *field_sizes, 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.

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 *field_sizes

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

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

Last modified: March 21, 2008