Classes:
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)
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
<hr size=3 width="100%" align=center>
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, false
otherwise.
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.
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.
<hr size=3 width="100%" align=center>
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, 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, 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: FreeBuff
Signatures:
int FreeBuff
()
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 free.
hvl_t *buffer
IN: Pointer to location.
Returns:
Returns SUCCEED, on success, and FAIL on error.
<hr size=3 width="100%" align=center>
FL_Packet_Table:
Name: "Create" Constructor
Signature:
FL_PacketTable(hid_t
fileID, hid_t plistID, 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. Compression can be set via the dataset create
property list, specified by plistID.
Parameters:
hid_t fileID
IN: Identifier of the file or group to create the table
within.
hid_t plistID
IN: Identifier of the creation property list.
const char *pt_name
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.
Name: "Create" Constructor (deprecated)
Signature:
FL_PacketTable(hid_t
fileID, char* ptname, hid_t dtypeID, hsize_t chunkSize, int compression)
Purpose:
Creates a new packet table for storing fixed-length packets.
Description:
This constructor will be deprecated in favor of the previous
constructor, 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.
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 must be
fixed-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.
Name: AppendPacket / AppendPackets
Signature:
int AppendPacket(void
* data)
int AppendPackets(size_t numPackets, void *data)
Purpose:
Appends packet(s) to the packet table.
Description:
These functions write packet(s) 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.
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 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 read numPackets packets.
Parameters:
size_t numPackets (optional)
IN: How many packets to read.
void * data
OUT: Buffer to hold packets read.
Returns:
Returns SUCCEED, on success, and FAIL on error.
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.
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 ID.
Returns:
Returns a valid identifier on success, or H5I_INVALID_HID on error.
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 ID.
Returns:
Returns a valid identifier on success, or H5I_INVALID_HID on error.
<hr size=3 width="100%" align=center>