Open VI Reference Function

type specifier VI Refnum (for type only) determines the connector pane information and data type of vi reference. LabVIEW ignores the actual value of this input. By default, the function returns a Generic VI reference.

If you want to use the vi reference output of this function with the Call By Reference node or the Start Asynchronous Call node, you must wire a strictly typed VI reference to this input.

If you wire a strictly typed VI reference to this input, the connector pane of the VI specified by vi path must match the connector pane of this input.

application reference is a reference to a LabVIEW application instance. By default, LabVIEW uses the application instance of the calling VI. You can obtain references to other application instances with the Open Application Reference function. If you wire a reference to another application instance to the application reference input, vi path refers to a location in the file system of the computer that is running that application instance.

vi path accepts a string containing the name of the VI that you want to reference or a 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.

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.

Note If you specify a remote application instance with application reference, the path is interpreted on the remote machine in the context of the remote file system. The path is expressed using the local computer's path separators, but is translated to the remote computer's path separators when the request arrives there.

For example, to reference a VI on macOS at My HD/LabVIEW Vis/foo.vi from a Windows–based application, use the path My HD:\LabVIEW Vis\foo.vi. Conversely, to reference a VI on a computer running Windows at C:\labview\foo.vi from an macOS application, wire the path C/labview/foo.vi.

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.

Note LabVIEW does not support the ability to open a reference to a clone VI with the Open VI Reference function. Using this function to open a reference to a clone VI may cause LabVIEW to crash.

options determines characteristics of the VI referenced by vi reference, including whether you can call the VI asynchronously. The default is 0x0. Create options by combining a subset of the following option flags.

Option flag

Description

0x01

Record modifications—Use this option flag when you want an asterisk (*) to appear by the VI title when changes have been made using VI Server. The VI must be in edit mode for LabVIEW to record the modifications.

0x02

Open templates for editing—Use this option flag to open the original .vit file. If you do not select this option flag, LabVIEW opens a new instance of the template VI. Edits made to an instance do not affect the original .vit file. This option flag has no effect on non-template files.

0x04

Prompt user to save—Use this option flag to prompt the user to save changes when this VI reference closes if all the following conditions are true:

The referenced VI or its subVIs contain unsaved changes.
There are no other open references to the referenced VI.
The referenced VI is able to leave memory. A VI is able to leave memory, for example, if no other VIs call the VI, the front panel of the VI is closed, and the VI is not a member of an open project library, and so on.

0x08

Prepare for reentrant run—Use this option flag when you want a reference to a reentrant clone of the target VI, instead of the target VI itself. Reentrant clones of a VI allow you to open multiple front panels of the same VI or to run multiple copies of the same VI in parallel. For each reference to the target VI, LabVIEW creates a separate clone of the target VI. This clone is not part of the pool of shared clones used by regular subVI calls.

LabVIEW ignores this flag if you wire the type specifier VI Refnum (for type only) input because when you provide a type specifier, you can always get a reentrant clone if the target VI is reentrant. LabVIEW returns error 1096 if the target VI is not reentrant.

Tip Use this flag in combination with the Run VI method to execute multiple reentrant clones in parallel. Use the Start Asynchronous Call node instead of the Run VI method to run target VIs asynchronously. In addition to providing a simpler interface and better performance, the Start Asynchronous Call node allows you to collect the outputs of the target VI with a corresponding Wait On Asynchronous Call node.

0x10

Prompt to find missing subVIs—Use this option flag to prompt the user to allow LabVIEW to search for missing subVIs of the referenced VI.

0x20

Hide loading dialog box—Prevents LabVIEW from displaying the loading dialog box when searching for missing subVIs of the referenced VI.

Note This option flag does not affect whether LabVIEW prompts you to find the missing VIs or not.

0x40

Enable simultaneous calls on reentrant VIs—Use this option flag when you want to use multiple Call By Reference or Start Asynchronous Call nodes to execute clones of a reentrant target VI in parallel, as when you use these nodes within a For Loop with parallel loop iterations. This option flag enables parallel execution because it gives each Call By Reference node access to the data spaces of the clone VIs. If you do not use this option flag, calls to the same target VI execute one at a time because they must wait for access to the same data space.

The 0x40 option flag is valid only in the following situations:

The target VI is reentrant and shares clones.
The target VI is reentrant, and you also include either the 0x80 or the 0x100 option flag.

Note LabVIEW returns error 1591 if the 0x40 option flag is not valid for the target VI or the other included option flags.

0x80

Prepare to call and forget—Use this option flag when you want to call a target VI asynchronously with the Start Asynchronous Call node but you do not need to know when or what the VI returns. Do not use this option flag with 0x08 or 0x100.

Note LabVIEW returns error 1578 if you use this option flag with a reference to a remote VI.

0x100

