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

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

Related Functions

ctOpen, ctListNew, ctListFree, ctListAdd, ctListRead, ctListDatactListWrite

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