SelectorStyleRepCap::SetActiveSelector

Vi

[in] ViSession handle for the driver session.

szSelector

[out] The active selector to use for subsequent operations on the repeated capability.

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

See the documentation on the ExpandSelector function for additional details on the possible failure codes this function may return.

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 set here is stored within the driver in two forms. First, it is stored in an unmodified form so that it can be retrieved exactly as the user specified. The GetActiveSelector function is used to retrieve the unmodified form. Next, the ExpandSelector function is called internally in order to translate any virtual names to physical names and to expand any lists of names or ranges of names. The result of this expansion is stored as a list of physical names that can be retrieved via the GetActivePhysicalNames function.

This function internally uses the ExpandSelector function to process the szSelector parameter. See that topic for more information on how the expansion is performed and the possible error codes that may be returned.

Important

For dynamic repeated capabilities, where the list of supported physical names may change during the driver session, it is important to keep in mind that any calls to the RemovePhysicalNames function may affect the behavior of the driver in ways that may be confusing to the end user. Specifically, if the SetActiveSelector function is used to make a set of physical names active and then the RemovePhysicalNames function is used to remove one or more of those physical names, then runtime errors are likely, depending upon the specific details of the driver implementation. The list of physical names resulting from the expansion of the szSelector parameter is only validated at the time the SetActiveSelector function is called.

The following example demonstrates use of the SetActiveSelector function.

ViStatus _VI_FUNC acme4321_set_ACTIVE_MARKER(ViSession Vi, ViConstString RepCapIdentifier, ViConstString AttributeValue)
{
    ValidateSession(Vi);
    ObtainLock(Vi);

    auto status = VI_SUCCESS;

    status = Marker::SetActiveSelector(Vi, AttributeValue);

    return status;
}