Shutdown Intercept Script
The Shutdown Intercept Script event is unique in that it runs when a user attempts to shutdown a client, but before actual shutdown occurs. This means it will actually run before the Shutdown Script, and there is only a client version of it. There is a special event object that you can set a cancel property to prevent shutdown by using the code event.cancel = 1. Doing this will cancel the shutdown event and leave the user at the spot they were last at. This allows you to set special restrictions on when the client is actually allowed to shut down, such as having a certain role, as seen in the example below:
- initialChange - a variable that is a flag (0 or 1) which indicates whether or not the event is due to the initial subscription or not. This is useful as you can filter out the event that is the inital subscription, preventing a script from running when the values haven't actually changed.
- event - a TagChangeEvent object which contains the properties: tag, tagPath, and tagProperty, all of which are also complex objects.
- event.tag - a Tag object which contains basic information about the Tag such as name, value, and type that can be accessed via event.getTag().getName().
- event.tagPath - a TagPath object which contains information pertaining to the Tag path such as the parent and child paths via event.getTagPath().getParentPath(). You can also get the path of the Tag by calling event.getTagPath().toString().
- event.tagProperty - a TagProperty object, which can be used to create an enum of a property, which can be used in conjunction with the Tag object to access properties of the Tag such as OPC Item Path or Scale mode via event.getTag().getAttribute(event.getTagProperty().getProp("OPCItemPath")). The possible properties are: 'AccessRights', 'AlarmActiveAckCount', 'AlarmActiveUnackCount', 'AlarmClearUnackCount', 'AlarmHighestAckName', 'AlarmHighestAckPriority', 'AlarmHighestUnackName', 'AlarmHighestUnackPriority', 'AlarmShelvedCount', 'AlertAckMode', 'AlertAcknowledgeUser', 'AlertAcknowledged', 'AlertAcknowledgedTime', 'AlertActive', 'AlertActiveTime', 'AlertClearedTime', 'AlertCurrentSeverity', 'AlertCurrentState', 'AlertDeadband', 'AlertDisplayPath', 'AlertExecEnabled', 'AlertMessage', 'AlertMessageMode', 'AlertMessageSubject', 'AlertMode', 'AlertNotes', 'AlertSendClear', 'AlertTimestampSource', 'ClampMode', 'DataType', 'Deadband', 'DeadbandMode', 'DeriveExpressionGetter', 'DeriveExpressionSetter', 'Documentation', 'DriverName', 'Enabled', 'EngHigh', 'EngLimitMode', 'EngLow', 'EngUnit', 'EventScripts', 'Expression', 'ExpressionType', 'ExtendedProperties', 'FormatString', 'HistoricalDeadband', 'HistoricalDeadbandMode', 'HistoricalScanclass', 'HistoryEnabled', 'HistoryMaxAge', 'HistoryMaxAgeMode', 'HistoryTimestampSource', 'InterpolationMode', 'LastChange', 'Name', 'OPCItemPath', 'OPCServer', 'OPCWriteBackItemPath', 'OPCWriteBackServer', 'PersistValue', 'PollRate', 'PrimaryHistoryProvider', 'PropertyOverrides', 'Quality', 'QueryType', 'RawHigh', 'RawLow', 'RuntimeQuality', 'SQLBindingDatasource', 'ScaleFactor', 'ScaleMode', 'ScaledHigh', 'ScaledLow', 'ScanClass', 'SourceDataType', 'SourceTagPath', 'TagType', 'TagTypeSubCode', 'Tooltip', 'UDTMemberUID', 'UDTParentType', 'Value'.
- newValue - a newValue object which contains a value, quality, and a timestamp of the Tag. They can be called via newValue.getValue().
Gateway Tag Change Behavior
Having the Tag Change Scripts run in the Gateway Scope means that the scripts will trigger when a Tag in their tag list changes as long as the Gateway is running. The script will be able to interact with the Gateway and other Tags, but not the project.
Client Tag Change Behavior
Having the Tag Change Scripts run in the Client Scope means that the scripts will trigger when a Tag in their Tag list changes, but only if a Client of that project is open. This means that if no Clients are open, the script will not fire, regardless of the number of times the Tag changes. However, because this is run from the Client Scope, it
Under the list of handlers, three small buttons allow you to add, remove and manage your handlers.
- Add Message Handler - Will add a message handler.
- Remove Message Handler - Will delete the highlighted message handler.
- Modify Message Handler - Will modify the settings for the highlighted message handler.
When adding or modifying a message handler, a small settings window will popup. In it, you can give your message handler a name or modify its existing name, enable or disable the message handler, and even select how it executes under the Threading dropdown. There are three different options that dictate how the message handler will execute:
- Shared - The default way of running a message handler. Will execute the handler on a shared pool of threads, in the order that they are invoked. If too many message handlers are called all at once and they take long periods of time to execute, there may be delays before each message handler gets to execute.
- Dedicated - The message handler will run on its own dedicated thread. This is useful when a message handler will take a long time to execute, so that it does not hinder the execution of other message handlers.
- EDT - This will run the message handler on the event dispatch thread which also updates the GUI. If a message handler were to take a long time to execute, it would block the GUI from running which may lock up your client. This is helpful when your message handler will be interacting with the GUI in some way, as the GUI will not be able to update until the message handler finishes.
Inside the message handler is your script. The script will have a single object available to it, the payload. The payload is a dictionary containing the objects that were passed into it. Each object in the payload dictionary can be accessed by calling their corresponding key. For example:
Gateway Message Handlers
Gateway message handlers are setup and function similarly to client message handlers. However there are two major differences:
They are setup in the Message section of the Gateway Event Scripts. As such, they are executed on the Gateway.
- They have an added layer of security. In the message handler settings, it is possible to configure Security Zone/User Role pairs. The user invoking the message handler must match one of the combinations of Security Zone/User Role listed or else the message handler will not execute.
Using Message Handlers
Once you have your message handlers created, you can then call them from a script using one of three scripting functions: system.util.sendMessage, system.util.sendRequest, and system.util.sendRequestAsync. These functions allow you to call a message handler in any project, even if the project that the message handler resides on is different from the one you are calling it from. The message handler will then execute in the scope in which it was created, and will use any parameters that you pass in through the payload.