H5Pset_copy_object.htm

H5Pget_mcdt_search_cb.htm

H5Pset_mcdt_search_cb.htm

H5Padd_merge_committed_dtype_path.htm

H5Pfree_merge_committed_dtype_paths.htm

H5O_mcdt_search_cb_t.htm

H5Ocopy.htm

# H5Pset_copy_object.htm

Last modified: 14 March 2012
Name: H5Pset_copy_object
Signature:
  herr_t `H5Pset_copy_object`( hid_t `ocpypl_id`, unsigned `copy_options` )

Purpose:
  Sets properties to be used when an object is copied.

Description:
  `H5Pset_copy_object` sets properties in the object copy property list `ocpypl_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. Default behavior, without flag: Update only the values of object references.
  `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. See the “See Also” section immediately below for functions related to the use of this flag.

Parameters:

  hid_t `ocpypl_id` | IN: Object copy property list identifier
  unsigned `copy_options` | IN: Copy option(s) to be set

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

See Also:

  `H5Ocopy` The following functions and callback function can be used to tune copy behavior when the flag `H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG` is used:
  `H5Padd_merge_committed_dtype_path` `H5Pfree_merge_committed_dtype_paths` |  | `H5Pset_mcdt_search_cb` `H5Pget_mcdt_search_cb` `H5O_mcdt_search_cb_t`

Fortran90 Interface: h5pset_copy_object_f

      SUBROUTINE h5pset_copy_object_f(ocpypl_id, copy_options, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: ocpypl_id
                                    ! Object copy property list identifier
        INTEGER, INTENT(IN) :: copy_options
                                    ! Copy option(s) to be set, valid options are:
                                    !   H5O_COPY_SHALLOW_HIERARCHY_F
                                    !   H5O_COPY_EXPAND_SOFT_LINK_F
                                    !   H5O_COPY_EXPAND_EXT_LINK_F
                                    !   H5O_COPY_EXPAND_REFERENCE_F
                                    !   H5O_COPY_WITHOUT_ATTR_FLAG_F
                                    !   H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG_F

        INTEGER, INTENT(OUT) :: hdferr
                                    ! Error code
                                    ! 0 on success and -1 on failure
      END SUBROUTINE h5pset_copy_object_f

History:

  Release | C
  1.8.0 | Function introduced in this release.
  1.**.** | `H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG` added in this release.

# H5Pget_mcdt_search_cb.htm

Last modified: 14 March 2012
Name: H5Pget_mcdt_search_cb
Signature:
  herr_t `H5Pget_mcdt_search_cb`( hid_t `ocpypl_id`, H5O_mcdt_search_cb_t *`func`, void **`op_data` )

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

Description:
  `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 `ocpypl_id`.

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

Parameters:

  hid_t `ocpypl_id` |  | IN: Object copy property list identifier
  H5O_mcdt_search_cb_t *`func` |  | OUT: User-defined callback function
  void **`op_data` |  | OUT: User-defined input data for the callback function

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

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

See Also:

  `H5Ocopy` `H5Pset_copy_object` |  | `H5Pset_mcdt_search_cb` `H5O_mcdt_search_cb_t`

History:

  Release | Change
  *.**.** | C function introduced in this release.

# H5Pset_mcdt_search_cb.htm

Last modified: 14 March 2012
Name: H5Pset_mcdt_search_cb
Signature:
  herr_t `H5Pset_mcdt_search_cb`( hid_t `ocpypl_id`, H5O_mcdt_search_cb_t `func`, void *`op_data` )

Purpose:
  Sets the callback function that `H5Ocopy` will invoke before searching the entire destination file for a matching committed datatype.

Motivation:
  `H5Pset_mcdt_search_cb` provides the means to define a callback function. An application can then use that callback to take an additiional action before the default search of all committed datayptes in the destination file or to take an action that replaces that default search. This mechanism is intended to improve performance when the global search might take a long time.

Description:
  `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`.

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

Parameters:

  hid_t `ocpypl_id` |  | IN: Object copy property list identifier
  H5O_mcdt_search_cb_t `func` |  | IN: User-defined callback function
  void *`op_data` |  | IN: User-defined input data for the callback function

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

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

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

      /* The user-defined callback function */
      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);

          /* Enable the merging committed datatype feature. */
          H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

          /* Add a path to search for a matching committed datatype. */
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

          /*
           * Set the callback function to discontinue the global search
           * if H5Ocopy cannot find a matching committed datatype from the
           * above suggested path.
           */
          action = H5O_MCDT_SEARCH_STOP;
          H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
          H5Ocopy(...ocpypl_id...);
          ...
          ...
      }

See Also:

  `H5Ocopy` `H5Pset_copy_object` |  | `H5Padd_merge_committed_dtype_path` `H5Pget_mcdt_search_cb` `H5O_mcdt_search_cb_t`

History:

  Release | Change
  *.**.** | C function introduced in this release.

# H5Padd_merge_committed_dtype_path.htm

Last modified: 14 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 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`

History:

  Release | Change
  *.**.** | C function introduced in this release.

# H5Pfree_merge_committed_dtype_paths.htm

Last modified: 14 March 2012
Name: H5Pfree_merge_committed_dtype_paths
Signature:
  herr_t `H5Pfree_merge_committed_dtype_paths`( hid_t `ocpypl_id` )

Purpose:
  Clears the list of paths stored in the object copy property list `ocpypl_id`. These are the suggested paths previously set with `H5Padd_merge_committed_dtype_path`.

Description:
  `H5Pfree_merge_committed_dtype_paths` clears the suggested paths stored in the object copy property list `ocpypl_id`.

Parameters:

  hid_t `ocpypl_id` |  | IN: Object copy property list identifier.

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

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

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

          /* Enable the merging committed datatype feature. */
          H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

          /* Add a path to search for a matching committed datatype. */
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

          /* Do the copy. */
          H5Ocopy(...ocpypl_id...);
          ...
          ...
          /* Free the previous suggested path. */
          H5Pfree_merge_committed_dtype_paths(ocpypl_id);

          /* Add a path to search for a matching committed datatype. */
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dtypeB");

          /* Do the copy. */
          H5Ocopy(...ocpypl_id...);
          ...
          ...
      }

