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:
|
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 |
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
)
H5TBmake_table creates and writes a dataset named
table_name attached to the object specified by the
identifier loc_id.
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. |
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
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
)
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.
loc_id
dset_name
nrecordstype_size sizeof(). field_offset field_sizes data 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>)
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. loc_id table_name start nrecords type_size sizeof(). field_offset field_sizes data 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
)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. loc_id table_name field_names start nrecords type_size sizeof(). field_offset field_sizes data
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
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
)
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. loc_id table_name fields field_index array. field_index start nrecords type_size sizeof(). field_offset field_sizes data
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
H5TBread_table reads a table named table_name attached to
the object specified by the identifier loc_id. loc_id table_name dst_size sizeof(). dst_offset dst_sizes sizeof() macro. dst_buf H5TBread_records reads some records identified
from a dataset named table_name attached to
the object specified by the identifier loc_id. loc_id table_name start nrecords type_size sizeof(). field_offset data 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. loc_id table_name field_names start nrecords type_size sizeof. field_offset data
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
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. loc_id table_name fields field_index array. field_index start nrecords type_size sizeof. field_offset data
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
H5TBget_dimensions retrieves the table dimensions from a dataset named
table_name attached to
the object specified by the identifier loc_id. loc_id table_name nfields nrecords
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
H5TBget_field_info gets information about a dataset named table_name attached to
the object specified by the identifier loc_id. loc_id table_name field_names[] field_sizes field_offsets type_size
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
H5TBdelete_record deletes records from middle of table ("pulling up" all the records after it) loc_id dset_name start nrecords H5TBinsert_record inserts records into the middle of the table ("pushing down" all the records after it) loc_id dset_name start nrecords data 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. loc_id dset_name1 start1 nrecords dset_name2 start2 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. loc_id1 dset_name1 loc_id2 dset_name2 dset_name3 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. loc_id dset_name field_name field_type position fill_datadata
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
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. loc_id dset_name field_name
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