CPYFRMTAP (Copy from Tape)

CPYFRMTAP Command syntax diagram

 

Purpose

The Copy from Tape (CPYFRMTAP) command copies records from a tape file to an output file or to a printer. The from-file must be a tape file, but the to-file can be a physical file, a DDM file, diskette file, tape file, or program-described printer file. To obtain a formatted printer file of the records using the IBM-supplied printer file QSYSPRT, TOFILE(*PRINT) is specified.

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. If parameters are needed that are not available on the CPYFRMTAP command, the user can either use overrides for the from-file or to-file, or use the CPYF command or a combination of file overrides with the CPYF command. Only a single tape file (sequence number) can be copied with one call of this command.

The to-file must exist when the CPYFRMTAP command is started. This command does not create the to-file, but it does add a member to an existing physical file if the member does not already exist in the to-file.

 

Restrictions

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

  2. Non-labeled tapes cannot be duplicated to 1/4 inch or 8mm cartridge devices.

 

Required Parameters

FROMFILE
Specifies the qualified name of the tape device file that contains the records that are copied.

The name of the tape 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 containing records to be copied.

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

Note: If no library qualifier is given, *LIBL is used to find the file. The device file can be a diskette, tape, or program-described printer file.

*PRINT: The records are copied to the IBM-supplied printer file QSYSPRT, and the file is formatted according to the OUTFMT parameter. The IBM-supplied printer file, QSYSPRT, may not be overridden to a different file name, and the RPLUNPRT(*YES) and CTLCHAR(*NONE) attributes must be specified.

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.

to-file-name: Specify the name of the physical file or device file that receives the copied records.

 

Optional Parameters

FROMSEQNBR
Specifies the sequence number of the tape file that is copied. If the tapes for the from-file have standard labels, the file sequence number is read from the first header label of the data file. When bypass label processing has been specified for the from-file (that is, FROMREELS(*BLP) has been specified on this command or on the command used to describe the tape file) or when tapes with standard labels are not being used, the system uses the tape marks and the value specified on this parameter to locate the correct data file that is copied.

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

*NEXT: The next file in the sequence is processed. If the tape is currently in a position that is prior to the first file, the first file on the tape is processed.

sequence-number: Specify the sequence number of the file on the tape that is copied. For a labeled tape file, the label specified in the FROMLABEL parameter must be found at this sequence number. Valid sequence numbers range from 1 through 16777215.

FROMLABEL
Specifies the data file identifier of a file that is copied from the tape. The file identifier specified must be found at the sequence number specified in the FROMSEQNBR parameter.

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

*NONE: The file identifier is not specified. No check is made for the file identifier in the labels file specified by the FROMSEQNBR parameter. Any label identifier is accepted.

data-file-identifier: Specify the name of the file label that is copied from the tape from-file. A label may be up to 17 characters in length.

generic*-data-file-identifier: Specify the generic name of the data file identifier. 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.

TOMBR
Specifies the name of the file member that receives the copied records.

Note: Either *FROMLABEL or *FIRST must be specified for this parameter if the to-file is a printer device file or if *PRINT is specified for the TOFILE parameter. If a member (specified by name or implied by a parameter value of *FROMLABEL) does not exist in a physical to-file, it is added to the to-file by the copy operation.

*FROMLABEL: The file specified by the FROMLABEL and FROMSEQNBR parameters is copied into a corresponding member or label in the to-file.

The name of the from-file tape label identifier is used as the member or label identifier for a physical to-file, diskette to-file, or tape to-file. If the to-file is a diskette or tape file, the from-file label identifier is used without modification.

If the to-file is a database file, the last 10 characters that appear before all consecutive blanks for the from-file label are used for the to-file member name. If the last 10 characters that appear before all consecutive blanks are not valid, then the characters to the right of the last period (.) are used for the to-file member name.

If the from-file is a nonlabeled tape file, then a to-file member or label name is created that corresponds to the data file on the tape from-file in the form of CPYnnnn, where nnnn is the tape sequence number of the data-file. If the to-file is a tape or diskette device file, the label in the device file description or override is used.

