Last modified: 17 April 2012
Name: H5O_mcdt_search_cb_t
Signature:
typedef H5O_mcdt_search_ret_t ( *H5O_mcdt_search_cb_t )( void *op_data )

Purpose:
Provides the mechanism by which a user application may set an action for H5Ocopy to take after checking all suggested paths for a matching committed datatype but before starting the global search of the destination file.

Description:
H5O_mcdt_search_cb_t is the callback function that H5Ocopy will invoke if the callback is set and when the merge committed datatype feature is enabled in the object copy property list (see H5Pset_copy_object).

After searching the list of suggested committed datatype paths, H5Ocopy will invoke this callback before searching all committed datatypes in the destination file. This allows a user application to add a customized step to the search process. The callback function is set with H5Pset_mcdt_search_cb and the search process is described in H5Padd_merge_committed_dtype_path.

Valid return values from this callback function are as follows (defined in the enumerated datatype H5O_mcdt_search_ret_t in H5Opublic.h):
H5O_MCDT_SEARCH_ERROR      Aborts H5Ocopy.
H5O_MCDT_SEARCH_CONT   Continues the global search of all committed datatypes in the destination file.
H5O_MCDT_SEARCH_STOP   Stops the search, but continues copying.

Warning:
If the callback’s return value is H5O_MCDT_SEARCH_ERROR, H5Ocopy will abort and the destination file may be left in an inconsistent or corrupted state.

Parameters:
void *op_data   IN/OUT: Pointer to user-defined input data. This is a pass-through of the data that was passed to H5Pset_mcdt_search_cb.

Returns:
Returns one of the H5O_MCDT_SEARCH_* values described above.

Failure Modes:
H5O_mcdt_search_cb_t failure modes are dependent on the implementation of the callback function.

Example Usage:
This example defines a callback function in the object copy property list to discontinue the global search if a matching committed datatype cannot be found among the suggested paths.
/* 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 the 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);

    /* Do the copy. */
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}
        

See Also:
H5Ocopy
H5Pset_copy_object
  H5Pset_mcdt_search_cb
H5Pget_mcdt_search_cb

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 type introduced in this release.