Copy To Tape (CPYTOTAP)

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

Parameters
Examples
Error messages

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, tape, or inline data file.

Note: For more information on DDM files, see the Distributed database programming topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

This command offers a subset of the parameters available on the Copy File (CPYF) command, along with more specific tape-oriented parameters.

Restrictions:

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

Parameters

Keyword	Description	Choices	Notes
FROMFILE	From file	Qualified object name	Required, Positional 1
	Qualifier 1: From file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
TOFILE	Tape file	Qualified object name	Required, Positional 2
	Qualifier 1: Tape file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
FROMMBR	From member	Generic name, name, FIRST, ALL	Optional
TOSEQNBR	File sequence number	1-16777215, TAPF, END	Optional
TOLABEL	Tape label	Character value, FROMMBR, TAPF, *NONE	Optional
TODEV	Device	Single values: *TAPF Other values (up to 4 repetitions): Name	Optional
TOREELS	Copy to reels	Element list	Optional
TOREELS	Element 1: Label processing type	TAPF, SL, NL, LTM	Optional
TORCDLEN	Record length	Integer, TAPF, CALC, *FROMFILE	Optional
TOENDOPT	End of tape option	TAPF, REWIND, UNLOAD, LEAVE	Optional
TOVOL	Volume identifier	Single values: TAPF, NONE Other values (up to 50 repetitions): Character value	Optional
TOBLKLEN	Block length	1-524288, TAPF, CALC	Optional
TORCDBLK	Record block type	TAPF, F, FB, V, VB, D, DB, VS, VBS, U	Optional
TOEXPDATE	File expiration date	Date, TAPF, PERM	Optional
NBRRCDS	Number of records to copy	Unsigned integer, *END	Optional
COMPACT	Data compaction	TAPF, NO	Optional

From file (FROMFILE)

Specifies the physical file, logical file, DDM file, tape file, or inline data file from which records are copied.

This is a required parameter.

Qualifier 1: From file

name: Specify the name of file to be copied.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

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

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

Tape file (TOFILE)

Specifies the file that receives the copied records.

This is a required parameter.

Qualifier 1: Tape file

name: Specify the name of the tape file to be used for the to-file.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

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

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

From member (FROMMBR)

Specifies the database members or the identifiers of the tape files to be 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 of the specified file is used.

*ALL: All members of a database from-file are copied. FROMMBR(*ALL) is not valid for a tape file or inline data file.
generic-name: Specify the generic name of the set of database members to be copied. A generic name is not valid for a tape file or inline data file.
name: Specify the name of the database file member or the label of a tape data file that is to be copied. If the tape label identifier of the tape file to be copied contains special characters or is greater than ten characters in length, then it must be specified on the CRTTAPF, CHGTAPF, or OVRTAPF command for the device file.

File sequence number (TOSEQNBR)

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

*TAPF

The sequence number specified in the tape file is used.

*END

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

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.

1-16777215

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

Tape label (TOLABEL)

Specifies the label of the data file that receives the copied records. This 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 label value specified in the tape file or on an override is used to identify the label that receives the copied records.
*NONE: No data file identifier is specified. *NONE is not valid if the to-file tape has standard labels.
character-value: Specify the label value that identifies the tape data file to receive the copied records.

Device (TODEV)

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

Single values

*TAPF: The devices specified in the tape file description are used.

Other values (up to 4 repetitions)

name: Specify the names of up to four tape devices, one virtual tape device, 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.

Copy to reels (TOREELS)

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

*TAPF: The value specified in the tape file for the to-file is used.
*SL: The volume used for receiving copied records has standard labels.
*NL: The volume used has no labels. Tape marks are used to indicate the end of each volume and the data file on each volume.
*LTM: The volume used has no labels, but has a leading tape mark before the first data record.

Record length (TORCDLEN)

Specifies (in bytes) the length of the records that are 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.
*TAPF: The record length defined in the tape file is used.
*CALC: The record length from the existing data file label is used.
record-length: Specify the record length ranging from 1 through 32767 bytes that is used for records that are written to the to-file. The record length must be consistent with the block length and the record block format values.

End of tape option (TOENDOPT)

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

*TAPF: The tape is repositioned according to the value specified in the tape file.

*REWIND: The tape is rewound, but not unloaded.

*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.

Volume identifier (TOVOL)

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

Single values

*TAPF: The tape volume identifiers in the tape file are 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.

Other values (up to 50 repetitions)

character-value: 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. A message is sent to the operator if they are not. Each identifier can have up to 6 alphanumeric characters.

Block length (TOBLKLEN)

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

*TAPF: The block length value from the tape 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.
18-524288: Specify the maximum length of the data block written to the tape.

Record block type (TORCDBLK)

Specifies the record format and blocking attributes of records that are 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 record block format value from the tape file is used.
*F: Fixed-length, deblocked records in either EBCDIC or ASCII format are used.
*FB: Fixed-length, blocked records in either EBCDIC or ASCII format are used.
*V: Variable-length, deblocked records in EBCDIC format are used.
*VB: Variable-length, blocked records in EBCDIC format are used.
*D: Variable-length, deblocked records in ASCII type D format are used.
*DB: Variable-length, blocked records in ASCII type D format are used.
*VS: Variable, spanned records are used.
*VBS: Variable, spanned blocked records are used.
*U: Records in an undefined format are used.

File expiration date (TOEXPDATE)

Specifies the expiration date for the data file that is 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 expiration date from the tape file is used for the to-file.
*PERM: The data file being added is protected permanently.
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.

Number of records to copy (NBRRCDS)

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

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

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

Data compaction (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.

*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

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

*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.