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
nrecords
type_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_data
data
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
The HDF Group Help Desk:
Describes HDF5 Release 1.8.20, November 2017. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |