===== Data Source Connections in MIStudio =====
In MIStudio, a data source refers to any component that sends out the data output, including but not limited to just the database servers.
Data source connections allow data flow from a data source to a target component. There are several ways to make data source connections.
==== Use Wired Connection ====
A data source could be connected by graphically drawing a connection wire to a target component. When connected, the data source’s output becomes the target component’s input.
In the diagram window, connect the data source output to the target input, by simply drawing a connector line.
The connection wire can be different colors in the Diagram Window depending on if data has been sent through it or not, or if there was an error.
A gray connector indicates that no Value Objects have been sent through since the application was loaded.
A green connector indicates that a Value Object was sent successfully to its target.
A red connector indicates an error.
==== Use "Manage Connections" ====
A data source and the target component also have “Manage Connections” to allow setting up connections. Right click on the component to bring up “Manage Connections”. How to set up connections in this method see below “Using Manage Connections” section.
As an alternative to drawing connections in the Diagram Window, connections can be added to and from components by using the Name of the source or target or. This is done by using "Manage Connections" on a component.
For example, assume that your data source is an Increment Server, and the target is an annunciator. Your intention is to have the annunciator receive and display the data sent out from the Increment Server, and you’ve already have these two components in the Diagram Window.
To get data flow from the Increment Server (data source) to the annunciator (target),
- Right click on the Increment Server and select "Manage Connections''.
- Right click on "output" and you will be able to "Add Targets".
- Click on "Add Targets" and you will be shown another panel with all the available targets for the Increment Server.
- Select Target. Find the target entry of your intention (The annunciator), click on it and you will see the "Input" for data input.
Select it and click. Press “Done” and Close the Select Target window.
To check if the Increment server output is connected to the input of the target com (annunciator), right click on the annunciator, select “Manage Connections”, you will see that the input is the output of the Increment Server, even though there is no connector line wired them together.
You could also look at the Test Frame, seeing the output of the Increment Server is displaying and updating in the annunciator.
==== Use Scripts ====
A data source could also be connected in scripting, e.g. adding scripts to the server, or using the JavaScript bean, for calculations or situations needing more manipulations, where above connections can not handle.
“Data Flow/Scripts” are manipulators in MIStudio, they could get data from data sources, do calculations or other manipulations, and pass data to a target. How to use, and in which condition to use each and every “Data Flow/Scripts” manipulator is in another wiki.
JavaScript is used as a manipulator in MIStudio. JavaScript could get data by referencing data source and scripting input value, and pass data by scripting output value, and sending data to manupulator inputs.
=== JavaScript Referencing Data Source ===
All components in the Diagram Window of MIStudio have names. For example when you add a new Increment Server to the logic its name will automatically be set to "IncrementServer". You can change the name to be more descriptive to your application.
All named data sources can be accessed in Javascript by using the syntax "ServerName ->" where the name of the data source is "ServerName". For example, to get the current value of the Increment Server called "IncrementServer", you would add this line to the script:
newValue = IncrementServer->getLongValue();
The "->" syntax gets you a reference to the server to the left of the "->". With this reference you can get a value from the server and assign it to a script variable “newValue”.
You can get integers (long), floats (doubles), booleans, and Strings from the server. Please make sure that the value converts to the type you intend or you will get a Java exception logged every time the JavaScript bean is triggered.
Here are some conversions for the simple Increment Server example:
intValue = IncrementServer -> getIntValue();
longValue = IncrementServer -> getLongValue();
floatValue = IncrementServer -> getFloatValue();
doubleValue = IncrementServer -> getDoubleValue();
stringValue = IncrementServer -> getStringValue();
boolValue = IncrementServer -> getBoolValue();
**Note: Be sure to pay attention to the spelling of the data source names and be aware that these names are case sensitive. If you edit the name of the data source in your logic, you must make the same change in your script.****Bold Text**
You can also get Array Value Objects from the server (if it is generating Array Value Objects) and get any data value from the individual elements of the array or other properties such as the size of the array. To test the script below add an Array Data Source (called "ArrayDataSource") to your Diagram Window.
avo = ArrayDataSource->getValueObject();
value1 = avo.elementAt(0); //this gets the first element of the array
Arrays are indexed starting at 0, so some of the elements of the array would be:
value2 = avo.elementAt(1);
value3 = avo.elementAt(2);
etc.
You can also get an element of an AVO using getValue(). For example, to get the 4th element of the array (array indexes are zero based):
value4 = avo.getValue(3);
Here is a small script that accesses a variable element of an input array:
array = TestArray->getValueObject();
index = Index -> getIntValue();
test = array.getValue(index);
=== Scripting Input Value ===
When a script is used in a Manipulator, the script is executed after the manipulator's function on the incoming Value Object.
The Value Object that was used to trigger the script can be accessed using "incomingValue" as its name. This is a Value Object so the data contained in it is accessed using the "dot" operator.
For example: in your application you need to use the time from the incomingValue which triggers the script, it is like this:
timestamp=incomingValue.getDate();
To get the String Value of the Value Object,
string = incomingValue.getStringValue();
To get the Long (or integer) value of a numeric input,
value = incomingValue.getLongValue();
=== Scripting Output Value ===
The last line of the script will generate the output of the script. For example, if the following were the last line of the script a String Value Object would be automatically generated with the value "Hello":
output = "Hello";
You may explicitly create other types of Value Objects and use them for the output. In this next script the Double Value Object "dvo" will be the output of the JavaScript bean when it is triggered:
output = "something";
svo = new StringValueObject(output);
dvo = new DoubleValueObject(43.128);
output = dvo;
And the next script does the same thing (no need to use "output = " as the dvo creation was the last line of the script) :
output = "something";
svo = new StringValueObject(output);
dvo = new DoubleValueObject(43.128);
which is also equivalent to:
output = "something";
svo = new StringValueObject(output);
new DoubleValueObject(43.128);
=== Sending Data to manupulator Inputs ===
In many cases, you may want to send values in Javascript to another named manipulator (or Broadcast Server) in your project's application logic. For example, you want to put the value you get from a data source IncrementServer in a sql statement and insert the data into a table in a database. All you need to do is to put the Broadcast Server ( we call it “BCS”) next to the Javascript component in the Diagram Window. In the Javascript, write this codes like this:
Value1 = IncrementServer->getStringValue();
assume there is a "test.sqlite" database, and a table called "test", the column is "TheTestValue".
sql = "INSERT INTO test set TheTestValue";
sql = sql + "'" + Value1 + "'";
BCS -> setStringValue(sql);
sql;
When the BCS connects to the DatabaseRawWrite component ( the component writes to the database), the BCS should handle the SQL statement first, then trigger the write. Therefore, right click on the DatabaseRawWrite to bring up “Expose properties”, check “SQL statement”, connect the output of the BCS to this port; then connect the BCS output to the “Trigger” port. After this, check “Manage Connections” on the BCS, make sure the connections are in the order of “SQL statement” first, “Trigger” second.
If the data source, or the target is in a different application screen, you must qualify the name using the forward slashes around the application name.
For example:
DataValue=/ApplicationName/TheExactDataSource->getStringValue();
In this script:
/Overview/BCS -> valueInput(ValueChangedEvent(this,vo));
The above example creates a Value Changed Event to send the Value Object "vo" to the manipulator called "BCS" in the "Overview" screen's logic.
Similarly to this, “Manage Connections” has the same function. You could set up a Broadcast Server to receive data from another application, just specify the source and the target in the “Manage Connections”.
=== Debugging JavaScript ===
When you trigger the JavaScript bean to start its script, you can easily determine whether a mistake has been made in the JavaScript program because the connection line between the trigger data source and the JavaScript bean will be red. If it was successful, the line would be green. This does not mean that your program is correct, but that there were no errors.
If the connection line is red, select the connection and look at the description line at the bottom of the Diagram Window to get some information about the problem.
**Syntax Errors**
The script is interpreted in two passes. The first pass checks the syntax of the program lines (does not try to evaluate any statements). In this pass, the script will stop immediately if there is an error and produce an error line that has "SyntaxError:" with a short message and a line number in it, such as: "SyntaxError: missing ( before condition (JavaScript1; line 35)"
You have to go to the 35th line in the JavaScript code and find that you forgot to enclose a boolean condition statement with parentheses. Sometimes it is easier to find the nth line in the code by copying the JavaScript into a text editor that will display line numbers.
Another common syntax error is forgetting a quote on a String. If you see
"SyntaxError: unterminated string literal (JavaScript; line 12)"
look on line 12 of the script and make sure you have quotes around the string in the line. For example,
sql="SELECT "+ mno + " from table1); needs to be changed to sql="SELECT "+ mno + " from table1");
**Execution Errors**
Once the interpreter gets past the syntax check, it will try to execute the code, top down. Functions are not evaluated until called. Typical errors at this stage do not tell you any line numbers. Here are some examples and causes.
**TypeError: Cannot convert null to an object**
JavaScript Error: Internal Error: TypeError: Cannot convert null to an object.
When you get a "Cannot convert null to an object" this means you have referenced something in the Javascript that is not a server or manipulator in the Diagram Window logic. Look for mistakes such as:
1. Referencing graphical objects
source = Button->getLongValue();
This will cause an error because "Button" is a graphical object (a Button on the Design Window). Do not reference graphical objects in the JavaScript, even if you copy its icon to the Diagram Window. The way to get the value from the Button in JavaScript is to connect a Broadcast Server to the output of the Button and reference the Broadcast Server in the script.
2. Referencing beans that do not exist (wrong name)
MyServer -> getValueObject();
if there is no logic component named "MyServer" in the logic, or it is on a different screen, or if you mistype the name (look for upper vs. lower case in the server name). Unfortunately the error message does not indicate what name is null (does not exist) so you will need to look at your JavaScript carefully to find the problem.
**TypeError: undefined is not a function**
This error will say
"JavaScript Error: Internal Error: TypeError: undefined is not a function."
This will happen if you are calling a server method such as myServer->getValueObject() and you mistype the method name or if the method does not exist for the bean. For example, this will cause an error:
Ivo = IncrementServer->getLongValue();
test = lvo.getLength();
because getLength() does not exist as a method for a Value Object.
Unfortunately for this error there is no indication of what the faulty method name is so you have to study your JavaScript carefully to see the problem.
**ReferenceError: "myVariable" is not defined**
If you reference a variable that does exit you will get an
"Internal Error: ReferenceError: "myVariable" is not defined." error
For example, if your code says:
vo = new StringValueObject(stateString);
and the variable "stateString" has not been defined yet or is misspelled, the error will say:
"Internal Error: ReferenceError: "stateString" is not defined."
Define "stateString" with a statement such as:
stateString = CombineStrings -> getStringValue();
or
stateString = "Hello";
**ReferenceError: "functionName" is not defined**
This error is caused by referencing a defined function called "functionName" that does not exist. It will say something like: "JavaScript Error: Internal Error: ReferenceError: "functionName" is not defined". This will happen if you are using a function called "functionName" and you have not defined it in the JavaScript, or if you have misspelled the function name.
((**A DataSourceConnections.frx file is attached for you to download and add to your applications directory. You could open the DataSourceConnections application to see the examples. The Design Window has descriptions and the Diagram window is the place to see all the connections and data flows.**
))