|
LOCATE stage v1.2 |
Pipelines v2.0 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
_1-*_________________ >>__LOCate__ _________ __|_____________________|__ __________________ __ _____ ________>< |_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 LOCATE stage to select
records that contain the specified target string
of characters. LOCATE writes primary input stream records that contain the
specified string to its primary
output stream. If its secondary output stream is connected; LOCATE writes the
unselected input records to its secondary output stream; otherwise they are
discarded.
LOCATE searches for the string within one or more locations of
the input record. If you do not specify an inputrange,
LOCATE searches the entire input record. When a single inputrange location is specified; if you do not specify the string operand, LOCATE writes to its
primary output stream only input records of length inputrange or greater.
In addition, LOCATE can select a
Set of records which precede and/or follow the target record; writing each Set
of records to the primary output stream. Records which are not selected are
written to the secondary output stream, if it is connected; otherwise they are
discarded. You can also specify that an interleaving separator sepstring is written between each Set of
primary output stream records.
|
Operands |
|
● |
ANYCase specifies that when LOCATE
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 LOCATE stage:
|
Stream |
Action |
|
|
|
|
Primary input stream |
LOCATE reads records from its
primary input stream. |
|
Primary output stream |
LOCATE writes the records which
are selected to its primary output stream. |
|
Secondary output stream |
If it is connected, LOCATE writes
the records which are not selected to the secondary output stream. |
|
Usage notes |
|
1) |
LOCATE
without the count operand does not delay the records. LOCATE used with the count and BOTH or BEFORE operands;
delays every count number of
records. |
|
2) |
If the
LOCATE stage discovers that its primary input stream is not connected, the
LOCATE 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: LOCATE /5/ is not equivalent to LOCATE (5( The first LOCATE stage selects records that 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) |
If you specify the count
operand; LOCATE 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/’,04 ‘| split’,05 ‘| locate /B/ 1 after /---/’,06 ‘| cons’0708 Exit 0**** End of file ****Output:BB---BD---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 AFTER operands. Once a Set is started, LOCATE selects the
specified number of records before searching for the next target record. |
|
6) |
You can use the LOCATE stage
followed by an NLOCATE 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 | locate 20 | nlocate 21 | console’ 0405 Exit 0*** End of file **** |
|
7) |
If you want to remove blank lines
from a file; use the STRIP stage to remove leading and trailing spaces, and
then use LOCATE with no operands to search for records of length 1 or
greater. For example: **** Top of file **** 01 Address Rxpipe0203 ‘pipe < myfile.txt | strip | locate | > myfile.txt’0405 Exit 0**** End of file **** |
|
8) |
You may want to locate/identify
records or sections of a record that comprise only the specified characters.
The following example demonstrates how you might use the regular expression
capabilities of the LOCATE stage to VERIFY that a record only contains
numeric digits. **** Top of file ****01 Address Rxpipe0203 ‘pipe lit /12345 12T45/’,04 ‘| split’,05 ‘| locate reg /^[0-9]+$/’, 06 ‘| cons’0708 Parse pull09 Exit 0**** End of file ****Output:12345
This approach to selecting
records based on a restricted set or sets of characters may be of particular
use, for example; in selecting records that comprise only numeric data,
alphanumeric characters or a specific set of any mixture of characters, a
valid email address or a properly formatted telephone number, etc.. |
|
9) |
When you specify a numerical
comparison operator, you must be mindful that when representing a floating
point value; rounding may occur and this may affect the result when comparing
values that comprise a significant number of decimal digits.. |
|
10) |
LOCATE will accept any valid
floating-point double-precision
representation of a number to locate in both the input record and the
operand; value. For example; the
following definitions are considered to be identical: 78000 7.8e4 7.8e+4 78e3 |
|
11) |
LOCATE 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/ | locate wordsep /-/ w3 /c/ | console’0405 Exit 0**** End of file ****Output:
a-b-c |
|
2) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /a?b?/ | literal /e??f/ | locate fieldsep /?/ f2-3 /f/ | console’0405 Exit 0**** End of file ****Output:
e??f |
|
3) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /?ab?c??a ab?c?a/ | split | locate (ws /?/ w1 w3) /a/ | console’0405 Exit 0**** End of file ****Output:?ab?c??a
ab?c?a |
|
4) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /afbc adef ghfi fjkl/ | split | locate -2;-1 /f/ | console’0405 Exit 0**** End of file ****Output:adef
ghfi |
|
5) |
**** Top of file ****01 Address Rxpipe0203 ‘pipe literal /12 1.23e5 -9.5 150000.00/ | split | locate >= 123000 | console’0405 Exit 0**** End of file ****Output:1.23e5150000.00 |