Last modified: 7 January 2016

Name: H5Pset_append_flush

Signature:
herr_t H5Pset_append_flush ( hid_t dapl_id, int ndims, const hsize_t boundary[], H5D_append_cb_t func, void *user_data )

Purpose:
Sets two actions to perform when the size of a dataset’s dimension being appended reaches a specified boundary.

Description:
H5Pset_append_flush sets the following two actions to perform for a dataset associated with the dataset access property list dapl_id:

When a user is appending data to a dataset via H5DOappend and the dataset’s newly extended dimension size hits a specified boundary, the library will first perform action #1 listed above. Upon return from the callback function, the library will then perform the above action #2 and return to the user. If no boundary is hit or set, the two actions above are not invoked.

The specified boundary is indicated by the parameter boundary. It is a 1-dimensional array with ndims elements, which should be the same as the rank of the dataset’s dataspace. While appending to a dataset along a particular dimension index via H5DOappend, the library determines a boundary is reached when the resulting dimension size is divisible by boundary[index]. A zero value for boundary[index] indicates no boundary is set for that dimension index.

The setting of this property will apply only for a chunked dataset with an extendible dataspace. A dataspace is extendible when it is defined with either one of the following:

When creating or opening a chunked dataset, the library will check whether the boundary as specified in the access property list is set up properly. The library will fail the dataset create or open if the following conditions are true:

The callback function func must conform to the following prototype:

The parameters of the callback function, per the above prototype, are defined as follows:


Parameters:
hid_t dapl_id IN: Dataset access property list identifier.
int ndims IN: The number of elements for boundary.
hsize_t *boundary IN: The dimension sizes used to determine the boundary.
H5D_append_cb_t func    IN: The user-defined callback function.
void *user_data IN: The user-defined input data.

Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Example Usage:
The example below illustrates the usage of this public routine to manage flush behavior while appending to a dataset. Note also the use of H5DOappend.
hsize_t dims[2] = {0, 100};
hsize_t max_dims[2] = {H5S_UNLIMITED, 100};
hsize_t boundary_dims[2] = {5, 0};
unsigned counter;
void *buf;
hid_t file_id;
hid_t dataset_id, dapl_id, type;

/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR|H5F_ACC_SWMR_WRITE, H5P_DEFAULT);

/* Create a copy of the dataset access property list */
dapl_id = H5Pcreate(H5P_DATASET_ACCESS);

/* Set up the append property values */
/* boundary_dims[0]=5: to invoke callback and flush every 5 lines */
/* boundary_dims[1]=0: no boundary is set for the non-extendible dimension */
/* append_cb: callback function to invoke when hitting boundary (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_append_flush(dapl_id, 2, boundary_dims, append_cb, &counter);

/* DATASET is a 2-dimensional chunked dataset with dataspace: 
   dims[] and max_dims[] */
dataset_id = H5Dopen2(file_id, “dataset”, dapl_id);

/* Get the dataset’s datatype */
type = H5Dget_type(dataset_id);

/* Append 50 lines along the unlimited dimension (index = 0) to the dataset */
for(n = 0; n < 50; n++) {

    /* Append 1 line to the dataset */  
    /* Whenever hitting the specified boundary i.e., every 5 lines, 
       the library will invoke append_cb() and then flush the dataset. */ 
    H5DOappend(dataset_id, H5P_DEFAULT, 0, 1, type, buf);
}
:
:
:
/* counter will be equal to 10 */
:
:
:

/* The callback function */
static herr_t
append_cb(hid_t dset_id, hsize_t *cur_dims, void *_udata)
{
    unsigned *count = (unsigned *)_udata;
    ++(*count++);
    return 0;
} /* append_cb() */

Fortran Interface:
None

See Also:



History:
Release     Change
1.10.0 C function introduced with this release.