H5PT: HDF5 Packet Table

HDF5 Packet Table API Reference

The HDF5 Packet Table API is designed to allow records to be appended to and read from a table. Packet Table datasets are chunked, allowing them to grow as needed.

The Packet Table API, with the H5PT prefix, is not to be confused with the H5TB Table API (H5TB prefix). The H5TB APIs are stateless (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables require less performance overhead. Also, H5TB Tables support insertions and deletions, while H5PT Packet Tables support only append operations. H5TB functions should not be called on tables created with the H5PT API, or vice versa.

Packet Tables are datasets in an HDF5 file, so while their contents should not be changed outside of the H5PT API calls, the datatypes of Packet Tables can be queried using H5Dget_type. Packet Tables can also be given attributes using the normal HDF5 APIs.

The following functions are part of the HDF5 Packet Table API. 

Programming Hint:

The following line includes the HDF5 Packet Table package, H5PT, in C applications:
         #include "hdf5_hl.h"
Without this include, an application will not have access to these functions.

The C Interfaces:

Name: H5PTcreate

Signature:

hid_t H5PTcreate(hid_t loc_id, const char * ptable_name, hid_t dtype_id, hsize_t chunk_size, hid_t plist_id)

Purpose:

Creates a packet table to store fixed-length or variable-length packets.

Description:

H5PTcreate creates and opens a packet table named ptable_name attached to the object specified by the identifier loc_id. The created packet table should be closed with H5PTclose, eventually. The datatype, dtype_id, may specify any datatype, including variable-length data. If dtype_id specifies a compound datatype, one or more fields in that compound type may be variable-length.

Parameters:

hid_t loc_id

IN: Identifier of the file or group to create the table within.

const char * ptable_name

IN: The name of the packet table to create.

hid_t dtype_id

IN: The datatype of the packet.

hsize_t chunk_size

IN: Chunk size, in number of table entries per chunk. Packet table datasets use HDF5 chunked storage to allow them to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.

hid_t plist_id

IN: Identifier of the property list. Can be used to specify the compression of the packet table.

Returns:

Returns an identifier for the new packet table or H5I_INVALID_HID on error.

History:

Release	Change
1.10.0 and 1.8.17	Function introduced.

Name: H5PTcreate_fl

Signature:

hid_t H5PTcreate_fl(hid_t loc_id, const char * dset_name, hid_t dtype_id, hsize_t chunk_size, int compression)

Purpose:

Creates a packet table to store fixed-length packets.

Description:

H5PTcreate_fl creates and opens a packet table named dset_name attached to the object specified by the identifier loc_id. It should be closed with H5PTclose.

The datatype, dtype_id, may specify any datatype, including variable-length data. If dtype_id specifies a compound datatype, one or more fields in that compound type may be variable-length.

Parameters:

hid_t loc_id

IN: Identifier of the file or group to create the table within.

const char * dset_name

IN: The name of the dataset to create.

hid_t dtype_id

IN: The datatype of a packet.

hsize_t chunk_size

IN: Chunk size, in number of table entries per chunk.
Packet table datasets use HDF5 chunked storage to allow them to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.

int compression

IN: Compression level, a value of 0 through 9. Level 0 is faster but offers the least compression; level 9 is slower but offers maximum compression. A setting of -1 indicates that no compression is desired.

Returns:

Returns an identifier for the new packet table, or H5I_BADID on error.

Name: H5PTopen

Signature:

hid_t H5PTopen(hid_t loc_id, const char *dset_name)

Purpose:

Opens an existing packet table.

Description:

H5PTopen opens an existing packet table in the file or group specified by loc_id. dset_name is the name of the packet table and is used to identify it in the file. This function is used to open both fixed-length packet tables and variable-length packet tables. The packet table should later be closed with H5PTclose. 

Parameters:

hid_t loc_id

IN: Identifier of the file or group within which the packet table can be found.

const char * dset_name

IN: The name of the packet table to open.

Returns:

Returns an identifier for the packet table, or H5I_BADID on error.

Name: H5PTclose

Signature:

herr_t H5PTclose(hid_t table_id)

Purpose:

Closes an open packet table.

Description:

H5PTclose ends access to a packet table specified by table_id.  

Parameters:

hid_t table_id

IN: Identifier of packet table to be closed.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTappend

Signature:

herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data)

Purpose:

Appends packets to the end of a packet table.

Description:

H5PTappend writes nrecords packets to the end of a packet table specified by table_id. data is a buffer containing the data to be written. For a packet table holding fixed-length packets, this data should be in the packet table's datatype. For a variable-length packet table, the data should be in the form of hvl_t structs.  

Parameters:

hid_t table_id

IN: Identifier of packet table to which packets should be appended.

size_t nrecords

IN: Number of packets to be appended.

const void * data

IN: Buffer holding data to write.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTcreate_index

Signature:

herr_t H5PTcreate_index(hid_t table_id)

Purpose:

Resets a packet table's index to the first packet.

Description:

Each packet table keeps an index of the "current" packet so that get_next can iterate through the packets in order. H5PTcreate_index initializes a packet table's index, and should be called before using get_next. The index must be initialized every time a packet table is created or opened; this information is lost when the packet table is closed. 

Parameters:

hid_t table_id

IN: Identifier of packet table whose index should be initialized.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTset_index

Signature:

