Technical Reference > CtAPI Functions > Function Reference > ctListNew


Creates a new list. The CTAPI provides two methods to read data from I/O Devices. Each level varies in its complexity and performance. The simplest way to read data is via the ctTagRead() function. This function reads the value of a single variable, and the result is returned as a formatted engineering string.

The List functions provide a higher level of performance for reading data than the tag based interface, The List functions also provide support for overlapped operations.

The list functions allow a group of tags to be defined and then read as a single request. They provide a simple tag based interface to data which is provided in formatted engineering data. You can create several lists and control each individually.

Tags can be added to, or deleted from lists dynamically, even if a read operation is pending on the list.


ctListNew(hCTAPI, dwMode)


Type: Handle
Input/output: Input
Description: The handle to the CTAPI as returned from ctOpen().


Input/output: Input
Description: The mode of the list creation. The following modes are supported:

CT_LIST_EVENT - Creates the list in event mode. This mode allows you to use the ctListEvent() function.

CT_LIST_LIGHTWEIGHT_MODE - Setting this mode for a list means any tag updates will use a "lightweight" version of the tag value that does not include a quality timestamp or value timestamp.

These flags can be used in combination with each other.

Return Value

If the function succeeds, the return value specifies a handle. If the function does not succeed, the return value is NULL. To get extended error information, call GetLastError().

Related Functions

ctOpen, ctListFree, ctListAdd, ctListDelete, ctListEvent, ctListRead, ctListWrite, ctListData


HANDLE	 hList;
hList = ctListNew(hCTAPI, 0);
hTagOne = ctListAdd(hList, "TagOne");
hTagTwo = ctListAdd(hList, "TagTwo");
while (you want the data) {
ctListRead(hList, NULL);
ctListData(hTagOne, sBufOne, sizeof(sBufOne), 0);
ctListData(hTagTwo, sBufTwo, sizeof(sBufTwo) , 0);