Configuring the Call Library Function Node

»Table of Contents

Use the Call Library Function Node to directly call a 32-bit Windows DLL, a Mac OS Framework, or a Linux Shared Library function. With this node, you can create an interface in LabVIEW to call existing libraries or new libraries specifically written for use with LabVIEW. National Instruments recommends using the Call Library Function Node to create an interface to external code.

Note Be aware when using the Call Library Function Node or writing code that is called by the Call Library Function Node that LabVIEW reserves Windows messages WM_USER through WM_USER+99 for internal use only.

Right-click the Call Library Function Node and select Configure from the shortcut menu to open the Call Library Function dialog box, shown in the following figure. Use the Call Library Function dialog box to specify the library, function, parameters, return value for the object, and calling conventions on Windows. When you click OK in the Call Library Function dialog box, LabVIEW updates the Call Library Function Node according to your settings, displaying the correct number of terminals and setting the terminals to the correct data types.

As you configure parameters, the Function Prototype text box displays the C prototype for the function you are building. This text box is a read-only display.

Configuring for Multiple Thread Operation

In a multithreaded operating system, you can make multiple calls to a DLL or shared library simultaneously. By default, all call library objects run in the user interface thread. The control below the Browse button in the Call Library Function dialog box reflects your selection of Run in UI Thread or Reentrant.

Before you configure a Call Library Function Node to be reentrant, make sure that multiple threads can call the function simultaneously. The following characteristics are the basic characteristics of thread safe code in a shared library:

The code is thread safe when it does not store any global data, such as global variables, files on disk, and so on.
The code is thread safe when it does not access any hardware. In other words, the code does not contain register-level programming.
The code is thread safe when it does not make any calls to any functions, shared libraries, or drivers that are not thread safe.
The code is thread safe when it uses semaphores or mutexes to protect access to global resources.
The code is thread safe when it is called by only one non-reentrant VI.

Setting the Calling Convention

Use the Calling Conventions pull-down menu in the Call Library Function dialog box to select the calling convention for the function. The default calling convention is C.

Windows You also can use the standard Windows calling convention, stdcall.

Refer to the documentation for the DLL you want to call for the appropriate calling conventions.

Configuring Parameters

This section discusses the return value and how to add parameters to the Call Library Function Node.

Initially, the Call Library Function Node has no parameters and has a return type of Void. The return type for the Call Library Function Node returns to the right terminal of the top pair of terminals. If the return type is Void, the top pair of terminals is unused. Each additional pair of terminals corresponds to a parameter in the Parameter list of the Call Library Function Node. To pass a value to the Call Library Function Node, wire to the left terminal of a terminal pair. To read the value of a parameter after the Call Library Function Node call, wire from the right terminal of a terminal pair. The following figure shows a Call Library Function Node that has a return type of Void, a string parameter, and a numeric parameter.

Configuring Return Type

For return type, you can set Type to Void, Numeric, or String. Void is only available for return type and is not available for parameters. Use Void for the return type if your function does not return any values.

Even if the function you call returns a value, you can use Void for the return type. When the function returns a value and you select Void as the return type, the value returned by the function is ignored.

Note If the function you are calling returns a data type not listed, choose a return data type the same data size as the one returned by the function. For example, if the function returns a char data type, use an 8-bit unsigned integer. A call to a function in a DLL cannot return a pointer because there are no pointer types in LabVIEW. However, you can specify the return type as an integer that is the same size as the pointer. LabVIEW then treats the address as a simple integer, and you can pass it to future DLL calls.

Adding and Deleting Parameters

To add parameters to the Call Library Function Node, click the Add a Parameter Before button or the Add a Parameter After button. To remove a parameter, click the Delete this Parameter button.

Editing Parameters

Use the Parameter pull-down menu to select the return value or a parameter for editing. When selected, you can edit the Parameter name to something more descriptive, which makes it easier to switch between parameters. The Parameter name does not affect the call, but it is propagated to output wires. Also, you can edit all fields in the Parameter section for the selected parameter.

Selecting the Parameter Type

Use the Type pull-down menu to indicate the type of each parameter. You can select from the following parameter types:

Numeric
Array
String
Waveform
Digital Waveform
Digital Data
ActiveX
Adapt to Type

After you select an item from the Type pull-down menu, you see more items you can use to indicate details about the parameter and about how to pass the data to the library function. The Call Library Function Node has a number of different items for parameter types because of the variety of data types required by different libraries. Refer to the documentation for the library you call to determine which parameter types to use.

The following sections discuss the different parameter types available from the Type pull-down menu.

Windows Refer to the labview\examples\dll\data passing\Call Native Code.llb for an example of using data types in shared libraries.

Numeric

For numeric data types, you must indicate the exact numeric type by using the Data Type pull-down menu. You can choose from the following data types:

