Company Events Academic Community Support Solutions Products & Services Contact NI MyNI

Open VI Reference Function

LabVIEW 2010 Help

Edition Date: June 2010

Part Number: 371361G-01

»View Product Info

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.

Details  

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.
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 a Macintosh at My HD:LabVIEW VIs:foo.vi from a Windows–based application, you would 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 a Mac OS X 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.

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.
0x01Record modifications. An asterisk (*) appears by the VI title to indicate that changes have been made using VI Server. The VI must be in edit mode for LabVIEW to record the modifications.
0x02Open templates for editing. This option opens the original .vit file. If you do not select this option, LabVIEW opens a new instance of the template VI. Edits made to an instance do not affect the original .vit file. This option has no effect on non-template files.
0x04Prompt 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.
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, this function returns an error. When you release the VI reference, LabVIEW unreserves the reentrant target VI and deallocates a parallel data space. Use this option with the Run VI method to run multiple instances of a reentrant VI simultaneously. If you target a reentrant VI and do not use this option, this function returns a reference to the VI without allocating a parallel data space for the VI reference. When you do not use this option, multiple calls to this function for a reentrant VI return references to the same VI with the same data space, and this function does not clone the VI. Refer to the examples\viserver\runvi.llb for examples of using this option. 
0x10Prompt user to find missing subVIs of the referenced VI.
0x20Do not display the loading dialog box when searching for missing subVIs of the referenced VI.
Note  This option does not affect whether LabVIEW prompts you to find the missing VIs or not.
0x40Share clone VIs. If the target is a reentrant VI that shares clones, LabVIEW allows Call By Reference Node functions to use the data spaces of the clone VIs. If you use multiple Call By Reference Node functions, the Call By Reference Node functions can use multiple clone VIs to execute in parallel. If you do not use this option, parallel Call By Reference Node functions must queue up and use a single data space. You can use this option if you add a Call By Reference function to a For Loop with parallel loop iterations.
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.

Open VI Reference Details

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:

  • The VI cannot be broken for any reason.
  • The VI must be executable as a subVI. That is, it cannot be active as a top-level VI unless the VI is reentrant.
  • The connector pane of the VI must match that of the type specifier.

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.


 

Your Feedback! poor Poor  |  Excellent excellent   Yes No
 Document Quality? 
 Answered Your Question? 
Add Comments 1 2 3 4 5 submit