|
CHANGE stage v1.1 |
Pipelines v2.0 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
_STRing_>>__CHANGE__ _________ __ _______ __|________|__fromstring__tostring__ ___________ ____>< |_ANYCase_| | Range | |_REGexp_| |_maxchange_| Range: |__ _1-*_____________________ |_ _______________________|__________________________________________________________| |_columnrange___________| | <_____________ | |_(____columnrange_|__)_| Notes:(1) columnrange is unsigned.
|
Purpose |
Use the CHANGE
stage to replace a character or string of characters with another character or
string of characters of the same or different length. CHANGE reads records from
its primary input stream, replacing any occurrences of fromstring that are found within the specified columnrange with tostring,
and writes the records to its primary output stream. If fromstring does not appear in an input record, CHANGE writes the
record unchanged to its secondary output stream, if it is connected, otherwise
it writes the unchanged record to its primary output stream.
|
Operands |
|
● |
ANYCase when specified
in conjunction with the STRING operand; the case of letters are preserved in the following manner: The text specified in fromstring
and in the input record are compared in uppercase. If fromstring is found and contains one or more uppercase characters
or contains no letters; then tostring
replaces the given text in the output record without change of case.
Otherwise, an attempt is made to preserve the case of the text being
replaced. When the text contains no uppercase letters and starts with one or
more lowercase letters, the following rules determine the case of the
replacement text in tostring. |
||||||
|
|
|
||||||
|
|
When specified
in conjunction with the REGEXP operand; the regular expression fromstring is compared with the
contents of an input record without regard to case. |
||||||
|
● |
is an unsigned integer column range in which to search for fromstring. If you do not specify columnrange, CHANGE searches the entire
record for occurrences of fromstring.
You
can specify any number of columnrange
operands. If you specify more than one, you must place at least one space
between each columnrange and you
must enclose the set of columnrange
operands within parentheses. If you specify more than one columnrange operand, the range of
columns must not overlap. |
||||||
|
● |
STRing specifies that the fromstring and tostring
operands are literal strings. |
||||||
|
● |
REGexp specifies that the fromstring
operand is a regular expression
of characters to locate and the tostring
operand is an expression format string. |
||||||
|
● |
in conjunction with the STRING operand; fromstring defines a string that is to be replaced by tostring. If you specify a null string for fromstring, CHANGE inserts tostring immediately before the first column of the columnrange which defines the leftmost column of the record. When used in conjunction with the REGEXP operand; fromstring is a regular expression of characters to locate. If columnrange is not specified and if
both fromstring and tostring consist only of decimal
numbers (0-9), you cannot specify a left parenthesis or a number as the
delimiting character. |
||||||
|
● |
in conjunction with the STRING operand; tostring defines a string that is to replace fromstring. If you specify a null
string for tostring, CHANGE deletes
occurrences of fromstring within
the range or ranges you specify for columnrange.
When used in conjunction with the REGEXP operand; tostring defines a format string which specifies the way in which
the occurrences of the expression fromstring
are to be changed/formatted. |
||||||
|
|
|
|
Streams used |
The following streams are used by the CHANGE stage:
|
Stream |
Action |
|
|
|
|
Primary input stream |
CHANGE reads records from its primary input stream.
|
|
Primary output stream |
After replacing any specified strings in records read from its
primary input stream, CHANGE writes both records that have been changed and
records that remain unchanged to its primary output stream when no secondary
output stream is connected. |
|
Secondary output stream |
When
the secondary output stream is defined and connected, CHANGE writes changed
records to its primary output stream and unchanged records to its secondary
output stream. |
|
Usage notes |
|
1) |
CHANGE does not delay the records. |
|
2) |
If the CHANGE stage discovers that all of its output
streams are not connected, the CHANGE stage ends. |
|
3) |
If columnrange is not specified and if both fromstring and tostring
consist of only decimal numbers (0-9), you cannot specify a left parenthesis
or a number as the delimiting character. For example: change /8//9/
is not equivalent to change 383393
The first CHANGE stage changes
the string 8 to 9. The second stage results in an error message because
383393 is processed as a columnrange
operand rather than a delimited string. The error message is issued because fromstring and tostring are missing and they are required operands. |
|
4) |
CHANGE verifies that its
secondary input stream is not connected and then begins execution. |
|
Examples |
|
See also |
Reference the
following links for additional information:
|
History of change |
|
Version |
Action |
Description |
|
|
|
|
|
1.1 |
Added |
Support for the REGEXP operand; which specifies that the fromstring and tostring operands are interpreted as a regular expression and a
format string, respectively. |
|
|