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`:

  - 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 `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:

  - 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.
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:

- H5Fstart_swmr_write
- H5DOappend
- H5Pget_append_flush
- H5Pset_object_flush_cb
- H5Pget_object_flush_cb

- H5Odisable_mdc_flushes
- H5Oenable_mdc_flushes
- H5Oare_mdc_flushes_disabled
- H5Fdisable_mdc_flushes
- H5Fenable_mdc_flushes
- H5Fare_mdc_flushes_disabled
- H5Fget_mdc_flush_disabled_obj_ids

- H5Dflush
- H5Drefresh
- H5Gflush
- H5Grefresh
- H5Oflush
- H5Orefresh
- H5Tflush
- H5Trefresh

History:

  Release | Change
  1.10.0 | C function introduced with this release.