ssCore.Shell.execute

Use Shell.execute to run other applications. The only required parameter is the path to the application you want to launch, all of the other parameters are optional and allow you to control the behavior of the launched application and to retrieve information about it.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

path - A fully qualified path to an executable file. This parameter supports monikers.

arguments - [Optional] - Arguments that should be passed to the executable on its command line. This parameter supports monikers.

currentDir - [Optional] - The current (working) directory for the executable. If no current directory is specified the SWF Studio application basepath will be used. This parameter supports monikers.

timeout - [Optional] - Maximum amount of time in milliseconds SWF Studio should wait for the application to complete (waitForExit) or start (waitForWindow). If not specified (or 0) the timeout is infinite. We recommend using 0 with waitForExit and a resonable delay (e.g. 15 seconds) to allow the application to start when using waitForWindow.

waitForWindow - [Optional] - A boolean value that indicates whether you want to wait for the application's main window to appear or not (splash screens are ignored). Valid values include: true and false.

waitForExit - [Optional] - A boolean value that indicates whether you want to wait for the application to complete or not. This argument is required if you want to retrieve the Exit Code. Valid values include: true and false.

saveStdOut - [Optional] - A boolean value that indicates whether you want to capture data written to the standard output (StdOut) stream or not. Setting saveStdOut to TRUE automatically enables the waitForExit flag. Valid values include: true and false.

is16Bit - [Optional] - A boolean value that indicates that the application you are trying to launch is a 16-bit application. This is necessary when using saveStdOut and 16bit apps to ensure that the output is captured properly. Valid values include: true and false.

winState - [Optional] - The startup state of the application window. If not specified NORMAL will be used as the default. Not all applications respond well to being started in HIDDEN mode. Valid values include: normal, minimized, maximized, and hidden.

topmost - [Optional] - A boolean value that indicates whether the application should be made the topmost window. Valid values include: true and false.

x - [Optional] - X coordinate where the new application window should be displayed.

y - [Optional] - Y coordinate where the new application window should be displayed.

width - [Optional] - Width of new application window.

height - [Optional] - Height of new application window.

forceChild - [Optional] - A boolean value that, when true, forces the new application window to be opened as a child of the player window instead of as a normal window. Note: Some applications may not behave as expected when forced to become the child of another application.

findAny - [Optional] - If set to true, allows Shell.execute to return when it finds any window associated with the process id. Used with waitForWindow Valid values include: false and true.


Output Parameters:

elapsed - Elapsed time (in milliseconds) from the application startup to shutdown (run time) if you are using waitForExit or the elapsed time until application startup (launch time) if you are using waitForWindow.

hwnd - The window handle of the application. You must use the waitForWindow flag if you want a window handle returned. Not all applications return window handles (you may have to test your application to determine this).

exitCode - The exit code returned by the application. Not all applications return exit codes (you may have to test your application to determine this).

output - Contents of the standard output stream, normally used with console or command line utilities, BAT files and older DOS/Win9x applications. The output will be an emptry string unless saveStdOut has been enabled.

pid - The process id of the application.


Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.Shell.execute( paramsObject [, callbackParamsObject] [, errorParamsObject] );


Synchronous Mode:

When this method is called synchronously, a return object containing the output parameters is returned to the caller immediately.

var returnObject = ssCore.Shell.execute( paramsObject );


Notes:

None.


Examples:

The following example opens a text file by launching Notepad and passing the path to the text file as an argument to Notepad.

ssCore.Shell.execute({path:"windows://notepad.exe", arguments:"startdir://file.txt"});

If you have a long running process that you want to capture the output from, but you don't want to wait for the process to finish, you can use the onShellExecuteFeedback event.

ssCore.init();
ssDefaults.synchronousCommands = true;

ssCore.Shell.setNotify({event:"onShellExecuteFeedback"}, {callback:onFeedback});

function onFeedback(r, c, e)
{
var a:Array = r.result.split("\r\n");

for (i=0; i<a.length; i++)
ssDebug.trace(a[i]);
}

function onComplete(r, c, e)
{
if (r.success == false)
ssDebug.trace(r.Error.description);
}

var r:Object = ssCore.SysInfo.getEnv({variable:"COMSPEC"});

cmd = r.result;
args = "/C " + "dir c:\\windows /s";

     ssCore.Shell.execute({path:cmd, arguments:args, saveStdOut:true}, {callback:onComplete});