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.
Currently we only provide a C interface for the library.
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.
- 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 *dst_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
*
dst_sizes
- IN: An array containing the sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- 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 *dst_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
*
dst_sizes
- IN: An array containing the sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- 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 *dst_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
*
dst_sizes
- IN: An array containing the sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- void *
data
- IN: Buffer with data.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- 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 *dst_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 n
fields
- 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
*
dst_sizes
- IN: An array containing the sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- void *
data
- IN: Buffer with data.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- 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 in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- 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 sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- 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 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 the
sizeof()
operator.
-
const size_t *
field_offset
- IN: An array containing the offsets of the fields.
- const size_t
*
dst_sizes
- IN: An array containing the sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- void *
data
- OUT: Buffer with data.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- 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 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 n
fields
- 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 sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- void *
data
- OUT: Buffer with data.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- 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.
- 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_info
gets information about a dataset named table_name
attached to
the object specified by the identifier loc_id
. The sizes
of the fields, the offsets and the total size of the compound datatype that
defines the fields are all native type sizes. A native type is a
system-specific instance datatype obtained by the HDF5 library from the
datatype stored in the file.
- 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: An array containing the size of the HDF5 type associated with the
table.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- 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 *dst_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
*
dst_sizes
- IN: An array containing the sizes in bytes of the fields. These sizes can be
calculated with the
sizeof()
operator.
- 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.
- 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.
HDF Help Desk
Last modified: April 06, 2004