ParameterStyleRepCap::ExpandSelector

Vi

[in] ViSession handle for the driver session.

szSelector

[in] A repeated capability selector which can include virtual names, physical names, comma-separated lists of names and physical name ranges.

physicalNames

[out] A PhysicalNameList object containing the results of the expansion of the szSelector parameter.

bVerifyPhysicalNamesExist

[in] Indicates if the implementation should return an error if the expanded PhysicalNameList contains physical names that have not been defined for the repeated capability. This parameter defaults to true and should always be left at the default of true by driver developer code. Use of a false value here is reserved for internal Nimbus implementation purposes.

Returns a VI_SUCCESS if the operation was successful or a failure ViStatus otherwise. Some of the error codes that can be reported by this function based on various error conditions in the szSelector are as follows:

• IVIC_ERROR_CHANNEL_NAME_REQUIRED

• IVIC_ERROR_BADLY_FORMED_SELECTOR

• IVIC_ERROR_INVALID_RANGE_IN_SELECTOR

• IVIC_ERROR_INVALID_NUMBER_OF_LEVELS_IN_SELECTOR

• IVIC_ERROR_UNKNOWN_PHYSICAL_IDENTIFIER

This function first replaces virtual names with their corresponding physical names (and ranges) and then expands the resulting expression. The procedure followed for the expansion and virtual name substituion are described in "IVI 3.1 Section 4.4.7 Formal Syntax for Repeated Capability Selectors". The relevant details of that formal syntax is reproduced below for convenience.

Repeated capability selectors are widely used in IVI-C drivers, and this function performs critical validation and error checking required by the IVI specifications. Thus, this function should be used whenever a repeated capability selector is passed by the user as a driver function parameter.

If the szSelector parameter is VI_NULL or whitespace, then this function validates that the repeated capability has only a single physical name defined. If more than one physical name is defined when szSelector is VI_NULL or whitespace, then this function returns a ViStatus value of IVIC_ERROR_CHANNEL_NAME_REQUIRED, as required by the IVI specifications.

The following describes the formal syntax for repeated capability selectors:

• A syntactically valid repeated capability selector consists of zero or more repeated capability path segments separated by colons (:). White space around colons is ignored.

• A repeated capability path segment consists of one or more repeated capability list elements, separated by commas (,). White space after commas is ignored. A repeated capability path segment may be enclosed in square brackets ([]).

• A repeated capability list element consists of a repeated capability token or a repeated capability range.

• A repeated capability range consists of two repeated capability tokens separated by a hyphen (-).

• The order of precedence of operators is square brackets ([]), hyphen (-), colon (:), and comma (,). Each operator is evaluated from left to right.

• A repeated capability token is a physical repeated capability identifer or a virtual repeated capability identifier.

• A syntactically valid physical or virtual repeated capability identifier consists of one or more of the following characters: a z, A Z, 0 9, !, and _.

The following example demonstrates use of the ExpandSelector function.

ViStatus _VI_FUNC acme4321_ConfigureGlitchArmSource(ViSession Vi, ViConstString Source, ViReal64 Level, ViReal64 Width, ViInt32 Polarity, ViInt32 Condition)
{
    // Assume the Source parameter value supplied is "C1,C3,C5-C8"
    // 
    PhysicalNameList<::ArmSource> physicalNames;
    ReturnOnError(ArmSource::ExpandSelector(Vi, Source, physicalNames));

    for (const auto& physicalName : physicalNames)
    {
        cout << physicalName.Name();
    }

    // Prints the following:
    // 
    //    C1
    //    C3
    //    C5
    //    C6
    //    C7
    //    C8
    // 
}