Last modified: 22 August 2012
Name: H5Pset_mcdt_search_cb
Signature:
  herr_t `H5Pset_mcdt_search_cb`( hid_t `ocpypl_id`, H5O_mcdt_search_cb_t `func`, void *`op_data` )

Purpose:
  Sets the callback function that `H5Ocopy` will invoke before searching the entire destination file for a matching committed datatype.

Motivation:
  `H5Pset_mcdt_search_cb` provides the means to define a callback function. An application can then use that callback to take an additional action before the default search of all committed datatypes in the destination file or to take an action that replaces the default search. This mechanism is intended to improve performance when the global search might take a long time.

Description:
  `H5Pset_mcdt_search_cb` allows an application to set a callback function, `func`, that will be invoked before searching the destination file for a matching committed datatype. The default, global search process is described in `H5Padd_merge_committed_dtype_path`.

  The callback function must conform to the `H5O_mcdt_search_cb_t` prototype and will return an instruction for one of the following actions:

  - Continue the search for a matching committed datatype in the destination file.
  - Discontinue the search for a matching committed datatype. `H5Ocopy` will then apply the default behavior of creating an anonymous committed datatype.
  - Abort the copy operation and exit `H5Ocopy`.

Warning:
  If the callback function return value causes `H5Ocopy` to abort, the destination file may be left in an inconsistent or corrupted state.

Programming Note for C++ Developers Using C Functions:

  If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

  Examples of this kind of routine include callbacks such as `H5Pset_elink_cb` and `H5Pset_type_conv_cb` and functions such as `H5Tconvert` and `H5Ewalk2`.

  Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Parameters:

  hid_t `ocpypl_id` |  | IN: Object copy property list identifier
  H5O_mcdt_search_cb_t `func` |  | IN: User-defined callback function
  void *`op_data` |  | IN: User-defined input data for the callback function

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

Failure Modes:
  `H5Pset_mcdt_search_cb` will fail if the object copy property list is invalid.

Example Usage:
  This example defines a callback function in the object copy property list.

      /* The user-defined callback function */
      static H5O_mcdt_search_ret_t
      mcdt_search_cb(void *_udata)
      {
          H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);

          return(action);
      }

      int main(void) {
          hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

          /* Enable the merging committed datatype feature. */
          H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

          /* Add a path to search for a matching committed datatype. */
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

          /*
           * Set the callback function to discontinue the global search
           * if H5Ocopy cannot find a matching committed datatype from the
           * above suggested path.
           */
          action = H5O_MCDT_SEARCH_STOP;
          H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
          H5Ocopy(...ocpypl_id...);
          ...
          ...
      }

See Also:

  `H5Ocopy` `H5Pset_copy_object` |  | `H5Padd_merge_committed_dtype_path` `H5Pget_mcdt_search_cb` `H5O_mcdt_search_cb_t`

  Copying Committed Datatypes with `H5Ocopy` |  | A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

History:

  Release | Change
  1.8.9 | C function introduced in this release.