TagReadEx

Reads the value, quality or timestamp of a particular tag from the I/O device. The variable tag needs to be defined in the Variable Tags database. Because the variable tag is specified as a string (not as a tag), you can ignore the data type of the variable.

This function is a blocking function. It blocks the calling Cicode task until the operation is complete.

TagReadEx should only be used when the variable tag name is a calculation such as sAlarmExt+".Paging". For simple assignment of variables use the assignment operator. For example, MyString = MyCluster.MyAlarm.MyProperty.

If you try to read many variables at the same time, the TagReadEx() function may be slow. The offset index for array variables is checked against the size of the array.

Note: TagReadEx can only return the values of elements for those tags having "Good" quality. If the quality of a tag is not “Good”, TagReadEx may return an obsolete value (due to TagRead asynchronous nature). Control the returned error/quality while using this function.

Syntax

TagReadEx(STRING sTag [, INT nOffset [, STRING ClusterName]])

sTag:

The string can refer to either the alarm name and the alarm property name or the tag name with optional elements and items as it is defined by Tag Extensions [Cluster.]Tag[.Element][.Item][[N]…] (Refer to Tag Extensions for more information). If the element name is not specified, it will be resolved at runtime as an unqualified tag reference. The name of the tag can be prefixed by the name of the cluster that is "ClusterName.Tag".

To read a particular element in an array, you can enter the array name here, followed by an index to the element as follows:

"PLC_Array[9] "

The above example tells the function to read the 10th element in the array variable PLC_Array (remember, the address of the first element in an array is 0 (zero)).

If you enter an array offset using the nOffset argument, it will be added to the index value specified here. For example, TagReadEx("PLC_Array[9]", 4) will read the 14th element in PLC_Array (because [9] means the 10th element, and an offset of 4 means 4 elements after the 10th = element 14).If you want to read the value of <Valid> element in the above example,

TagReadEx("PLC_Array.Valid.V[9]", 4)

nOffset:

The offset for an array variable. This argument is optional - if not specified, it has a default value of 0.

If you enter an array index as part of the sTag argument, it will be added to this offset value. For example, TagReadEx("PLC_Array[9]", 4) will read the 14th element in PLC_Array (because [9] means the 10th element, and an offset of 4 means 4 elements after the 10th = element 14).

ClusterName:

Specifies the name of the cluster in which the Tag resides. The argument is enclosed in quotation marks.

Return Value

The function can return:

• The tag element value (depending on the sTag parameter, of the I/O device variable) when the tag has “Good” quality.
• The tag element value (depending on the sTag parameter, of the I/O device variable) and the error 257 (can be checked by IsError() built-in function) when the value of the tag is out of the predefined range.
• Some value and an error when the tag has not “Good” quality”.

Related Functions

TagRead, TagWrite, IODeviceControl, IODeviceInfo

Example

STRING sStringTagValue;

STRING sStringTagValueField;

INT nIntTagValue;

REAL fRealTagValue;

// Tag1 has a STRING data type.

sStringTagValue = TagReadEx(“Tag1”);

sStringTagValueField = TagReadEx(“Tag1.Field”);

// Tag2 has an INTEGER data type.

nIntTagValue = TagReadEx(“Tag2”);

// Tag3 has a REAL data type.

fRealTagValue = TagReadEx(“Tag3”);

TIMESTAMP t1 = TagReadEx(”Tag1.T”);

TIMESTAMP t2 = TagReadEx(”Tag1.VT”);

TIMESTAMP t3 = TagReadEx(”Tag1.Qt”);

QUALITY q1 = TagReadEx(”Tag1.Q”);

See Also

Tag Reference /TagReadEx() behavior in Cicode Expressions

Tag Functions