Running Processes on BrightServer
Contents Hide
Description
This tutorial provides an example BEP which may be used to execute programs and batch files on the machine running the BrightServer instance, invoked by BrightForms' sync engine. The tutorial provides simple samples to retrieve both exit codes and program outputs, via an online RPC script on BrightServer.
Process Builder
The Java ProcessBuilder class is used to create operating system processes. This class may be used in conjunction with BrightServer scripts to invoke processes on the host machine running the BrightServer instance.
By default, this class is not included in scripts. To have access to this class and methods, they must be imported in the script with the following lines:
importClass (java.lang.ProcessBuilder);
importClass (java.lang.Process);
With the above classes imported, simple execution such as running, waiting, and then retrieving the exit result may be achieved. For example:
// Run a batch file, wait for result
var process = new ProcessBuilder("cmd.exe","/C","c:/test.bat","").start();
process.waitFor();
// Return result
result = new ResultRPC();
result.setOutputParameter ("outExitCode", process.exitValue());
return result;
Additional methods may be called before starting the process to further set up the environment. For more information, please refer to the Java ProcessBuilder API Specification.
The above code covers a basic case, which waits on results of the ProcessBuilder. As such, using this as-is will suspend BrightServer during its execution. Therefore, for processes which take long or indefinite amounts of time, it is suggested to start the process, without waiting for results. If retrieving and performing further calculations on the outputs of these processes are necessary, consider creating a separate thread for the process, managing the results separately from the RPC or script result.
Reading Output Streams
The process' error and output streams may be read by importing additional classes as follows:
importClass (java.io.BufferedReader);
importClass (java.io.InputStreamReader);
importClass (java.lang.StringBuilder);
Then utilising them as displayed below:
var builder = new ProcessBuilder("cmd.exe","/C","c:/test.bat","");
var process = builder.start();
// Prepare readers to populate output stream
var reader = new BufferedReader(new InputStreamReader(process.getInputStream()));
var builder = new StringBuilder();
// Populate with output stream
var line = null;
while ( (line = reader.readLine()) != null) {
builder.append(line);
builder.append("\n");
}
// Retrieve string value of the StringBuilder
var output = builder.toString();
Calling the Script
Executing processes via BrightForms' sync engine on BrightServer is handled within scripts. For demonstration purposes in this tutorial, the process' creation and execution will be contained within a single RPC script, which may be called by BrightForms via sync rule. For more information on this calling pattern, and the BSP/BEP configuration behind it, please refer to the How to Use Remote Procedure Calls tutorial in this document.
It
may be required to execute the batch procedure before or after
the user synchronises all their table data to the server. If using
the sync panel in these scenarios, the order of sync rules should
be set by the Synchroniser object's "SetExecutionOrder"
method in BrightForms, which will ensure the order of execution
is adhered to.
Example
The two files attached demonstrates the launching of processes on BrightServer via BrightForms' sync engine. To operate this demonstration, perform the following steps:
Create a .bat file with the following contents:
@echo off
(echo first line) > output.txt
(echo second line) >> output.txt
type output.txt
exit
When run, this file will create the file output.txt in the running directory, and then print the contents as output. Save this .bat file to a publicly accessible location on the BrightServer running machine.
Open the BEP and BSP in BrightBuilder.
In the BEP, locate the ScriptRunProcess script under the Scripts node, and open it. Replace the file/path of the bat in the ProcessBuilder constructor to the values set in step 1.
Run/deploy the server configuration on BrightServer.
Run BrightForms, and configure its settings to the BrightServer instance running the BEP.
Tap the button to run the script. The exit code and output stream of the batch file should be returned in the edit controls accordingly.
Exit Code: 0
Output: first line
second line
The output.txt file will also be created in the same directory which BrightServer was started.