Purpose, Argument, Streams, Usage, Examples, Related

(1)
>>──┬─CONSole──┬──┬─────────────┬────────────────────────────────────────────────────>< 
    ├─SCReen───┤  └─STOP─string─┘
    └─TERMinal─┘

(2)
STOP ?

Notes:
(1) May be specified only when CONSOLE is the first stage of a pipeline.
(2) Display the CONSOLE prompt and STOP string.

(1)
>>────CONSole──────────────────────┬─────────────────────────┬───────────────────────>< 
                                   └─prefixstr─┬───────────┬─┘
                                             └─suffixstr─┘

Notes:
(1) May be specified only when CONSOLE is not the first stage of a pipeline.

Use the CONSOLE stage to read lines from the keyboard or write lines to the console.

1. When CONSOLE is the first stage of the first pipeline; CONSOLE reads records from the keyboard and writes them to its primary output stream.
   
   CONSOLE stops reading when:
   
   
   • Its primary output stream becomes disconnected.
   • No argument is specified, CONSOLE stops reading when a null line is entered from the keyboard. To enter a null line, press <enter> without typing anything on the command-line.
   • When the input text matches the string specified by the STOP keyword.
     
     
   Only a single active CONSOLE stage (from the moment it is initialised until it completes processing and ends) can read from the keyboard at any one time. You may specify multiple CONSOLE stages that read from the keyboard, including those in a CALLPIPE chain, but only a single active instance can have exclusive access to the keyboard for input. If more than one CONSOLE stage attempts to secure exclusive access to the keyboard for input; then an error is raised and the pipeline ends.
   
   
2. When CONSOLE is not the first stage of a pipeline; CONSOLE reads records from its primary input stream and writes them to the console and to its primary output stream, if it is connected. CONSOLE appends a Line-Feed character to each output record that it writes to the console, primary output stream records are written unchanged.

• STOP
  specifies that CONSOLE is to stop reading from the keyboard when the input text matches string.
  
  
  • string
    is a string that you want CONSOLE to recognise as a signal to stop reading from the keyboard and end the stage. The string is not written to the output stream. Uppercase and lowercase representations the same characters do not match. CONSOLE stops reading from the keyboard if the line read exactly matches the target string you specify.
  
  
• STOP ?
  is a runtime CONSOLE query command that will display the CONSOLE prompt and STOP string. The query command itself is echoed to the console screen but it is not written to the output stream.
  
  
• prefixstring
  is a literal string that will prefix the output record.
  
  
• suffixstring
  is a literal string that will append the output record. The CONSOLE stage only uses these enclosing strings when writing the record to the console, they are not included in the record written to the output stream.
  
  For example, to display a record surrounded by a pair of quotation marks:
  
  

  'pipe literal /A literal string/ | console /"/ /"/'
  
  output:
  
  "A literal string"
  

1. CONSOLE does not delay the records.
   
   
2. When CONSOLE is the first stage of the first pipeline and it discovers that its primary output stream is not connected, the CONSOLE stage ends.
   
   
3. The following example shows how the CONSOLE stage reads interactively from the keyboard; writing each of the input records to the output file: keyboard.txt.
   
   

   **** Top of file ****
   Address Rxpipe
   
   'pipe cons stop /eof/',
       '| xlate',
       '| specs recno 1 1-* nw',
       '| console',
       '| > keyboard.txt'
   
   Exit 0
   **** End of file ****
   

   
   

   console:
   
   CONSOLE(0): 'eof' to stop.
   CONSOLE(0): ?
   one
            1 ONE
   CONSOLE(0): ?
   flew over
            2 FLEW OVER
   CONSOLE(0): ?
   the cuckoos
            3 THE CUCKOO'S
   CONSOLE(0): ?
   nest
            4 NEST
   CONSOLE(0): ?
   eof
   

   
   

   keyboard.txt
   
   ...|...+....1....+....2....+....3....+....4....
      **** Top of file ****
    1          1 ONE
    2          2 FLEW OVER
    3          3 THE CUCKOO'S
    4          4 NEST
      **** End of file ****
   

   
   
4. CONSOLE may stop reading from the keyboard before the condition specified in the argument is satisfied. If a stage that reads records which flow out of the CONSOLE stage, ends or disconnects its input stream, the CONSOLE stage ends; as in the following example:
   
   The first CONSOLE stage stops reading from the keyboard after the second line of data or a null has been entered. (The TAKE stage reads exactly 2 records and then disconnects is primary input stream; causing the primary output stream of the CONSOLE stage to become disconnected; which terminates the stage).
   
   

   **** Top of file ****
   Address Rxpipe
   
   'pipe console',
       '| take 2',
       '| console'
    
   Exit 0
   **** End of file ****
   

   
   
5. When the pipe TRACE ON option is specified (or the pipeline has inherited the TRACE ON setting through the CALLPIPE stage command); the CONSOLE stage encloses it's console output in angle brackets – prefixed with the CONSOLE stage name. For example:
   
   

   'pipe (trace on) literal /A literal string/ | console /"/ /"/'
   
   output:
   
   CONSOLE: >A literal string<
   

   
   However; the CONSOLE stage only uses this output format when writing a record to the console; records that are written to the primary output stream are written without modification.
   
   
6. CONSOLE verifies that its secondary input and output streams are not connected and then begins execution.

See: Usage.

IN, OUT, OUTPUT