TagReadEx | Tag Functions

Cicode Programming Reference > Cicode Function Categories > Tag Functions > TagReadEx

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

Syntax

TagReadEx(STRING Tag [, INT Offset [, STRING ClusterName]])

Tag:

A string that can be one of the following:

A tag name — for example, "Fire1"
An equipment item reference — for example, "Motor1.Fire"
A tag property — for example, "Fire1.v"
An equipment item property — for example, "Motor1.Fire.v"
An alarm property — for example, "AlarmFire1.On"
An alarm equipment item property — for example, "Motor1.AlarmFire.On"

Currently only the "v" tag extension item is supported by TagRead. References to other extension items will generate an error message. 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, for example, "ClusterName.Tag" or "ClusterName.Equipment.Item".

Note: If the tag name exceeds the length limit of 254 characters the hardware alarm "Tag name exceed length limit" will be raised.

In the example below, assuming the following variable tag, equipment and item are defined in your project :

Tag: PLC_Array

Equipment: PLC

Item: Array

Address: 30000[10]

You can refer to the variable tag using the following syntax:

"PLC_Array"

"PLC.Array"

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

"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, TagRead("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)

Offset:

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

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.
A value and an error code when the tag does not have "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");