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

Syntax

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

 

Parts

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".

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

flags - window show state and other options. Integer.

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 (max 1 minute). It is effective way to wait until program will be ready to accept input (e.g., key or mouse commands). May not work with some windows.
0x400 Wait until program exits (if program is actually started, and file is not shortcut).
0x800 After program is started, wait for window window.
0x1000 If window exists, do nothing (default - activate).
0x2000 Run even if window exists.
0x10000 QM 2.2.0. Run as administrator. On administrator account it does not show a consent or Run As dialog, except in exe running on Vista. 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.

window - application's window. If the window exists, run only activates it (depends on flags). Otherwise, runs file and, if flag 0x800 is set or window is used, waits max 1 minute until the window becomes active.

hwnd - int variable that receives window handle (window must be specified).

 

Remarks

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

 

You can use run as function. When using as function, it returns the handle of the started process (program). If new process wasn't started (for example, if file is shortcut), returns -1. Returned handle can be used for example with wait function and, when no longer needed, must be closed using CloseHandle. With flag 0x400 (wait for exit), run returns program's exit code.

 

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, if UAC is on, most programs don't have administrator privileges even on administrator account. If a program has administrator privileges, programs launched from it also have the same privileges. run behaves differently, except in exe. Even if QM is running as administrator, programs launched by run don't have administrator privileges. To run as administrator, use flags 0x10000-0x30000. Function web also launches IE as not administrator. Functions StartProcess, RunAs and some Windows API functions also can launch programs with different privileges. Other functions (RunConsole, CreateProcess, etc) launch programs with the same privileges 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 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 command ("wait", "wait for active window", "wait for CPU", etc).

 

Sometimes, program started by run command 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 RunConsole 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 to run as current user with elevated privileges (instead use run with flags 0x10000-0x30000 or verb "runas", or StartProcess).

 

Examples

run "c:\f\text.txt" ;;open text.txt
run "notepad" ;;run Notepad
run "c:\f\my file.lnk" ;;run shortcut
run "c:\f\name.qml" ;;open other QM macro list file
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" "" "" "" 3 ;;run Notepad, maximized

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

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

 Run program and max. 15 seconds wait until it will fully loads (processor usage will be less than 10%):
run "largeapp.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

 Zip files (requires WinZip command line support addition): 
lpstr a = "-P ''d:\app\backup.zip'' @''d:\app\filelist.txt''"
run "C:\Program Files\WinZip\wzzip.exe" a

 Run Notepad and wait untill it terminates:
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