ctListItem

Gets the tag element item data. For specific quality part values please refer to The Quality Tag Element.

Syntax

ctListItem(hTag, dwItem, pBuffer, dwLength, dwMode)

hTag

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

dwitem

Type: DWORD
Input/output: Input
Description: The tag element item:

CT_LIST_VALUE - value.

CT_LIST_TIMESTAMP – timestamp.

CT_LIST_VALUE_TIMESTAMP – value timestamp.

CT_LIST_QUALITY_TIMESTAMP quality timestamp.

CT_LIST_QUALITY_GENERAL - quality general.

CT_LIST_QUALITY_SUBSTATUS - quality substatus.

CT_LIST_QUALITY_LIMIT - quality limit .

CT_LIST_QUALITY_EXTENDED_SUBSTATUS - quality extended substatus.

CT_LIST_QUALITY_DATASOURCE_ERROR - quality datasource error.

CT_LIST_QUALITY_OVERRIDE - quality override flag.

CT_LIST_QUALITY_CONTROL_MODE - quality control mode flag.

pBuffer

Type: VOID*
Input/output: Input
Description: Pointer to a buffer to return the data. The data is returned scaled and as a formatted string.

dwLength

Type: Dword
Input/output: Input
Description: Length (in bytes) of the raw data buffer.

dwMode

Type: DWORD
Input/output: Input
Description: Mode of the data. The following modes are supported:

0 (zero) - The value is scaled using the scale specified in the Citect SCADA project, and formatted using the format specified in the Citect SCADA project.

FMT_NO_FORMAT - The value is not formatted to the format specified in the Citect SCADA project. A default format is used. If there is a scale specified in the Citect SCADA project, it will be used to scale the value.

The dwMode argument no longer supports option FMT_NO_SCALE which allowed you to dynamically get the raw value or the engineering value of a tag in the list. If you wish to get the raw value of a tag, add it to the list with this mode by calling ctListAddEx and specifying bRaw = TRUE..

Return Value

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 the data from the I/O Device, the return value will be FALSE and GetLastError() will return the associated Citect SCADA error code.

Related Functions

ctOpen, ctListNew, ctListFree, ctListAdd, ctListRead, ctListData, ctListWrite

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];

char 	sProcessValueFieldQualityGeneral[20];

char 	sProcessValueFieldQualitySubstatus[20];

char 	sProcessValueFieldQualityLimit[20];

char 	sProcessValueFieldQualityExtendedSubstatus[20];

char 	sProcessValueFieldQualityOverride[20];

char 	sProcessValueFieldQualityControlMode[20];

char 	sProcessValueFieldQualityDatasourceError[20];

char 	sProcessValueFieldTimestamp[20];

char 	sProcessValueFieldValueTimestamp[20];

char 	sProcessValueFieldQualityTimestamp[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);

ctListItem(hTagOneField, CT_LIST_VALUE, sProcessValueField, sizeof(sProcessValueField), 0);

ctListItem(hTagOneField, CT_LIST_TIMESTAMP, sProcessValueFieldTimestamp, sizeof(sProcessValueFieldTimestamp), 0);

ctListItem(hTagOneField, CT_LIST_VALUE_TIMESTAMP, sProcessValueFieldValueTimestamp, sizeof(sProcessValueFieldValueTimestamp), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_TIMESTAMP, sProcessValueFieldQualityTimestamp, sizeof(sProcessValueFieldQualityTimestamp), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_GENERAL, sProcessValueFieldQualityGeneral, sizeof(sProcessValueFieldQualityGeneral), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_SUBSTATUS, sProcessValueFieldQualitySubstatus, sizeof(sProcessValueFieldQualitySubstatus), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_LIMIT, sProcessValueFieldQualityLimit, sizeof(sProcessValueFieldQualityLimit), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_EXTENDED_SUBSTATUS, sProcessValueFieldQualityExtendedSubstatus, sizeof(sProcessValueFieldQualityExtendedSubstatus), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_OVERRIDE, sProcessValueFieldQualityOverride, sizeof(sProcessValueFieldQualityOverride), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_CONTROL_MODE, sProcessValueFieldQualityControlMode, sizeof(sProcessValueFieldQualityControlMode), 0);

ctListItem(hTagOneField, CT_LIST_QUALITY_DATASOURCE_ERROR, sProcessValueFieldQualityDatasourceError, sizeof(sProcessValueFieldQualityDatasourceError), 0);

ctListFree(hList);

Published June 2018