.. highlightlang:: us

.. index:: system

.. _system:

system
======

.. us.tag  system NOTREADYGERMAN Programming.os Changed530 Changed5511

:ref:`system` erzeugt einen neuen Prozess.

.. function::  exit_code = system(ssName, options)

Die folgenden Formen sollten nicht mehr verwendet werden:

.. function::  bool = system(ssName)
               bool = system(ssName, nShow)
               bool = system(ssName, nShow, bSynchron)
               bool = system(ssName, nShow, bSynchron, bGetExitCode)

.. us.return

**Returnwert**

Falls system() in der Form ``system(ssName, options)`` aufgerufen wird, gibt die
Funktion den exit-code des aufgerufenen Prozesses zurück. Falls der
Prozess nicht erzeugt werden konnte, wird ein Error-Objekt zurück gegeben
(siehe :ref:`error_create`).

Falls system() mit 1 bis 3 Parametern aufgerufen wurde: *bool* ist TRUE (1) wenn
der Prozess erfolgreich erzeugt werden konnte und FALSE (0), wenn der Prozeß
nicht erzeugt werden konnte.

Falls system() mit *bGetExitCode*  gleich TRUE (1) aufgerufen wurde: Falls der
Prozess nicht erzeugt werden konnte, wird ein Error-Objekt zurück gegeben
(siehe :ref:`error_create`), ansonsten der Return-Code des Prozesses. *bSynchron*
muss TRUE (1) sein.

.. us.params

**Parameter**

.. uparam:: ssName

   *ssName* ist die Kommandozeile, die ausgeführt werden soll.

.. uparam:: options

   *options* ist ein Objekt mit folgenden Elementen:

   .. list-table::
      :header-rows: 0

      * - show_window
        - Wird von GUI-Programmen werwendet. Der Defaultwert ist ``SW_SHOW (5)``.
          Liste der möglichen Werte:

          .. list-table::
             :header-rows: 0

             * - ``SW_HIDE (0)``
             * - ``SW_SHOWNORMAL (1)``
             * - ``SW_NORMAL (1)``
             * - ``SW_SHOWMINIMIZED (2)``
             * - ``SW_SHOWMAXIMIZED (3)``
             * - ``SW_MAXIMIZE (3)``
             * - ``SW_SHOWNOACTIVATE (4)``
             * - ``SW_SHOW (5)``
             * - ``SW_MINIMIZE (6)``
             * - ``SW_SHOWMINNOACTIVE (7)``
             * - ``SW_SHOWNA (8)``
             * - ``SW_RESTORE (9)``
             * - ``SW_SHOWDEFAULT (10)``
             * - ``SW_MAX (10)``

      * - synchron
        - Wenn *synchron* TRUE ist (Defaultwert), startet :ref:`system` das
          Programm und wartet bis es sich beendet.
      * - timeout
        - Zeit in Millisekunden bis das aufgerufene Programm zwangsweise beendet
          wird. Wenn *timeout* nicht angegeben wird oder 0 ist, wird das
          aufgerufene Programm nicht beendet.

          Falls timeout > 0 ist, wird *synchron* auf TRUE gesetzt.
      * - console
        - Bei Nicht-GUI-Programmen wird eine Console für Ein/Ausgabem erzeugt.
          Der Default-Wert ist FALSE (0), es wird keine Konsole erzeugt.
      * - current_directory
        - Zum Beispiel ``"c:\\test"``. Wenn der Parameter nicht angegeben wird, 
          wird das aktuelle Verzeichnis des aufrufenden Prozesses verwendet.
      * - environment
        - Ein String der Form ``"name=value|name=value"`` mit
          Environment-Variablen. Da die Zeichen ``=`` und ``|`` als Trennzeichen
          verwendet werden, dürfen sie in ``name`` oder ``value`` nicht verwendet
          werden.

.. uparam:: nShow

   *nShow* legt den Defaultwert für den ersten Aufruf der ShowWindow-Funktion
   fest. Der Defaultwert ist ``SW_SHOW (5)``. Liste der möglichen Werte, siehe
   oben.

.. uparam:: bSynchron

   Wenn *bSynchron* TRUE (1) ist, wartet UniScript mit der weiteren Ausführung
   des Programms, bis der aufgerufene Prozess beendet ist. Falls sich das
   aufgerufene Programm nicht beendet, kann die Funktion das (mehrmaliges)
   Drücken der Escape-Taste abgebrochen werden.

   Wenn *bSynchron* FALSE (0) ist, wird der Prozess nur gestartet und das
   Programm wird sofort weiter durchlaufen. Defaultwert ist FALSE (0).

.. uparam:: bGetExitCode

   Wenn *bGetExitCode* TRUE (1) wird der Return-Code des Prozesses zurück
   gegeben. Siehe Beschreibung des Return-Wertes. *bSynchron*  muss dann
   ebenfalls  TRUE (1) sein.

.. us.example

**Beispiel**

Starte ``notepad.exe`` und warte bis es beendet wird:: 

    system("notepad", [.]);

Starte ``notepad.exe`` und **warte nicht** bis es beendet wird:: 

    system("notepad", [. show_window = SW_SHOWMAXIMIZED, synchron = FALSE]);

Starte :ref:`us_exe` und gib ein Meldungsfenster aus. Wenn der Anwender nicht
innerhalb von 5s auf den OK-Button drückt, beende ``us.exe``::

   ssTemp = GetTempFileName();
   text_file_write(ssTemp, "MessageBox(\"Hello\");\n");
   system(GetRootDirectory() + "program\\us.exe " + ssTemp, [. timeout = 5*1000]);

Angabe von Umgebungsvariablen::

   def test()
   {
       ssTemp = GetTempFileName();
       text_file_write(ssTemp, "[[ MessageBoxInfo("A = %s", getenv("A"));\n ]]");

       system(GetRootDirectory() + "program\\us.exe " + ssTemp, 
                                    [. timeout = 5*1000, environment = "A=123"]);
   }

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Beschreibung
   * - R2013.11
     - Neuer Parameter *options*.
   * - 5.3.0
     - Neuer Parameter *bGetExitCode*.

.. seealso::
   :ref:`uberblick-programmierung`,
   :ref:`ShellExecute`

:sub:`id-544257`