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 run 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 runtime 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 a script and associate it with an object

1. Add a script. On the Scripts page of the Object Editor, select 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.

   Note: For detailed information about each item on the Scripts page, see Scripts page.

3. Select a trigger that starts the script in the runtime 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 runtime 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.

     Trigger Type	Description
     Periodic	When the object containing the script is going On Scan, a Periodic script evaluates its expression at the next scheduled scan period of the AppEngine. The script then runs periodically at the trigger interval specified in the Trigger Period box. A time interval of zero (0) starts the script during every scan. This trigger does not require an expression.
     While True	When the object containing the script is going On Scan, a While True script evaluates its expression at the next scheduled scan period of the AppEngine. The script runs if true and then periodically thereafter at the trigger interval. The script continues running as long as the Expression value evaluates to true. A Trigger Period is required. Zero (0) evaluates the expression at the AppEngine scan period and non-zero means the expression is evaluated at the specified time interval.
     On True	When the object containing the script is going On Scan, an On True script evaluates its expression at the next scheduled scan period. The script starts at the transition between the expression going from false to true.
     On False	When the object containing the script is going On Scan, an On False script evaluates its expression at the next scheduled scan period. The script starts at the transition between the expression going from true to false.
     Data Change	Scripts run when the value or quality of the expression changes. The expression must evaluate to a single, non-arrayed value of the following types: integer, real, time, elapsedtime, string, double, Boolean, custom enumeration and quality. To allow execution based on quality, select the Quality changes check box. A deadband can be specified for all data types. Deadband units for time and elapsedtime types are milliseconds. Deadband is always ignored for strings because any change (even from "ABC" to "abc") is considered a change. Only major changes in quality (from Good/Uncertain to Bad/Initializing or vice versa) are considered changes. After the object is put on scan, Data Change-triggered scripts start running at the AppEngine’s next scan period and then at each subsequent scan period in which the value or quality changes.
     While False	When the object containing the script is going On Scan, a While False script evaluates its expression at the next scheduled scan period, runs if false, and then periodically thereafter at the trigger interval. The script runs as long as the Expression value evaluates to be false. A Trigger Period is required. Zero (0) evaluates the expression at the AppEngine scan period and non-zero means the expression is evaluated at the specified time interval.

4. Select one or more of the following:

   • Set the Runs Asynchronously and associated Timeout Limit parameters, as needed. The Timeout Limit is set in milliseconds. Note that if a script exceeds the Timeout Limit, it continues to execute all sequential statements, but generates a warning in the logger when it completes. If the script contains a loop, it will exit the loop and complete execution of the script, when the timeout limit is reached.

   • 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, select 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 select 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. For help with the specific commands and syntax, see "QuickScript .NET Functions" in the Application Server Scripting Guide.

   Select 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, select 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.