Managing Script Libraries

Script Libraries are Lua scripts that can be housed in I/O model objects for access by others script running objects (ActionItems and GenericItems for example). A Script Library housed in an I/O object is accessible to the entire subtree beneath the object housing the Script Library. The Script Library can therefore contain functions or methods that can be referenced by script running objects. A Script Library can be housed in the following objects in the I/O Model tree:

System
Core
Connector
Datasource
Folder

Script Libraries can be entered using DataStudio either during the creation of the object using the Create Wizard or afterwards using the Object Properties panel. They can also be added as a property values via Lua script or the SCI.

Lua Script Library Syntax

Lua scripts can reference Lua script libraries in the tree by referencing the Module Name of the library with the "require" function. The "ModuleName" is the Script library compound property of an object used to identify the library. For example, to reference the Script Library with module name "SimpleMathLib" in a script-executing object beneath this folder, use:

require “SimpleMathLib”

The script library itself should be formatted in the following way. The module name is assigned in the first line and the entirety of the functions in the library enclosed within curly braces, separated by commas (the functions of the library are essentially elements in a Lua table). The library is then "returned" in the final line. For example:

SimpleMathLib = {
	Add = function(a,b) return a+b end,
	Subtract = function(a,b) return a-b end
}
return SimpleMathLib

The functions in the library can then be used in a script in an object below the library in the following way:

local mathlib = require“SimpleMathLib” local sumval = mathlib.Add(10, 4) return sumval

Adding Script Libraries with Lua

The properties must be set as an array (even if only one script library is being added to an object)
All the script library properties must be set at the same time (Module Name, Lua Script Body and Mandatory execution)

syslib.setvalue("/System/Core/Energy.ScriptLibrary.LuaModuleName", {"SimpleMathLib"})

syslib.setvalue("/System/Core/Energy.ScriptLibrary.AdvancedLuaScript", {
[[SimpleMathLib = {
	Add = function(a,b)	return a+b end,
	Subtract = function(a,b) return a-b	end
}
return SimpleMathLib]]
})

syslib.setvalue("/System/Core/Energy.ScriptLibrary.LuaModuleMandatoryExecution", {1})

Example adding two script libraries to an object:

syslib.setvalue("/System/Core/Energy.ScriptLibrary.LuaModuleName", {"SimpleMathLib", "CreateObjectHelper"})
syslib.setvalue("/System/Core/Energy.ScriptLibrary.AdvancedLuaScript", {[[SimpleMathLib = {
	Add = function(a,b)
		return a+b
	end,
	Subtract = function(a,b)
		return a-b
	end
}
return SimpleMathLib]], [[CreateObjectHelper = {
	createFolder = function(parentpath, name)
		local par = syslib.getobject(parentpath)
		local fol = nil
		if par ~= nil then
			fol = syslib.getobject(parentpath .. "/" .. name)
			if fol == nil then
				fol = syslib.createobject(parentpath, "MODEL_CLASS_GENFOLDER")
				fol.ObjectName = name
				fol:commit()
			end
		end
		return fol
	end
	}
return CreateObjectHelper]]})
syslib.setvalue("/System/Core/Energy.ScriptLibrary.LuaModuleMandatoryExecution", {1, 0})

The same applies if you are creating an object and setting the properties using the obj:commit() method. The property values are set as an array and all the Script Library compound properties must be set.

folder = syslib.createobject("/System/Core", "MODEL_CLASS_GENFOLDER")
folder.ObjectName = "Energy"
folder.ScriptLibrary.LuaModuleName = {"SimpleMathLib"}
folder.ScriptLibrary.AdvancedLuaScript = {[[SimpleMathLib = {
	Add = function(a,b)
	return a+b
	end,
	Subtract = function(a,b)
	return a-b
	end
}
return SimpleMathLib]]}
    folder.ScriptLibrary.LuaModuleMandatoryExecution = {0}
    folder:commit()

Adding Script Libraries in DataStudio

To add a Script library in DataStudio, click the plus icon in either the Create Object Wizard or the Object Properties panel. Multiple Script Libraries can be added to the same I/O object.

Figure 1. Adding a Script Library in DataStudio

Figure 2. Adding Script Library - Properties

If the Mandatory Execution option is checked then the script in the Script Library is executed every time an object in the subtree initializes its script environment. The default setting is false. For an example of Script Libraries in action, see the Using Lua Scripting Jump Start, where Script Libraries are used to simulate production data and create new objects in the KPI Model.