C Interface Generator for LabVIEW Project-Style Instrument Drivers Readme (Windows Only)

August 2006

This file contains important information about the C Interface Generator for LabVIEW Project-Style Instrument Drivers. The C Interface Generator for LabVIEW Project-Style Instrument Drivers creates wrapper DLLs with a user-friendly C programming language interface for project-style LabVIEW instrument driver VIs that you specify. With the C Interface Generator for LabVIEW Project-Style Instrument Drivers, you can quickly and easily reuse existing LabVIEW instrument driver functionality in a C programming environment.

System and Tool Requirements
Converting LabVIEW Project-Style Instrument Drivers to C Instrument Drivers
C Interface Generator for LabVIEW Project-Style Instrument Drivers Dialog Box
Working with the Converted Instrument Driver DLLs
Known Issues
Copyright

System and Tool Requirements

You must have the following software installed before you can install and use the C Interface Generator for LabVIEW Project-Style Instrument Drivers:

• Windows 2000/XP
• LabVIEW 8.0 or LabVIEW 8.2 (with Application Builder activated)

Converting LabVIEW Project-Style Instrument Driver VIs to C Instrument Drivers

The C Interface Generator for LabVIEW Project-Style Instrument Drivers generates a C interface for your instrument driver VIs by creating the following important files:

• Raw DLL and header files that include the LabVIEW native data types.
• Wrapper DLL and header files that are familiar to C programmers.

The C Interface Generator for LabVIEW Project-Style Instrument Drivers has two configuration modes (basic and advanced). The advanced mode provides more settings and options when creating the DLL and header files. If you are not familiar with LabVIEW instrument drivers, use the basic configuration.

Complete the following steps to create a C interface for the VIs in your LabVIEW instrument driver.

1. If you have LabVIEW 8.0 or LabVIEW 8.2, select Tools»Instrumentation»Generate C Interface for LabVIEW Driver. If you have a previous version of LabVIEW, select Tools»Generate C Interface for LabVIEW Driver. LabVIEW launches the C Interface Generator for LabVIEW Project-Style Instrument Drivers dialog box.
2. Select the Basic or Advanced option and click the Next button.
3. Enter the path to and filename of the Project library (.lvlib) file that contains the instrument driver VIs you want to convert. You also can use the Browse button to navigate to and select a file.

   Note  Only .lvlib files compatible with LabVIEW 8.0 or LabVIEW 8.2 are supported.

4. Select the Project library (.lvlib) file and Destination Directory and click the Next button.
5. Select the files you want to generate and click the Next button.
6. Review and edit the instrument driver information, if necessary, and click the Next button. LabVIEW includes this information in the generated DLL.
7. (Advanced configuration only) Select which functions to generate by adding or removing checkmarks in the checkboxes to the left of each function. You also can double-click a function name to edit it. The number in the upper right corner of the listbox indicates the number of functions currently selected. Click the Next button.
8. (Advanced configuration only) Review and edit the documentation conversion tasks for each generated function. Documentation conversion includes searching and replacing strings within the functions to be generated. You can complete any of the following tasks:
   • Click in a table cell to edit a conversion task.
   • Click in a blank table cell to add a new conversion task.
   • Click in the Change column and enter Always, Never, or Prompt to always make the change in the help text, never make the change in the help text, or be prompted to accept or skip the change, respectively.
   • Place a checkmark in the Show prompts checkbox if you want to be prompted to accept or skip each change to the help text that has a value of Prompt in the Change column.
9. Click the Next button.
10. Click the Accept or Skip button to accept or skip each proposed change. Click the Accept All or Skip All button to accept or skip all remaining instances of proposed changes. You can edit the help text directly by clicking inside either text box.
11. Review the summary of conversion tasks and click the Next button to convert the LabVIEW instrument driver.
12. (Optional) Click the View the Report button to view the conversion report.
13. (Optional) If you have installed LabWindows™/CVI™, you can click the View Driver In LabWindows/CVI button to review the generated C interface in LabWindows/CVI.
14. Click the Finish button.

C Interface Generator for LabVIEW Project-Style Instrument Drivers Dialog Box

