2

Shared Libraries (DLLs)

This chapter describes how to call shared libraries—called DLLs on the Windows platform—from LabVIEW. Examples and troubleshooting information appear later in the chapter to help you build and use DLLs and configure LabVIEW’s Call Library Function successfully. The general methods described here for DLLs also apply to other types of shared libraries.

Calling Shared Libraries

Use Call Library Function to call a 32-bit Windows DLL, a Macintosh

Code Fragment, or a UNIX Shared Library function directly.

The diagram on the left shows the Call Library Function object on the block diagram. You access this function on the Functions»Advanced palette.

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

Note The shortcut menu for the Call Library Function object also contains the Create .c File item, which creates a .c prototype file that contains C declarations for the parameters that you are passing.

© National Instruments Corporation

2-1

Using External Code in LabVIEW

Chapter 2 Shared Libraries (DLLs)

Figure 2-1. Call Library Function Dialog Box

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

The return value for the function returns to the right terminal of the top pair of terminals of the object. If there is no return value, this pair of terminals is unused. Each additional pair of terminals corresponds to a parameter in the functions parameter list. To pass a value to the function, wire to the left terminal of a terminal pair. To read the value of a parameter after the function call, wire from the right terminal of a terminal pair.

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 object to be reentrant, make sure that multiple threads can call the function(s) simultaneously. The following list shows the basic characteristics of thread safe code in a shared library.

•The code is thread safe when it stores no global data (for example, no global variables, no files on disk, and so on); does not access any

Using External Code in LabVIEW

2-2

www.ni.com

Chapter 2 Shared Libraries (DLLs)

hardware (in other words, does not contain register-level programming); and makes no 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.

Refer to the Execution Properties page topic in LabVIEW Help for more information about reentrancy. Refer to the Using LabVIEW to Create Multithreaded VIs for Maximum Performance and Reliability Application Note for more information about multithreading in LabVIEW.

Calling Conventions (Windows)

Use the Calling Conventions pull-down menu in the Call Library Function dialog box to select the calling conventions for the function. The default calling convention is C. You can also use the standard Windows calling convention, __stdcall. Refer to the documentation for the DLL you want to call for the appropriate calling conventions.

Parameters

Initially, Call Library Function has no parameters and has a return value of

Void. To add parameters to the function, click the Add a Parameter

Before or After buttons. To remove a parameter, click the Delete this

Parameter button.

Use the Parameter pull-down menu to select different parameters or the return value. 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.

Use the Type pull-down menu to indicate the type of each parameter.

The return type can be Void, meaning the function does not return a value,

Numeric, or String.

For parameters, you can select Numeric, Array, String, Waveform,

ActiveX, or 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 data type and about how to pass the data to the library function. Call Library Function has a number of different items for data types, because of the variety of data types required

© National Instruments Corporation

2-3

Using External Code in LabVIEW

Chapter 2 Shared Libraries (DLLs)

by different libraries. Refer to the documentation for the library you call to determine which data types to use.

•Void—Accepted only for the return value. This value is not available for parameters. If your function does not return any values, use Void for the return value.

•Numerics—For numeric data types, you must indicate the exact numeric type using the Data Type pull-down menu. Valid types include the following:

–Signed and unsigned 8-bit, 16-bit, and 32-bit integers

–Four-byte, single-precision numbers

–Eight-byte, double-precision numbers

You cannot use extended-precision numbers and complex numbers.

Standard libraries generally do not use them.

You also must use the Pass pulldown menu to indicate whether you want to pass the value or a pointer to the value.

•Arrays—Indicate the data type of arrays using the same items as for numeric data types, the number of dimensions, and the format to use in passing the array. Use the Array Format pull-down menu to make one of the following choices:

–Array Data Pointer—Passes a pointer to the array data.

–Array Handle—Passes a pointer to a pointer to a four-byte value for each dimension, followed by the data.

–Array Handle Pointer—Passes a pointer to an array handle.

Caution Do not attempt to resize an array with system functions, such as realloc. Doing so might crash your system. Instead, use one of the CIN manager functions, such as

NumericArrayResize.

Strings—Indicate the string format for strings. Valid values for String Format include C String Pointer, Pascal String Pointer, String Handle, or String Handle Pointer.

Select a string format that the library function expects. Most standard libraries expect either a C string (string followed by a null character) or a Pascal string (string preceded by a length byte). If the library function you are calling is written for LabVIEW, you might want to use the String Handle format, which is a pointer to a pointer to four bytes for length information, followed by string data.

Using External Code in LabVIEW

2-4

www.ni.com