Open VI Reference

Returns a reference to a VI specified by a name string or path to the VI's location on disk. The connector pane displays the default data types for this polymorphic function. Details

type specifier VI Refnum is used for its data type only. The value of the input is ignored. Its data type determines the data type of vi reference. The default is to output 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.
application reference is a reference to a LabVIEW application. The default is a reference to an application on the local instance of LabVIEW. If wired and the reference is to a remote instance of LabVIEW, the remote instance of LabVIEW is queried to return the VI reference.
vi path accepts a string containing the name of the desired VI or a path containing the complete path (including the name) to the desired VI. If you wire a name string, the VI must already be in memory. If you wire a path and the VI is already in memory, you get the one in memory, whether its path is the same as the input or not. If the VI is not in memory, the VI must be at the specified path for this function to succeed. If it is at that location, it is loaded into memory.

Note  If you specify a remote instance of LabVIEW by the application reference input, 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 a Macintosh at My HD:LabVIEW VIs:foo.vi from a Windows application, you would use this Windows path syntax My HD:\LabVIEW VIs\foo.vi. Conversely, to reference a VI on a Windows computer at C:\labview\foo.vi from a Macintosh application, use this Macintosh path syntax C:labview:foo.vi.

vi path can be a relative path, meaning relative to the caller VI or relative to the application directory if the caller VI is not saved.

options is a bitset that specifies how the VI reference is treated. options can be a combination of the following values.

0x01Record modifications.
0x02Open templates for editing.
0x04Prompt user at close. When you attempt to close a VI refnum after making changes, the VI Server prompts you to save before closing the VI.
0x08Prepare for reentrant run. Reserves the target VI so it cannot be edited and if the target VI is reentrant, allocates a dedicated parallel data space for this VI reference. If the target VI is not reentrant, the function returns an error. When you release the VI reference, LabVIEW unreserves the reentrant target VI and deallocates a parallel data space. Allows you to run multiple instances of a reentrant VI simultaneously, using the Run VI method. Refer to the examples\viserver\runvi.llb for examples of using this option.
error in describes error conditions that occur before this VI or function runs. The default is no error. If an error occurred before this VI or function runs, the VI or function passes the error in value to error out. This VI or function runs normally only if no error occurs before this VI or function runs. If an error occurs while this VI or function runs, it runs normally and sets its own error status in error out. Use the Simple Error Handler or General Error Handler VIs to display the description of the error code. Use error in and error out to check errors and to specify execution order by wiring error out from one node to error in of the next node.
status is TRUE (X) if an error occurred before this VI or function ran or FALSE (checkmark) to indicate a warning or that no error occurred before this VI or function ran. The default is FALSE.
code is the error or warning code. The default is 0. If status is TRUE, code is a non-zero error code. If status is FALSE, code is 0 or a warning code.
source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning. The default is an empty string.
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. You cannot edit the VI through that 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. If error in indicates that an error occurred before this VI or function ran, error out contains the same error information. Otherwise, it describes the error status that this VI or function produces. Right-click the error out indicator on the front panel and select Explain Error from the shortcut menu for more information about the error.
status is TRUE (X) if an error occurred or FALSE (checkmark) to indicate a warning or that no error occurred.
code is the error or warning code. If status is TRUE, code is a non-zero error code. If status is FALSE, code is 0 or a warning code.
source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning.

Open VI Reference Details

You can get references to VIs in another LabVIEW applications 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 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.

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.

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 forget to close this reference, it closes automatically when the top-level VI associated with this function finishes executing. However, it is good practice to conserve the resources involved in maintaining the connection by closing 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 may 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 does not execute in parallel, but executes serially, one after the other. As another example, a reentrant VI could get a reference to itself (allocating a new data space) and call itself recursively through the Call By Reference Node.
Note  Allocating a data space dynamically is both time consuming and memory consuming and is not generally recommended for implementing recursive algorithms.

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.