Finding, Reading, and Writing Shared Variables Programmatically
Use the Variable properties and methods to find shared variables programmatically. Use the Shared Variable functions to read and write shared variables programmatically. You can use the programming techniques described in this document to find and access the following types of shared variables:
- PSP Variables
- I/O Variables
To access shared variables programmatically, you must specify the variable using a unique variable identifier URL. You can build the variable identifier URL programmatically in a loop to read or write multiple variables programmatically without placing individual shared variable nodes on the block diagram. By building the shared variable references programmatically, you can create scalable VIs that access hundreds or thousands of variables with relatively little LabVIEW code.
Shared Variable Architecture
The following list summarizes the set of LabVIEW constructs that relate to shared variables.
- Shared Variable—A memory space that holds data.
- Shared Variable Node—A node on the block diagram that accesses shared variable data.
- PSP Variable—A data item published on the network using the NI Publish-Subscribe Protocol (NI-PSP). Common examples of PSP variables include network-published shared variables and DAQ channels published through the DAQmx I/O server.
- I/O Variable—A type of shared variable that uses the NI Scan Engine for single-point access to I/O data.
- I/O Alias—An alias variable linked to an I/O variable or another I/O alias.
- Variable Container—A set of variables and nested variable containers. The most common type of variable container is a project library. However, other items such as I/O modules, Wireless Sensor Network (WSN) nodes, and EtherCAT devices also can serve as variable containers. You can use the Browse Variables dialog box to find all the variable containers currently deployed on the network.
- Variable Engine—A run-time component that manages a hierarchy of variable containers and variables.
- Project Library—A collection of VIs, type definitions, shared variables, palette files, and other files, including other project libraries. A project library that includes shared variables is a variable container, but not all variable containers are project libraries.
- Target Name—The name assigned to a target item, such as My Computer or an RT target, in a LabVIEW project.
Note (Real-Time Module) You can use the Name field on the General Properties page of the RT Target Properties dialog box to specify an RT target name.
Variable Identifier URL Syntax
A variable identifier takes the form of a URL that conforms to the Uniform Resource Identifier (URI) Generic Syntax specification (RFC 3986). The URL syntax of a variable identifier is:
[Variable Engine]://[Host Name]/[Container Name]/[Variable Name]
You must specify the Container Name and Variable Name components for all variable identifier URLs. However, you can omit the Variable Engine if it is implied by the class. You also can omit the Host Name if the variables are hosted on the same computer where the VI runs.
For example, the following LabVIEW project contains both network-published shared variables and I/O variables.
The following table includes the full variable identifier URLs for several of the variables in this project.
| Variable Name | Variable Type | Variable Identifier URL |
|---|---|---|
| Network Variable1 | Network-Published Shared Variable | ni.var.psp://My Computer/Network Variables/Network Variable1 |
| AI0 | I/O Variable | ni.var.io://RT CompactRIO Target/I%2FO Module1/AI0 |
| Network Variable3 | Network-Published Shared Variable | ni.var.psp://RT CompactRIO Target/RT Network Variables/Network Variable3 |
The variable identifier URL is not case sensitive. However, you must replace reserved characters with the corresponding escape codes to prevent parsing errors. For example, you must replace the ⁄ character with the escape code %2F.
The Variable Engine component of the URL depends on the type of variable you plan to read or write. The following table includes the Variable Engine URL for each type of shared variable that the Shared Variable Dynamic API supports.
| Type | Variable Engine URL |
|---|---|
| Network-published shared variable, I/O variable, or I/O alias (remote access) | ni.var.psp |
| I/O variable or I/O alias (local access) | ni.var.io |
You can use either the PSP Variable Engine or the I/O Variable Engine to access a network-published I/O variable or I/O alias. Use the I/O Variable Engine (ni.var.io) to read or write a network-published I/O variable or I/O alias locally. Use the PSP Variable Engine (ni.var.psp) to read or write a network-published I/O variable or I/O alias remotely.
The Variable Engine component of the URL is implied and therefore optional when using one of the following classes:
- PSP Variable Engine
- I/O Variable Engine
- PSP Variable Container
- I/O Variable Container
- PSP Variable
- I/O Variable
In this case, you can omit the Variable Engine component of the URL and use the following URL syntax:
//[Host Name]/[Container Name]/[Variable Name]
If you are using a generic class that does not imply the Variable Engine, and you do not specify the Variable Engine, LabVIEW attempts to resolve the variable identifier URL by searching variable engines in the following order of precedence.
- I/O Variable Engine
- PSP Variable Engine
In this case, if a matching URL exists in multiple engines, LabVIEW uses the first matching URL.
The [Host Name] component of the variable identifier URL is optional. You can specify the host name as a DNS name, a target name, or an IP address. However, if you do not specify a host name in the variable identifier URL, LabVIEW assumes the host is the same computer where you run the VI. You also can use the string localhost to explicitly specify the computer where you run the VI. To avoid name collisions, use unique names whenever possible.
If you do not need to specify a host name, you can use the following URL syntax:
/[Container Name]/[Variable Name]
If the host name you specify can be interpreted in more than one way, for example both as a project name and as a DNS name, LabVIEW searches for a valid interpretation of the specified host name in the following order of precedence.
- Target name (as specified in the LabVIEW project)
- DNS name
- IP address
The name of each shared variable within a container must be unique. However, because the variable identity includes the container name, variables in different containers can share the same variable name and still maintain unique variable identities.
Variable Class IDs
The following table summarizes the correspondence between Class Names and Class Ids for the Variable classes included in LabVIEW. Some I/O drivers, such as NI-RIO, might install additional classes that inherit from the Variable class hierarchy. Refer to your I/O driver documentation for information about additional classes.
| Class Name | Class Id |
|---|---|
| Variable Object | VariableObject |
| Variable | Variable |
| PSP Variable | PSPVariable |
| I/O Variable | IOVariable |
| Variable | Variable |
| Variable Container | VariableContainer |
| PSP Variable Container | PSPVariableContainer |
| I/O Variable Container | IOVariableContainer |
| Variable Engine | VariableEngine |
| PSP Variable Engine | PSPVariableEngine |
| I/O Variable Engine | IOVariableEngine |
You can use the Class Id property of any class that inherits from Variable Object to obtain the Class Id programmatically.
Switching to Programmatic Access
If you have an existing application that uses Shared Variable nodes, you can right-click an individual Shared Variable node and select Replace with Programmatic Access from the shortcut menu to get started with switching to programmatic shared variable access.
When you use the Replace with Programmatic Access shortcut menu option, LabVIEW replaces the Shared Variable node with the corresponding programmatic function from the Shared Variable palette. LabVIEW creates a variable refnum constant populated with the URL of the original shared variable and wires this constant to the shared variable refnum in input of the programmatic access function. LabVIEW also configures the variable refnum constant to match your original configuration.
|
Note LabVIEW does not include an option to reverse the Replace with Programmatic Access operation. To reverse the operation, you can select Edit»Undo immediately after selecting Replace with Programmatic Access. |
For large applications that access many shared variables, you can use the Replace with Programmatic Access shortcut menu option as a starting point for switching to programmatic access. However, rather than using this option on each shared variable node in your application, refer to the following section for information about finding shared variables programmatically. When you rearchitect your VI to find and access shared variables programmatically inside For Loops, you can avoid using a Shared Variable node each time you access a shared variable. This programming technique can create a cleaner, more scalable block diagram for a large-channel-count application.
Finding Variables Programmatically
Use the Search Variable Container function to search for shared variables and variable containers that meet specific criteria. For example, the VI shown in the following block diagram uses this function to find all the shared variables under a given container that meet the following criteria:
- Double data type
- Variable identifier URL contains the string foo
You also can use the following Variable Container properties and method to find shared variables programmatically.
 |
