COPY command (STREAM or DATASET)

Summary

Privileges

System administrator

Function

Copies the contents of a stream to another stream

Syntax

COPY [STREAM | DATASET] streamnameI TO [STREAM | DATASET] streamnameO [RESTART] [CHECKPOINT | JOURNAL] [COUNT=nnn]

Where:

streamnameI	Specifies the name of the input stream to be copied from. If the keyword STREAM is specified and the entity streamnameI is not defined as a STREAM, the COPY command fails. If the keyword DATASET is specified and the entity streamnameI is not defined as a sequential data set, the COPY command fails. If the keywords STREAM and DATASET are both omitted, the COPY command attempts to locate a STREAM entity for streamnameI, and, failing to do so, then attempts to locate a data set entity for the output stream.
streamnameO	Specifies the name of the output stream to be copied to. If the keyword STREAM is specified, and the entity named streamnameO is not defined as a STREAM, the COPY command fails. If the keyword DATASET is specified, and the entity named streamnameO is not defined as a sequential data set, the COPY command fails. If the keywords STREAM and DATASET are both omitted, the COPY command attempts to locate a STREAM entity for streamnameO, and, failing to do so, then attempts to locate a data set entity for the output stream.
RESTART	Applies only to ring streams with an offload stream that is concatenated. RESTART specifies that copying start from the ring member that was offloading at the time of the system crash. Without RESTART (or if the offload stream was not originally defined as a concatenated stream), COPY copies the entire concatenated stream from its beginning and then adds any information not previously offloaded from the ring stream. Note: Do not use RESTART if the system crash occurs when offloading is active. In this situation, RESTART is likely to duplicate some of your records. If offloading was active at the time of the system crash, RESTART starts the copying process from a point prior to the crash: from the beginning of the ring member that was offloading at the time of the crash. Records from that ring member that were successfully offloaded to the concatenated stream before the crash are also copied to your output stream (streamnameO). If the offload process was idle at the time of the system crash or when the ring stream was closed, the RESTART copying process begins from the idle point and not from an earlier point. No ring stream records are duplicated. Records offloaded before the crash or ring closing are in the concatenated stream; any remaining records are copied to streamnameO.
CHECKPOINT or JOURNAL	Specifies the use of data set formatting to improve the performance of the copy process. This option detects the proper end-of-file after an abnormal termination in the creation of the input stream. Specify the CHECKPOINT option if the stream being copied contains checkpoint records. Specify the JOURNAL option if the stream being copied contains journal records. If the option is omitted, no data set formatting of the input is performed. A GDG stream, if CHKPOINT or CCAJRNL, can also be used as input to the COPY STREAM command. The following DEFINE commands and COPY command will copy a journal GDG stream. JRNLIN could have been a CCAJRNL or CCARF GDG stream in an Online or recovery run. //JRNLOUT DD DSN=complete.online.journal,DISP=SHR DEFINE STREAM JRNLIN WITH SCOPE=SYSTEM GDG=JRN1 CONTROL=JCTL DEFINE DATASET JRN1 WITH SCOPE=SYSTEM OLD SEQUENTIAL - DSN=your.CCAJRNL DEFINE DATASET JCTL WITH SCOPE=SYSTEM OLD SEQUENTIAL - DSN=your.CCAJRNL.CTL.M204 COPY STREAM JRNLIN TO JRNLOUT JOURNAL
COUNT	Specifies the maximum number of blocks to be copied from the input stream or data set to the output stream or data set. If this option is omitted, all of the blocks in the input stream or data set are copied.

Example

COPY DATASET MEMBERA TO DATASET MEMBERB CHECKPOINT COUNT=50 COPY STREAM AAA TO STREAM BBB CHECKPOINT

Usage notes

The COPY command allows the system manager to copy the contents of a stream to another stream. The input and output streams can be any of the following stream configurations:

• Concatenated
• Ring
• Parallel

You can specify whether the stream being copied is a checkpoint stream or a journal stream. With either of these stream types, you can validate the input records by using an appropriate routine to detect logical I/O errors. Run this process as a batch task.

If the stream was originally defined as a ring with an offload stream that was concatenated, COPY is useful for completing offload processes that either:

• Were interrupted by system failures
• Had the CLOSE=NOAUTO parameter setting specified in the DEFINE STREAM command

In these cases, instead of copying from the beginning of the offloaded concatenated stream, you can start the copying from the oldest ring stream member with records not offloaded. For a discussion of this option, see the RESTART command.

Completion of offload processes is necessary if the stream is going to be used as input to the MERGEJ utility. The definition of the input stream must be identical to the definition used when the stream was originally created.

The copying process ends when an I/O error occurs on either the input or output stream, or when an end-of-data condition occurs on the input stream.

For more information on sequential I/O processing, refer to Sequential I/O processing|.

Interrupting a COPY STREAM command

The COPY STREAM command recognizes a bump or an urgent message and terminates processing. The following messages are issued:

M204.0303:.USER INTERRUPTED, PROCESS TERMINATED M204.1859:Txxxx BLOCKS HAVE BEEN COPIED TO OUTPUT STREAM/DATASET

• A bump causes a user restart with all messages written to the audit trail.
• A message generated by either the BROADCAST URGENT or WARN commands is also issued to the user following the M204.0303 and M204.1859 messages. BROADCAST URGENT or WARN processing does not restart the user.