====== Functions to get access to registers ======

==== GetReg(variable_name[, connection_name]) ====
The GetReg function returns the current value of the specified register.

Before version 3.2 following notation was used:

The variable name **variable_name** where **variable_name** is the value of **Script alias** from the register's settings. Instead of variable_name you can specify a number - the register ID. However, the register ID is a less obvious way and it complicates the reading of the program.

The optional parameter **connection_name** can be specified if in several different connections there are registers with the same **variable_name**. In this case, connection_name indicates from which particular connection it is necessary to read the register named variable_name. Also, instead of the string connection_name, you can specify the connection ID. However, again, constants complicate the reading of the code and it is preferable to use named lines.

Since version 3.2 new enhanced notation used:

There is no **connection_name** parameter anymore. **variable_name** is the only parameter. It can be in one of 3 following formats:
  - number with register Id. Not recommended to use because it is hard to read code with hardcoded numbers. Example: GetReg(12)
  - string with script alias of register. Example: GetReg("speed")
  - string in format "connection_alias.register_alias" where first part is connection alias and second part is register alias. Example: GetReg("mixer.speed"); In this example value or "speed" register from "mixer" connection will be fetched.

If the register was not found or was not read, then the value **nil** is returned.

For the convenience of selecting registers for GetReg, there is a special button in toolbar (4).

{{ network:get_reg_button.png?direct&300 |}}

When you click on any of them, a pop-up window appears with a list of registers.

{{ network:select_register_dialog.png?direct&800 |}}

After clicking on the register of interest, the editor will insert the code with the identifier of the selected register (variable_name if exists or ID) and a comment with the register name, its address and the connection name.

{{ network:reg_inserted_after_getreg.png?600 |}}


==== GetRegStatus(variable_name) ====
The GetRegStatus function returns the status of specified register. Function works exactly like function **GetReg**.

On success function will return one of the following states:
  * unknown
  * disabled
  * normal
  * warning
  * alert

==== SetReg(variable_name[,connection_name], new_value) ====
The SetReg function sets the current value of the register with the name of the variable **variable_name** to **new_value** for the current scan. This function **DOES NOT** send new value to external devices. When polling this register in subsequent cycles, the old value will be read. 

Function returns 1 if an error occurred and 0 on success.

The parameters **variable_name** and **connection_name** work just like in the GetReg function. Since version 3.2 there is no more **connection_name** parameter.


==== WriteReg(variable_name, new_value) ====
The WriteReg function sets the current value of the register with the name of the variable **variable_name** (optionally you can specify the connection **connection_name**) to provided **new_value** for the current scan and writes this value to the external device in the beginning of the next cycle. When polling this register in subsequent scans, a new value will be read (if it was not changed by the device itself). 

Function's returns value **false** if any error occurred or **true** on success.

The parameters **variable_name** and **connection_name** work just like in the GetReg function. 
Before version 3.2 there was **connection_name** parameter.
WriteReg(variable_name[, connection_name], new_value) 

===== Getting register's values stored in a log =====

----

==== GetRegFromLog(variable_name, query_parameters) ====

The GetRegFromLog function fetches data from register log. **varialbe_name** is an identified of register (see GetReg function for details). **query_parameters** is a table with up to 4 parameters:
   * from (unixtime, required)
   * to (unixtime, required)
   * order ("ASC" or "DECS, ASC is default)
   * limit (integer number between 1 and 5000, 1000 is default)

Using these parameters WebHMI will construct query like:
SELECT * FROM log WHERE reg = //regId// AND datetime >= //from// AND datetime <= //to// ORDER by //order// LIMIT //limit//

On success function will return table with register records from log database. Each row is a table with following records:
  * state (unknown, disabled, normal, warning, alert)
  * regid (integer)
  * time (unixtime)
  * value (string)

Example:

<code lua>
function tprint (tbl, indent)
  if not indent then indent = 0 end
  for k, v in pairs(tbl) do
    formatting = string.rep("  ", indent) .. k .. ": "
    if type(v) == "table" then
      ERROR(formatting)
      tprint(v, indent+1)
    else
      ERROR(formatting .. v) 
    end
  end
end

function main (userId)
    now = os.time();
    
    data = GetRegFromLog("myconn.myreg", {from = now-3600, to = now, order = "desc", limit = 10});

    tprint(data);
end
</code>

Output:
<code>
Sep 13 17:37:25.098: ERROR: LUA scripts: 0: 
Sep 13 17:37:25.098: ERROR: LUA scripts:   state: disabled
Sep 13 17:37:25.098: ERROR: LUA scripts:   regid: 1
Sep 13 17:37:25.098: ERROR: LUA scripts:   time: 1536849431
Sep 13 17:37:25.098: ERROR: LUA scripts:   value: 1
Sep 13 17:37:25.598: ERROR: LUA scripts: 1: 
Sep 13 17:37:25.598: ERROR: LUA scripts:   state: disabled
Sep 13 17:37:25.598: ERROR: LUA scripts:   regid: 1
Sep 13 17:37:25.598: ERROR: LUA scripts:   time: 1536849410
Sep 13 17:37:25.598: ERROR: LUA scripts:   value: 0
</code>