COMAdminCatalogObject class

Represents items in collections in the COM+ catalog. Use it to retrieve and modify properties exposed by an item in a collection.

When to implement

This class is implemented by COM+.

When to use

Use objects created from the COMAdminCatalogObject class to modify the properties of items contained in collections in the COM+ catalog. These items correspond to items shown inside folders in the console tree of the Component Services administration tool. Folders in the Component Services administration tool correspond to collections in the catalog, which you can represent by using objects created from the COMAdminCatalogCollection class.

Not all of the collections and items exposed through COMAdminCatalogCollection and COMAdminCatalogObject are available in the Component Services administration tool.

For information regarding specific collections and their properties, see COM+ Administration Collections.

For an introduction to programmatic administration of COM+, see Automating COM+ Administration.

Remarks

You cannot directly create a COMAdminCatalogObject object. To use the methods this object, you must create a COMAdminCatalog object, obtain a reference to ICOMAdminCatalog, and then use ICOMAdminCatalog::GetCollection to get a reference to an ICatalogCollection interface that represents a top-level collection or use ICatalogCollection::GetCollection to access collections that are not top-level.

After you have a reference to the ICatalogCollection interface of the collection in which you are interested, call ICatalogCollection::Populate to populate the collection with all of its items. Iterate through each of the items in the collection by calling ICatalogCollection::get_Item to get a reference to each ICatalogObject interface. When you find the item of interest, you can modify the item's properties and exit the iteration. If you make any changes to any items in a collection, you must call ICatalogCollection::SaveChanges to save the changes to the COM+ catalog.

This is shown in the following example, where "TopCollection" must be replaced by the name of one of the top-level COM+ administration collections; "ItemName" must be replaced by the name of the item that you are interested in; "PropertyName" must be replaced by the name of the property that you are modifying in the item; and varNewProp must be replaced by a VARIANT that contains the new value for the property.

// Convert ItemName to a BSTR.
bstrItemName = SysAllocString(L"ItemName");
HRESULT hr = CoCreateInstance(CLSID_COMAdminCatalog, NULL, 
  CLSCTX_INPROC_SERVER, IID_IUnknown, (void**)&pUnknown);
if (FAILED(hr)) exit(0);  // Replace with specific error handling.
hr = pUnknown->QueryInterface(IID_ICOMAdminCatalog, 
  (void**)&pCatalog); 
if (FAILED(hr)) exit(0);  // Replace with specific error handling.
hr = pCatalog->GetCollection(L"TopCollection", 
  (IDispatch**)&pTopColl);
if (FAILED(hr)) exit(0);  // Replace with specific error handling.
// Populate the TopCollection collection.
hr = pTopColl->Populate();
if (FAILED(hr)) exit(0);  // Replace with specific error handling.
// Get the number of items in the collection.
hr = pTopColl->get_Count(&lCount);
if (FAILED(hr)) exit(0);  // Replace with specific error handling.
VARIANT varName;
VariantInit(&varName);
// Iterate through each item in the collection.
for (LONG lIdx = 0; lIdx < lCount; lIdx++) {
    hr = pTopColl->get_Item(lIdx, (IDispatch**)&pItem);
    if (FAILED(hr)) exit(0);  // Replace with specific error handling.
    hr = pItem->get_Name(&varName);
    if (FAILED(hr)) exit(0);  // Replace with specific error handling.
    // Compare the item name to bstrItemName.
    hr = VarBstrCmp(varName.bstrVal, bstrItemName, 1024L, NULL);
    if (FAILED(hr)) exit(0);  // Replace with specific error handling.
    if (VARCMP_EQ == hr) {  // The strings are equal.
        // Use the put_Value method to modify properties of the item.
        hr = pItem->put_Value(L"PropertyName", varNewProp);
        if (FAILED(hr)) exit(0);  // Replace with specific error handling.
        break;  // Exit the iteration.
    }
}
hr = pTopColl->SaveChanges(&lNum);
if (FAILED(hr)) exit(0);  // Replace with specific error handling.
SysFreeString(bstrItemName);

To use this class from Microsoft Visual Basic, add a reference to the COM+ Admin Type Library. A COMAdminCatalogCollection object can be created by calling GetCollection on a COMAdminCatalog or COMAdminCatalogCollection object.

Call the Populate method of the COMAdminCatalogCollection object to populate the collection with all of its items. Iterate through each of the items in the collection. When you find the item of interest, you can modify the item's properties and exit the iteration. If you make any changes to any items in a collection, you must call the SaveChanges method of the COMAdminCatalogCollection object to save the changes to the COM+ catalog.

This is shown in the following example, where "TopCollection" must be replaced by the name of one of the top-level COM+ administration collections; "ItemName" must be replaced by the name of the item that you are interested in; "PropertyName" must be replaced by the name of the property that you are modifying in the item; and NewPropValue must be replaced by the new value for the property.

Dim objCatalog As COMAdmin.COMAdminCatalog
Set objCatalog = CreateObject("COMAdmin.COMAdminCatalog")
Dim objTopCollection As COMAdmin.COMAdminCatalogCollection
Set objTopCollection = objCatalog.GetCollection("TopCollection")
objTopCollection.Populate
Dim objItem As COMAdmin.COMAdminCatalogObject
For Each objItem in objTopCollection
    If objItem.Name = "ItemName" Then
        objItem.Value("PropertyName") = NewPropValue
        Exit For
    End If
Next
objAppCollection.SaveChanges

Requirements

See also

COMAdminCatalog

COMAdminCatalogCollection

ICatalogObject