Browsing TwinCAT configuration

In a separate article, we have already shown you how to access TwinCAT via the Visual Studio Automation Model. This reference to TwinCAT is being represented by an object of type ITcSysManager. From this point on we would like to discuss now how you can navigate through the TwinCAT configuration.

General information

It is important to understand that all information in TwinCAT is ordered in a tree-like structure. In Automation Interface, every tree node, and therefore every element of a TwinCAT configuration, is represented by the interface ITcSmTreeItem.

Navigating the TwinCAT data model can be done in different ways, depending on the sort of information that should be retrieved.

Lookup-Methods are searching for specific tree items via specified search criterias, e.g. the path to a tree item
Iterators or browsing functions iterate over a set of retrieved tree items

Both methods are now being discussed in the following article.

LookupMethods

The Lookup methods are always working on the whole data model (unfiltered).

ITcSysManager::LookupTreeItem determines a tree item with the specified absolute path name.
ITcSysManager3::LookupTreeItemById determines a tree item with the specified item type and item Id.
ITcSmTreeItem::LookupChild determines a tree item within a subtree specified by a relative path name.

Each tree item in TwinCAT can be identified by its unique pathname. The pathname of a tree item is based on the hierarchical order of its parent item (its name) and its own name, separated by circumflex accents ('^'). To shorten the pathnames and to avoid language dependencies, the top level tree items have special abbreviations which are listed in ITcSysManager::LookupTreeItem.

Iterators

Now, three different types of iteration functions are supported:

Browsing all tree items (unfiltered)
Browsing main tree items
Browsing variables / symbols only

Browsing all tree items (unfiltered)

To browse all tree items in an unfiltered way, the property ITcSmTreeItem::_NewEnum may be used. _NewEnum iterates over all subnodes of the currently referenced ITcSmTreeItem. This (COM-) property is used by many Programming and Script languages that support the COM Enumerator model (e.g. .NET languages, VB6 or script languages) by a 'foreach' statement. For non-supporting languages like C++ the foreach loop must be implemented manually by using the IEnumVariant interface.

We recommend to use this way to iterate through child nodes.

Sample (C#):

 ITcSmTreeItem parent = sysMan.LookupTreeItem("TIID^Device1^EK1100");
foreach(ITcSmTreeItem child in parent)
{
  Console.WriteLine(child.Name);
}

Sample (C++):

 ...
#import "C:\TwinCAT3\Components\Base\TCatSysManager.tlb" // Imports the System Manager / XAE Base Type library
// Usage of automatically generated Auto-Pointers (see MSDN documentation of #import statement)
...

void CSysManDialog::IterateCollection(TCatSysManagerLib::ITcSmTreeItemPtr parentPtr)
{
     IEnumVARIANTPtr spEnum = parentPtr->_NewEnum;
     ULONG nReturned = 0;
     VARIANT variant[1] = {0};
     HRESULT hr = E_UNEXPECTED;
          
     do
     {
          hr = spEnum->Next(1, &variant[0], &nReturned);
          if(FAILED(hr))
               break;
          for(ULONG i = 0; i < nReturned; ++i)
          {
               IDispatchPtr dispatchPtr;
               IDispatch* pDispatch;
               TCatSysManagerLib::ITcSmTreeItemPtr childPtr;
               HRESULT hr;
               if(variant[0].vt == VT_DISPATCH)
               {
                    TCatSysManagerLib::ITcSmTreeItem* pChild = 0;
                    dispatchPtr.Attach((variant[0].pdispVal));
                    hr = dispatchPtr.QueryInterface(__uuidof(TCatSysManagerLib::ITcSmTreeItem), reinterpret_cast(&pChild));
                    childPtr.Attach(pChild);
                    _bstr_t strName = pChild->GetName();
               }
          }
     } 
     while(hr != S_FALSE); // S_FALSE indicates end of collection
}

Sample (IronPython):

parent = systemManager.LookupTreeItem("TIRC");
for child in parent : print child.Name

Sample (PowerShell):

$systemItem = $systemManager.LookupTreeItem("TIRC")
foreach($child in $systemItem)
{ 
    write-host$child.Name
}

Browsing Main Tree Items (Filtered)

For browsing only the main childs of the current tree item use the ITcSmTreeItem::ChildCount and ITcSmTreeItem:Child(n) pair of properties. These methods only work on the direct childs (non-recursive).

Browsing Variables / Symbols only

To Browse the Variables / Symbols use the ITcSmTreeItem::VarCount(x) , ITcSmTreeItem::Var(x,n) pair of properties. A selection of the variable type (input variables or output variables) can be done by parameter.