COPY Options

You can specify the following different options in a COPY statement:

  • BACKUP

  • BECOMEOWNER

  • CATALOG

  • COMPARE

  • DSONERROR

  • FROMSTART

  • PROPAGATE

  • REMOVE

  • REPORT

  • SELECT

  • SKIPEXCLUSIVE

  • USEPATH

  • VERIFY

  • WAITONERROR

BACKUP

Description

Places a backup reference in the system catalog directory of the source disk for each cataloged file that is copied.

Constraints

  • Applies only to a cataloging system.

  • If you specify AS or ONTO with the BACKUP option, you get a WFL syntax error.

  • If you specify a tape source, you get a WFL syntax error.

  • You cannot use this option with CD-ROM sources or destinations.

  • The source and destination volumes must be listed in the volume library before the BACKUP option can be used.

  • You cannot use this option with FTP, NFT, or Host Services File Transfer.

BECOMEOWNER

Description

Controls the ownership of the destination directories and files moved within the permanent directory namespace and controls the ownership of the destination backup files in the reserved backup directories. This option causes the OWNER attribute to be set to the usercode of the task performing the operation rather than having the value copied from the source.

All other attribute values, including those for GROUP and SECURITYMODE, are copied from the source. If a nonprivileged user issues a COPY or ADD statement without the BECOMEOWNER option, only the source directories and files already owned by that user are included.

Constraints

  • Applies only within the permanent directory and reserved backup directory namespaces.

  • You cannot use this option with FTP, NFT, or Host Services File Transfer.

CATALOG

Description

Marks copied files as cataloged files and lists the source versions as backup copies in the catalog directory for the destination disk.

If you use the Native File Transfer (NFT) Service to transfer the files between hosts, the source versions are not marked as backup copies at the destination host, but the destination files are marked as cataloged files.

The source and destination volumes must be listed in the volume library of the applicable source or destination host before you can use the CATALOG option.

Constraints

  • Applies only to a cataloging system.

  • If you specify AS or ONTO with the CATALOG option, you get a WFL syntax error.

  • If you specify a tape destination, you get a WFL syntax error.

  • You cannot specify a CD-ROM destination.

  • You cannot use this option with FTP or Host Services File Transfer.

COMPARE

Description

Ensures that the new copies of the file are written correctly.

Ensures that the new copies of the files are readable, and that the data in the files matches the data in the source files.

Compares the copied file and the original file bit by bit, immediately after the file is copied.

Gives you a chance to approve a recopy if an error occurs while comparing a file.

Constraints

  • Not available for quarter-inch cartridge tapes; use the VERIFY option instead.

  • Not available with Open Systems Interconnection (OSI), Transmission Control Protocol/Internet Protocol (TCP/IP) File Transfer Protocol (FTP), or Host Services File Transfer (HS).

DSONERROR

Description

Causes library maintenance to terminate with a DS response whenever

  • A file or directory to be copied is missing, and library maintenance issues a “<filename> FILE NOT ON <source volume>” message.

  • An error prevents a file from being copied to one or more destinations.

  • Library maintenance issues a “RECOPY REQUIRED” RSVP, and the operator replies with DS, FR, or OF.

If a COPY or ADD statement terminates abnormally when the DSONERROR option is used, library maintenance purges all of the output tapes it is currently copying.

If a COPY or ADD statement terminates abnormally and multivolume output tapes are being used, library maintenance purges only the current volume.

In the case of multiple output tapes, an error termination causes all destination volumes to be purged.

Example 1

COPY & DSONERROR F1 TO T1, TO T2;

An error termination causes both T1 and T2 to be purged.

In the case of multiple copy requests, an error termination causes one of the destination tapes to be purged.

Example 2

COPY & DSONERROR F1 TO T1, F2 TO T2;

An error termination causes either tape T1 or tape T2 to be purged, but not both tapes.

If a COPY or ADD statement with both the BACKUP and DSONERROR options terminates abnormally, then in addition to purging any output tapes, library maintenance erases or deletes any catalog backup information for files that refer to the purged tapes.

In the case of multivolume output tapes, library maintenance erases or deletes the catalog backup information for files that reference any of the volumes in the specified set of tapes.

Constraint

You cannot use this option with FTP, NFT, or Host Services File Transfer.

FROMSTART

Description

Overrides any file transfer resumption if the transfer had been previously interrupted, and instead completely transfers again all of the files, including those already transferred with the NFT Service before the interruption.

Constraints

This option applies only when NFT is used to transfer files between hosts.

PROPAGATE

Description

Enables copied files and permanent directories to inherit the security of the destination directory.

Constraints

  • This option applies only when the destination PROPAGATESECURITYTOFILES or PROPAGATESECURITYTODIRS attribute of the directory so specifies.

  • You cannot use this option with FTP, NFT, or Host Services File Transfer.

REMOVE

Description

