InTouch Proxy Object

The InTouchProxy Object is a gateway between Galaxy application objects and data that is available through an InTouch™ application. The InTouchProxy object enables you to browse a selected InTouch application tagname dictionary, add selected tags as attributes in the Galaxy application, and then read these attributes from the InTouch application at run time.

Important! Before using the tagname browser to browse for tags, make sure that InTouch WindowMaker is not running on the InTouch node. WindowViewer, however, can be running. Also, be sure that you have given share permission of Read to the InTouch folder that contains the Tagname.X file.

Click one of the following Help topics to navigate to information about that topic.

Overview

The InTouchProxy object is a key member of the core set of AutomationObjects within the ArchestrA system infrastructure. The InTouchProxy object is a DeviceIntegration object that represents a running InTouch node. The InTouch node effectively serves as the data provider (supporting the SuiteLink communication protocol) by providing data points to Galaxy application objects through the InTouchProxy object.

There is a one-to-one relationship between an instance of the InTouchProxy object and a running InTouch node. An InTouch "node" is a unique combination of the computer name and InTouch application. If you want to reference data points in more than one InTouch node, you must configure and deploy more than one InTouchProxy object. For example, you would need to configure one InTouchProxy object to get data from an InTouch application running on Computer1 and another one to get data from an InTouch application running on Computer2.

When you configure the InTouchProxy object, you might want to specify one or more existing InTouch tagnames (items) to use as object attributes. At run time, if these attributes are added in the client (for example, the Object Viewer watch window), they will be updated with the latest values from the InTouch items. InTouch will send a new data value for an item to the InTouchProxy object each time the value changes. Any items that you configure for an InTouchProxy object will automatically become available within the ArchestrA Attribute Browser.

From other objects and from scripts, you can reference the attributes you created for InTouch items. For example, you might configure the input source for a FieldReference object to reference one of these InTouchProxy object attributes. Thus, the FieldReference object's input source would be receiving data from a tag in an InTouch node via the InTouchProxy object. The reference syntax for an InTouchProxy object data point is:

Topic Category	Topic Subcategory	Topic Details
Overview
Run-Time Behavior
Configuration	General Configuration
Items Configuration
Run-Time Object Attributes	Alarm Aggregation Attributes
Alarm Attributes

The <objectname> is the name that you choose to give to the InTouchProxy object.

The group of specified InTouch items for an InTouchProxy object is also known as the "scan group." Only one scan group exists in the InTouchProxy object. Run-time object attributes within the scan group allow you to monitor errors related to the data quality for InTouch item values in a scan group.

Items in a scan group can be “dynamic” in that they can be created or activated dynamically during run time.

The time stamp is retained for attribute values coming from the InTouch HMI. If the quality for a dynamic attribute changes from GOOD to INITIALIZING, BAD, or UNCERTAIN, but the data value does not change, the current time provided by the hosting AppEngine is used.

An InTouchProxy object cannot establish a data connection to an InTouch application running in a terminal session.

For general information on objects, including relationships, deployment, and alarm distribution, see the Integrated Development Environment (IDE) documentation.

For information on configuration options of object scripts, attributes, or features, click Attributes Help in the Help file header.

Run-Time Behavior

The following information describes the run-time behavior of InTouchProxy objects. Run-time behavior is limited to the state of individual InTouchProxy objects.

After it has been deployed and is operating, an InTouchProxy object can assume one of several states, which are described in the following table:


State Change	Behavior
Startup	In this state, the InTouchProxy object connects to the InTouch node.
Going onscan	None.
Running onscan	In this state, the InTouchProxy object: Services read and write requests for tag values in the target InTouch node. Receives updated data from the InTouch node. Sends values to the InTouch node. Monitors and controls the connection to the InTouch node. Detects alarm conditions, if alarming is enabled. Monitors the data quality for InTouch data values and updates run-time error statistics if the quality is not GOOD.
Going offscan	None.
Offscan	The object is passive, and reads and writes to InTouch are not enabled.
Shutdown	In this state, the InTouchProxy object disconnects from InTouch.

An InTouchProxy object cannot establish a data connection to an InTouch application running in a terminal session.

Configuration

The following table describes the object editor options for configuration and the associated attributes:

For general information on objects, including relationships, deployment, and alarm distribution, see the Integrated Development Environment (IDE) documentation.

Topic Category	Topic Subcategory	Topic Details
Configuration	General Configuration
Items Configuration

For information on configuration options of object scripts, attributes, or features, click Attributes Help in the Help file header.

General Configuration

Use the General tab to specify the InTouch node from which to retrieve data and to enable alarming for the data connection.


