The Script Editor is where you define the Actions that the script performs. In addition, you define how the script will appear in the Script Dashboard and what values can be edited by the script user. To open the Script Editor, select a script in the Script Manager and select Edit. Figure 1.6 identifies the sections of the Script Editor.

This section describes how to use the Script Editor to define the script. This assumes you have created a new Script from the Script Manager. The Script Editor opens automatically for new scripts or select Edit to open an existing script.

You can copy one or more actions from a script and paste them in any other script. Standard multi-select controls allow you to select multiple actions­: Drag or Shift+Click to select a contiguous block of actions, and Ctrl+Click to select non-contiguous actions.

With one or more script actions selected in the Script Editor, use the following operations in the Script Editor in the actions panel:

To access these operations, use the Edit menu as illustrated in Figure 1.8 or from the context menu for the action list as shown in Figure 1.9. Keyboard accelerators are also available: Copy: Ctrl+C and Paste: Ctrl+V.The context menu also gives access to slots referenced by the action, where applicable.

Also, on the script dashboard, the right-click context menu provides access to copy an action. These can then be pasted into a Script Editor as described above

Use the Search panel to find an action by text, type, or value in the script editor. This can be very useful if you have a script that issues an error as the message says the type of action and its name. Use the search to find that action in the editor. To open the Search panel, use the Search check box, use Edit menu and then Search or use the Ctrl+F keyboard shortcut.

Then, type in the desired text and select the attributes in which to search. The attributes correspond to columns in the Script Editor’s action panel and settings panel:

To perform the search, select Enter or use the up or down arrows. When a matching action is found, that action is selected in the Action panel. The search will wrap when it meets the end of the script.

When creating and debugging your script, it may be convenient to run the script from the editor than opening the Script Dashboard. There are three ways to execute actions from the editor:

These operations execute the actions but do not give status or display information on progress. As a result, running actions is best performed from the Script Dashboard; see Script Dashboard for details.

Table 1.1 describes the types of actions. Within the Script Editor, select Help for a quick reference of the actions. Each action type also has a link to additional information on its settings. See Action Type Settings Reference for details about the settings.

An action is controlled by user settings. Actions of all types have the following settings:

For this sample Set Scalar Slot action, the resulting description would show on the dashboard as two lines below the display text above any override controls:

The following sections provide more information on certain settings or on settings that are shared by many actions that have additional controls.

Datetimes in a script can be specified either as absolute values or a symbolic values. There are two slightly different interfaces, but both have essentially the same functionality. Depending on the action and whether it is the editor or dashboard, one of the following interfaces will be used.

Following is additional information on each of these ways to specify the datetime.

Filenames can be entered manually or chosen using the file chooser. You can specify files using environment variables using the $VARIABLE syntax.

