Purpose

This example demonstrates how to pass a TestStand container as a C-style struct to a function in a LabWindows/CVI DLL. The container consists of several different data types. For a DLL function to change the value of a TestStand container, you must pass the reference of the container to the function.

Example File Location

<TestStand Public>\Examples\Fundamentals\Passing Structs to Code Modules\CVI\Passing Structs to Code Modules.seq

Highlighted Features

• LabWindows/CVI Adapter
• Local variables
• Data types

Major API

None

Prerequisites

You must have the LabWindows/CVI Run-Time Engine installed and you must configure the LabWindows/CVI Adapter to execute steps in-process. If you want to use the Execute Steps in an External Instance of CVI option, you must have the LabWindows/CVI development environment installed.

How to Use This Example

The sequence specifies a CVIStruct container local variable, which you can review on the Variables pane. When the sequence runs, TestStand copies the values in the CVIStruct container to the individual local variables, and then assigns new values to the CVIStruct container. The LabWindows/CVI DLL handles both operations. Before you run the sequence, the CVIStruct container contains values, and the individual local variables contains default values.

Complete the following steps to use this example.

1. Select Execute»Test UUTs to run the sequence.
2. Enter any serial number in the UUT Information dialog box and click OK. TestStand launches a Results for Unpacking dialog box that lists values loaded from the CVIStruct container and assigned to the individual local variables.
3. Click OK in the Results for Unpacking dialog box. TestStand launches another Results dialog box that lists values modified and saved back to the CVIStruct container.
4. Click OK when TestStand informs you that the sequence passed.
5. Click Stop in the UUT Information dialog box to end the execution.

You can review the two Message Popup steps in the sequence to verify that the appropriate sources are providing values. You can open CVIStructTestSource.c, located in the <TestStand Public>\Examples\Fundamentals\Passing Structs to Code Modules\CVI directory, to see how the data is being copied. The PassStructAndUnpack method accesses the values in the CVIStruct container and assigns the values to the individual method parameters. The PassStructAndModify method assigns arbitrary values to the elements of the CVIStruct container by reference. These assignments modify the container in TestStand. The sequence is using CVIStructTest.dll, into which the PassStructAndUnpack and PassStructAndModify methods were built.

To pass a TestStand container as a struct to a DLL, you must define the container as a custom data type, and you must specify that objects of the data type can be passed as structs.

Complete the following steps to use the Types window to review the data type definition for a container.

1. In the Sequence File window, right-click the CVIStruct container on the Variables pane and select View»Type Definition from the context menu to launch the Types window.
2. Right-click the CVIStructExample data type and select Properties from the context menu to launch the Type Properties dialog box. Because the sequence is using a DLL, you must enable C struct passing for the data type.
3. Click the C Struct Passing tab. Notice that the Allow Objects of This Type to be Passed as Structs option is enabled. The Packing ring control specifies the Default Adapter Packing option, which is the packing scheme the LabWindows/CVI DLL uses.
4. Click OK to close the Type Properties dialog box.
5. In the Types window, expand the CVIStructExample data type. You can right-click each property and select Properties from the context menu to launch the Type Properties dialog box for each property of the data type. You can review each property to see how it is configured.