CL Command Reference - CPYF
CL Command List > CPYF Reference
Description:
The Copy File (CPYF) command copies all or part of a file from the database or from an external device to the database or to an external device. It can:
. Copy data and source files between database files. Records can be copied from physical or logical files. However, records can be copied only to physical files, not to logical files.
. Copy data and source files from external devices, such as diskette and tape, to the database.
. Copy data and source files from the database to external devices.
. Copy data and source files from external devices to other external devices.
. Copy data and source files from inline data files to the database or to external devices.
Restrictions:
. During the time a CPYF request is run, the file specified for the To file (TOFILE) parameter may be locked (similar to an *EXCL lock with no timeout) so that no access is possible.
. When the CRTFILE(*YES) parameter is specified and the file copied (FROMFILE parameter) has an associated trigger, the file created (TOFILE parameter) does not have the associated trigger. The Add Physical File Trigger (ADDPFTRG) command must be used to add a trigger to the file.
. This command is conditionally threadsafe. In multithreaded jobs, this command is not threadsafe when copying from or to multiple database file members, device files (except SPOOL(*YES) print files), distributed files, or DDM files of type SNA. This command fails for distributed files that use relational databases of type *SNA and DDM files of type *SNA. It is threadsafe only when copying from and to single database file members (local or DDM of type *IP) or SPOOL(*YES) print files.
Examples:
Example 1: Physical File to Physical File
CPYF FROMFILE(PERSONNEL/PAYROLL) TOFILE(TESTPAY/PAYROLL)
MBROPT(*ADD) CRTFILE(*YES) ERRLVL(10)
This command copies all of the records in the physical file named PAYROLL in the PERSONNEL library to the file PAYROLL in the TESTPAY library. If the from-file contains more than one member, only the first member is copied. If TESTPAY/PAYROLL does not exist, it is created before the records are copied and a member with the same name as the from-file is added to TESTPAY/PAYROLL to receive the copied records.
Because MBROPT(*ADD) is specified, the copied records are added to any existing records in the to-file member. Because RCDFMT(*NONE) is assumed, the to-file TESTPAY/PAYROLL must have the same record format as the from-file. If the to-file (TESTPAY/PAYROLL) is created by the copy operation, it will have the same record format and access path as the from-file (PERSONNEL/PAYROLL). If more than ten recoverable errors occur during the copy operation, the operation ends.
If FROMMBR(*ALL) and TOMBR(*FROMMBR) had also been specified, all of the members in the from-file would be copied to corresponding members (having the same names) in the to-file. For each from-member that has no corresponding to-member, a member is added to the to-file and all the records in the from-member are copied to the new member. For each to-member that already exists, only new records are added to the member. No updates are made to existing records on any type of copy operation. If the to-file contains members for which there are no corresponding members in the from-file, the to-file contains more members than the from-file after the copy operation.
If more than ten recoverable errors occur within a member being copied, the copy operation ends at that point, and remaining members are not copied. ERRLVL(*NOMAX) can be specified to tolerate all recoverable errors, so the copy operation does not end no matter how many recoverable errors occur in a particular file member.
Example 2: Physical File to Physical File
CPYF FROMFILE(PERSONNEL/EMP1) TOFILE(PERSONNEL/VACLEFT)
FROMMBR(VAC) MBROPT(*REPLACE)
FROMKEY(1 X¡¯0008872F¡¯) TOKEY(1 X¡¯0810199F¡¯)
INCREL((*IF VAC *GT 5.0)) FMTOPT(*MAP *DROP)
In this example, the to-file (VACLEFT) is an existing physical file, but its record format differs from that of the physical file named EMP1, which is being copied. Both files are in the PERSONNEL library. The from-file contains employee records and has a key (employee number). The records selected in the from-file are those with employee numbers ranging from 008872 through 810199. Only records for employees with more than five days of vacation (VAC) are mapped to the receiving file. Records are selected from member VAC, and they replace existing records in the first member of file VACLEFT.
Because the key for the file is a packed decimal number, the FROMKEY and TOKEY values must be specified as hexadecimal strings, and the leading zeros and hexadecimal sign are required in the value. An alternative way of specifying the same key value range follows:
FROMKEY(*BLDKEY 8872) TOKEY(*BLDKEY 810199)
When *BLDKEY is specified, the copy operation converts each number to the format required for the file key definition. Because only a single value is specified, only one key field is used. The *BLDKEY form of the FROMKEY and TOKEY parameters allows omission of leading zeros and a positive sign value when the key is numeric.
If the key for a file is a composite of more than one key field, the *BLDKEY form is used with a list of values for the FROMKEY and TOKEY parameters. For instance, if the key fields for a file are a sales region (10 characters) and the sales for the last month (7 packed decimal numbers with 2 decimal positions), a complete key is specified in either of the following ways:
FROMKEY(*BLDKEY (GEORGIA 99.50))
- or -
FROMKEY(2 X¡¯C7C5D6D9C7C9C14040400009950F¡¯)
When the *BLDKEY form is used, each character field is padded with blanks, and each numeric field is converted to the actual key format with the value shifted left or right to correctly align the decimal point.
Example 3: Physical Data File to Physical Source File
CPYF FROMFILE(MYLIB/DATAFILE) TOFILE(QIDU/QTXTSRC)
FROMMBR(A1) TOMBR(*FROMMBR)
MBROPT(*REPLACE) FMTOPT(*CVTSRC)
This command copies records from physical file DATAFILE in library MYLIB, which is defined as FILETYPE(*DATA), to physical file QTXTSRC in library QIDU, which is defined as FILETYPE(*SRC). Because the two database files are of different types, FMTOPT(*CVTSRC) must be specified. Records are copied to member A1, which has the same name as the from-file member. Values are assigned to the sequence number source field of the records copied to the source file, starting with 1.00 and incremented by 1.00. If SRCOPT(*SEQNBR) is specified, the SRCSEQ parameter is used to control the sequence numbers that are created. The date source field is always set to zeros.
Example 4: Logical File to Physical File
CPYF FROMFILE(DEPTS/SALES) TOFILE(DEPTS/YTDSALES)
FROMMBR(TOTSALES) TOMBR(MARCH) RCDFMT(AA)
NBRRCDS(5) MBROPT(*REPLACE)
This command copies five records from member TOTSALES of logical file SALES (in library DEPTS) to member MARCH in the physical file YTDSALES (in library DEPTS). If member MARCH does not exist, it is created and added to the to-file automatically by the copy operation. Only records from the logical file SALES in library DEPTS that use record format AA are copied, and they are copied to YTDSALES, which has the same format. After the copy operation, the MARCH member contains only five nondeleted records, because all records in that member are first cleared, then only the data in the first five records (in keyed sequence) in the TOTSALES member are copied to it.
Example 5: Device File to a Physical File
CPYF FROMFILE(QDKT) TOFILE(QGPL/QCLSRC) FROMMBR(PAY*)
TOMBR(*FROMMBR) MBROPT(*REPLACE)
SRCOPT(*SEQNBR) SRCSEQ(1 .25)
This command copies records from the generic set of diskette labels with names that start with the characters PAY. They are copied to like-named members in source file QCLSRC in the QGPL library. Even though the to-file is a source file, a diskette file (QDKT) defined as FILETYPE(*DATA) is used as the from-file, because QDKT is more efficient than a device file defined as FILETYPE(*SRC). For each label copied, the sequence number of the first record is 1.00 and is incremented by .25 for each subsequent record. The source date field is automatically set to zeros.
Example 6: Physical File to the Printer
CPYF FROMFILE(TEMPFILE) TOFILE(*PRINT) FROMMBR(EMP1)
FROMKEY(1 448762) NBRRCDS(20) OUTFMT(*HEX)
This command copies records from member EMP1 in the file named TEMPFILE. The records are employee records. One key field, the employee number, is used to search the record keys. Twenty records, starting with employee number 448762, are copied to the IBM-supplied printer file QSYSPRT and listed in both character and hexadecimal format. The IBM-supplied printer file is indicated by coding TOFILE(*PRINT).
Example 7: Physical File to a Device File
CPYF FROMFILE(PERSONNEL/PAYROLL) TOFILE(DISK1)
FROMMBR(VAC1) INCCHAR(NAME 1 *CT SMITH)
INCREL((*IF VAC *GT 10.5)(*AND HOLIDAYS *EQ 0))
This command copies all employee records of employees whose last name is SMITH and that have accumulated more than ten and a half vacation days, none of which is holidays, from the PAYROLL file in the PERSONNEL library to a diskette. The file member name copied is VAC1. The vacation (VAC) and holiday (HOLIDAYS) fields are defined as packed decimal, but a value is specified in character form on the INCREL parameter. The diskette device file used is DISK1, which contains the label of the file being copied to, and other diskette attributes such as location and volume ID.
Example 8: Physical File to Device Files
CPYF FROMFILE(PERSONNEL/PAYROLL) TOFILE(DISK1)
FROMMBR(*ALL) TOMBR(*FROMMBR)
This command copies all members of file PAYROLL in the PERSONNEL library to data files on diskette (device file DISK1). Each from-file member name must be a valid diskette label identifier; if not, use the RNMM (Rename Member) command to rename the members in the from-file before they are copied.