SICLIMAT X TECLA Scripts

Overview of the Migration Process

Desigo CC provides scripted execution of actions using JavaScript™ as the programming language. Apart from the standard functions and operators available in the language, additional functions, like for read/write of data points, have been added in the standard library. This enables the engineering user to write a control program in JavaScript™ while using library-provided functions. The following code snippet shows an example script:

Each such script document is stored in the Desigo CC project and represented as an instance of a data point. They provide the interface to start, stop, and monitor the status of the script execution. Consequently, these representative data points can be used in applications such as Macros and Reactions to invoke script execution.

Since there is a direct relationship between a TECLA Script document and an instance of JavaScript™ object inDesigo CC , we convert each TECLA Script document to a corresponding JavaScript™ file (with a representative data point object). The conversion process is carried out by a language cross-compiler which converts the language constructs (such as conditions, loops or operators) and replaces system service functions in TECLA (like data point read/write) with equivalents from the Desigo CC standard library. Since many system service functions in TECLA do have an equivalent in the standard library, the Siclimat Extension Module contains an additional JavaScript™ library which contains the equivalent functions. Not all functions in TECLA are possible in Desigo CC runtime. In case of a missing function equivalent a notification displays user during the migration process. Hence, it may be required to manually modify or extend the migrated TECLA script so that the missing parts can be worked around. The figure below depicts the overview of the relation between the TECLA scripts and the JavaScript™ objects in Desigo CC.

Key Considerations for TECLA Scripts Migration

Error Handling

The constructs of FWHILE and FWHEN that were designed to act as code parts dealing with error conditions are replaced with try/catch blocks. The original TECLA error codes are mapped to Desigo CC specific codes, which are listed in the appendix.

Multilingual Scripts

TECLA Scripts can be written using English or German syntax and function names. However, after migration, the JavaScript™ and its function calls are based on only English texts. The functions defined in the standard library are also based on English names.

Multi-System Projects

In a distributed system, data points exist within the containers of the respective systems. The migration tool needs to locate data points which are referred in the TECLA scripts. In order to do this in a multi-system project, the migration tool will go through all available systems and for each system, it will search the logical view and then the User View.
NOTE: These virtual objects (called Rechenwert) are searched only in Application View. If the migration tool is not able to locate the data point in any of these systems, it will log an error in the migration summary.

JavaScript™ Functions in the Siclimat EM Library

The library for SICLIMAT X contains numerous JavaScript™ functions that enable you to perform SICLIMAT X-specific actions like SetOperatingMode (Betriebsart). Such function calls may be used in extensions and new JavaScript™ code that you want to create.

Overriding of Data Point Property Values

If an object is in manual or hand mode, the writing of the default property will fail and the message will be logged to console and trace channel.

Calendar is not accessible in JavaScript™

Access to calendar entries, such as Special day, holiday or weekend, will not be supported in JavaScript.

Virtual object Creation

Prior to script migration, the user has to create a virtual object manually under Application View > Logics > Virtual Objects. However, if the virtual object was not created and the reference is not resolved in the migrated JavaScript™, the user can create it after the migration and drag the reference in the migrated JavaScript™. The name of the virtual object should start with a digit. Virtual objects must be created using four types: Analog(A), Multistate(M), Binary(B) and Unsigned(Z). If the virtual object has a user-defined name (for example, UserdefinedVirtualObject1) that does not follow the naming convention of the virtual object should be created and reference in script should be changed manually.

Examples (from SICLIMAT) of object models and virtual object names

Examples for SET, SETOP, SWITCH, and SWITCHOP

SET / SOLL:

• Example Use: _script.SetProperty("System1.LogicalView:LogicalView.SomeObject", 2);
• Sets the Sollwert property of the object to a value. If the object is in Manual mode, it will not change the value of the property.
• In this example, it sets the value 2 to the Sollwert property of an object.

SETOP / SOLLBA:

