Adding and Releasing References in LabWindows/CVI

TestStand 2019 Help

Edition Date: May 2019

Part Number: 370052AA-01

»View Product Info
Download Help (Windows Only)

LabWindows/CVI automatically maintains an object reference for each handle you obtain for an object. When you assign the handle to another variable, LabWindows/CVI does not add a reference to the object. Use the CA_DuplicateObjHandle function in the LabWindows/CVI ActiveX Automation Library to obtain a new handle to an existing object, which adds a reference to the object.

LabWindows/CVI automatically releases the object reference for each handle you obtain when you call the CA_DiscardObjHandle function from the LabWindows/CVI ActiveX Automation Library.

The following example shows how to obtain a handle to the TestStand Engine from the SequenceContext object, how to call a method on the engine to acquire a version string, and how to release the handle to the engine and the string.

int GetEngineVersion(CAObjHandle seqContextCVI)


int error = 0;

ErrMsg errMsg = "";

ERRORINFO errorInfo;

CAObjHandle engine = 0;

char *versionString = NULL;

tsErrChk(TS_SeqContextGetEngine(seqContextCVI, &errorInfo, &engine));

tsErrChk(TS_EngineGetVersionString (engine, &errorInfo, &versionString));


// Free Resources

if (engine)


if (versionString)


return error;


Note Note  If you do not release the handle, LabWindows/CVI does not release the object for you. Repeatedly opening references to objects without closing them can cause the computer to run out of memory.

While many of the functions specified in the tsapicvi.fp library are simple wrappers to API methods that require no storage of information, there are several functions, especially those containing Get or New, where TestStand is actively allocating new memory to hold the information. In any instance where you are using a function of this type, you must release the allocated memory at the end of the code using calls to CA_FreeMemory, CA_DiscardObjHandle, or similar functions.

When you are concerned about a function returning a piece of data that must be manually released, refer to the LabWindows/CVI Help or to the NI TestStand Help for that function. Both of these resources explicitly state if the function is allocating memory and often contain additional code fragments explaining how to use the function.

The following are examples of functions that allocate memory:

  • TS_PropertyGetValString()
  • TS_PropertyGetValIDispatch()
  • TS_PropertyGetPropertyObject()
  • TS_NewEngine()
  • TS_SeqFileNewEditContext()
  • TS_EngineNewSequence()

The following example uses one of the previous functions and then releases the memory:

char *stringVal = NULL;

TS_PropertyGetValString (propObj, &errorInfo, "Step.Limits.String", 0, &stringVal);


CA_FreeMemory (stringVal);


Not Helpful