|Download Help (Windows Only)|
Owning Palette: Application Control VIs and Functions
Requires: Base Package
Returns a reference to a VI, custom control, or global variable specified by a name string or path to the VI's location on disk.
Wire a VI reference control or constant to the type specifier VI Refnum input to create a strictly typed VI reference, which you pass to the Call By Reference Node. The connector pane displays the default data types for this polymorphic function.
|type specifier VI Refnum (for type only) determines the data type of vi reference. This function ignores the value of this input and uses this parameter only to define the data type of the VI reference output. By default, the function returns a Generic VI reference.
Use type specifier if you want to use the output reference to call the VI with the Call By Reference Node. Either click and drag a VI icon onto the reference or right-click the input and select Create»Constant from the shortcut menu. Right-click the constant that appears and select Select VI Server Class»Browse from the shortcut menu. Use the file dialog box that appears to navigate to the VI.
If you wire this input, you cannot wire the output reference to the Run VI method.
|application reference is a reference to a LabVIEW application. The default is a reference to the application instance for the calling VI. If wired and the reference is to a remote application instance, the remote application instance is queried to return the VI reference.|
|vi path accepts a string containing the name of the VI that you want to reference, or a path containing the complete path to the VI that you want to reference. If you wire a name string, the string must match the full delimited name of a VI in memory on that target. If you wire a path, LabVIEW searches for a VI in memory that you previously loaded from that path on the same target. If a matching VI is not found in memory, LabVIEW then tries to load the VI from that file on disk. An error occurs if LabVIEW cannot find the file or if the file conflicts with another VI in memory.
If the path is relative, the VI interprets the path as relative to the caller VI or to the application directory, if the caller VI is not saved.
If you wire a path, LabVIEW waits until the user interface is idle to load the VI from disk. If you wire a name string, LabVIEW does not need to wait until the user interface is idle, as it does not load a VI from disk. LabVIEW will only search in memory for a VI with a specified name.
You can open a reference to a clone of a reentrant VI. Use the VI Clone Name property to return the name of the clone of the VI in the format SampleVI.vi:2. You can then wire the name of the clone of the VI to the vi path control.
|options is a bit set that specifies how the VI reference is treated. The default is 0x0. options can be a combination of the following values.
|error in describes error conditions that occur before this node runs. This input provides standard error in functionality.|
|password is the password for the VI. If the VI is not password protected, this function ignores password. If the VI is password protected and you enter an incorrect password, this function returns an error and an invalid VI reference.|
|vi reference is the refnum associated with the requested VI. If the function fails, vi reference contains Not A Refnum.|
|error out contains error information. This output provides standard error out functionality.|
You can get references to VIs in another LabVIEW application by wiring an application reference (obtained from the Open Application Reference function) to this function. In this case, path input refers to the file system on the remote computer. If you wire a reference to the local LabVIEW application you get the same behavior as if you had not wired anything to the application reference input.
If you intend to perform editing operations on the referenced VI, and the VI has a password-protected block diagram, you can provide the password to the password string input. If you provide the incorrect password, the Open VI Reference function returns an error and an invalid VI reference. If you provide no password when opening a reference to a VI that is password protected, you can still get the reference, but you perform operations that do not edit the VI.
|Note If you set the Run When Opened or Show Front Panel On Load properties or the corresponding options in the VI Properties dialog box for a VI and you use this function to open a reference to the VI, LabVIEW ignores the settings.|
If you intend to call the specified VI through the Call By Reference Node, wire a strictly typed VI reference to the type specifier input. The function ignores the value of this input. The function uses only the input type, the connector pane information. By specifying this type, the Open VI Reference function verifies at run time that the referenced VI's connector pane matches that of the type specifier input.
|Note You can wire a Generic VI refnum type to type specifier. Doing so results in the same behavior as if you had not wired type specifier. You also can wire a FacadeVI class to type specifier to return a Fašade VI reference.|
If you wire type specifier with a strictly typed VI refnum, the VI must meet the following requirements before the VI reference is returned successfully:
If you do not close this reference, it closes automatically after the top-level VI associated with this function executes. However, it is good practice to conserve the resources involved in maintaining the connection by using the Close Reference function to close the reference when you finish using it.
If you get a strictly typed reference to a reentrant VI, a dedicated data space is allocated for that reference. Use this data space always and only in conjunction with the output VI reference. This can lead to some new behaviors that you might not be accustomed to in LabVIEW. For example, parallel calls (using the Call By Reference Node) to a reentrant VI using the same VI reference do not execute in parallel, but execute serially, one after the other.
|Note If you use the Equal? function to compare two VI references that refer to the same reentrant VI, LabVIEW always returns TRUE, regardless of whether the references have the same capability or the same value. To compare the actual values of the references, use the Type Cast function to convert the references to 32-bit signed integers. Then use the Equal? function to compare those integers.|
Notice that a VI reference is similar to what is known as a function pointer in other languages. However, in LabVIEW, these function pointers also can be used to call VIs across the network.
If you reference a VI that you are building into a stand-alone application, the Application Builder moves all dependencies of the VI to the destination you designate, rather than keep the dependencies in the built application. If two or more VIs that are always included or top-level VIs call a VI and try to move it to two different locations, the Application Builder moves the VI and all subVIs to the built application.