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

Open VI Reference Function

LabVIEW 2013 Help

Edition Date: June 2013

Part Number: 371361K-01

»View Product Info

Owning Palette: Application Control VIs and Functions

Requires: Base Development System

Returns a reference to a VI, custom control, or global variable specified by a name string or path to the VI location on disk.

Details  Examples

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 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, 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 then can wire the name of the clone of the VI to the vi path control.
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 flagDescription
0x01Record 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.
0x02Open 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.
0x04Prompt 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.
0x08Prepare for reentrant run—Use this option flag when you want to use the Run VI method to run multiple instances of a reentrant target VI in parallel. Setting this option flag causes LabVIEW to allocate a dedicated parallel data space in which a clone of the target VI can run. Without this option flag, the Open VI Reference function always returns a reference to the same data space of the original target VI, preventing multiple calls to that VI from executing simultaneously. LabVIEW returns error 1096 if the target VI is not reentrant. Refer to the runvi LLB for an example of using this option flag.
Tip  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. Refer to the TCPDateServerUsingStartAsynchronousCall LLB for an alternative implementation of the runvi LLB example.
0x10Prompt to find missing subVIs—Use this option flag to prompt the user to allow LabVIEW to search for missing subVIs of the referenced VI.
0x20Hide 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.
0x40Enable 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. Refer to the AsynchronousCallAndCollectUsingOption0x40 VI for an example of using this option flag.

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.
0x80Prepare 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. Refer to the AsynchronousCallAndForget VI for an example of using this option.
Note  LabVIEW returns error 1578 if you use this option flag with a reference to a remote VI.
0x100Prepare 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. Refer to the AsynchronousCallAndCollect VI for an example of using this option.
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 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. 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.
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

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
  • Asynchronous Call and Forget VI: labview\examples\Application Control\VI Server\Asynchronous Call By Reference
  • Asynchronous Call and Collect VI: labview\examples\Application Control\VI Server\Asynchronous Call By Reference

 

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