A-Shell Reference

xcall MIAMEX, MX_SHELLEX, status, objectspec {,action ,parms ,dir, showflags ,waitflag, clisvr, exitstatus}

(Windows or ATE only) MX_SHELLEX (MIAMEX 96) provides an interface to "Shell Execute," which is one of the two fundamental mechanisms for launching a new process under Windows. The other method is known as "Execute Windows Command Line" or "CreateProcess" or "Win Exec," and is used by HOSTEXxs and AG_WINEXEC.

Shell Execute is the method used by Windows itself when you click on a file or shortcut in Explorer, or even type a command line in the Start..Run dialog, and although it supports the ability to form command lines with parameters, it is most commonly used by specifying just an object (e.g. a file, URL, folder, etc.), and letting Windows decide which application is needed to perform the default (or specified) action on the object. Windows does this based on a table of file type associations in the Registry (which you can edit by means of the File Types dialog on the Explorer Tools...Folder Options menu).  

This function has both a subroutine and a print tab implementation.

Parameters

Note that all parameters after objectspec are optional.

status (F6)

will return one of the following:

 

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

showflags

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 AUI_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

 

 

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

Comments

This method is generally preferred over the "Execute Windows Command Line" method (e.g. executing an explicit command line with an explicit location and name for the executable) since it eliminates three of the biggest problems normally associated with launching local applications: knowing the actual name of the executable, the command line syntax, and directory where it is located. All of these are taken care of by the association definition.

Under Vista, there is an added bonus in that "Shell Execute" will automatically request "elevation" if necessary in order to perform the specified action, whereas "CreateProcesss" will simply fail if the user doesn't have the necessary privileges.

Aside from a -15 return code for timeout, applications should be aware of return code 1223, which indicates that the user was given some kind of prompt to enable or accept the launch of the program (such as with Vista 'elevation'), and the user chose to cancel rather than allow the launch.

In addition to an individual parameters length of 1024 bytes, there is an overall limit of 4096 bytes for all of the arguments combined. If the limit is exceeded, the routine will return with status 8 (out of memory).

Example

See the discussion "Executing Windows command-prompt commands" on the A-Shell Forum.

See Also