UIS Command Task

A UIS command task initiates a UIS command on a user-defined basis to one or more field devices. UIS commands must first be defined in the Device Definition Service (DDS); the MSS merely enables the choosing of specific ones to issue. The Can Schedule property of a UIS command must be selected in order for a command to be available for scheduling by means of the MSS. For more information, see Configuring a UIS Command.

The UIS Command Task property sheet enables you to specify the parameters by which a UIS command task resolves. A defined task resolves to the specified parameters and the UIS. In addition to set schedule polling where tasks are initiated on a predefined schedule, you can also set up polling to occur on a conditional basis and on a continuous basis.

The following diagram illustrates how UIS command tasks resolve to their respective remote devices:

UIS Command Task

UIS Command Task

For more information, see the subsections below:

See Scheduling a Task for information about configuring the Schedule property sheet for a UIS command task.

To Configure a UIS Command Task

  1. Once you have finished scheduling a task, click the UIS Command Task page to open the UIS Command Task property sheet.
  2. Select the relevant UIS, command type, and command priority. If you require a status UDC, select one now as well.
  3. Define the device descriptor rules for the selected command type. These enable device filtering so that only relevant devices are affected by the selected command type. A useful description of the rule(s) generates in the Description field at the bottom of the Device Descriptor(s) field.
    1. Select at least one Parameter. More may be specified in sequence if you require finer-tuned filtering than one parameter provides.
    2. Select the appropriate Operator.
    3. Enter the appropriate Value.
    4. Optional: Depending on Parameter selected, you can select a Tag Type.
    5. Optional: If Tag Type is selected, select an available Tag ID.
  4. When you are finished defining rules, test the results by clicking Resolve and confirm the results are what you expect. Results only reflect the rules defined by device descriptors; the task does not resolve to the command type.
  5. If you are finished defining your UIS command task, click OK to save your settings and exit.

Back to top

UIS Task Examples

The following examples illustrate common ways to configure a UIS task.

Basic Polling Example

The following task shows that a STATUS command with Low priority is to be issued by the CYGSITE3.UIS service. The first Device Descriptor specifies all devices because Device ID uses a wildcard (*). The second Device Descriptor specifies a Curr. Comm ID value of "RADIO1". Because the logical operator used is And, all characteristics of both descriptors must be met. The result is that the task resolves to all devices that also have a current communication device ID of "RADIO1".

Basic Polling Example

Basic Polling Example

Conditional Polling Example: Using Tag-Specific Values

Conditional polling enables you to create a polling schedule based on the value of a specific tag. Conditional polling must be set up in conjunction with either duration or interval polling (see Scheduling a Task). Jobs are issued by duration or interval until a condition is met, then the appropriate task is executed in response to the condition. For example, if a poll is scheduled to run every 3 minutes and the conditional trigger for the poll is a high pressure, the job runs every three minutes but the task is only executed when the pressure becomes high.

The following task shows that a STATUS command with High priority is to be issued by the CYGSITE3.UIS service. The first Device Descriptor specifies all devices because Device ID uses a wildcard (*). The second Device Descriptor specifies a Point Value greater than or equal to 100 for the specified UDC called LTANK (tank level). Because the logical operator used is And, all characteristics of both descriptors must be met. The result is that the job resolves to all devices that also have a UDC called LTANK, but a UIS command task is only issued if the point value for LTANK is equal to or greater than 100.

Conditional Polling Example

Conditional Polling Example

Conditional Polling Example: Adjusting the Comm Queue to Avoid Over-Polling

Depending on your communication infrastructure, it is possible to schedule jobs to execute at a rate that is faster than your pending UIS communication queue can handle. This is not an optimal situation. For example, you might schedule a command to poll every 60 seconds but your pending communication queue is only able to issue commands every 70 seconds. Over time, your pending communication queue might back up and exhaust UIS memory.

An optimal solution is to adjust your MSS schedule to poll with enough time to fully execute a UIS command. But this is not always practical. Another way to solve this problem is to set up a condition that regulates the maximum number of tasks allowable at one time in a pending UIS communication queue. When the number of pending messages in the relevant pending communication queue is down to an acceptable level, an MSS task is issued to the queue. When the UIS executes the next command, the MSS can send yet another task. And so forth. If configured properly, this method of polling ensures that messages do not back up in a pending communication queue to a level that causes the UIS to exhaust its memory. However, it does mean that you are not truly polling on the schedule configured in your MSS task; you are polling at a rate the UIS communication device can handle.

To View Communication Statistics

  1. Using CygNet Explorer, open the relevant UIS.
  2. Click the Comm Devices page and view relevant statistics in the service pane.
  3. Right-click the relevant communication device and select options from the context menu.

For more information, see Universal Interface Service and Viewing Communication Statistics.

To Adjust the Comm Queue to Avoid Over-Polling

  1. Using CygNet Explorer, create a new point in the Point Service (PNT).
    1. In the Facility ID field, enter the relevant communication device facility.
    2. In the Uniform Data Code field, enter SYCSPEND. (The SYCSPEND value is the number of messages pending in a communication queue.)
    3. In the Point Type field, select Analog Input.
  2. Using CygNet Explorer, open the relevant MSS.
    1. On the Schedule page, define an interval.
    2. On the UIS Command Task page, select the relevant UIS and command type.
    3. Define at least one descriptor to identify devices affected.
    4. Use another descriptor to define the condition by which polling should occur. Be sure to enter the long-point ID of the point you created in step 1 above.
    5. Make any other required settings, then click OK to save and exit.
  3. Test your results by issuing jobs from the MSS and confirming their success in the UIS. (A Trend Tool might be a useful way to monitor results.)

