SelectorStyleRepCap::GetActiveSelector

Vi

[in] ViSession handle for the driver session.

nSelectorBufferSize

[in] Number of characters allocated by the caller in the szSelector parameter.

szSelector

[out] The active selector for the repeated capability as set by a previous call to the SetActiveSelector function. If the SetActiveSelector function has not yet been called by the client program, this function returns an empty string.

Returns a VI_SUCCESS if the operation was successful or a failure ViStatus otherwise.

Unlike parameter-style repeated capabilities which explicitly pass a RepCapIdentifier parameter to each function or attribute associated with the repeated capability, selector-style repeated capabilities operate on an active selector, which is a cached string that may accurately be thought of as a "hidden" or "implicit" RepCapIdentifier parameter. Client programs call the SetActiveSelector function and the driver caches the resulting physical names and uses it on subsequent calls to functions and attributes as if the client program had directly passed a RepCapIdentifier parameter to each function and attribute invocation.

The active selector retrieved here is the same literal value previously set via the SetActiveSelector function. That is to say, virtual names, lists, and ranges all appear as-specified without any of the expansion semantics performed by the ExpandActiveSelector function. Use the GetActivePhysicalNames function to retrieve the expanded active selector as a list of physical names.

The following example demonstrates use of the GetActiveSelector function.

ViStatus _VI_FUNC acme4321_get_ACTIVE_MARKER(ViSession Vi, ViConstString RepCapIdentifier, ViInt32 AttributeValueBufferSize, ViChar AttributeValue[])
{
    ValidateSession(Vi);
    ObtainLock(Vi);
    CheckForNull(Vi, AttributeValue);

    auto status = VI_SUCCESS;

    status = Marker::GetActiveSelector(Vi, AttributeValueBufferSize, AttributeValue);

    return status;
}