ctTagReadEx

Performs the same as ctTagRead, but with an additional new argument. Reads the value, quality and timestamp, not only a value. The data will be returned in string format and scaled using the CitectSCADA scales.

The function will request the given tag from the CitectSCADA I/O Server. If the tag is in the I/O Servers device cache the data will be returned from the cache. If the tag is not in the device cache then the tag will be read from the I/O Device. The time taken to execute this function will be dependent on the performance of the I/O Device. The calling thread is blocked until the read is finished.

Syntax

ctTagReadEx(hCTAPI, sTag, sValue, dwLength, pctTagvalueItems)

hCTAPI

Type: Handle
Input/output: Input
Description: The handle to the CTAPI as returned from ctOpen().

sTag

Type: LPCSTR
Input/output: Input
Description: The tag name or tag name and element name, separated by a dot. If the element name is not specified, it will be resolved at runtime as for an unqualified tag reference. You may use the array syntax [] to select an element of an array.

sValue

Type: LPCSTR
Input/output: Output
Description: The tag element value.

dwLength

Type: Dword
Input/output: Input
Description: The length of the read buffer. If the data is bigger than the dwLength, the function will not succeed.

pctTagvalueItems

Type: CT_TAGVALUE_ITEMS
Input/output: Input
Description: The pointer to CT_TAGVALUE_ITEMS structure containing quality and timestamp data or NULL. For specific quality part values, refer to The Quality Tag Element

Return Value

TRUE if successful, otherwise FALSE. Use GetLastError() to get extended error information.

Related Functions

ctOpen, ctTagWrite, ctTagWriteEx

Example

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

char			 sProcessValue[20];

char			 sProcessValueField[20];

char			 sProcessValueControlMode[20];

char			 sProcessValueStatus[20];

CT_TAGVALUE_ITEMS		ctTagvalueItems = {0};

extendedTagData.dwLength = sizeof(CT_TAGVALUE_ITEMS);

ctTagReadEx(hCTAPI, "PV123", sProcessValue, sizeof(sProcessValue), NULL);

ctTagReadEx(hCTAPI, "PV123", sProcessValue, sizeof(sProcessValue), &ctTagvalueItems);

ctTagReadEx(hCTAPI, "PV123.Field", sProcessValueField, sizeof(sProcessValueField), &ctTagvalueItems);

ctTagReadEx(hCTAPI, "PV123.ControlMode", sProcessValueControlMode, sizeof(sProcessValueControlMode), &ctTagvalueItems);

ctTagReadEx(hCTAPI, "PV123.Status", sProcessValueStatus, sizeof(sProcessValueStatus), &ctTagvalueItems);