|
COLLATE stage v1.0 |
Pipelines v2.0 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
_NOPAD____>>__COLLATE__|__________|__| Group |___________________________________________________>< |_PAD_char_| Group:
_1-*_____________1-*____________ _MASTER DETAILs_|__|________________________________|__|________________|_______________________________| |_columnrange1__ ______________ _| |_MASTER_________| |_columnrange2_| |_DETAILs________| |_DETAILs MASTER_| Notes:(1) columnrange1 and columnrange2 are unsigned.
|
Purpose |
Use the COLLATE stage to match
records in its primary input stream with records in its secondary input stream
and write the matched and unmatched records to different output streams. The
records in each input stream must be in ascending order based on the contents
of a key field.
The records in the primary input
stream are referred to as master records. Each master record has a key field; a
specific range of columns within a record with unique contents that identifies
the record. Two master records cannot have the same contents in their key
field.
The records in the secondary input
stream are referred to as the detail records. The detail records have key
fields as well and both the master and detail records should be sorted in
ascending order by their key fields. A detail record matches a master record
when the key field in both records contains the same data. Two or more detail
records can have the same data in their key field.
COLLATE writes records to three
output streams if each is connected:
|
● |
The primary output stream
contains matching records. The operands for COLLATE let you specify the
sequence of the master and detail records in the primary output stream and
whether COLLATE writes both the master and detail records, only the master
records, or only the detail records to the primary output stream. |
|
● |
The secondary output stream
contains master records that do not have any matching detail records. |
|
● |
The tertiary output stream
contains detail records that do not have a matching master record. |
|
Operands |
|
● |
NOPAD specifies that shorter key fields are not extended with a pad character before they are compared with longer key fields in other records. This is the default. |
||
|
● |
PAD specifies that shorter key fields are extended with a pad character before they are compared with longer key fields in other records. |
||
|
|
|
||
|
● |
is an unsigned integer column range which defines
a key field for the master records. If columnrange1 is not specified, the key
field is the entire record for both the primary and secondary input streams.
The format of columnrange1 is identical to the format specification
for columnrange2. |
||
|
|
|
||
|
● |
MASTER DETAILs specifies that the master record followed by its matching detail records
are written to the primary output stream. This is the default. |
||
|
● |
MASTER specifies that only the master records are written to the primary
output stream. The matched detail records are discarded. |
||
|
● |
DETAILs specifies that only the detail records are written to the primary
output stream. The matched master records are discarded. |
||
|
● |
DETAILs MASTER specifies that the matched detail records followed by their master record are written to the primary output stream. |
|
Streams used |
The following streams are used by the COLLATE stage:
|
Stream |
Action |
|
|
|
|
Primary input stream |
COLLATE reads master records from its primary input
stream. |
|
Secondary input stream |
Reads detail records from its
secondary input stream. The secondary input stream must be defined. |
|
Primary output stream |
Writes matching records to its
primary output stream. |
|
Secondary output stream |
Writes master records that do not have
any matching detail records to its secondary output stream, if it is
connected. |
|
Tertiary output stream |
Writes
detail records that do not have a matching master record to its tertiary
output stream, if it is connected. |
|
Usage notes |
|
1) |
COLLATE does not delay the records. |
|
2) |
If the
COLLATE stage discovers that all of its output streams are not connected, the
COLLATE stage ends. |
|
3) |
The following
diagram shows the input and output streams for the COLLATE stage using the
default operands:
|
|
4) |
Although the
COLLATE and LOOKUP stages
both process master and detail records read from their input streams, COLLATE
reads master records from its primary input stream and LOOKUP reads master
records from its secondary input stream. COLLATE reads detail records from
its secondary input stream and LOOKUP reads detail records from its primary
input stream. |
|
5) |
Unlike the
LOOKUP stage, COLLATE requires that input records be sorted in ascending
order by their key field. |
|
6) |
COLLATE verifies that
its tertiary input stream is not connected and then begins execution. |
|
Examples |
The pipeline in the following
example shows how to specify a COLLATE stage as shown in the preceding diagram.
The COLLATE stage reads records from its primary and secondary input streams
and writes the contents of its primary, secondary and tertiary output streams
to separate files.
**** Top of file ****01 Address Rxpipe0203 ‘pipe (endchar ?)’,04 ‘< master.txt’, /* Read master records. */05 ‘| c: collate’, /* Find matches. */06 ‘| > matchingrecords.txt’, /* Write matching masters and details. */07 ‘?’,08 ‘< details.txt’, /* Read detail records. */09 ‘| c:’, /* Define secondary stream for COLLATE. */10 ‘| > unrefmasters.txt’, /* Write masters without details. */11 ‘?’,12 ‘c:’, /* Define tertiary stream for COLLATE. */13 ‘| > unrefdetails.txt’ /* Write details without masters. */1415 Exit 0**** End of file ****
|
See also |
Reference the following links for
additional information:
|
History of change |
None.
|
|