Selector Strings (C or LabWindows™/CVI™)

RFmx TD-SCDMA 19.1 Help

Edition Date: October 2019

Part Number: 375493H-01

»View Product Info
Download Help (Windows Only)

RFmx is a powerful API that supports basic and advanced features and provides multiple ways to configure measurements and fetch measurement results. You can use the same configuration and fetch functions in basic and advanced use cases, such as named signal configurations, without having to rewrite code. The following code shows a basic ACP measurement that does not use named signal configurations.

/* Initialize a session */
RFmxSpecAn_Initialize(resourceName, "", &instrumentHandle, NULL);
/* Configure ACP measurement */
RFmxSpecAn_CfgRF(instrumentHandle, "", centerFrequency, referenceLevel, externalAttenuation);
RFmxSpecAn_ACPCfgAveraging(instrumentHandle, "", averagingEnabled, averagingCount averagingType);
RFmxSpecAn_ACPCfgCarrierAndOffsets(instrumentHandle, "",
                                   integrationBandwidth, numberOfOffsetChannels, channelSpacing);
/* Retrieve results */
RFmxSpecAn_ACPRead(instrumentHandle, "", timeout, &carrierAbsPower, &offCh0LowerRelativePower,
                   offCh0UpperRelativePower, &offCh1LowerRelativePower, &offCh1UpperRelativePower);
/* Close session */
RFmxSpecAn_Close(instrumentHandle, RFMXSPECAN_VAL_FALSE);

You can enhance the code as shown in the following code to use named signal configurations by adding an  RFmxSpecAn_CreateSignalConfiguration function to create the signal and the RFmxSpecAn_BuildSignalString function to build a signal string in a required form and passing that signal string into the selectorString input of the functions that the basic ACP code is using.

/* Initialize a session */
RFmxSpecAn_Initialize(resourceName, "", &instrumentHandle, NULL);
/* Create a signal and build a signalString */
RFmxSpecAn_CreateSignalConfiguration(instrumentHandle, “MySignalConfig”);
RFmxSpecAn_BuildSignalString("MySignalConfig", "", MAX_SELECTOR_STRING, selectorString);
/* Configure ACP measurement */
RFmxSpecAn_CfgRF(instrumentHandle, selectorString, centerFrequency, referenceLevel, externalAttenuation);
RFmxSpecAn_ACPCfgAveraging(instrumentHandle, selectorString, averagingEnabled, averagingCount averagingType);
RFmxSpecAn_ACPCfgCarrierAndOffsets(instrumentHandle, selectorString, integrationBandwidth,
                                   numberOfOffsetChannels, channelSpacing);
/* Retrieve results */
RFmxSpecAn_ACPRead(instrumentHandle, selectorString, timeout, &carrierAbsPower, &offCh0LowerRelativePower,
                   offCh0UpperRelativePower, &offCh1LowerRelativePower, &offCh1UpperRelativePower);
/* Close session */
RFmxSpecAn_Close(instrumentHandle, RFMXSPECAN_VAL_FALSE);

The selectorString parameter in RFmx functions allows you to specify the full context of what you are configuring or fetching. The following code shows an example of the selectorString parameter on one of the RFmx fetch measurement functions.

int32 __stdcall RFmxSpecAn_ACPFetchCarrierMeasurement (niRFmxInstrHandle instrumentHandle, char selectorString[], float64 timeout, float64* absolutePower, float64* totalRelativePower,
float64* carrierOffset, float64* integrationBandwidth);

For example, an ACP measurement can have multiple offset channels, and you can configure the frequency and measurement bandwidth properties for each offset channel. When you configure the measurement bandwidth for a specific offset channel, you must specify the offset channel for which you are configuring the Measurement Bandwidth attribute. When you configure the first offset channel, you must specify the context in the selectorString input as “offset0”, as shown in the following code.

/* Fetch ACP offset measurements */
RFmxSpecAn_ACPFetchOffsetMeasurement (instrumentHandle, “offset0”, timeout, &lowerRelativePower,
                                      &upperRelativePower, &lowerAbsolutePower, &upperAbsolutePower);

The contexts you can specify depend on what you are configuring or fetching. For example, if you are configuring a carrier channel, you specify which carrier channel, such as “carrier3”, you are configuring. If you are configuring an offset channel, you specify which offset channel, such as “offset2”, you are configuring.

Some contexts, such as a named signal configuration, can be specified in all configuration and fetch functions. Some contexts, such as a named result, can be specified in only the initiate and fetch functions.

Multiple Contexts

When using multiple features in the API, you can specify multiple contexts in the same selectorString input separated with a ‘/’. For example, to configure carrier 0 in the named signal configuration called “MySignal”, you must specify “signal::Mysignal/carrier0” as the selector string.

