Name: system - execute a UNIX command in a parallel process.

Synopsis:

CommandString              system }    { Flag=0 or omitted: 
CommandArray               system }    {  Status NormalExitFlag 
} -&gt; { 
CommandString Flag         system }    { Flag=1: - 
CommandArray  Flag         system }    { 
}    { Flag=2: ChildPID 
CommandString Flag Precode system } 
CommandArray  Flag Precode system }


Examples:

1. (ls) system % This is the same as: (ls) 0 system 
2. (xterm) 1 system 
3. %The follwing asks SLI to make itself, do something else in parallel 
%and report make's exit code: 
(make --silent) 2 system /MyChild Set 
&lt;do anything in parallel&gt; 
MyChild false waitPID %wait for child to terminate 
pop pop (make returned exit code: ) =only =


Description:

"system" creates a child process of the current SLI process 
and executes the given command in that child process. 
Depending on the value of "Flag", the parent process will 
wait for the child to terminate or continue execution in 
parallel. 
The command may be given either as a string containing 
the command name and all options, or as an array of 
strings, specifying the command name and every single 
option. 
If you are interested in communicating to the child process 
via pipes, see "spawn" or "shpawn". 
Alternatives: Functions system_as_i_p with array or 
string and integer(flag) and precode, system_as_di_i_p 
with array or string and dictionary followed by 
integer(flag) and precode (both undocumented) -&gt; behaviour and 
synopsis are the same.


Parameters:

In : CommandString(string)/CommandArray(array of string): 
The UNIX command to execute. 
Either a string containing the command and all 
parameters, or an array of strings, containing the 
command and the parameters in separate (see "sysexec"). 
Flag: 0: Wait for termination of child process. 
A flag indicating if the child process exited 
normally or abnormally, and the exit status is 
left on the stack. 
1: Return immediately. This is the "no-care-mode". 
An orphaned grandchild process is created. 
I.e. a child is forked, which again forks 
a child and then exits. The orphaned grandchild 
is inherited by the init-process immediately, 
which will perform any waiting. 
This is a legal way of producing a child you don't 
have to wait for. (However, see remarks below.) 
&bull; All ressources occupied by the child process will 
be automatically released with its termination. - 
No result is left on the stack. 
2: Return immediately. 
Create a normal child process and return immediately, 
leaving it's PID on the stack. 
! The parent has to call "wait" or "waitPID" in order 
to free the ressources occupied by the child process 
after it's termination ! 
The "Flag" parameter may be omitted in which case 
it defaults to zero. 
Precode(executable procedure): 
-This parameter is for internal use with the "spawn" 
command. However, it is documented here for there may be 
unexpected applications.- 
In "Precode" there can be supplied a sequence of SLI 
commands that will be executed by the child process 
prior to calling "sysexec". The main application 
is to instruct the child process to redirect it's 
standard input/output to a pipe, as does the "spawn" 
command (for a example, see the code of "spawn"). 
Out: NormalExitFlag(boolean): 
True, if the child terminated normally, i.e. by a call to 
exit() or by returning from main(). In that case, the exit 
code is reported in the Status argument (see below). 
False, if the child terminated due to a signal that was 
not caught. In that case, the number of that signal is 
reported in the Status argument (see below). 
Status(integer): 
If NormalExitFlag is true, this reports the child's exit 
code, i.e. the low-order eight bits of the status argument 
that the child passed to exit(), or the value the child 
process returned from main(). 
If NormalExitFlag is false, this reports the number of the 
signal that caused the termination of the child process. 
Look up this number in signaldict, to know what it means. 
ChildPID(integer): The process ID of the newly created child.


Bugs:

Be aware of citation-mark-bug in breakup (see "breakup")


Remarks:

The no-care-mode (Flag=2) gives no way to know about the 
child`s exit code. If you need to care about the exit code, 
use Flag=0, which will leave it on the stack, or use Flag=1 
and get the exit code by calling "wait" or "waitPID". 
If you are interested in communicating to the child process 
via pipes, see "spawn" or "shpawn". 
To Do:   It should be possible to spawn a parallel SLI Process. This 
should be supported by a future version. Actually, as this is 
the more general case, the spoon/system/spawn chain of commands 
could be restructured.


Author:

R Kupper


FirstVersion:

Apr 23 1999


SeeAlso:

spawn
sysexec
spoon
fork
waitPID
wait
breakup
environment

Source:

/var/www/debian/nest/nest-simulator-2.20.0/lib/sli/processes.sli
