Copy Optical (CPYOPT)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Copy Optical (CPYOPT) command copies a specific file, all files, new files, or changed files in a specified directory to another directory or to another optical volume. This command also allows you to:

Create a directory in which to copy the files.
Copy all subdirectories and their files for a specified directory.
Replace an existing file with the same name.

If the from-volume or the to-volume is a backup optical volume, the names of the directories, the subdirectories, and the files do not change during the copy operation. The creation and modification dates and times of a directory, a subdirectory, or a file also do not change during the copy operation.

Restriction: To use this command you must have *USE authority to the authorization list securing the volume being copied (FROMVOL) and *CHANGE authority to the authorization list securing the new volume (TOVOL).

Top

Parameters

Keyword	Description	Choices	Notes
FROMVOL	From volume identifier	Element list	Required, Positional 1
	Element 1: Volume	Character value
	Element 2: Volume type	PRIMARY, BACKUP
FROMPATH	From path	Character value	Required, Positional 2
TOVOL	To volume identifier	Element list	Required, Positional 3
	Element 1: Volume	Character value, *FROMVOL
	Element 2: Volume type	PRIMARY, BACKUP
TOPATH	To path	Character value, *FROMPATH	Optional
SLTFILE	Select files to copy	CHANGED, NEW, *ALL	Optional
CPYSUBDIR	Copy subdirectories	NO, YES	Optional
CRTDIR	Create directory	NO, YES	Optional
ALWCPYOPP	Allow copy to opposite side	NO, YES	Optional
COPYTYPE	Copy option	IOP, SYSTEM	Optional
FROMTIME	Starting date and time	Element list	Optional
	Element 1: Starting date	Date, *BEGIN
	Element 2: Starting time	Time, *AVAIL

Top

From volume identifier (FROMVOL)

Specifies the volume identifier and the type of the optical volume that contains the directories and the files being copied.

Element 1: Volume

volume-identifier: Specify the identifier of the volume that contains the directories and files being copied.

Element 2: Volume type

*PRIMARY: The optical volume is a primary volume.
*BACKUP: The optical volume is a backup volume.

Top

From path (FROMPATH)

Specifies the path name of the directory or file being copied from the from-volume. If the path name is a directory, all files in the specified directory are copied. If the path name is a file, only that file is copied.

*BOOT

The boot file is copied from the from-volume.

Note

Copying the boot file will initialize and clear any existing data on the volume.

'path-name'

Specify the path name of the directory or file being copied from the from volume.

Top

To volume identifier (TOVOL)

Specifies the volume identifier and the type of the optical volume to which the directories and the files are being copied.

Element 1: Volume

*FROMVOL: The volume identifier is the same as the identifier of the optical volume from which the the objects are copied.
volume-identifier: Specify the name of the optical volume to which the objects are copied.

Element 2: Volume type

*PRIMARY: The optical volume is a primary volume.
*BACKUP: The optical volume is a backup volume. You can use a new backup volume or a backup volume which has previously been used as the volume to which objects are copied. For more information about backup volumes, refer to the Optical Support, SC41-4310 book.

Top

To path (TOPATH)

Specifies the path name of the file to be written or the path name of the directory to receive the new file on the to-volume beginning with the root directory of the volume.

*FROMPATH: The path name is the same as the path name of the files or directories being copied from the from-volume.
'path-name': Specify the path name of the directory to receive the copied files or the path name of the file to be written.

Top

Select files to copy (SLTFILE)

Specifies how the files or directories are selected for copying. If files are not copied based on the SLTFILE value specified, it is not considered an error condition. The files will be considered 'not eligible to copy' in the completion message but the command may still complete without errors.

*CHANGED: The file is copied if the file on the from-volume has a changed date and time later than that of the file on the to-volume. Two sets of dates and times determine if a file has changed: either the date and time the file was last changed, or the date and time the file attributes were last changed. These dates and times can be displayed by specifying DATA(*FILATR) on the Display Optical (DSPOPT) command.
*ALL: All files are copied. The files that exist on the to-volume are replaced even if the dates are the same.
*NEW: The files are copied only if they do not exist on the to-volume.

Top

Copy subdirectories (CPYSUBDIR)

Specifies whether to copy the files in the subdirectories.

