TagRead | Tag Functions

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

TagRead

Reads a variable from an I/O device or a local variable. 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.

TagRead is useful 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.

Note: If the Tag property has not been initialized the timestamp value displayed for that tag will be equal to the Unix Epoch, January 1st 1970.

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

Note:TagRead can only return the values of elements for those tags having "Good" quality. If the quality of a tag is not "Good", TagRead returns an empty string. In order to obtain values of tags having not "Good" quality one can use their 'v' item. For example, TagRead("MyBadQualityTag.v"). However, the value returned by a TagRead call on a tag with not "Good" quality may be obsolete (due to TagRead asynchronous nature). Use the IsError Cicode function to control the returned error code when using this function.

Syntax

TagRead(STRING Tag [, INT nOffset [, 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,

TagRead("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 index as part of the sTag argument, it will be added to this offset value. 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).

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.
An empty string and an error code when the tag has not "Good" quality".

Related Functions

TagReadEx, TagWrite, IODeviceControl, IODeviceInfo

Example

STRING sStringTagValue;

STRING sStringTagValueField;

INT nIntTagValue;

REAL fRealTagValue;

// Tag1 has a STRING data type.

sStringTagValue = TagRead("Tag1");

sStringTagValueField = TagRead("Tag1.Field");

// Tag2 has an INTEGER data type.

nIntTagValue = TagRead("Tag2");

// Tag3 has a REAL data type.

fRealTagValue = TagRead("Tag3");