|
LOCATE stage v1.1 |
Pipelines v1.6 |
|
Purpose, Operands, Streams used, Usage notes, Examples, See also |
|
Syntax |
_1-*_________________ >>__LOCate__ _________ __|_____________________|__ __________________ __ _____ ________><
|_ANYCase_| |_inputrange__________| |_STRing__ | | Set | | <____________ | |_________|_string_| |_(__inputrange__|__)_| |_REGexp__| |_PATtern_| |_ANYof___|Set: _BOTH___|__count__|________|__ ___________ _____________________________________________________| |_BEFORE_| |_sepstring_| |_AFTER__|
Notes:(1) If you specify ANYCASE, multiple inputrange operands or any of the string operand keywords; 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. |
||
|
|
|
||
|
● |
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) |
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 |