# Command: system

NEST HelpDesk | Command Index | NEST Quick Reference

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:

- spawn
- sysexec
- spoon
- fork
- waitPID
- wait
- breakup
- environment

Source:

    /opt/conda/conda-bld/nest_1512421404550/work/nest-2.12.0/lib/sli/processes.sli

NEST HelpDesk | Command Index | NEST Quick Reference

© 2004 The NEST Initiative