Causes library maintenance to remove files from the source disk being copied. Library maintenance removes source files even if they are in use by another program.

  • If you specify the VERIFY option when copying to tape, library maintenance verifies the destination tape before removing the source files.

  • If you specify the DSONERROR option, library maintenance delays removing the source files until all the files have been successfully copied.

  • If a program updates or replaces a source file before library maintenance removes it, then library maintenance removes the updated or replaced version of the file.

Constraints

You cannot use this option with tape or CD-ROM sources, with NFT specified, or in any host to host transfer.

REPORT

Description

Causes library maintenance to print a report of the files it copied and any errors encountered. When & REPORT is specified, library maintenance does not write “file copied” messages in the job log or the system sumlog.

Constraints

You cannot use this option with FTP, NFT, or Host Services File Transfer.

SELECT

Description

Causes library maintenance to call the LIBMAINTSELECTOR procedure in the ARCHIVESUPPORT library for each file to be copied. You or your site can code a special version of the LIBMAINTSELECTOR procedure that indicates which destinations, if any, a file should be copied to.

For information on how to code a custom LIBMAINTSELECTOR procedure, refer to the SYMBOL/ARCHIVESUPPORT DCALGOLSYMBOL file and the MCP System Interfaces Programming Reference Manual.

Constraints

You cannot use this option with FTP, NFT, or Host Services File Transfer.

SKIPEXCLUSIVE

Description

Causes the system to not copy those files from disk that are opened with EXCLUSIVE=TRUE or that are KEYEDIOII files marked as being updated.

Constraints

You cannot use this option with FTP or Host Services File Transfer.

USEPATH

Description

Causes the DATAPATH attribute to be used when resolving nonqualified file names. This includes file names without a usercode or system (*) prefix and without a family name or with a family name of DISK.

Constraints

Only the first element in the DATAPATH attribute string is used. Substitution is only applied when the source volume is disk. It is not used if the source is tape or CD-ROM. You cannot use this option with FTP, NFT, or Host Services File Transfer.

Examples

The following example shows the use of the USEPATH modifier to copy the files *DIR/SHARED/PROJECTFILES/MYFILE from PROJECTPACK and *YOURFILE from DISK to tape:

COPY & USEPATH MYFILE, *YOURSELF TO BACKUPTAPE;
   DATAPATH = *DIR/SHARED/PROJECTFILES ON PROJECTPACK;

The following example shows the interaction of the USEPATH modifier with the AS library maintenance option:

COPY & USEPATH A AS D/E, B AS *F/G

The command in the previous example when run with the following DATAPATH attribute copies the files.

DATAPATH = *DIR/SHARED/PRODUCTION ON SHAREDFILES, (*)ON DISK

The following is the result:

*DIR/SHARED/PRODUCTION/A 
  (retitled *DIR/SHARED/PRODUCTION/D/E) and
*DIR/SHARED/PRODUCTION/B (retitled *F/G)
  from SHAREDFILES to SHAREDFILES

VERIFY

Description

Ensures that the new copies of the file are written correctly and readable, and the data in them is not garbled.

Verifies files by calculating the checksums for those files as they are copied, and compares those values as follows:

  • Disk source

    No checksum is calculated for files read from disk. Library maintenance does not verify files read from disk.

  • Disk destination

    Library maintenance calculates a checksum for a file as the file is copied to disk. The verify process re-reads the file from disk when the copy is completed; calculates the checksum of the new file; then compares that value with the value calculated while writing the file to disk. If a mismatch or I/O error occurs, library maintenance issues an error message, and it might issue a recopy RSVP message.

  • Tape source

    The copy procedure calculates a checksum for the file as it is read from the tape. That value is compared with the checksum record, at the end of the file, read from the tape. If the VERIFY option was not specified when the tape was created, there is no checksum record on the tape and library maintenance issues a warning.

    If a mismatch occurs, library maintenance issues an error message; it might also issue an RSVP message.

  • Tape destinations

    The copy procedure calculates a checksum for each file as the file is written to the tape. After each file an extra record containing a checksum is written on the tape. When all the files have been written to the tape, the tape is rewound, and the verify process starts. The verify procedure reads each file from the tape and calculates a checksum for the file. If that checksum does not match the checksum on the tape, or if there are I/O errors while reading from the tape, library maintenance issues an error message, and it might issue a special RSVP message to check whether the tape is to be purged or the bad file is to be skipped.

  • CD-ROM sources or destinations

    Library maintenance does not calculate a checksum when reading from or writing to CD-ROMs.

Constraints

This option is not available with FTP or Host Services File Transfer.

WAITONERROR

Description

Causes library maintenance to issue an RSVP message whenever an error occurs. Examples of possible errors include

  • Requesting a file or directory that is missing

  • Failing an attempt to open a tape

The RSVP message halts library maintenance until the operator or programmer responds with either OK or DS.

A response of OK causes library maintenance to continue the COPY with other files or tapes.

A response of DS will terminate the library maintenance program. After investigating the error which created the RSVP message, you can re-issue the COPY or ADD statement.

Constraints

You cannot use this option with FTP, NFT, or Host Services File Transfer.