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:

  - 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, `H5Ocopy` 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.

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.