system()

Runs a system shell command.

Synopsis

int system(string shellcommand | dyn_string progAndArgs | mapping options [, string &stdout [, string &stderr]]);

Parameters

Parameter Description
shellcommand Shell command that is performed.
progAndArgs

Program call as a dyn_string.

The first element is the program required, the other elements are used as arguments.
options A mapping of options for the function. It can contain the following key & value pairs:
"program" (string) The program to be started.
"arguments" (dyn_string) A dyn_string containing the list of arguments.
"timeout" (int)

The timeout for the process end. If the program is not finished during this timeout, it is stopped with "terminate".

Possible values are:

  • -1: The end is not waited for, the program is started and then detached (see also startDetached). In this case the out-arguments for "stderr" and "stdout" are ignored, as they may not exist anymore at process termination. The return value will be the PID or in case of errors -1.
  • 0: No time limit. This is the default.
  • positive int value: Defines the milliseconds to termination.
"terminateTimeout" (int)

The second timeout after the "terminate" is sent after the first timeout. If this time is exceeded, the process is ended with "kill". If a "kill" is used, the function returns -2.

Possible values are:

  • -1: "terminate" is not executed, the process is immediately stopped with "kill".
  • 0: No time limit. No "kill" is executed.
  • positive int value: Defines the milliseconds until "kill". The default value is 1000.
"env" (mapping)

A mapping that defines the environment variables for the new process. The key & value pairs consist of the variable name and the needed value.

Anmerkung: The entire environment is set.
"addEnv" (mapping) A mapping that adds the given variables to the present environment. The key & value pair is the variable name and the needed value.
"workingDir" (string) The working directory for the new process. A relative path must be relative to the project directory.
"stderr" /"stderr+"(string)

The filename to which stderr is redirected. The file is truncated. The present file content is deleted before writing. If an empty string is set, the system-null-device is used. A relative path must be relative to the project directory.

Anmerkung: If "stderr" is set as an option, the stderr argument is not used.
Anmerkung: If "stderr+" is used, meaning that stderr is used together with a + sign, the content of the specified file is not truncated but appended instead before writing to the file.
"stdout" /"stdout+"(string)

The filename to which stdout is redirected. The present file content is deleted before writing. If an empty string is set, the system-null-device is used. A relative path must be relative to the project directory.

Anmerkung: If "stdout" is set as an option, the stdout argument is not used.
Anmerkung: If "stdout+" is used, meaning that stdout is used together with a + sign, the content of the specified file is not deleted before writing to the file.
"stdin" (string)

The filename of the file the standard input is redirected to. An empty string represents the system's null device.

Example:

system(makeMapping("program", "cat", "stdin", "/tmp/input", "stdout", "/tmp/output"));

This results in the same behaviour as using cat < /tmp/input > /tmp/output in the commandline.
stdout Returned standard output of the called shell command.
stderr Error output of the called shell command.

Return value

Returns the return code of the program that was executed. system() sets the last error (see getLastError()) in case of an error where -1 is returned: if no argument was specified, a new process could not be created or if the started process was not finished normally.

If the child process returns -1 as exit code, the function returns -1, but a last error is not set.

In case the "options" mapping is used and the "timeout" is set to -1, the return value will be the PID.

If the process was terminated with "kill" after the "timeout" and "terminateTimeout", -2 is returned.

Errors

Missing or incorrect arguments or a process crash.

Description

The system() function is used to run a shell command in WinCC OA.:

  • system("program") launches a program synchronously. The program launched runs parallel to the manager that uses the system() function. The corresponding CTRL thread waits until the system() call is finished. The manager itself is not stopped or blocked.
  • system("program &") starts a program asynchronously (in the background) under Linux. The program launched runs parallel to the manager that uses the system() function. The manager is not stopped.
  • system("xterm -e program &") starts an xterm console and executes the given program in the console (in this case in the background). This guarantees that the program output is visible in its own console and is not propagated in the log viewer.
  • system("start /b program") starts without DOS window in the background under Windows.
  • Both system("cmd /c program") and system("start cmd /c program") start synchronously but in a DOS window. Therefore, they can only be used under Windows.
    Anmerkung: When calling the function system() under Windows a maximum of 62 threads can be started! This applies to CTRL threads that call the "system()" function.
    Anmerkung: None of the both system calls blocks the manager (see the list above).
Anmerkung: Spaces and Unicode chars are only handled correctly when the dedicated options-parameter is used.

Deletes all files with the extension "bak" from the test and the users directory as a background process on a Linux machine.

main()
{
   system("rm /users/test/*.bak &");
}

The following script outputs the result of the git command.

main()
{
    string quotedPath = "\"" + makeUnixPath(PROJ_PATH) + "\"";
    string out;

    system("git -C " + quotedPath + " status --untracked-files=all --porcelain", out);
}

/* Out contains the result output of the git command. */

The following script runs the script "NewFile.ctl" from the command line and returns its process ID.

main()
{
  string stdOut, stdErr;
  string cmd = makeNativePath(WINCCOA_BIN_PATH) + getComponentName(CTRL_COMPONENT);

  if ( _WIN32 )
    cmd += ".exe";

  mapping options = makeMapping("program", cmd,  "arguments", makeDynString("NewFile.ctl", "-proj myProject"),  "timeout", -1);
  int pid = system(options, stdOut, stdErr);

  DebugTN("pid = " + pid);
}

Assignment

Miscellaneous functions

Availability

CTRL, UI