Purpose, Argument, Streams, Usage, Examples, Related

(1)                          ┌─FROM─1─┐
>>──ARRAY──name──┬────────┬──┼────────┼──────────────────────────────────────────────>< 
                 └─BUFfer─┘  └─FROM─n─┘

(2)                          ┌─FROM─1─┐
>>──ARRAY──name──────────────┼────────┼──┬────────┬──┬──────┬────────────────────────>< 
                             └─FROM─n─┘  └─APPend─┘  └─KEEP─┘

Notes:
(1) When ARRAY is specified as the first stage of a pipeline.
(2) When specified in any other position.

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

For each variable retrieved, ARRAY 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~items.

Without specifying additional stage command arguments; 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 array. When ARRAY is not the first stage of a pipeline, ARRAY sets variables. By default, when ARRAY 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.

• name
  is the name of the array whose values you want to set or retrieve.
  
  
• BUFfer
  specifies that ARRAY will read the entire array into a buffer before writing any records to its primary output stream. This option, for a small to medium sized array, provides a fast and efficient option. However, for a large array, caching the entire array will impact on the amount of storage required.
  
  
• FROM n
  when ARRAY is the first stage in a pipeline; the list of variables to be retrieved begins with name[n]; where n is the array element index. When retrieving a variable, n should be a positive integer. When ARRAY is not the first stage in a pipeline; the list of variables to be set begins with the nth primary input stream record.
  
  
• APPend
  specifies that variables are to be set beginning with index (name~items + 1), where name~items is the current size of the array.
  
  
• KEEP
  specifies that if ARRAY does not write any new values to the array, and the array already exists, then it remains unchanged. Otherwise the array is destroyed; the array is dropped from the ooRexx variable pool.

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

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

   **** Top of file ****
   Address Rxpipe
   
   banana = .array~of( "Lady Finger", "Cavendish", "Williams", "Candy Apple" ) 
   'pipe array banana | sort | array bunch'
   
   do n = 1 to bunch~items
      Say bunch[n]
   End
   
   Exit 0
   **** End of file ****
   

   
   

   output:
   
   Candy Apple
   Cavendish
   LadyFinger
   Williams
   

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

   **** Top of file ****
   Address Rxpipe
   
   line = .array~new(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 array line from 3 | console'
   
   Exit 0
   **** End of file ****
   

   
   

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

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

   **** Top of file ****
   Address Rxpipe
   
   brand = .array~new()
   brand~put('Gretsch', 1)
   brand~put('Hofner', 2)
   brand~put('Gibson', 3)
   
   'pipe literal /Fender Peavey/',
       '| split',
       '| array brand append'
   
   Do i = 1 to brand~items
       Say brand[i]
   End
   
   Exit 0
   **** End of file ****
   

   
   

   output:
   
   Gretsch
   Hofner
   Gibson
   Fender
   Peavey
   

STEM, VARIABLE