CPYTOTAP (Copy To Tape)

CPYTOTAP Command syntax diagram

 

Purpose

The Copy to Tape (CPYTOTAP) command copies records to a tape file. The to-file must be a tape file. The from-file can be a physical, logical, DDM, diskette, tape, or spooled inline file.

Note:

For more information on DDM files, see the Distributed Data Management topic in the Information Center.

This command offers a subset of the parameters available on the Copy File (CPYF) command, along with more specific tape-oriented parameters. This should eliminate the need for using a separate override command. If parameters that are not available on the CPYTOTAP command are needed, use overrides for the from-file or the to-file, use the CPYF command, or use a combination of file overrides with the CPYF command.

Restriction: A file's open data path (ODP) cannot be shared with any other program in the job (routing step) during the copy operation.

 

Required Parameters

FROMFILE

Specifies the qualified name of the physical, logical, diskette, tape, or spooled inline file from which records are copied.

The name of the from-file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

from-file-name: Specify the file from which records are copied.

TOFILE

Specifies the qualified name of the file that receives the copied records.

The name of the to-file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

tape-file-name: Specify the name of the tape device file that receives the copied records.

 

Optional Parameters

FROMMBR

Specifies, the database file members, diskette data file member identifiers, or a tape file members copied from the from-file. If the from-file is a spooled inline file, *FIRST must be specified for this parameter.

*FIRST: The first member in the database file is copied. If the from-file is a tape or diskette file, the label in the device file description is used.

*ALL: All members in a database diskette file are copied.

from-member-name: Specify the name of the database file member or the label of a tape or diskette data file identifier that is copied. If the tape label identifier of the tape or diskette file that is copied contains special characters or is greater than 10 characters in length, then it must be specified on the CRTTAPF, CHGTAPF, or OVRTAPF command for the device file.

generic*-member-name: Specify the generic name of the member. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. See generic names for additional information.

TOSEQNBR

Specifies the sequence number of the data file that receives the copied records.

*TAPF: The value specified in the tape device file is used.

*END: The system saves the file after the last sequence number on the tape.

For a labeled tape file, the label specified on the TOLABEL parameter must be found at this sequence number. Valid sequence numbers range from 1 through 16777215.

If a new data file is added to the tape to-file, the sequence number must be one higher than the sequence number of the last data file on that volume. No gaps are allowed in the series of sequence numbers. If a sequence number of an existing data file is specified, that file is overwritten, and all following files on the volume are destroyed.

file-sequence-number: Specify the sequence number of the file that is used. Valid values range from 1 through 65535.

TOLABEL

Specifies the label of the data file that receives the copied records. The data file identifier is ignored for a nonlabeled tape.

*FROMMBR: The receiving data file in the to-file has the same label as the member/label copied from the from-file. If a member/label name was specified as a value for the FROMMBR parameter (or implied by (*TAPF)), then a data-file with the same name in the tape to-file receives the copied records. If a generic name or *ALL is specified as a value for the FROMMBR parameter, then this value is not valid.

If the from-file is a nonlabeled tape file, a label identifier is created for the tape to-file in the form of CPYnnnnn, where nnnnn is the tape sequence number of the data file.

*TAPF: The value specified in the tape device file or override is used.

*NONE: No data file identifier is specified. *NONE is not valid if to-file tape has standard labels.

data-file-identifier: Specify the label value (17 characters maximum) that identifies the data file to receive the copied records.

TODEV

Specifies the names of devices that are used to copy records to the tape to-file.

*TAPF: The value specified in the tape device file is used.

device-name: Specify the names of up to four tape devices or one media library device used when writing records to the tape to-file. The order in which the device names are specified is the order in which tapes on the devices are successively written to the tape to-file. Each device must have been defined in a device description (by using the Create Device Description (CRTDEVD) command) before being specified on this command.

TOVOL

Specifies, for tapes with standard labels, one or more volume identifiers of the tapes used when copying records to the tape to-file. The tape volumes must be in the device in the same order as the identifiers are specified. A message is sent to the operator if they are not.

*TAPF: The value specified in the tape device file is used.

*NONE: No tape volume identifiers are specified for this file. No volume checking is done beyond verifying that a volume with the correct label type is on the device.

volume-identifier: Specify up to 50 volume identifiers used to identify the tapes to receive the copied records. The tape volumes must be on the device in the same order as the identifiers are specified and in the same order as the device names are specified on the TODEV parameter. Each identifier can have up to 6 alphanumeric characters.

TOREELS

Specifies the type of labeling used on the tape reels that receive the copied records. The system writes only to standard-label tape or to nonlabeled tapes.

*TAPF: The value specified in the tape device file is used.

*SL: The volume used for receiving copied records has standard labels.

*NL: The volume used for receiving copied records has no labels. Tape marks are used to indicate the end of each volume and the data file on it.

*LTM: The volume used for receiving copied records has no labels, but has a leading tape mark before the first data record.

TORCDLEN

Specifies the length (in bytes) of the records written on the tape to-file. The records in the from-file may be truncated or padded with blanks to conform to the record length specified before they are written to the tape. If an existing data file (with standard labels) is being extended on tape, the record length is obtained from the second header label (HDR2). The record length, block length and record block format must be consistently specified. If a new data file is being added or if it is a nonlabeled file, the record length must be explicitly specified by this parameter or by the RCDLEN parameter in one of the tape device file commands.

