Script Environment¶

Scripts are essentially pieces of code that can implement some functions. The scripting language in the MIKE CUSTOMISED platform is IronPython which is the Microsoft .NET framework implementation of the python scripting language. The Script Manager in the platform offers interface and functionality for users to write their own scripts utilising the API of the platform to create their customized applications.

Scripts in the Script Manager can be arranged in groups or by storage and are shown in the user interface as folders. The user is able view these two explorer structures by selecting “View by Group” or “View by Storage” in the Script Manager explorer as depicted in Figure 1.

Figure 1: “View by” menu

What is a Storage?¶

Storage is a physical collection of script functions. It is similar to a file. The user needs to create a new storage before writing a script. This will be discussed in more detail in the “Walk-Through: Get the values of a time series” section of this document. Script functions with common functionalities in a storage can be called by other functions in the same storage. Figure 2 illustrates the storage explorer in the script manager.

Figure 2: Storage explorer

Note the following:

There is no folder in the storage explorer. The item in this explorer is a script storage. The user can delete, rename or edit a storage by right-clicking on it and selecting corresponding menu item.

What is a Script Entity?¶

A script entity in the script manager is a script function in a storage, with specific comments. The script manager saves script functions with formatted comments in the database. To comply with the coding standard, the user should add comments in the definition of the function. This will allow the script manager to interpret the function parameters correctly. The following listing illustrates the format of the comments.

Listing 1 Formatted comments of a Script

Note the following:

The author of the script.
The function description of the script.
Parameter description of the script - describes the names, types and meanings of the parameters. If these parameters are defined before execution, the user will be prompted to set correct values for these input parameters.
Return value of the script - describes the type and meaning of the return value.

The script entity can be viewed in group explorer. Figure 3 shows the group explorer of script manager.

Figure 3: Group explorer

Note the following:

The folder corresponds to the script group entity.
The item corresponds to the script entity.

Folders in the group explorer can be created, deleted, renamed or moved like any normal folder. Scripts under a folder may originate from different storages and a storage may contain more than one script.

What is a Function?¶

The function is a script function without formatted comments as described for the script entity above. The function will be stored in the script storage but will not be treated as a script entity in the script manager. The function however, can call and be called by a script entity.

Organizing Scripts¶

This section describes some possible ways to create and organize scripts.

Scripts are conveniently arranged in groups (and subgroups if desired) and storages. A storage is a physical collection of script functions similar to a file, and the scripts within the storage may call each other (allowing common functionality to be shared among scripts in the same storage). Groups and subgroups can be created and renamed, and subgroups can be moved between groups, similar to the way files and folders are managed on disk. A group (or sub Group) can contain a number of scripts and theses scripts may come from different storages. Similarly the scripts in a storage may be organized in difference groups.

View by Scripts or Storage¶

Description	Illustration
The view of scripts can be either by Scripts, where the scripts are organized in Groups or by storage where the scripts are displayed directly without their group association. To select the view: Right click on the database level and select either Scripts or Storage from the context menu.

Add a new group¶

Description	Illustration
When the Group view has been selected, a new group can be added. Create a new Group by right clicking on the database level, and select Add New Group from the context menu. The new script group is created as a subgroup under the group that was selected.
The new model group will by default be called New GroupX, where X refers to the group number at the specific level where is has been created.

Rename a group¶

Description	Illustration
An existing script group can always be renamed. Right-click on the group and select Rename from the context menu.

Add a storage¶

Description	Illustration
When the Storage view has been selected, a new storage can be added. Create a new Storage by right clicking on the database level, and select Add Storage from the context menu.

Rename a storage¶

Description

Illustration

When the Storage has been added an empty script will appear in the Data View with the default name.

Furthermore a Script Debugger will appear.

The storage can be renamed by right clicking on its name and select rename from the context menu.

Note: In the following the data view will be referred to as the script view.

Note: Scripts in the storage will not appear in the Group view until the storage has been saved.

Script Development¶

This section introduces the tool context menu in the script editor. The script editor has a lot of tool buttons which can assist the user to perform an action. The following figure indicates these tools.

Figure 16: Tools in the script editor

Note the following:

Tools for debugging. The user can utilise these tools to step into/step over/step out a script function, pause or stop a debugging and disable or delete breakpoints.
Tool to insert a script without arguments – the following listing shows this auto-generated script.

