1. How does the C/CVI Standard Prototype Adapter execute code modules?Here is some background information about the C/CVI Standard Prototype Adapter. This information will be useful in the remainder of this document. The C/CVI Standard Prototype Adapter has two options to execute code modules:
- Execute Steps in an External Instance of LabWindows/CVI
- Execute Steps In-Process
Executing Code Modules In-Process
If you execute code modules in-process, TestStand directly calls functions in the DLL, object file, or static library. If you use C source files, TestStand requires that the source file be compiled into an object file to execute it. Later, if you modify the C source file, you need to rebuild the object file before your changes will take effect. For TestStand to reload the modified object file, you will need to select Unload All Modules.
Executing Code Modules in an External Instance of LabWindows/CVI
To execute tests in an external instance of CVI, the adapter launches a copy of CVI and loads an execution server project. You can specify the execution server project to load in the C/CVI Standard Adapter Configuration dialog box. The default project is TestStand\AdapterSupport\CVI\tscvirun.prj.
When a TestStand step calls a function in an object, static library, or DLL file, the execution server project automatically loads the file and executes the function in the external instance of CVI.
If you want a TestStand step to call a function in a C source file, you must include the C source file in the execution server project before you run the project. Also, you must include all support libraries other than
LabWindows/CVI libraries in the project.
You can specify a different project, create a new project, or modify the default project to meet your needs. If you create a different project , we recommend that you use the Create feature in the C/CVI Standard Adapter Configuration dialog to ensure that you include the correct files and configure the settings correctly.
2. Which Module Type Should I Use?
When using the C/CVI Standard Prototype Adapter, the first decision you should make is what module type to use. The C/CVI Standard Prototype Adapter can call DLLs, C source files, object files, and static libraries. You can interactively debug DLLs and C source files, while you cannot interactively debug object files or static libraries. Execution speed is about the same for all four types of code modules. During the development phase, object files and static libraries offer no significant advantages over DLLs or C source files. Now, the choice is whether to use DLLs or C source files for test code modules and instrument drivers. If you decide to use C source files, after you finish the development, you can simply create object files and distribute these rather than the C source files. When executing code modules in-process, if you specify C source module, TestStand will look for the corresponding .obj file. Therefore your modules’ specification does not need to change. The next part of this document explains the advantages and disadvantages of using DLLs or C source files.
Debugging Code Modules
When executing code modules in-process, the only code modules you can debug are DLLs that you create for debugging in CVI. To do so, you must launch the sequence editor or operator interface from CVI. For more information, refer to Chapter 12, Module Adapters, in the TestStand User Manual.
If you execute code modules in an external instance of CVI, you can interactively debug your C source files or DLLs from TestStand. To interactively debug DLLs, you must create your DLLs with DLL debugging enabled using the same version of CVI that you use to debug your DLLs. You do not need to launch TestStand from CVI. To interactively debug C source files, you must add your source file(s) to the project that contains the execution server.
Managing CVI Projects
When using a DLL, the C/CVI Standard Prototype Adapter requires two distinct CVI projects: one project which loads the execution server for interactive debugging and a separate project for creating your DLL and editing your source code.
If you use C source modules in all of your CVI Steps then you only need one CVI project for editing and interactive debugging. Insert your source files into the tscvirun.prj project or create a new project by clicking the Create button in the C/CVI Standard Adapter Configuration dialog.
However, if you use DLLs, object files, or static library code modules, then TestStand opens other projects for code editing because every DLL and Static library requires its own project that instructs CVI how to build that particular library or DLL. CVI and other compilers use project files to store the information they need to rebuild the DLL or Library. There can be any number of source files and instrument drivers that make up a DLL or Library.
3. Location and Type of Subsidiary Code Modules
TestStand directly loads and runs the code modules that you specify in the Specify Module dialog for the C/CVI Standard Prototype Adapter. Most likely, your code modules will call other subsidiary code modules and libraries, i.e. instrument drivers. The subsidiary code may be in a DLL, C source file, static library, or object file. The location of code modules may be an issue when distributing or debugging your application.
Subsidiary DLL Code Modules
DLLs provide more flexibility in the organization of the various software components. The operating system finds the subsidiary DLLs using the search directory precedence listed below:
- The directory from which the user loads the application
- The current working directory
- Under Windows 95, the Windows system directory. Under Windows NT, the Windows system32 and system directories
- The Windows directory
- The directories listed in the PATH environment variable
There is no need to preload any DLL into memory before one of its functions is called. In addition, if your DLL was created with the DLL debugging option, you can debug into your subsidiary DLLs.
Subsidiary C Source Files
If you execute code modules in-process, you can use C source files for your “subsidiary” modules by compiling the source files into your DLL, object, or static library file.
If you execute code modules in an external instance of CVI, you can use C source files for your subsidiary code if you include the source files in the execution server project before you run the project. The location of these source files doesn’t matter.
You can debug into the C source files. If you later decide to use the C/CVI Standard Prototype Adapter in-process, you must build your source file into a DLL, object, or static library file.
Subsidiary Object Files and Static Libraries
If your subsidiary code modules are object or static library files and your code modules are NOT DLLs, the subsidiary code modules must be loaded into memory before you can call your code modules that use them. If you execute code modules in an external instance of CVI, include your object or static library files in the execution server project before you run the project. The location of these code modules does not matter.
When running tests in-process, the adapter must load the subsidiary code modules that the object file or static library file depends on before it loads the file.
You can configure a list of support libraries for the adapter to load by clicking on the Configure Auto-loading of Support Libraries Needed for Linking .objs and .libs button on the C/CVI Standard Adapter Configuration dialog box. This feature copies the support libraries to the TestStand\AdapterSupport\CVI\AutoLoadLibs directory. The adapter preloads the code modules in the TestStand\AdapterSupport\CVI\AutoLoadLibs directory.
The auto-load feature also stores the original path of the object or static library files in the TestExec.ini file If these files are updated, the TestStand Engine will automatically copy the new version to the AutoLoadLibs directory the next time that you launch the TestStand application.
Note: If the object or static library files are updated but placed somewhere other than the original directory from which it was added to TestStand, then TestStand will not copy the new version of these files into the AutoLoadLibs directory.
Note: If an object or static library file is modified during interactive debug, then the file in the AutoLoadLibs directory is not updated until the TestStand Engine is terminated and restarted. In TestStand 1.0.2 and later versions, whenever you switch the setting from external process to in-process the adapter updates the files. In addition, after you UnloadAllModules, the adapter updates the files the next time it loads an .obj or static library.
For more information about auto-loading, refer to Chapter 12, Module Adapters, in the TestStand User Manual.
4. UIR File Location
Many applications require user input and/or feedback. CVI applications typically use UIR files for the graphical user interface. If using UIR files, you must ensure that LoadPanel or LoadPanelEx can load your UIR files. When you call LoadPanel or LoadPanelEx, you can use a complete pathname or a simple filename for the Filename parameter. Below are some guidelines on working with user interfaces.
Don’t use UIR Files
CVI 5.5 and later versions have a utility that builds the code to programmatically create your user interface. You can create an object file that you build into your project or auto-load.
Using UIR Files with DLL Code Modules
With DLL code modules, you must use LoadPanelEx rather than LoadPanel. You must also initialize the CVI runtime library in your DLLMain function.
If you use an external instance of CVI, you can specify a simple filename or the complete pathname for the Filename parameter in LoadPanelEx. If you specify a simple filename, place the UIR file in the same directory as the DLL or include the UIR file in the tscvirun.prj project. Either of these locations will ensure that CVI finds the UIR file.
If you use the complete pathname for the Filename parameter in LoadPanelEx, you can use the testData->modPath member to get the path of the module containing the test function and build the absolute path of the UIR file. In this situation, you must ensure that the UIR file will be found in the absolute path that you specify.
If you execute your code modules in-process, you can also use a simple filename or the complete pathname for the Filename parameter in LoadPanelEx. If you use a simple filename, place the UIR file in the same directory as the DLL.
If you use the complete pathname for the Filename parameter in LoadPanelEx, use the testData->modPath member to get the path of the DLL containing the test function and build the absolute path of the UIR file. In this situation, you must ensure that the UIR file will be found in the absolute path that you specify.
Using UIR Files with C Source, Object, or Static Library Files
If using an external instance of CVI, you can use a simple filename or the complete pathname for the Filename parameter in LoadPanel. If you use a simple filename, include the UIR file in the tscvirun.prj project. This ensures that CVI finds the UIR file.
If you use the complete pathname for the Filename parameter in LoadPanel, use the testData->modPath member to get the path of the module containing the test function and build the absolute path of the UIR file. In this situation, you must ensure that the UIR file will be found in the absolute path that you specify.
If executing your code modules in-process (object and static library files), use the complete pathname as explained above. In general, using the complete pathname is the safest approach because it allows you to switch the adapter configuration between in-process and using an external process of CVI with no modifications.
This document explained some of the issues that arise when developing TestStand applications. It explained issues that involve different types of code modules. In addition, the location of subsidiary code modules and UIR files was explained. In conclusion, you can choose the code module types that best suit your needs, but DLLs are often easier to work with than object, C source, or static library files.
TestStand User Manual