Basic Copy Request
A basic copy request consists of a COPY or ADD verb, followed by a list of files and/or directories to be copied, an optional FROM <source volume> specification, and an optional TO <destination volume> specification.
FROM
You can optionally include a FROM source volume phrase that designates from where the files are to be copied. If you do not specify a FROM source volume construct, the files are copied from the disk family named DISK.
TO
You can optionally include a TO destination volume phrase that designates where the files will be copied. If you do not specify a TO destination volume construct, the files are copied to the disk family named DISK.
Family Substitution
Family substitution occurs for one or more of the source and/or destination disk family names specified in the COPY statement when either of the following conditions exist:
-
The target family name in the FAMILY assignment statement matches the source and/or destination disk family names specified in the COPY statement.
-
You omitted either the FROM source volume or the TO destination volume phrase in the COPY statement, and the implied family name DISK matches the name DISK in the FAMILY statement.
Library maintenance never uses the name supplied after OTHERWISE in a family substitution statement.
COPY Constructs
The copy file, source volume, destination volume, and volume name constructs are described in the following material.
Specifies the names of the files or directories to be copied. If you use the AS option, specifies the names to which the files or directories should be copied. If you do not use the AS option, the output file names are exactly the same as the input file names. Output file names might differ from input names. The following conditions also apply when you use the AS option:
-
If you specify a universal file name, the new copy of the file is given the new name you specify.
-
If you specify a directory name, then the new copy of each file copied from that directory is given the new directory name you specified instead of the old directory name, and the portion of the file name that follows the old directory name is retained.
-
If you specify a file or directory name, if the copy process runs under a usercode and you do not include a usercode or an asterisk (*) with the new file name or new directory name, the new file names will all be prefixed with the usercode under which the copy process is running. The ONTO option is limited to use with data files whose integer value of the FILEKIND attribute is greater than or equal to 64.
The ONTO option cannot be used for object code files, compilers, or system files. If the NOCOPYONTO security option is set, then the ONTO option cannot be used for any file. The NOCOPYONTO option is available only on a system that contains the Security Accountability Facility software.
<source volume> <destination volume>
Specifies the source volume of the files to copy and the destination volume(s) for those files. If the source or destination volume is not specified, the volume DISK is assumed. If all the copy file constructs contain an AS name, you do not have to specify a source or destination volume. If more than one destination volume is specified, all files are copied at the same time and in the same order, to all destination volumes, thus creating multiple copies. In addition, you can indicate certain file attributes and tape volume attributes for files being copied from a source volume or to a destination volume with the source volume attribute list and destination volume attribute list constructs.
Indicates the name of the volume from which or onto which the files are copied. If the volume name is DISK or PACK, the default file kind is DISK; otherwise, the default file kind is TAPE. If # <string primary> is specified for the volume name, the default file kind is TAPE. When the volume name includes a <string primary>, embedded periods will terminate the volume name unless the entire name is enclosed in quotes. If the file kind is DISK, the volume name cannot contain a period. A volume name cannot contain a period for a file kind of DISK.
Family substitution is used if the file kind is DISK and the job or task has an active family specification. Only the primary substitute family name is used by Library Maintenance and NFT. (Refer to FAMILY Assignment and Interrogating Complex Task Attributes.)
<tape file number>
Specifies the position number of the file on the source tape or source CD-ROM. The position number of the first file on a tape is 1, and so forth. The <tape file number> must be a positive integer that is greater than zero (0) and has less than 12 digits (counting leading zeros).
To determine the tape file number of a particular file on a CD or a tape that does not have an associated LIBMAINTDIR directory, use the TDIR system command or use FILEDATA:
RUN *SYSTEM/FILEDATA ("TAPEDIR: <volume name>")or
RUN *SYSTEM/FILEDATA ("TAPEDIR: <volume name> CD")To determine the tape file number of a particular file on a CD or tape that has an associated LIBMAINTDIR directory, use FILEDATA:
RUN *SYSTEM/FILEDATA ("NAMELIST: LIBMAINTDIR=<file title>")The <file title> variable is the file title of the LIBMAINTDIR file associated with the tape or CD.
| Note: | To see the file numbers in the FILEDATA LIBMAINTDIR report, you can use the output option PRINTER. If you use the output option SCREEN, SPO, TTY, or FILENAME, then you need to include a DEFINEOUTPUT request that sets LINEWIDTH to at least 81. |
For more information on using FILEDATA, see the System Software Utilities Operations Reference Manual.
You can use the tape file number in ordinary library maintenance copy statements and in NFT file transfer copy statements. You cannot use the tape file number with other file transfer protocols. You cannot specify the ORIGIN family name for a tape file number.
ORIGIN Clause
When copying from tape or CD-ROM, you can use the ORIGIN clause to select those files that were originally copied to tape or CD-ROM from the specified disk family. This can be useful if you previously copied files with the same file names from different disk families to the same tape or CD-ROM. For example, the following form of the statement copies two versions of SYSTEM/ALGOL to the SA tape:
COPY SYSTEM/ALGOL FROM PACK, SYSTEM/ALGOL FROM SYS (PACK) TO SA;
You can then retrieve the version of the file that was copied from either one of the disk families by specifying the disk family name as in the following statement:
COPY SYSTEM/ALGOL ORIGIN SYS FROM SA TO NEWSYS (PACK),
TO SYSTAPE;You can use ORIGIN in the file list for a FROM clause that refers to a tape or CD-ROM source. You cannot, however, use ORIGIN for disk sources. You can use ORIGIN with NFT file transfer requests but not with other kinds of file transfer requests.
You cannot use ORIGIN to select files on tapes if the tapes do not have origin information. Tapes created before SSR 41.2 and tapes created by the NFT file transfer service before SSR 50.1 do not have origin information. Any file copied from a tape or CD-ROM without origin information to another tape or CD-ROM does not have origin information either. You can use the FILEDATA TAPEDIR report to check which files on a tape or CD-ROM has origin information.
ONTO Clause
| Note: | The ONTO clause was originally intended for copying data to Installation Allocated Disk (IAD) files. Because IAD files are no longer supported, there is little reason to use the ONTO clause. |
The ONTO clause changes the handling of cases where a file of the requested name already exists at a disk destination. In such a case, library maintenance
-
Opens the existing disk file at the destination. (If no file of the same name exists at the destination, library maintenance does not perform the copy.)
-
Copies data from the source file to the existing destination file.
By contrast, when ONTO is not specified, library maintenance normally does the following:
-
Creates a new file on disk.
-
Copies the data and file attributes from the source file to the new file.
-
Locks the new file into the directory. If a permanent file of the same name already exists at the destination, the system removes that file when the new file is locked.
Tape and CD-ROM Destinations
For tape and CD-ROM destinations, the ONTO clause works like an AS clause. Library maintenance always writes a new file on the tape or CD-ROM.
|
When you use the ONTO clause, the integrity of the copy is not assured. If library maintenance terminates while copying data onto an existing disk file, the disk file might be left with some data copied from the source file and some data leftover from the destination file. |
CautionExample
COPY F ONTO OLDF, D/= ONTO OLDDD/= FROM DPMAST(PACK) TO UDDOCS(PACK)
Copies file F from DPMAST family to UDDOCS family. Library maintenance copies the source F contents onto the existing destination file OLDF ON UDDOCS.
All files are copied in directory D/= from DPMAST family to UDDOCS family. For each file, if a file of the same name already exists on UDDOCS family, the source file contents are copied onto the existing destination file.
Restrictions
The WFL compiler returns a syntax error if the ONTO clause is used in a COPY & BACKUP or a COPY & CATALOG statement.
Library maintenance will not copy a file onto an existing disk file if any of the following restrictions are violated:
|
Type of Restriction |
Details |
|---|---|
|
AREAS, AREASIZE, FILESTRUCTURE |
Values for the source and destination file must match. |
|
EOFBITS, EOFSEGMENT |
Values for the source and destination file must match if the destination file is crunched. |
|
Areas allocated |
Any allocated area of either the source file or the destination file must also be allocated in the other. |
|
Destination file usage |
Cannot be in use by any program. |
|
Destination file characteristics |
Cannot be
|
Attribute Lists
<source volume attribute list>
┌◄────────────────────────── , ─────────────────────────┐
── ( ─┴─┬─/1\─ AUTHMODE ── = ─┬─ NONE ──────────────────────┬─┴─ ) ────┤
│ ├─ SSL ───────────────────────┤
│ └─ SSH ───────────────────────┤
├─/1\─ AUTOUNLOAD ── = ─┬─ ON ──────────────────────┤
│ ├─ OFF ─────────────────────┤
│ └─ DONTCARE ────────────────┤
├─/1\─── SSLMODE ── = ─┬─ NONE ─────────────────────┤
│ ├─ IMPLICIT ─────────────────┤
│ ├─ EXPLICIT ─────────────────┤
│ ├─ EXPLICITLOGON ────────────┤
│ └─ EXPLICITCOMMAND ──────────┤
├─/1\─ BLOCKSIZE ── = ──<integer>───────────────────┤
├─/1\─┬─ DOMAINNAME ── = ── " ──<domain name>── " ──┤
│ ├─ HOSTNAME ── = ──<hostname>─────────────────┤
│ └─ IPADDRESS ───── = ── " ──<IP address>── " ─┤
├─/1\─ MYIPADDRESS ── = ─── " ──<IP address>── " ───┤
├─/1\─ FAMILYOWNER ── = ─┬─ "" ─────────────────────┤
│ ├─ * ──────────────────────┤
│ └─<usercode>───────────────┤
├─/1\─┬─────────────┬─┬─ CD ────────────────────────┤
│ ├─ KIND ── = ─┘ ├─ CDROM ─────────────────────┤
│ │ ├─ DISK ──────────────────────┤
│ │ ├─ PACK ──────────────────────┤
│ │ └─ TAPE ──────────────────────┤
│ └─ KIND ── = ── # ──<string primary>──────────┤
├─/1\─ LIBMAINTDIR ─┬───────────────────────────────┤
│ └─ = ──<Boolean Exp>────────────┤
├─/1\─ LOCATECAPABLE ─┬─ ON ────────────────────────┤
│ ├─ OFF ───────────────────────┤
│ └─ DONTCARE ──────────────────┤
├─/1\─ MULTIVOLUME ─┬───────────────────────────────┤
│ └─ = ──<Boolean Exp>────────────┤
├─/1\─ OFFSITE ─┬───────────────────────────────────┤
│ └─ = ──<Boolean Exp>────────────────┤
├─/1\─ SERIALNO ── = ──<serial number list>─────────┤
├─/1\─ UNITNO ── = ──<integer expression>───────────┤
├─/1\─ USERCODE ── = ──<log-on info>────────────────┤
├─/1\─ WINDOWSIZE ── = ──<integer expression>───────┤
└─/1\─ YOURNAME ── = ──<port number>────────────────┘<destination volume attribute list>
┌◄──────────────────────────── , ────────────────────────────┐
── ( ─┴─┬─/1\─ AUTHMODE ── = ─┬─ NONE ───────────────────────────┬─┴─ ) ────┤
│ ├─ SSL ────────────────────────────┤
│ └─ SSH ────────────────────────────┤
├─/1\─ AUTOUNLOAD ── = ─┬─ ON ───────────────────────────┤
│ ├─ OFF ──────────────────────────┤
│ └─ DONTCARE ─────────────────────┤
├─/1\─── SSLMODE ── = ─┬─ NONE ────────────┬─────────────┤
│ ├─ IMPLICIT ────────┤ │
│ ├─ EXPLICIT ────────┤ │
│ ├─ EXPLICITLOGON ───┤ │
│ └─ EXPLICITCOMMAND ─┘ │
├─/1\─ BLOCKSIZE ── = ──<integer>────────────────────────┤
├─/1\─ CDCOPIES ── = ──<integer>─────────────────────────┤
├─/1\─ COMPRESSIONCONTROL ── = ─┬─ USER ─────────────────┤
│ └─ SYSTEM ───────────────┤
├─/1\─ COMPRESSIONREQUESTED ─┬───────────────────────────┤
│ └─ = ──<Boolean expression>─┤
├─/1\─ CYCLE ── = ──<integer expression>─────────────────┤
├─/1\─ DENSITY ── = ─┬─<cd density>──────────────────────┤
│ ├─ BPI1250──────────────────────────┤
│ ├─ BPI11000 ────────────────────────┤
│ ├─ FMTAIT ──────────────────────────┤
│ ├─ FMTAIT2 ─────────────────────────┤
│ ├─ FMTDDS ──────────────────────────┤
│ ├─ FMTDDS2 ─────────────────────────┤
│ ├─ FMTDDS3 ─────────────────────────┤
│ ├─ FMTDDS4 ─────────────────────────┤
│ ├─ FMTDDS5 ─────────────────────────┤
│ ├─ FMTDLT10 ────────────────────────┤
│ ├─ FMTDLT20 ────────────────────────┤
│ ├─ FMTDLT35 ────────────────────────┤
│ ├─ FMTDLT40─────────────────────────┤
│ ├─ FMTDLT160────────────────────────┤
│ ├─ FMTDLT300 ───────────────────────┤
│ ├─ FMTST9840────────────────────────┤
│ ├─ FMTST9840C───────────────────────┤
│ ├─ FMTST9940────────────────────────┤
│ ├─ FMTLTO───────────────────────────┤
│ └─ FMTLTO3 ─────────────────────────┤
├─/1\─┬─ DOMAINNAME ── = ── " ──<domain name>── " ───────┤
│ ├─ HOSTNAME ── = ──<hostname>──────────────────────┤
│ └─ IPADDRESS ───── = ── " ──<IP address>── " ──────┤
├─/1\─ MYIPADDRESS ── = ─── " ──<IP address>── " ────────┤
├─/1\─ ENCRYPT ── = ─────┬─ NO───────────────────────────┤
│ ├─ AES256 ──────────────────────┤
│ ├─ AESGCM ──────────────────────┤
│ └─ TDES─────────────────────────┤
├─/1\─ ENCRYPTVERSION ─ = ─┬─ V1 ────────────────────────┤
│ └─ V2 ────────────────────────┤
├─/1\─ FAMILYINDEX ── = ──<integer expression>───────────┤
├─/1\─ FAMILYOWNER ── = ─┬─ "" ──────────────────────────┤
│ ├─ * ───────────────────────────┤
│ └─<usercode>────────────────────┤
├─/1\─┬─────────────┬─┬─ CD ─────────────────────────────┤
│ ├─ KIND ── = ─┘ ├─ CDROM ──────────────────────────┤
│ │ ├─ DISK ───────────────────────────┤
│ │ ├─ PACK ───────────────────────────┤
│ │ └─ TAPE ───────────────────────────┤
│ └─ KIND ── = ── # ──<string primary>───────────────┤
├─/1\─ LIBMAINTAPPEND ── = ─┬─ NO ───────────────────────┤
│ ├─ TOEND ────────────────────┤
│ └─ TOENDRESTORE ─────────────┤
├─/1\─ LIBMAINTDIR ─┬────────────────────────────────────┤
│ └─ = ──<Boolean expression>──────────┤
├─/1\─ LOCATECAPABLE ── = ─┬─ ON ────────────────────────┤
│ ├─ OFF ───────────────────────┤
│ └─ DONTCARE ──────────────────┤
├─/1\─ LOCKEDFILE ─┬─────────────────────────────────────┤
│ └─ = ──<Boolean expression>───────────┤
├─/1\─ MULTIVOLUME ─┬────────────────────────────────────┤
│ └─ = ──<Boolean Exp>─────────────────┤
├─/1\─ OFFSITE ─┬────────────────────────────────────────┤
│ └─ = ──<Boolean Exp>─────────────────────┤
├─/1\─ PACKETWRITE ─┬────────────────────────────────────┤
│ └─ = ──<Boolean Exp>─────────────────┤
├─/1\─ SAVEFACTOR ── = ──<integer expression>────────────┤
├─/1\─┬─ SCRATCHPOOL ── = ──<scratch pool name>──────────┤
│ └─ SERIALNO ── = ──<serial number list>────────────┤
├─/1\─ SECURITYGUARD ── = ──<file title>─────────────────┤
├─/1\─ SECURITYTYPE ── = ──<file mnemonic primary>───────┤
├─/1\─ SECURITYUSE ── = ──<file mnemonic primary>────────┤
├─/1\─ SENSITIVEDATA ─┬──────────────────────────────────┤
│ └─ = ──<Boolean expression>────────┤
├─/1\─ SINGLEUNIT ─┬─────────────────────────────────────┤
│ └─ = ──<Boolean expression>───────────┤
├─/1\─ UNITNO ── = ──<integer expression>────────────────┤
├─/1\─ USECATALOG ── = ─┬────────────────────────────────┤
│ └─ = ──<Boolean expression>──────┤
├─/1\─ USERCODE ── = ──<log-on info>─────────────────────┤
├─/1\─ VERSION ── = ──<integer expression>───────────────┤
├─/1\─ WINDOWSIZE ── = ──<integer expression>────────────┤
└─/1\─ YOURNAME ── = ──<port number>─────────────────────┘
►─ ) ──────────────────────────────────────────────────────────────────┤ ──<log-on usercode>─┬────────────────────────────────────────────────┬─┤
└─ / ──<log-on password>─┬───────────────────────┤
└─ / ──<log-on account>─┘
──┬───────────────────────────────┬────────────────────────────────────┤ ├─ <name constant> ─────────────┤ ├─ <interchange name constant> ─┤ ├─ # ── <string parameter> ─────┤ ├─ " ── " ──────────────────────┤ └─ ' ── ' ──────────────────────┘
──┬─<integer constant>────┬────────────────────────────────────────────┤ └─ # ──<string primary>─┘
You can use the # <string primary> syntax to dynamically specify a port number. The <string primary> must evaluate to an integer.
Explanation
When you use the COPY statement,you can indicate certain file attributes for files being copied and certain file attributes for each source volume or destination volume. For more specific information on an attribute, refer to the File Attributes Programming Reference Manual.
You can specify the following file attributes for either the source volume attribute list or the destination volume attribute list:
|
|
|
AUTHMODE
You can use the AUTHMODE attribute in FTP file transfer requests only. When you use AUTHMODE=SSL, the FTP system uses the Secure Socket Layer encryption algorithm for data transfers. If set to SSL, the SSLMODE attribute defaults to implicit SSL. When you use AUTHMODE=SSH, the FTP system uses the SFTP file transfer protocol over the SSH secure shell protocol. Explicitly setting AUTHMODE overrides any setting in the FTP configuration file or an FTP startup file.
AUTOUNLOAD
Determines whether or not a tape is unloaded when it is released by the system during a reel switch or a file close operation. If the value is ON, the tape is rewound and unloaded. If the value is OFF, the tape is not unloaded. If the value is DONTCARE, or if this value is not specified, the tape behavior is controlled by the setting of the AUTOUNLOAD option of the MODE (Unit Mode) system command. Refer to the System Operations Guide for further information. If a reel is switched during a COPY and COMPARE operation, intermediate reels are not unloaded, regardless of the AUTOUNLOAD value, until the COMPARE phase is finished.
BLOCKSIZE
Specifies the blocksize in words that library maintenance uses when copying files to or from disk or tape volume. Library maintenance automatically rounds the value you specify up to an integer multiple of 900 words. If you specify a value larger than 64800 words, library maintenance uses 64800 instead. If you specify a value greater than 4500 words for a tape destination, then library maintenance automatically uses that blocksize for all disks involved in the operation.
Using the same block size for the source and all the destinations greatly improves the performance of the copy task. Using a larger blocksize increases the amount of data that can be stored on any given tape volume.
-
Certain magnetic tape devices have limits on the maximum length I/O they can process. If you specify a block size larger than the limit for a tape device, library maintenance automatically reduces the blocksize to a valid value for that tape destination.
-
If you do not specify BLOCKSIZE for a tape, library maintenance uses the default value established by the SYSOPS LMBLOCKSIZE system command; or if the default is zero (0), library maintenance uses a small default blocksize that it selects for each tape and disk.
-
Whenever you copy from a tape or CD-ROM, library maintenance will use the BLOCKSIZE that was used when the tape or CD-ROM was created, and ignore the value that is specified.
The following table lists the maximum block sizes for the specified tape drives.
|
Tape Drive Name |
Density |
Maximum Library Maintenance Blocksize |
|---|---|---|
|
CLU9710-DLT4 |
FMTDLT10, FMTDLT20 |
64800 words |
|
CLU9710-DLT7 |
FMTDLT10, FMTDLT20, FMTDLT35 |
64800 words |
|
CLU9710-DLT8 |
FMTDLT20, FMTDLT35, FMTDLT40 |
64800 words |
|
CTS9840, CTS9840B |
FMTST9840 |
42300 words |
|
CTS9840C |
FMTST9840C |
42300 words |
|
CTS9940B |
FMTST9940 |
42300 words |
|
ALP430 |
FMTDDS, FMTDDS2, FMTDDS3 |
10800 words |
|
ALP440 |
FMTDDS, FMTDDS2, FMTDDS3, FMTDDS4 |
10800 words |
|
ALP450 |
FMTDDS3, FMTDDS4, FMTDDS5 |
10800 words 10800 words 64800 words |
|
ALP920 |
FMTAIT, FMTAIT2 |
64800 words |
|
HS8500(C) (8mm) |
11000 |
40500 words |
|
LTO Gen 2 |
FMTLTO |
64800 words |
|
LTO Gen 3 |
FMTLTO3 |
64800 words |
|
MA15OT(U), QIC1000 |
1250 |
10800 words |
|
SDLT320 |
FMTDLT20, FMTDLT35, FMTDLT40, FMTDLT160 |
64800 words |
|
SDLT600 |
FMTDLT160, FMTDLT300 |
64800 words |
|
TAL408012 |
FMTDDS, FMTDDS2, FMTDDS3, FMTDDS4 |
10800 words |
In addition to these limits, any tape connected to the system through a “soft” or “emulated” SCSI DLP has a library maintenance blocksize limit of 10800 words.
Library maintenance automatically limits the blocksize it uses when writing to tape volumes on these tape units so that it will not exceed their blocksize limits.
Library maintenance complies with these limits even if you specify a SYSOPS LMBLOCKSIZE that exceeds these limits. If you are going to be copying files to a tape volume on a unit that does not have limits, but might someday need to be read on a tape unit that has limits, then you should ensure that library maintenance writes the tape with a blocksize that can be read on the target tape unit.
CYCLE
Designates the specific generation of a tape volume family. This file attribute is used in conjunction with the VERSION attribute. The default value is 1.
DOMAINNAME
Indicates the domain name of the remote host where the source or destination volume is located. This can be used for FTP only.
FAMILYOWNER
Indicates the usercode of the owner of a tape volume. If you specify a usercode with the FAMILYOWNER attribute, the usercode becomes the owner. If you do not use the FAMILYOWNER attribute or you specify a null string (" "), the usercode of the copy process is used. If you specify an asterisk (*) with the FAMILYOWNER attribute, the tape volume becomes a nonusercoded volume.
The FAMILYOWNER attribute can be used only if the Security Accountability Facility software is installed, and the TAPECHECK option of the SECOPT system command is set to AUTOMATIC. This attribute is ignored if the SECOPT TAPECHECK attribute is set to NONE.
HOSTNAME
Indicates the host name of the remote host where the source or destination volume is located. The default value is the name of the local host. The HOSTNAME attribute can be specified for the source or destination volume to copy files from or to a remote host; or it can be specified for both source and destination volumes to enable files to be copied from one foreign host to another.
| Note: | Although the local host name is the default value, assigning the local host name to the HOSTNAME attribute might not produce the same results as omitting the attribute. If the assignment is through a constant (HOSTNAME = <local host>), then the assignment is ignored, and the behavior is the same as if the HOSTNAME attribute had not been specified. If the assignment is through a variable (HOSTNAME = #HN where HN is a string variable with a value of "<local host>"), the COPY or ADD statement is handled by DSS, which imposes file transfer restrictions on the request (for example, a CD destination is disallowed). |
IPADDRESS
Indicates the numerical designator that uniquely identifies the remote host where the source or destination volume is located. Can be used for FTP only.
KIND
Describes the peripheral unit associated with the logical file. The default value is TAPE, unless the volume name is DISK, PACK, or CD. If you want to indicate the kind of tape to be used, use the DENSITY attribute.
LIBMAINTDIR
Determines, on destination tapes, whether library maintenance should create a tape directory disk file on the DL LIBMAINTDIR disk family. The LIBMAINTDIR tape directory disk file describes the destination tape and the files copied to it. Library maintenance gives tape directory disk files names of the form LIBMAINTDIR/<tape name>/<date>/<tape serialno>. It also puts them under the usercode that library maintenance is running under, or * if there is no usercode.
Library maintenance stores the following information in these files:
-
Serial numbers of the tapes used
-
Names of the files copied to those tapes
-
Certain other attributes of those files
You receive a report of the information in tape directory disk files by running the SYSTEM/FILEDATA utility program using the following syntax:
<filedata modifier> LIBMAINTDIR = <disk file name>
| Note: | When you specify LIBMAINTDIR = TRUE library maintenance writes the tape with ANSI87 labels. |
On source tapes, if you
-
Specify LIBMAINTDIR = FALSE, library maintenance uses the tape directory on the tape volume itself to determine what files are on the tape.
-
Specify LIBMAINTDIR = TRUE on a tape that was originally created with LIBMAINTDIR = FALSE or without any LIBMAINTDIR specification, library maintenance uses the directory on the tape to determine what files are on the tape and where the files are located on the tape.
-
Specify LIBMAINTDIR = TRUE on a tape that was originally created with LIBMAINTDIR = TRUE, library maintenance uses the LIBMAINTDIR disk file instead of the directory on the tape to determine what files are on the tape and where the files are located on the tape.
-
Do not specify LIBMAINTDIR on a tape that was originally created with LIBMAINTDIR = TRUE, library maintenance attempts to use the LIBMAINTDIR disk file. If the LIBMAINTDIR file is missing or if library maintenance encounters an error while reading records from it, library maintenance reverts to using the directory on the tape to determine what files are on the tape and where the files are on the tape.
Library maintenance may access the tape directory disk file for source tapes that library maintenance originally generated with LIBMAINTDIR = TRUE, if the file is resident on the disk family specified by the DL LIBMAINTDIR system command. If you specify TRUE for a source tape that was originally generated with LIBMAINTDIR = TRUE, the tape directory disk file for the tape must be resident on the disk family specified by the DL LIBMAINTDIR system command, or library maintenance will wait with a “NO FILE” RSVP.
Any attempt to purge a library maintenance tape for which there is a tape directory disk file resident on the DL LIBMAINTDIR disk family requires approval by the operator. Whenever a program or library maintenance overwrites a tape for which there is a resident LIBMAINTDIR tape directory disk file the system removes that file from the disk.
LOCATECAPABLE
Indicates that the file requires a tape drive capable of processing the READ POSITION and LOCATE BLOCK ID tape commands for fast tape access.
If the assigned tape drive is locate capable, then library maintenance automatically takes advantage of this feature to do high-speed spacing in the following situations:
-
COMPARE Option
Library maintenance uses the LOCATE BLOCK ID tape command to backspace to compare the file. If you receive a RECOPY REQUIRED message and respond “OK,” library maintenance uses LOCATE BLOCK ID to backspace to the beginning of that file to recopy the file. If you respond with “OF,” the file is erased.
-
LIBMAINTDIR for Destination Tapes
For a tape that is locate capable, library maintenance stores the BLOCK ID of the start of each file it copies in the LIBMAINTDIR directory.
-
LIBMAINTDIR for Source Tapes
If the original tape was created on a locate capable tape drive, and a LIBMAINTDIR directory was created for the tape, then library maintenance uses the LOCATE BLOCK ID information found in the LIBMAINTDIR directory to rapidly space up to each of the files to be copied.
MYIPADDRESS
Indicates the numerical designator that uniquely identifies the local host where the source or destination volume is located.
OFFSITE
When you specify OFFSITE for a tape destination, library maintenance updates the onsite/offsite status of that tape in the volume library or in the volume directory.
If library maintenance does not successfully copy a file to a destination tape, it purges the tape and does not update the onsite/offsite status for the tape.
If library maintenance successfully copies the files and OFFSITE is TRUE, then, when library maintenance closes the tape, it updates the entry for the tape in the volume library or in the volume directory to indicate that the volume or volumes are “offsite.” If library maintenance successfully copies the files and OFFSITE is false, then, when library maintenance closes the tape, it updates the entry for the tape in the volume library or in the volume directory to indicate that the volume or volumes are “onsite.”
| Note: | Library maintenance performs these actions only when the tape volume is listed in either the Volume Library, at sites that use the OP + CATALOGING option, or the Volume Directory, at sites that use the SECOPT TAPECHECK = AUTOMATIC option. |
SCRATCHPOOL
Indicates the scratch pool that the tape is retrieved from when files are copied. The scratch pool name is a 17-character identifier. There is no default value.
SERIALNO
Identifies the specific disk or tape volumes to be used when copying files. To copy a few specific files from a multi-reel library maintenance tape set, you can use this attribute to skip directly to the reel holding the file or files you need. If you know which reel contains the file you want (or the first reel that contains one of the files you want), use the serial number of that tape volume for the value of the SERIALNO attribute. The SERIALNO attribute does not have a default value. For more information, refer to Serial Number Assignment.
SSLMODE
You can use the SSLMODE attribute in FTP file transfer requests only. The SSLMODE can be set to use an explicit SSL transfer, an implicit SSL transfer, or a normal file transfer. Setting SSLMODE in the volume attribute overrides any setting from the FTP configuration file. Explicitly setting the AUTHMODE attribute to a value other than SSL overrides the SSLMODE attribute.
UNITNO
Designates the assigned hardware unit number of the tape volume to be used when copying files. In the case of a multi-volume tape set, UNITNO is applied only to the first volume.
USERCODE
Passes log-on information, which consists of a usercode, password, and charge account, to the remote host specified with the HOSTNAME attribute. The default value is a null string (" "). The log-on information has a maximum length of 255 characters, which include all quotation marks ("), single quotation marks or apostrophes ('), and slashes (/). The USERCODE attribute is ignored if the HOSTNAME attribute is not specified, if Host Services File Transfer is used, or if NFT is used.
| Note: | if the log-on information includes a password, the password and delimiting slash are erased from the job summary. If a charge account is included, it is retained. |
YOURUSERCODE is an acceptable synonym for USERCODE.
WINDOWSIZE
Indicates the maximum amount of data, in octets, that can be outstanding between the source and the destination processes involved in an NFT transfer. An octet is a unit of data that is 8 bits in length.
| Note: | The WINDOWSIZE attribute is applicable only if an NFT transfer is executed. For more information, refer to the Distributed Systems Services Operations Guide. |
YOURNAME
Overrides the default value for the control port number. When you copy from a remote system, specify YOURNAME in the <source volume> attributes. When you copy to a remote system, specify YOURNAME in the <destination volume> attributes. YOURNAME must be an integer in the range 1 to 64999.
The following example copies a file to a remote system with an IP address of 1.1.1.1 and assigns a port number of 12345:
COPY [FTP] A_FILE AS 'a.txt' TO DISK (IPADDRESS = "1.1.1.1", YOURNAME = 12345)
| Note: | The control port number used by the Batch Client is determined
in the following order:
|
Examples
The following statements illustrate various aspects of the COPY statement with the AUTOUNLOAD and SCRATCHPOOL file attributes.
The following statement will copy file X as A/B from disk PACK to tape T. Since the value of AUTOUNLOAD file attribute is ON, the tape will be unloaded when the operation is completed.
COPY X AS A/B FROM PACK TO T(KIND=TAPE, AUTOUNLOAD=ON);
The following statement will copy the file X as A/B from disk PACK to tape T in the TEST scratch pool:
COPY X AS A/B FROM PACK TO T(KIND=TAPE, SCRATCHPOOL=TEST);
Additional File Attributes
You can specify the following additional file attributes for the destination volume attribute list:
|
|
-
These file attributes cannot be specified for the source volume attribute list construct.
-
The tape attributes SECURITYGUARD, SECURITYTYPE, and SECURITYUSE only work if the Security Accountability Facility software is installed and the TAPECHECK option of the SECOPT system command is set to AUTOMATIC. If the TAPECHECK option of the SECOPT command is set to NONE, these three attributes are ignored for disk and tape destination volumes.
You can specify how many copies of a CD-R disc are to be burned with the attribute CDCOPIES. The default value of CDCOPIES is 1.
When data is copied to a CD-R disk, it is first copied from the source media to a temporary disk file. The data in the temporary disk file is formatted exactly as it is to appear on the CD-ROM. The temporary disk file is then copied to a CD-R drive. CDCOPIES causes the disk file to be copied to the CD-R drive as many times as you specify, without having to recopy the data from the source media.
COMPRESSIONCONTROL
Determines whether data compression will occur for a specific tape volume. This attribute must be selected before a tape volume is assigned.
When the value USER is selected, the value of the attribute COMPRESSIONREQUESTED will determine whether compression will occur. When the value SYSTEM is selected, compression will occur based upon the value of the compression flag in the tape label.
For further information, refer to the File Attributes Programming Reference Manual.
COMPRESSIONREQUESTED
This attribute only has significance for tape files if the COMPRESSIONCONTROL attribute is set to a value of USER.
If COMPRESSIONCONTROL = USER, COMPRESSIONREQUESTED will determine whether compression will occur for a tape file.
Compression will only occur if COMPRESSIONCONTROL = USER and COMPRESSIONREQUESTED = TRUE.
For further information, refer to the File Attributes Programming Reference Manual.
DENSITY
Indicates the recording density of a magnetic tape volume. The default value for output files is the density setting of the tape unit selected.
When the destination volume has kind CD, the DENSITY value identifies the size of the CD image that needs to be created and burnt on to the CD or DVD media. Refer to the section on DENSITY in the File Attributes Programming Reference Manual for the allowable values.
ENCRYPT
Specifies that library maintenance encrypt the data it writes to the specified destination CD or tape. The following three encryption algorithms are provided:
-
TDES
-
AES256
-
AESGCM
To use AESGCM, Media Encryption Version 2 is required.
| Note: | You cannot specify ENCRYPT for disk destinations. |
If you specify LIBMAINTAPPEND, then library maintenance ignores the ENCRYPT setting and instead uses the original ENCRYPT value for that set of tapes.
The LOADER cannot read encrypted library maintenance tapes.
You cannot specify ENCRYPT for a source CD or tape. Library maintenance automatically decrypts data when reading from an encrypted CD or tape, so you can use a simple COPY statement to copy files from an encrypted CD or tape:
COPY ... files ... FROM <tape name>;
ENCRYPTVERSION
Specifies the Media Encryption Version to be used. This overrides the value of the SYSOPS LMDEFENCRYPT version.
-
V1
-
V2
FAMILYINDEX
Designates a specific physical volume within a disk family. If you do not specify the FAMILYINDEX attribute, the FAMILYINDEX value of each source file is used (if that file has had explicit values specified for FAMILYINDEX). By specifying this attribute, you can alter or erase the FAMILYINDEX attribute of the new copies. If you specify a value of 0 or an integer expression that equals 0 for the FAMILYINDEX attribute, the disk areas will be allocated in the normal rotational order of the system.
LIBMAINTAPPEND
You can use this attribute to add files to the tape volume originally created when the LIBMAINTDIR = TRUE file attribute is set.
-
Library maintenance does not update the tape directories on any reels already copied with the file names of the files being added. Library maintenance only updates the LIBMAINTDIR tape directory disk files with the names of the new files.
-
The message BACKUP START ON: data and time appears in the PD display for files that have archive backups. This message refers to the time of the original task that started the tape. It does not refer to the start time of the task with LIBMAINTAPPEND = TOEND specified.
LIBMAINTAPPEND = NO
If you specify LIBMAINTAPPEND = NO, or do not specify LIBMAINTAPPEND, the copy procedure copies to a new tape.
LIBMAINTAPPEND = TOEND
If you specify LIBMAINTAPPEND = TOEND, then library maintenance searches for an existing library maintenance tape with the name and serial number that you specify.
When using LIBMAINTAPPEND, if you specify a SERIALNO list, then the serial numbers in the list are used as follows:
The first serial number indicates to library maintenance the tape set to which files are appended. You must do one of the following:
-
Specify a serial number of one of the tape volumes that is already in the tape set. The best serial number to choose is that of the last tape volume added to the set. You can also specify the serial number of the original tape volume created with LIBMAINTDIR = TRUE, or the serial number of any other tape in the set.
-
Omit the first serial number.
Library maintenance uses any additional serial numbers you specify to add new tape volumes to the set, as required. Ensure that these serial numbers do not match the serial numbers of existing tape volumes in the set. If there is a conflict in serial numbers, then library maintenance automatically deletes the conflicting serial numbers from the SERIALNO list.
The tape you specify must be a tape created with the LIBMAINTDIR = TRUE specification. Library maintenance opens the LIBMAINTDIR disk file with the EXCLUSIVE file attribute TRUE. This prevents other archive, library maintenance, and FILEDATA processes from using that LIBMAINTDIR disk file while library maintenance is updating it. Library maintenance checks the LIBMAINTDIR tape directory disk file for that tape to determine the serial number of the last tape in that set of tapes. (Even if the tape contains no tape directory, it does contain a pointer to the LIBMAINTDIR file on disk, which is used to find the location of the end of the last file on the final tape.)
If necessary, library maintenance searches for that tape. Then library maintenance skips to the end of the last file copied to that tape and copies the files that you specified. The copy procedure expands the LIBMAINTDIR tape directory disk file for the tape with the names and status of all files copied to the LIBMAINTDIR file.
You cannot use the LIBMAINTAPPEND = TOEND attribute for a library maintenance tape if the most recent library maintenance that copied files to the tape terminated because of an error. If you try to use LIBMAINTAPPEND = TOEND for such a tape library, library maintenance issues the following error message and does not add any files to that tape:
MT<unit number> LOCATION OF THE END OF THE LAST FILE ON THE TAPE NOT KNOWN
If an error occurs that stops the copy to the tape (for example, if the operator issues a <mix number> DS command to terminate the append task), then all the files successfully copied up to that point are on the tape and are listed in the LIBMAINTDIR file. However, no more files can be appended to the tape. Any attempt to use LIBMAINTAPPEND again to add more files to that tape is rejected with an error message.
The following conditions must be met to use LIBMAINTAPPEND = TOEND:
-
The destination tape must have been created by a COPY or ARCHIVE statement that specifies LIBMAINTDIR = TRUE for that tape.
-
You must specify & VERIFY for the append operation if the & VERIFY option was specified when the tape was originally created.
-
You must not specify & VERIFY for the append operation if the & VERIFY option was not specified when the tape was originally created.
When library maintenance copies files to a tape with LIBMAINTAPPEND = TOEND, it does not add the names of those files to the tape directory for the tape. You cannot use the TDIR system command or the FILEDATA utility TAPEDIR request to view the names of files copied to tape with LIBMAINTAPPEND = TOEND. Instead, use the FILEDATA utility LIBMAINTDIR modifier to view the names of all the files copied to a tape.
If you specify a list of tape serial numbers for the SERIALNO attribute, library maintenance takes special action. Library maintenance uses the first serial number in the list to locate any existing tapes in the set of tapes to which the files are to be added or appended. Library maintenance then reads the LIBMAINTDIR file for that tape to determine the serial number of the last tape volume in the set. Library maintenance immediately opens that tape, if necessary, and then uses the other serial numbers you supplied when it reaches the end of that tape.
Example
The original tapes have the serial number 111111, 222222, and 333333, and the following COPY statement is specified:
COPY . . . TO <tape name> (LIBMAINTAPPEND = TOEND,
SERIALNO = (222222, "AAAAAA"));The preceding COPY statement is processed as follows:
-
The tape with serial number 222222 opens and the LIBMAINTDIR file is read. It is determined that the tape 333333 is the last tape in the set.
-
Tape 222222 closes.
-
Tape 333333 opens.
-
Library maintenance moves to the end of the last file on tape 333333.
-
Library maintenance appends three new files to the end of tape 333333.
-
If tape 333333 fills before the copy operation completes, tape AAAAAA opens and the additional data is appended to tape AAAAAA.
LIBMAINTAPPEND = TOENDRESTORE
This case works similarly to the LIBMAINTAPPEND = TOEND case except when an error occurs while copying to the tape. If an error occurs that stops the copy to the tape, then the system restores the LIBMAINTDIR file to where it was at the start of the append request. This means none of the files were appended to the tape. However, you can retry the append request.
LIBMAINTDIR
Determines whether library maintenance should create a tape directory disk file on the DL LIBMAINTDIR disk family. The DL LIBMAINTDIR disk family describes the destination tape and the files copied to it. Library maintenance gives these files names of the form, LIBMAINTDIR/<tape name>/<date>/<tape serialno>. It also puts them under the usercode that library maintenance is running under, or * if there is no usercode.
Library maintenance stores the following information in these files:
-
Serial numbers of the tapes used
-
Names of the files copied to those tapes
-
Certain other attributes of those files
You get a report of the information in tape directory disk files with the SYSTEM/FILEDATA utility program.
If the HOSTNAME volume attribute is also specified for the destination volume of the COPY or ADD statement, the LIBMAINTDIR file is created on the host with the destination tape.
LOCKEDFILE
When used in the COPY statement, this file attribute can be set for files copied to tape only. It has no effect on disk files. If this file attribute is set to TRUE for a file, the entire content of the specified destination library tape has locked file protection, and cannot be purged without operator confirmation.
MULTIVOLUME
Causes a multivolume set of CD-ROMs to be written when the data to be copied overflows a single CD-ROM. (If MULTIVOLUME is FALSE when a data overflow occurs, the copy is terminated with an error.)
When a multivolume set is written, data for a given CD-ROM is written to a temporary disk file, the CD-ROM is burned, and the temporary disk file is removed, all before the data for the next CD-ROM is written to a temporary disk file. In this way, the system ascertains whether storage capacity equal to or less than CD-ROM is needed.
In a multivolume copy, the system splits files across CD-ROM boundaries. This capability makes it possible to copy to a set of CD-ROMs files that are much larger than the capacity of a single CD-ROM.
Each CD-ROM in a multivolume set has a complete library maintenance directory listing all files on the entire set. As a result, you can use the TDIR system command on any of the CD-ROMs to list all files on the set.
The directory of a given CD-ROM (volume N) of a multivolume set contains the correct locations for the file data of all files located on previous CD-ROMs in the set (volumes 1 thru N). However, the directory records the location of all subsequent files as volume N+1. For example, if volume 1 of a multivolume set is mounted and you enter a COPY command specifying a file that happens to be on volume 3, the system asks for volume 2. If volume 2 is then mounted, the system asks for volume 3. If volume 3 is mounted, the COPY is then carried out.
Packet write recording is used to back up and restore files and is selected by specifying the PACKETWRITE attribute. When set to TRUE, packet write recording is used when the CD-ROM is written. PACKETWRITE causes the data to be written to the CD-ROM in relatively small packets.
The MCP enables the buffer underrun prevention feature on CD-RW drives that support it. With this feature enabled, these drives resume writing after a buffer empty condition. Thus, buffer underrun does not occur in track-at-once mode, and there is no need to use the packet mode.
Packet write recording has the following advantages and disadvantages compared with track-at-once:
|
Advantages |
Disadvantages |
|---|---|
|
The risk of buffer underrun is eliminated. |
The resulting disc can be read only in CD-R drives. |
|
Less save memory is used for output buffers—130,390 words of output buffers are used for packet write versus 651,950 words for track-at-once. |
The resulting disc cannot be used as a master to be sent to a CD-ROM factory for replication. Track‑at-once output must be used for this purpose. |
|
The burn runs at normal priority. |
The capacity of the disc is reduced by 3.6% and throughput is reduced when writing to the disk. |
When PACKETWRITE is FALSE (the default), track-at-once recording is used. Track‑at‑once causes the data to be written to the CD-ROM an entire track at a time. Track-at-once is the default recording mode and is normally used to create CD-ROMs to be read in CD-ROM drives or to create master CD-ROMs for replication.
However, this mode carries a potential risk of “buffer underrun.” Buffer underrun occurs when CD-ROM drive buffers become empty in the middle of a track, subsequently ruining the disc. To reduce this risk, track-at-once recording uses ten output buffers of 391,168 bytes and permits the implementation to run at MCP priority while writing to the CD-ROM drive.
The following events cause buffer underrun:
-
Memory dump
-
Path failure or path reconfiguration anywhere on the paths to the CD-ROM drive or the CD-ROM image disk file
-
Heavy contention for the disk drives containing the CD-ROM image disk file
-
Very long stack searches
Due to the limitations of packet write, it is currently used only to backup and restore files.
SAVEFACTOR
Indicates the expiration date of a tape volume in terms of the number of days past the creation date. The default value when a COPY statement creates a tape is 30 days. (When a library maintenance tape expires, the system does not automatically mark the tape as a scratch tape. The system uses the SAVEFACTOR value of the library maintenance tapes for reporting purposes such as in the reports generated by the LISTVOLUME utility program.)
SECURITYGUARD
Identifies the guard file to be invoked for the tape volume if the SECURITYTYPE attribute is assigned GUARDED or CONTROLLED. The default value is a null string (" " ). For more information about guard files, refer to the Security Features Guide.
SECURITYTYPE
Specifies how a usercode, other than that of the owner of a file can access a tape volume. The SECURITYTYPE attribute can have a value of PRIVATE (default), PUBLIC, GUARDED, or CONTROLLED. PRIVATE tape volumes can be accessed or overwritten only by their owners and privileged users. PUBLIC tape volumes can be accessed by tasks with any usercode, as limited by the setting of the SECURITYUSE attribute. The security of GUARDED and CONTROLLED tape volumes is determined by the guard file referenced by the SECURITYGUARD attribute.
SECURITYUSE
Specifies how a tape volume that is to be protected by the SECURITYTYPE attribute can be accessed by nonprivileged users using nonprivileged programs. This attribute can have a value of IO (default), IN, or OUT.
When a PUBLIC tape volume is accessed by a task with a usercode that differs from the FAMILYOWNER attribute value, the SECURITYUSE attribute can be used for the following actions based on its value:
-
A value of IO permits reading, writing, overwriting, and purging.
-
A value of IN permits reading but not writing, overwriting, or purging.
-
A value of OUT permits writing, overwriting, or purging, but not reading.
SENSITIVEDATA
When the file is removed, causes the disk or pack areas assigned for a file to be overwritten with an arbitrary pattern before the disk space is returned to the system for reallocation.
SINGLEUNIT
Indicates whether areas for a disk file are to be allocated from a single family member. The default value is FALSE.
USECATALOG
If true, indicates that a tape listed in the volume library should be used. Library maintenance uses this attribute at cataloging installations only.
VERSION
Designates the successive iteration of the same generation of a tape volume. This file attribute is used in conjunction with the CYCLE attribute. The default value is 0.
