system


Name:
system - execute a UNIX command in a parallel process.
Synopsis:
CommandString	 system }   { Flag=0 or omitted:  
CommandArray system } { Status NormalExitFlag
} -> {
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

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) -> 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.)
- 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: Source:
/home/nest/work/nest-2.14.0/lib/sli/processes.sli