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 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.
Finding Variables Programmatically
You 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. You must design the application carefully to ensure data integrity. |
The VI shown in the following block diagram uses the Remote Engines property of the local PSP Variable Engine to obtain 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 a single array, 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 programatically 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 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.
LabVIEW must open a connection to a shared variable before reading or writing the variable in a VI. If you do not open the variable connection explicitly, LabVIEW opens the variable connection automatically.
Opening and Closing Variable Connections
You can 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. |