.. highlightlang:: us

.. index:: system

.. _system:

system
======

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

:ref:`system` creates a new process.

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

The following parameter lists should not be used any longer:

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

.. us.return

**Return Value**

If system() is invoked with the parameters ``system(ssName, options)`` the 
function returns the process exit-code. If the process could not be started, the
function returns an error object.(see :ref:`error_create`).

If system() is invoked with 1 to 3 parameters: *bool* is TRUE (1) if the 
process has been successfully created, and FALSE (0) if the process could not be
created.

If system() is invoked with *bGetExitCode* set to TRUE (1): If the process
could not be created, an error object is returned (see :ref:`error_create`) and
otherwise the return value of the process is returned. *bSynchron* must be set
to TRUE (1).

.. us.params

**Parameters**

.. uparam:: ssName

   *ssName* is a string that specifies the command line to execute.

.. uparam:: options

      *options* is an object with the following elements:

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

      * - show_window
        - Is used from GUI programs. Default value is ``SW_SHOW (5)``.
          Possible Values:

          .. 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
        - If *synchron* is TRUE (default value), :ref:`system` starts the program 
          and waits until the process is terminated.
      * - timeout
        - Time in milliseconds until the started process is forced to terminate.
          If *timeout* is not specified or set to 0 the process will not be 
          killed.
          If timeout > 0, *synchron* is set to TRUE.
      * - console
        - For non GUI programs the console will be created for input/output data.
      * - current_directory
        - For example ``"c:\\test"``. If the parameter is not specified, 
          the current directory of the invoked process is used.
      * - environment
        - A string of the form ``"name=value|name=value"`` with environment
          variables. Because the characters ``=`` and ``|`` are used as 
          separators, these characters cannot be used in element ``name`` or 
          ``value``.

.. uparam:: nShow

   *nShow* specifies the default value the first time ShowWindow is called to
   display the process on the  monitor. Default value is ``SW_SHOW``.
   Possible values see above.

.. uparam:: bSynchron

   If *bSynchron* is TRUE (1) the function waits until the new process has
   finished. Otherwise the function returns without waiting for the new process
   to finish. Default value is FALSE (0).

.. uparam:: bGetExitCode

   If *bGetExitCode* is TRUE (1), the return code of the process is returned.
   See the description of the return value. *bSynchron*  must be set to  TRUE (1).

.. us.example

**Example**

Start ``notepad.exe`` and wait until it is finihed:: 

    system("notepad", [.]);

Start ``notepad.exe`` and **do not wait** until it is finished:: 

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

Start :ref:`us_exe` and display a message box. Exit ``us.exe`` and remove the box
if the user does not click the OK button during the 5s timeout interval::

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

Specify enviroment variables::

   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
     - Description
   * - R2013.11
     - New parameter *options*.
   * - 5.3.0
     - New parameter *bGetExitCode*.

.. seealso::
   :ref:`overview-programming`,
   :ref:`ShellExecute`

:sub:`id-544257`