? tab(-10, AG_WINEXEC); cmdlin; chr(127);

? tab(-10, AG_WINEXEC); cmdlin; "~"; workdir; chr(127);

Note: see History below for special variations of the syntax.

AG_WINEXEC (23) executes a Windows command line on the local Windows workstation or ATE client. The first syntax shown above assumes the current A-Shell or ATE working directory; the second allows you to specify a different directory.

Parameters

cmdlin

A string containing a valid Windows command line. The string may contain any of the suffix characters supported by HOSTEX.SBR to control how the command line is executed and whether we have to wait for it to complete, as summarized in this table. (Note: only one suffix option, at max, is allowed, and it must be preceded by a space.):

Return value

A single byte will be placed in the keyboard buffer 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 cases where A-Shell is supposed to wait for the command (no suffix or "%" suffix), the byte is not returned until the process exits.

Examples

! launch notepad to view miame.ini on PC and wait

? TAB(-10,AG_WINEXEC);"notepad.exe %MIAMEFILE%";chr(127);

xcall ACCEPN,A

! launch calculator and don't wait

? TAB(-10,AG_WINEXEC);"CALC.EXE $";chr(127);

xcall ACCEPN,A

Notes

Environment variables (known to the PC) may be embedded in the command line using the %VARNAME% syntax, as shown in the first example above.

HOSTEX.SBR provides nearly the same functionality under A-Shell/Windows, but under A-Shell/UNIX executes a UNIX command line on the server, whereas AG_WINEXEC always executes a Windows command line on the local workstation.

Also see the following topic, Shell Execute.

History

2006 October, A-Shell 4.9.969:  Two new macros have been added:

TAB(-10,AG_WINEXEC);"$COPY ";src$;" ";dst$;"~";flags;chr(127);

TAB(-10,AG_WINEXEC);"$MOVE ";src$;" ";dst$;"~";flags;chr(127);

These macros provide a clean way to move or copy a file. They are both equivalent to the MX_COPYFILE function and they share the same flags (0=copy, +1=move, +2=overwrite existing destination). The only difference between $MOVE and $COPY is in how the flags argument is defaulted if not specified. Note that this is a deviation from the usual behavior where an omitted numeric argument is equivalent to an explicit zero. In this case, specifying a flags value of 0 or 2 would override $MOVE, converting it to $COPY.

2005 May, A-Shell 4.9.932:  AG_WINEXEC now supports a new macro $DEL to delete a file. For example:

? TAB(-10,AG_WINEXEC);"$DEL %ATELOCALDIR%\myfile.dat";chr(127);

input "",A

This would delete the file myfile.dat from the directory specified by the environment variable ATELOCALDIR (which is set by ATE to point to its FTP Local Directory). The return code is CR for success or ^C for failure. Note that a non-existent file is treated as success, so the only error would be if the file existed but could not be deleted.

2005 April, A-Shell 4.9.926:  A special symbol, "$ATE", may now be used with AG_WINEXEC to make it easier to launch another ATE session. For example:

? TAB(-10,AG_WINEXEC);"$ATE";chr(127);

? TAB(-10,AG_WINEXEC);"$ATE ";cmdlin;chr(127);

The first example above ($ATE with no other argument) launches another ATE connection to the current server using the current profile, without suspending the current connection.

The second example ($ATE following by additional arguments) launches another A-Shell/Windows session on the local ATE client and passes it the command line cmdlin. You could use this format to launch a connection to some other server, assuming you knew the profile name, for example:

? TAB(-10,AG_WINEXEC);"$ATE telnet ";CFG$;chr(127);

Since ATE connections are established with the telnet command, the above command would launch a new ATE connection using the profile CFG$. Note that by default, AG_WINEXEC suspends the current session until the child session completes. If you don't want that, you must append the special suffix characters used by HOSTEX.SBR. For example, to not suspend the current session, the above command could be amended to add " $", i.e.:

? TAB(-10,AG_WINEXEC);"$ATE telnet ";CFG$;" $";chr(127);

Or you could execute any valid A-Shell command in the child session, for example:

? TAB(-10,AG_WINEXEC);"$ATE VUE %MIAMEFILE%";chr(127);

This would launch VUE to edit ATE's copy of the miame.ini file. Or:

? TAB(-10,AG_WINEXEC);"$ATE VUE %MIAME%\ashlog.log";chr(127);

The above command would VUE ATE's log file.