|
JOIN stage v1.2 |
Pipelines v2.1 |
|
Syntax |
┌─1───────┐>>──JOIN──┬──┼─────────┼──┬───────────┬──────────────────────┬──┬───────────┬────────><
│ ├─numrecs─┤ └─insstring─┘ │ └─maxlength─┘ │ ├─ALL─────┤ │ (1) │ └─*───────┘ │ │ ┌─1-*────────┐ │└──UNTIL──┬─────────┬──┼────────────┼──┤ Target ├──┘
└─ANYCase─┘ └─inputrange─┘ Target: ┌─STRing──┐
├──┼─────────┼──tostring──┬───────────┬───────────────────────────────────────────────┤
├─REGexp──┤ └─insstring─┘ └─PATtern─┘ Notes:(1) The maxlength operand cannot be specified without specifying other operands.
|
Purpose |
Use the JOIN stage to concatenate one or more input records into
a single output record. JOIN reads records from its primary input stream,
concatenates the records, and writes the concatenated records to its primary
output stream. Records are concatenated in the order in which they appear in
the primary input stream.
JOIN concatenates consecutive input records, up to, but not
including a null input record. When JOIN reads a null input record; the output record
built so far (and if it contains any data) is written to the primary output
stream, JOIN then copies the null input record or records unchanged to its
primary output stream. JOIN initialises a new output record and continues to
read and concatenate input records. This process continues until JOIN reaches
end-of-file on its primary input stream.
|
Operands |
|
● |
is an unsigned integer which specifies the additional number of input records to join to the first record. That is, it concatenates the first numrecs+1 records into a single record up to the maxlength, if specified. It then concatenates the next numrecs+1 records up to the maxlength, if specified. This process continues until all primary input stream records have been processed. If the number of records in the input stream is not evenly divisible by numrecs+1, then the last output record written contains the remaining records. If you do not specify numrecs, JOIN concatenates pairs of input records. If you specify 0 for numrecs, JOIN copies all primary input stream records unchanged to its primary output stream. |
||||||||||||
|
● |
ALL * specifies that all records
in the input stream are combined into a single output record, if maxlength is not specified, or it is a
value greater than the combined length of all the input records. If maxlength is specified, input records
are combined into one or more output records. |
||||||||||||
|
● |
is a string to insert between
concatenated records. If numrecs
is not specified but insstring is
specified and insstring consists of
only decimal numbers (0-9), you cannot specify a number as the delimiting
character. |
||||||||||||
|
● |
UNTIL specifies that JOIN will concatenate records up to, but not including a record that matches the target tostring. Each time JOIN reads a record that matches the target tostring, the output record built so far and if it contains any data, is written to the primary output stream. The matching input record is discarded, a new output record is initialised and JOIN continues to read input records from its primary input stream. This process continues until the JOIN stage reaches end-of-file. |
||||||||||||
|
|
|
||||||||||||
|
● |
is an unsigned integer which defines
the maximum length of an output record. If you specify, for example, * and a value of 72 for maxlength, input records are
concatenated into one or more output records that are not longer than 72
characters. JOIN does not split input records when trying to create an output
record with a length specified by maxlength.
An input record with a length that is equal to or greater than the maxlength specified,
is written unchanged to the output stream. |
|
Streams |
The following streams are used by the JOIN stage:
|
|
Usage |
|
1. |
JOIN
delays the records. The
last input record in each set of concatenated records is not delayed. |
|
2. |
If
the JOIN stage discovers that its primary output stream is not connected, the
JOIN stage ends. |
|
3. |
If
numrecs is not specified but insstring is specified and consists of
only decimal numbers (0-9), you cannot specify a number as the delimiting
character. For example: join /2/
is not equivalent to join 121
The first JOIN stage concatenates
pairs of records and inserts the string 2 between each pair. The second;
concatenates groups of 122 records. That is, 121 is
processed as numrecs rather than as
a string. |
|
4. |
JOIN verifies that its secondary
input and output streams are not connected and then begins execution. |
|
Examples |
|
1. |
|
|
2. |
|
|
3. |
|
|
4. |
|
To combine all lines of file INPUT FILE into a
paragraph with lines of length 72 in file OUTPUT FILE A, specify:
pipe < INPUT FILE
| split | join * / / 72 | > OUTPUT FILE A
The string operand in this example
assures that a blank is inserted between each word in INPUT FILE.
pipe < JOIN DATA | join 2 /***/ | console
Figure 101. JOIN Stage Example: Input File Contents
JOIN
DATA A1 V 80
Trunc=80 Size=8 Line=0 Col=1 Alt=0
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
===== * * * Top of File * * *
===== 111
===== 222
===== 333
===== 444
===== 555
===== 666
===== 777
===== 888
===== * * * End of File * * *
Figure 102. JOIN Stage Example: Command and Terminal Output
pipe < JOIN DATA | join 2 /***/ | console
111***222***333
444***555***666
777***888
Ready;
|
Related |