|
NLOCATE stage v1.2 |
Pipelines v2.0 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
_1-*_________________>>__NLOCate__ _________ __|_____________________|__ __________________ __ _____ _______>< |_ANYCase_| |_inputrange__________| |_STRing__ | | Set | | <____________ | |_________|_string_| |_(__inputrange__|__)_| |_REGexp__| | |_PATtern_| | |_ANYof___| | |_<_______|_value__| |_<=______| |_==______| |_!=______| |_>=______| |_>_______|Set: _BOTH___|__count__|________|__ ___________ _____________________________________________________| |_BEFORE_| |_sepstring_| |_AFTER__| Notes:(1) If you specify ANYCASE, multiple inputrange operands or any of the string operand operands; you must provide a string to locate.(2) You cannot specify a Set of records without specifying other operands.
|
Purpose |
Use the NLOCATE stage to select records
that do not contain a specified target string
of characters. NLOCATE writes primary input stream records that do not contain
the specified string to its primary
output stream. If its secondary output stream is connected; NLOCATE writes the
unselected input records to its secondary output stream; otherwise they are
discarded.
NLOCATE searches for the string within one or more locations of
the input record. If you do not specify an inputrange,
NLOCATE searches the entire input record. When a single inputrange location is specified; if you do not specify the string operand, NLOCATE writes to its
primary output stream only input records of length inputrange –1 or less.
In addition, NLOCATE can select a
Set of records which precede and/or follow the target record; writing each Set
of records to the secondary output stream, if it is connected; otherwise they
are discarded. Records which are not selected are written to the primary output
stream. You can also specify that an interleaving separator sepstring is written between each Set of
secondary output stream records.
|
Operands |
|
● |
ANYCase specifies that when NLOCATE
compares the contents of an input record specified by inputrange and the target string,
the comparison made is non-case-sensitive. |
||
|
● |
is an integer column, word or field range on which to operate. |
||
|
● |
STRing specifies that the string
operand is a literal string of characters to locate. |
||
|
● |
REGexp specifies that the string operand is a regular expression of characters to locate. |
||
|
● |
PATtern specifies that the string
operand is a pattern of characters to locate. |
||
|
● |
ANYof specifies that
the string operand is a list of
characters, any of which are to be located. |
||
|
|
|
||
|
● |
< specifies that the numeric value of the literal
string defined by inputrange is located
only when it is less than the operand; value. |
||
|
● |
<= specifies that the numeric value of the literal
string defined by inputrange is
located only when it is less than or equal to the operand; value. |
||
|
● |
== specifies that the numeric value of the literal
string defined by inputrange is
located only when it is exactly equal to the operand; value. |
||
|
● |
!= specifies that the numeric value of the literal
string defined by inputrange is
located only when it is not equal to the operand; value. |
||
|
● |
>= specifies that the numeric value of the literal
string defined by inputrange is
located only when it is greater than or equal to the operand; value. |
||
|
● |
> specifies that the numeric value of the literal
string defined by inputrange is
located only when it is greater than the operand; value. |
||
|
|
|
||
|
● |
is an unsigned integer which specifies the number of records to select before and/or after a target record. |
||
|
● |
BOTH specifies that
count number of records which
precede and follow a record that contains the target string are also selected. This is the default. |
||
|
● |
BEFORE specifies that count number of
records which precede a record that contains the target string are also selected. |
||
|
● |
AFTER specifies that count number
of records which follow a record that contains the target string are also selected. |
||
|
● |
is a string to write after each Set of selected records. |
|
Streams used |
The following streams are used by the NLOCATE stage:
|
Stream |
Action |
|
|
|
|
Primary input stream |
NLOCATE reads records from its primary input stream. |
|
Primary output stream |
NLOCATE writes the records which are not selected to its
primary output stream. |
|
Secondary output stream |
If it is connected, NLOCATE writes the records which are
selected to its secondary output stream. |
|
Usage notes |
|
1) |
NLOCATE without the count
operand does not delay the records. NLOCATE used with the
count and BOTH or BEFORE operands;
delays every count number of
records. |
|
2) |
If the NLOCATE stage discovers that its primary input
stream is not connected, the NLOCATE stage ends. |
|
3) |
If no operands are specified before string, and if string
consists of only decimal numbers (0-9), you cannot specify a left parentheses
or a number as the delimiting character. For example: nlocate /5/ is not
equivalent to nlocate (5(The first
NLOCATE stage selects records that do not contain the string 5. The second stage results in an error message, because (5(
is processed as a number range rather than a delimited string. |
|
4) |
If no inputrange is specified; you cannot
specify an asterisk (*) as the delimiting character for string when it consists of only a hyphen (-). |
|
5) |
You can use the NLOCATE stage
followed by a LOCATE stage to select records of a particular length. For
example, the following pipeline displays only those records of the file; myfile.txt, that are exactly 20
characters long: **** Top of file **** 01 Address Rxpipe0203 ‘pipe < myfile.txt’,04 ‘| nlocate 21’,05 ‘| locate 20’,06 ‘| console’0708 Exit 0**** End of file **** |
|
6) |
To select only null records, use
NLOCATE as so: ... | nlocate 1 | ... |
|
7) |
If you specify the count operand; NLOCATE will always
finish selecting a Set of records before it begins searching for a new
occurrence of the target string,
for example: **** Top of file ****01 Address Rxpipe0203 ‘pipe lit /A B B C B D/ | split | nlocate /B/ 1 after /---/ | cons’0405 Exit 0**** End of file ****Output:AC
In the example above; the second
occurrence of B is treated as the first
record in the Set of records which follow the target record and not the start
of another Set. The same is true of the BOTH and BEFORE operands. Once a Set
is started, NLOCATE selects the specified number of records before searching
for the next target record. |
|
8) |
NLOCATE verifies that its
secondary input stream is not connected and then begins execution. |
|
Examples |
|
1) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /a-b-c/ | literal /d-e-f/ | nlocate wordsep /-/ w3 /c/ | console’0405 Exit 0**** End of file ****Output:
d-e-f |
|
2) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /a?b?/ | literal /e??f/ | nlocate fieldsep /?/ f2-3 /f/ | console’0405 Exit 0**** End of file ****Output:
a?b? |
|
3) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /?a?c?f a??c?e/ | split | nlocate (ws /?/ word 3) /e/ | console’0405 Exit 0**** End of file ****Output:
?a?c?f |
|
4) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /afbc adef ghfi fjkl/ | split | nlocate -2;-1 /f/ | console’0405 Exit 0**** End of file ****Output:afbc
fjkl |
|
5) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /12 1.23e5 -9.5 150000.00/ | split | nlocate == 123000 | console’0405 Exit 0**** End of file ****Output:12-9.5150000.00 |