Purpose, Argument, Streams, Usage, Examples, Related

>>──stage──ZONE(─┬────────────┬──┬───────┬──┬─────────┬─)──┬──────────┬──────────────>< 
                 └─inputrange─┘  └─CASEI─┘  └─REVerse─┘    └─operands─┘

Use the ZONE pre-process function to alter the input records read by the stage from any of its input streams. The ZONE function operates on the input records before they are presented to the stage.

There are a number of stages that permit the use of the ZONE function and these are stages that do not perform any translation of their input records. They are purely filter type stages that simply select input records based on some criteria.

The ZONE function instructs the manager to extract a substring of the record, determined by the column, word or field range, and optionally; to translate both the stage operands and the content of the input records to uppercase, and present this altered record to the stage when a read-record is requested. The ZONE function does not alter the way in which a stage processes its input and output records, it only alters the format of the record which is presented to the stage. When the stage performs a subsequent write-record request, the manager writes the original unmodified input record to the specified output stream.

• stage
  is the name of a stage that reads records from any connected input stream and writes them to any connected output stream. A stage that supports the CASEI function does not delay the records.
  
  
• inputrange
  is an integer column, word or field range on which to operate.
  
  
• CASEI
  Perform a non-case-sensitive selection comparison.
  
  
• REVerse
  reverses an input record before it is presented to the stage. If you specify an inputrange operand, only the characters in the specified range are reversed.
  
  
• operands
  The stage command argument.

• ZONE does not read or write any input or output stream records.
  

1. You cannot specify the ZONE preprocess function with a stage that does not support it.
   
   
2. A stage that supports the ZONE preprocess function does not delay the records.
   
   
3. The CASEI operand translates input records to uppercase before they are presented to the stage. As such, if the stage searches for a hexadecimal or binary representation of a lowercase character; the stage will not find the character because the input record has already be translated to uppercase, as in the following example:
   
   

   **** Top of file ****
   Address Rxpipe
   
    'pipe literal /aBbCc def ghi/',
        '| split',
        '| between zone( 3-* casei3-* ) x62 /b/',
        '| console'
   
   Exit 0
   **** End of file ****
   

   
   The lowercase b (x'62') in the literal string is not found because it was translated to an uppercase B before BETWEEN processed its input record. Similarly, if the stage specifies a word or field range with a word or field separator string in hexadecimal or binary format, then the extracted range may not be as expected as the record presented to the stage will have been translated to uppercase.
   

1. In the following example, the pipeline specifies only word number 2 as the input location:
   
   

   **** Top of file ****
   Address Rxpipe
   
   'pipe literal /a-B-c c-b-A/',
       '| split',
       '| fromlabel casei( zone wordsep /-/ w2 ) /b/',
       '| console'
   
   Exit 0
   **** End of file ****
   

   
   

   output:
   
   a-B-c
   c-b-A
   

   
   
2. The following pipeline specifies the third-from-last to the second-from-last columns as the input location:
   
   

   **** Top of file ****
   Address Rxpipe
   
   'pipe literal /ABCDE FGHIJ/',
       '| split',
       '| tolabel casei( zone -3;-2 ) /hi/',
       '| console'
   
   Exit 0
   **** End of file ****
   

   
   

   output:
   
   ABCDE
   

   
   
3. The following pipeline example reads the file: input.txt and selects records from (and including) one that ends in two hyphens up to (and including) one that ends in a full-stop (period), and writes its output to the file: output.txt.
   
   

   'pipe < input.txt | between zone(-2;-1 reverse) /--/ /./ | > output.txt'
   

   
   When the last character in a record is a full-stop (period), ZONE reverses the period and the character preceding it so BETWEEN can then find the records that begin with a period.

BETWEEN, CASEI, FROMLABEL, INSIDE, LOCATE, NOTLOCATE, OUTSIDE, TOLABEL, ZONE