Home Support NI Product Manuals LabVIEW NXG 5.1 Manual

Table Of Contents

Open VI Reference (G Dataflow)

Download Manual | Offline Viewer Required
Version:
Last Modified: November 4, 2020

Returns a reference to a VI you specify with a name string. For a VI exported from a specific library, wire the component reference input.

Open VI Reference prepares a VI reference for Call by Reference, Start Asynchronous Call, or Wait on Asynchronous Call to make dynamic calls. Use the Item tab for this node to configure the type of call you want to make.

connector_pane_image
datatype_icon

type specifier VI reference

The connector pane information and data type of the VI reference output you specify.

The compiler ignores the actual value of this input. By default, the node returns a generic VI reference.

If you want to use the vi reference output with Call by Reference or Start Asynchronous Call, you must wire a strictly typed VI reference to this input. The connector pane of the VI specified by vi name must match the connector pane of this input.

datatype_icon

component reference

A reference to a component. By default, this node uses the component reference of the component where the calling VI is located.

datatype_icon

vi name

The name of the VI you want to reference.

The string you wire to the vi name string must match the full delimited name of a VI in memory on that target.

If you want to use the vi reference output with Call by Reference or Start Asynchronous Call, you must wire a strictly typed VI reference to type specifier vi reference. The connector pane of the VI specified by vi name must match the connector pane of type specifier vi reference.

The node does not wait until the user interface is idle, as it does not load a VI from disk.

datatype_icon

error in

Error conditions that occur before this node runs.

The node responds to this input according to standard error behavior.

Standard Error Behavior

Many nodes provide an error in input and an error out output so that the node can respond to and communicate errors that occur while code is running. The value of error in specifies whether an error occurred before the node runs. Most nodes respond to values of error in in a standard, predictable way.

error in does not contain an error error in contains an error
If no error occurred before the node runs, the node begins execution normally.

If no error occurs while the node runs, it returns no error. If an error does occur while the node runs, it returns that error information as error out.

If an error occurred before the node runs, the node does not execute. Instead, it returns the error in value as error out.

Default: No error

datatype_icon

vi reference

A reference to the requested VI.

datatype_icon

error out

Error information.

The node produces this output according to standard error behavior.

Standard Error Behavior

Many nodes provide an error in input and an error out output so that the node can respond to and communicate errors that occur while code is running. The value of error in specifies whether an error occurred before the node runs. Most nodes respond to values of error in in a standard, predictable way.

error in does not contain an error error in contains an error
If no error occurred before the node runs, the node begins execution normally.

If no error occurs while the node runs, it returns no error. If an error does occur while the node runs, it returns that error information as error out.

If an error occurred before the node runs, the node does not execute. Instead, it returns the error in value as error out.

Configuring References for Dynamic VI Calls

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

  • type specifier VI reference (for type only)—Wire a strictly typed VI reference to this input.
  • Item tab—Use the Item tab for this node to configure the type of call you want to make:
    • Enable simultaneous calls on reentrant VIs
      • Prepare for synchronous call—Uses Run VI to run multiple instances of a reentrant target VI in parallel. Setting this option causes the application to allocate a dedicated parallel data space in which a clone of the target VI can run. Without this option, Open VI Reference always returns a reference to the same data space of the original target VI, preventing multiple calls to that VI from executing simultaneously.
      • Prepare for asynchronous call without wait—Prepare to call and forget: Use this option when you want to call a target VI asynchronously with Start Asynchronous Call but you do not need to know when or what the VI returns.
      • Prepare for asynchronous call with wait—Prepare to call and collect: Use this option when you want to collect the results of an asynchronous call to a target VI with Wait on Asynchronous Call. If you use this option, you must include one Wait on Asynchronous Call for every call that you begin with a Start Asynchronous Call node to ensure that the application does not retain any started calls in memory indefinitely.

Criteria for Opening Strictly Typed References

If you wire a strictly typed VI reference to the type specifier VI reference (for type only), the VI that vi name specifies 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 reference (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 otherwise in the Item tab.
  • If you configure the VI reference 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 Call by Reference and Start Asynchronous Call call a clone of the target VI.
  • Equal? 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 Type Cast to convert the references to 32-bit signed integers. Then use Equal? 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 Abort VI. However, VI references prepared for asynchronous execution have important caveats depending on how you configure the reference:

  • Prepare for asynchronous call without wait—A call-and-forget VI aborts only if you manually abort it from its front panel or call Abort VI on it. Otherwise, the VI runs to completion, even if you close the reference or abort the calling VI.
  • Prepare for asynchronous call with wait—Call-and-collect VIs abort for the following reasons:
    • You abort the VI that opened the call-and-collect VI reference. In this case, the application 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 Abort VI on the call-and-collect VI reference. In this case, the application 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 Close Reference. Explicitly closing a reference enables the application to free the resources involved in maintaining that reference, thereby contributing to optimal memory allocation and performance. Otherwise, the application cannot close the reference until the VI that opened the reference finishes executing.

spd-note-note
Note  

Closing a reference that was opened with the Prepare for asynchronous call without wait configuration does not abort the referenced VI.

Where This Node Can Run:

Desktop OS: Windows

FPGA: Not supported

Web Server: Not supported in VIs that run in a web application

Recently Viewed Topics