Caution When reading and writing shared variables that you find programmatically, you could end up reading or writing data of the wrong data type. Use the data type input of the Search Variable Container function to avoid reading or writing a shared variable of the wrong data type. |
The VI shown in the following block diagram uses the All Variables property to find all the PSP variables hosted on the local network. First, the VI uses a Local Variable Object Reference constant to pass a reference to the local PSP Variable Engine to the Remote Engines property. The Remote Engines property returns an array of PSP Variable Engines hosted on other computers on the network. The VI then iterates over each PSP Variable Engine in a For Loop. For each PSP Variable Engine, the VI uses the Root property to obtain a reference to the root PSP Variable Container on each remote computer and then uses the All Variables property to obtain an array of references to all the variables hosted on each remote computer. The VI adds all the variables found on the network to the All PSP Variables array shown in the following block diagram.
 |
Tip You can use the Variable Property Node, which is preconfigured with the Variable Object class. |
Finding Variables Interactively
You can use the Browse Variables dialog box to browse for shared variables and variable containers either on the network or in the current project. Click the drop-down arrow on a Variable control or constant and select Browse to display the Browse Variables dialog box.
Reading and Writing Variables
Use the Read Variable function to read live variable values programmatically. Unlike the Shared Variable node, which you must bind to a specific shared variable at edit time, the Read Variable function includes a shared variable refnum in input that you can use to specify the shared variable to read programmatically at run time. For example, you can use the Read Variable function inside a For Loop to read multiple shared variables specified by an array of refnums, as shown in the following block diagram.
Use the Read Variable with Timeout function to read only new data from a network-published shared variable. Use the Direct Variable Read function to read live I/O variable values using direct access. Use the Scanned Variable Read function to read live I/O variable values using scanned access.
Use the Write Variable function to write live variable values programmatically. For example, you can use the Write Variable function inside a For Loop to write to multiple shared variables specified by an array of refnums.
|
Tip You can optimize performance and streamline the block diagram by reading and writing I/O variable containers as arrays. |
Opening and Closing Variable Connections
Use the Open Variable Connection function to open a connection to a variable programmatically. If you use one of the read or write functions on the Shared Variable palette to access a shared variable without first opening a connection to the variable, LabVIEW automatically opens a connection to the variable. LabVIEW creates one implicit connection for each variable that you read or write without explicitly opening a connection. These implicit connections are shared between all read and write functions that run on the same computer.
However, this implicit open operation can add jitter to the application. Whenever possible, use an Open Variable Connection function to open all necessary variable connections before accessing the variables, as shown in the following block diagram.
After the application finishes accessing the shared variables, you can use the Close Variable Connection function in a For Loop to close all the variable references. If you do not use the Close Variable Connection function to close variable connections explicitly, LabVIEW automatically closes the connections when you stop the VI.
|
Tip To avoid jitter due to implicit open and close operations, always open and close variable connections explicitly. |
Creating a VI That Uses Programmatic Shared Variable Access
The following block diagram shows an example of a VI that uses programmatic shared variable access to find all the shared variables under a library, My Library, open references to all the variables in the library, read and process these variables continuously in a Timed Loop, and then close the references.
