oProcess is a Worker Object (external component) providing a simple interface to launch and manage other processes, executables and applications, thereby providing you with greater interoperability from within Omnis Studio.
You can interact with oProcess using the standard worker methods, e.g. $init(), $run(), etc, which are described below, plus the external component has the common worker properties which are described here.
The oProcess object has the following properties:
| Property | Description |
|---|---|
| $callbackinst | Sets the instance that will receive a worker's callbacks |
| $cancancel | If kFalse, you can only cancel the worker forcefully. Defaults to kTrue |
| $elapsed | Seconds elapsed since the worker's process was launched. Stops counting when the process returns an exit code |
| $pid | The worker's process identification |
| $exitcode | The worker's process exit code |
| $timeout | Seconds the worker's process is allowed to run before getting cancelled. Defaults to 0 (no timeout) |
| $eol | End-of-line character which when encountered, a callback to the appropriate stream the worker's process wrote to is executed. Defaults to kLf for Linux and macOS and kCr,kLf for Windows. Setting $eol to an empty string i.e. eol.assign("") will cause an immediate callback to the stream the worker's process has written to |
| $state | Returns the worker's current state |
| $errortext | Returns the error text associated with the last action |
| $threadcount | Returns the number of active background threads for all worker instances |
| $errorcode | Error code associated with the last action |
$init(cProcess [,rArguments, cInitialDirectory, lEnvironment])
Initialises the worker to launch process in cProcess parameter. Use the rArguments row parameter to pass arguments to the process. cInitialDirectory can be used to launch the process with a different current directory. lEnvironment is a two-column list of environment variables and their values to be used during the process' runtime. For example, launching the following process:
proc.$init('/bin/echo$TEST',,,list(row("TEST","Hello world!")))
will result in callback to $stdout with "Hello world!" in the stdout column.
Runs the process on the worker's main thread, therefore blocking code execution until the process returns. Should be avoided, unless there are specific synchronous requirements.
Starts the process on the worker's background thread (non-blocking).
$cancel([bForce=kFalse])
Cancels the worker's process. Pass kTrue for bForce parameter to close the process forcefully (currently supported only on Linux and macOS, sends SIGTERM signal). If bForce is kFalse, a SIGINT signal is sent. Note: if $cancancel property is kFalse and bFore is kFalse, the call to $cancel will be ignored: use kTrue for bForce to override the $cancancel property.
$completed(wResults)
Callback method when the worker has finished running. wResults is a row with a retcode column containing the return code of the process and runtime_seconds column containing the seconds the process was alive for.
Callback method when the worker's process has been cancelled.
Callback method when the worker's process has started and can now write to stdin. You can use this callback to work with processes that expect input as soon as they start running, e.g. when they prompt for a password.
Returns kTrue if the worker's process is running, meaning that is has a PID greater than 0.
$stdout(wResults)
Callback method when worker's process writes to the stdout stream. wResults is a row with a stdout column containing the text the worker's process has written.
$stderr(wResults)
Callback method when worker's process writes to the stderr stream. wResults is a row with a stderr column containing the text the worker's process has written.
$write(cCharacters)
Writes cCharacters to the stdin stream of the worker's process.
$readlines(iStream [,nLines=0])
Returns a list containing all the lines written to kOProcessStd... stream, starting from the beginning of the stream. Use optional parameter nLines to limit the number of lines returned. For example:
$readlines(kOProcessStdin, 3)
will return the first 3 lines of the stdin stream.
iStream for $readlines() and $readtail() can be one of the following constants:
| Constant | Description |
|---|---|
| kOProcessStdin | Identifier for the stdin stream |
| kOProcessStdout | Identifier for the stdout stream |
| kOProcessStderr | Identifier for the stderr stream |
$readtail(iStream [,nLines=0])
Returns a list containing all the lines written to kOProcessStd... stream, starting from the end of the stream. Use optional parameter nLines to limit the number of lines returned. For example:
$readlines(kOProcessStdout, 3)
will return the last 3 lines of the stdout stream.
Using the $init method you can run multiple bash commands as follows:
proc.$init("/bin/bash",row("-c","echo hey && echo hey2"))or without using the arguments parameter
proc.$init("/bin/bash -c 'echo hey && echo hey2'")On macOS and Linux, you can run processes as the root user as follows:
proc.$init("/usr/bin/sudo",row("-S","/usr/bin/whoami"))and when the $started callback is received, call proc.$write(con("password",kLf)) to respond with the password. In this case, you will receive a call to $stdout with the stdout column containing "root", indicating that process is running with higher privileges.
On Windows, you cannot elevate the currently running process since the underlying APIs that make use of RunAs cannot redirect the stdout and stderr streams, suggesting that you cannot directly capture the output streams of an elevated process from a non- elevated process. Although the best way to ensure the elevated privileges are transferred to the process launched is to run Omnis with elevated privileges, you could do:
proc.$init('powershell.exe start powershell -Verb runAs -ArgumentList \"net session\" -WindowStyle hidden -Wait')to execute something as admin when Omnis is not running as admin, but you will not get the $stdout or stderr callbacks and you will not be able to use $write to the elevated process, making it a run-and-forget process.