Documentation
IPS_ExecuteEx
string IPS_ExecuteEx (string $ProgramPath, string $Parameter, bool $ShowWindow, bool $Wait, int $SessionID)
Parameters
| ProgramPath | Full path to the program |
| Parameter | Parameter which is to be passed to the program (optional) |
| ShowWindow | True if the window should be displayed; False if the window should not be visible |
| Wait | Specifies whether to wait for the end of the program |
| SessionID | The user session ID to be used (under XP from 0, 2003/Vista from 1), < 0 for automatic selection |
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, FALSE is returned.
Description
The function starts the external program with the path ProgramPath in the session of a logged-in user, so that the program can e.g. be displayed on the user's desktop. The string Parameter is passed to the program as command line parameter. The Boolean value ShowWindow determines whether the program window is displayed. In contrast to IPS_Execute, this parameter is evaluated here. The Boolean value Wait determines if the end of the program should be awaited or the calling script should be resumed immediately.
If the function waits for the program, the output of the program is returned as a string. If the program wrote anything to stderr, this output is returned, otherwise the output to stdout. 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.
The SessionID parameter specifies in which user session the program should be started. (In Windows 2003, for example, multiple terminal sessions can run in parallel.) If the parameter is less than 0, IP-Symcon automatically determines the first active session and starts the program there. Starting a program in a user session requires IP-Symcon to run as a service.
This function is only available on Windows. On other operating systems, a warning is issued and FALSE is returned.
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.
Example
// Start Notepad
IPS_ExecuteEx("C:\\Windows\\notepad.exe", "", true, false, -1);