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

For more information on DDM files, see the Distributed Data Management information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

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

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

Top

---

 

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
	Element 1: Label processing type	*TAPF, *SL, *NL, *LTM
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

Top

 

From file (FROMFILE)

Specifies the name and library of the physical file, logical file, diskette file, or tape file, from which records are copied.

The possible library values are:

*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 job is used to locate the physical file, logical file, diskette file, or tape file. 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 where the physical file, logical file, diskette file, or tape file, is located.

Top

 

Tape file (TOFILE)

Specifies the file that receives the copied records.

The possible library values are:

*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 job is used to locate the tape file. If no library is specified as the current library for the job, QGPL library is used.

library-name

Specify the name of the library where the tape file is located.

Top

 

From member (FROMMBR)

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

*ALL

All members of a database from-file, or all file label identifiers for a diskette from-file are copied. FROMMBR(*ALL) is not valid for a tape file or inline data file.

from-member-name

Specify the name of the database file member or the label of a tape or diskette data file identifier that is being 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 set of database members or diskette labels that are being copied.

Top

 

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.

file-sequence-number

Specify the sequence number of the data file that receives the copied records. Valid sequence numbers range from 1 through 16777215.

Top

 

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.

data-file-identifier

Specify the label value that identifies the data file to receive the copied records.

Top

 

Device (TODEV)

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

*TAPF

The devices specified in the tape file description are used.

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

Top

 

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.

Top

 

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.

Top

 

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.

Top

 

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.

You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase "+ for more", and press the Enter key.

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

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.

Top

 

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.

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.

Top

 

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.

Top

 

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.

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.

Top

 

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.

number-of-records

Specify a record number, ranging from 1 through 4294967288, that identifies the number of records 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.

Top

 

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.

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.

Top

---

 

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.

Top

---

 

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.

Top