Last modified: 21 March 2012
Name: H5Padd_merge_committed_dtype_path
Signature:
herr_t H5Padd_merge_committed_dtype_path( hid_t ocpypl_id, char *path )

Purpose:
Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.

Motivation:
H5Padd_merge_committed_dtype_path provides a means to override the default behavior of H5Ocopy when H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is set in an object copy property list.

H5Padd_merge_committed_dtype_path is the mechanism for suggesting search paths where H5Ocopy will look for a matching committed datatype. This can be substantially faster than the default approach of searching the entire destination file for a match.

Description:
H5Padd_merge_committed_dtype_path adds a path, path, which points to a committed datatype, to the current list of suggested paths stored in the object copy property list ocpypl_id. The search as described in the next paragraph is effective only if the H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is enabled in the object copy property list via H5Pset_copy_object.

When copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of a committed datatype, the default behavior of H5Ocopy is to search for a matching committed datatype:

  1. First search the list of suggested paths in the object copy property list.
  2. Then, if no match has been found, search all the committed datatypes in the destination file.

The default Step 2 in this search process can changed by setting a callback function (see H5Pset_mcdt_search_cb).

Two datatypes are determined equal if their descriptions are identical, in a manner similar to H5Tequal. If either committed datatype has one or more attributes, then all attributes must be present in both committed datatypes and they must be identical. Two attributes are considered identical if their datatype description, dataspace, and raw data values are the same. However, if an attribute uses a committed datatype, that committed datatype’s attributes will not be compared.

If a match is found, H5Ocopy will perform the following in the destination file:

If no match is found, H5Ocopy will perform the following in the destination file:

Parameters:
hid_t ocpypl_id      IN: Object copy property list identifier.
char *path   IN: The path to be added.

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

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

It will also fail if there is insufficient memory when duplicating path.

Example Usage:
This example adds two paths to the object copy property list. H5Ocopy will search the two suggested paths for a match before searching all the committed datatypes in the destination file.

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 a committed datatype */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

    /* Add a path to a dataset with committed datatype */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dset");
    
    /* Does the copy */
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}
        

See Also:
H5Ocopy
H5Pset_copy_object
  H5Pset_mcdt_search_cb
H5Pfree_merge_committed_dtype_paths

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.