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

Call Library Function Dialog Box

LabVIEW 2013 Help

Edition Date: June 2013

Part Number: 371361K-01

»View Product Info

Requires: Base Development System

Right-click a Call Library Function Node on the block diagram and select Configure from the shortcut menu to display this dialog box.

Use this dialog box to specify the library, function, parameters, return value for the object, and calling convention for a call to a shared library. When you click the OK button in the dialog box, LabVIEW updates the object on the block diagram. The object reflects the settings from this dialog box, displaying the correct number of terminals and setting the terminals to the correct data types.

This dialog box includes the following components:

  • Function—Use the Function tab to configure the Call Library Function Node.

    This tab includes the following components:
    • Library name or path—Specifies either the name or the path for the library you are calling. These two techniques are not interchangeable and produce different consequences when you distribute or relocate your VIs and applications. Refer to Specifying the Location of Shared Libraries on Disk for more information about when to specify a shared library by name or by path.

      To make the reference platform independent, use the * wildcard. If you use the C++ compiler, the names of the functions in the library are altered by a process called name mangling and are platform dependent. Keep the C++ compiler from introducing platform dependence in exported function names through a process called name mangling by using the C++ compiler function export directive, extern "C"{}, in your header file.
    • Specify path on diagram—Determines if you can input the Library name or path on the block diagram. When you place a checkmark in this checkbox, path in and path out appear as input and output terminals on the connector pane for the node. When you place a checkmark in the checkbox, any library referenced in the Library name or path control will not be used.
      Tip  You can use the path in input to unload a previously referenced library from memory. Wire an empty or invalid path to the path in input to unload any library previously referenced by the node from memory.
    • Function name—Specifies the name of the function you are calling.
      Note  When you reference a library, the Function name control is populated with the function names found in that library.
    • Thread—Controls whether the Call Library Function Node switches from the thread the VI is currently executing in to the user interface thread or continues in the currently executing thread. The default is Run in UI thread.
      • Run in UI thread—Specifies the Call Library Function Node execution must switch from the current thread to the user interface thread. Execution in the UI thread of a LabVIEW-built shared library that is dynamically loaded using Specify path on diagram causes LabVIEW to hang.
      • Run in any threadSpecifies that the Call Library Function Node execution continues on the current thread executing the VI. You must make sure that multiple threads can call the function simultaneously.
        Note  All calls to LabVIEW-built shared libraries should specify Run in any thread. If you configure the Call Library Function Node using LabVIEW-built shared libraries and specify Run in UI thread, LabVIEW might hang and require you to restart.
    • Calling convention—Specifies the calling convention for the function. The default is C.
      • stdcall (WINAPI)—Controls whether the object uses the __stdcall calling convention.
      • C—Controls whether the object uses the __cdecl calling convention.
    • Function prototype—Displays the C prototype for the function. This is a read-only display.
  • Parameters—Use the Parameters tab to configure the parameters of the Call Library Function Node.

    This tab includes the following components:
    • Parameters—Lists the current parameters for the Call Library Function Node. You can configure the Parameters list using the following buttons along the right side of the Parameters list. Return type is a required parameter that you cannot delete. Refer to Configuring the Call Library Function Node for more information about configuring parameters.
      • Add a parameter—Adds a parameter below the selected parameter from the Parameters list.
      • Delete the selected parameter—Deletes the selected parameter from the Parameters list.
      • Move the selected parameter up one—Moves the selected parameter up one level in the Parameters list, which modifies the order of the parameters in the function prototype.
      • Move the selected parameter down one—Moves the selected parameter down one level in the Parameters list, which modifies the order of the parameters in the function prototype.
    • Current parameter—Allows you to configure the settings for the selected parameter.
      • Name—Specifies the parameter name.
      • Type—Specifies the data type of the parameter.
        • Numeric—Specifies to use the Numeric data type.
          • Data type—Specifies the exact type of the data selected in the Type control.
            Note  If you use the Signed Pointer-sized Integer or Unsigned Pointer-sized Integer numeric data types, the Call Library Function Node adapts to the specific operating system it is being executed on and returns data of the appropriate size to the library function. On 64-bit platforms LabVIEW translates these numeric data types to 64-bit integer types. On 32-bit platforms LabVIEW translates the numeric data types to 32-bit integer types.
          • Pass—Indicates whether you want to pass the value or a pointer to the value.
        • Array—Specifies to use the Array data type.
          • Data type—Specifies the exact type of the data selected in the Type control.
            Note  If you use the Signed Pointer-sized Integer or Unsigned Pointer-sized Integer numeric data types, the Call Library Function Node adapts to the specific operating system it is being executed on and returns data of the appropriate size to the library function. On 64-bit platforms LabVIEW translates these numeric data types to 64-bit integer types. On 32-bit platforms LabVIEW translates the numeric data types to 32-bit integer types.
          • Dimensions—Specifies the dimensions of the parameter.
          • Array format—Specifies the array format to use.
          • Minimum size—Indicates the minimum size of a 1D array and allocates the correct amount of memory. You can enter a numeric value, or, if you configure an integer parameter in the Parameters list, you can select the parameter from the pull-down menu. The default is none. This option is available only for array data pointers. If you pass in an array that is smaller than the minimum size, LabVIEW enlarges the size of the array to the minimum. If you pass in an array that is bigger than the minimum, the array retains the larger size.
        • String—Specifies to use the String data type.
          • String format—Specifies the string format to use.
          • Minimum size—Indicates the minimum size of the string and allocates the correct amount of memory. You can enter a numeric value, or, if you configure an integer parameter in the Parameters list, you can select the parameter from the pull-down menu. The default is none. This option is available only for C string pointers. If you pass in a string that is smaller than the minimum size, LabVIEW enlarges the size of the string to the minimum. If you pass in an string that is bigger than the minimum, the string retains the larger size.
        • Waveform—Specifies to use the Waveform data type. You must specify the exact numeric data type in the Data Type pull-down menu.
          • Data type—Specifies the exact type of the data selected in the Type control.
          • Dimensions—Specifies the dimensions of the parameter. If the parameter is a single waveform, specify Dimensions as 0. If the parameter is an array of waveforms, specify Dimensions as 1. LabVIEW does not support an array of waveforms greater than one-dimensional.
        • Digital Waveform—Specifies to use the Digital Waveform data type.
          • Dimensions—Specifies the dimensions of the parameter. Specify Dimensions as 0 if the parameter is a single digital waveform. Specify Dimensions as 1 if the parameter is an array of digital waveforms. LabVIEW does not support an array of digital waveforms greater than one-dimensional.
        • Digital Data—Specifies to use the Digital Data data type.
          • Dimensions—Specifies the dimensions of the parameter. Specify Dimensions as 1 if the parameter is an array of digital data. Otherwise, specify Dimensions as 0. LabVIEW does not support an array of digital data greater than one-dimensional.
        • ActiveX—Specifies to use the ActiveX data type.
          • Data type—Specifies the exact type of the data selected in the Type control.
        • Adapt to Type—Specifies to use the Adapt to Type data type.
          • Data format—Specifies the format of the data selected in the Type control.
            • Allow Resize—Specifies whether the library is allowed to resize the parameter. In some cases you can avoid creating extra copies in memory if you do not allow resizing. LabVIEW disables this option if the Constant checkbox contains a checkmark because you cannot resize a constant parameter.
              Note  This option is available only if you select Interface to Data from the Data format pull-down menu.
        • Instance Data Pointer—Specifies to use the Instance Data Pointer data type. The instance data pointer references a pointer sized allocation that you may use at your own discretion. This allocation is also passed to each of the callback functions on the Callbacks tab.
      • Constant—Indicates whether the parameter is a constant.
    • Function prototype—Displays the C prototype for the function. This is a read-only display.
  • Callbacks—Use the Callbacks tab to specify functions to call at predefined times. The functions allow you to initialize, update, and/or cleanup data for the DLL or shared library based on the particular instance of the Call Library Function Node you are configuring. Each call passes in the Instance Data Pointer for the Call Library Function Node the function is configured for.

    Note  You cannot use the Callback tab to pass callback functions as parameters to library functions. The Call Library Function Node cannot directly call library functions that require a callback function as a parameter, but you can create a wrapper library to implement such calls.
    This tab includes the following components:
    • Reserve—Specifies the function to call at reserve time for each node and dataspace instance of a reentrant VI.
    • Unreserve—Specifies the function to call at unreserve time for each node and dataspace instance of a reentrant VI. Use the unreserve callback to save or analyze the information and carry out clean up operations.
    • Abort—Specifies the function to call if you abort a VI while a call to a shared library or DLL is in progress. If the Call Library Function node is set to run in the UI thread, the Abort process is not called. Use the abort callback to save or analyze the information and carry out clean up operations.
    • Prototype for these procedures—Displays the C prototype for the user-defined procedure calls. Each function passes an InstanceDataPtr parameter. This parameter allows you to initialize and access data for this instance of the Call Library Function Node that can be passed to any function the node calls. The prototype may be typecast to any type that may be held in a pointer type, including a numeric value or an actual pointer to a structure allocated by the shared library or DLL.

      This is a read-only display.
    • Function prototype—Displays the C prototype for the function. This is a read-only display.
  • Error Checking—Use the Error Checking tab to specify the error checking level for the Call Library Function Node.

    This tab includes the following components:
    • Error Checking Level—Contains the following options:
      • Maximum—Enables the maximum level of error checking for the Call Library Function Node. In addition to the error checking capabilities of the Default level, the Maximum level causes the Call Library Function Node returns a warning if the function being called in the shared library or DLL writes beyond the space allocated for the specified string or array parameter.
        Note  Selecting the Maximum control on the Error Checking tab reduces the execution speed and increases the memory usage of the Call Library Function Node. Therefore, you should select the Maximum control only when debugging your configuration of the Call Library Function Node.
      • Default—Enables the default level of error checking for the Call Library Function Node. The default level of error checking allows LabVIEW to recover from unhandled exceptions that occur during execution of the called shared library or DLL. This error checking level also causes the Call Library Function Node to return an error if the Calling convention you select on the Function tab does not match the calling convention of the function you are calling in the shared library or DLL.
      • Disabled—Disables error checking for the Call Library Function Node. Disabling error checking for the Call Library Function Node improves the execution speed of the Call Library Function Node. However, certain errors can cause an irregular shutdown of LabVIEW. Before disabling error checking, be sure that the function the Call Library Function Node references does not raise any unhandled exceptions.
    • Function prototype—Displays the C prototype for the function. This is a read-only display.

You can use the Call Library Function Node to call code written in text-based programming languages. If you want to call a shared library that contains ActiveX objects, use the Automation Open function with the Property Node and the Invoke Node.


 

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