execAsynchronous execution of external programs
Executes the <commandline> by passing it to a command interpreter. The <commandline> is executed asynchronously: this means that when exec returns the control to the next command, <commandline> may be still running.
The <callback command> is triggered on several events related to the child process and it gets passed the following parameters:
$0 = <event cause>
$1 = <event parameter>
$2 = <magic data>
The first parameter specifies the event cause and contains one of the following strings: "stdout","stderr","terminated","started" and "ping". By default (if no switches are used) only "stdout" type events are triggered. The second parameter depends on the event cause and contains data sensible to each event type. The third parameter is the eventual <magic data> passed to the exec command call.
Interacting with the process
If you use halt to terminate the callback then the slave process is killed immediately and no other callback events are triggered.
If you return some non empty string then this string will be written to the process stdin stream. This trick can be used to control interactive processes. Please note that you must include all the relevant carriage returns and newlines in the return value (see $cr and $lf).
If the -x switch is used then the startup event is triggered just after the process has been succesfully launched. The $0 parameter passed to the callback contains the string "started". Parameter $1 contains the pid of the slave process.
Stdout data event
The stdout data event is triggered when the process prints some output on its stdout stream. This event is triggered by default and to disable it you must use the -n switch. $0 contains the string "stdout". If the -b switch is not used then $1 contains a single line of process output with the trailing carriage return and/or line feed stripped. If -b is used then $1 contains the whole process output block (eventually empty) with all the cr/lf pairs.
Stderr data event
The stderr data event is similar to the stdout one but there are three differences. The first one is that the stderr event is NOT triggered by default: you must use the -e switch to enable it. The second difference is that $0 contains "stderr" instead of "stdout". The last difference is that $1 contains data coming from the slave process stderr stream.
The termination event is triggered after the slave process has terminated its execution. You must use the -t switch to enable it since it is disabled by default. $0 contains the string "terminated". $1 contains the process exit status value. (Note that if the process has crashed or has been terminated by an external singnal then this value will be 0).
The ping event is triggered only if the -p=<timeout> switch is passed.
This event may be useful to monitor the process status while it is not emitting any output, to write data to its stdin stream (by the means of return) or simply to give some feedback to the user while the slave process is doing a long computation.
The extended scope variables
The <callback command> has a set of extended scope variables that conserve their value during the whole life time of the slave process.
These variables can be accessed through the %:<varname> syntax and are useful to store process private data between multiple <callback command> calls.
Some words about the switches
If the -b switch is used then the <callback command> is called only once for the events stdout and stderr (if enabled) with the complete output block from the process. With the -b switch the events stdout and stderr are triggered once even if the process emits no output. The -s=<interpreter> switch may be used to specify the path of the command interpreter that is "sh -c" by default on unix machines and "cmd.exe /c" on windows. The interpreter executable is searched on the system PATH. If the process can't be started then a warning message is printed in the current window unless the -q (quiet) flag is used.