H5TB: HDF5 Packet Table

HDF5 Packet Table API Reference

The HDF5 Packet Table API is an extension of the HDF5 high-level Table API. The Packet Table API is lower-level than the Table API, to maximize throughput. Packet Tables can contain either fixed-length or variable-length records. Packet Table API calls should not be made on Tables, nor should Table API calls be made on Packet Tables. 

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

The C Interfaces:

Creation and Opening

Storage

Table Index

Retrieval

Query

Memory Management

 

Name: H5TBmake_packet_table
Signature:
hid_t H5TBmake_packet_table( hid_t loc_id, const char * dset_name, hid_t dtype_id, hsize_t chunk_size )
Purpose:
Creates a packet table to store fixed-length packets.
Description:
H5TBmake_packet_table creates and opens a packet table named dset_name attached to the object specified by the identifier loc_id. It should be closed with H5TBclose_packet_table. 
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: The packet table uses HDF5 chunked storage to allow it to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.
Returns:
Returns an identifier for the new packet table, or H5I_INVALID_HID on error.
Name: H5TBmake_vl_packet_table
Signature:
hid_t H5TBmake_vl_packet_table( hid_t loc_id, const char *dset_name, hsize_t chunk_size )
Purpose:
Creates a packet table to store variable-length packets.
Description:
H5TBmake_vl_packet_table creates and opens a dataset named dset_name attached to the object specified by the identifier loc_id. This dataset can then be written to as a packet table. It should be closed with H5TBclose_packet_table. 
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.
hsize_t chunk_size
IN: The packet table uses HDF5 chunked storage to allow it to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.
Returns:
Returns an identifier for the new packet table, or H5I_INVALID_HID on error.
Name: H5TBopen_packet_table
Signature:
hid_t H5TBopen_packet_table( hid_t loc_id, const char *dset_name )
Purpose:
Opens an existing packet table.
Description:
H5TBopen_packet_table 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 H5TBclose_packet_table. 
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_INVALID_HID on error.
Name: H5TBclose_packet_table
Signature:
herr_t H5TBclose_packet_table( hid_t table_id )
Purpose:
Closes an open packet table.
Description:
H5TBclose_packet_table ends access to a packet table specified by dataset_id.  
Parameters:
hid_t dataset_id
IN: Identifier of packet table to be closed.
Returns:
Returns a non-negative value if successful, otherwise returns a negative value.
Name: H5TBappend_packets
Signature:
herr_t H5TBappend_packets( hid_t table_id, hsize_t nrecords, const void* data)
Purpose:
Appends packets to the end of a packet table.
Description:
H5TBappend_packets 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.
hsize_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: H5TBappend_single_packet
Signature:
herr_t H5TBappend_single_packet( hid_t table_id, const void* data)
Purpose:
Appends a single packet to the end of a packet table.
Description:
H5TBappend_single_packet writes one packet 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 a hvl_t struct. This function is identical to calling H5TBappend_packets to append a single packet. 
Parameters:
hid_t table_id
IN: Identifier of packet table to which packet should 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: H5TBcreate_ptable_index
Signature:
herr_t H5TBcreate_ptable_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_packets can iterate through the packets in order. H5TBcreate_ptable_index initializes a packet table's index, and should be called before using get_next_packets. 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: H5TBset_ptable_index
Signature:
herr_t H5TBset_ptable_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_packets can iterate through the packets in order. H5TBset_ptable_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: H5TBread_packets
Signature:
herr_t H5TBread_packets( hid_t table_id, hsize_t start, hsize_t nrecords, void* data)
Purpose:
Reads a number of packets from a packet table.
Description:
H5TBread_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 H5TBfree_vlen_readbuff.  
Parameters:
hid_t table_id
IN: Identifier of packet table to read from.
hsize_t start
IN: Packet to start reading from.
hsize_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: H5TBread_single_packet
Signature:
herr_t H5TBread_single_packet( hid_t table_id, hsize_t index, void* data)
Purpose:
Reads a single packet from a packet table.
Description:
H5TBread_packets reads a single packet with index index 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 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 H5TBfree_vlen_readbuff.  
Parameters:
hid_t table_id
IN: Identifier of packet table to read from.
hsize_t index
IN: Index of packet to be read (packet tables are zero-indexed).
void * data
OUT: Buffer into which to read data.
Returns:
Returns a non-negative value if successful, otherwise returns a negative value.
Name: H5TBget_next_packets
Signature:
herr_t H5TBget_next_packets( hid_t table_id, hsize_t nrecords, void* data)
Purpose:
Reads packets from a packet table starting at the current index.
Description:
H5TBread_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 H5TBset_index and H5TBcreate_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 H5TBfree_vlen_readbuff.  
Parameters:
hid_t table_id
IN: Identifier of packet table to read from.
hsize_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: H5TBget_num_packets
Signature:
herr_t H5TBget_num_packets( hid_t table_id, hsize_t * nrecords)
Purpose:
Returns the number of packets in a packet table.
Description:
H5TBget_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: H5TBis_valid
Signature:
herr_t H5TBis_valid( hid_t table_id)
Purpose:
Determines whether an indentifier points to a packet table.
Description:
H5TBis_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: H5TBis_varlen
Signature:
herr_t H5TBis_varlen( hid_t table_id)
Purpose:
Determines whether a packet table contains variable-length or fixed-length packets.
Description:
H5TBis_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.
Name: H5TBfree_vlen_readbuff
Signature:
herr_t H5TBfree_vlen_readbuff( 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. H5TBfree_vlen_readbuff 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.