AvScript

SUMMARY

Scripting for ALPHA-VISION®-VISUalization runtime.

SYNTAX

AvScript <script-file>

OPTIONS

script-file
File name and evtl. path of the lua script to be executed.

DESCRIPTION

LUA is a scripting language widely in use in embedded and gaming applications. It's characteristics are robustness, speed and low memory requirements. LUA is open source and may be used under the terms of a MIT-licence (see below). Documentation and libraries for LUA may be found at www.lua.org. AvScript uses the actual version 5.1 of LUA.

AvScript works as a LUA-interpreter with an embedded library aci that allows LUA scripts the read and modify data object properties, event log entries etc. managed by aci.dll. This allows you to combine the values of several data objects and display the result in ALPHA-VISION® or you may read and write to files.

Use aci.ExecLoop to run LUA functions with a fixed cycle time. When a cyclic script is running with the aci.ExecLoop-function AvScript evaluates the $SHUTDOWN-object. When the value of $SHUTDOWN is 1 aci.ExecLoop returns and the part of the script after aci.ExecLoop is executed. When no $SHUTDOWN object is found, aci.ExecLoop runs indefinitely or until you terminate the script with os.exit() (see the LUA reference manual).

Lua license (Lua 5.0 and future Lua versions)
Copyright © 1994-2006 Lua.org, PUC-Rio.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

EXAMPLES

Combination of Several Conditions to Enable or Disable a Button
Normally you can specify only one function to enable or disable a button depending on the properties of a data object. If the enabling condition depends on several conditions you can use something like the following lua-script: 
aci.ConnectApp("MYNAME", "odense") --connect to the ALPHA-VISION ACI as an application

--store the object number of the object that enables the button because we need it in several places
enable_btn = aci.Obj_QueryAttr("ENABLE_BTN", DOATTR.ObjNum)
                
aci.ExecLoop(1000, --cycle time 1000 milliseconds
        function() --create an anonymous function that will be executed once per second (see the cycle time above)
        
                --get the actual username:
                user = aci.Obj_QueryAttr("$USR", DOATTR.Txt) 
                
                --get the OS number:
                osno = aci.Obj_Value("$OSNO") 
                
                --an additional object that enables the button if not equal to 0
                --There is somewhere a button that toggles this object's value. 
                --Overrides the OS and user dependent conditions:
                enable = aci.Obj_Value("ENABLE_COND") 
                
                --evaluate conditions
                if (user == "CHIEF" and osno == 101) or enable ~= 0 then
                        -- write a diagnostic message to the command line when the enable-status changes
                        if aci.Obj_Value(enable_btn) ~= 3 then
                                print(os.date("%c") .. " : User='"..user.."' OS="..osno.." ENABLE_COND="..enable.. " Button enabled\n") 
                        end
                        aci.Obj_SetVal(enable_btn, 3) --enable the button
                else
                        -- write a diagnostic message to the command line when the enable-status changes
                        if aci.Obj_Value(enable_btn) ~= 0 then
                                print(os.date("%c") .. " : User='"..user.."' OS="..osno.." ENABLE_COND="..enable.. " Button disabled\n") 
                        end
                        aci.Obj_SetVal(enable_btn, 0) --disable the button
                end
        end)

Calculate the Volume of the Contents of an Irregularly Formed Tank Using a Tank Curve Specified in a File
--connect to the ALPHA-VISION aci
aci.ConnectApp("AvScript", "systst")

--remember the object numbers in a global table
OBJ = {}
OBJ.TANKLEVEL = aci.Obj_QueryAttr("TANKLEVEL", DOATTR.ObjNum)
OBJ.TANKVOLUME = aci.Obj_QueryAttr("TANKVOLUME", DOATTR.ObjNum)

--[[ multi line comment
Reads the tank curve from a text file where each line contains the 
x and y coordinates of a point that belongs to a polygon describing the tank curve

An example of reading from a CSV-file is included in "Programming in Lua" by Roberto Ierusalimschy
--]]
function ReadCurve()
        local file = assert(io.open("tankcurve.txt", "r")) --open the file, check for errors
        while true do
                n1, n2 = file:read("*number", "*number")
                if (n1 == nil or n2 == nil) then break end
                table.insert(curve, { x = n1, y = n2 })
        end
        file:close()
end

--the cyclic task that calculates the tank volume
function Cycle()
        local x = aci.Obj_Value(OBJ.TANKLEVEL)
        local y = -1 --indicates error if x is outside of the range defined by curve
        local msg = "OUT OF RANGE" --indicates error if x is outside of the range defined by curve
        local p1 = curve[1]; --the first point
        --loop for all points of the curve, starting with the 2nd point
        for i = 2,table.getn(curve) do 
                local p2 = curve[i] --the next point
                if p1.x <= x and x <= p2.x then
                        --matching section found, calculate the volume and exit loop
                        y = (x - p1.x)/(p2.x-p1.x)*(p2.y-p1.y) + p1.y
                        msg = "" --reset error message
                        break
                end
                p1 = p2
        end
        -- write to aci
        aci.Obj_SetVal(OBJ.TANKVOLUME, y) 
        --error message, assumes that TANKVOLUME is a system object
        aci.Obj_SetTxt(OBJ.TANKVOLUME, "X", msg) 
end

curve = {} --global table of points

ReadCurve()

aci.ExecLoop(1000, Cycle)
Example for the content of tankcurve.txt: 
0 0
10 5
20 15
30 20

Syntax Notation
[aaa]
aaa is optional (zero or one occurences)
(aaa|bbb)
aaa exclusive or bbb
(aaa)*
aaa may occur indefinitely often or may be omitted
(aaa)+
aaa may occur indefinitely often but at least once
(aaa)m..n
aaa may occur from m to n times