*FROMFILE: The record length for the to-file is the same as the record length of the from-file. If the from-file has a variable record length, the maximum record length of the from-file is used as the record length of the to-file.

*CALC: No record length is specified for the tape to-file. The record length from the existing data file label is used if an existing data file is being extended in the to-file.

*TAPF: The value specified in the tape device file is used.

record-length: Specify the record length, ranging from 1 through 32767 bytes, of records that are written to the to-file. The record length must be consistent with the block length and the record block format values.

TOBLKLEN

Specifies the length of data (in bytes) of data blocks transferred to the tape. The block length must be consistent with the record length and record block format values.

*TAPF: The value specified in the tape device file is used.

*CALC: No block length is specified for the tape to-file. The block length from the existing data file label is used if the copied records are being written into a data file that is being extended.

block-length: Specify the maximum length of the data block written to the tape. The minimum block size value is 18 bytes and the maximum size is 524288 bytes.

TORCDBLK

Specifies the record format and blocking attributes of records being copied to the tape to-file. The record block format from an existing data file label is used if an existing data file is being extended as the to-file. The record length, block length, and record block format parameters must be consistently specified.

*TAPF: The value specified in the tape device file is used.

*D: The tape to-file has variable-length, unblocked records in ASCII type D format.

*DB: The tape to-file has variable-length, blocked records in ASCII type D format.

*F: The tape to-file has fixed-length, unblocked records in either EBCDIC or ASCII format.

*FB: The tape to-file has fixed-length, blocked records in either EBCDIC or ASCII format.

*U: The tape to-file has records in an undefined format.

*V: The tape to-file has variable-length, unblocked records in EBCDIC format.

*VB: The tape to-file has variable-length, blocked records in EBCDIC format.

*VBS: The tape to-file has variable, spanned blocked records.

*VS: The tape to-file has variable, spanned records.

TOEXPDATE

Specifies the expiration date for the data file being added to the to-file. The data file expiration date is established for standard label tape files only and is stored in the tape header label immediately preceding the data file that the label describes.

*TAPF: The value specified in the tape device file is used.

*PERM: The data file is permanently protected. An expiration date of 999999 is assigned.

file-expiration-date: Specify the expiration date that is used for the data file. The date must be specified in the format defined by the system values QDATFMT and, if separators are used, QDATSEP.

TOENDOPT

Specifies the positioning operation that is done automatically on the to-file tape volume when the tape device-file is closed. For a multivolume tape to-file, this parameter applies to the last reel only; all intermediate reels are positioned *UNLOAD.

*TAPF: The value specified in the tape device file is used.

*REWIND: The tape is automatically rewound, but not unloaded, after the operation has ended.

*UNLOAD: The tape is automatically rewound and unloaded after the operation ends.

*LEAVE: The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.

NBRRCDS

Specifies the number of records copied to the to-file.

*END: Records are copied until the end-of-file condition is indicated.

number-of-records: Specify the number of records, ranging from 1 to 4294967288, that are copied to the to-file. Fewer records are copied if an end-of-file condition occurs before the specified number of records have been copied.

COMPACT

Specifies whether device data compaction is performed. If the tape device used by the to-file does not support data compaction, this parameter is ignored. The possible values are:

*TAPF: To-file device data compaction is performed only if the device used by the to-file supports data compaction.

*NO: To-file device data compaction is not performed.

Examples for CPYTOTAP

Example 1: Copying the First Member in a Database File to Tape

CPYTOTAP   FROMFILE(MYLIB/MYFILE)  TOFILE(QTAPE)
  TODEV(QTAPE1)   TORCDLEN(*FROMFILE)
  TOEXPDATE(10 15 89)

This command copies the first member in database file MYFILE in library MYLIB to tape. The tape device file QTAPE is used which has attributes of SEQNBR(1) and RCDBLKFMT(*F), which are used as defaults for parameters TOSEQNBR and TORCDBLK. The additional attributes specified on the copy command include the tape device name and the expiration date of the file written on tape. The label name used on tape is the same name as that of the member copied. The record length of the tape file is also the same as the database from-file record length since TORCDLEN (*FROMFILE) was specified.

Example 2: Copying a Member in a Database File to Tape

CPYTOTAP   FROMFILE(MYLIB/MYFILE)  TOFILE(QTAPE)
  FROMMBR(M1)  TOLABEL(BACKUPM1)  TODEV(QTAPE1)
  TORCDLEN(50)  TOBLKLEN(1000)  TORCKBLK(*FB)
  TOENDOPT(*LEAVE)

This command copies member M1 from database file MYFILE in library MYLIB to tape, using tape device file QTAPE. The records are copied to label BACKUPM1 on tape device QTAPE1 and the reel is left at its current position when the copy is completed. The data file written on tape has fixed-length 50-byte records that are blocked 1000 bytes (or 20 records) to a block.

Error messages for CPYTOTAP

*ESCAPE Messages

CPF2816

File &1 in &2 not copied because of error.

CPF2817

Copy command ended because of error.

CPF2859

Shared open data path not allowed.

CPF2864

Not authorized to file &1 in library &2.

CPF2875

Wrong file member or label opened.

CPF2904

Diskette labels not valid for multiple label copy.

CPF2949

Error closing member &3 in file &1 in &2.

CPF2952

Error opening file &1 in library &2.

CPF2968

Position error occurred copying file &1 in &2.

CPF2971

Error reading member &3 in file &1.

CPF2972

Error writing to member &3 in file &1.

CPF9212

Cannot load or unload DDM file &2 in &3.