Name
Run -- asynchronously execute a program
Synopsis
Run(file$[, args$, t])
Deprecated syntax
Run(cmdline$[, resetkeys, userdata])
Function
This function executes the program specified by file$ asynchronously and passes the arguments specified in args$ to it. If you need to execute a program synchronously, you have to use the Execute() function. See Execute for details.

If supported by the operating system, this command can also be used to view data files like documents or images using their default viewer. In that case, file$ can also be a non-executable file like a JPEG image or an MP3 file.

On Android file$ has to be either a data file like a JPEG image or a package name like com.airsoftsoftwair.hollywood if you want this function to start another app.

If you want to be informed when the program started using Run() is terminated, you can install a listener for the RunFinished event handler using InstallEventHandler(). See InstallEventHandler for details.

There is also a listener called RunOutput which can be installed using InstallEventHandler(). The RunOutput listener will redirect the program's output to your program which is useful when writing GUIs for console programs, for example. See InstallEventHandler for details.

Note that due to historical reasons, there are some pitfalls when using this function. Before Hollywood 9.0 this command expected program and arguments combined in just a single cmdline$ string. In that case, extra care has to be taken when dealing with spaces (see below for details). Starting with Hollywood 9.0, there is a new syntax which allows you to pass program and arguments as two separate arguments which makes things much easier. However, to maintain compatibility with previous versions this new syntax can only be used if you explicitly pass a string in the second argument. So if you want to use the new syntax, make sure to pass a string in the second argument. If the program you want to start doesn't need any arguments, just pass an empty string ("") just to signal Hollywood that you want to use the new syntax.

If you don't pass a string in the second argument, the old syntax will be used which means that you need to be very careful when passing program paths that contain spaces since the very first space in cmdline$ is interpreted as the separator of program and arguments. If you want to start a program whose path specification uses spaces, you need to use double quotes around this path specification or it won't work. You can easily avoid these complications by simply passing a string in the second argument, even if it is empty (see above for details).

Starting with Hollywood 9.0, it is possible to specify the program and its arguments in two separate arguments, which makes things much more convenient. Also, there is a new optional table argument now that can be used to specify further options.

The following options are currently supported by the optional table argument:

Directory:
This table argument allows you to set the current directory for the program that is to be started. (V9.0)

ResetKeys:
This table argument is only interesting for advanced users. If this is set to False, Run() won't reset all internal key states after executing the program. By default, all key states will be reset when Run() returns because programs started using Run() often assume the keyboard focus and Hollywood might be unable to reset its internal state flags because the new program started via Run() takes over keyboard focus. That's why by default Run() will reset all internal key state flags when it returns. Disabling this behaviour can make sense if you use Run() to start programs that don't have a GUI and don't take away the keyboard focus. Defaults to True. (V5.1)

RawMode:
This tag is only used when the RunOutput event handler is active. By default, the RunOutput event handler expects programs to output text only. This is why RunOutput will make sure to pass only properly UTF-8 encoded text to your callback function. If you don't want RunOutput to format the text as UTF-8, you need to set the RawMode argument to True when calling Run(). In that case, RunOutput won't do any preformatting and will just forward the program's raw output to you. This means that your event handler callback has to be ready to process binary data as well. Defaults to False. (V9.0)

IgnoreHandlers:
If event handlers for RunFinished or RunOutput are installed, those handlers will automatically trigger whenever Run() is called. If you only want those event handlers to trigger for certain calls to Run(), you can use this tag to tell Run() which event handlers to ignore. This must be set to a string containing the event handlers that should be ignored. Multiple event handlers must be separated by a vertical bar character. For example, setting IgnoreHandlers to RunFinished|RunOutput would tell Run() to not throw events for both event handlers, RunFinished and RunOutput. (V9.0)

ReturnCode:
If you have a RunFinished event handler installed, you can set this tag to True to indicate that your event handler should also receive the program's return code when it terminates. Note that when setting this tag to True on AmigaOS 4 and MorphOS, Hollywood can't be quit before the program started using Run() has terminated. Defaults to False. (V9.0)

ForceExe:
If this tag is set to True, Run() will always treat the file passed in file$ as an executable. This is only useful on Linux and macOS because on those platforms files that have an extension will be treated as data files so Hollywood will try to launch the corresponding viewer for the data file instead. Thus, trying to use Run() on an executable named "test.exe" will not work on Linux and macOS because of the *.exe extension. By setting ForceExe to True, however, you can make it work. Defaults to False. (V9.0)

UserData:
This argument can be used to specify user data that should be passed to the RunFinished and RunOutput event handlers that can be installed via InstallEventHandler(). See InstallEventHandler for details. The user data you specify here can be of any type. (V6.1)

Verb:
On Windows, this can be set to a string telling Run() what to do with the file. This can be one of the following verbs:

edit
Opens the specified file in an editor.

explore
Opens the specified folder in Explorer. When using this verb, you must pass a folder instead of a file to Run().

find
Opens the search dialog for the specified folder. When using this verb, you must pass a folder instead of a file to Run().

open
Opens the specified file.

print
Prints the specified file.

runas
Launches the specified file in administrator mode.

Note that the Verb tag is only supported on Windows. (V9.1)

Inputs
file$
the program (or data file) to be started
args$
optional: arguments to pass to the program; note that you must pass this parameter to signal Hollywood to use the new syntax; you can do so by just passing an empty string (""); see above for a detailed discussion (V9.0)
t
optional: table containing further arguments (see above) (V9.0)
Example
Run("Sys:Prefs/Locale")
The above code executes the locale preferences on AmigaOS based systems. Your script's execution will go on immediately after executing the locale program (asynchronous execution).


Run("\"C:\\Program Files (x86)\\Hollywood\\ide.exe\"")
The code above runs the Hollywood IDE on Windows systems. Note that we've embedded the program specification inside double quotes. This is absolutely necessary because the first space in the string passed to Run() is normally interpreted as the separator between program and arguments. If we didn't use double quotes in the code above, Run() would try to start the program "C:\Program" and pass the arguments "Files (x86)\Hollywood\ide.exe" to it which we obviously don't want. Note that since Hollywood 9.0, it is now much easier to deal with spaces in paths. You just need to use the new syntax which takes the program and its arguments in two separate arguments. With Hollywood 9.0, you could simply use this code:


Run("C:\\Program Files (x86)\\Hollywood\\ide.exe", "")
Note that passing the empty string in the second argument is absolutely necessary here to signal Hollywood that you want to use the new syntax. See above for a detailed discussion on this.

Show TOC