As indicated in Table 10 and Table 11, you can copy from a physical or logical database file, open query file, diskette file, tape file, or inline data file. The to-file can be a physical database file, diskette file, tape file, program-described printer file, or *PRINT. When you specify TOFILE(*PRINT), the CPYSRCF command uses a different format from the other copy commands. This format shows source information in a more readable format, and for multiple member copies the members are copied and listed in alphabetical order.
If you are copying from a database file and the to-file does not exist, you must specify CRTFILE(*YES) and identify the file name and library name on the TOFILE parameter in order to create the to-file. You cannot copy from a diskette to a diskette unless the to-file is spooled and a diskette spooling writer is not active.
The from-file (not including the CPYFRMQRYF command where the from-file is not opened), to-file, and the QSYSPRT printer file (if TOFILE(*PRINT), PRINT(*COPIED), PRINT(*EXCLD), or PRINT(*ERROR) is specified) are opened with the SHARE(*NO) attribute. Because the copy may not function correctly with a shared file, it will end with an error message if the from-file, to-file, or QSYSPRT printer file is overridden to SHARE(*YES) and the file has already been opened in the job.
If you specify TOFILE(*PRINT), the records are copied to the IBM-supplied printer file QSYSPRT, and the OUTFMT parameter formats the list.
If you do not want a formatted list or if you want to use first-character forms control (CTLCHAR(*FCFC) on the Create Printer File (CRTPRTF) or Override with Printer File (OVRPRTF) command), you should specify a program-described printer file name (such as QSYSPRT) instead of *PRINT on the TOFILE parameter.
When the from-file and to-file are different types (source and data), the following is true. For the CPYFRMQRYF command, the from-file is always treated as a data file:
The access path is the sequence in which records are organized in a database file. There are two types of access paths: keyed sequence and arrival sequence. With the copy function, you can process records in a database file in either arrival sequence or keyed sequence. An arrival sequence copy transfers records in the order in which they physically exist in the from-file. Relative record numbers represent this order. The relative record number is the position where the records physically exist in storage. Because records are always added to the end of the file, the relative record number represents the order in which records arrived in the file.
A keyed sequence copy selects and transfers records by key value from a
keyed physical file. This may result in a different physical order in
the to-file. The to-file will be a reorganized version of the
from-file. The relative record number of a specific record may change
when a file is copied by key value:
| Relative Record Number | Arrival Sequence | Keyed Sequence |
|---|---|---|
| 1 | 1011 | 0016 |
| 2 | 0762 | 0762 |
| 3 | 0810 | 0810 |
| 4 | 3729 | 1011 |
| 5 | 0016 | 3729 |
You can copy a keyed physical file in arrival sequence by specifying the FROMRCD or TORCD parameter on the COPY commands. When you do this, the keyed sequence access path is not used to retrieve the records in key sequence. The records are retrieved in arrival sequence. This is helpful when the physical relative record location in the file is significant and needs to remain the same as it is in the original file. Specifying FROMRCD(1) is a good way to copy all the records in arrival sequence. Copying a physical file in arrival sequence instead of keyed sequence is also faster.
The kind of copy you run is determined by the type of from-file and the method of selecting records to copy. In general, files are copied using their keyed sequence, if they have one, otherwise, their arrival sequence. For more information on the selection methods, refer to Selecting the records to copy.
A copy from a keyed file to a keyed file usually places records at the end
of the to-file in key field order, by the from-file key, regardless of their
physical order in the from-file. But if you select records in the
from-file by relative record number (using the FROMRCD or TORCD parameter),
they are physically placed at the end of the to-file in relative record number
order, regardless of their keyed sequence in the from-file. The
following example shows the result of a COPY command that specifies from
record 3 to record 5:
| FROM-FILE | TO-FILE | |||
|---|---|---|---|---|
| Relative Record Number | Key |
| Relative Record Number | Key |
| 1 | 1011 |
| . | -- |
| 2 | 0762 |
| . | -- |
| 3 | 0810 |
< Arrival < Sequence < Copy | 1401 | 0810 |
| 4 | 3729 | 1402 | 3729 | |
| 5 | 0016 | 1403 | 0016 | |
When the to-file has a keyed sequence, the records appear in correct order in the to-file when using the keyed sequence access path. A copy by relative record number always copies by arrival sequence.
If you run a COPY command from a CL program, the completion message indicating the number of records that are copied is not sent directly to the system operator. You can direct this message to the system operator by resending it ( SNDPGMMSG command) from the CL program, using the following CL program as an example:
PGM DCL &MSGID TYPE(*CHAR) LEN(7) DCL &MSGDTA TYPE(*CHAR) LEN(82) CPYF FROMFILE(LIB1/XXX) TOFILE(LIB2/XXX) + MBROPT(*ADD) RCVMSG MSGID(&MSGID) MSGDTA(&MSGDTA) + MSGTYPE(*COMP) RMV(*NO) SNDPGMMSG MSGID(&MSGID) MSGF(QCPFMSG) + MSGTYPE(*INFO) TOMSGQ(QSYSOPR) + MSGDTA(&MSGDTA) ENDPGM
The copy function sends one of the following completion messages for each from-file member/label successfully copied to the to-file:
The escape message CPF2817 is sent to indicate many different error conditions. Except for the empty from-file member case which is described later, when this message is sent:
The CPF2817 escape message is always preceded by at least one diagnostic message that indicates the specific error condition. The message identifier of the diagnostic message which immediately precedes the CPF2817 escape is used as message replacement data (MSGDTA parameter on the SNDPGMMSG command) for the CPF2817 escape message. This allows you to monitor for specific error cases from the CPF2817 escape message by using the CMPDTA parameter on the MONMSG command.
For example, message CPF2802 is a diagnostic message. It indicates that the from-file cannot be found. You can monitor for just the from-file not found condition as follows:
PGM
/* The replacement text of escape
CPF2817 contains the msg ID
CPF2802 for the 'from-file not
found' condition */
CPYF FROMFILE(NOLIB/NOFILE) TOFILE(D504/KEY) +
FROMMBR(NOMBR) TOMBR(MBR1) MBROPT(*ADD)
MONMSG MSGID(CPF2817) CMPDTA(CPF2802) +
EXEC(SNDPGMMSG TOPGMQ(*EXT) +
MSG('File NOFILE in NOLIB not found'))
ENDPGM
Any error other than from-file not found, including any other error reported with a CPF2817 escape message, causes a check in this program because the MONMSG command applies only to the CPF2817 escape when it has the compare data from message CPF2802.
If you are running the CPYFRMQRYF command, it does not normally close the open query file after completing the copy. However, if you are running the CPYFRMQRYF command from a command entry line, any error messages occurring after the OPNQRYF command is successfully run will close the file unless you specified TYPE(*PERM) on the OPNQRYF command. The system automatically runs a Reclaim Resources (RCLRSC) command if an error message occurs. If the OPNQRYF command specified TYPE(*PERM), the system does not automatically close the file.
The following messages can be sent as diagnostic messages, followed
immediately by a CPF2817 escape message. Some of these messages can
also be sent as other message types (such as an informational or escape
message). When the message is sent as a diagnostic message type, the
message identifier appears in the replacement text of the CPF2817 escape
message. You can monitor the condition by using the CMPDTA parameter on
the
MONMSG
command:
| CPD2807 CPD2808 CPD2809 CPD2810 CPD2811 CPD2812 CPD2825 CPD2968 CPD2969 CPD2970 CPD2971 CPD2972 CPD2973 CPD2974 CPD2975 CPD2976 CPD2979 CPD2980 CPD2981 CPF2801 CPF2802 CPF2803 CPF2804 CPF2805 | CPF2806 CPF2807 CPF2808 CPF2810 CPF2811 CPF2812 CPF2813 CPF2814 CPF2816 CPF2819 CPF2820 CPF2821 CPF2822 CPF2823 CPF2825 CPF2826 CPF2827 CPF2831 CPF2832 CPF2833 CPF2834 CPF2836 CPF2837 CPF2839 | CPF2840 CPF2841 CPF2842 CPF2843 CPF2844 CPF2847 CPF2848 CPF2849 CPF2851 CPF2853 CPF2854 CPF2855 CPF2856 CPF2857 CPF2860 CPF2861 CPF2862 CPF2863 CPF2864 CPF2865 CPF2868 CPF2869 CPF2870 CPF2871 | CPF2872 CPF2873 CPF2874 CPF2877 CPF2878 CPF2879 CPF2881 CPF2883 CPF2884 CPF2890 CPF2891 CPF2893 CPF2960 CPF2962 CPF2963 CPF2965 CPF2969 CPF9807 CPF9808 CPF9820 CPF9830 |
There are some special considerations for copy when the from-file is a physical or logical file and one or more members to be copied are empty. A member is considered empty in the following cases:
Members copied involving record selection (CPYFRMQRYF command or the INCCHAR and INCREL parameters of the CPYF command) that produce no records are not considered empty.
When the to-file is a printer file (including *PRINT), or when the to-file is a physical file and you specified MBROPT(*ADD) or MBROPT(*UPDADD), empty from-file members are copied because no existing data will be destroyed. Each member that is copied is identified by a normal copy completion message. If the to-file is spooled, an empty spooled file is produced for each empty from-file member. If the PRINT parameter on the CPYF command specifies *COPIED, *EXCLD, or *ERROR, the empty members are shown in the lists, and no records are printed.
Except for the CPYFRMQRYF command, an empty from-file member is never copied to a diskette or tape file, or to a physical file when MBROPT(*REPLACE) is specified. Empty from-file members are skipped for these types of to-files, and a CPF2869 message is sent (as either an informational or diagnostic message) to identify each empty member. The empty members are skipped to avoid destroying existing data. When an empty from-file member is skipped, the following considerations apply:
When the copy command specifies a generic name or *ALL for the FROMMBR parameter, each empty from-file member skipped is identified by message CPF2869, sent as an informational message. If all the from-file members are skipped, a CPF2870 diagnostic message is sent after all the CPF2869 informational messages, followed by a CPF2817 escape message.
When the copy command specifies a single member name or FROMMBR(*FIRST), or when there is an override for the from-file that forces a single member to be processed, an empty member that is skipped is identified by the diagnostic message CPF2869. The CPF2869 diagnostic message is followed by a CPF2817 escape message.
In the following example, the from-file and to-file are both database files, and EMPTY1 and EMPTY2 are empty members in the from-file.
PGM
/* No need to monitor for zero records
when MBROPT(*ADD) specified */
CPYF FROMFILE(D504/GEORGE) TOFILE(D504/KEN) +
FROMMBR(EMPTY1) TOMBR(MBR1) MBROPT(*ADD)
CPYF FROMFILE(D504/GEORGE) TOFILE(D504/KEN) +
FROMMBR(EMPTY2) TOMBR(MBR2) MBROPT(*REPLACE)
MONMSG MSGID(CPF2817) CMPDTA(CPF2869) +
EXEC(CLRPFM FILE(D504/KEN) MBR(MBR2))
/* Monitor for zero records and
send a message when all members
to copy are empty */
CPYF FROMFILE(D504/GEORGE) +
TOFILE(D504/NEWFILE) FROMMBR(EMPTY*) +
TOMBR(NEWMBR) MBROPT(*REPLACE)
MONMSG MSGID(CPF2817) CMPDTA(CPF2870) +
EXEC(SNDPGMMSG TOPGMQ(*EXT) +
MSG('All members to copy are empty'))
ENDPGM
For the first CPYF command, MBROPT(*ADD) is specified, so an escape message is not sent to the program because of the empty from-file member. Note that if MBR1 does not exist before the copy, it is added to the to-file (if either the from-file member is empty or contains data).
For the second CPYF command, copy does not clear the to-file member when the from-file member is empty, so the MONMSG command after the second CPYF command starts the CLRPFM command to clear the to-file member when the from-file member is empty.
For the third CPYF command, the CPF2817 escape message has compare data of CPF2870 if all members to be copied are empty because the generic from-file member name, EMPTY*, requests that multiple members be copied.
When your application requires an exact duplicate of the records in the to-file member (if either the from-file is empty or contains data), an alternative solution is to use the Clear Physical File Member (CLRPFM ) command:
CLRPFM FILE(X) MBR(XYZ)
CPYF FROMFILE(Y) TOFILE(X) TOMBR(XYZ) +
MBROPT(*ADD)
Because MBROPT(*ADD) is specified, the CPYF command completes normally even if there is no data in file Y. MBR(XYZ) in file X contains an exact duplicate of the records in the member in file Y.
The Copy from Query File (CPYFRMQRYF ) command provides CCSID conversions for character and DBCS fields. The
Open Query File (OPNQRYF ) command converts all character and DBCS fields to the current job CCSID, except for fields that have a CCSID of 65535 or where *HEX is specified on the MAPFLD parameter. If the current job CCSID is 65535, then no conversions are done by OPNQRYF. The CPYFRMQRYF command may also do conversions to the to-file field CCSIDs, so it is possible that double conversions will be done and data may be lost. To avoid the possibility of doing double conversions, change the job CCSID to 65535 before doing an OPNQRYF if you plan to do a CPYFRMQRYF.
CPYFRMQRYF uses a different query format. It is the same as the open query file format except for the CCSIDs for character and DBCS fields. The CCSIDs in this query format are determined according to the following:
You can find more information on CCSIDs in the National Language Support book.
Using the Copy Source File (CPYSRCF) command automatically converts data in the from-file to the to-file CCSID. If you do not want the character data converted, use the CPYF command with FMTOPT(*NOCHK).
You can copy files that contain null-capable fields by using the CPYF and CPYFRMQRYF commands. The FMTOPT parameter allows mapping of null-capable fields. The INCREL parameter allows selection of records that are based on whether a field is or is not null.
While copying the records to the to-file, the following commands ignore null values in the from-file:
The following conditions or values on the CPYF or CPYFRMQRYF command ignore null values in the from-file while copying the records to the to-file:
Record selection involving null values may still be done, but only the user-specified or default value in the buffer (rather than a null value) is copied to the to-file. Null values cannot be preserved in these instances. Any print listings produced when a copy command is run (including TOFILE(*PRINT), PRINT(*COPIED), PRINT(*EXCLUDE), and PRINT(*ERROR)) also ignore null values.