See Also:

  `H5Ocopy` `H5Pset_copy_object` |  | `H5Pset_mcdt_search_cb` `H5Padd_merge_committed_dtype_path`

History:

  Release | Change
  *.**.** | C function introduced in this release.

# H5O_mcdt_search_cb_t.htm

Current plan: Place this entry in H5O/ and publish it on the H5O RM page. Links to it will be to the entry within the H5O page rather than to the free-standing entry. It could be published adjacent to `H5Pset_mcdt_search_cb`, but that breaks standard practice and would probably be more confusing.

Last modified: 14 March 2012
Name: H5O_mcdt_search_cb_t
Signature:
  `typedef` H5O_mcdt_search_ret_t ( `*H5O_mcdt_search_cb_t` )( void *`op_data` )

Purpose:
  Provides the mechanism by which a user application may set an action for `H5Ocopy` to take after checking all suggested paths for a matching committed datatype but before starting the global search of the destination file.

Description:
  `H5O_mcdt_search_cb_t` is the callback function that `H5Ocopy` will invoke if the callback is set and when the merge committed datatype feature is enabled in the object copy property list (see `H5Pset_copy_object`).

  After searching the list of suggested committed datatype paths, `H5Ocopy` will invoke this callback before searching all committed datatypes in the destination file. This allows a user application to add a customized step to the search process. The callback function is set with `H5Pset_mcdt_search_cb` and the search process is described in `H5Padd_merge_committed_dtype_path`.

  Valid return values from this callback function are as follows (defined in the enumerated datatype `H5O_mcdt_search_ret_t` in `H5Opublic.h`):

  `H5O_MCDT_SEARCH_ERROR` |  | Aborts `H5Ocopy`.
  `H5O_MCDT_SEARCH_CONT` |  | Continues the global search of all committed datatypes in the destination file.
  `H5O_MCDT_SEARCH_STOP``` |  | Stops the search, but continues copying.

