|
LOCATE stage v1.2 |
Pipelines v1.9 |
|
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: C:\>pipe "lit /A B B C B D/ | split | locate /B/ 1 after /---/ | cons"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: C:\>pipe “< myfile.txt | locate 20 | nlocate 21 | console” |
|
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: C:\>pipe “< myfile.txt | strip | locate | > myfile.txt” |
|
8) |
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.. |
|
9) |
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 |
|
10) |
LOCATE verifies
that its secondary input stream is not connected and then begins execution. |
|
Examples |
|
1) |
C:\pipe “literal /a-b-c/ | literal /d-e-f/ | locate wordsep /-/ w3 /c/ | console”
a-b-c |
|
2) |
C:\pipe “literal /a?b?/ | literal /e??f/ | locate fieldsep /?/ f2-3 /f/ | console”
e??f |
|
3) |
C:\pipe “literal /?ab?c??a ab?c?a/ | split | locate (ws /?/ w1 w3) /a/ | console”?ab?c??a
ab?c?a |
|
4) |
C:\pipe “literal /afbc adef ghfi fjkl/ | split | locate -2;-1 /f/ | console”adef ghfi |
|
5) |
C:\pipe “literal /12 1.23e5 -9.5 150000.00/ | split | locate >= 123000 | console”1.23e5150000.00 |