Call Library Function Dialog Box

Requires: Base Package

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 contains the following components:
  • Library name or path—Specifies the library name or path for the function you are calling. Enter only the library name if the library is in the search path of the system. Enter the entire path if the library is not in the search path of the system. Refer to the KnowledgeBase at ni.com for more information about system search paths.
    
    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 thread—Specifies 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 contains 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 technique to use when passing data to the array.
        • 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.
      • 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.
  
  This tab contains 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 contains the following components:
  • Error Checking Level—Contains the following options:
    • Maximum—Enables the maximum level of error checking for the Call Library Function Node. If you enable the maximum level of error checking, the Call Library Function Node returns 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. The maximum level of error checking also 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. The maximum level of error checking allows LabVIEW to recover from unhandled exceptions that occur during execution of the called shared library or DLL.

      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.
    • 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.