Prepare to call and collect—Use this option flag when you want to collect the results of an asynchronous call to a target VI with the Wait On Asynchronous Call node. If you use this option flag, you must include one Wait On Asynchronous Call node for every call that you begin with a Start Asynchronous Call node to ensure that LabVIEW does not retain any started calls in memory indefinitely. Do not use this option flag with 0x08 or 0x80.

Note LabVIEW returns error 1578 if you use this option with a reference to a remote VI.

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 whose reference you want to open. Wire a password to this input if you want to edit a password-protected target VI. If you wire the correct password, the function returns an authenticated reference to the VI. If you wire an incorrect password to this input, the function returns an error and an invalid VI reference. LabVIEW ignores this input if the target VI is not password-protected. If you do not wire a password to this input and the target VI is password-protected, the Open VI Reference function returns a valid reference, but you cannot use the reference to edit the VI.

Note You can also use a VI Server Reference to get an authenticated reference to a VI.

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.

Open VI Reference Details

The Open VI Reference function prepares a VI reference for dynamic calls by the Call By Reference node, the Start Asynchronous Call node, and the Wait On Asynchronous Call node. Use the type specifier VI Refnum (for type only) and the options inputs to prepare a reference for dynamic execution.

Opening References for Dynamic VI Calls

If you want to call the specified VI dynamically with the Call By Reference Node or the Start Asynchronous Call Node, you must use appropriate data for the following parameters:

type specifier VI Refnum (for type only)—Wire a strictly typed VI reference to this input.
options—Determine whether the 0x08, 0x40, 0x80, and 0x100 option flags apply to the way you want to call the referenced VI.

Criteria for Opening Strictly Typed References

If you wire a strictly typed VI reference to the type specifier VI Refnum (for type only), the VI specified by vi path must meet the following criteria:

The VI cannot be broken.
The VI cannot be active as a top-level VI unless the VI is reentrant.
The connector pane of the VI must match the connector pane of type specifier VI Refnum (for type only).

Opening References to Reentrant VIs

If you open a reference to a reentrant VI, consider the following details:

Dynamic calls to reentrant target VIs execute serially unless you specify 0x40 as one of the options.
If you use the 0x40 option flag to execute instances of a reentrant target VI in parallel, vi reference refers to the target VI rather than to a clone of the target VI. However, both the Call By Reference node and the Start Asynchronous Call node call a clone of the target VI. Therefore, if you call a VI Server property or method on vi reference, the property or method does not affect the clone VIs that those nodes actually call.
The Equal? function always returns TRUE when you compare two references to the same reentrant VI. To determine whether the references refer to the same instance of the reentrant VI, use the Type Cast function to convert the references to 32-bit signed integers. Then use the Equal? Function to compare those integers.

Aborting Open References

You can abort all open VI references either manually from the front panel of the VI or by using the Abort VI method. However, VI references prepared for asynchronous execution have important caveats depending on the options used to open the reference:

0x80—A call-and-forget VI aborts only if you manually abort it from its front panel or call the Abort VI method on it. Otherwise, the VI runs to completion, even if you close the reference or abort the calling VI.
0x100—Call-and-collect VIs abort for the following reasons:
- You abort the VI that opened the call-and-collect VI reference. In this case, LabVIEW aborts all running instances of the VI.
- You manually abort a specific instance of the VI. In this case, exactly one Wait On Asynchronous Call node returns an error indicating that the called VI aborted. All other Wait On Asynchronous Call nodes that are waiting on calls to the same VI reference continue waiting.
- You call the Abort VI method on the call-and-collect VI reference. In this case, LabVIEW aborts all currently running instances of the VI. A corresponding number of Wait On Asynchronous Call nodes return errors.

Closing Open References

After you finish using a reference that you obtain with this function, close the reference with the Close Reference function. Explicitly closing a reference enables LabVIEW to free the resources involved in maintaining that reference, thereby contributing to optimal memory allocation and performance. Otherwise, LabVIEW cannot close the reference until the VI that opened the reference finishes executing.

Note Closing a reference that was opened with the 0x80 option flag does not abort the referenced VI.

Opening a VI Reference in a Stand-Alone Application

If you want to dynamically open a VI on both the development computer and within a stand-alone application, use a relative path for vi path.

Miscellaneous Details

If you set the Execution:Run When Opened, Execution:Show Front Panel On Load, or Execution:Show Front Panel On Call properties or the corresponding options in the VI Properties dialog box of the target VI, LabVIEW ignores the settings.
To open a new Facade VI reference, wire a FacadeVI class to type specifier VI Refnum (for type only).

Examples

Refer to the following VIs for examples of using the Open VI Reference function:

Asynchronous Call and Collect (Using Option 0x40) VI: labview\examples\Application Control\VI Server\Asynchronous Call By Reference
Open example Find related examples
Asynchronous Call and Forget VI: labview\examples\Application Control\VI Server\Asynchronous Call By Reference
Open example Find related examples
Asynchronous Call and Collect VI: labview\examples\Application Control\VI Server\Asynchronous Call By Reference
Open example Find related examples