CONSOLE stage v1.3

Pipelines v2.1

 

Purpose, Operands, Streams, Usage, Examples, Related

Home

 

Syntax

 
(1)
>>──┬─CONSole──┬──┬────────────┬─────────────────────────────────────────────────────><
    ─SCReen───  └─EOFstring─┘
    └─TERMinal─┘
 
(2)
>>────CONSole─────────────────────┬─────────────────────────────┬────────────────────><
                                  └─DELIMitstartstr─┬────────┬─┘
                                                     └─endstr─┘
 
Notes:
(1) May only be specified when console is the first stage of a pipeline.
(2) May only be specified when console is not the first stage of a pipeline.
 

Purpose

 

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 operands are 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 EOF operand.

 

 

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, at the same time, 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.

 

Operands

 

EOF

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. The string is not written to the output stream. Uppercase and lowercase representations of the same characters do not match. CONSOLE stops reading from the keyboard if the line read exactly matches the target string you specify.

 

DELIMit

specifies that records written to the console are prefixed and appended with a pair of delimiting character strings. The CONSOLE stage only uses the delimiting strings when writing the record to the console, they are not included in the record written to the primary output stream.

 

 

startstr

endstr

are a pair of delimited literal strings that enclose the record displayed on the screen.

 

For example: to display a record surrounded by a pair of quotation marks:

 

. . . console delimit /"/ /"/ . . .
 

Streams

 

The following streams are used by the CONSOLE stage:

 

Stream

 

Action

 

 

Primary input stream

When CONSOLE is not the first stage of the pipeline, CONSOLE reads records from its primary input stream.

Primary output stream

When CONSOLE is the first stage of the first pipeline, CONSOLE writes the records it reads from the keyboard to its primary output stream. When CONSOLE is not the first stage of the pipeline, CONSOLE writes the records it reads from its primary input stream to its primary output stream.

 

Usage

 

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.

CONSOLE may stop reading from the keyboard before the condition specified in the operands 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 ****

 1 Address Rxpipe

 2

 3 'pipe console',

 4    '| take 2',

 5    '| console

 6

 7 Exit 0

   **** End of file ****

 

4.

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:

 

CONSOLE: >some output text<

 

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.

 

5.

CONSOLE verifies that its secondary input and output streams are not connected and then begins execution.

 

Examples

 
See: Usage
 

Related

 
IN, OUT 
 

History

 

Version

 

Date

Action

Description

Pipelines

1.3

??.??.2025

changed

Application-wide rewrite.

2.1

1.2

23.05.2011

added

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

1.9

1.1

22.04.2008

changed

Carriage-Return control characters are now discarded by the string operand.

1.5

1.0

06.09.2007

created

First version.

1.0