LOCATE stage v1.2

Pipelines v2.0

 

Purpose, Operands, Streams used, Usage notes, Examples, See also

Home

 

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.

 

    

inputrange

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.

 

 

string

is a string to locate.

 

    

< 

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.

 

 

value

is a floating-point double-precision number.

 

    

count

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.

 

    

sepstring

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 Rxpipe
02
03 ‘pipe lit /A B B C B D/’,
04    ‘| split’,
05    ‘| locate /B/ 1 after /---/’,
06    ‘| cons
07
08 Exit 0
**** End of file ****
 
Output:
B
B
---
B
D
---
 

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 Rxpipe
02
03 ‘pipe < myfile.txt | locate 20 | nlocate 21 | console’
04
05 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 Rxpipe
02
03 ‘pipe < myfile.txt | strip | locate | > myfile.txt’
04
05 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 Rxpipe
02
03 ‘pipe lit /12345 12T45/’,
04      ‘| split’,
05      ‘| locate reg /^[0-9]+$/’,
06      ‘| cons’
07
08 Parse pull
09 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 Rxpipe
02
03 ‘pipe literal /a-b-c/ | literal /d-e-f/ | locate wordsep /-/ w3 /c/ | console
04
05 Exit 0
**** End of file ****
 
Output:

a-b-c

 

     2)

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /a?b?/ | literal /e??f/ | locate fieldsep /?/ f2-3 /f/ | console’
04
05 Exit 0
**** End of file ****
 
Output:

e??f

 

     3)

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /?ab?c??a ab?c?a/ | split | locate (ws /?/ w1 w3) /a/ | console’
04
05 Exit 0
**** End of file ****
 
Output:
?ab?c??a

ab?c?a

 

     4)

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /afbc adef ghfi fjkl/ | split | locate -2;-1 /f/ | console’
04
05 Exit 0
**** End of file ****
 
Output:
adef

ghfi

 

     5)

**** Top of file ****
01 Address Rxpipe
02
03 ‘pipe literal /12 1.23e5 -9.5 150000.00/ | split | locate >= 123000 | console’
04
05 Exit 0
**** End of file ****
 
Output:
1.23e5
150000.00
 

See also

 

Reference the following link for additional information:

 

NLOCATE

 

History of change

 

Version

Action

Description

 

 

 

1.1

Added

Support for the REGEXP operand; which specifies that the string operand is interpreted as a regular expression.

1.2

Added

Support for the numeric comparison operators: <, <=, ==, !=, >= and >.