GwConnects()

Edit online

The GwConnects(); rule retrieves a list of entities directly connected to a specified entity. This data is retrieved from the NCIM cache table, ncimCache.connects. A limitation on this rule is that it does not retrieve connections to contained entities. For example, if the entity passed to the rule represents a chassis, connections to interfaces within that chassis will not be returned.

Syntax

The GwConnects(); statement uses following syntax.

GwConnects ( entityId or entityName, [optional topology name] );

Arguments

The following table lists the properties of the arguments of this stitcher rule.

Table 1. Arguments of GwConnects()
Argument	Description	Accepts constants	Accepts variables	Accepts eval clauses
`entityId` or `entityName`	Instructs the rule to return entities connected to this entity.	Yes	Yes	Yes
`optional topology name`	Name of a topology as specified in the entityData table.	Yes	No	No

Example

The following example finds all connections to a specified entity and then prints out all of the results.

text entityName = eval( text, '&EntityName' ); 

# Find all connections to the given entityName...
RecordList connectedEntities = GwConnects( entityName );

# ...and iterate through the returned results
Record singleConnection;
foreach ( connectedEntities )
{
        singleConnection = GetInScopeRecord();
        PrintRecord( singleConnection );
}

Example

The following example finds all connections to a specified entity within a specific topology.

# Find all connections to the given entityName within a specific topology
RecordList specificConnectedEntities = NULL;
specificConnectedEntities = GwConnects( entityName, 'RouterLinksTopology' );

Returns

This rule returns a list of records. Each record contains information about a single connected entity, as contained in the ncimCache.connects table.

The following snippet shows an example of the results returned by this rule.

{
        TOPOENTITYNAME='RouterLinksTopology';
        UNIDIRECTIONAL=0;
        ENTITYNAME='freddy[ 0 [ 1 ] ]';
},
{
        TOPOENTITYNAME='RelatedToTopology';
        UNIDIRECTIONAL=0;
        ENTITYNAME='bob[ 0 [ 1 ] ]';
}