*FIRST: The first member in the physical to-file receives the copied records.

to-member-name: Specify the name of the physical file member or the label of a diskette or tape file that receives the records copied from the from-file. If the tape label identifier is longer than 10 characters or contains special characters, it must be specified on a CRTTAPF, CHGTAPF, or OVRTAPF command before starting the CPYFRMTAP command.

FROMDEV
Specifies the name of up to four tape devices or one media library device from which the tape from-file is copied.

*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 copying records from the tape from-file. The order in which the device names are specified is the order in which tapes on the devices are read. Each device name must already be known on the system by a device description.

FROMVOL
Specifies one or more volume identifiers of the tapes used when copying records from the (tape) from-file. These volumes must be placed in the devices in the same order as the identifiers are specified (and in the same order as the device names are specified in the FROMDEV parameter).

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

*NONE: No tape volume identifiers are specified for this file. No volume checking is done beyond verifying that the correct label type volume is placed in the device. The maximum number of reels processed for a *NL, *NS, or *BLP from-file when FROMVOL(*NONE) is specified is determined by the number-of-reels element of the FROMREELS parameter.

volume-identifier: Specify no more than 50 volume identifiers from which the tape file is copied. The identifiers of volumes must be entered in the same order in which they are placed in the devices. Each identifier can have up to 6 alphameric characters. The maximum number of reels processed for an *NL, *NS, or *BLP input file is determined by the number of volume identifiers in the list. For *SL and *BLP, the system compares the identifiers of the volumes against the identifiers in the list, and sends the operator an inquiry message if the wrong volume is placed in the device.

FROMREELS
Specifies the type of labeling used on the tape reels that contain the from-file. The number of reels value specified on this parameter is not a limiting value for tape with standard labels. For standard-label tape, the labels on the tape indicate an end-of-file condition that limits the number of volumes processed. The number of reels information is used only if there is no list of volume identifiers specified and if the from-file is either *NL, *NS or *BLP. When the number of reels value is used, the volume identifiers on the volumes that are placed in the device are ignored if the from-file resides on labeled tapes. In that case, the order in which the reels are placed in the device must be checked by the operator.

Element 1: Label Type

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

*SL: Each tape volume from which records are copied has standard labels.

*NL: The tape volumes, from which records are copied, have no labels. Tape marks are used to indicate the end of each data file on the tape.

*NS: Each tape volume from which records are copied has nonstandard labels. Any file label information contained on the tape is ignored; instead, tape marks are used to determine the start and end of a data file. Only a single data file can exist on a nonstandard tape reel (volume).

*BLP: Standard label processing is bypassed when copying the from-file volumes. Although each reel is checked for a standard label, all other volume label information and file labels on the tape are ignored. Only the tape marks are used when the tape volumes are being copied. Bypass label processing can be used if the names of the volumes are incorrect, or if some of the information in the file labels is incorrect.

*LTM: The volumes of the from-file have no labels but have a single leading tape mark before the first file on the tape.

Element 2: Number of Reels

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

number-of-reels: Specify the maximum number of reels used when copying records from the from-file for a *NL, *NS, *BLP, or *LTM tape file when there is no list of volume identifiers specified. If the next reel is not placed in the device when the end of a tape is reached, a message is sent to the operator requesting that the next tape be placed in the device.

FROMRCDLEN
Specifies the length (bytes) of the records contained in the tape from-file. This parameter should be specified in this command or a tape file command for *NS, *NL, *BLP, or *LTM tapes, or for the tapes that do not have HDR2 labels. For *SL tapes, the record length is obtained from the label itself.

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

*CALC: No record length is specified for the from-file. The system calculates a correct record length. When label processing is bypassed or when the tape from-file does not have standard labels, the record length is calculated from the block length; the record block format must not be blocked or spanned.

record-length: Specify a value, ranging from 1 through 32767, for use as the record length when copying records from the tape from-file. The record length must be consistent with the block length and record block format parameter values.

