====== External Communication ======

Dinamica EGO can communicate with external applications by exposing a communication session. By default, an opened session will be created and its name is displayed on the status bar:

{{:statusbar_external.png|}}

To send and receive data, the functors under the 'External Communication' folder in the Library can be used.\\

{{::externalcommfunctors.png|}}

<note important>If the status bar shows 'External communication: off', check the Message Log for more information.</note>

==== Pre Requisites ====
The following packages are necessary for sending and receiving data using R. To install the packages, do:
<code>
install.packages(c("Rcpp", "RcppProgress", "rbenchmark", "inline"))
</code>
<note important> if you are using Microsoft Windows, make sure your R installation path does not contain spaces.</note>
<note important> On Microsoft Windows, [[https://cran.r-project.org/bin/windows/Rtools/|R Tools]] is required (default installation path [c:\rtools] is **mandatory**). Make sure you also select the option to add RTools to system PATH.  </note>

==== Command Line ===
Download {{::dinamica_1.0.4.tar.gz|Dinamica Package for R}} and install it:
<code>
install.packages("PATH_TO_DOWNLOADED_FILE", repos=NULL, type="source")
</code>

where PATH_TO_DOWNLOADED_FILE should match the downloaded file path, e.g. "/home/csr/Downloads/dinamica_1.0.4.tar.gz" on Linux or "c:/Users/CSR/Downloads/dinamica_1.0.4.tar.gz" on Windows.\\
\\
Using the example path "/home/csr/Downloads/dinamica_1.0.4.tar.gz":
<code>
install.packages("/home/csr/Downloads/dinamica_1.0.4.tar.gz", repos=NULL, type="source")
</code>

==== R Studio ====
\\
Download {{::dinamica_1.0.4.tar.gz|Dinamica Package for R}} and install it (using RStudio):
<code>
Tools -> Install Packages...
</code>
\\
=== Documentation ===
The Dinamica R package contains all the documentation available on this page, including examples and R Studio references.

=== Session ===
To connect to an existing session:
<code>
Dinamica::openSession("DinamicaEGO") # "DinamicaEGO" is the session name.
</code>
\\
====== Send and Receive Data ======
===== Real value =====
To send a Real value (e.g. 3.141592, the PI constant):
<code rsplus>
Dinamica::sendNumber(3.141592);
</code>
\\
To receive a Real value:
<code rsplus>
myNumber <- Dinamica::receiveNumber(); 
</code>
In the above example, the received Real value will be stored in the **myNumber** variable.
\\
\\
===== List / Vector of Real values =====
To send a list of Real values (e.g. 1, 2, 3, 4, 5):
<code rsplus>
myList <- c(1, 5);
Dinamica::sendNumberVector(myList);
</code>
In the above example, the user created **myList** will be sent.
\\
\\
To receive a list of Real values:
<code rsplus>
receivedList <- Dinamica::receiveNumberVector();
</code>
In the above example, the variable **receivedList** will store the contents of the received List of Real values.
\\
\\
===== Lookup Table =====
Consider the following **LookupTable** stored on the variable **myLUT**:
<code rsplus>
myLUT <- list( Keys = c(1:5), Values = c(1:5) * 2 )
</code>
^ Keys ^ Values  ^
|1     | 2       |
|2     | 4       |
|3     | 6       |
|4     | 8       |
|5     | 10      |
To send the **myLUT** **LookupTable**:
<code rsplus>
Dinamica::sendLookupTable(myLUT$Keys, myLUT$Values);
</code>
\\
To receive a lookup table:
<code rsplus>
receivedLUT <- Dinamica::receiveLookupTable();
</code>
In the above example, the variable **receivedLUT** will store the contents of the received LookupTable.
The columns 'Keys' (receivedLUT**$**Keys) and 'Values' (receivedLUT**$**Values) will contain the transferred Data.
\\
\\
===== Table =====
When transferring **Tables**, extra caution must be taken (refer to [[r_communication_utilities|this page]] for auxiliar tools.)
  - **Factor** columns must be converted to **Character Vectors**
  - Key columns can contain the '*' character on their names (to indicate they represent unique values).
  - From R to Dinamica, the **Table** variable **must** have the **DataFrame** type (or compatible).
\\
Consider the following **Table**:
^ Product ^ Price ^ Stock Quantity ^
| Rice    | 2.50  | 1e6            |
| Pasta   | 1.50  | 500            |
| Corn    | 0.50  | 1000           |
<code rsplus>
myTable <- data.frame(Product = c("Rice", "Pasta", "Corn"), Price = c(2.5, 1.5, 0.5), Quantity = c(1e6, 500, 1000), stringsAsFactors = FALSE)
</code>
<note important>Notice the use of the **stringAsFactors = FALSE** flag. This flag prevents R from converting the passed strings to Factors.</note>
\\
To send the **myTable** **Table**:
<code rsplus>
Dinamica::sendTable(myTable);
</code>
<note important>We never specified which column is the **Key** column. By default, the first column will be converted to the Key column.</note>
\\
\\
Suppose you want to send the following Table instead:
^ State         ^ City    ^ Population ^
| Massachusetts | Boston  | 667137     |
| Massachusetts | Chelsea | 39398      |
<code rsplus>
myTable <- data.frame(State = c("Massachusetts", "Massachusetts"), City = c("Boston", "Chelsea"), Population = c(667137, 39398), stringsAsFactors = FALSE)
</code>
To send the new version of **myTable**:
<code rsplus>
Dinamica::sendTable(myTable, 2);
</code>
<note important>Notice the extra parameter **2**? This optional parameter tells Dinamica, how many Key columns are being sent, from the leftmost column.</note>
\\
To receive a table:
<code rsplus>
receivedTable <- Dinamica::receiveTable();
</code>
In the above example, the variable **receivedTable** will store the contents of the received Table.
\\
\\
===== String =====
To send a string (e.g. "testing!"):
<code rsplus>
Dinamica::sendString("testing!");
</code>
\\
To receive a string:
<code rsplus>
receivedString <- Dinamica::receiveString();
</code>
In the above example, the variable **receivedString** will contain the received String value.
\\
\\