ctListAdd

Adds a tag or tag element to the list. Once the tag has been added to the list, it may be read using ctListRead() and written to using ctListWrite(). If a read is already pending, the tag will not be read until the next time ctListRead() is called. ctListWrite() may be called immediately after the ctListAdd() function has completed.

Note: There is no limit on the number of lists you can add using this function. However, an excessive number of lists may impact system performance. This will be determined by a combination of computer specifications, server/client load and project size.

Syntax

ctListAdd(hList, sTag)

hList

Type: HANDLE
Input/output: Input
Description: The handle to the list, as returned from ctListNew().

sTag

Type: LPCSTR
Input/output: Input
Description: The tag or tag name and element name, separated by a dot to be added to the list. If the element name is not specified, it will be resolved at runtime as for an unqualified tag reference.

Variable tags can be specified as a string in multiple forms. Refer to Tag Names for more information.

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()

If a tag not currently defined in your system is specified using this function then the return value will specify a valid handle. Calling ctListData will allow identification of the true state of the tag. Passing an empty tag to this function will result in the function exiting immediately and returning NULL.

Related Functions

ctOpen, ctListNew, ctListFree, ctListRead, ctListWrite, , ctListAddEx

Example

HANDLE hCTAPI;

HANDLE hList;

HANDLE hTagOne;

HANDLE hTagOneField;

HANDLE hTagOneControlMode;

HANDLE hTagOneStatus;

char sProcessValue[20];

char sProcessValueField[20];

char sProcessValueControlMode[20];

char sProcessValueStatus[20];

hCTAPI = ctOpen(NULL, NULL, NULL, 0);

hList = ctListNew(hCTAPI, 0);

hTagOne = ctListAdd(hList, "TagOne");

hTagOneField = ctListAdd(hList, "TagOne.Field");

hTagOneControlMode = ctListAdd(hList, "TagOne.ControlMode");

hTagOneStatus = ctListAdd(hList, "TagOne.Status");

ctListRead(hList, NULL);

ctListData(hTagOne, sProcessValue, sizeof(sProcessValue), 0);

ctListData(hTagOneField, sProcessValueField, sizeof(sProcessValueField) , 0);

ctListData(hTagOneControlMode, sProcessValueControlMode, sizeof(sProcessValueControlMode) , 0);

ctListData(hTagOneStatus, sProcessValueStatus, sizeof(sProcessValueStatus) , 0);

ctListFree(hList);