CL Command Reference - COPY
CL Command List > COPY Reference
Description:
The Copy Object (COPY) command copies a single object or a group of objects.
By default, if the target object already exists, the copy of that individual object will fail. If the REPLACE(*YES) parameter is specified the target object is overwritten. The newly created object must be renamed if it is stored in the same directory as the original object. If it is stored in a directory other than the one that contains the original object, it can retain the name of the original object.
An object name pattern can be used to copy a group of related objects. A pattern cannot be used to copy a group of objects from one file system to another unless the names in the source meet the requirements of the target file system. For example, a file named /OBJA in QOpenSys cannot be copied to directory /QSYS.LIB/MYLIB.LIB/FILEA.FILE, because the QSYS.LIB file system requires a name in the form OBJA.MBR when writing to a file. All names found within the pattern would fail if they did not meet the requirement of name.object-type.
The copy command can also be used to copy a directory tree where the directory, its contents, and the contents of all of its subdirectories are copied. A subtree copy will attempt to preserve as many attributes from the original objects as possible. This would make it possible to migrate data from one file system to another.
If the original object is a read-only file (a file that has the PC read-only attribute flag turned on), and SUBTREE(*NODIR) is specified, the newly created object will not be read-only. This follows the conventions of the OS/2 hierarchical file system (HFS).
Note: When the value of the Directory subtree (SUBTREE) parameter is *NONE or *ALL, the PC read-only attribute flag will be copied. The subtree copy is intended to preserve as many attributes of the original objects as possible.
When the To directory (TODIR) parameter is specified, the object is copied to that directory with the same name. The copied object is authorized the same as the original object. The user who issues the command owns the copied object if the Owner (OWNER) parameter value is *NEW.
When copying a file with SUBTREE(*NODIR) specified to the ¡åroot¡å (/), QOpenSys, QDLS, and UDFS file systems, the Last access date/time and the Data change date/time are preserved in the new file, and the Attribute change date/time is updated to the current time. The Last access date/time of the original file is updated to the current time. In the case of copying to a database file member (*MBR) in the QSYS.LIB or independent ASP QSYS.LIB file systems, the Data change date/time is updated as well.
Note: If the parameter SUBTREE(*YES) is specified the Create date/time is updated as well.
This command is an alias for the Copy Object (CPY) command and can also be issued using the following alternative command name:
. CPY
In addition to the COPY command, the Copy To Stream File (CPYTOSTMF) and Copy From Stream File (CPYFRMSTMF) commands can be used to copy between stream files and database member files or save files.
Restrictions:
1. The copy command will copy the object¡¯s public and private authorities where it is supported.
Note: The authority requirements for this command are complex with respect to file systems, object types, requested operations etc.. Therefore, see the iSeries Security Reference, SC41-5302 book for information about the required authorities for this command.
QSYS.LIB and independent ASP QSYS.LIB File System Differences
. If copying to a database file member from a different object type, or copying to or from a member not in the current job¡¯s library name space, some attributes are copied.
. When copying a database member to another member within the same library name space, attributes are handled in the same manner as the Copy File (CPYF) command (this only applies if the Data Format (DTAFMT) parameter is *BINARY).
. Other object types copied are handled the way the Create Duplicate Object (CRTDUPOBJ) command handles attributes (this only applies if the DTAFMT parameter is *BINARY).
. The REPLACE(*YES) option is only supported on file members, user spaces, and save files when the target object exists. All other object types will fail when the target object exists.
QOPT File System Differences
. If copying a file within the QOPT file system, the Create date/time is always updated to the current time.
QNetWare File System Differences
. If copying a file or directory to a location on the same server, the owner of the target object is always the caller of the command and the PC read-only flag is not copied.
. The scan-related attributes are not copied.
QFileSvr.400 File System Differences
. The OWNER(*KEEP) parameter is not supported when copying an object to the QFileSvr.400 File System. The copy will fail with error message CPFA0AD.
. The scan-related attributes are not copied.
Network File System (NFS) Differences
. The OWNER(*KEEP) parameter is not supported when copying an object to or from a mounted Network File System (NFS) directory. The copy will fail with error message CPFA0AD.
. The scan-related attributes are not copied.
Examples:
The alternative command name for COPY is CPY. The following examples use the alternative command name, but COPY can be replaced directly for CPY in all of them.
Example 1: Copying a File
CPY OBJ(¡¯DECEMBER-1994-MONTHLY-PAYROLL-FILE¡¯) TOOBJ(¡¯PAY¡¯)
This command creates another file named PAY that is a duplicate of the file named DECEMBER-1994-MONTHLY-PAYROLL-FILE.
Example 2: Copying a File to Another Directory
CPY OBJ(¡¯PAY¡¯) TODIR(¡¯MYDIR¡¯)
This command creates another file named PAY in directory MYDIR.
Example 3: Copying a Symbolic Link
CPY OBJ(¡¯SL1¡¯) TOOBJ(¡¯YOURDIR/SL2¡¯) SYMLNK(*YES)
If SL1 is a symbolic link, the new object YOURDIR/SL2 is also a symbolic link. If SYMLNK(*NO) was specified, the new object would be a copy of whatever SL1 pointed to, as long as it was a legal candidate for the copy function.
Example 4: Copying with Conversion
CPY OBJ(¡¯/DATAFB¡¯)
TOOBJ(¡¯/QSYS.LIB/APP1.LIB/DATA.FILE/DATAFB.MBR¡¯)
TOCCSID(*CALC) DTAFMT(*TEXT)
This command copies stream file ¡¯DATAFB¡¯ to the database file ¡¯DATAFB.MBR¡¯. By specifying TOCCSID(*CALC), the file system being copied to (the QSYS.LIB file system in this case) will try to create the new member in the same coded character set identifier (CCSID) as ¡¯/DATAFB¡¯. If this fails (in this case, if ¡¯DATA.FILE is not in the same CCSID as ¡¯DATAFB¡¯), the file system will be allowed to choose an appropriate CCSID and complete the copy. By specifying DTAFMT(*TEXT), the data in ¡¯DATAFB¡¯ is handled as text and is converted into the CCSID chosen for the new file ¡¯DATAFB.MBR¡¯.
Example 5: Copying a Directory Subtree
CPY OBJ(¡¯/QDLS/MYINFO¡¯) TODIR(¡¯/myfolder¡¯) SUBTREE(*ALL)
OWNER(*KEEP) REPLACE(*YES)
The *FLR object (QDLS file system folder) is created in the ¡¯/myfolder¡¯ directory in the ¡åroot¡å (/) file system with the path name ¡¯/myfolder/MYINFO¡¯. Its contents are copied as well. Since OWNER(*KEEP) is specified, the new objects created will belong to the same profiles as the old objects. With the REPLACE parameter set to *YES if any of the target files already exist they will be overwritten.