Functions and Directives

Function ComEvalCollection() Foundation

Evaluate a collection of COM/ActiveX objects

ComEvalCollection( <oComCollection>, <bCodeblock> ) --> nElem
<oComCollection> is an instance of AutomationObject which is associated with a COM/ActiveX collection.
The code block <bCodeblock> gets evaluated for each element in the collection.

The function ComEvalCollection returns the number of elements in the collection as numeric value.


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 

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.

Enumerate all services installed
#pragma library( "ascom10.lib" ) 

LOCAL oWmiLocator, oWmiServices, oWmiInstances 
LOCAL bCollBlock 

// Access the services collection 
oWmiLocator   := GetObject( ,"WbemScripting.SWbemLocator" ) 
oWmiServices  := oWmiLocator:ConnectServer( "Localhost", "Root\CIMv2" ) 
oWmiInstances := oWmiServices:InstancesOf( "Win32_Service" ) 

// For illustration display the type of COM/ActiveX components 
// we are working with 
? oWmiLocator,  oWmiLocator:interfaceName 
? oWmiServices, oWmiServices:interfaceName 
? oWmiInstances, oWmiInstances:interfaceName, oWmiInstances:Count 

// Process all elements from oWmiInstance using the function 
// ComEvalCollection() and a code block 
bCollBlock := { |oService, n| Qout(n,                                      ; 
                                   PADR(oService:name,        30, " " ),   ; 
                                   PADR(oService:Status,       5, " " ),   ; 
                                   PADR(oService:ServiceType, 20, " " ) )} 
ComEvalCollection( oWmiInstances, bCollBlock ) 


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.