FROMBLKLEN
Specifies the length (bytes) of data blocks transferred from the tape from-file. This parameter should be specified for nonstandard or nonlabeled tapes, for tapes whose label processing has been bypassed, or for tapes that do not have HDR2 labels. For standard labeled tapes, the block length is obtained from the label itself, and this parameter is ignored.

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

*CALC: No block length is specified for the from-file. The system calculates a correct block length. When label processing is bypassed or when the tape from-file does not have standard labels, the block length is calculated from the record length. The record block format must not be blocked or spanned.

block-length: Specify a value, ranging from 18 through 524288 that specifies the block length of each block in the tape from-file. The block length must be consistent with the record length and record block format values.

FROMRCDBLK
Specifies the record block format and blocking attribute of records in the tape from-file. This parameter should be specified for nonstandard or nonlabeled tapes, for tapes whose label processing has been bypassed, or for tapes that do not have HDR2 labels. For standard labeled tapes, the record block format is obtained from the HDR2 label itself and this parameter is ignored.

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

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

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

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

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

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

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

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

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

*VS: The tape from-file has variable-length spanned records.

FROMENDOPT
Specifies the positioning operation that is performed automatically on the last from-file tape volume when the tape device file is closed. For a multi-volume tape from-file, this parameter applies to the last reel (volume) only; all intermediate volumes are copied with *UNLOAD as the positioning attribute.

*TAPF: The value specified in the tape device file or override 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.

MBROPT
Specifies whether the new records replace or are added to the existing records.

Note: This parameter is required for a physical file and ignored for a device to-file.

*NONE: No records are added or replaced in the member. This value is valid only for a copy to a device file.

*ADD: The system adds the new records to the end of the existing records.

*REPLACE: The system clears the existing member and adds the new records.

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.

OUTFMT
Specifies, if TOFILE(*PRINT) is specified, whether the copied records are printed in character or hexadecimal format.

*CHAR: Records are printed in character format only.

*HEX: Records are printed in both character format and hexadecimal format.

Examples for CPYFRMTAP

Example 1: Adding Copied Records to Existing Records 

CPYFRMTAP  FROMFILE(QTAPE)  TOFILE(DEPT/YTDSALES)
  FROMSEQNBR(3)  FROMLABEL(DAILY)  FROMDEV(QTAPE1)
  MBROPT(*ADD)

This command copies records from tape by using the tape device file QTAPE. The data file at sequence number 3 labeled DAILY on device QTAPE1 is copied. The specific attributes of the data file, such as record length and record block format, is determined by the system from the label on the tape. The records are added to the existing records in the member DAILY, which is implied by the parameter default of (TOMBR(*FROMLABEL), in file YTDSALES, which is in library DEPT.

Example 2: Replacing Existing Records 

CPYFRMTAP  FROMFILE(QTAPE)  TOFILE(MYLIB/KEN)
  FROMSEQNBR(2)  FROMDEV(QTAPE1)  FROMREELS(*NL 1)
  FROMRCDLEN(100)  FROMBLKLEN(1000)
  FROMRCDBLK(*FB)  TOMBR(*FIRST)  MBROPT(*REPLACE)

This command copies records from tape by using the tape device file QTAPE. Records in the data file at sequence number 2 of a nonlabeled tape file on tape device QTAPE1, with fixed-length records that are blocked 1000 bytes (or 10 records) to a block, are copied, and replace the existing records in the first member in file KEN, which is in library MYLIB.

Error messages for CPYFRMTAP

*ESCAPE Messages

CPF2816
File &1 in &2 not copied because of error.
CPF2817
Copy command ended because of error.
CPF2818
*FROMMBR value is not allowed on TOMBR parameter.
CPF2858
File attributes not valid for printed output.
CPF2859
Shared open data path not allowed.
CPF2875
Wrong file member or label opened.
CPF2888
Member &3 not added to file because of error.
CPF2909
Error clearing member &3 in file &1 in &2.
CPF2949
Error closing member &3 in file &1 in &2.
CPF2952
Error opening file &1 in library &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.