Updated May 2018
To access elements from a collection without knowing the specific keys, an "iterator" is used. Iterators are special variables which receive the value of the next element of a collection each time through the loop.
To iterate through a collection, a FOREACH loop is used:
foreach $$i in $aryname({startkey}) ! fwd iterator
print $$i ! print the element value
print .key($$i) ! print the element key
next $$i
foreach’reverse $$j in $aryname() ! reverse iterator
print $$j ! print the element value
print .key($$j) ! print the element key
next $$j
See Special ORDMAP Functions for a description of the .key() and other related functions.
The optional startkey may be any kind of expression that could appear on the right side of an assignment statement, i.e. a literal, a variable, a variable formatted with USING, a function call, etc. If the expression is numeric, the value is converted to string format (truncating a fractional value to integer). See History below for a revision to the startkey handling. Note that the startkey only applies to the forward iterator, and only has an effect if there is a exact match in the map. This is not like an ISAM lookup, where a failed initial key lookup will nevertheless affect the subsequent next operation.
Note: the above examples assume varstr elements; for varx elements, you wouldn’t try to print the $$i or $$j iterator values directly; instead you would assign them to a structure and then access the members, i.e.
Prodstruct = $$i ! copy iterator value to structure
print Prodstruct.field ! print a field of the element value
print .key($$j) ! print the element key
Although this is similar to a standard for/next loop, there are some noteworthy differences:
| • | First, unlike the standard for/next loop where the loop variable must have been previously defined, in the FOREACH loop, the iterator variable ($$i in the example above) is created on the fly and exists just for the duration of the loop. Iterator variables must all start with $$ (which should not be used for any other variable type.) Since it is destroyed at the end of the loop, the same iterator variable name can be used in other FOREACH loops. |
| • | Unlike the standard for/next loop, here there is no explicit ending value. The starting value is the first item in the collection (unless the optional startkey parameter is specified.) The concept is similar to sequencing through an indexed file until the end, except in this case if the specified startkey doesn’t exist, the entire sequence will be empty and the loop will be skipped.) To omit the startkey, use empty parens, e.g. $aryname(). |
| • | The order of the sequence will be according to the key. You can specify a reverse sequence by using the keyword foreach’reverse instead of FOREACH. Note however that for the reverse iterator, the startkey option is ignored; it always starts at the highest key in the collection. |
Subtopics
