H5P_ADD_MERGE_COMMITTED_DTYPE_PATH provides a means to override the default behavior of H5O_COPY when H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is set in an object copy property list.

H5P_ADD_MERGE_COMMITTED_DTYPE_PATH is the mechanism for suggesting search paths where H5O_COPY 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.

H5P_ADD_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 H5P_SET_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 H5O_COPY 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 H5P_SET_MCDT_SEARCH_CB).

Two datatypes are determined equal if their descriptions are identical, in a manner similar to H5T_EQUAL. 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, H5O_COPY will perform the following in the destination file:

• For a committed datatype, the library will create a hard link to the found datatype.
• For a dataset that uses a committed datatype, the library will modify the copied dataset to use the found committed datatype as its datatype.
• For an object with an attribute of a committed datatype, the library will modify the copied object’s attribute to use the found committed datatype as its datatype.

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

• For a committed datatype, the library will copy it as it would any other object, creating a named committed datatype at the destination. That is, the library will create a committed datatype that is accessible in the file by a unique path.
• For a dataset that uses a committed datatype, the library will copy the datatype as an anonymous committed datatype and use that as the dataset’s datatype.
• For an object with an attribute of a committed datatype, the library will copy the datatype as an anonymous committed datatype and use that as the attribute’s datatype.

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

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

This example adds two paths to the object copy property list. H5O_COPY 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...);
    ...
    ...
}