|
CHANGE stage v1.1 |
Pipelines v1.6 |
|
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 keyword; 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 keyword; 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 keyword; 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 keyword; 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 keyword; 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 keyword; 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 keyword;
which specifies that the fromstring
and tostring operands are
interpreted as a regular expression and a format string, respectively. |
|
|