TN Appsvr144 Overview of Scripting In System Platform
Description
An overview of writing scripts which extend and customize your objects. You can write scripts that run commands and logical operations based on specified criteria being met. For example, a script starts when a key is pressed, a window is opened, or the value of an attribute changes.
- Author: Peter Farrell
- Published: 6/30/2015
- Applies to: System Platform 2014
Details
Using scripts, you can create a variety of customized and automated system functions. A script adds behavior that runs when the object that contains the script is deployed and the object is either:
• On scan in the run-time environment or
• Changes scan or start/shutdown state
A script typically runs based on attributes of the object that contains it, but can be started by another script based on changing values of attributes of more than one object.
When a script condition is true, the script runs at least once immediately. The maximum length of a script trigger period is 49-days. A script never runs if the trigger period exceeds 49-days.
Important: You cannot pass attributes as parameters for system objects. Instead, use a local variable as an intermediary or explicitly convert the attribute to a string using an appropriate function call when calling the system object.
The following characteristics apply to the scripting environment:
• Script text has no length limitations.
• Selecting a script function from the Script Function Library dialog box adds it and its syntax to the script text where you can edit it.
• You can save a script with syntax errors, but the object cannot be deployed until you correct the script syntax errors.
• You can validate your scripts before using them. This helps you avoid syntactically correct but semantically incorrect combinations such as two statements declaring the same variable. Variables can be declared only one time in a single block.
• You can change the name of a script at any time by renaming it in the Object Editor.
• In the run-time environment, a script execution error stops the script’s current execution. Script execution is retried on the next AppEngine scan.
Script Execution
The existence and execution order of scripts associated with an object are inherently locked at each stage of development in the template, derived template, and instance. For example, a set of scripts associated with a template are treated as an ordered block in the Configure Execution Order dialog box when configuring execution order in a next-generation derived template.
New scripts in the derived template can be ran in any order before and after the template’s block of scripts. The derived template’s execution order is treated as a block in any downstream derived templates or instances. Scripts cannot trigger any faster than the scan period of the AppEngine the script is associated with or faster than the scan period of the AppEngine that hosts the object that the script is associated with.
Scripts run in one of two modes:
Synchronous scripting mode is the default for running scripts in the run-time environment. This mode runs scripts in order while an object is running on scan.
• Asynchronous scripting mode is a group of scripts running on the same, lower priority execution thread. These scripts only support Execute triggering and run independently from each other. Set the maximum number of independent threads in the AppEngine configuration editor. To use either scripting mode, you must select Execute as the Execution Type in the Scripts area on the Scripts page.
To create and associate a script with an object
1 Add a script. On the Scripts page of the Object Editor, click the Add button. A script is added to the Scripts Name list.
2 Type a name for the script and press Enter. Script names can be up to 32 alphanumeric characters, including periods. At least one character must be a letter.
3 Select a trigger that starts the script in the run-time environment.
Execution Type triggers include: Startup, On Scan, Execute, Off Scan and Shutdown.
• If you select Startup, On Scan, Off Scan, or Shutdown, the Basics group is unavailable. The script is triggered when the object starts, goes on scan, goes off scan, or shuts down. If you select Execute, the Basics group is available.
• If you selected Execute as the script trigger, select a Trigger Type. Depending on the type selected, you are required to enter an Expression and/or Trigger Period and Deadband values. When the combination of Expression, Trigger Type, Trigger Period and/or Deadband is satisfied in the run-time environment, the script starts running. See the following table for more information.
The Trigger Period format is as follows:
Hours:Minutes:Seconds:Milliseconds
For example, 3 hours, 5 minutes, and 10.5 seconds is:
03:05:10.5000000
Expressions are limited to one language statement in length and calling only synchronous mode script functions. Avoid using script functions with side effects in expressions because subtle behaviors can occur.
4 Select one or more of the following:
• Set the Runs Asynchronously and associated Timeout Limit parameters, as needed.
• Select Report Alarm on Execution Error and set a Priority for the alarm if you want the alarming function to alert you if a script execution failure occurs.
• Select Historize Script State to store the state of the script in your application’s historian.
5 In the Declarations area, type variable declarations about the script you are writing.
6 Set aliases for the reference strings in the Aliases area. This can simplify the script code and allows script code to be created and locked at a template level using alias names. When an individual instance of that template is created, you can link external attributes to the alias names.
In the Aliases area, click the Add button to add a new alias. An alias is added to the list. The name is shown in edit mode.
Double-click the Reference entry, and enter a reference string for the alias. You can also click the Browse button at the end of the Reference block to open the Attribute Browser for easy selection of an object’s attributes.
7 Write the script in the Script Creation box. Use the Display Script Function Browser and Display Attribute Browser buttons to help you insert script functions and object attribute references in your script.
Click the Validate Script button to validate if your script contains any syntax errors.
8 Order the scripts. If you have more than one script associated with a single object, click Configure Execution Order. Ordering does not apply to asynchronous scripts. If a script is added to an instance derived from a template that contains scripts, the new script automatically defaults to running after the derived scripts.
9 When you are done creating your script and setting its execution triggering parameters, save and close the Object Editor.
Locking Scripts
When you lock a script in a template, the following rules apply:
• The name of a script and its existence is implicitly always locked.
This means:
• You cannot delete the script in derived objects.
• You cannot change the name of the script in derived objects.
• If you rename the script in the template, the name changes in all derived objects.
• You can delete a script in the template after you create derived objects. The script disappears from the derived objects.
• You can add a script to the template after you create derived objects. The script appears in the derived objects.
• You can add scripts to derived objects. Adding scripts to derived objects does not affect parent object scripts.
• You can lock or unlock the script text in a template. There is script text for Declarations, Execute, Startup, Shutdown, On Scan and Off Scan. You cannot separately lock each script in the script editor. You use a single group lock to lock or unlock all at once.
After you lock a script, derived templates and instances cannot modify any of the script text.
• When the script text is locked in a template, the alias names are automatically locked. The alias references are never locked.
Locking of aliases is not specified separately.
Locking aliases means the entire list of alias names is locked, including the number of items in the list. You cannot add new alias names in derived templates or instances when the alias list is locked. The alias references are always editable in derived templates and instances even when the entire list of alias names is locked. This is the primary objective of aliases.
• The script description, runs asynchronous flag, expression, trigger type, trigger period, deadband and execution error alarm are individually lockable and can be locked separately from the script text. A group lock is provided for this group of attributes.
• When you add a script to a template, all properties of the script are editable.
• When you add a script to an instance, all properties of the script are editable except for the lock properties. A lock is never editable in an instance.
Important: An expression typically uses attribute references. To lock the expression and the associated script in a template, use aliases in both the expression and the script. This allows you to specify the attributes that the aliases point to on a per instance basis while the script code is locked.
The following rules apply to the derivation behavior of locked script attributes:
• If an attribute is locked in a template, then all templates and instances derived from the template share the copy of the value of the locked attribute. A change to the value is only allowed in the template that locked it. The change propagates to all derived templates and instances.
For scripts, locking an attribute of the script, such as its script text or execution type, in a template means all derived templates and instances point to that locked attribute. Future changes to that locked attribute’s value, such as modifying the script text, propagate and appear in all derived templates and instances.
If instances are deployed, they are marked pending update status. After they are redeployed, the change to the locked attribute in the template exists in the deployed instance.
• If an attribute is not locked in a template, then all templates and instances derived from that template receive their own copy of the value of that locked attribute. A change to that unlocked value is allowed in derived templates and instances because they own their own copy. Any change to the unlocked attribute value in the template does not propagate to any derived template or instance.
An unlocked attribute in a script (such as expression or script order) in a template means that all derived templates and instances have their own copy and the value of that unlocked attribute can change. Future changes to that locked attribute’s value (for example, modified expression) in the template does not propagate to any derived template or instance. If instances are deployed, their status does not change to pending update. Redeploying them does not cause the value to change in the deployed instance.