Copies an object in an HDF5 file
Procedure:
H5O_COPY(src_loc_id, src_name, dst_loc_id, dst_name, ocpypl_id, lcpl_id)
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
)
SUBROUTINE h5ocopy_f(src_loc_id, src_name, dst_loc_id, &
dst_name, hdferr, ocpypl_id, lcpl_id)
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: src_loc_id
CHARACTER(LEN=*), INTENT(IN) :: src_name
INTEGER(HID_T) , INTENT(IN) :: dst_loc_id
CHARACTER(LEN=*), INTENT(IN) :: dst_name
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: ocpypl_id
INTEGER(HID_T) , INTENT(IN), OPTIONAL :: lcpl_id
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 |
Description:
H5O_COPY 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 copy will be created with the path specified in dst_name
, which must not pre-exist in the destination location. If dst_name
already exists at the location dst_loc_id
, H5O_COPY will fail. If dst_name
is an absolute path, the copy will be created relative to the file’s root group.
The copy of the object is created with the property lists specified by ocpypl_id
and lcpl_id
. H5P_DEFAULT can be passed in for these property lists. The default behavior:
- of the link creation property list is to NOT create intermediate groups.
- of the flags specified by the object creation property list is described in H5P_SET_COPY_OBJECT.
These property lists or flags can be modified to govern the behavior of H5O_COPY as follows:
H5O_COPY 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 H5P_SET_COPY_OBJECT for optional settings. - If the path specified in
src_name
is or contains a soft link or an external link, H5O_COPY will copy the target object. Use H5L_COPY if the intent is to create a new soft or external link with the same value as the original link.
H5O_COPY can be used to copy an object in an HDF5 file. If an object has been changed since it was opened, it should be written back to the file before using H5O_COPY. The object can be written back either by closing the object (H5G_CLOSE, H5O_CLOSE, H5D_CLOSE, or H5T_CLOSE) or by flushing the HDF5 file (H5F_FLUSH).
See Also:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Example:
History:
Release | Change |
---|
1.8.9 | Fortran subroutine introduced in this release. |
1.8.0 | Function introduced in this release. |
--- Last Modified: August 09, 2019 | 09:21 AM