Packet Table C++ Wrapper Reference Manual

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 H5R H5S H5T H5Z Tools Datatypes Fortran

# H5PT: HDF5 Packet Table
C++ Wrappers

Classes:

- PacketTable - functions shared by all packet tables
- FL_PacketTable - a packet table storing fixed-length and variable-length packets

Functions (none are static; all must be called on an object):

Packet Table:

Name: Null Constructor
Signature:
  `PacketTable( )`
Purpose:
  Creates an invalid packet table object.
Description:
  The object created with this call will return false if `IsValid()` is called on it. To create a valid packet table, use the `FL_Packet_Table constructors`. This function does not make any change to the underlying HDF5 file.

Name: “Open” Constructor
Signature:
  `PacketTable(hid_t fileID, const char* ptname)`
  `PacketTable(hid_t fileID, char* ptname) (deprecated)`
Purpose:
  Opens an existing packet table.
Description:
  Opens an existing packet table, named `ptname`, which can contain either fixed-length or variable-length packets.
Parameters:

`hid_t fileID`
  IN: File or group in which the packet table is located
`const char* ptname`
  IN: The packet table’s name

History:

  Release | Change
  1.10.0 and 1.8.17 | Function parameters were revised.

Name: Destructor
Signature:
  `~PacketTable()`
Description:
  The destructor closes the packet table in the file, so a packet table created or opened with the C++ wrapper does not need to be closed manually.

Name: IsValid
Signature:
  `bool IsValid()`
Purpose:
  Determines if this is a valid packet table.
Description:
  This function is used to ensure that a PacketTable object corresponds to an open packet table in the file. It should be called after the constructor to check that there were no errors creating or opening the packet table.
Returns:
  Returns true if this is an open packet table; otherwise returns false.

Name: IsVariableLength
Signature:
  `int IsVariableLength()`
Purpose:
  Determines if this is a valid packet table.
Description:
  This function returns `1` if this packet table uses a variable-length datatype, `0` if not, and `FAIL` if failure occurs.
Returns:
  Returns `1`, `0`, or `FAIL`.
History:

  Release | Change
  1.10.0 and 1.8.17 | Function introduced.

Name: ResetIndex
Signature:
  `void ResetIndex()`
Purpose:
  Resets the packet table’s index to point to the first packet.
Description:
  A packet table keeps track of the user’s current location in the table so that the user can iterate through packets. This function should be called before using `GetNextPacket`.

Name: SetIndex
Signature:
  `int SetIndex(hsize_t index);`
Purpose:
  Sets a packet table’s current index.
Description:
  This function allows the user to begin iterating through packets starting from any arbitrary index. Packet tables are zero-indexed, so packet 0 is the first packet.
Parameters:

`hsize_t index`
  IN: The value to which the packet table’s index should be set

Returns:
  Returns non-negative on success and negative on error.

Name: GetIndex
Signature:
  `hsize_t GetIndex(int& error);`
Purpose:
  Returns the position of the current packet.
Description:
  This function allows the user to determine the position of the current packet.

  If `GetIndex` returns `0` (zero), you must then check the value of the parameter `error`. If `error` is negative, `GetIndex` has failed; if `error` is `0` (zero), the position of the current packet is `0` (zero).

Parameters:

`int& error` (optional)
  OUT: Non-negative if index was successfully retrieved, negative on failure.

Returns:
  Returns the position of the current packet on success and `0` (zero) on error.

Name: GetPacketCount
Signatures:
  `hsize_t GetPacketCount()`
  `hsize_t GetPacketCount(int& error)`
Purpose:
  Retrieves the number of packets in the packet table.
Description:
  This function is overloaded so that it can be called with or without returning an error value. If `error` is not supplied, any error value is ignored. Using this parameter allows the user to distinguish between an open packet table with 0 packets and an invalid packet table.
Parameters:

`int& error` (optional)
  OUT: Non-negative if packet count was successfully retrieved, negative if packet table is invalid.

Returns:
  Number of packets in packet table. Returns `0` if packet table contains zero packets or on error.

Name: GetDatatype
Signature:
  `hid_t GetDatatype ()`
Purpose:
  Returns the datatype of this packet table.
Description:
  This function returns the identifier of the datatype used by this packet table. However, it is better to avoid using this identifier in packet table applications unless the desired functionality cannot be performed via the packet table identifier.
Returns:
  Returns a valid identifier on success or `H5I_INVALID_HID` on error.
History:

  Release | Change
  1.10.0 and 1.8.17 | Function introduced.

Name: GetDataset
Signature:
  `hid_t GetDataset ()`
Purpose:
  Returns the dataset of this packet table.
Description:
  This function returns the identifier of the dataset of this packet table. However, it is better to avoid using this identifier in packet table applications unless the desired functionality cannot be performed via the packet table identifier.
Returns:
  Returns a valid identifier on success or `H5I_INVALID_HID` on error.
History:

  Release | Change
  1.10.0 and 1.8.17 | Function introduced.

Name: GetTableId
Signature:
  `hid_t GetTableId ()`
Purpose:
  Returns the identifier of the packet table.
Description:
  This function returns the packet table identifier. However, the identifier is usually not needed by applications.
Returns:
  Returns a valid identifier on success or `H5I_INVALID_HID` if the packet table is not valid.
History:

  Release | Change
  1.10.0 and 1.8.17 | Function introduced.

