IPS_Execute

 string IPS_Execute (string $ProgramPath, string $Parameter, bool $Dummy, bool $Wait) 

Parameters

Returns

The output of the program if the Wait parameter is TRUE: the output to stderr if present, otherwise the output to stdout. If Wait is FALSE, an empty string is returned. On failure (e.g. if the program does not exist or cannot be started), FALSE is returned.

Description

The function starts the external program with the path ProgramPath. The string Parameter is passed to the program as command line parameter. The Boolean value Wait determines if the end of the program should be awaited or the calling script should be resumed immediately. The Dummy parameter is not evaluated: IPS_Execute never shows a program window. If a window should be displayed, IPS_ExecuteEx must be used.

If the function waits for the program, the output of the program is returned as a string. The same rule applies on all operating systems:

• If the program wrote anything to stderr, this output is returned, e.g. to not lose any error messages. The output to stdout is discarded in this case.
• Otherwise the output to stdout is returned (an empty string if the program did not output anything).

If the function does not wait for the program, it always returns an empty string. If the program does not exist or cannot be started, a warning is issued and FALSE is returned.

The exit code of the program is not available. If the exit code or the outputs to stdout and stderr are needed separately, the PHP functions exec or proc_open should be used.

Differences between the operating systems:

• Windows: The program must be specified with its full path. It is started with the command line ProgramPath Parameter, the working directory is the directory of the program.
• Linux, macOS and SymBox: A program name without a path is searched in the directories of the PATH environment variable. With Wait = TRUE, the command is executed via the shell (/bin/sh -c '"ProgramPath" Parameter'), so Parameter may contain shell syntax such as quotes, variables, redirections or pipes. With Wait = FALSE, the program is started directly. Parameter is split into individual arguments like the shell does (quotes and variables are evaluated), but redirections and pipes are not possible.

Caution: While waiting for the program to end, the script execution time is extended accordingly. Scripts have no maximum runtime, but while waiting the script occupies one of the limited threads in which scripts are executed. Long-running programs should therefore not be started with waiting enabled. This is especially important if the program expects user input.

Attention: If the program to be started is interactive (e.g. has a window), it will not be displayed/visible. It starts in the background as a system process and can only be stopped with the help of the Task Manager. If the program should be displayed on the desktop, the function IPS_ExecuteEx must be used.

Example

//Start a batch file
IPS_Execute("C:/autoexec.bat", "", false, false);