HDF5 documents and links 
Introduction to HDF5 
HDF5 User Guide 
Other High-level API documents 		And in this document, the HDF5 Reference Manual  
H5DS   H5IM   H5LT   H5PT   H5TB  
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L  
H5O   H5P   H5R   H5S   H5T   H5Z   Tools   Datatypes  

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:

Creation

Storage

Modification

Retrieval

Query

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.

Creation

Storage

Modification

Retrieval

Query

 

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