PhysicalName::AncestorIndex

Returns the 0-based index of any parent or ancestor component of a physical name.

Syntax

template <typename TAncestor>
int AncestorIndex(ViSession Vi) const;

Parameters

Vi

[in] ViSession handle for the driver session.

Return value

The 0-based index of an ancestor repeated capability instance. If the physical name is not defined for the repeated capability associated with the PhysicalName object, then this function returns -1.

Remarks

Important

This function is only available for PhysicalName instances that are associated with a nested repeated capability. Attempting to access this function from a non-nested PhysicalName instance will produce a compile error.

Example

The following example demonstrates use of the AncestorIndex function.

ViStatus _VI_FUNC acme4321_ConfigureArmCount(ViSession Vi, ViConstString RepCapIdentifier, ViInt32 ArmCount)
{
    // The Trace repeated capability is a child repeated capability of a Channel repeated capability
    // that defines a "C1" physical name.  The "trace" variable below represents the "T1" Trace instance
    // within the C1 instance of the parent repeated capability.
    //
    // Assume the following repeated capability physical names are defined in the following order for the Trace repeated capability:
    //
    //     "C1:T1"
    //     "C1:T2"
    //     "C1:T3"
    //     "C2:T1"
    //     "C2:T2"
    //     "C2:T3"
    //     "C3:T1"
    //     "C3:T2"
    //     "C3:T3"
    //
    PhysicalName<Trace> trace1("C2:T3");

    cout << trace1.AncestorIndex<Channel>(Vi);  // prints "1" (not "5")

    PhysicalName<Trace> trace2("C2:T1");

    cout << trace2.AncestorIndex<Channel>(Vi);  // still prints "1" (not "3")

    PhysicalName<Trace> trace3("C1:T3");

    cout << trace3.AncestorIndex<Channel>(Vi);  // prints "0" (not "2")
}