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

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

• Call the callback function func set in the property list
• Flush the dataset associated with the dataset access property list

When a user is appending data to a dataset via H5DO_APPEND 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 H5DO_APPEND, 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:

• A dataspace with fixed current and maximum dimension sizes
• A dataspace with at least one unlimited dimension for its maximum dimension size

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:

• ndims, the number of elements for boundary, is not the same as the rank of the dataset’s dataspace.
• A non-zero boundary value is specified for a non-extendible dimension.

The callback function func must conform to the following prototype:

• typedef herr_t (H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *user_data)

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

• dataset_id is the dataset identifier.
• cur_dims is the dataset’s current dimension sizes when a boundary is hit.
• user_data is the user-defined input data.

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

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() */