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. These records can be of fixed length
(having an HDF5 datatype) or of variable-length, with each record potentially
having a different size on disk.
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 (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 variable-length records. 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 fixed-length Packet Tables can be queried using H5Dget_datatype().
Packet Tables can also be given attributes using the normal HDF5 APIs.
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: H5PTcreate_fl
- Signature:
- hid_t H5PTcreate_fl( 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:
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. - 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_BADID on error.
- Name: H5PTcreate_vl
- Signature:
- hid_t H5PTcreate_vl( hid_t loc_id,
const char *dset_name, hsize_t
chunk_size )
- Purpose:
- Creates a packet table to store variable-length packets.
- Description:
H5PTcreate_vl 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
H5PTclose. - 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_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
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: H5PTappend
- Signature:
- herr_t H5PTappend( hid_t table_id,
hsize_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.
- 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: 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, hsize_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_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: H5PTget_next
- Signature:
- herr_t H5PTget_next( hid_t table_id,
hsize_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_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: 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.
- Name: H5PTfree_vlen_readbuff
- Signature:
- herr_t H5PTfree_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.
H5PTfree_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.