herr_t H5PTset_index(hid_t table_id, hsize_t pt_index)

Purpose:

Sets a packet table's index.

Description:

Each packet table keeps an index of the "current" packet so that get_next can iterate through the packets in order. H5PTset_index sets this index to point to a user-specified packet (the packets are zero-indexed). 

Parameters:

hid_t table_id

IN: Identifier of packet table whose index is to be set.

hsize_t index

IN: The packet to which the index should point.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTread_packets

Signature:

herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void* data)

Purpose:

Reads a number of packets from a packet table.

Description:

H5PTread_packets reads nrecords packets starting at packet number start from a packet table specified by table_id. data is a buffer into which the data should be read.
For a packet table holding variable-length records, the data returned in the buffer will be in form of hvl_t structs, each containing the length of the data and a pointer to it in memory. The memory used by this data must be freed using H5PTfree_vlen_buff.

Parameters:

hid_t table_id

IN: Identifier of packet table to read from.

hsize_t start

IN: Packet to start reading from.

size_t nrecords

IN: Number of packets to be read.

void * data

OUT: Buffer into which to read data.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTget_next

Signature:

herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data)

Purpose:

Reads packets from a packet table starting at the current index.

Description:

H5PTread_packets reads nrecords packets starting with the "current index" from a packet table specified by table_id. The packet table's index is set and reset with H5PTset_index and H5PTcreate_index. data is a buffer into which the data should be read.

For a packet table holding variable-length records, the data returned in the buffer will be in form of a hvl_t struct containing the length of the data and a pointer to it in memory. The memory used by this data must be freed using H5PTfree_vlen_buff.

Parameters:

hid_t table_id

IN: Identifier of packet table to read from.

size_t nrecords

IN: Number of packets to be read.

void * data

OUT: Buffer into which to read data.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTget_dataset

Signature:

hid_t H5PTget_dataset(hid_t table_id)

Purpose:

Returns the backend dataset of this packet table.

Description:

H5PTget_dataset returns the identifier of the dataset storing the packet table table_id. This dataset identifier will be closed by H5PTclose.

Parameters:

hid_t table_id

IN: Identifier of the packet table.

Returns:

Returns a dataset identifier or H5I_INVALID_HID on error.

History:

Release	Change
1.10.0 and 1.8.17	Function introduced.

Name: H5PTget_type

Signature:

hid_t H5PTget_type(hid_t table_id)

Purpose:

Returns the backend datatype of this packet table.

Description:

H5PTget_type returns the identifier of the datatype used by the packet table table_id. This datatype identifier will be closed by H5PTclose.

Parameters:

hid_t table_id

IN: Identifier of the packet table.

Returns:

Returns a datatype identifier or H5I_INVALID_HID on error.

History:

Release	Change
1.10.0 and 1.8.17	Function introduced.

Name: H5PTget_num_packets

Signature:

herr_t H5PTget_num_packets(hid_t table_id, hsize_t * nrecords)

Purpose:

Returns the number of packets in a packet table.

Description:

H5PTget_num_packets returns by reference the number of packets in a packet table specified by table_id.  

Parameters:

hid_t table_id

IN: Identifier of packet table to query.

hsize_t nrecords

OUT: Number of packets in packet table.

Returns:

Returns a non-negative value if successful, otherwise returns a negative value.

Name: H5PTis_valid

Signature:

herr_t H5PTis_valid(hid_t table_id)

Purpose:

Determines whether an indentifier points to a packet table.

Description:

H5PTis_valid returns a non-negative value if table_id corresponds to an open packet table, and returns a negative value otherwise.  

Parameters:

hid_t table_id

IN: Identifier to query.

Returns:

Returns a non-negative value if table_id is a valid packet table, otherwise returns a negative value.

Name: H5PTis_varlen

Signature:

herr_t H5PTis_varlen(hid_t table_id)

Purpose:

Determines whether a packet table contains variable-length or fixed-length packets.

Description:

H5PTis_varlen returns 1 (TRUE) if table_id is a packet table containing variable-length records. It returns 0 (FALSE) if table_id is a packet table containing fixed-length records. If table_id is not a packet table, a negative value is returned.  

Parameters:

hid_t table_id

IN: Packet table to query.

Returns:

Returns 1 for a variable-length packet table, 0 for fixed-length, or a negative value on error.

History:

Release	Change
1.10.0 and 1.8.17	Function re-introduced. Function had been removed in 1.8.3.

Name: H5PTfree_vlen_buff

Signature:

herr_t H5PTfree_vlen_buff(hid_t table_id, hsize_t bufflen, void * buff)

Purpose:

Releases memory allocated in the process of reading variable-length packets.

Description:

When variable-length packets are read, memory is automatically allocated to hold them, and must be freed. H5PTfree_vlen_buff frees this memory, and should be called whenever packets are read from a variable-length packet table.  

Parameters:

hid_t table_id

IN: Packet table whose memory should be freed.

hsize_t bufflen

IN: Size of buff.

void * buff

IN: Buffer that was used to read in variable-length packets.

Returns:

Returns a non-negative value on success or a negative value on error.

History:

Release	Change
1.10.0 and 1.8.17	Function re-introduced. Function had been removed in 1.8.3.

The HDF Group Help Desk: Describes HDF5 Release 1.8.18, November 2016.

Copyright by The HDF Group and the Board of Trustees of the University of Illinois