ctListRead

Reads the tags on the list. This function will read tags which are attached to the list. Once the data has been read from the I/O Devices, you may call ctListData()to get the values of the tags. If the read does not succeed, ctListData() will return an error for the tags that cannot be read.

While ctListRead() is pending you are allowed to add and delete tags from the list. If you delete a tag from the list while ctListRead() is pending, it may still be read one more time. The next time ctListRead() is called, the tag will not be read. If you add a tag to the list while ctListRead() is pending, the tag will not be read until the next time ctListRead() is called. You may call ctListData() for this tag as soon as you have added it. In this case ctListData() will not succeed, and GetLastError() will return GENERIC_INVALID_DATA.

You can only have 1 pending read command on each list. If you call ctListRead() again for the same list, the function will not succeed.

Before freeing the list, check that there are no reads still pending. wait for the any current ctListRead() to return and then delete the list.

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

Type: CTOVERLAPPED*
Input/output: Input
Description: CTOVERLAPPED structure. This structure is used to control the overlapped notification. Set to NULL if you want a synchronous function call.

If the function succeeds, the return value is TRUE. If the function does not succeed, the return value is FALSE. To get extended error information, call GetLastError().

If an error occurred when reading any of the list data from the I/O Device, the return value will be FALSE and GetLastError() will return the associated CitectSCADA error code. As a list can contain tags from many data sources, some tags may be read correctly while other tags may not. If any tag read does not succeed, ctListRead() will return FALSE, however, the other tags will contain valid data. You can call ctListData() to retrieve the value of each tag and the individual error status for each tag on the list.

HANDLE	 hList;

HANDLE	 hAlarmOne;

HANDLE	 hAlarmTwo;

hList = ctListNew(hCTAPI, 0);

hTagOne = ctListAdd(hList, "AlarmOne.Paging");

hTagTwo = ctListAdd(hList, "AlarmTwo.Paging");

while (you want the data) {

	 ctListRead(hList, NULL);

  ctListData(hAlarmOne, sBufOne, sizeof(sBufOne), 0);

	 ctListData(hAlarmTwo, sBufTwo, sizeof(sBufTwo) , 0);

}

ctListFree(hList);