HDF5 High Level APIs

HDF5-HL Packet Table
Use Cases

General Use Case:

  1. Create/Open HDF5 File
  2. Create/Open packet table
  3. Perform operations on packet table (as many as desired)
  4. Close packet table
  5. Close HDF5 File


Writing one kind of data to a fixed-length packet table

An experimenter wants to store data from a single kind of sensor in a Packet Table. First, she must create or load an HDF5 datatype representing a "packet" of her data. This can be any valid HDF5 datatype, though it is likely to be a compound datatype, since each packet corresponds to a horizontal entry in a table. If the experimenter has used HDF5 in the past, she may have already created a datatype representing her data and can simply load it from a file. This step is covered in more detail in the HDF5 User’s Guide.
The experimenter then creates the packet table. She must specify the location (file or group identifier), name, and datatype of the new packet table. Her function call might look like this:

hid_t ptable_id= H5PTcreate_fl( file_id, "/trial1", datatype_id, 500 );

The last argument is the "chunk size," which affects how HDF5 stores data in the file; the experimenter may fine-tune this number later. Chunked storage is discussed in more detail in the HDF5 User's Guide.
Now the experimenter starts the experiment itself. Each time a sensor takes a reading, the data is stored in a buffer, which the experimenter uses to create an entry in the packet table:

ret_value= H5PTappend( ptable_id, 1, &(dataBuffer) );

The above statement executes inside a loop and is called to add a new packet every time a new sensor reading is placed in the data buffer.
When the experiment is over, the experimenter closes the packet table.

ret_value= H5PTclose( ptable_id );

She may also wish the close the HDF5 file if she is done accessing it.

Reading data from a fixed-length packet table

An analyst wants to read from a fixed-length packet table like the one created by the experimenter above.
First, he must open the packet table. To do this, he needs to know its location and name.

hid_t ptable_id= H5PTopen( file_id, "/trial1" );

Once the packet table is open, the analyst wants to discover how many packets it contains.

hsize_t num_packets;
ret_value= H5PTget_num_packets( ptable_id, &num_packets );

The analyst then begins to read records one-by-one from the beginning of the packet table. He sets the packet table's index to the first packet.

ret_value= H5PTcreate_index( ptable_id );

Then, he creates a for-loop to read each packet into a buffer and perform his analysis on it.

for(int x=0; x<num_packets; x++) {
   ret_value= H5PTget_next( ptable_id, 1, &(readBuffer) );
   // Perform analysis on readBuffer
}

The analyst may want to read several packets into a larger buffer, and start from an arbitrary index without losing his place in the table. To read twenty packets starting from packet number 400, he uses the following call:

ret_value= H5PTread_packets( ptable_id, 400, 20, &(bigReadBuffer) );

Finally, the analyst closes the packet table.

ret_value= H5PTclose(ptable_id);

He may also wish to close the HDF5 file, or he may go on to examine other objects in the same file.

Handling an unknown packet table identifier

A function receives an identifier from another location in the program and the programmer wishes to confirm that it is the packet table she is expecting.

First, she checks that it is in fact a packet table and that it has been opened.

ret_value= H5PTis_valid( ptable_id );

If the identifier does not refer to an open packet table, the return value will be negative.

The programmer may need to remember to close the packet table, depending on the semantics of the application.


The HDF Group Help Desk:

Last modified: 24 April 2005

Last modified: 13 March 2015: Removed mention of variable-length packet tables.