Another example of multiple contexts is when performing LTE non-contiguous carrier aggregation measurements. In this case the signal is composed of multiple subblocks and each subblock can contain multiple carriers. When you configure a property of a carrier in LTE non-contiguous carrier aggregation, you must specify the index of the carrier within the subblock and the index of the subblock. For example, you would specify that you are configuring the first carrier in the second subblock by using “subblock1/carrier0” as the selector string.

String Prefixes in Selector Strings

RFmx requires a prefix, such as “carrier” or “signal::” before the number or name in the selector string so that it is clear what is being configured. The “::” is required for “signal::” and “result::” because those items use arbitrary user-defined names and the API must identify where the user specified name starts in the selector string. You can specify the selector strings as constants, such as “carrier0” and “signal::mysignal”, or use the build string utility functions provided by RFmx to create correctly formed strings.

Build String Utility Functions

RFmx provides a set of utility functions as shown below to build context string for various measurement configurations.

  • RFmxSpecAn_BuildSignalString
  • RFmxSpecAn_BuildCarrierString2
  • RFmxSpecAn_BuildHarmonicString2
  • RFmxSpecAn_BuildOffsetString2
  • RFmxSpecAn_BuildSpurString2
  • RFmxSpecAn_BuildRangeString2
  • RFmxSpecAn_BuildMarkerString2

For example, the BuildSignalString function takes in a named signal configuration name and/or a result name and produces a string containing the contexts you specified. If you call the BuildSignalString function with “MySignal” passed to the signalName input, the output string is “signal::MySignal”. Each RFmx driver provides build string utility functions for specific cases, such as BuildRangeSpurString, which takes in a range number and spur number, in addition to optionally taking in a previously constructed selector string. If you call the BuildSpurString2 function with a spur set to 2, and the selectorString input set to the output of the previously called BuildRangeString2 function, say range1, the output string is “signal::MySignal/range1/spur2”.

int32 __stdcall RFmxSpecAn_BuildSpurString2 (char selectorString[], int32 spurNumber,
                                             int32 selectorStringOutLength, char selectorStringOut[]);

Selector String in Set or Get Property Functions

When setting properties from an RFmx property set or get function in C, you specify the context using the selectorString parameter.

Selector Strings when using Array Functions

Notice that RFmx provides array versions of configure and fetch functions for many cases that allow you to configure multiple instances of a property or fetch multiple instances of a result. For example, to configure the frequencies of all the ACP measurement offset channels, you can use ACPCfgOffsetArray passing in an array that has the frequency for each of the offset channels. When using these array functions, you do not need to specify in the selectorString input the context for the elements in the array. For example, you pass "" as the selectorString in ACPCfgOffsetArray. However, if you are using named signal configurations or named results, you pass those contexts in the selector string even when you use the array functions.

Selector String Syntax

The following table lists the various selector string formats that you can use. For integral channel specifiers, valid values for i are 0 to (number of channels - 1). For example, if you set the value of the RFMXSPECAN_ATTR_ACP_NUMBER_OF_OFFSETS attribute to 5, you can configure ACP offset attributes for offset0, offset1, offset2, offset3, and offset4.

Selector String String FunctionExample
ch<i> Configures one channelcarrier0
ch<i>-<j> Configures a range of channels between i and jcarrier0-5
ch<i>:<j> Configures a range of channels between i and jcarrier0:5
ch<i>, ch<j>, ch<k> Configures channels i, j, and k carrier0, carrier2, carrier4
ch<i>, ch<j>-<k> Configures channel i and a range of channels between j and k carrier0, carrier1-5
ch<i>, ch<j>:<k> Configures channel i and a range of channels between j and k carrier0, carrier1:5
ch::all Configures all channels from 0 to (Number of X - 1).  Number of X is the current value of the Number of ... property that corresponds to the context being used.  For example, in an ACP measurement, you set the Number of Offsets property before setting any offset properties and when you use “all”, RFmx uses the current value of Number of Offsets to determine which offset channels to configure. offset::all

The following table lists the various selector string formats that you can use to specify the named signal configurations, using the “signal::” prefix, and named results, using the “result::” prefix.  Notice that the “result::” prefix is valid only when fetching results and currently cannot be used to configure measurements.

Syntax String Function Example
signal::<signalname> Specifies signal <signalname> signal::sig1
signal::<signalname>/ch<i> Specifies channel i on signal <signalname> signal::sig1/carrier0
signal::<signalname>/result::<resultname>/ch<i> Specifies channel i for result <resultname> on signal <signalname> signal::sig1/result::r1/carrier0
signal::<signalname>/result::<resultname> Specifies named result <resultname> on signal <signalname> signal::sig1/result::r1
result::<resultname> Specifies named result <resultname> on the default signal result::r1

The following characters are not allowed in signal names and result names: ()*+,-./{} !"#$%&':;<=>?@[]\^`|~ and any non-printable character.


Not Helpful