You are here: NI Home > Support > Product Reference > Manuals > LabVIEW 8.5 Help

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 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 application, you would use the path My HD:\LabVIEW VIs\foo.vi. Conversely, to reference a VI on a Windows computer at C:\labview\foo.vi from a Mac OS application, wire the path C:labview:foo.vi.
	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. 0x01 Record 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. 0x02 Open 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. 0x04 Prompt 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. 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.  0x10 Prompt user to find missing subVIs of the referenced VI. 0x20 Do not display the Find dialog box or prompt user to find missing subVIs of the referenced VI.
	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 occurred 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 nonzero error code. If status is FALSE, code is 0 or a warning code. source specifies 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.
	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 front panel indicator 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 nonzero 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 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 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 FacadeVI 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 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.