include Function

The method include allows importing the defined script. When the include instruction is executed, a file with the specified name is searched either in the Application View > Scripts folder or in the Scripts library block of a Scripting library (if the file is not found).

To prevent functions redefinition, some rules must be considered when implementing a script that will be delivered in a library:

• The method include will execute the code of the included scripts (regardless of whether they are protected) and will expect a return value from such execution. This object will be returned as result of the include method in the importing script.
• The librarian will decide the properties and functions to be exposed and will make them accessible through such object. Everything else will remain private and not accessible.
• If the librarian wants to expose a single object (for example, a value or a function), such object can be directly returned.

In case of errors if a script is included to a Scripts library and has linked objects, one of the following messages of Warning type displays in the Error List expander of the Script Editor:

• At least one linked object is present in the system with wrong type
• At least one linked object is missing in the system
• At least one linked object has a type that is not present in the system

To easily find the error to fix, do the following:

When a script is included in a Scripts library, the status of the included file is indicated in one of the following ways:

• A message in green color displays in the Editor expander, if the included file is signed and the signature is valid. The name of who signed the file displays in a tooltip.
• One of the following messages of Warning type displays in the Error List expander:
• If the included file was not signed:
  The included file is not signed and can be harmful.
  The include code line is highlighted in blue and the script can be executed.
• If the included file was signed but the signature is not valid:
  The included file is signed but the certificate is not valid.
The include code line is highlighted in blue and the script can be executed.
• If the included file was signed but the certificate for its validation cannot be found:
  The included file is signed but the certificate is not found. The signature cannot be validated.
The include code line is highlighted in blue and the script can be executed.
• If the included file was signed but the certificate for its validation is not valid (because it is expired or because it was revoked):
  The included file is signed but the certificate chain is invalid.
The include code line is highlighted in blue and the script can be executed.
• The following message of Error type displays in the Error List expander, if the included file was signed but the signature is invalid (tampered file):
• The included file is signed but the signature is not valid or tampered.
  The include code line is highlighted in red and It is not be possible to execute the script.

Syntax

It is possible to include one or multiple scripts into another script to reuse them. See the following syntax:

var exports = include(<scriptName>, <libraryName>);

All the defined functions can be invoked as if they were defined in the current script.

Parameters Usage

Additional Notes for <scriptName>

• The root can be:
• The Scripts directory, if <libraryName> is not provided (for example, "[Installation Drive]:\[Installation Folder]\[Project Name]"), or a filesystem path in the Scripts library block at the following levels, in order of precedence: L4-Project, L3-Country, L2-Region, or L1-Headquarter. For example:
  -- "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_Project_1"
  -- "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_RC_1"
  -- "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_ZN_1"
  -- "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_HQ_1"
• A script is a file with extension JS
• The separator for specifying subdirectories is "\\".
• The name of the file is case insensitive. It is optional to specify the script file extension, so all these instructions are equivalent and correct:
  - include("MyDir\\MyScript");
  - include("mydir\\myscript");
  - include("MyDir\\MyScript.js");
  - include("MYDIR\\MYSCRIPT.JS");
• When processing the instruction:
  
  include("MyDir\\MyScript ", "Global_Scripting_1");

  The Script Manager searches for the code to include in this order:
  
  1. "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_Project_1\MyDir\MyScript.js"
2. "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_RC_1\MyDir\MyScript.js"
3. "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_ZN_1\MyDir\MyScript.js"
4. "[Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_HQ_1\MyDir\MyScript.js"

Result

The result of the include operation is the export object that is returned by the included script. Such object can be of any type and contains the result of the execution of the included code. This allows exposing new functions and object properties using the result value as access point provided that the format of the return value is known to access it properly.

The return value is optional. This means that it is possible to include a script without a return value. In this case, the script that calls the included script takes over only when any instructions of the called script are carried out.

//This is libraryScript01.js

//Only "value" is accessible by scripts performing an include of this script

var value = "libraryScript";

var value2 = 100;

return value;

//This is libraryScript02.js

//myFunction() is accessible by scripts performing an include of this script

