Last modified: 3 July 2013
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 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 dataype in the destination copy. Subsequent `H5Ocopy` operations, however, will be unaware of prior anonymous committed dataypes and will create new ones. 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` |  |
  Copying Committed Datatypes with `H5Ocopy` |  | A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5
  `H5Padd_merge_committed_dtype_path` `H5Pfree_merge_committed_dtype_paths` `H5Pset_mcdt_search_cb` `H5Pget_mcdt_search_cb` `H5O_mcdt_search_cb_t` |  | Functions and a callback function used to tune committed datatype copying behavior

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.8.9 | `H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG` added in this release.