Purpose, Argument, Streams, Usage, Examples, Related

             ┌─PREFace─┐
>>──LITeral──┼─────────┼──┬───────────┬──────────────────────────────────────────────>< 
             └─APPend──┘  ├─string────┤
                          └─charrange─┘

Use the LITERAL stage to write the specified literal string as a record to its primary output stream. If the primary input stream for the LITERAL stage contains any records, LITERAL copies the records from its primary input stream to its primary output stream.

• PREFace
  specifies that LITERAL writes the string or charrange to its primary output stream first, followed by the records from its primary input stream. This is the default.
  
  
• APPend
  specifies that LITERAL writes the records from its primary input stream to its primary output stream first, followed by the string or charrange.
  
  
• string
  is a string of characters that make up a record. If you do not specify the string or charrange argument, LITERAL creates and writes a null record.
  
  
• charrange
  is a character range that makes up a record. For example, specifying A-K for charrange; expands to the literal string ABCDEFGHIJK.

1. LITERAL does not delay the records.
   
   
2. If the LITERAL stage discovers that its primary output stream is not connected, the LITERAL stage ends.
   
   
3. Because LITERAL writes its argument as the first record to its output stream before copying its input stream, records from multiple LITERAL stages are written to the output in reverse order compared to the order of the stages in the pipeline. For example:
   
   

   **** Top of file ****
   Address Rxpipe
   
   'pipe literal /or not to be/',
       '| literal /To be/',
       '| console'
   
   Exit 0
   **** End of file ****
   

   
   

   output:
   
   To be
   or not to be
   

   
   
4. You cannot define a charrange which can also be interpreted as a string, for example.
   
   

   literal a-a
   

   
   The argument a-a will always be interpreted as a literal string with the value '-' (DASH); the string representation takes precedence. LITERAL always tries to interpret its argument firstly as a string and then as a charrange. If the argument does not represent a valid string or charrange definition; LITERAL issues an error message in respect of a charrange definition error, not a string definition error.
   
   
5. LITERAL verifies that its secondary input and output streams are not connected and then begins execution.

1. The following pipeline writes the string '12345' to the console.
   
   

   'pipe literal x3132333435 | console',
   

   
   

   output:
   
   12345
   

   
   
2. The following pipeline writes the string 'ABCDEFGHIJK' to the console.
   
   

   'pipe literal A-K | console',
   

   
   

   output:
   
   ABCDEFGHIJK
   

SPECS, OUT