|
DEAL stage v1.0 |
Pipelines v1.9 |
|
Purpose,
Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
_STOP_ALLEOF________>>__DEAL__|____________________|_______________________________________________________><
|_STOP_ _ALLEOF__ ___| | |_ANYEOF__| | | |_streams_| | |_SECONDARY__________| | _1-*________ _| |_KEY_|____________|_| |_inputrange_|
|
Purpose |
Use the DEAL stage to read records
from its primary input stream and write records to one of its connected output
streams in either sequential order; starting with the primary output stream, or
some other order specified on the secondary input stream. Unless otherwise
specified; DEAL writes the first input record to the connected primary output
stream, the second input record to the connected secondary output stream, and
so on, until the last connected output stream receives a record, and then the
cycle is repeated.
When the SECONDARY operand is
specified; DEAL sequentially processes a secondary input record and primary
input record as a pair. Each secondary input stream record must contain an
integer output stream identifier which will control the order in which DEAL
writes output records. In this way you can choose your own output stream order
rather than use the sequential default. DEAL first reads and inspects a record
from the secondary input stream, and retrieves the identity of the output
stream that will receive a written record. DEAL then reads a record from its
primary input stream. When DEAL determines that the output stream identified in
the secondary input stream is connected; DEAL writes a record from the primary
input stream to the specified output stream. DEAL then consumes the records
from both its primary and secondary input streams.
You can also write a contiguous
series of primary input stream records that have matching keys to the same
output stream. DEAL searches for an identified location in each input record
that contains the specified key, comparing the key from one record to the next.
If the key location is not specified, or it is specified but is not found, DEAL
uses the entire record as the key.
|
Operands |
|
● |
STOP specifies how many output streams must be at end-of-file for DEAL to stop writing output records. STOP ALLEOF is the default. |
||
|
|
|
||
|
|
|
||
|
|
|
||
|
● |
SECONDARY specifies that DEAL first
reads and inspects a secondary input stream record containing a stream
identifier before reading a primary input stream record and writing it to
that identified output stream. One secondary input stream record is processed
with one primary input stream record as a pair, so the order of the records
on the secondary input stream controls the order in which DEAL writes primary
input stream records to its output streams. |
||
|
● |
KEY identifies the location in
each input record that contains the key of each record. A contiguous group of
input records with the same key are written to the same output stream. When
the key changes from one input record to the next; DEAL writes the record
with the changed key to the next sequential, connected output stream. |
||
|
|
|
|
Streams used |
The following streams are used by the DEAL stage:
|
Stream
|
Action |
|
|
|
|
Primary input
stream |
DEAL reads records in sequential order
from its primary input stream. |
|
Secondary input
stream |
DEAL reads a
record from its secondary input stream, if it is connected and the SECONDARY
operand is specified. The secondary input stream record is paired with a
primary input stream record. |
|
Output streams |
DEAL writes each of its primary input
stream records to one of its connected output streams, in either sequential
order starting with the primary output stream, or the order specified on the
secondary input stream. |
|
Usage notes |
|
1) |
DEAL
does not delay the records. |
|
2) |
If
the DEAL stage discovers that its primary or secondary input streams are not
connected, the DEAL stage ends. If
the SECONDARY or KEY operand is specified and the DEAL stage discovers that
the output stream it needs to write the next record to is not connected; DEAL
ends and any remaining input records are not fully processed. If
the DEAL stage discovers that the number of streams specified by the STOP
operand are not connected; DEAL ends. If the number on the STOP operand is
greater than the total number of output streams in the pipeline; DEAL
processes as though STOP ALLEOF were specified. |
|
3) |
Leaving
an output stream unconnected will not cause records to be dropped; it causes
DEAL to end. |
|
4) |
With
any operand other than the SECONDARY operand; DEAL verifies that its primary
input stream is the only connected input stream and then begins execution. If
the SECONDARY operand is specified; DEAL verifies that both its primary and
secondary input streams are connected and then begins execution. |
|
Examples |
The following
example pipeline shows how you might use DEAL to control the order in which a
particular output stream receives a record. By specifying the SECONDARY operand
on the DEAL stage; the pipeline writes input records to specific output streams
defined by the LITERAL stage command in the third pipeline.
pipe (endchar
?)
literal /a j b p l/
| split
| j: deal secondary
| specs /Stream
0:/ 1 1-* nw
| console
?
j:
| specs /Stream 1:/ 1 1-* nw
| console
?
j:
| specs /Stream 2:/ 1 1-* nw
| console
?
literal /0 2 0 1
1/
| split
| j:
The
pipeline produces the following output:
Stream 0:
a
Stream 2:
j
Stream 0:
b
Stream 1:
p
Stream 1:
l
|
See also |
Reference the
following links for additional information:
ELASTIC,
FANIN,
FANINANY, FANOUT
|
|