NOTLOCATE stage v1.3

Pipelines v2.1

 

Purpose, Operands, Streams, Usage, Examples, Related

Home

 

Syntax

 

                                ┌─1-*────────────────┐
>>───NOTLOCate──────────────┼────────────────────┼──┤ Set ├───────────────────────><
    └─NLOCate───┘  └─ANYCase─┘  inputrange─────────
                                   ┌─<──────────┐   
                                ─(inputrange─)─┘
 
Set:
 
──────────────────────────────────────────────────────────────────────────────────
   STRing──string          ┌─BOTH───┐                

   REGexp──          └─count──┼────────┼──────────────┘

   PATtern                   BEFORE  └─sepstring─┘
   ANYof───┘                   └─AFTER──┘
   <───────value──┘
   <=──────
   ==──────
   !=──────
   >=──────
   └─>───────┘
 
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 NOTLOCATE stage to select records that do not contain a specified target string of characters. NOTLOCATE writes primary input stream records that do not contain the specified string to its primary output stream. If its secondary output stream is connected; NOTLOCATE writes the unselected input records to its secondary output stream; otherwise they are discarded.

 

NOTLOCATE searches for the string within one or more locations of the input record. If you do not specify an inputrange, NOTLOCATE searches the entire input record. When a single inputrange location is specified, and you do not specify the string operand or you specify a null string; NOTLOCATE writes to its primary output stream only input records of length inputrange –1 or less.

 

In addition, NOTLOCATE 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 NOTLOCATE 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

 

The following streams are used by the NOTLOCATE stage:

 

Stream

 

Action

 

 

Primary input stream

NOTLOCATE reads records from its primary input stream.

Primary output stream

NOTLOCATE writes the records which are not selected to its primary output stream.

Secondary output stream

If it is connected, NOTLOCATE writes the records which are selected to its secondary output stream.

 

Usage

 

1.

NOTLOCATE without the count operand does not delay the records. NOTLOCATE used with the count and BOTH or BEFORE operands; delays every count number of records.

 

2.

If the NOTLOCATE stage discovers that its primary input stream is not connected, the NOTLOCATE 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:

 

notlocate /5/
 

is not equivalent to

 

notlocate (5(
 

The first NOTLOCATE 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 NOTLOCATE 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 ****
 1 Address Rxpipe
 2
 3 'pipe < myfile.txt',
 4    '| notlocate 21',
 5    '| locate 20',
 6    '| console'
 7
 8 Exit 0
   **** End of file ****
 

6.

To select only null records, use NOTLOCATE as so:

 

... | nlocate 1 | ...
 

7.

If you specify the count operand; NOTLOCATE will always finish selecting a Set of records before it begins searching for a new occurrence of the target string, for example:

 

'pipe lit /A B B C B D/ | split | notlocate /B/ 1 after /---/ | cons'
 
output:
A
C

 

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, NOTLOCATE selects the specified number of records before searching for the next target record.

 

8.

NOTLOCATE verifies that its secondary input stream is not connected and then begins execution.

 

Examples

 

1.

'pipe literal /a-b-c/ | literal /d-e-f/ | notlocate wordsep /-/ w3 /c/ | console'
 
output:

d-e-f

 

2.

'pipe literal /a?b?/ | literal /e??f/ | notlocate fieldsep /?/ f2-3 /f/ | console'
 
output:

a?b?

 

3.

'pipe literal /?a?c?f a??c?e/ | split | notlocate (ws /?/ word 3) /e/ | console'
 
output:

?a?c?f

 

4.

'pipe literal /afbc adef ghfi fjkl/ | split | notlocate -2;-1 /f/ | console'
 
output:
afbc

fjkl

 

5.

In this example, the NOTLOCATE stage selects only those records for students who did not received a grade of 100 on exam 2 or exam 3.

 

studentgrades.txt (input)

 

...|...+....1....+....2....+....3....+....4....+....5....+....

   **** Top of file ****

 1 STUDENT           EXAM 1    EXAM 2    EXAM 3    EXAM 4

 2

 3 CAROLYN             78        87       100        95

 4 EVELYN              85        84        82        89

 5 JACK               100        89        89       100

 6 KEN                 88        79        79        93

 7 KAREN               90       100       100        95

 8 MICHAEL             87       100        99       100

   **** End of file ****

 

The following pipeline inspects the entries for exam 2 and exam 3 only.

 

'pipe < studentgrades.txt | locate (30-32 40-42) /100/ | console'

 
The resulting console output is shown below.
 
output:

CAROLYN             78        87       100        95

EVELYN              85        84        82        89

KEN                 88        79        79        93

KAREN               90       100       100        95

 

The same result can also be achieved by utilising the WORD (WORDSEPARATOR) capabilities of the inputrange specification:

 

'pipe < studentgrades.txt | Notlocate (w3 w4) /100/ | console

 

6.

To find all records in the file: fruit.txt that do not contain the character string apple anywhere within the last 10 characters of the record.

 

fruit.txt (input)

 

...|...+....1....+....2....+....3....+....4....5....

   **** Top of file ****

 1 Blueberry Strawberry Raspberry

 2 Pear Apple

 3 Peach Nectarine Plum

 4 Orange Tangerine

 5 Watermelon Cantaloupe Honeydew

 6 Pineapple

   **** End of file ****

 

'pipe < fruit.txt | (anycase) notlocate -10;-1 /apple/ | console'

 

output:

Blueberry Strawberry Raspberry

Peach Nectarine Plum

Orange Tangerine

Watermelon Cantaloupe Honeydew

 

Related

 

LOCATE

 

History

 

Version

 

Date

Action

Description

Pipelines

1.3

??.??.2025

changed

Application-wide rewrite.

2.1

1.2

04.02.2012

added

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

2.0

1.1

09.05.2010

added

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

1.7

1.0

06.09.2007

created

First version.

1.0