Purpose, Argument, Streams, Usage, Examples, Related

                         ┌─1───────────────┐
>>──BUFFER──┬─────────┬──┼─────────────────┼─────────────────────────────────────────>< 
            └─REVerse─┘  └─sets─┬────────┬─┘
                                └─string─┘

Use the BUFFER stage without an argument to accumulate all the records (including null records) from its primary input stream, not passing any of the records until end-of-file is reached on the primary input stream. When BUFFER reaches end-of-file on its primary input stream, it writes all the records to its primary output stream.

Use the BUFFER stage with an argument to accumulate input records until a null record is read or end-of-file is reached. BUFFER writes this set of input records sets number of times. If you specify a number greater than one, a null record or a record containing the specified string is written between the copies of the set of input records. Then BUFFER copies the null input record or the specified string to its primary output stream. This process continues until BUFFER reaches end-of-file on its primary input stream and all sets of input records have been written.

• REVerse
  specifies that the accumulated set of records is written to the primary output stream in reverse record order. That is to say; the last record in the buffer is written to the primary output stream first, followed by last-1, last-2 and so on, ending a set of output records with the first record in the buffer.
  
  
• sets
  is an unsigned integer which specifies the number of copies of the set of input records that are to be written to the primary output stream. If you do not specify sets, one copy of the set of records is written to the primary output stream. If you specify sets without specifying string, BUFFER writes a null record between copies of the set of input records.
  
  
• string
  is a string to write between each set of records.

1. If no arguments are specified, BUFFER delays the records until end-of-file is reached on its primary input stream. If one or more arguments are specified, BUFFER delays the records until the end of a set of input records is reached.
   
   
2. The timing of the output records is different if there are null records in the input stream. When used without arguments, BUFFER reads all input records before writing output records. When used with arguments, BUFFER produces its first output record after it reads the first null record.
   
   
3. A BUFFER stage can be used to prevent a pipeline from stalling. See: pipeline stall for an explanation.
   
   
4. BUFFER verifies that its secondary input and output streams are not connected and then begins execution.

1. In the following example; the pipeline creates the file: fruit.txt, that contains three copies of the input stream, in reverse record order, with an interleave string between them.
   
   

   **** Top of file ****
   Address Rxpipe
   
   'pipe console eof /stop/
       '| buffer rev 3 /------/'
       '| > fruit.txt'
   
   Exit 0
   **** End of file ****
   

   
   

   console:
   
   console(0): 'stop' to end.
   console(0): ?
   Apple
   console(0): ?
   Orange
   console(0): ?
   Banana
   console(0): ?
   stop
   

   
   

   fruit.txt
   
   ...|...+....1....+....2....+....3....
   **** Top of file ****
   Banana
   Orange
   Apple
   ------
   Banana
   Orange
   Apple
   ------
   Banana
   Orange
   Apple
   **** End of file ****
   

   
   
2. Buffering records
   
   Employs a BUFFER stage to accumulate all the records in its primary input stream in order to prevent a pipeline stall. Once BUFFER reaches the end-of-file on its primary input stream and the stream has become disconnected; BUFFER begins writing the queued records to its primary output stream.
   
   
3. Reading a file backwards
   
   Uses a BUFFER stage to re-reverse the entire sequence of output records written by the FILEIN stage.

STEM, VARIABLE