8-, 16-, 32-, and 64-bit signed and unsigned integers
4-byte, single-precision numbers
8-byte, double-precision numbers

Note Extended-precision numbers and complex numbers can be passed by selecting Adapt to Type from the Type pull-down menu. However, standard libraries generally do not use extended-precision numbers and complex numbers.

Use the Pass pull-down menu to indicate whether you want to pass the value or a pointer to the value.

Array

Use the Data Type pull-down menu to indicate the data type of the array. You can choose from the same data types available for numeric parameters.

Specify the dimensions of the array in Dimensions.

Use the Array Format pull-down menu to make one of the following choices:

Array Data Pointer passes a one-dimensional pointer to the array data.
array handle passes a pointer to a pointer that points to a four-byte value for each dimension, followed by the data.
array handle Pointer passes a pointer to an array handle.

Note Do not attempt to resize an array with system functions, such as realloc. Doing so might crash your system. Instead, use one of the Code Interface Node (CIN) manager functions, such as NumericArrayResize.

String

Use the String Format pull-down menu to indicate the string format. You can choose from the following string formats:

C String Pointer—a string followed by a null character
Pascal String Pointer—a string preceded by a length byte
string handle—a pointer to a pointer to four bytes for length information, followed by string data
string handle Pointer

Select a string format that the library function expects. Most standard libraries expect either a C string or a Pascal string. If the library function you are calling is written for LabVIEW, you might want to use the string handle format.

Note Do not attempt to resize a string with system functions, such as realloc, because your system might crash.

Waveform

When you call a shared library that includes a waveform data type, you do not have to specify a numeric value from the Data Type pull-down menu; the default is 8-byte double. However, you must specify a Dimension. If the Parameter is a single waveform, specify a Dimension of 0. If the Parameter is an array of waveforms, specify a Dimension of 1. LabVIEW does not support an array of waveforms greater than 1D.

Digital Waveform

Specify a Dimension of 0 if the Parameter is a single digital waveform. Specify a Dimension of 1 if the Parameter is an array of digital waveforms. LabVIEW does not support an array of digital waveforms greater than 1D.

Digital Data

Specify a Dimension of 1 if the Parameter is an array of digital data. Otherwise, specify a Dimension of 0. LabVIEW does not support an array of digital data greater than 1D.

Note You can pass waveforms, digital waveforms, and digital data through shared libraries, but accessing the data inside the shared libraries is not supported at this time.

ActiveX

Select one of the following items from the Data Type pull-down menu:

ActiveX Variant Pointer passes a pointer to ActiveX data.
IDispatch* Pointer passes a pointer to the IDispatch interface of an ActiveX Automation server.
IUnknown Pointer passes a pointer to the IUnknown interface of an ActiveX Automation server.

Adapt to Type

Use Adapt to Type to pass arbitrary LabVIEW data types to DLLs in the same way they are passed to a CIN. The arbitrary LabVIEW data types are passed to DLLs in the following ways:

Scalars are passed by reference. A pointer to the scalar is passed to the library.
Arrays and strings are passed according to the Data Format setting. You can choose from the following Data Format settings:
- Handles by Value passes the handle to the library. The handle is not NULL.
- Pointers to Handles passes a pointer to the handle to the library. If the handle is NULL, treat the handle as an empty string or array. To set a value when the handle is NULL, you must allocate a new handle.
Clusters are passed by reference.
Scalar elements in arrays or clusters are in line. For example, a cluster containing a numeric is passed as a pointer to a structure containing a numeric.
Clusters within arrays are in line.
Strings and arrays within clusters are referenced by a handle.

Note When one or more of the parameters of the function you want to call in a DLL are of types that do not exist in LabVIEW, ensure that each parameter is passed to the function in a way that allows the DLL to correctly interpret the data. Create a skeleton .c file from the current configuration of the Call Library Function Node. By viewing the .c file, you can determine whether LabVIEW will pass the data in a manner compatible with the DLL function. You then can make any necessary adjustments.

Calling Functions That Expect Other Data Types

You might encounter a function that expects data in a form that the Call Library Function Node cannot pass. Specifically, the Call Library Function Node does not support structures or arrays containing a pointer to other data or structures containing flat arrays that can be variably sized. You can call a function that expects an unsupported data type in the following ways:

If the data contains no pointers, you might be able to use the Flatten to String function to create a string containing the binary image of the data required and pass this string as a C string pointer. You will probably want to use the byte order input to Flatten to String to specify that the data be flattened in native byte order.
Write a library function that accepts the data in the form used by LabVIEW and builds the data structure expected by the other library. This function can then call the other library and retrieve any returned values before returning. Your function will probably accept the data from the diagram as adapt to type, so that any diagram data type can be passed.