Functions and Directives

Function ComEvalCollection() Foundation

Evaluate a collection of COM/ActiveX objects

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

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

Description

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.

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

PROCEDURE main() 
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 ) 

wait 
RETURN 
Feedback

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.