BETWEEN stage v1.0

Pipelines v1.9

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

Home

Syntax

 
 _STRing__ _STRing__
>>__BETWEEN__ ____________ __|_________|__fromstring__|_________|__ _tostring_ ________><
 |_CASEI(...)_| |_REGexp__| |_REGexp__| |_numrecs__|
 |_ZONE(...)__| |_PATtern_| |_PATtern_|
 |_ANYof___|  |_ANYof___|
 

Purpose

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 is reached.

Unless the CASEI or ZONE pre-process option 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.

Operands

●

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 tostring are the starting string to locate fromstring and the ending string to locate tostring, respectively. 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.

Streams used

The following streams are used by the BETWEEN stage:

Stream	Action
Primary input stream	BETWEEN reads records from its primary input stream.
Primary output stream	BETWEEN writes to its primary output stream input records that begin with fromstring and all records up to and including the record that begins with tostring, or up to and including the record corresponding to the number specified by numrecs.
Secondary output stream	If its secondary output stream is connected, BETWEEN writes all input records not selected to its secondary output stream.

Usage notes

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 /a/ /7/ is not equivalent to between 1a1 171 The first BETWEEN stage selects records between a record beginning with a and a record beginning with 7. The second stage selects a group of records that includes a record beginning with a 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: C:\>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: C:\>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: C:\>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.

Examples

Changing records between labels

See also

Reference the following links for additional information:

CASEI, INSIDE, FROMLABEL, OUTSIDE, TOLABEL, ZONE