MIAMEX 96: Shell execute

Parameters

Note that all parameters after objectspec are optional.

status  (F,6)

will return one of the following:

Value	Meaning		Value	Meaning
0	Success		8	Out of memory
-1	Out of system resources		11	Bad format
-15	ATE failure to respond		26	Sharing error
2	File not found		27	File association incomplete
3	Path not found		31	No association defined
5	Access denied		32	DLL not found
			1223	See Comments, below

 

objectspec

is the specification (Windows format) of the file/object to open or act on, or the URL to link to. For example, you might specify a XLS file, such as "C:\Windows\Temp\My Spreadsheet.XLS", in which case the presumed action would be to launch the spreadsheet program (e.g. Excel) to open the spreadsheet. For example, you might specify a URL, such as "http://www.microsabio.com" in which case the presumed action would be launch the browser and link to the specified web site or HTML document.

Embedded environment variables (using the %env% notation, e.g. %temp%\test.doc) are supported.

You may also specify an executable, such as %systemroot%\system32\mspaint.exe. Use the parms parameter for the remainder of the arguments and switches to be passed to the executable.

A special macro, "$ASHELL" can also be used to launch another session of A-Shell using the same executable and ini file as the current session. You can combine this with additional switches in the parms parameter to customize the action of the new session.

Note that in the ATE environment, the objectspec will be evaluated by (and relative to) the ATE client, not the server. If the object originates on the server, you'll have to first transfer it to the ATE client before using Shell Execute on it.

action  (String)

may specify an action: open, edit, print, find, explore or runas. If omitted, the default action for that file association is performed. Typically the default action is "open", which just opens the document. Such actions are defined with the file association in the Explorer Tools...Folder Options...File Types dialog.

Note that the "runas" action invokes the request for elevation dialog. For GUI commands, this is automatic, but for console commands (e.g. regsvr32), it is not, and this would be the only way to get it to prompt the user for the elevation needed. (Otherwise the operation would just fail.) Unfortunately there is no way to programmatically supply the administrator password. If you need something like that, you may want to check out a Microsoft-sponsored utility called "PsExec".

parms  (String)

is an optional list of parameters. Typically parms is used when objectspec contains the name of an executable (e.g. %miame%\bin\ashw32.exe), in which combination of objectspec and parms may effectively form a complete command line. parms has a maximum size of 1024 characters.

dir  (String)

is an optional starting directory. This can generally be omitted or specified as "".

showcmd

is an optional numeric parameter specifying the way to show the window launched by the program associated with the object and action. If omitted, the default window size will be used. Note that if you do specify the parameter, a value of zero means to make the window invisible. The values are the same as for MIAMEX 77: Show window. Note that this is only a suggestion to the target application. There is no way to force it to follow your suggestion if it insists otherwise.

waitflag

 

Value	Description
0	No wait. Focus will most likely remain on launched app. Default.
1	Wait until launched app exits before returning.
2	Don't wait, but try to get the focus back.
4	Disables the normal 10 second time out waiting for the ShellExecute operation to complete.

 

Note that waiting (1) doesn't necessarily wait until the launched app exits. It only waits until the app "signals", which can mean different things for different applications. (It will wait for A-Shell).

Option 2 will get the focus and keep getting it (if necessary) over a period of 4 seconds, in order to deal with difficult apps (like image viewers) that may take a couple of seconds to launch, after which they set the focus on themselves.

Ten seconds is normally more than enough time to determine whether the launch was successful or not, but there are some cases, most notably under Vista when the launch requires the user to confirm "elevation", that the server was otherwise timing out while ATE was still waiting for the ShellExecute to return. In such as case, an unreliable error status was often being returned, and then when the command finally did return, the normal response code was ending up in the keyboard buffer, possibly confusing the application. Specifying the +4 flag should not have any effect on older versions of A-Shell or under non-ATE situations.

Note that wait is independent of the existing waitflag option +1, which suspends ATE until the launched application completes. +4 only waits until the program is launched, not until it is closed.

clisvr (String), 1)  [in]

may be set to "S" (for server), or "L" (for local, which is the same as server in this context); anything else is treated as meaning "client". The option only has significance in the ATSD environment where the possibility exists of performing the function relative to the ATSD server or the client. In all other cases, the parameter is ignored and the operation is performed relative to the client, or returns an empty string if an applicable client is not present.

Beginning with A-Shell 1373 of January 2014, local mode (clisvr = "S" or "L") now supports the waitflag options and the exitstatus parameter. Previously, these only worked in the normal/default (client) mode where the operation is forwarded to ATE via the AG_SHLEXEC command. Also, both modes now support shell commands that require COM initialization.

exitstatus  (Num)[out]

returns the exit status of the launched process