LabWindows/CVI Tip: Modify Instrument Drivers Programmatically

[Anna_K.]

Automating Tasks with the LabWindows/CVI ActiveX Automation Interface

LabWindows/CVI has the ability to act as an automation server. This means that you can control the LabWindows/CVI Development Environment within other automation controllers. For example, you can move files in and out of LabWindows/CVI projects, compile a file, or build a project from within some other application. In this LabWindows/CVI Tip, we will use the LabWindows/CVI ActiveX Automation Interface to programmatically make changes to a instrument driver. For other examples using LabWindows/CVI as an automation server select Help » Find Examples in the LabWindows/CVI menu and then navigate to Communicating with External Applications » ActiveX » CVI.

Steps for Automating LabWindows/CVI

1. ActiveX Automation Controller To instantiate objects of any ActiveX server, we must generate an API to access the properties and methods of the ActiveX server. This can be done by creating an ActiveX controller using the ActiveX Controller Wizard provided by LabWindows/CVI in the Tools menu, which generates an instrument driver for the ActiveX Server class. In this case, the instrument driver that corresponds to the LabWindows/CVI automation server that we want to use already exists in the samples directory: "C:\Users\Public\Documents\National Instruments\<cvidir>\samples\activex\cvi\cvisrvr.fp", so there is no need to use the ActiveX Controller Wizard.
   • Add cvisvr.fp to your project
   • Include "cvisrvr.h" in your source file
     
     
2. Determine which instance of LabWindows/CVI is used for Automation When automating LabWindows/CVI from within another LabWindows/CVI program, you must identify which instance you want to manipulate. This is most important during development and debugging because at least one instance of LabWindows/CVI is already running. Best practice is to launch a new instance of LabWindows/CVI, when debugging, so as to not interfere with the "development" instance. You may choose to define these scenarios and switch between them easily using #define NEWAPP:

// hCVIApp will be our handle to the LabWindows/CVI server instance

#ifdef NEWAPP

    // Launch new instance of LabWindows/CVI to automate (Best for debugging and performing "one-off" tasks)

    CVI_NewApp (NULL, 1, LOCALE_NEUTRAL, 0, &hCVIApp);

#else

     // Create a handle for the currently running instance of LabWindows/CVI (Best for automating tasks as part of development)

    CVI_ActiveApp(NULL,1,LOCALE_NEUTRAL,0, &hCVIApp);

#endif

If launching a new instance of LabWindows/CVI, be sure to close it properly at the end of your program. Also, always remember to discard automation handles:

//Close LabWindows/CVI and cleanup

#ifdef NEWAPP

    CVI_AppExitCVI (hCVIApp, NULL, 0, &retVal);

#endif

    CA_DiscardObjHandle (hCVIApp);

Steps for Programmatically Modifying Instrument Drivers

Using the LabWindows/CVI Server objectHandle Now that we have a reference to the LabWindows/CVI automation server, you will pass this reference to any of the LabWindows/CVI server functions. For a complete alphabetical list of LabWindows/CVI server functions, reference the Help topic here.

1. Open a reference to the Instrument Driver you wish to modify
   CVI_AppFPGenOpenFunctionTree (CAObjHandle objectHandle, ERRORINFO *errorInfo, const char *fpFilePathname, long *treeId, long *returnValue);
2. Insert a new class in the function tree
   CVI_AppFPGenInsertClassInTree (CAObjHandle objectHandle, ERRORINFO *errorInfo, long treeId, const char *className, long prevNodeIndex, long asChild, const char *classHelp, long *classIndex, long *returnValue);
3. Insert a new function in the function tree
   CVI_AppFPGenInsertFunctionInTree (CAObjHandle objectHandle, ERRORINFO *errorInfo, long treeId, long functionId, long prevNodeIndex, enum CVIEnum_CVIFPGenFunctionInsertLocation insertLocation, long *newNodeIndex, long *returnValue);
4. Create a new function panel
   CVI_AppFPGenCreateFunctionPanel (CAObjHandle objectHandle, ERRORINFO *errorInfo, const char *fpNodeName, const char *functionName, const char *qualifierStr, const char *helpStr, long *functionId, long *returnValue);
5. Add a parameter to the end of a function parameter list
   CVI_AppFPGenAddParamToFunction (CAObjHandle objectHandle, ERRORINFO *errorInfo, long functionId, long paramId, long *returnValue);
6. Add a custom data type to the list of data types that can be used in the specified instrument driver
   CVI_AppFPGenAddCustomDataType (CAObjHandle objectHandle, ERRORINFO *errorInfo, long treeId, const char *newTypeName, enum CVIEnum_CVIFPGenIntrinsicDataType intrinsicDataType, long *returnValue);
7. Delete a specified node from the function tree
   CVI_AppFPGenDeleteNode (CAObjHandle objectHandle, ERRORINFO *errorInfo, long treeId, long nodeIndex, long *returnValue);

To learn from a running example that demonstrates the use of these functions, please refer to the fpeditor.cws example found in the Example Finder under Communicating with External Applications » ActiveX » CVI This example demonstrates the use of the LabWindows/CVI ActiveX server to generate an instrument driver function tree (FP) programmatically. Although using the LabWindows/CVI ActiveX Automation Interface is a great way to programmatically modify an existing instrument driver, it is not the recommended way to generate an instrument driver.  A future LabWindows/CVI Tip topic will be dedicated to recommended best practices for generating new instrument drivers. This example also uses the Microsoft TreeView ActiveX control and the Lists structure functions from the Programmer's toolbox.

There are many other functions available for manipulating a instrument driver programmatically, for a complete list, please refer to the Alphabetical List of LabWindows/CVI Server Functions Help Topic.

Did you find this tip useful? Rate this document or add a comment.

If you give this a try, share your experience! Add a comment below.