Function ComEvalCollection() Foundation

The function ComEvalCollection() is used for iterating the elements of a COM/ActiveX collection. For each element within that collection the code block <bCodeblock> gets evaluated where the code block receives the collection element as first parameter. The index position of the collection's element is the second parameter of the code block.

COM/ActiveX components are often organized in so-called Collections. These Collections often offer interfaces (IVARs and methods)in order to access their elements.

Collections can be regarded similarly to an Xbase++ array. For Xbase++ arrays the function Len() and the index operator ([ ]) can be used to manipulate each individual element in the array.

Collections often possess the IVAR :Count and the method :Items(). Then the FOR program loop, :Countand :Items() can be used to iterate the elements in a Collection. This is illustrated in the following example:

// The Microsoft Excel Range collection provides the IVar :Count 
// and the method :Item() for accessing elements within a collection, 
// thus the collection can be iterated using a FOR loop. 
oRange := oSheet:Range( "A1:C5" ) 
nLen := oRange:Count 
FOR n := 1 TO nLen 
  oElem := oRange:Item(1) 
  //... do something with oElem 
NEXT 

In some instances methods and IVARs miss to a Collection to access individual elements. In these cases the function ComEvalCollection() has to be used. ComEvalCollection()is to that extent similar to the function AEval(). With AEval() a code block is executed for each element in the Xbase++ array. With ComEvalCollection() a code block is executed for each element in the COM/ActiveX Collection. Thus one can formulate above code example also as follows:

oRange := oSheet:Range( "A1:C5" ) 
bBlock := { |oElem, n| /*... oElem benutzen*/ } 
ComEvalCollection( oRange, bBlock ) 

Collections, which the Windows management instrumentation (WMI) comes of, are examples of such Collections, which possess neither IVARs nor methods, in order to access individual elements. Therefore the FOR loop cannot be used for iterating the elements. In these cases the function ComEvalCollection() is used, as shown in the following example.