Listing 13 Script without arguments

If the user wants to add a script function without arguments, he just needs to update the above one without starting from the very beginning. In other words, the user does not need to add these comments word by word.

Tool to insert a script with arguments. The auto-generated script is shown in the following listing.

Listing 14 Script with arguments

The user can update this script to create own script function with arguments, without having to start from scratch. In the above listing, the IClass and Member are rarely used. They may possibly be removed from the MIKE CUSTOMISED platform in future.

Tool to save a script storage in the database.
Tools to execute a selected script.
Tool to find a word in the storage.
Tool to find a word and replace it with a new one in the storage.
Tool to comment selected lines in the script functions.
Tool to uncomment selected lines in the script functions.
Tool to show the snippet manager dialog used to add customized snippets which can be inserted in a script function later. The script snippets have been introduced in detail in the Inserting script snippets section.

Some tool functionalities mentioned above can also be found in the script editor context menu.

Working with Scripts¶

Start a new script¶

Description	Illustration
When the Storage has been created an empty script is created in the Script View. A script which is not listed in the data view can be accessed by: Double click on the storage, or right click and select Edit Storage. Once the storage open in the Data View the scripts within it can be edited.
To write a script: Right click in the empty script editor and select Insert. In the context menu two types of script templates can be selected. The templates provide a starting point for creating a more comprehensive script. Existing scripts can also be copied and pasted into a new script and thereby provide a template for the new script.

Simple script template	Advanced script template

Modify a script¶

Description	Illustration
The script can now be modified: Modify the script name Modify the script description Insert script code

Save a script¶

Description	Illustration
When the script has been modified it should be saved: Click save in the Script editor’s toolbar. Note: If the script contains syntax errors it cannot be saved.
Confirm the changes by pressing the Save button in the Confirm changes dialog
The script will now appear in the group view and can be moved to a group or subgroup.
Once a script has been saved, the script can be moved to a group or subgroup. The properties of the script are described in the properties dialog.

Execute a script¶

Description	Illustration
A script can be executed in two different ways: Right click on the script in the group view and select Run in the Context menu.
Open the script in the Script editor and select the script from the pull down menu, and click on the run menu in the toolbar of the Script Editor.
After execution of a script, the information about the execution is displayed in the Properties Editor.

Comment about input parameters:

Beware that when passing arguments to a script, the format has to match the expected type. For example, if a script has an attribute of type Single, it will not accept as valid value a number that can be considered as a Integer. In this example, passing the value 13 would fail while 13.0 would succeed.

Debug a script¶

Description	Illustration
Before a script can be executed, it often needs to be compiled. If there are syntax errors it will not be saved. Example of a syntax error upon saving is shown in the figure. When the script has been modified it should be saved: Click save in the Script editor’s toolbar. Note: If the script contains syntax errors it cannot be saved.
When debugging a script it is convenient to place the debugger view below the script editor, so both editor and debugger are visible at the same time.
When debugging a script it can be analyzed in more detail by running the script stepwise in order to localize the error. Breakpoints can be inserted to stop the execution and investigate variables and conditions, and subsequently continue the executing until the next breakpoint. Insert breakpoints by clicking the mouse at the left column and in the line where the program should stop temporarily. In the adjacent figure a break point is located at line 30.
When the execution stops at the breakpoint, the line will be highlighted in a yellow color, which indicates the current position of the execution. Note: In the adjacent figure, the line above the breakpoint indicates that the script should print the following: “CalculateAverage(‘int’)”. In the debugger under the output tab, the printed statement is shown. Indicating it has passed the line containing the print statement.
Click at the Step Into menu in the toolbar (or press F11) to continue the execution Note: In the example the new current execution line at line 14 is highlighted yellow, and execution line from the function call in line 30 is highlighted green. Click on the Call Stack tab in Script Debugger window to review the current Call Stack (which corresponds to highlighted lines from previous point).
Switch to the ‘Watch’ tab in ‘Script Debugger’ window and review the variable properties
When an unhandled exception error is detected it will be highlighted in red. Click on the red exclamation mark menu in the toolbars to view exception error details (in this case division with zero). Click on stop menu in the toolbar (or press Shift+F5) to stop the script execution.