• Example Use: _script.SetPropertyWithOperationalMode ("System1.LogicalView:LogicalView.SomeObject", 2 , 3);
• First, it sets the Betriebsart property of the object to a value. If the object is in Manual mode, it will not change the value of the property.
• Second, it sets the Sollwert property of the object to a value. If the object is in Manual mode, it will not change the value of the property.
• In this example, it sets the value 3 to the Betriebsart property and value 2 to the Sollwert property of an object.

SWITCH / SCHALTE:

• Example Use: _script.ExecuteSwitch ("System1.LogicalView:LogicalView.SomeObject", 2);
• Sets the Sollstufe property of the object to a value. If the object is in Manual mode, it will not change the value of the property.
• In this example, it sets the value 2 to the Sollstufe property of an object.

SWITCHOP / SCHALTEBA:

• Example Use: _script.ExecuteSwitchWithOperationalMode ("System1.LogicalView:LogicalView.SomeObject", 2 , 3);
• First, it sets the Betriebsart property of the object to a value. If the object is in Manual mode, it will not change the value of the property.
• Second, it sets the Sollstufe property of the object to a value. If the object is in Manual mode, it will not change the value of the property.
• In this example, it sets the value 3 to the Betriebsart property and the value 2 to the Sollstufe property of an object.

Matrix for Possible Properties of Objects for SET, SETOP, SWITCH, and SWITCHOP

Resolving the Error Target not found for SET, SETOP, SWITCH, and SWITCHOP

In TeclaJavascript™ library for SET, SETOP, SWITCH, SWITCHOP fixed properties are used.

• SET / SETOP: Fixed Sollwert property is used.
• SWITCH / SWITCHOP: Fixed Sollstufe property is used.

However, while executing the Tecla script, these fixed properties can be missing in object due to different object type, which results in the error message Target not found being displayed. The user can define the required property explicitly by using “object/PropertyName” as shown in following example.

Example 1:

_script.SetProperty("System1.LogicalView:LogicalView.SomeObject", 3);

Output on console: Target not found

Reason:

The object SomeObject does not have the Sollwert property but the Grundsollwert property.

New implementation:

_script.SetProperty("System1.LogicalView:LogicalView.SomeObject/Grundsollwert", 3);

Example 2:

_script.ExecuteSwitch ("System1.LogicalView:LogicalView.SomeObject", 3);

Output on console: Target not found

Reason:

The object SomeObject does not have the Sollstufe property but the AktualSollstufe property.

New implementation:

_script. ExecuteSwitch("System1.LogicalView:LogicalView.SomeObject/AktualSollstufe", 3);

Example 3:

_script.SetProperty("System2.Logical2:Logical2Root.GiWi.DI_CC.CC_SEMINAR.KLIMA2.RF1_DRUCKREG.DRUCK_REGL", 180);

Output on console: Target not found

Reason:

The object “DRUCK_REGL” does not have the Sollwert property but the Grundsollwert property.

New implementation:

_script.SetProperty("System2.Logical2:Logical2Root.GiWi.DI_CC.CC_SEMINAR.KLIMA2.RF1_DRUCKREG.DRUCK_REGL/Grundsollwert", 180);

Appendix SICLIMAT X

Mapping of TECLA error code to Desigo CC specific codes

JavaScript Functions in the SICLIMAT Library

The following statement includes the library JavaScript file.

var _script = include("TeclaScriptLibrary.js" ,"BA_Software_Siclimat_Script_Migration_1");

Handling Missing Functions in the System in SICLIMAT X

Some functions which are not migrated in Desigo CC are replaced with dummy function call in migrated JavaScript. Following is the list of such functions and possible workaround.

TECLA Calls

• Service Pack 501 is successfully installed.

1. Log on to the console as the sicx user.

2. Run the teclaCalls script.
   This will compile a list of which TECLA scripts are called within Siclimat-X and where they are called. This includes calling scripts from:
   a. Schedules
   b. Events
   c. Pictures
   d. Scripts
   NOTE: A full list of options can be displayed with teclaCalls –h.

• The list of TECLA calls done in Siclimat-X is created in the current working directory or optional given output directory with the filename scriptCalls.csv.

• The list contains comma-separated values and can be imported into Microsoft Excel.