Editor Option	Associated Attribute	Description	Run-Time Access (Supervisory, User, Read-Only, None)
InTouch runtime node	InTouchNode	The name of the node (computer) on which the InTouch application runs. If you leave this attribute blank, it is assumed that InTouch 7.11 or higher is running on the same node as the InTouchProxy object.	Supervisory, User
Item browse path	InTouchApplication	The full UNC directory path that contains the Tagname.X file for the target InTouch application. The format is: \\Node\directory The InTouch application directory must be a shared directory. Click the ellipse button to browse to the shared directory.	None
Detect connection alarm	ConnectionAlarm.Alarmed	If enabled, an alarm is triggered when the InTouchProxy object can no longer communicate with the InTouch node.	None
Priority	ConnectionAlarm.Priority	See Alarm Attributes.	Supervisory, User
Reconnect security	Reconnect	Used to set security for reconnections to the InTouch node.	Supervisory, User

Items Configuration

Use the Items Configuration tab to configure InTouch items (tagnames) to be used as object attributes.


Editor Option	Associated Attribute	Description	Run-Time Access (Supervisory, User, Read-Only, None)
Scan Mode	ScanMode	The scanning mode for the scan group, either ActiveOnDemand, Active, or ActiveAll. For the ActiveOnDemand mode, attributes that are not actively being referenced by any client or object are not scanned. For the Active mode, an attribute is always in the active scanning state. When the last reference to the attribute is unregistered (unadvised) , the attribute is deleted. For ActiveAll, an attribute is always in the active scanning state, but when the last reference to the attribute is unregistered (unadvised), the attribute is not deleted.	Supervisory, User
Attribute	ItemList	The InTouch items (tagnames) that will be used as attributes of the InTouchProxy object. A maximum of 5000 InTouch tagnames can be added. Use the Add (plus sign) button to add items to the list. You can click the ellipsis button to browse and select InTouch tagnames. To delete an item, select the item in the list and click the Delete (cross sign) button.	None.

Run-Time Object Attributes

Topic Category	Topic Subcategory	Topic Details
Run-Time Object Attributes	Alarm Aggregation Attributes
Alarm Attributes

Note Configurable run-time attributes are described in the configuration sections. For more information, see Configuration.

For a list of common attributes, click Attributes Help in the Help file header.


Attribute	Description	Run-Time Access (Supervisory, User, Read-Only, None)
Active	If the Active attribute is set to TRUE, and the ScanMode attribute is set to Active or ActiveAll, the object attempts to scan all of the data items in the group. If the Active attribute is set to TRUE, and the ScanMode attribute is set to ActiveOnDemand, the object attempts to scan data items in the group individually according to demand. If the Active attribute is set to FALSE, no scanning occurs, regardless of the setting of the ScanMode attribute.	Supervisory, User
AlarmDSCnt	The total number of disabled and silenced alarms in the object. Sub-areas or sub-notification-distributors are not included.	Read-Only
AlarmOnCnt	The number of active alarms in the distributor. Does not include sub-areas or sub-notification-distributors.	Read-Only
AlarmUnAckCnt	The number of unacknowledged alarms in the distributor (including unacknowledged return-to-normals). Does not include sub-areas or sub-notification-distributors.	Read-Only
AliasDatabase	Used to store pairs of alias attribute names and the corresponding item references.	Read-Only
ConnectionAlarm	If TRUE, the InTouchProxy object can no longer communicate with the InTouch node.	Read-Only
ConnectionStatus	The status of the communications link between the DeviceIntegration Object and the InTouch node.	Read-Only
ItemCnt	The total number of items in the group that are on advise by a client application.	Read-Only
ItemErrorCnt	The current number of items that have been successfully added to this group and have data quality other than GOOD. This value is calculated.	Read-Only
ItemErrorCntAlarm	Set to TRUE if the current error count is not zero. This value can be alarmed.	Read-Only
ItemErrorCntLast	The error count immediately prior to the current error count.	Read-Only
ItemErrorCntLastEnd	The last time the error count returned to zero. The date format reflects the current locale setting for the operating system.	Read-Only
ItemErrorCntLastStart	The last time that the error count changed from zero to non-zero, not including the most recent change to the error count. The date format reflects the current locale setting for the operating system.	Read-Only
ItemErrorCntStart	The time that the error count most recently changed from zero to non-zero. The date format reflects the current locale setting for the operating system.	Read-Only
ItemUpdateCnt	The number of items whose values were updated during the most recent scan cycle.	Read-Only
PingItem	The item quality of this item is checked on each scan to determine the scan group status.	Read-Only
Reconnect	When set to TRUE, the InTouchProxy object will make one attempt to reconnect to the InTouch node. Upon losing a connection, the InTouchProxy object will not automatically reconnect. This attribute can be scripted to achieve automatic reconnect.	Supervisory, User
UpdateRateCmd	The rate, in milliseconds, at which the object will receive updated data values for the scan group. The default is 250.	Supervisory, User