return myFunction() {

    console("log me");

}

//This is libraryScript03.js

//value1, function1 and myArray are accessible is by scripts performing an include of this script

var objects = {}; //the object is created

objects.value1 = "a value"; //a property is added

objects.function1 = function() { doSomething() }; //a function is added

objects.myArray = [1, 2, 3]; //another property is added

return objects;

Error Handling

Errors can occur in case:

• <scriptName>
• Is not specified, null, or empty. This error results in a failure of the script execution. In the Extended Operation tab, the Last ExecutionStatus is Failed and the Result is Script file not found ( ).
• Has incorrect separator. If the incorrect separator is '\' (instead of '\\') it is ignored, the script is not found, and its execution fails. In the Extended Operation tab, the Result is Script file not found (<scriptName>). If the incorrect separator is '/' or '//' (instead of '\\'), it is treated as "\\". The script is found, and its functions are successfully included.
• Non-existing script is included.
• The script fails. In the Extended Operation tab, the Result is Script file not found (NonExistingDir\NonExistingScript).
• A script is included by providing invalid <libraryName>.
• The script fails. In the Extended Operation tab, the Result is Script file not found.

Examples of Use

How to include a script (driverFunctions.js) and use its functions from another script

For example:

• Create a script (driverFunctions.js) with functions to start and stop a driver that check if the Start and Stop commands are available.

driverFunctions.js

//Start the driver

function startDriver(driverObject) {

    return executeDriverCommand(driverObject, 32);

}

//Stop the driver

function stopDriver(driverObject) {

    return executeDriverCommand(driverObject, 33);

}

//Execute the command with the input aliasId on a driver object (start or stop)

function executeDriverCommand(driverObject, aliasId) {

    if (isDriverCommandAvailable(driverObject, aliasId) == false) {

        console("The command with alias {0} is not available", [aliasId]);

        return false;

    }

    var result = executeCommand(driverObject, aliasId);

    if (!result.error)

        return true;

    return false;

}

//Check if the command with aliasId is available on the input driver object

function isDriverCommandAvailable(driverObject, aliasId) {

    var availableCommands = getCommandList(driverObject, "AutomaticStart.State", true);

    if(availableCommands == null || !availableCommands.error || availableCommands.commands == null)

        return false;

    for (var i = 0; i < availableCommands.commands.length; i++) {

        var cmd = availableCommands.commands[i];

        if (cmd != null && cmd.aliasId == aliasId)

            return true;

    }

    return false;

}

return {

    start: startDriver,

    stop: stopDriver

};

• From another script, include driverFunctions.js and use the functions defined in it (see the following code sample.)
  

var driverCommands = include("driverFunctions");

//Stop all the drivers, wait for a while, then start them again

//Create the driver objects

var bacnetDriver = new BrowserObject("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server.Drivers.GmsBacnetDriver_1");

var opcDriver = new BrowserObject("System1.ManagementView:ManagementView.ManagementSystem.Servers.Server.Drivers.GmsOPCDADriver_2");

//Stop the drivers

console("Stopping BACnet driver: {0}", new Date());

driverCommands.stop(bacnetDriver);

console("Stopping OPC driver: {0}", new Date());

driverCommands.stop(opcDriver);

//Wait for a while (30 seconds) to let the drivers stop

sleep(30000);

//Start the drivers

console("Starting BACnet driver: {0}", new Date());

if (driverCommands.start(bacnetDriver) == true)

    console("BACnet driver successfully started");

console("Starting OPC driver: {0}", new Date());

if (driverCommands.start(opcDriver) == true)

    console("OPC driver successfully started");

How to define multiple scripts with the same name at different levels

(a)

• Create a script with name consoleScripts.js under the node Application View > Logics > Scripts. This creates a file with name "[Installation Drive]:\[Installation Folder]\[Project Name]\MyProject\scripting\consoleScripts.js". The content of the file is:

//Local

//System Browser: Application View > Applications >Logics > Scripts

//File system: [Installation Drive]:\[Installation Folder]\[Project Name]\scripting\consoleScript.js