If you have LabVIEW 8.0 or LabVIEW 8.2, select Tools»Instrumentation»Generate C Interface for LabVIEW Driver to display this dialog box. If you have a previous version of LabVIEW, select Tools»Generate C Interface for LabVIEW Driver to display this dialog box.

Use this dialog box to create C-compatible DLL and header files based on LabVIEW instrument driver VIs.

This dialog box includes the following pages and components:

• Choose Configuration.
  • Basic—Use the basic configuration of the C Interface Generator for LabVIEW Project-Style Instrument Drivers.
  • Advanced—Use the advanced configuration of the C Interface Generator for LabVIEW Project-Style Instrument Drivers, in which you specify advanced settings such as selecting the functions to generate during the conversion process and editing documentation conversion tasks.
• Select the LabVIEW instrument driver and destination directory.
  • Library (.lvlib) File—.lvlib file of the LabVIEW instrument driver you want to convert.
  • Browse—Displays a file dialog box in which you can navigate to and select a library (.lvlib) file.
  • Destination Directory—Directory in which to save the generated files. By default the destination directory is the LVtoC subdirectory within the default data directory. For most Windows users, the default data directory is the My Documents\LabVIEW Data folder.
  • Browse—Displays a file dialog box in which you can navigate to and select a directory in which to save the generated files.
• Select the files to generate during the conversion process.
  • Generate DLL and header file—Creates the wrapper DLL and header file for the LabVIEW instrument driver to be converted.
  • Generate driver installer—Creates an installer of the generated instrument driver with C interfaces. The installer checks whether the target computer has the LabVIEW Run-Time Engine installed because the generated instrument driver needs the LabVIEW Run-Time Engine to function correctly.
  • Generate function panel (.fp file)—A .fp file is the LabWindows/CVI-specific function panel file. The component files are installed according to the VXIplug&play Systems Alliance specifications or IVI Foundation specifications. The .h file will be in the same directory as the .fp file or in the IVI or VXIplug&play include directory. The DLL or shared library file will be in the IVI or VXIplug&play bin directory.
  • Convert help text—Enables searching the converted help for terms that are specific to LabVIEW to replace with C language terms.
• Review the instrument driver information.
  • Version number—Specifies the version number for both the raw and wrapper DLLs.
  • Driver Name—Shows the driver name.
  • Driver Prefix—Shows the instrument prefix that the .fp file applies. LabWindows/CVI adds this prefix to all C function names in the function panel tree.
  • Legal copyright—Specifies the copyright for both the raw and wrapper DLLs.
  • Company name—Specifies the company name for both the raw and wrapper DLLs.
  • Description—Specifies the description for both the raw and wrapper DLLs.
• Select functions to generate. (Advanced configuration only)
  • Select All—Places a checkmark next to every function to generate.
  • Deselect All—Removes the checkmark from every function in the list.
  • Edit Name—Enables you to rename the selected VI or folder in the list.
• Select, create, and edit documentation conversion tasks.
  • Change—Select Always, Never, or Prompt to always make the change in the help text, never make the change in the help text, or be prompted to accept or skip the change, respectively.
  • Show prompts—Prompts you to accept or skip each change to the help text that has a value of Prompt in the Change column. If you remove the checkmark from the checkbox, LabVIEW does not prompt you to accept or skip any changes to the help text.
• Accept or skip help string replacement and deletion.
  • Change to—Displays the word or string to replace the highlighted word or string.
  • Accept—Replaces the highlighted word or string with the word or string in the Change to text box.
  • Skip—Makes no changes to the highlighted word or string and continues to the next instance.
  • Accept All—Replaces every instance of the word or string with the word or string in the Change to text box.
  • Skip All—Makes no changes to the remaining instances of the word or string and continues to the next word or string.
• Conversion complete.
  • View the Report—Displays the conversion report in the default Web browser.
  • View Driver in LabWindows/CVI—Opens the LabWindows/CVI project file. This option is available only when LabWindows/CVI 7.0 or later is installed.

Working with the Converted Instrument Driver DLLs

The following partial code sample demonstrates how you might get started with the code converted for the Agilent 34401 instrument driver to retrieve error information. This project library (Agilent 34401.lvlib) is available in the labview\instr.lib\Agilent 34401 directory.

#include "ag34401.h" // the generated wrapper header file

#define STR_LEN 256

#define ELT_LEN 1024

