HDF5 Packet Table Interface, H5PT

HDF5 documents and links Introduction to HDF5 HDF5 User’s Guide Other High-level API documents | In the HDF5 Reference Manual H5DS H5IM H5LT H5PT H5TB Optimized H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5PL H5R H5S H5T H5Z Tools Datatypes Fortran

# 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:

Creation and Opening H5PTcreate_fl H5PTopen H5PTclose Storage H5PTappend Table Index H5PTcreate_index H5PTset_index | Retrieval H5PTread_packets H5PTget_next Query H5PTget_num_packets H5PTis_valid

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.
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.

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_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.

HDF5 documents and links Introduction to HDF5 HDF5 User’s Guide Other High-level API documents | In the HDF5 Reference Manual H5DS H5IM H5LT H5PT H5TB Optimized H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5PL H5R H5S H5T H5Z Tools Datatypes Fortran