HDF5 1.14.5
API Reference
|
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. | |
Adds a path to the list of paths that will be searched in the destination file for a matching committed datatype.
[in] | plist_id | Object copy property list identifier |
[in] | path | The path to be added |
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:
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:
If no match is found, H5Ocopy() will perform the following in the destination file:
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...); ... ... }
path
.Clears the list of paths stored in the object copy property list.
[in] | plist_id | Object copy property list identifier |
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...); ... ... }
Retrieves the properties to be used when an object is copied.
[in] | plist_id | Object copy property list identifier |
[out] | copy_options | Copy option(s) set in the object copy property list |
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().
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.
[in] | plist_id | Object copy property list identifier |
[out] | func | User-defined callback function |
[out] | op_data | User-defined data for the callback function |
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
.
Sets properties to be used when an object is copied.
[in] | plist_id | Object copy property list identifier |
[out] | copy_options | Copy option(s) to be set |
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
See the “See Also” section immediately below for functions related to the use of this flag. |
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.
[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 |
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:
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...); ... ... }