6.4.13COPY
Syntax
COPY [TRUNCATE] [GROUP | DATASET | ATTRIBUTE | [SOFT] LINK | EXTERNAL LINK] [file_name] object_name [, [file_name] object_name]* TO [target_file_name] new_object_name [, [target_file_name] new_object_name]*
Description
Copy an existing HDF5 group, dataset, attribute, (soft) link, or external link named object_name to new_object_name. Multiple groups, datasets, attributes, (soft) links, or external links can be copied at once by separating their names with a comma (,). If new_object_name already exists, it is not overwritten, no subsequent objects are copied, and an error is raised. To overwrite an existing object, specify the keyword TRUNCATE (all data stored in the object will be permanently lost). In case (1) a group and an attribute or (2) a dataset and an attribute with identical names (object_name) are stored in the same location (i.e. group) and none of the keywords GROUP, DATASET, or ATTRIBUTE is specified, the object to be copied is the group or dataset, respectively. To explicitly copy an object according to its type, the keyword GROUP, DATASET, ATTRIBUTE, [SOFT] LINK, or EXTERNAL LINK must be specified.
Parameter(s)
file_name – optional string that specifies the name of the HDF5 file storing the object to be copied. If file_name is specified, the file is opened on the fly, the object is copied, and the file is subsequently closed. If not specified, the file currently in use is used instead.
object_name – mandatory string that specifies the name of the object to copy.
target_file_name – optional string that specifies the name of the HDF5 file in which to copy the object.
new_object_name – mandatory string that specifies the new name and/or location (within the HDF5 file or in another HDF5 file specified by target_file_name) to use for copying object_name.
Return
Nothing
Example(s)
# create two HDF5 groups named "my_group0" and "my_group1"
CREATE GROUP my_group0, my_group1
# create two HDF5 datasets named "my_dataset0" and "my_common" of data type short
CREATE DATASET my_dataset0, my_common AS SMALLINT
# create two HDF5 attributes named "my_attribute0" and "my_common" of data type float
CREATE ATTRIBUTE my_attribute0, my_common AS FLOAT
# copy an object named "my_group0" to "my_group2" (the object "my_group2" will not be overwritten if it already exists)
COPY my_group0 TO my_group2
# copy an object named "my_group1" into object "my_group0" and rename it as "my_subgroup0" (the object "my_subgroup0" will be overwritten if it already exists in object "my_group0")
COPY TRUNCATE my_group1 TO my_group0/my_subgroup0
# copy two objects named "my_dataset0" and "my_attribute0" into objects "my_group0" and "my_group0/my_subgroup0", respectively (both objects "my_dataset0" and "my_attribute0" will not be overwritten if they already exist in objects "my_group0" and "my_group0/my_subgroup0")
COPY my_dataset0, my_attribute0 TO my_group0/, my_group0/my_subgroup0/
# copy attribute "my_common" to "my_attribute1" (the attribute "my_attribute1" will not be overwritten if it already exists)
COPY ATTRIBUTE my_common TO my_attribute1
# copy dataset "my_common" to "my_dataset1" (the dataset "my_dataset1" will not be overwritten if it already exists)
COPY DATASET my_common TO my_dataset1# copy an object named "my_group3" from the file currently in use to "my_group4" in an HDF5 file named "my.file0.h5" (the object "my_group4" will not be overwritten if it already exists in the file)
COPY my_group3 TO my_file0.h5 my_group4
# copy an object named "my_group5" from an HDF5 file named "my_file1.h5" to "my_group6" in the file currently in use (the object "my_group6" will not be overwritten if it already exists in the file)
COPY my_file1.h5 my_group5 TO my_group6
# copy an object named "my_group7" from an HDF5 file named "my_file2.h5" to "my_group8" in an HDF5 file named "my.file3.h5" (the object "my_group8" will not be overwritten if it already exists in the file)
COPY my_file2.h5 my_group7 TO my_file3.h5 my_group8