Purpose, Argument, Streams, Usage, Examples, Related

                             ┌─STRing──┐              ┌─STRing──┐
>>──BETWEEN──┬────────────┬──┼─────────┼──fromstring──┼─────────┼──┬─tostring─┬──────>< 
             ├─CASEI(...)─┤  ├─REGexp──┤              ├─REGexp──┤  └─numrecs──┘
             └─ZONE(...)──┘  ├─PATtern─┤              ├─PATtern─┤
                             └─ANYof───┘              └─ANYof───┘

Use the BETWEEN stage to select groups of records from its primary input stream, starting with the first record that begins with the specified string fromstring. BETWEEN writes a group of records to its primary output stream, ending a group with the record that has the second specified string tostring, or with all remaining records once the specified number of records numrecs is reached.

Unless the CASEI or ZONE pre-process keyword specifies a different column range, both fromstring and tostring must begin in the first column of an input record. If the secondary output stream is connected; BETWEEN writes the records not selected to its secondary output stream. If the secondary output stream is not connected, BETWEEN discards these records.

• CASEI
  perform a non-case-sensitive comparison between the strings and an input record.
  
  
• ZONE
  restrict data selection to a specific column, word or field range.
  
  
• STRing
  specifies that the string operand is a literal string of characters to locate. A null string matches a null record.
  
  
• 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.
  
  
  • fromstring
    is the starting string to locate.
    
    
  • tostring
    is the ending string to locate. If tostring is specified and it consists of only decimal numbers (0-9), you cannot specify a number as the delimiting character.
    
    You cannot use a B, b, H, h, X or x for a delimiting character.
    
    
• numrecs
  is an unsigned integer which specifies the number of records to be written to the primary output stream; starting with and including the record that begins with fromstring. BETWEEN writes numrecs records each time fromstring is located. numrecs cannot be less than 2. If the number of records remaining in the input stream is less than numrecs, the remaining records are written to the primary output stream.
  

1. BETWEEN does not delay the records.
   
   
2. If the BETWEEN stage discovers that all of its output streams are not connected, the BETWEEN stage ends.
   
   
3. If tostring is specified and it consists of only decimal numbers (0-9), you cannot specify a number as the delimiting character. For example,
   
   

   between /b/ /7/
   

   
   is not equivalent to:
   
   

   between 1b1 171
   

   
   The first BETWEEN stage selects records between a record beginning with b and a record beginning with 7. The second stage selects a group of records that includes a record beginning with b and the next 170 records. That is, 171 is processed as numrecs rather than as a delimited string.
   
   
4. If the input stream does not contain a record that begins with tostring, BETWEEN writes all the records in its input stream to its primary output stream, starting with the record that begins with fromstring. For example, after issuing the following pipe command:
   
   

   'pipe < abc.txt | between /ccc/ /rrr/ | console'
   

   
   the contents of the primary input stream (which is the data from the file: abc.txt), the primary output stream, and the secondary output stream are:
5. If multiple sets of the strings are found, BETWEEN will complete the first group before writing the second group. For example, if you specify the starting and ending strings and a second occurrence of fromstring is found before tostring, BETWEEN writes the records that are between (and including) the first occurrence of the starting and ending strings to its primary output stream. This also includes the second record that begins with fromstring.
   
   For example, after issuing the following pipe command:
   
   

   'pipe < abc.txt' | between /aaa/ /ccc/ | console'
   

   
   the contents of the primary input stream (which is the data from the file: abc.txt), the primary output stream, and the secondary output stream are: Similarly, if you specify fromstring and numrecs and a second occurrence of fromstring is found within the selected group of records, BETWEEN writes numrecs records starting with fromstring including the record that begins with the second occurrence of fromstring to its primary output stream.
   
   For example, after issuing the following pipe command:
   
   

   'pipe < abc.txt' | between /aaa/ 4 | console'
   

   
   the contents of the primary input stream (which is the data from the file: abc.txt), the primary output stream, and the secondary output stream are:
   
6. If you specify the ZONE pre-process option of the BETWEEN stage, each string must begin in the first column of the specified column range instead of the first column of the input record. To be selected, each string must be completely located within the column range; therefore, the length of the string must be less than or equal to the width of the column range.
   
   
7. BETWEEN verifies that its secondary input stream is not connected and then begins execution.

1. 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.

CASEI, INSIDE, FROMLABEL, OUTSIDE, TOLABEL