*NO: Subdirectories and files in any subdirectories are not copied.
*YES: The files in the subdirectories are copied. The subdirectories are created on the to-volume if they do not exist. The newly created subdirectories have the same name as they did on the from-volume, even though the parent directory name can be different.
A check is made prior to the copy operation to ensure that any resulting new path name does not exceed the maximum path name length. A check is also made to ensure that you do not attempt to copy all subdirectories of a directory to a subdirectory of that directory on the same volume.

Top

Create directory (CRTDIR)

Specifies whether or not the last directory of the to-path is created if it does not exist on the to-volume. The existence of all elements of the to-path, execpt for the last element, are verified prior to the start of the CPYOPT request.

Note: If either the to-volume or from-volume was initialized as an optical volume whose type is backup, this parameter is ignored.

*NO: The last directory of the to-path will not be created if it does not exist on the to-volume.
*YES: The last directory of the to-path will be created if it does not exist on the to-volume. This parameter refers only to the directory to which files or directories are copied and does not apply to subdirectories under that directory. The CPYSUBDIR parameter controls whether subdirectories are created.

Top

Allow copy to opposite side (ALWCPYOPP)

Specifies whether to allow copying files or directories from a volume on one side of an optical cartridge to the opposite side of the optical cartridge.

Note: System performance is degraded when copying large amounts of data to the opposite side of an optical cartridge.

*NO: The copy operation is not attempted if the to-volume is on the opposite side of the from-volume. You can use this value to prevent inadvertent copying to the opposite side of an optical cartridge.
*YES: The copy operation is attempted if the to-volume is on the opposite side of the from-volume.
Note: This value is not valid if either the from-volume or to-volume optical cartridge was initialized as an optical volume whose type is backup.

Top

Copy option (COPYTYPE)

Specifies the type of processing to be used for the copy request.

*IOP

The input/output processor (IOP) copies the data from one volume to another with minimal data movement. If two volumes are required, two drives in the optical media library are allocated for the duration of the copy operation.

Note: Specifying COPYTYPE(*IOP) provides the best performance for the copy request; however, it can also adversely affect interactive performance of requests to other volumes in the optical media library because two optical drives in the optical media library are allocated for the duration of the copy.

*SYSTEM

The system copies the data using available resources. This type of processing is automatically used when:

Only one drive is operable
The two volumes are in separate optical media libraries
The two volumes are on the opposite side of the same optical cartridge
The media format of either volume is Universal Disk Format (UDF)
The coded character sets of the volumes are different

This option is recommended if interactive requests will be made to volumes in the optical media library during the copy operation.

Top

Starting date and time (FROMTIME)

Specifies a starting date and time used to determine if a file or directory is selected for copying. All files or directories that have been created or changed, or whose attributes have changed, on or after the starting date and time are selected for copying. This parameter is ignored if copying a single file or when copying from a backup volume to a primary volume.

You can determine when a file was last created or changed by:

Specifying DATA(*FILATR) on the Display Optical (DSPOPT) command.
Using the hierarchical file system (HFS) API program QHFRTVAT. The standard attribute, QWRTDTTM, is the file last changed date and time. The extended attribute, OPT.CHGATDTTM, is the attribute last changed date and time.

Element 1: Starting date

*BEGIN: All dates found are used. All the files and directories are selected for copying.
start-date: Specify a date to be used as a starting point. All files created or modified on or after the start date are selected.
The date must be entered in the format specified by the system values, QDATFMT, and, if separators are used, QDATSEP.

Element 2: Starting time

*AVAIL

All available times for the starting date are used.

start-time

Specify a time to use as the starting time or the starting date. The time separator is defined by the system value QTIMSEP. separator as follows:

With a time separator, specify a string of 5 or 8 digits, where the time separator for the job separates the hours, minutes, and seconds. If you issue this command from the command line, the string must be enclosed in apostrophes. If a time separator other than the separator specified for your job is used, this command fails.
Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds. Valid values for hh range from 00 through 23. Valid values for mm and ss range from 00 through 59.

Top

Examples

Example 1: Copying All Files in All Directories

CPYOPT   FROMVOL(VOL01)  FROMPATH('/')  TOVOL(VOL02)
         CPYSUBDIR(*YES)  SLTFILE(*ALL)  CRTDIR(*YES)

