|
OUT stage v1.1 |
Pipelines v1.9 |
|
Purpose, Operands, Streams used, Usage notes,
Examples, See also |
|
Syntax |
_0______
>>__OUT__|________|____________________________________________________________________><
|_stream_|
|
Purpose |
Use the OUT stage to read records from its primary input stream and write them to the specified target stream and to its primary output stream, if it is connected. OUT appends a Line-Feed character to each output record that it writes to the specified target stream, primary output stream records are written unchanged.
|
● |
When OUT is specified in a pipeline that has been launched by the CALLPIPE stage command; the target stream operand corresponds to either the primary or secondary output stream of that CALLPIPE stage. In other words, records that are written by OUT to stream 0; flow back into the CALLPIPE stage and out through its primary output stream, similarly, records written to stream 1; flow back into the CALLPIPE stage and out through its secondary output stream. When OUT determines that the target stream has become disconnected (i.e. that the corresponding CALLPIPE output stream has become disconnected) the OUT stage ends. |
|
● |
When
OUT is specified in a pipeline that has not been launched by the CALLPIPE
stage command; records that are written to stream 0 are routed to the system output stream; STDOUT.
Specifying an output stream of 1;
causes the OUT stage to end immediately. |
|
Operands |
|
● |
is an unsigned integer which specifies
an output stream number; a value of
0 or 1 is allowed. |
|
Streams used |
The following streams are used by the OUT
stage:
|
Stream
|
Action |
|
|
|
|
Primary input
stream |
OUT reads records from its primary input
stream. |
|
Target output
stream |
When OUT is
specified in a pipeline that has been launched by the CALLPIPE stage command;
the primary and secondary output streams of the OUT stage correspond to
primary and secondary output streams of that CALLPIPE stage. When OUT is specified in a pipeline that has not been launched by the CALLPIPE stage command; records that are written to stream 0 are routed to the system output stream; STDOUT. Specifying an output stream of 1; causes the OUT stage to end immediately. |
|
Primary output
stream |
OUT writes records to its primary output
stream, if it is connected. |
|
Usage notes |
|
1) |
OUT does not delay the records. |
|
2) |
After writing a record to the specified
target stream; OUT writes that same
record to its primary output stream, if it is connected. OUT then determines
if its target output stream has
become disconnected. |
|
3) |
When OUT writes to the system output
stream; STDOUT, it writes the records one at a time; waiting for each one to
be consumed from the target STDIN stream before writing another. When OUT
reaches end-of-file on its primary input stream or the target STDIN stream
has become disconnected; OUT disconnects its STDOUT stream and the stage
ends. |
|
4) |
You should only specify a single OUT 0 stage and a single OUT 1 stage in any one set of
pipelines; otherwise the results may be unpredictable. |
|
5) |
OUT is designed
primarily to work in conjunction with the CALLPIPE stage command. OUT
connects the specified output stream to
the corresponding output stream of the CALLPIPE stage; this allows you to
construct pipelines which serve as filter subroutines; where selected and
unselected records are written to separate output streams. Consider the
following example: mypipe.pplpipe (endchar ?) literal /abcd acdbef abcdef abcdefg/ .* Some text to play with. | split .* Separate text into words. | a: call mylocate 1-* "cd" -2;* "ef" .* Find phrase cd only in.. .*..records that end with ef. | specs /Pri output stream:/ 1 1-* nw .* Indicate the stream. | cons .* Display. ? a: | specs /Sec output-stream:/ 1 1-* nw .* Indicate the stream. | cons .* Display.mylocate.ppl pipe (endchar ?) in .* Read input records from CALLPIPE. | a: locate &arg3 /&arg4/ .* Find text: &arg4 in position: &arg3. .* Write matches to pri output stream.. .* ..Non-matches to sec output stream. | b: locate &arg1 /&arg2/ .* Find text: &arg2 in position: &arg1. .* Write matches to pri output stream.. .* ..Non-matches to sec output stream. | out 0 .* Matches out through CALLPIPE.. .* ..pri output stream. | hole .* Keep the pipeline alive. | c: faninany .* Route in records not selected. | out 1 .* Non-matches out through CALLPIPE.. .* ..sec output stream. ? a: | take * .* Handle records rejected by first.. | c: .* ..locate and send back to faninany. ? b: | take * .* Handle records rejected by second.. | c: .* ..locate and send back to faninany.Executing mypipe.ppl produces the following output: C:\>pipe mypipe Sec output stream: abcd Pri output stream: acdbef Pri output stream: abcdef Sec output stream: abcdefg |
|
6) |
OUT verifies that
its secondary input and output streams are not connected and then begins
execution. |
|
Examples |
The following
pipeline reads the file: myfile.cpp
and changes any occurrence of the word ifdef to ifndef and writes the records to
STDOUT (in this case, the console).
D:\>type myfile.cpp | pipe in | change /ifdef/ /ifndef/ | out
|
See also |
Reference the following links for additional information:
CALLPIPE, CONSOLE, IN