COPY command (STREAM or DATASET): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(15 intermediate revisions by 4 users not shown)
Line 4: Line 4:
<dd>System administrator
<dd>System administrator
<dt>Function
<dt>Function
<dd>Copies the contents of a stream to another stream
<dd>Copies the contents of a stream or dataset to another stream or dataset.
</dl>
</dl>
==Syntax==
==Syntax==
<p class="syntax">COPY [STREAM | DATASET] <var class="term">streamnameI</var>
<p class="syntax">COPY [STREAM | DATASET] <span class="term">streamnameI</span>
  TO [STREAM | DATASET] <var class="term">streamnameO</var>
  TO [STREAM | DATASET] <span class="term">streamnameO</span>
  [RESTART] [CHECKPOINT | JOURNAL] [COUNT=<var class="term">nnn</var>]
  [RESTART] [CHECKPOINT | JOURNAL] [COUNT=<span class="term">nnn</span>]
</p>
</p>
   
   
<b>Where:</b>
Where:
<ul>
 
<li>
<table>  
<p><var class="term">streamnameI</var> specifies the name of the input stream to be copied from. If the keyword STREAM is specified and the entity <var class="term">streamnameI</var> is not defined as a STREAM, the COPY command fails. If the keyword DATASET is specified and the entity <var class="term">streamnameI</var> 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 <var class="term">streamnameI</var>, and, failing to do so, then attempts to locate a data set entity for the output stream.   </p>
<tr><th>streamnameI</th>
</li>
<td>Specifies the name of the input stream to be copied from.  
<ul>
<li>
<li>If the keyword <var>STREAM</var> is specified and the entity <var class="term">streamnameI</var> is not [[DEFINE STREAM command|defined as a STREAM]], the <var>COPY</var> command fails. </li>
<p><var class="term">streamnameO</var> specifies the name of the output stream to be copied to. If the keyword STREAM is specified, and the entity named <var class="term">streamnameO</var> is not defined as a STREAM, the COPY command fails. If the keyword DATASET is specified, and the entity named <var class="term">streamnameO</var> 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 <var class="term">streamnameO</var>, and, failing to do so, then attempts to locate a data set entity for the output stream. </p>
 
</li>
<li>If the keyword <var>DATASET</var> is specified and the entity <var class="term">streamnameI</var> is not [[DEFINE DATASET command|defined as a sequential data set]], the <var>COPY</var> command fails. </li>
 