Name: FreeBuff
Signature:
  `FreeBuff(size_t numStructs, hvl_t * buffer)`
Purpose:
  Frees the buffer created when accessing data in a variable-length packet table.
Description:
  Takes the number of `hvl_t` structs to be freed and a pointer to their location in memory.
Parameters:

`size_t numStructs`
  IN: Number of structs to be freed.
`hvl_t *buffer`
  IN: Pointer to location.

Returns:
  Returns `SUCCEED` on success and `FAIL` on error.
History:

  Release | Change
  1.10.0 and 1.8.17 | Function introduced in this release.

FL_Packet_Table:

Name: “Create” Constructor
Signature:
  `FL_PacketTable(hid_t fileID, const char* ptname, hid_t dtypeID, hsize_t chunkSize)`
Purpose:
  Creates a new packet table for storing fixed-length or variable-length packets.
Description:
  This constructor creates and opens a packet table, named `ptname`, in the file specified by `fileID`. Packets will be of the datatype specified by `dtypeID`. The packet table uses HDF5 chunked storage to allow it to grow. The chunk size can be specified by `chunkSize`. The chunk size affects performance, so it should be determined with care when performance is important.
Parameters:

`hid_t fileID`
  IN: Identifier of the file or group to create the table within.
`const char * ptname`
  IN: The name of the packet table to create.
`hid_t dtypeID`
  IN: The datatype of a packet.
`hsize_t chunkSize`
  IN: Desired chunk size; defaults to 0.

History:

  Release | Change
  1.10.0 | Function revised.

Name: “Create” Constructor (deprecated in 1.10.0 and in 1.8.17)
Signature:
  `FL_PacketTable(hid_t fileID, const char* ptname, hid_t dtypeID, hsize_t chunkSize, int compression)`
Purpose:
  Creates a new packet table for storing fixed-length packets.
Description:
  This constructor has been deprecated in favor of the “Create” Constructor above, which provides flexibility in the compression method.

  This constructor creates and opens a packet table in the file specified by `fileID` named `ptname`. Packets will be of the datatype specified by `dtypeID`. The packet can be specified to contain data with deflate compression using the parameter `compression`.

Parameters:

`hid_t fileID`
  IN: Identifier of the file or group to create the table within.
`const char * ptname`
  IN: The name of the packet table to create.
`hid_t dtypeID`
  IN: The datatype of a packet.
`hsize_t chunkSize`
  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.
`int compression`
  IN: Desired compression level: `0` (zero) through `9,` or `-1` for no compression.

History:

  Release | Change
  1.10.0 and 1.8.17 | Function revised and deprecated.

Name: “Open” Constructor
Signature:
  `FL_PacketTable(hid_t fileID, const char* ptname)`
  `FL_PacketTable(hid_t fileID, char* ptname) (deprecated)`
Purpose:
  Opens a fixed-length packet table.
Description:
  This constructor opens an existing packet table named `ptname` in the location `fileID`. This packet table can be either fixed-length or variable-length.
Parameters:

`hid_t fileID`
  IN: Identifier of the file or group containing the packet table.
`const char * ptname`
  IN: The name of the packet table to open.

History:

  Release | Change
  1.10.0 and 1.8.17 | Function arguments were changed.

Name: AppendPacket / AppendPackets
Signatures:
  `int AppendPacket(void * data)`
  `int AppendPackets(size_t numPackets, void *data)`
Purpose:
  Appends packets to the packet table.
Description:
  These functions write packets to the end of the packet table.
Parameters:

`size_t numPackets`
  IN: Number of packets to add.
void * data:
  IN: Data to write. Must be a buffer of packets of the packet table’s datatype.

Returns:
  Returns `SUCCEED` on success and `FAIL` on error.
History:

  Release | Change
  1.10.0 and 1.8.17 | Function changed: function now works with fixed-length and variable-length packets.

Name: GetPacket / GetPackets
Signatures:
  `int GetPacket(hsize_t index, void * data)`
  `int GetPackets(hsize_t startIndex, hsize_t endIndex, void * data)`
Purpose:
  Reads packets from the packet table.
Description:
  This function fills a buffer, `data`, with fixed-length packets from the packet table. The one-argument function can be called to retrieve a single packet at the given index, or the two-argument function can be used to read a range of packets (zero-indexed, inclusive).
Parameters:

`hsize_t index` (single packet)
  IN: Index of the single packet to be read.
`hsize_t startIndex` (multiple packets)
  IN: Index at which to start reading packets.
`hsize_t endIndex` (multiple packets)
  IN: Index at which to stop reading packets.
`void * data`
  OUT: Buffer for packets being retrieved.

Returns:
  Returns `SUCCEED` on success and `FAIL` on error.

Name: GetNextPacket / Get Next Packets
Signatures:
  `int GetNextPacket(void * data)`
  `int GetNextPackets(size_t numPackets, void * data)`
Purpose:
  Iterates through packets from the packet table.
Description:
  This function reads packets starting from the current index in the packet table and updates the index. It can be used with the `ResetIndex` and `SetIndex` functions to iterate through the packet table. `GetNextPacket` reads a single packet, and `GetNextPackets` reads `numPackets` packets.
Parameters:

`size_t numPackets` (optional)
  IN: The number of packets that will be read.
`void * data`
  OUT: Buffer to hold packets that were read.

Returns:
  Returns `SUCCEED` on success and `FAIL` on error.

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 H5R H5S H5T H5Z Tools Datatypes Fortran