|
CHANGE stage v1.0 |
Pipelines v1.9 |
|
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:
|
|