Warning:
  If the callback’s return value is `H5O_MCDT_SEARCH_ERROR`, `H5Ocopy` will abort and the destination file may be left in an inconsistent or corrupted state.

Parameters:

  void *`op_data` |  | IN/OUT: Pointer to user-defined input data. This is a pass-through of the data that was passed to `H5Pset_mcdt_search_cb`.

Returns:
  Returns one of the `H5O_MCDT_SEARCH_*` values described above.

Failure Modes:
  `H5O_mcdt_search_cb_t` failure modes are dependent on the implementation of the callback function.

Example Usage:
  This example defines a callback function in the object copy property list to discontinue the global search if a matching committed datatype cannot be found among the suggested paths.

      /* The user-defined callback function */
      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);

          /* Enable the merging committed datatype feature. */
          H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

          /* Add the path to search for a matching committed datatype. */
          H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

          /*
           * Set the callback function to discontinue the global search
           * if H5Ocopy cannot find a matching committed datatype from the
           * above suggested path.
           */
          action = H5O_MCDT_SEARCH_STOP;
          H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);

          /* Do the copy. */
          H5Ocopy(...ocpypl_id...);
          ...
          ...
      }

See Also:

  `H5Ocopy` `H5Pset_copy_object` |  | `H5Pset_mcdt_search_cb` `H5Pget_mcdt_search_cb`

History:

  Release | Change
  *.**.** | C function type introduced in this release.

# H5Ocopy.htm

Last modified: 14 March 2012
Name: H5Ocopy
Signature:
  herr_t `H5Ocopy`( hid_t `src_loc_id`, const char *`src_name`, hid_t `dst_loc_id`, const char *`dst_name`, hid_t `ocpypl_id`, hid_t `lcpl_id` )

Purpose:
  Copies an object in an HDF5 file.

Description:
  `H5Ocopy` copies the group, dataset or committed datatype specified by `src_name` from the file or group specified by `src_loc_id` to the destination location `dst_loc_id`.

  The destination location, as specified in `dst_loc_id`, may be a group in the current file or a location in a different file. If `dst_loc_id` is a file identifier, the copy will be placed in that file’s root group.

  The new copy will be created with the name `dst_name`. `dst_name` must not pre-exist in the destination location; if `dst_name` already exists at the location `dst_loc_id`, `H5Ocopy` will fail.

  The new copy of the object is created with the creation property lists specified by `ocpypl_id` and `lcpl_id`.

  `H5Ocopy` will always try to make a copy of the object specified in `src_name`.

  - If the object specified by `src_name` is a group containing a soft or external link, the default is that the new copy will contain a soft or external link with the same value as the original. See `H5Pset_copy_object` for optional settings.
  - If the path specified in `src_name` is or contains a soft link or an external link, `H5Ocopy` will copy the target object. Use `H5Lcopy` if the intent is to create a new soft or external link with the same value as the original link.

  Several flags are available to govern the behavior of `H5Ocopy`:

  - A flag controlling the creation of intermediate groups that may not yet exist is set in the link creation property list `lcpl_id` with `H5Pset_create_intermediate_group`.
  - Copying of committed datatypes can be tuned through the use of `H5Pset_copy_object`, `H5Padd_merge_committed_dtype_path`, `H5Pset_mcdt_search_cb`, and related functions.
  - Flags controlling other aspects of object copying are set in the object copy property list `ocpypl_id` with `H5Pset_copy_object`.

Parameters:

hid_t `src_loc_id` | IN: Object identifier indicating the location of the source object to be copied
const char *`src_name` | IN: Name of the source object to be copied
hid_t `dst_loc_id` | IN: Location identifier specifying the destination
const char *`dst_name` | IN: Name to be assigned to the new copy
hid_t `ocpypl_id` | IN: Object copy property list
hid_t `lcpl_id` | IN: Link creation property list for the new hard link

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

See Also:

  | `H5Pset_copy_object` `H5Pset_create_intermediate_group` |  | `H5Padd_merge_committed_dtype_path` `H5Pset_mcdt_search_cb`

Fortran90 Interface:
  None.

History:

Release | C
1.8.0 | Function introduced in this release.