/* Return value of wrapper function call. VI_SUCCESS for success */

ViStatus result = VI_SUCCESS;

/* VISA Resource Name */

ViRsrc VISAResourceName = "GPIB0::22::INSTR"; // VISA Resource Name

/* VISA Session */

ViSession session = VI_NULL;

/* Used for getting string information*/

ViChar BufferString[STR_LEN] = {0};

ViInt32 BufferStringSize = STR_LEN;

ViInt32 BufferStringActualSize = 0;

/* Used for getting measurement points information*/

ViReal64 BufferPoints[ELT_LEN]={0.0};

ViInt32 BufferPointsSize = ELT_LEN;

ViInt32 BufferPointsActualSize = 0;

/* The instrument driver session handle returned by the Initialize ( ) function cannot be used with VISA function calls. The handle only can be used by other instrument driver wrapper functions. */

/* Check for errors. You can call GetLastErrorMsg() following each instrument driver wrapper function. */

if (VI_SUCCESS != result)

{

/* Be sure to use GetLastErrorMsg() to retrieve error information instead of any other functions. The wrapper driver remembers the latest error in a VISA session. You can specify the VISA session to get the latest error information belonging to that VISA session. Once GetLastErrorMsg is called, it clears the latest error information. */

);

}

/* Do configuration work here*/

/* You can put check code here if you want

if(VI_SUCCESS != result) { ag34401_GetLastErrorMsg (?..);}*/

/* Read the measurement data* /

);

/* You can put check code here if you want*/

/* Include other instrument driver calls, such as configure and read functions */

/* Make sure to close the VISA session when all jobs are done.*/

result = ag34401_Close(session);

The C Interface Generator for LabVIEW Project-Style Instrument Drivers also can build an installer if you select the Generate driver installer option. To use this feature, the target computer must have the LabVIEW Run-Time Engine installed with the same version as the LabVIEW environment.

Once you have initially converted your instrument drivers, you might want to update the wrapper code. If you have LabWindows/CVI 7.0 or later, you can modify the generated C source files in LabWindows/CVI and then rebuild the wrapper driver, but you may not create the installer directly within LabWindows/CVI. After you modify the source code, you can recreate the installer using Rebuild.vi, available in your LabVIEW installation directory at labview\project\_DriverLVtoC\ReBuild Installer. Select the LabWindows/CVI project file, fill in the destination folder, and click Rebuild. The new generated wrapper driver and its installer will be saved to the destination folder.

Known Issues

Refer to the KnowledgeBase for the latest information about the C Interface Generator for LabVIEW Project-Style Instrument Drivers.

• The C Interface Generator for LabVIEW Project-Style Instrument Drivers creates DLLs that you can access interactively from a function panel in LabWindows/CVI 8.0 and later. LabWindows/CVI 7.1 and earlier are not supported. To run correctly in LabWindows/CVI 8.0 and later, the function panel must link to a library file (.lib) instead of a source file (.c), or you can configure LabWindows/CVI to force all project files into the interactive window by selecting Options»Environment and selecting the Force project files into interactive window option. If you continue getting link errors, try rebuilding the generated DLL in LabWindows/CVI.
• The C Interface Generator for LabVIEW Project-Style Instrument Drivers cannot create corresponding DLLs or header files for LabVIEW instrument driver VIs with the following LabVIEW data types:
  • Waveform
  • Array of strings
  • Array of clusters
  • Multi-dimensional arrays (arrays with 2 or more dimensions)
  • Clusters with nesting clusters

  Note  To work around this issue, for each VI that includes an unsupported data type, create a wrapper VI that separates the unsupported data type controls into supported data type controls. For example, for a VI that includes a waveform control, you can create a wrapper VI that includes a timestamp control, a double control, and a double array control on the front panel window. Refer to unsupp_data.html in the labview\project\_DriverLVtoC\Wrapper Sample directory for more details about how to work with unsupported data types.

Copyright

This product includes software developed by the Apache Software Foundation (http://www.apache.org).

Copyright © 1999 The Apache Software Foundation. All rights reserved.

Refer to XercesLicense.txt in the labview\project\_DriverLVtoC directory for more information about the Apache Software License.

© 2006 National Instruments Corporation. All rights reserved.