Company Events Academic Community Support Solutions Products & Services Contact NI MyNI

Selector Strings

NI-RFmx SpecAn 2.3 Help

Edition Date: May 2017

Part Number: 374264G-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. The same configuration and fetch VIs/functions can be used in basic and advanced use cases, such as named signal configurations, without having to rewrite code. The following image shows a basic ACP measurement that does not use named signal configurations.

You can enhance the code as shown in the following figure to use named signal configurations by adding a Create Signal VI and wiring the signal name into the Selector String input of the VIs/functions the basic ACP code was already using.

The NI-RFmx Selector String input allows you to specify the full context of what you are configuring or fetching. The following figure shows an example of the Selector String input on one of the NI-RFmx fetch measurements VIs.

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 property.  When you configure the first offset channel, you must specify the context in the Selector String input as “offset0”, as shown in the following figure.

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 VIs.  Some contexts, such as a named result, can be specified in only the initiate and fetch VIs.

Multiple Contexts

When using multiple features in the API, you can specify multiple contexts in the same Selector String 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 performing LTE noncontiguous 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 noncontiguous 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

NI-RFmx requires a prefix, such as “carrier” or “signal::”, before the number or name in the selector string so that it is clear what object 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 VIs/functions provided by RFmx to create correctly formed strings.

Build String Utility VIs/Functions

NI-RFmx provides a set of utility VIs/functions/methods, as shown in the following figure, to build the context string for various measurement configurations.

For example, the Build Signal String VI takes in a named signal configuration name and/or a result name and constructs a string containing the contexts you specified.  If you call the Build Signal String VI with “MySignal” passed to the Signal Name input, the output string is “signal::MySignal”.  Each RFmx driver provides build string utility VIs/functions/methods for specific cases, such as Build Spur String2, which takes in a spur number in addition to optionally taking in a previously constructed selector string. If you call the Build Spur String2 VI with a spur set to 2, and the Selector String input set to the output of the previously called Build Range String2 VI, say range1, the output string is “signal::MySignal/range1/spur2”.

Selector String in Property Node

When setting properties or fetching results from an RFmx property node in LabVIEW, you specify the context using the Selector String property. You must set the Selector String property above the other properties that you want the context in the selector string to apply to.

Selector Strings when using Array VIs

Notice that NI-RFmx provides array versions of configure and fetch VIs 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 the ACP Configure Offset (Array) VI, passing in an array that has the frequency for each offset channel.  When using these array VIs/functions/methods, you do not need to specify in the Selector String input the context for the elements in the array.  For example, you pass “” as the selector string in the Configure ACP Offset Channel (Array) VI.  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 VIs/functions/methods.

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 ACP Num Offsets property to 5, you can configure ACP offset properties for offset0, offset1, offset2, offset3, and offset4.


In the following table, the term channel or ch is used to refer to numeric contexts such as carrier, offset, or range.

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 used.  For example, in an ACP measurement, you set the Number of Offsets property before setting any offset properties and when you use “all”, NI-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 FunctionExample
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 signalresult::r1

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


 

Your Feedback! poor Poor  |  Excellent excellent   Yes No
 Document Quality? 
 Answered Your Question? 
Add Comments 1 2 3 4 5 submit