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 CitectSCADA project, and formatted using the format specified in the CitectSCADA project.

FMT_NO_FORMAT - The value is not formatted to the format specified in the CitectSCADA project. A default format is used. If there is a scale specified in the CitectSCADA 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 CitectSCADA 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);