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.

TagSubscribe(sTagName [, iPollTime] [, sScaleMode] [, dDeadband] [, sCallback] [, bLightweight])

String representing the tag or tag element to subscribe to in the form of "<cluster_name>.<tag_name>.<element name>". If the element name is not specified, it will be resolved at runtime as an unqualified tag reference.

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

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

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.

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

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.

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

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   sTag;
 
	 sTag = SubscriptionGetAttribute(handle, "FullName");  // If the name is needed 

	 subsVal = SubscriptionGetAttribute(handle, "Value");

	 subsQual = SubscriptionGetAttribute(handle, "ValueQuality");

...

END

...

Function ValChanged2(INT handle)

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

	 subsVal = SubscriptionGetAttribute(handle, "Value");

	 subsTime = SubscriptionGetAttribute(handle, "ValueTimestamp");

...

END

...

// Remove all callbacks and unsubscribe

TagUnsubscribe(subsHandle);