Scripting and Server Values [ErgoTech Systems, Inc. TechWiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Scripting and Server Values =====

This article gives you an overview and some examples for using ValueObject in scripts and the role of the incomingValue (the value which triggers the script).

====The "incomingValue"====

In scripts, the variable "incomingValue" represents the proposed new value (ValueObject) for the server. incomingValue is the value just read from a device or used to trigger the server or javascript bean.  This value is only a proposal, so within your script you are able to change this value so that actual value of the server will become the value output from your script. 


<note important>
The value on the last line of the script is the "return" value.  That is, this will become the value of the server. So if you put a line
<code javascript>
incomingValue;
</code>
on the very last line of your script, the incomingValue will be passed out of the script to the next target. If you want to change the outgoing value, be sure this is the value on the last line of your script, for example:
<code javascript>
output = incomingValue + 50;
output;
</code>
If you do not put any value on the last line of the script the script will only run again if the incoming value has change. See more on this topic under Trigger Limits.
</note>

====Using Named Servers in Scripts====

Most of the time you will getting or setting values of servers by name. In other words, to set a value of a server called  "BroadcastServer" you set the value using:

<code javascript>
BroadcastServer->setIntValue(10);
</code>

or to get the value from this server:

<code javascript>
latestValue = BroadcastServer->getIntValue();
</code>


Calculations can be made on these server values. An obvious case is scaling. This single line script will result in the value of the server being one tenth the value read from the device.
<code javascript>
incomingValue/10;
</code>


You can still get the current value of the server by referencing the server by name.

<code javascript>
/Devices/MyServers_Servers/MyServer->getValueObject();
</code>

This value (/Devices/MyServers_Servers/MyServer->getValueObject()) will not be updated until after your script has run so can be thought of as representing the "old" or "last" value and the incomingValue can be thought of as the "new" or "proposed" value.

If the last line of the script does not have a value, the "incomingValue" will become the value of the server after the script returns, so the script:

<code javascript>
print ("Incoming Value" + incomingValue.getStringValue());
</code>

will result in the server being set to the value of "incomingValue".

If you find you're getting results that are one reading behind what you expect, check to make sure that you're using the incomingValue, not the old server value in your scripts.



==== Indirect Access To Servers in JavaScript ====

Most of the examples you will see use the "->" operator to access a server directly by its name in a script the MIStudio logic (Diagram Window) or in TransSECS. Another way to access a server is by assigning a variable to the server's name then using this variable to access the server value or a property value of the bean. This is called //indirectly accessing// the server. To do this we use the "-->" operator. For example:

<code javascript>
serverName = "MyServer";
serverName --> setTimebase(2.0);
currentValue = serverName --> getLongValue();
</code>
 
The "-->" operator is useful when you need to iterate through server names. For example, if you have ten Modbus servers in your logic called "Modbus1", "Modbus2", "Modbus3", ... "Modbus10", and you need to read a value from each one and perform some operation on each, you could write an iteration loop to compose each server name and use it indirectly. Here is an example of how to find the largest and smallest values in a series of five named servers (the first one is Modbus0 and the last one is Modbus4):
 
<code javascript>
serverNameRoot = "Modbus";
minValue = 1e6; //make the min value ridiculously high
maxValue = -1e6; //make the max value ridiculously low
for (i=0;i<5;i++) {
   serverName = serverNameRoot + i; 
   value = serverName --> getFloatValue(); 
   if (value <= minValue) {
   minValue = value;
   }

   if (value >= maxValue) {
      maxValue = value;
   }
}

</code>

====Other Built-in Variables====

Besides "incomingValue", each script has access to the name of bean running the script (originatingBeanName) and the outport name (originatingOutportName). The outport name will be null in most cases. However it is useful to know the name of the bean running the script, especially when logging or using print() in your script.

The class of originatingBeanName is DataSource. So you can use DataSource methods in the script with this bean. For example, to get the container name you can reference the name of the DataSource using the "-->" syntax, then use getContainer().getContainerName() to get the container name. The "container name" is the name of the MIStudio application in which this script is running.

Here is a sample javascipt code which uses all of these variables:

<code javascript>
 beanName = originatingBeanName;
 outportName = originatingOutportName;
 containerName = originatingBeanName-->getContainer().getContainerName();
 
//example print or logging using this information
 print("This script is running from "+beanName+" in application " + containerName);
 incomingValue; //don't forget to use incomingValue or some other output value at the end of the script
</code>

====Trigger Limits====

To avoid a script being triggered with errors or the same value over and over again, the valueObject  (type and value) must change between triggers if there is no output to the script (if you do not have a value output on the last line of the script). 

As an example, this script will be triggered and the output value will be sent to the next server every time the script is triggered, no matter what the incomingValue is:

<code javascript>
output=2;
</code>

But this script will only work (run) if the incomingValue has changed and the script result does not generate an error:


<code javascript>
BroadcastServer->setIntValue(incomingValue.getIntValue());
</code>