TagSubscribe

Subscribes a tag so that Cicode functions can be called when a tag's value changes. The subscription checks each poll period whether the tag has changed value and if it has, the specified callback function is called. This avoids continuously polling a tag value to monitor changes. To add a function callback to the subscription, use the optional parameter in this command or the SubscriptionAddCallback function.

Multiple subscriptions are possible to the same tag. Each new subscription returns a new subscription handle. Multiple callbacks are possible to the same subscription.

You can use this function to subscribe to a variable that is an array by specifying an array index in the TagName argument. For example:

TagSubscribe("tag[5]", ...)

When the array value changes, a runtime callback will pass the indexed tag value. If an invalid index value is passed, a hardware error will be generated.

• If a negative array index value is used, an "Invalid argument" hardware alarm will be raised.

• If an index value exceeds the maximum value of the array offset, an "Array overrun" hardware alarm will be raised.

To unsubscribe a tag, use the TagUnsubscribe function.

Syntax

TagSubscribe(STRING TagName [, INT PollTime] [, STRING ScaleMode] [, REAL Deadband] [, STRING Callback] [, INT Lightweight] [, INT NoUpdateForDuplicateValues])

TagName

String representing the tag or tag element or 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 is not specified, it will be resolved at runtime as an unqualified tag reference.

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

PollTime

Optional integer representing the Datasource Poll time in milliseconds (default 250).

ScaleMode

Optional string stating the mode to subscribe. Supported modes are: Raw, Eng, Percent. Default is "Eng".

Deadband

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

Callback

Optional string stating the name of a function to call when the value is updated. If an empty string is specified, no handler is registered. Default value is "" (empty string).

The function should have the structure:

FUNCTION evtHandler([INT handle] [, STRING value] [, QUALITY quality] [, TIMESTAMP timestamp])
...
END

Where:
handle is the subscription that raised the event.
value is the tag value.
quality is the value quality.
timestamp is the value timestamp.

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. For a client to retrieve quality and value timestamps for a tag, you should explicitly specify that a full tag value is required by setting this option to 0.

NoUpdateForDuplicateValues

This optional boolean argument allows you to specify if the subscription accepts duplicated values. Set this value to 1 to indicate that a duplicated update is not required for values that have already successfully written to the device.

Note: ScaleMode and Deadband are ignored for digital tags.

Return Value

Integer representing the subscription handle that can be used to read values, hook to events or unsubscribe. If unsuccessful, -1 is returned and an error is set. Even though a subscription handle is returned immediately, it can't be used to get attributes until the subscription has been confirmed as this is an asynchronous Cicode function call. The typical Cicode error is 423 when a subscription handled is used too soon. We recommend the use of a callback function or the direct use of the tag extension, e.g. <tag>.VT

Related Functions

TagUnsubscribe, SubscriptionAddCallback, SubscriptionGetAttribute, SubscriptionRemoveCallback

Example

The following example subscribes the tag "Conveyor1" in order to manually poll for attributes of the tag.

...

// Get the last changed value, quality and timestamp for the tag every 1s

...

// LOOP START

SleepMs(1000);

ErrSet(1);

convValue = SubscriptionGetAttribute(subsHandle, "Value");

IF IsError() = 0

convQual = SubscriptionGetAttribute(subsHandle, "ValueQuality");

convTime = SubscriptionGetAttribute(subsHandle, "ValueTimestamp");

// Format and use data here

END

// LOOP END

...

// Unsubscribe the tag TagUnsubscribe(subsHandle);

The following example subscribes the "conveyor1" tag as a percentage and polls it every 100ms to check for changes. When the value changes the functions OnValueChanged and ValChanged2 are called. This is the recommended way to do polling of special variables:

...

INT subsHandle = TagSubscribe("Conveyor1", 100, "Percent",

"OnValueChanged");

...

// Later on if no callback was registered initially, a new one can be added.

SubscriptionAddCallBack(subsHandle, "ValChanged2");

...

Function OnValueChanged(INT handle, STRING tagValue, QUALITY valueQuality, TIMESTAMP valueTimestamp)

STRING sTag;

INT qualityGeneral;

INT year;

INT second;

sTag = SubscriptionGetAttribute(handle, "FullName"); // If the name is needed

qualityGeneral = QualityGetPart(valueQuality, 0); // If General Quality value is needed

year = TimestampGetPart(valueTimestamp, 0); // if year part is needed

second = TimestampGetPart(valueTimestamp, 5); // if second part is needed

...

END

...

Function ValChanged2(INT handle, STRING tagValue, QUALITY valueQuality, TIMESTAMP valueTimestamp)

STRING sTag;

INT qualityGeneral;

INT year;

INT second;

sTag = SubscriptionGetAttribute(handle, "FullName"); // If the name is needed

qualityGeneral = QualityGetPart(valueQuality, 0); // if General Quality value is needed

year = TimestampGetPart(valueTimestamp, 0); // if year part is needed

second = TimestampGetPart(valueTimestamp, 5); // if second part is needed

...

END

...

// Remove all callbacks and unsubscribe

TagUnsubscribe(subsHandle);

See Also

Tag Functions