TagGetValue

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

TagGetValue

Reads the value, quality and timestamp of a tag based on the tag subscription.

This function sets up an asynchronous subscription that checks at the specified polling period whether the value of a tag has changed. If the function fails to get a value from the tag initially, subsequent calls at periodic intervals retrieve the tag value. Unused subscriptions initiated by the function automatically expire at the end of the timeout period.

This is a non-blocking function.

Syntax

TagGetValue(STRING TagName [, INT Item] [, INT Index] [, LONG PollTime] [, INT ScaleMode] [, REAL Deadband] [, INT Lightweight] [, LONG KeepAliveSeconds])

TagName

String representing the tag/tag element/ the equipment and item name (using equipment.item notation) associated with that tag, to subscribe to in the form of "cluster_name.tag_name.element name" or "cluster_name.equipment. item.element_name". If the element name (for example, 'Field') is not specified, it will be resolved at runtime as an unqualified tag reference. . If you need to access a specific tag element item to get timestamp and quality values, use the nItem parameter as well (for further information, refer to the Tag Extensions documentation in the main help).

Note: Cluster name is optional for single-cluster projects.

If the TagName represents an array, the entire array is subscribed and will be reused. Note that square brackets for array indexing are unsupported. To retrieve values from individual elements of the array, use the nindex parameter.

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

Item

Optional element number to access tag element values. For more information, refer to the Tag Extensions documentation in the main help.

0: Unqualified tag reference (default) – equivalent to empty element name
1: Value. Equivalent to “v” on Tag Extensions.
2: Value timestamp. Equivalent to “vt” on Tag Extensions.
3: Quality. Equivalent to “q” on Tag Extensions.
4: Quality timestamp. Equivalent to “qt” on Tag Extensions.
5: Timestamp. Equivalent to “t” on Tag Extensions.

Index:

Optional index for an array variable. If not specified, it has a default value of 0. Since the TagName parameter does not support array indexing, use the Index parameter to access an element in an array. Note that the address of the first element in an array is 0 (zero).

PollTime

Optional integer representing the Datasource Poll time in milliseconds. Default is 250 milliseconds.

ScaleMode

Optional number to specify scaling mode of subscription.

0: Equivalent to “Eng” (default)
1: Equivalent to “Raw”
2: Equivalent to “Percent”

(Deadband, Lightweight, KeepAliveSeconds: Unchanged.)

Deadband

Optional real value specifying the percentage of the variable tag's engineering range by which a tag needs to change for an update to be sent through the system. Default is -1.0, indicating the deadband specified by the tag definition is to be used.

Note: ScaleMode and Deadband are ignored for Digital tags.

Lightweight

This optional boolean argument indicates whether or not subscription updates use a "lightweight" version of the tag value that does not include a quality timestamp or a value timestamp.

If not used, this option is set to 1 which means lightweight tag values will be used by default.

Note: To retrieve quality and value timestamps for a tag, you need to set the Lightweight option to 0.

KeepAliveSeconds

Optional length of time (in seconds) for which the subscription will remain in memory. The default is 30 seconds. If there are multiple requests to the same tag with different timeout values, only the first timeout value will be taken into account.

Return Value

Returns the value, quality and timestamp of a subscribed tag. The data type of the value returned depends on the type of the subscribed tag and also the tag extension. The quality and timestamp of the subscribed tag are read and passed with the value returned by the function.

Returns 0 for numerical data types or an empty string for strings if an error occurs. A hardware alarm will be also raised for an error. The tag value may be the last known value (LKV) if the quality of the tag is not good.

When a new subscription is being made and while waiting for its initial value, this function may return 0 or an empty string, which is not regarded as an error.

Note:If tag quality is important such that only good quality data values from this function need to be used in your project, you need to monitor the tag quality by calling this function separately with tag extensions. The tag value returned by this function does not reflect the original data quality and it is necessary to specify tag quality item number such as 3 (Quality) on Item argument in order to check the data quality.

Examples

The following example returns the assigned RealPower item tag value on equipment item "Building.External.Light1".

REAL RealPower = TagGetValue("Building.External.Light1.RealPower", 0, 0, 250, 0, -1.0, 1, 30);

The following example returns the value of the "BIT_1" tag.

TagGetValue("BIT_1");

The following example returns the field timestamp of "BIT_1" tag.

TagGetValue("BIT_1.Field", 5, 0, 250, 0, -1.0, 0, 30);

The following example returns the the valid quality timestamp of the StatusEnum item tag value on equipment "Plant.Bottler.Bottle1". Note that lightweight mode is turned off to get quality timestamp values.

TagGetValue("Plant.Bottler.Bottle1.StatusEnum.Valid", 4, 0, 250, 0, -1.0, 0, 30);

The following example returns the value of the 3rd array element of Plot_1. Note that array index starts from zero.

TagGetValue("Plot_1", 0, 2, 250, 0, -1.0, 0, 30);

The following example returns the Quality timestamp of the 1st array element of Plot_1.

TagGetValue(“Plot_1", 4, 0, 250, 0, -1.0, 0, 30);