A-Shell Reference

and revised December 2023

tab(-10, AG_SHLEXEC); objecspec, action, parms, dir, showcmd, waitflag; chr(127);     Tab(-10,x) Syntax Notes

AG_SHLEXEC (24) provides an interface to one of the two fundamental mechanisms for launching a new process under Windows, i.e. "Shell Execute". The other method is Execute Windows Command Line, also known as "CreateProcess" or " or "Win Exec". 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

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 (Str)

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 (Str)

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.

dir (Str)

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

Response

If the &h0200 bit is not set in waitflag, the return value will be a single byte to indicate success (ASCII 13, aka RETURN) or failure (ASCII 3, aka Control-C). Note that success just means that the command was successfully executed, not necessarily that the resulting process ran correctly. In the case of waitflag value 1, the status byte is not returned until the sub-process exits, else it is returned as soon as the sub-process is launched.

If the &h0200 flag is set in waitflag, the return value is a string containg a pair of integer values (launch-status and exit-status) separated by a comma. The launch-status indicates whether the sub-process launched ok (0=success, else a standard Windows error code indicating failure). The exit-status is only relevant when combined with waitflag value 1 (i.e. &h0201), in which case it indicates the exit-status returned by the launched sub-process when it exits. Most programs follow the standard of returning 0 for success, else an error code, although the error codes may vary among programs.

When the launch-status is non-zero, a file will also be left in the current directly, shellex.log, containing further details about the launch parameters to help in debugging failures.

Examples

! browse to a website using the default browser

? TAB(-10,AG_SHLEXEC);"http://www.microsabio.com";chr(127);

xcall ACCEPN,A

! Open a CSV file (presumably in a spreadsheet app)

? TAB(-10,AG_SHLEXEC);"%ATELOCALDIR%\test data.csv";chr(127);

xcall ACCEPN,A

! Open Explorer to browse a directory on the Windows LAN

? TAB(-10,AG_SHLEXEC);"\\server\share";chr(127);

xcall ACCEPN,A

! Launch email client to send message

? TAB(-10,AG_SHLEXEC);"mailto:arnold@calif.gov";chr(127);

xcall ACCEPN,A

! Launch an instance of A-Shell/Windows to execute an IMGDSX.LIT command

? TAB(-10,AG_SHLEXEC);"$ASHELL,,–e IMGDSX ";IMGSPEC$;",,1,2";chr(127);

! Play a video, SW)SHOWMAXIMIZED, wait, get exit status

? TAB(-10,AG_SHLEXEC);"mplayer2.exe,,/play,c:\temp\vid.wmv,,3,501";chr(127);

input STATUS,EXITSTS

Notes

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 Under Windows versions with UAC (User Account Control), 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.

See Also

History

2012 June, A-Shell 6.0.1254 / 6.1.1314:  Add waitflag value &h0200.