|
OVERLAY stage v1.0 |
Pipelines v2.1 |
Done.
|
Syntax |
┌─SPACE──┐
>>──OVERlay──┼────────┼──────────────────────────────────────────────────────────────><
└─char───┘
|
Purpose |
Use the OVERLAY stage to read one record from each connected input stream and create a single output record such that each position in the output record contains the character in the relative position from the highest-numbered input stream. OVERLAY writes the output record to its primary output stream.
One character has the property that it does not overlay a character from a lower-numbered stream. By default, this character is a space. The operand may select a different character. If a record in the highest-numbered input stream contains the specified character in any position, OVERLAY replaces the character in the output record with the corresponding character from the next highest-numbered input stream that has something other than the specified character in that position.
|
Operands |
|
● |
SPACE specifies that a space character (hexadecimal value; x'20') is the overlay character. This is the default. |
|
● |
is a character which does not overlay data on lower-numbered
input streams. |
|
Streams |
The following streams are used by the OVERLAY stage:
|
|
Usage |
|
1. |
OVERLAY
delays one record. |
|
2. |
If
the OVERLAY stage discovers that its primary output stream is not connected,
the OVERLAY stage ends. |
|
3. |
If
a position in each input stream contains the specified character, OVERLAY
places that character in the output record. |
|
4. |
If
a record in the highest-numbered input stream is not as long as a
lower-numbered input stream record, OVERLAY writes the remaining characters
from the lower-numbered input stream records to the output stream. |
|
5. |
If
OVERLAY processes input streams where one input stream does not have a record
to compare, it compares the records from the other streams. Consider the
following streams: stream 0 contains 12 recordsstream 1 contains 14 recordsstream 2 contains 10 records
OVERLAY combines the first 10
records from all three streams and writes those records to its output stream.
Then it compares the 11th and 12th records of its
primary and secondary input streams and writes those two records to its
output stream. Finally, OVERLAY copies the 13th and 14th
records from its secondary input stream to its output stream. |
|
6. |
OVERLAY reads a record from an
input stream, processes it, and then releases it before it reads a record
from the next highest input stream or writes to its output stream. |
|
7. |
OVERLAY processes input records
until all input streams reach the end-of-file. |
|
8. |
OVERLAY verifies that its
secondary output stream is not connected and then begins execution. |
|
Examples |
|
1. |
The following diagram shows two
input streams for OVERLAY and its resulting output stream, where char is SPACE; the default.
|
||
|
2. |
This next diagram uses the same
input stream data, but specifies char
as A.
|
||
|
3. |
The
following example uses the OVERLAY stage to overlay the contents of the file:
form.txt with the contents of the
file: employee.txt and produces a
single 'merged' output file: header.txt.
The OVERLAY stage below, process two input streams; a primary input stream (records read from: format.txt) and a secondary input stream (records read from: employee.txt). However, OVERLAY can process any number of input overlay files, see: Purpose for an explanation and example 4, below, for more information. **** Top of file ****
1 Address Rxpipe 2 3 'pipe (endchar ?)', 4
'< form.txt', /* Read form.txt. */ 5 '|
a: overlay', /* Combine primary and secondary input streams. */ 6 '|
> header.txt', /* Write the result to header.txt. */ 7 '?', 8
'< employee.txt', /* Read employee.txt. */ 9 '|
a:' /* Route back to OVERLAY.*/ 10 11 Exit 0 **** End of file **** header.txt (output) ...|...+....1....+....2....+....3....+....4.... **** Top of file ****
1 Name:
Christine Smith 2 Address: 2020 Wilson Street 3 City:
Los Angeles 4 State:
CA **** End of file **** |
||
|
4. |
The OVERLAY stage in the following
example combines the records from three input streams: **** Top of file ****
1 Address Rxpipe 2 3 'pipe (endchar ?)', 4
'literal /BBBBB/', /* Write BBBBB to the primary input of OVERLAY. */ 5 '|
o: overlay', /* Combine primary, secondary, & tertiary inputs.
*/ 6 '|
console', /* Display combined results on the console. */ 7 '?', 8
'literal /AAA/', /* Write AAA to secondary input of OVERLAY. */ 9 '|
o:', /* Define secondary input for OVERLAY. */ 10 '?', 11 'literal /A B C/', /* Write A B C
to tertiary input of OVERLAY. */ 12 '| o:' /*
Define tertiary input for OVERLAY. */ 13 14 Exit 0 **** End of file **** output: AABBC If you change the OVERLAY stage to
o:
overlay A, the result is: output: B B C |
|
Related |
|
History |
|
Version |
Date |
Action |
Description |
Pipelines |
|
1.2 |
23.12.2021 |
changed |
Application-wide rewrite. |
|
|
04.02.2012 |
added |
Support
for the REGEXP operand; which specifies that the string operand is interpreted as a regular expression. |
||
|
1.0 |
06.09.2007 |
created |
First version. |
|
|