  |
GoFiler Legato Script Reference
Legato v 1.4j Application v 5.22b
|
| Table of Contents | < < Previous | Next >> |
Chapter Four — Flow Control (continued)
Overview
The RunProgram function requests that the Windows Shell execute a particular program or command and then immediately returns. The function does not wait for the called process to complete.
Syntax/Parameters
Syntax
int = RunProgram ( string name, [string parameters], [int showmode], [string working] );
Parameters
name
A string containing the name of the program to run or file to process. This should generally be a qualified name and path referencing an executable (“exe”) file or a file type known to the Shell.
parameters
An optional string that specifies the parameters to be passed to the called program. The parameters and their syntax are dependent on the receiving application. For many applications, placing a filename as a parameter will cause the target program to open and process that file. Note that most applications will treat unquoted text with spaces as multiple parameters and therefore the parameters must be appropriately prepared.
showmode
An optional int specifying the requested mode to show the application, assuming it is a window. These flags match those in the Windows SDK; for more information, see MSDN. The default is SW_RESTORE.
SW_HIDE
Hides the window and activates another window.
SW_MAXIMIZE
Maximizes the specified window.
SW_MINIMIZE
Minimizes the specified window and activates the next top-level window in the z-order.
SW_RESTORE
Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW
Activates the window and displays it in its current size and position.
SW_SHOWMAXIMIZED
Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED
Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE
Displays the window as a minimized window. The active window remains active.
SW_SHOWNA
Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE
Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL
Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
Note that not all programs process this parameter in the same manner and some override its operation depending on the mode requested. For example, Internet Explorer ignores all modes except SW_HIDE.
working
An optional string specifying a working directory.
Return Value
Returns an int as ERROR_NONE or a formatted error code. The error returned will be translated into ERROR_ style formatted errors while the value retrieved by the GetLastError function will be the raw error as returned from Windows.
Remarks
This function runs the Windows SDK ShellExecute function. See MSDN for more information. The script does not wait for the target application’s process to complete. The Windows shell is run and then immediately returns execution to the script. Unlike CreateProcess which runs a program, RunProgram is very generic and does not require an actual program be specified. For example, if an html file is passed as the name parameter, the default action would be to open the default browser.
Note that, in the event of an error, the low part of the error code is always from 0-32 and many codes do not follow the standard Windows error codes. Also, the GetLastError function can return 0 indicating out of memory or resources. In this case, the RunProgram function will return ERROR_WINDOWS_API | ERROR_NOT_ENOUGH_MEMORY.
In addition to the above, the return error status only applies to the action of starting the requested program. It does indicate the success of the target program in processing the request. For example:
rc = RunProgram("firefox.exe", "NotAValidPageAddressXYZ");
Assuming FireFox is installed, this will return ERROR_NONE even if the resultant action fails to execute properly. In this case, Firefox will run and then perform some operation resulting in a page not loading (depending on the system and ISP, it will likely load a search page). The Legato script will continue its execution.
When using this function to execute another instance of the application and a running instance receives control from another instance (e.g., this instance), the command line parameters are not passed through. To insure the control is not passed to an existing instance, use the /NewInstance command line option.
For the target program to access certain information, it may need to run in an elevated state. See the RunProgramElevated function.
Related Functions
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE, Legato Basic
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.