This action allows you to reorder items (rules, goals, groups, or even statements within the specified set. The new order is specified on a table slot. Following is an example that shows the use of this action. Figure 1.12 shows the ruleset before the script is executed.

Figure 1.13 shows the specified table that describes the desired ordering. The row labels must match the names of the items in the set.

Figure 1.14 shows a text description of this reordering.

Figure 1.15 shows the ruleset after reordering.

This section contains important information on the following actions that set slot values in the model:

Configuring User Control on the Script Dashboarddescribes how to configure user controls on the dashboard. Then, see Setting Slot Values Using a Global Function for more information on setting numeric values using a global function.

This section applies when the “Set by” setting is using “Values” For actions that set values in the model (Set Scalar Slot Value, Set Series Slot Values, Set Table Slot Value, Set Periodic Slot Values), you can either specify the value to set or give a default, but allow the user of the script to override that value. This section describes configuring the action so that the user can modify the value using either a value editor, radio buttons or a slider. These are controlled by the settings shown in Figure 1.16.

The following sections describe the three “Yes” cases. In each case, an example will be shown where a script is setting a scalar slot called Data.Factor to a value between 0.1 and 1.5. Perhaps this factor is then referenced by a rule to compute demands or inflows. For reference, Figure 1.17 shows this scalar slot.

For all of the Yes selections for Allow Editing, you can also choose to Show Current Value. When Yes, the current value (for a single scalar slot only) is shown on the Dashboard below the editing controls.

When the Allow Editing setting is Yes: Editor, an editable field is shown on the Script Manager. The default value will be used unless the user enters a different value in the field. Figure 1.18 shows the settings to get this control.

When the Allow Editing setting is Yes: Radio Buttons and an Encoding Table Slot is specified, radio buttons are shown on the Script Manager. The default value will be used unless the user selects one of the radio buttons to use that value.

The Encoding Table Slot Name setting specifies a Table Slot whose row labels and values establish a textual encoding of values. Figure 1.19 shows a sample encoding table slot. The row labels are used as the labels on the radio buttons. The values in the table are displayed on the Script Manager and will be used by the action for that button.

When the Allow Editing setting is Yes: Slider and Minimum and Maximum Edit Values are defined, a slider will be shown on the Script Manager. The default value will be used unless the user moves the slider to a different value. Figure 1.20 shows the settings to configure this control. The available slider positions are computed by dividing the interval between the minimum and maximum by 100.

The three script actions allow slot values to be set to values as described above. They also allow the slot value to be set to numeric or datetime values using a RPL Global Function.

To use this functionality, in any of these actions, in the “Set by” setting, choose “Function”. Then choose the desired RPL Global Functions Set and the specific RPL Global Function to use as shown in Figure 1.21.

The global function can contain various combinations of arguments based on the action. You can use zero, one or more arguments. The arguments passed for each action are:

Whether an action executes or not can depend on the value of a variable set by another action, often controlled by the script dashboard user or operator. This allows scripts that can be executed with different settings or in different “modes” without requiring scripts to be duplicated many times for each potential variation.

To set this up, following these three steps as described in this section.

These three steps are described below:

In the Script Editor, create Specify Script Variable Value action. This action uses three settings to define a variable:

Then, optionally select how you want the selection to appear on the dashboard.

For more information on this specific action, see Specify Script Variable Value.

Once configured, the dashboard user is able to select the value of the variable. The dashboard will reflect this selection by disabling actions that will not execute due to a dependency on the variable. Actions disabled this way have a special icon and cannot be manually re-enabled until the variable selection changes. See Specify the Script Variable Values on the Dashboard

Three settings are used to control an action’s execution based on the value of a script variable. These settings are available on any action:

Thus, an action will execute when:

The script dashboard user selects the value of the variable from the dashboard. The dashboard will reflect this selection by turning off actions that will not execute due to a dependency on the variable. Actions disabled this way have a special icon and cannot be manually re-enabled until the variable selection changes.

If the script operator switches the variable in action/row 1 to Planning, the action/row 2 would be turn to yellow to be executed and action/row 3 would be disabled.

The following section describes some additional information on using the Script Variables.

The action Specify Script Variable Value creates the variable when they are executed. That is, a variable cannot be referenced before the Specify Script Variable Value action defines it. Script execution will abort and an error will be posted to the Diagnostics Output if the variable on which an action depends has not been defined. Thus, it is generally a good idea to insert these actions early in a script to ensure that their variables are present when they are needed.

The rest of this section applies when the Allow Sub-actions to Override Variable Values is set to “No”. In that case, a script variable can only be defined once within any given script and any subscripts it executes via the Execute Script action. If a Specify Script Variable Value action attempts to redefine a variable that has already been defined (including in parent scripts), then any definition other than the first will be ignored. This can be seen in Figure 1.24; the “Additional run setup” script defines the “Run Type” variable as its first action.

However, because the “Additional run setup” script is being executed as a subscript of the “Run model” script, only the variable definition in the “Run model” script takes effect. Furthermore, the first of the “Set DataObj1.ModelRunData” actions is enabled because it executes when “Run Type” has a value of “Standard” while the second is disabled because it executes when the variable has a value of “Model Testing”.

Figure 1.25 shows that if the “Additional run setup” script is executed on its own, that its definition of the variable is used. As before, the first of the “Set DataObj1.ModelRunData” actions executes when “Run Type” has a value of “Standard” while the second executes when the variable has a value of “Model Testing”.

Script variables can be defined multiple times, although later or subscript definitions will be ignored. Figure 1.26 shows an example of the “Run Type” variable being defined in both the “Additional run setup” script as well as the “Even more run setup” script. However, they do not interfere with each other because the “Run Type” variable is not also defined in the “Special run setup” parent script.

When Allow Sub-actions to Override Variable Value is set to “Yes” on the first Specify Script Variable Value action encountered, then all subsequent Specify Script Variable Value actions can redefine or override the variable value. This allows you to either modify the value or prompt the user for a new value after first defining.