function writeConsole() {

    console("Local script: {0}", new Date());

}

return writeConsole;

(b)

• Create a file with name ConsoleScript.js, whose content is the following:

//In a Project library

//System Browser: Management View > Project > System Settings > Libraries > L4-Project > Global > Scripting > Scripts

function writeConsole() {

    console("Project library script: {0}", new Date());

}

return writeConsole;

Then import it in the L4-Project library level, under Global > Scripting > Scripts.

(c)

• Create a file with name ConsoleScript.js, whose content is the following:

//In a Country library (RC)

// System Browser: Management View > Project > System Settings > Libraries > L3-Country > Global > Scripting > Scripts

function writeConsole() {

    console("Country library script: {0}", new Date());

}

return writeConsole;

Then import it in the L3-Country library level, under Global > Scripting > Scripts.

(d)

• Create a file with name ConsoleScript.js, whose content is the following:

//In a Region library (ZN)

//System Browser: Management View > Project > System Settings > Libraries > L2-Region > Global > Scripting > Scripts

function writeConsole() {

    console("Region library script: {0}", new Date());

}

return writeConsole;

Then import it in the L2-Region library level, under Global > Scripting > Scripts.

(e)

• Create a file with name ConsoleScript.js, whose content is the following:

// In a Headquarter library (HQ)

// System Browser: Management View > Project > System Settings > Libraries > L1-Headquarter > Global > Scripting > Scripts

function writeConsole() {

    console("Headquarter library script: {0}", new Date());

}

return writeConsole;

Then import it in the L1-Headquarter library level, under Global > Scripting > Scripts.

(f)

• Create a script with name TestInclude under the node Application View > Logics > Scripts, whose content is the following:

var write = include("consoleScript");

var writeFromLibrary = include("consoleScript", "Global_MyLib_1");

write();

writeFromLibrary(); //The choice depends on where consoleScripts is located

When the script TestInclude runs, the function WriteConsole refers to the following:

• The local script created at point (a).
• The script of the L4-Project library (b), after the deletion of the local script (a).
• The script of the L3-Country library (c), after the deletion of the local script (a), the script of the Project library (b).
• The script of the L2-Region library (d), after the deletion of the local script (a), and the script of the L4-Project library (b) and the script of the L3-Country library (c).
• The script of the L1-Headquarter library (e), after the deletion of the local script (a), the script of the L4-Project library (b), the script of the L3-Country library (c), and the script of the L2-Region library (d).

How to include a script (libraryScript.js) stored in the Scripts folder of the Application View

libraryScript.js

function logText() {

    console("I'm printing from the module");

}

var privateProperty = "this is private";

var module= {};

module.method = logText;

module.prop1 = "hello";

return module;

mainScript.js

var libModule = include('libraryScript.js');

libModule.method();

console("I'm printing from the main script: " + libModule.prop1);

The output in the Console expander is:

I'm printing from the module

I'm printing from the main script: hello

Note that privateProperty cannot be accessed from mainScript.js. Note also that libraryScript.js is searched only in Application View > Logic > Scripts.

How to include a script (libraryScript.js) stored in L1-Headquanter > Global > Scripting library

libraryScript.js (in L1-Headquanter > Global > Scripting)

function logText() {

    console("I'm printing from the module");

}

var privateProperty = "this is private";

var module= {};

module.method = logText;

module.prop1 = "hello";

return module;

Note that a function (logText) and a property (prop1) are exposes.

mainScript.js

var libModule = include('libraryScript.js', 'Global_Scripting_1');

libModule.method();

console("I'm printing from the main script: " + libModule.prop1);

As the libraryScript.js stored in L1-Headquarter > Global > Scripting library, you have to specify the library name for including it.

The output in the Console expander is:

I'm printing from the module

I'm printing from the main script: hello

Note that privateProperty cannot be accessed from mainScript.js. Note also that libraryScript.js is searched not only in Application View > Logic > Scripts but also in [Installation Drive]:\[Installation Folder]\[Project Name]\libraries\Global_Scripting_HQ_1 (provided that a project named MyProject is available).