Purpose, Operands, Streams, Usage, Examples, Related

(1)                          ┌─FROM─1─┐
>>──STEM──name.──┬────────┬──┼────────┼───────────────────────────────────────────>< 
                 └─BUFFer─┘  └─FROM─n─┘

(2)                          ┌─FROM─1─┐
>>──STEM──name.──────────────┼────────┼──┬────────┬──┬──────┬─────────────────────>< 
                             └─FROM─n─┘  └─APPend─┘  └─KEEP─┘
Notes:
(1) When STEM is specified as the first stage of a pipeline.
(2) When specified in any other position.

Use the STEM stage to (1) retrieve, or (2) set, an ooRexx compound variable whose name begins with the stem you specify.

The stem name of an ooRexx variable is that part of a variable name up to and including the last period, for example; pipe.var. is the stem of the ooRexx variables pipe.var.1, pipe.var.2, and pipe.var.3.

When STEM is the first stage of a pipeline, STEM retrieves variables. Before STEM can be used to retrieve variables, variable name.0 must contain the number of variables whose value you want to retrieve. The value should be 0 or a positive integer.

For each variable retrieved, STEM writes a separate record containing the variable's value to its primary output stream. By default, output records are written beginning with name.1, followed by name.2, name.3 and so on until the number of records written equals the value of name.0.

Without specifying additional stage command operands; the output records are written in ascending order of the numeric suffix of the variables until the number of records written equals the size of the stem. When STEM is not the first stage of a pipeline, STEM sets variables. By default, when STEM is used to set variables, it sets one variable for each record in its primary input stream. Variables name.1 through name.n, where n is the number of records in the primary input stream, are set to the contents of the first through the nth input stream record, respectively. After n records have been set, STEM sets the variable name.0 to the number of variables that were set.

• name
  is the name of the stem whose values you want to set or retrieve. The name of the stem is that part up to and including the last period.


• BUFFer
  specifies that STEM will read the entire stem into a buffer before writing any records to its primary output stream. This option, for a small to medium sized stem, provides a fast and efficient option. However, for a large stem, caching the entire stem will impact on the amount of storage required.


• FROM n
  when STEM is the first stage in a pipeline; the list of variables to be retrieved begins with name.n; where n is the stem element index. When retrieving a variable, n should be a positive integer. When STEM is not the first stage in a pipeline; the variables to be set begin with the nth primary input stream record. STEM sets variable name.0 to the numeric suffix of the last variable that was set.


• APPend
  specifies that variables are to be set beginning with index (name.0 + 1), where name.0 is the current size of the stem. Variable name.0 must contain a zero or positive whole number prior to invoking the STEM stage with the APPEND operand. After all variables have been set, STEM sets variable name.0 to the numeric suffix of the last variable that was set.


• KEEP
  specifies that if STEM does not write any new values to the stem, and the stem already exists, then it remains unchanged. Otherwise the stem is destroyed; the stem is dropped from the ooRexx variable pool.

1. Without the BUFFER operand; STEM does not delay the records. With the BUFFER operand; STEM delays the records until end-of-file is reached on its primary input stream.
2. If the STEM stage discovers that both its primary input and primary output streams are not connected, the STEM stage ends.
3. When STEM is not the first stage in a pipeline and the stage specifies a new output stem name; Pipelines cannot determine if that name will register as a valid ooRexx variable until the pipeline updates the ooRexx variable pool. As update to the variable pool occurs immediately prior to returning control from that pipeline; and invalid variable name will only be identified and signalled at that point.
4. STEM verifies that it has either a primary input stream and/or a primary output stream connected and then begins execution.
< cr>

1. The following example shows you how to specify the STEM stage in both the input and output position.

   **** Top of file ****
   Address Rxpipe
   
   banana.0 = 4
   banana.1 = "Lady Finger"
   banana.2 = "Cavendish"
   banana.3 = "Williams"
   banana.4 = "Candy Apple"
   
   'pipe stem banana. | sort | stem bunch.'
   
   Do n = 1 to bunch.0
      Say bunch.n
   End
   
   Exit 0
   **** End of file ****
   

   output:
   
   Candy Apple
   Cavendish
   Lady Finger
   Williams
   

2. STEM allows you to specify a starting index. In the following example; the STEM stage begins writing records to its primary output stream, starting with entry var.3.

   **** Top of file ****
   Address Rxpipe
   
   line.0 = 4
   line.1 = "I won't pass this line on"
   line.2 = "Or this one either"
   line.3 = "This is the first line that I want.."
   line.4 = "..followed by this one!"
   
   'pipe stem line. from 3 | console' 
   
   Exit 0
   **** End of file ****
   

   output:
   
   This is the first line that I want..
   ..followed by this one!
   

3. STEM can append new entries to an existing stem. In the following example; the STEM stage appends two new entries to the brand stem.

   **** Top of file ****
   Address Rxpipe
   
   brand.0 = 3
   brand.1 = "Gretsch"
   brand.2 = "Hofner"
   brand.3 = "Gibson"
   
   'pipe literal /Fender Peavey/',
       '| split',
       '| stem brand. append'
   
   Do i = 1 to brand.0
      Say brand.i
   End
   
   Exit 0
   **** End of file ****
   

   output:
   
   Gretsch
   Hofner
   Gibson
   Fender
   Peavey
   

ARRAY, VARIABLE