Example

The following task shows that a STATUS command with Low priority is to be issued by the CYGSITE3.UIS service. The first Device Descriptor specifies all devices because Device ID uses a wildcard (*). The second Device Descriptor specifies a Point Value less than 10 for the specified long-point ID called COMDEV_SYCSPEND. Because the logical operator used is And, all characteristics of both descriptors must be met. The result is that the job resolves to all devices that share a communication device called COMDEV and a UDC called SYCSPEND, but a UIS command task is only issued when the point value for SYCSPEND is less than 10.

Continuous Polling Example

Continuous Polling Example

Back to top

UIS Command Task Properties

The following table lists and describes properties of the UIS Command Task property sheet.

Parameter Description
[UIS Command Task Information]

UIS Service

The UIS that will process the task.

Cmd Type

The command type (name). A command in the DDS must have its Can Schedule option enabled or it will not be listed.

Cmd Priority

The priority of a UIS command in the UIS communication message queue (CmdPriority). Cmd Priority options include:

  • Low — the lowest priority
  • Medium
  • High
  • User
  • Admin — the highest priority

Each higher priority trumps priorities lower than it. See Prioritizing Messages in the Communication Queue for more information about command priority.

Status UDC

Use this field to assign a status UDC to the UIS command task. Status monitoring affects the CygNet Studio UIS Command Button tool. See UIS Command Button for more information. This property is optional.

Device Descriptor(s)

Logical Operator

Select And or Or to define your use of search parameters.

Resolve

Once the Device Descriptors are defined, click Resolve to display a list of devices that match the Descriptors.

Parameter

The Parameter specifies an identifier by which to resolve a command.

Parameter Description Value
<none> No parameter is specified. This descriptor will not be used to resolve devices. –
Device ID The device ID.  
Facility ID The facility ID.  
Facility Type The facility type. DEVICE or user-defined
Facility Description The facility description.  
Facility Info0 The facility info attribute 0. The default name of this attribute in the metadata is "Facility Location".  
Facility Info1 The facility info attribute 1. The default name of this attribute in the metadata is "Facility Contact".  
Device Type The device type.  
Short Point ID The short point ID of a specified point.  
Long Point ID The long point ID of a specified point.  
Point Value The value of a specified point. Indicate the Tag Type: Long Point ID, Short Point ID or UDC, and specify the Tag ID.  
Point Desc The description of a specified point. Indicate the Tag Type: Long Point ID, Short Point ID or UDC, and specify the Tag ID.  
Point Status The status of the point. Choose whether the point status is unreliable or has any individual alarm bits enabled. Indicate the Tag Type: Long Point ID, Short Point ID or UDC, and specify the Tag ID. Unreliable or Has Alarm Bits Set
Timestamp The timestamp for the specified point. Indicate the Tag Type: Long Point ID, Short Point ID or UDC, and specify the Tag ID.  
Curr. Comm ID The current active communication line. 1 - Primary
2 - Device2
3 - Device3
Primary Comm ID The ID of the configured primary communication device.  
Secondary Comm ID The ID of the configured secondary communication device.  
Tertiary Comm ID The ID of the configured tertiary communication device.  
Facility Is Active Indicates whether the associated facility is active. True or False
Facility Category The category of the facility. REMDEV
COMMDEV
DDSFAC
EXPDEV
GENFAC
SITE
SERVICE
Facility Comment The facility comment.  
Facility Security App The facility security application.  
Attribute 0 - 39 Text attributes 0 through 39.  
Table Attrib 0 - 59 Table-driven attributes 0 through 59.  
Yes/No Attrib 0 - 19 Yes/No attributes 0 through 19.  

Operator

Select an available operator to define the relationship between a parameter and a value.

Value

Enter a user-defined value. The Value field is not case sensitive. The wildcards "*" and "?" can be used when specifying a Value:

  • "*" is a multi-character wildcard
  • "?" is a single-character wildcard

Tag Type

The Tag Type buttons enable you to specify the type of tag that corresponds to the value entered in the Tag ID field. Options are as follows:

  • For Long ID
  • For Short ID
  • For UDC

Simply click the Tag Type button to toggle between options.

The Tag Type buttons only become available when used with the following Parameter values:

  • Point Desc
  • Point Status
  • Point Value
  • Timestamp

For more information, see Conditional Polling Example.

Tag ID

The Tag ID field enables you to specify a tag that corresponds to the selected Tag Type. Click the Browse button to open the Select Point dialog box for a list of available tags in one of three formats; formats correspond to that selected by the Tag Type button.

The Tag ID field only becomes available when used with the following Parameter values:

  • Point Desc
  • Point Status
  • Point Value
  • Timestamp

For more information, see Conditional Polling Example.

Description

An easy-to-read description of the descriptor rule(s) defined above.

Back to top