The daxlua module basically runs three types of scripts. The first is the configuration file itself. Daxlua will look for the daxlua.conf file in the normal place (sysconfdir) or a filename can be given at the command line with -C. There is only one configuration directive to set at the moment and that is "init". It is a string that represents the script that is to run once at program start. This script is guaranteed to finish properly before any other scripts are allowed to run.
Adding scripts to the system is quite easy. Set a table with the right indexes and call the function add_script() in the configuration script. The indexes are name, filename and rate. The name is a string used to identify the script, the filename is the Lua script itself and the rate is the number of milliseconds between script executions.
There can be as many scripts as the user wants to write. The only limitations are system resources.
There are five functions added by the C code to Lua. They are...
dax_tag_add(<tagname>,<type>,<count>)
dax_write(<tagname>,<value>)
dax_read(<tagname>)
register_tag(<scriptname>,<tagname>,<mode>)
register_static(<scriptname>,<variablename>)
dax_tag_add() does what it looks like it would do. Adds a tag to the database. It's just like the dax_tag_add() function in the libdax library.
dax_write() sets the tag to a given value. If the tag is an array then it expects <value> to be a table with integer indexes that represent each member that should be set. For instance ...
dax_tag_add("TagName", "INT", 5)
z = {}
z[1] = 12
z[3] = 45
z[5] = 55
dax_write("TagName",z)
It should be noted that z[1] will correspond to TagName[0]. Lua is a 1 indexed array language. I could change this easy enough and I may do it yet but for right now I'm trying to keep with the Lua traditions. As I gain more experience with Lua I'll be looking for good reasons to leave it this way. If I don't then I'll change it to be zero referenced.
If the tagname given to dax_write() is not an array (it has a length of 1) then a single value can be passed. For example, given the above TagName, dax_write() could have been called as...
dax_write("TagName", 45)
The system will do a pretty thorough job of coercing the variables into the right type for the tag. If you assign a string "45" to a variable the tag should get assigned the value of 45. If you assign a string "Duddly" to the variable the tag will most likely become 0. Errors will be raised if the tag is an array and the variable given is not a table, or the tag is not an array and the variable that is passed is a table.
dax_read() works the same way but backwards. If the given tag is an array then the returned value will be an integer indexed table, otherwise it will be a simple value.
There are two functions for manipulating the global data that will be presented to each periodic script before and after they are run. The first is register_tag(). This function takes three arguments. The first is the name of the script, the second is the tag to be registered and the third is a string describing the mode.
Once a tag is registered, daxlua will handle the interface of that tag outside of the Lua script itself. The mode determines whether the tag will be read, write or both. The string would be "R", "W" or "RW." Neither case nor order matters. If the string contains an 'R' the tag will be read from the server before the script is run and a global variable will be created for the scripts use that represents that tag. Likewise if the string contains a 'W' then a global with that tags name will be searched for in the Lua context and the data written to the server.
The second function is register_static(). This function takes two arguments. The first is the name of the script and the second is a variable that the user would like to remain static between script executions. This data would survive between executions of the script but would not be written to the OpenDAX server for storage. Think of it as private data.
It is important to note that any static variables will not be read from the registry before the execution of the script and unless it is properly initialized the first time the script is run then unusual thing will happen. Use the _firstrun global variable as a condition to initialize any static variables the first time through. See the example scripts included in the distribution for more information.
The global tags and the static variables are only available to the periodic scripts although the init script can call the functions to add them to each script. Each script could also add them to itself. It might be handy to use the _name global in each call as a way to signify self.
There are several global variables that are made available to each periodic script.
_name is the name of the running script as assigned in the configuration script. It is read only.
_filename is the path of the currently running script. This is read only.
_firstrun is a boolean that is set true for the first run of the script only. It is false thereafter. It is read only.
_executions is a number that represents how many times the script has executed. It is read only.
_lastscan is a number that represents the total number of milliseconds that it took to execute the script the last time that it was run. This is not the same as the rate. This is the actual time that the script took to run. It is read only.
_rate is a number that represents the scripts current rate. This can be changed by the script to effect how quickly it is called, so obviously this is read/write.