Purpose | Argument | Streams | Usage | Examples | Related

               ┌─1──────┐
>>──DUPlicate──┼────────┼────────────────────────────────────────────────────────────><
               ├─copies─┤
               ├─ALL────┤
               ├─*──────┤
               └─ -1 ───┘

Use the DUPLICATE stage to write each input record in addition to the specified number of copies of each input record. DUPLICATE reads records from its primary input stream and writes records to its primary output stream, if it is connected. It does not discard null input records.

• copies
  is an unsigned integer which specifies the additional number of input records to duplicate. A positive number or 0 must be specified for copies, which causes DUPLICATE to write the original record to its output stream. If you do not specify copies, DUPLICATE writes 1 additional copy of each input record.
  
  
• ALL
  *
  specifies an infinite number of copies of the input stream. When you specify DUPLICATE *, the first input record is the only one duplicated because it is the only one ever read.
  
  
• -1
  specifies that all input records are consumed and no output is written to the output stream.
  

1. DUPLICATE does not delay the records.
   
   
2. If the DUPLICATE stage discovers that its primary output stream is not connected, the DUPLICATE stage ends.
   
   
3. DUPLICATE verifies that its secondary input and output streams are not connected and then begins execution.
   

1. The following pipeline reads the input file: input.txt, and creates an output file: output.txt, that contains five additional copies of each input record. (The resulting output file will contain six records: the original record plus five copies.)
   
   

   input.txt (input)
   
   ...|...+....1....+....2....+....3....+....4....
      **** Top of file ****
    1 Name........... Address.................
      **** End of file ****
   

   
   

   'pipe < input.txt | duplicate 5 | > output.txt'
   

   
   

   output.txt (output)
   
   ...|...+....1....+....2....+....3....+....4....
      **** Top of file ****
    1 Name........... Address.................
    2 Name........... Address.................
    3 Name........... Address.................
    4 Name........... Address.................
    5 Name........... Address.................
    6 Name........... Address.................
      **** End of file ****
   

   
   
2. In this example, there are two input records to duplicate and each is duplicated once (the default value for copies).
   
   

   address rxpipe
   
   'pipe literal /Your boat/',
       '| literal /Row/',
       '| duplicate',
       '| console'
   
   exit rc
   

   
   

   console:
   
   Row
   Row
   Your boat
   Your boat
   

   
   Note. that Row is displayed before Your boat, in reverse order of the LITERAL stages in the pipeline.
   
   
   • The rule is that the LITERAL stage writes before copying.
     
     
   • The first LITERAL stage writes a record containing Your boat (the operand) to its primary output stream. The second LITERAL stage writes a record containing its operand Row to its primary output stream, and then copies its primary input stream record containing Your boat to its primary output stream.
     
     
   • The Row record travels through the pipeline before the Your boat record. The DUPLICATE stage reads the Row record, the first in its primary input stream, and writes out that original record, followed by its copy. DUPLICATE does the same with its next, and last primary input stream record, Your boat.

BUFFER