Detailed Description

Object copy property list functions (H5P)
Function	Purpose
H5Padd_merge_committed_dtype_path	Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.
H5Pfree_merge_committed_dtype_paths	Clears the list of paths stored in the object copy property list.
H5Pset_copy_object/H5Pget_copy_object	Sets/gets the properties to be used when an object is copied.
H5Pset_mcdt_search_cb/H5Pget_mcdt_search_cb	Sets/gets the callback function that H5Ocopy() will invoke before searching for a matching committed datatype.

Functions
herr_t	H5Padd_merge_committed_dtype_path (hid_t plist_id, const char *path)
	Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.

herr_t	H5Pfree_merge_committed_dtype_paths (hid_t plist_id)
	Clears the list of paths stored in the object copy property list.

herr_t	H5Pget_copy_object (hid_t plist_id, unsigned *copy_options)
	Retrieves the properties to be used when an object is copied.

herr_t	H5Pget_mcdt_search_cb (hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data)
	Retrieves the callback function from the specified object copy property list.

herr_t	H5Pset_copy_object (hid_t plist_id, unsigned copy_options)
	Sets properties to be used when an object is copied.

herr_t	H5Pset_mcdt_search_cb (hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data)
	Sets the callback function that H5Ocopy() will invoke before searching the entire destination file for a matching committed datatype.

Function Documentation

◆ H5Padd_merge_committed_dtype_path()

herr_t H5Padd_merge_committed_dtype_path	(	hid_t	plist_id,
		const char *	path
	)

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

Parameters

[in]	plist_id	Object copy property list identifier
[in]	path	The path to be added

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

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 plist_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:

First search the list of suggested paths in the object copy property list.
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 be 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.

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.

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);

       H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
       H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");
       H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dset");
       H5Ocopy(...ocpypl_id...);
       ...
       ...
    }

Note: 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.

See also

Since: 1.8.9

◆ H5Pfree_merge_committed_dtype_paths()

herr_t H5Pfree_merge_committed_dtype_paths ( hid_t plist_id )

Clears the list of paths stored in the object copy property list.

Parameters

[in] plist_id Object copy property list identifier

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

H5Pfree_merge_committed_dtype_paths() clears the suggested paths stored in the object copy property list plist_id. These are the suggested paths previously set with H5Padd_merge_committed_dtype_path().

Example Usage: This example adds a suggested path to the object copy property list, does the copy, clears the list, and then adds a new suggested path to the list for another copy.

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

          H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");
          H5Ocopy(...ocpypl_id...);
          ...
          ...
          H5Pfree_merge_committed_dtype_paths(ocpypl_id);
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dtypeB");
          H5Ocopy(...ocpypl_id...);
          ...
          ...
      }

Note: H5Pfree_merge_committed_dtype_paths() will fail if the object copy property list is invalid.

See also

Since: 1.8.9

◆ H5Pget_copy_object()

herr_t H5Pget_copy_object	(	hid_t	plist_id,
		unsigned *	copy_options
	)

Retrieves the properties to be used when an object is copied.

Parameters

[in]	plist_id	Object copy property list identifier
[out]	copy_options	Copy option(s) set in the object copy property list

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

H5Pget_copy_object() retrieves the properties currently specified in the object copy property list plist_id, which will be invoked when a new copy is made of an existing object.

copy_options is a bit map indicating the flags, or properties, governing object copying that are set in the property list plist_id.

The available flags are described in H5Pset_copy_object().

Since: 1.8.0

◆ H5Pget_mcdt_search_cb()

herr_t H5Pget_mcdt_search_cb	(	hid_t	plist_id,
		H5O_mcdt_search_cb_t *	func,
		void **	op_data
	)

Retrieves the callback function from the specified object copy property list.

Parameters

[in]	plist_id	Object copy property list identifier
[out]	func	User-defined callback function
[out]	op_data	User-defined data for the callback function

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

H5Pget_mcdt_search_cb() retrieves the user-defined callback function and the user data that are set via H5Pset_mcdt_search_cb() in the object copy property list plist_id.

The callback function will be returned in the parameter func and the user data will be returned in the parameter op_data.

Note: H5Pget_mcdt_search_cb() will fail if the object copy property list is invalid.

See also

Since: 1.8.9

◆ H5Pset_copy_object()

herr_t H5Pset_copy_object	(	hid_t	plist_id,
		unsigned	copy_options
	)

Sets properties to be used when an object is copied.

Parameters

[in]	plist_id	Object copy property list identifier
[out]	copy_options	Copy option(s) to be set

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

H5Pset_copy_object() sets properties in the object copy property list plist_id. When an existing object is copied, that property list will determine how the new copy is created.

The following flags are available for use in an object copy property list:

H5O_COPY_SHALLOW_HIERARCHY_FLAG	Copy only immediate members of a group Default behavior, without flag: Recursively copy all objects in and below the group.
H5O_COPY_EXPAND_SOFT_LINK_FLAG	Expand soft links into new objects Default behavior, without flag: Copy soft links as they are.
H5O_COPY_EXPAND_EXT_LINK_FLAG	Expand external link into new objects Default behavior, without flag: Copy external links as they are.
H5O_COPY_EXPAND_REFERENCE_FLAG	Copy objects that are pointed to by references and update reference values in destination file Default behavior, without flag: Set reference values in destination file to zero (0)
H5O_COPY_WITHOUT_ATTR_FLAG	Copy object without copying attributes Default behavior, without flag: Copy object with all its attributes
H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG	Use a matching committed datatype in the destination file when copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of committed datatype Default behavior without flag: A committed datatype in the source will be copied to the destination as a committed datatype. If a dataset in the source uses a committed datatype or an object in the source has an attribute of a committed datatype, that committed datatype will be written to the destination as an anonymous committed datatype. If copied in a single H5Ocopy() operation, objects that share a committed datatype in the source will share an anonymous committed datatype in the destination copy. Subsequent H5Ocopy() operations, however, will be unaware of prior anonymous committed datatypes and will create new ones. See the “See Also” section immediately below for functions related to the use of this flag.

See also

Functions and a callback function used to tune committed datatype copying behavior:

Version: 1.8.9 H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG added in this release.

Since: 1.8.0

◆ H5Pset_mcdt_search_cb()

herr_t H5Pset_mcdt_search_cb	(	hid_t	plist_id,
		H5O_mcdt_search_cb_t	func,
		void *	op_data
	)

Sets the callback function that H5Ocopy() will invoke before searching the entire destination file for a matching committed datatype.

Parameters

[in]	plist_id	Object copy property list identifier
[in]	func	User-defined callback function
[in]	op_data	User-defined input data for the callback function

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

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().

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.

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

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);

     H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);
     H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

     action = H5O_MCDT_SEARCH_STOP;
     H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
     H5Ocopy(...ocpypl_id...);
     ...
     ...
}

Note: H5Pset_mcdt_search_cb() will fail if the object copy property list is invalid.

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

See also

Since: 1.8.9