Run or open file, folder, www page, create e-mail message

Syntax

run file [par] [verb] [dir] [flags] [window] [hwnd]

 

Parameters

file - full path or filename.

par - command line parameters. Used only with executable files.

verb - "open", "edit", "print", "explore" or other action that is listed in file's right click menu. Not all actions can be used. The default verb string is the one that is bold in the menu. Usually it is "open". See also flag 0x40000.

dir - default directory. Use "*" to extract from file.

flags:

First 8 bits Window show state: 0 or 1 - normal (default), 2 - minimized, 3 - maximized, 4 - inactive, 7 - min. inactive, 16 - hidden. Most programs don't support this.
0x100 On error, don't show error message box.
0x200

Wait for input idle, i.e. until the program is ready to accept user input (keyboard, mouse). It works not with all windows.

0x400

Wait until the program exits.

  • Waits only if the program is actually started, and file is not shortcut.
0x800

After the program is started, wait until window window is active.

  • Waits max 5 minutes (1 minute before QM 2.3.3). Error on timeout.
  • Without this flag, if window and hwnd used, waits until the window is visible (can be inactive). QM 2.3.3: If flag 16 (hidden) used, waits until created (can be invisible).
0x1000 If window window exists, do nothing. If this flag not used, activates it.
0x2000

Run even if window window already exists.

  • If need to wait for window, waits for another (new) window. Therefore will fail if the attempt to run the program just activated the existing window.
0x4000 QM 2.3.4. Disable file system redirection on 64-bit Windows. Use this to run 64-bit system programs.
0x10000

QM 2.2.0. Run as administrator. On Vista/7/8/10 administrator account it does not show a consent or Run As dialog, except in exe and portable. To show the dialog, use verb "runas" instead. Read more in remarks.

0x20000 QM 2.2.0. The same as above, but only on administrator account. On standard user account the program will run as standard user.
0x30000 QM 2.2.0. Run as administrator if QM is running as administrator.
0x40000 QM 2.4.1. Support verbs from shell menu extensions, including "Properties".

window - a window of the program.

hwnd - int variable that receives handle of window window.

 

Remarks

file can be program, document, shortcut, folder or Internet resource ("http://...", "mailto:...", etc). To open web pages, you can also use web.

 

When using as function, run returns handle of the started process (running program) or -1. Later it must be closed with CloseHandle, unless assigned to a __Handle variable. Example: __Handle h=run("notepad.exe"); wait 0 H h; out "closed".

 

When using as function with flag 0x400 (wait for exit), run returns program's exit code.

 

The speed depends on spe.

 

To run/open objects that cannot be specified by path (e.g., Control Panel objects), can be used ITEMIDLIST string.

 

Class id strings in format "::{XXXX}\{XXXX}" also are supported. Starting from QM 2.2.0, some other functions also can use it, e.g. can get icon, create shortcut.

 

On Vista/7/8/10, if UAC is on, most programs don't have administrator privileges even on administrator account. They have Medium integrity level (IL). If a program has Administrator IL, programs launched from it also run as administrator. However run behaves differently, except in exe and portable. Even when QM is running as administrator, programs launched by run have Medium IL. To run a program as administrator, use flags 0x10000-0x30000. Function web also launches IE as not administrator. Functions StartProcess and RunAs also can launch programs with different IL. Other functions (RunConsole2, CreateProcess, etc) launch programs with the same IL as of QM, but without uiAccess.

 

Tips

You can drag and drop a file onto the macro text to insert run command for that file. Ctrl can be used to insert shortcut path instead of target path. You also can drag Internet links, virtual folders/objects, multiple files. You can also drop onto a toolbar.

 

If file is document, opens it in default program for that file type. To open in certain program, use program in file and document in par. Example: run "wordpad.exe" "c:\x.txt".

 

If macro intends to do something with new window, but program loads slowly, try flag 0x200, or/and window together with flag 0x800. Or, after run include wait or wait for command ("wait", "wait for active window", etc).

 

Sometimes, program started by run shows a dialog. Macro should close the dialog, but run waits until you manually close the dialog. In such case, create a function that closes the dialog, and start it from the macro using mac. See example.

 

To run a console program and capture its output, use RunConsole2 instead.

 

To run a program as another user, use RunAs instead. It does not require user interaction if you specify encrypted password. It cannot be used on Vista/7/8/10 to run as current user with elevated privileges (instead use run with flags 0x10000-0x30000 or verb "runas", or StartProcess).

 

64-bit Windows has two System32 and Program Files folders. Read more.

 

Before QM 2.3.3, did not support relative path for files in QM folder.

 

How to know if a program is running? Search for its window with win. If does not have windows, use function ProcessNameToId.

 

Examples

run "c:\f\text.txt" ;;open text.txt
run "notepad.exe" ;;run Notepad
run "c:\f\my file.lnk" ;;run shortcut
run "c:\m" "" "explore" ;;explore folder
run "c:\t.txt" "" "print" ;;print "t.txt"
run "control" "appwiz.cpl" ;;open Control Panel "Add/Remove Programs"
run "notepad.exe" "" "" "" 3 ;;run Notepad, maximized

 Run or activate Notepad:
run "notepad.exe" "" "" "" 0 "Notepad"

 Run Notepad with parameters "s.cpp", default directory "c:\f":
run "notepad.exe" "s.cpp" "" "c:\f"

 Run program and wait max. 15 s until CPU usage is < 10%:
run "app.exe"; wait 15 P 10

run "http://www.aaa.com" ;;open web page
run "mailto:name@isp.com" ;;create new e-mail message
run "mailto:name@isp.com?subject=Question" ;;create new e-mail message

 Run program with command line with variables:
str x.expandpath("$documents$\test.txt")
int y=5
str cl=F"/X ''{x}'' /Y {y}"
run "zzz.exe" cl

 Run Notepad and wait untill its process ends:
run "notepad.exe" "" "" "" 0x400

 Run program that shows a dialog at startup, which causes run to wait:
mac "CloseDialog"
run "program"
...
 _________________________________________
 Function CloseDialog:
wait(10 "Dialog Name"); err ret
key Y