<li>If the keywords <var>STREAM</var> and <var>DATASET</var> are both omitted, the <var>COPY</var> command attempts to locate a <var>STREAM</var> entity for <var class="term">streamnameI</var>, and, failing to do so, then attempts to locate a data set entity for the output stream. </li>
</ul></td></tr>
   
   
<li>
<tr><th>streamnameO</th>
<p><var>RESTART</var> 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.</p>
<td>Specifies the name of the output stream to be copied to.
<p class="note"><b>Note:</b> 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.</p>
<ul>
<p>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 (<var class="term">streamnameO</var>). </p>
<li>If the keyword <var>STREAM</var> is specified, and the entity named <var class="term">streamnameO</var> is not defined as a <var>STREAM</var>, the <var>COPY</var> command fails. </li>
</li>
<li>If the keyword <var>DATASET</var> is specified, and the entity named <var class="term">streamnameO</var> is not defined as a sequential data set, the <var>COPY</var> command fails. </li>
<li>If the keywords <var>STREAM</var> and <var>DATASET</var> are both omitted, the <var>COPY</var> command attempts to locate a <var>STREAM</var> entity for <var class="term">streamnameO</var>, and, failing to do so, then attempts to locate a data set entity for the output stream. </li>
</ul></td></tr>
   
   
<li>
<tr><th><var>RESTART</var> </th>
<p>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 <var class="term">streamnameO</var>. </p>
<td>Applies only to ring streams with an offload stream that is concatenated. <var>RESTART</var> specifies that copying start from the ring member that was offloading at the time of the system crash. Without <var>RESTART</var> (or if the offload stream was not originally defined as a concatenated stream), <var>COPY</var> copies the entire concatenated stream from its beginning and then adds any information not previously offloaded from the ring stream.
</li>
<p class="note"><b>Note:</b> Do not use <var>RESTART</var> if the system crash occurs when offloading is active. In this situation, <var>RESTART</var> is likely to duplicate some of your records.</p>
<ul>
<li>If offloading was active at the time of the system crash, <var>RESTART</var> 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 (<var class="term">streamnameO</var>). </li>
<li>If the offload process was idle at the time of the system crash or when the ring stream was closed, the <var>RESTART</var> 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 <var class="term">streamnameO</var>. </li>
</ul></td></tr>
   
   
<li>
<tr><th><var>CHECKPOINT</var> or <var>JOURNAL</var> </th>
<p><var>CHECKPOINT</var> or <var>JOURNAL</var> 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. It is used as follows: </p>
<td>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.
<ul>  
<ul>  
<li>
<li>Specify the <var>CHECKPOINT</var> option if the stream being copied contains [[Checkpoints:_Storing_before-images_of_changed_pages|checkpoint]] records.</li>  
<p>Specify the CHECKPOINT option if the stream being copied contains checkpoint records.</p>
<li>Specify the <var>JOURNAL</var> option if the stream being copied contains [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#Using_Model_204_journal_files|journal records]]. </li>
</li>
</ul>
<p>
<li>
If the option is omitted, no data set formatting of the input is performed.</p>
<p>Specify the JOURNAL option if the stream being copied contains journal records. </p>
<p>
</li>
A [[Configuring_checkpoint_and_journal_data_streams#Perpetual_journaling_for_z.2FOS|GDG stream]] , if <var>CHKPOINT</var> or <var>CCAJRNL</var>, can also be used as input to the <var>COPY STREAM</var> command. The following <var>DEFINE</var> commands and <var>COPY</var> command will copy a journal GDG stream. <code>JRNLIN</code> could have been a <var>CCAJRNL</var> or <var>CCARF</var> GDG stream in an Online or recovery run.</p>
</ul>
<p>If the option is omitted, no data set formatting of the input is performed.</p>
<p>A GDG stream, CHKPOINT or CCAJRNL, may also be used as input to the COPY STREAM command. The following DEFINE commands and COPY command will copy a journal GDG stream. JRNLIN may have been a CCAJRNL or CCARF GDG stream in an Online or recovery run.</p>
<p class="code">//JRNLOUT  DD  DSN=complete.online.journal,DISP=SHR
<p class="code">//JRNLOUT  DD  DSN=complete.online.journal,DISP=SHR
DEFINE STREAM JRNLIN WITH SCOPE=SYSTEM GDG=JRN1 -
DEFINE STREAM JRNLIN WITH SCOPE=SYSTEM GDG=JRN1 CONTROL=JCTL
      CONTROL=JCTL
DEFINE DATASET JRN1 WITH SCOPE=SYSTEM OLD SEQUENTIAL -
DEFINE DATASET JRN1 WITH SCOPE=SYSTEM OLD SEQUENTIAL -
       DSN=your.CCAJRNL
       DSN=your.CCAJRNL
DEFINE DATASET JCTL WITH SCOPE=SYSTEM OLD SEQUENTIAL -
DEFINE DATASET JCTL WITH SCOPE=SYSTEM OLD SEQUENTIAL -
       DSN=your.CCAJRNL.CTL.M204
       DSN=your.CCAJRNL.CTL.M204
COPY STREAM JRNLIN TO JRNLOUT JOURNAL
COPY STREAM JRNLIN TO JRNLOUT JOURNAL </p>
</p>
</td></tr>
</li>
   
   
<li>
<tr><th><var>COUNT</var> </th>
<p><var>COUNT</var> 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.</p>
<td>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.</td></tr>
</li>
</table>
</ul>


==Example==
==Example==
<p class="code">COPY DATASET MEMBERA TO DATASET MEMBERB -
<p class="code">COPY DATASET MEMBERA TO DATASET MEMBERB CHECKPOINT COUNT=50  
CHECKPOINT COUNT=50
 
COPY STREAM AAA TO STREAM BBB CHECKPOINT
COPY STREAM AAA TO STREAM BBB CHECKPOINT
</p>
</p>
==Usage notes==
==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:  
The <var>COPY</var> 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:  
<ul>  
<ul>  
<li>
<li>[[Configuring_checkpoint_and_journal_data_streams#Concatenated_stream_configuration|Concatenated]]</li>
<p>Concatenated</p>
</li>
   
   
<li>
<li>[[Configuring_checkpoint_and_journal_data_streams#Ring_stream_configuration|Ring]]</li>
<p>Ring</p>
</li>
   
   
<li>
<li>[[Configuring_checkpoint_and_journal_data_streams#Parallel_stream_configuration|Parallel]]</li>
<p>Parallel</p>
</ul>
</li>
<p>
</ul>
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.</p>
<p>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.</p>
<p>
<p>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: </p>
If the stream was originally defined as a ring with an offload stream that was concatenated, <var>COPY</var> is useful for completing offload processes that either: </p>
<ul>  
<ul>  
<li>
<li>Were interrupted by system failures </li>
<p>were interrupted by system failures, or </p>
</li>
   
   
<li>
<li>Had the <code>CLOSE=NOAUTO</code> parameter setting specified in the <var>[[DEFINE_STREAM_command|DEFINE STREAM]]</var> command </li>
<p>had the CLOSE=NOAUTO parameter specified in the DEFINE STREAM command. </p>
</ul>
</li>
<p>
</ul>
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 <var>[[RESTART command|RESTART]]</var> command. </p>
<p>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]]. </p>
<p>
<p>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.</p>
Completion of offload processes is necessary if the stream is going to be used as input to the [[Media_recovery#MERGEJ_utility|MERGEJ]] utility. The definition of the input stream must be identical to the definition used when the stream was originally created.</p>
<p>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.</p>
<p>
<p>For more information on sequential I/O processing, refer to [[DEFINE STREAM command]] and [[OFFLOAD command]] and to the <var class="book">Rocket Model&nbsp;204 System Manager's Guide</var>.</p>
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.</p>
<p>
For more information on sequential I/O processing, refer to [[Accessing BSAM and VSAM files#Sequential I/O processing|Sequential I/O processing]]|.</p>
 
====Interrupting a COPY STREAM command====
====Interrupting a COPY STREAM command====
<p>The COPY STREAM command recognizes a bump or an urgent message and terminates processing. The following messages are issued: </p>
<p>
The <var>COPY STREAM</var> command recognizes a <var>[[BUMP_command|bump]]</var> or an urgent message and terminates processing. The following messages are issued: </p>
<p class="code">M204.0303:.USER INTERRUPTED, PROCESS TERMINATED
<p class="code">M204.0303:.USER INTERRUPTED, PROCESS TERMINATED
M204.1859:Txxxx BLOCKS HAVE BEEN COPIED TO OUTPUT STREAM/DATASET
M204.1859:Txxxx BLOCKS HAVE BEEN COPIED TO OUTPUT STREAM/DATASET
</p>
</p>
<ul>  
<ul>  
<li>
<li>A bump causes a user restart with all messages written to the audit trail. </li>
<p>A bump causes a user restart with all messages written to the audit trail. </p>
</li>
   
   
<li>
<li>A message generated by either the <var>[[BROADCAST_command|BROADCAST URGENT]]</var> or <var>WARN</var> commands is also issued to the user following the M204.0303 and M204.1859 messages. <var>BROADCAST URGENT</var> or <var>WARN</var> processing does not restart the user.</li>
<p>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.</p>
</ul>
</li>
 
</ul>
[[Category: System administrator commands]]
[[Category: System administrator commands]]
[[Category:Commands]]
[[Category:Commands]]

Latest revision as of 14:11, 11 February 2019

Summary

Privileges
System administrator
Function
Copies the contents of a stream or dataset to another stream or dataset.

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:

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.