This command copies all files in all directories and subdirectories from the optical volume VOL01 to the optical volume VOL02. Directories are created on volume VOL02 if they do not exist. If the files already exist on volume VOL02, they are replaced.

Example 2: Copying Changed Files

CPYOPT   FROMVOL(VOL01)  FROMPATH('/DIR1/DIR2')  TOVOL(VOL02)

This command copies all changed files in the directory /DIR1/DIR2 to the same files on the optical volume VOL02.

Example 3: Copying Files From a Backup to a Primary Volume

CPYOPT   FROMVOL(VOL01BACKUP *BACKUP)  FROMPATH('/DIR1')
         TOVOL(VOL02)  CPYSUBDIR(*YES)

This command copies all files and subdirectories in the directory /DIR1 on the optical backup volume VOL01BACKUP to the same files on the primary optical volume VOL02.

Top

Error messages

*ESCAPE Messages

OPT0147: SLTFILE value not allowed for operation.
OPT0149: CPYSUBDIR(*YES) not allowed with FROMPATH value.
OPT0152: Specified start time not allowed with FROMTIME(*BEGIN).
OPT1105: File is read only.
OPT1115: File not found.
OPT1120: File already exists.
OPT1125: File is in use.
OPT1129: Operation not allowed to file opened for Expanding Buffer I/O.
OPT1130: File name specified is a reserved file name.
OPT1135: Request failed because number of open files is at the limit.
OPT1140: Unexpected error occurred during file processing.
OPT1185: Cannot access held optical file.
OPT1205: Directory not found.
OPT1212: Directory in use.
OPT1220: File or directory name already exists.
OPT1224: Path length exceeds the maximum of 256 bytes.
OPT1255: File is corrupted.
OPT1261: Active file found on volume &1.
OPT1305: Optical volume &1 is read only.
OPT1315: Optical volume &1 is write protected.
OPT1317: Directory name is too long.
OPT1320: Optical volume &1 in use.
OPT1325: Optical volume format not recognized.
OPT1330: Optical volume not found or not useable.
OPT1331: Optical volume &1 not found.
OPT1340: Optical volume &1 not initialized.
OPT1344: Optical file name not valid.
OPT1345: No free space available on media.
OPT1346: Operation not allowed to volume located in a remote optical device.
OPT1350: Write operation failed to optical volume &1.
OPT1360: Media directory corrupted on optical volume &1.
OPT1460: Optical volume &1 is not in an optical device.
OPT1462: Operation not completed, optical volume is not a backup volume.
OPT1463: Operation not completed, optical volume is not a primary volume.
OPT1530: &1 does not represent a valid optical device.
OPT1555: Optical device &1 in use.
OPT1605: Media or device error occurred.
OPT1640: Error occurred reading files or directories.
OPT1790: Operation not allowed or conflicts with another request.
OPT1795: Error accessing directory attributes.
OPT1805: Error accessing optical volume index file.
OPT1810: Error accessing optical directory index file.
OPT1813: Unexpected error occurred.
OPT1815: Internal program error occurred.
OPT1820: Internal error occurred on optical device &1.
OPT1821: Error occurred on optical device &1.
OPT1825: Optical indexes are incorrect for optical device &1.
OPT1860: Request to optical device &1 failed.
OPT1861: No device description configured for resource &1.
OPT1862: No active device description for resource &1.
OPT1863: Optical libraries need to be reclaimed.
OPT1872: Optical request timed out or was cancelled.
OPT2001: &1 files copied; &2 files or directories failed; &8 files not eligible to copy.
OPT2004: Copy request ended abnormally. &1 files copied.
OPT2005: No files found in directory.
OPT2006: Directory path length too long.
OPT2007: TOVOL on opposite side of FROMVOL.
OPT2008: Copy request is not allowed.
OPT2009: Copy not permitted from backup volume.
OPT2010: Copy not permitted to backup volume.
OPT2015: File failed to copy.
OPT2028: Copy to backup not allowed for optical volumes specified.
OPT2029: TOVOL on opposite side of FROMVOL
OPT2040: Error accessing backup control file.
OPT2301: Internal system object in use.
OPT2420: Not authorized to optical volume &2.
OPT2422: Not authorized to file or directory.
OPT7740: User not authorized to object &2 in library &3 type &4.

Top