Alarm Aggregation Attributes

The following attributes are available for all Objects. If alarm aggregation is enabled on the Area, the following attributes aggregate their respective alarm status values for the Area, for all sub-Areas, contained objects, and their descendants assigned to the Area. If alarm aggregation is disabled, these attributes remain at their default values. Alarm aggregation attributes behave similarly to alarm aggregation of individual attributes.


Attribute	Description	Run-Time Access (Supervisory, User, Read-Only, None)
<Attribute>.AlarmCntsBySeverity	Array of counts of all alarms that are in UNACK_ALM, ACK_ALM, or UNACK_RTN states on the object, aggregated by severity levels 1-4.	Read-Only
<Attribute>.AlarmMostUrgentAcked	TRUE (default) indicates that no alarms are in the InAlarm state or waiting to be Acked. A value of TRUE also indicates that the most urgent alarm(s) on the object and its descendants in the InAlarm state have been acknowledged, whether or not they are currently InAlarm.	Read-Only
<Attribute>.AlarmMostUrgentIn Alarm	FALSE (default) indicates that no alarms are in the InAlarm state or waiting to be Acked. A value of FALSE indicates whether the most urgent alarm(s) on the object and its descendants are in the InAlarm state, whether or not they have been acknowledged.	Read-Only
<Attribute>.AlarmMostUrgentMode	The AlarmMode of the most urgent alarm(s) on this Object and its descendants. If no alarms are in the InAlarm state or waiting to be Acked, the value is the same as the AlarmMode for the Object.	Read-Only
<Attribute>.AlarmMostUrgent Severity	Severity level expressed as an integer 1-4 of the most urgent alarm(s) on the object and its descendants. If no alarm is in the InAlarm state or waiting to be Acked, the value is 0 (zero).	Read-Only
<Attribute>.AlarmMostUrgent Shelved	The Shelved status as a Boolean value for the “most urgent” alarm(s) on this Object and its descendants. A value of FALSE indicates that no alarms have been Shelved for the "most urgent" alarm(s) on this Object and its descendants.	Read-Only

Alarm Attributes

If an alarm attribute is enabled, then the following additional alarm attributes become available. None of these attributes can be alarmed.


Attribute	Description
<Attribute>.Acked	Used to specify whether an alarm has been acknowledged. This attribute is updated when the AckMsg attribute is set. This attribute is always set to FALSE when a new alarm condition is detected (when the InAlarm attribute changes from FALSE to TRUE).
<Attribute>.AckMsg	The operator comment at the time the alarm is acknowledged. Any received text is stored, and the Acked attribute is set to TRUE. Also, the TimeAlarmAcked attribute is set to the current time. The maximum length is 256 characters.
<Attribute>.AlarmMode	The current alarm mode setting. Valid values are: Enable, Disable, Silence.
<Attribute>.AlarmModeCmd	The command to set the alarm mode. Valid values are: Enable, Disable, Silence.
<Attribute>.Category	The category of the alarm. The label of each alarm category is fixed.
<Attribute>.DescAttrName	The description of the alarm. The description must be of type String or InternationalizedString, with a maximum length of 329 characters. The DescAttrName attribute can contain a static alarm description or a reference to another string attribute within the same object containing the alarm description. The reference must be in the form: "me.AttrName". If the reference is invalid, the actual reference string is used for the description. If nothing is supplied for the DescAttrName attribute, the object’s ShortDesc attribute is used at run time.
<Attribute>.InAlarm	The alarm state. This is exactly the same as the attribute in the host primitive that represents the alarm condition, except when the alarm state is disabled, in which case, InAlarm is set to Off, regardless of the actual condition state. The quality is set during execute to the quality of the attribute, except when the alarm is disabled, in which case the quality is always GOOD.
<Attribute>.Inhibit	If true, the alarm is disabled. This attribute is intended to be written to by a script, a user, or an input feature. Only the individual alarm is disabled. No other alarms are disabled in the same object or in any objects that are assigned to or contained by this object.
<Attribute>.Priority	The value for the urgency of the alarm. Valid values are 1 through 999, with 1 being the most urgent.
<Attribute>.TimeAlarmAcked	The timestamp indicating the last time this alarm was acknowledged. The date format reflects the current locale setting for the operating system.
<Attribute>.TimeAlarmOff	The timestamp indicating the last time this alarm (as represented by the InAlarm attribute) went off. The date format reflects the current locale setting for the operating system.
<Attribute>.TimeAlarmOn	The timestamp indicating the last time this alarm (as represented by the InAlarm attribute) went on. The date format reflects the current locale setting for the operating system.